refactor(workflow): S18 documentation settings and release notes

[gsxdsm]

Stack Slice

• Slice: S18
• Milestone: Release
• Base branch: feature/workflow-owned-merge-s17-cutover-matrix
• Full plan: docs/plans/2026-06-09-003-refactor-workflow-owned-merge-full-migration-slices-plan.md

Goal

Update architecture, settings, dashboard, CLI, and testing docs for workflow-owned policy and compatibility projections.

Dependency

S17 end-to-end cutover matrix.

Expected Scope

docs/architecture.md; docs/workflow-steps.md; docs/dashboard-guide.md; docs/settings-reference.md; docs/testing.md; CONCEPTS.md; changeset.

Expected Tests

Docs inventory/search tests where applicable; lazy view inventory unchanged unless dashboard imports change.

Exit Gate

User-facing docs use the same state names as API/UI tests, and a patch changeset exists if published behavior changed.

Status

Draft stack placeholder. This PR reserves ordering and review context; implementation should replace or extend the handoff artifact before this slice is marked ready.

Implementation Added

• Added docs/workflow-owned-merge-runtime.md documenting the implemented runtime APIs and deletion guards.\n- Linked the runtime doc from architecture and testing guidance.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f3ffde5c-91f3-4d0e-b41d-15cbe03791c0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• ✅ Review completed - (🔄 Check again to review again)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/workflow-owned-merge-s18-docs-settings-release

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR delivers the S18 documentation layer for the workflow-owned merge migration stack, adding a runtime API reference document, glossary terms, an architecture patterns solutions doc, testing guidance, and a plan handoff artifact. All API surface names, state literals, and kind values in the new docs were verified against the source (WORKFLOW_WORK_ITEM_STATES, WORKFLOW_WORK_ITEM_KINDS in packages/core/src/types.ts) and the implementation files.

• docs/workflow-owned-merge-runtime.md documents the implemented runtime surfaces (claimDueWorkflowWorkItem, runWorkItem, publishWorkflowRecoveryEvent, projectWorkflowWorkStatus) along with the four deletion-guard test files.
• docs/solutions/architecture-patterns/workflow-owned-merge-stack-feedback-resolution.md captures the stacked-PR review-feedback workflow and includes correction patterns (projection cleanup, classifier routing, retry nullish checks, recovery events, guard tests).
• CONCEPTS.md adds "Workflow Work Item" and "Stacked PR" glossary entries; docs/testing.md adds targeted guidance for running migration guard tests.

Confidence Score: 5/5

Documentation-only changes with no runtime behavior modifications; safe to merge.

All six changed files are pure documentation. The state literals, kind values, and API surface names in the new runtime reference doc were verified directly against packages/core/src/types.ts and the implementation files — every value matches. All cross-referenced solution docs and the full-plan file exist on disk. The one inaccuracy found (nodeId vs kind label in a single bullet point) has a suggestion attached and does not affect any runtime behavior.

docs/workflow-owned-merge-runtime.md — one bullet mislabels the recovery-router nodeId as the work item kind (kind is recovery); a suggestion is attached.

Important Files Changed

Filename	Overview
docs/workflow-owned-merge-runtime.md	New runtime reference doc; all state/kind literals verified against types.ts, but 'recovery-router work' conflates nodeId with kind (kind is recovery, nodeId is recovery-router).
docs/solutions/architecture-patterns/workflow-owned-merge-stack-feedback-resolution.md	New solutions doc capturing stacked-PR feedback patterns; code snippets are accurate, cross-references to related docs all exist.
CONCEPTS.md	Adds Workflow Work Item and Stacked PR glossary terms in contextually correct positions; consistent with usage throughout the runtime docs.
docs/architecture.md	Adds a short reference paragraph linking to workflow-owned-merge-runtime.md; relative path resolves correctly.
docs/testing.md	Adds targeted guidance for migration guard tests; glob pattern workflow-*-deletion.test.ts correctly matches the three confirmed deletion-guard test files.
docs/plans/workflow-owned-merge-stack/s18-docs-settings-release.md	Stack handoff artifact; full-plan reference resolves to an existing file.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph "Workflow-Owned Merge Runtime (documented in this PR)"
        WI["workflow_work_items\n(runnable/running/held/retrying/\nmanual-required/succeeded/\nfailed/cancelled/exhausted)"]
        CLAIM["claimDueWorkflowWorkItem\n(leases due work)"]
        RUN["WorkflowTaskRuntime.runWorkItem\n(executes leased node)"]
        MERGE["runWorkflowMergeAttemptNode\n(calls guarded merge primitive)"]
        RECOVERY["publishWorkflowRecoveryEvent\n(self-healing facts to\nrecovery work item\nat recovery-router node)"]
        PROJ_STATUS["projectWorkflowWorkStatus\n(workflow-first projection\nfor dashboard/API/CLI)"]
    end
    subgraph "Projection from Legacy"
        PROJ_MR["TaskStore.projectMergeRequestToWorkflowWorkItem"]
        HANDOFF["createCompletionHandoffWorkflowWork\n(merge-gate / merge-manual-hold)"]
    end
    subgraph "Cutover Guards"
        G1["workflow-scheduler-policy-deletion.test.ts"]
        G2["workflow-merge-policy-deletion.test.ts"]
        G3["workflow-self-healing-policy-deletion.test.ts"]
        G4["workflow-cutover-matrix.test.ts"]
    end
    PROJ_MR --> WI
    HANDOFF --> WI
    WI --> CLAIM
    CLAIM --> RUN
    RUN --> MERGE
    RUN --> RECOVERY
    RECOVERY --> WI
    WI --> PROJ_STATUS
    G1 -.->|guards against| WI
    G2 -.->|guards against| MERGE
    G3 -.->|guards against| RECOVERY
    G4 -.->|cutover matrix| WI

Loading

_{Reviews (11): Last reviewed commit: "fix(FN-000): complete workflow stack ver..." | Re-trigger Greptile}

[gsxdsm]

Addressed Greptile commit-message feedback by rewriting the S18 branch to a single compliant commit: fix(FN-000): document workflow-owned merge runtime with Fusion-Task-Id: FN-000 trailer (962767f64). The old docs(workflow): ... placeholder commits are no longer in the S18 branch history.

[gsxdsm]

The new \workflow-owned-merge-runtime.md\\ lists \manual\\ and \recovery\\ as work-item states, but neither exists in the canonical \WORKFLOW_WORK_ITEM_STATES\\ enum.

Addressed: corrected docs/workflow-owned-merge-runtime.md so the persisted state list matches WORKFLOW_WORK_ITEM_STATES (runnable, running, held, retrying, manual-required, succeeded, failed, cancelled, exhausted) and documented recovery separately as a workflow work item kind.

[stage-review]

Ready to review this PR? Stage has broken it down into 4 individual chapters for you:

	Title
1	Define core workflow work item concepts
2	Document workflow-owned merge runtime and architecture
3	Establish stacked PR feedback resolution patterns
4	Update testing guidance and release planning

_{Chapters generated by Stage for commit ab59d72 on Jun 16, 2026 9:20am UTC.}