Files

gsxdsm 6ee20d9817 docs(U9): correct merge-stack slice statuses to measured wiring state (#2504 )

**U9, PR2.** Docs-only, no changeset (AGENTS.md: internal docs).

## Why

All seven slices in `docs/plans/workflow-owned-merge-stack/` were marked
`draft-stack-handoff` — accurate when drafted 2026-06-09, wrong now. **A
worker picking up this stack cold would have re-implemented S04, which
has already landed.** I nearly did.

## Measured, against `main @ 46f35323c`

| Slice | Was | Now | Evidence |
|---|---|---|---|
| S02 projection | draft | `landed-unwired` |
`projectMergeRequestToWorkflowWorkItem` implemented, **0 production
callers** |
| S03 scheduler claim | draft | `landed-unwired` |
`claimDueWorkflowWorkItem` implemented; its only caller is S05's
processor, itself unwired |
| S04 IR regions | draft | **`landed`** | `merge-gate`, `merge-retry`,
`manual-merge-hold`, `merge-attempt`, `recovery-router` present in the
coding IR |
| S05 runtime driver | draft | `landed-unwired` | `runWorkItem` /
`processDueWorkflowWorkItem` implemented, exported from `index.ts`, **0
production callers** |
| S06/S07/S08 | draft | `not-started` | merge still runs through
`merger.ts` + the live `ProjectEngine.mergeQueue` pump |

## The finding that changes U9's sequencing

`WorkflowWorkItemKind` is `task | merge | retry | manual-hold |
recovery`. The only live pump —
`InProcessRuntime.drainWorkflowContinuations` — filters `kinds:
["task"]`. The generic processor that would claim the other four kinds
has **no production caller**.

So the entire merge-lane work-item vocabulary is dormant: **zero
writers, zero readers.**

**I checked whether this is a live bug and it is not.** Nothing in
production writes a non-`task` kind — the only two writers
(`plan-review-continuation.ts`, `workflow-column-boundary-hooks.ts`)
both go through `replaceActiveTaskWorkflowContinuation`. Nothing is
stranded today. I'd rather say that plainly than let a scary-sounding
finding stand unqualified.

But it produces a hard ordering constraint, now recorded in S07:

> **S07 must not land before S03/S05 are actually driven.** S07 is the
slice that starts writing `merge`-kind work items. If it lands first,
those items are created and never claimed — a card that reaches the
merge boundary and silently stops.

This also reframes U9's job on S02/S03/S05: **wire them, don't build
them.**

## Scope discipline

Docs-only — `git diff --stat` is 9 files, all under `docs/`. No
production code, no tests, no behavior. `pnpm lint` clean.

I also fixed the three parent-plan lines asserting the slices are "all
still `draft-stack-handoff`", and the four landed slices' Stack Role
paragraphs that would otherwise contradict their own new Measured State
block. Leaving those stale would recreate exactly the defect this PR
fixes.

Related: #2494 pins the S04 caveat — the IR regions are declared but
their config is read by nothing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **Documentation**
- Updated workflow-owned merge planning documents with current
implementation and wiring statuses.
- Added measured wiring details showing which workflow capabilities are
active, implemented but unused, or not started.
- Clarified sequencing requirements to ensure merge processing is not
enabled before prerequisite workflow paths are operational.
- Corrected slice metadata and references to reflect the latest measured
state.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-07-28 17:15:16 -07:00

1.7 KiB

Raw Blame History

title, type, status, measured_against, date, slice, milestone, origin, stack_base

title	type	status	measured_against	date	slice	milestone	origin	stack_base
S05: runtime work-item driver	refactor	landed-unwired	main @ `46f35323c` (2026-07-28)	2026-06-09	S05	Runtime	docs/plans/2026-06-09-003-refactor-workflow-owned-merge-full-migration-slices-plan.md	feature/workflow-owned-merge-s04-builtin-ir-regions

S05: runtime work-item driver

Measured State (2026-07-28, U9 pre-flight)

WorkflowTaskRuntime.runWorkItem and processDueWorkflowWorkItem are implemented; the processor is exported from packages/engine/src/index.ts and has zero production callers. The only live pump, InProcessRuntime.drainWorkflowContinuations, filters kinds: ["task"] and does not use this path.

Status corrected from draft-stack-handoff, which was accurate when drafted on 2026-06-09 and is not now. See docs/workflow-policy-ownership-map.md → "Measured Wiring State" for the whole-stack table.

Stack Role

This slot was drafted 2026-06-09 as a handoff artifact. It is no longer only that — see the Measured State block above for what has actually landed.

Milestone

Runtime

Depends On

S1 workflow work items, S3 generic scheduler claim path, and S4 built-in IR regions.

Goal

Let WorkflowTaskRuntime start from a workflow work item and persist node/work-item outcomes.

Expected File Scope

packages/engine/src/workflow-task-runtime.ts; workflow graph executor and node handler files; runtime tests.

Expected Tests

Runnable completion, retrying work creation, manual hold creation, restart resume, and duplicate lease refusal.

Exit Gate

Runtime can progress workflow work without old merge queue callbacks.

Full Plan

See docs/plans/2026-06-09-003-refactor-workflow-owned-merge-full-migration-slices-plan.md.

1.7 KiB Raw Blame History