Merge pull request #70 from InverterNetwork/dev

Release dev to main

Author: lafawnduh1966

docs/user/cli-reference.md

@@ -255,14 +255,16 @@ incomplete untracked blockers fail with `dependency_not_tracked`.
 
 Linear-backed umbrella workflows use native Linear parent/child hierarchy. If
 the issue has Linear children, enqueue creates the umbrella workflow, derives
-the shared feature branch, and records the expected child set without spawning
-a subtask worker. If the issue has a Linear parent, enqueue requires that the
-parent umbrella has already been enqueued, verifies the child is expected, and
-targets the child task at the umbrella feature branch.
+the shared feature branch, records the expected child set, and materializes
+incomplete children as Quay tasks targeted at that feature branch. Children
+that are already complete in Linear are recorded as `complete_without_quay` and
+do not get Quay tasks. If the issue has a Linear parent, direct enqueue fails
+with `umbrella_child_direct_enqueue` unless `--as-normal-task` is passed.
 
 Umbrella parent enqueue returns coordination JSON instead of the normal task
 enqueue payload. The `expected_tasks` array exposes each persisted child row,
-including state values such as `expected` and `complete_without_quay`.
+including state values such as `linked` and `complete_without_quay`; the
+`child_tasks` array exposes materialized child task enqueue results.
 
 `--as-normal-task` applies to Linear child issues only. It ignores the child's
 native parent umbrella membership for this enqueue, but it does not turn a

docs/user/concepts.md

@@ -136,10 +136,12 @@ feature branch, and snapshots the expected Linear child set. Tick never polls
 Linear to discover changed membership later.
 
 Each umbrella child target uses the shared feature branch as its effective PR
-base. Child enqueue links the concrete Quay task to an expected child row. If a
-child was already complete in Linear when discovered, Quay can mark that
-expected row `complete_without_quay`; it then counts toward final readiness
-without requiring a Quay task.
+base. Parent enqueue materializes each incomplete child as a concrete Quay task
+and links it to an expected child row. If a child was already complete in
+Linear when discovered, Quay marks that expected row `complete_without_quay`;
+it then counts toward final readiness without requiring a Quay task. Direct
+enqueue of a child issue is not part of the umbrella flow and fails unless the
+operator passes `--as-normal-task`.
 
 Linear blocked-by relations define ordering. Same-umbrella dependency rows use
 `scope: "umbrella"` and wait for blockers to reach

docs/user/enqueueing-tasks.md

@@ -90,16 +90,17 @@ reaches `merged`. Incomplete untracked blockers fail enqueue with
 
 Umbrella workflows are driven by native Linear hierarchy. Enqueue the parent
 issue first; Quay records the expected child set and creates the shared feature
-branch. Enqueue child issues afterwards; Quay resolves the parent workflow from
-the child's Linear parent relation and targets the child task at the umbrella
-feature branch.
-
-Child-before-parent enqueue fails with `umbrella_not_enqueued`. A child not in
-the parent's persisted expected set fails with `umbrella_subtask_not_expected`.
-Use `--as-normal-task` on a child issue only to intentionally ignore the
-Linear parent umbrella membership for one enqueue. Parent issues with children
-still create umbrella coordination state. The flag still processes Linear
-blocked-by relations as normal dependencies.
+branch. Incomplete children are materialized as Quay tasks during the parent
+enqueue and target the umbrella feature branch; children already complete in
+Linear are recorded as `complete_without_quay`.
+
+Do not enqueue child issues afterwards for the umbrella flow. Direct child
+enqueue fails with `umbrella_child_direct_enqueue`, including after the parent
+has already materialized the child task. Use `--as-normal-task` on a child
+issue only to intentionally ignore the Linear parent umbrella membership for
+one enqueue. Parent issues with children still create umbrella coordination
+state. The flag still processes Linear blocked-by relations as normal
+dependencies.
 
 Inside an umbrella, Linear blocked-by relations create umbrella-scoped
 dependency rows. Same-umbrella blockers wait for

docs/user/index.md

@@ -25,6 +25,8 @@ verify against the CLI implementation and tests, then fix the docs.
 - [Monitoring And Artifacts](monitoring-and-artifacts.md): task JSON, events,
   and artifact retrieval.
 - [Linear And Slack](linear-and-slack.md): adapter setup and behavior.
+- [Parent-Owned Umbrella QA Matrix](qa-parent-owned-umbrella.md): deployed
+  Linear and test-repo validation scenarios for dependency and umbrella flows.
 - [Ticket Authoring](ticket-authoring.md): the `quay-config` block and ticket
   validation.
 - [Troubleshooting](troubleshooting.md): common errors and recovery paths.

docs/user/linear-and-slack.md

@@ -80,9 +80,11 @@ quay enqueue --repo myrepo --linear-issue ENG-200
 
 If the issue has native Linear child issues, Quay creates or verifies a shared
 feature branch derived from the parent external ref, persists an umbrella
-workflow row, and records every child in `umbrella_expected_tasks`. Children
-that are already complete in Linear are recorded as `complete_without_quay`.
-No worker is spawned for the umbrella parent in the current flow.
+workflow row, records every child in `umbrella_expected_tasks`, and
+materializes every incomplete child as a Quay task targeting the umbrella
+feature branch. Children that are already complete in Linear are recorded as
+`complete_without_quay` and do not get Quay tasks. No worker is spawned for the
+umbrella parent in the current flow.
 
 Child tickets use ordinary `quay-config` execution metadata:
 
@@ -95,10 +97,9 @@ authors:
     slack_id: U06TDC56VJB
 ```
 
-When a child is enqueued, Quay resolves its native Linear parent to the
-persisted umbrella workflow and verifies the child is in the expected set. A
-child-before-parent enqueue fails with `umbrella_not_enqueued`; a child missing
-from the persisted expected set fails with `umbrella_subtask_not_expected`.
+Do not enqueue child tickets individually for the umbrella flow. Direct enqueue
+of a Linear child issue fails with `umbrella_child_direct_enqueue`, even if the
+parent umbrella was already enqueued and the child task already exists.
 
 Pass `--as-normal-task` only on a child issue when you intentionally want to
 ignore its native Linear parent membership for this enqueue. The flag does not

docs/user/qa-parent-owned-umbrella.md

@@ -0,0 +1,44 @@
+# Parent-Owned Umbrella QA Matrix
+
+Use this matrix when validating Quay against a deployed Linear workspace and a
+test repository. Each scenario assumes the test repo is registered in Quay and
+the Linear issues contain valid ordinary `quay-config` blocks with `repo`,
+`tags`, and `authors`.
+
+## Blocked-By Dependencies
+
+| Scenario | Setup | Expected result |
+| --- | --- | --- |
+| Complete blocker | Issue B is blocked by issue A, and A is already complete in Linear. | Enqueueing B succeeds as a normal task. The ticket snapshot records A, but no blocking dependency row is created. |
+| Incomplete tracked blocker | A has an existing Quay task that is not merged. B is blocked by A. | Enqueueing B creates a task in `waiting_dependencies` with a dependency on A requiring `merged`. |
+| Incomplete untracked blocker | B is blocked by A, A is incomplete in Linear, and A has no Quay task. | Enqueueing B fails with `dependency_not_tracked` before creating a task, worktree, or artifact. |
+
+## Parent-Owned Umbrella Enqueue
+
+| Scenario | Setup | Expected result |
+| --- | --- | --- |
+| Parent with incomplete children | Parent P has children C1 and C2, both incomplete. | Enqueueing P creates or verifies the umbrella feature branch, persists the expected child rows, and materializes C1/C2 as Quay tasks targeting the feature branch. No parent worker task is spawned. |
+| Parent with completed child | Parent P has child C1 complete in Linear and child C2 incomplete. | Enqueueing P marks C1 `complete_without_quay` and materializes only C2 as a Quay task. |
+| Same-umbrella child ordering | Parent P has children C1 and C2, and C2 is blocked by C1. | Enqueueing P materializes both tasks and creates an umbrella-scoped dependency from C2 to C1 requiring `merged_to_feature_branch`. |
+| External blocker inside umbrella child | Child C1 is blocked by issue A outside the umbrella. | If A is tracked, C1 waits for A with normal `merged` semantics. If A is incomplete and untracked, parent enqueue fails before side effects. |
+| Umbrella dependency cycle | Children C1 and C2 block each other through Linear blocked-by relations. | Parent enqueue fails with `umbrella_dependency_cycle` before creating child tasks or worktrees. |
+
+## Direct Child Enqueue
+
+| Scenario | Setup | Expected result |
+| --- | --- | --- |
+| Child before parent | Child C1 has parent P, but P has not been enqueued. | Direct enqueue of C1 fails with `umbrella_child_direct_enqueue`. |
+| Child after parent | Parent P has already materialized C1 as a Quay task. | Direct enqueue of C1 still fails with `umbrella_child_direct_enqueue`; existing child tasks must not bypass the guard. |
+| Child override | C1 has parent P, and the operator passes `--as-normal-task`. | C1 is processed as a normal task, with no umbrella task link. Linear blocked-by relations still become normal dependencies. |
+
+## PR Lifecycle
+
+| Scenario | Setup | Expected result |
+| --- | --- | --- |
+| Approved subtask PR | A materialized child task opens a PR into the umbrella feature branch and receives approval with green CI. | Quay may merge the child PR into the umbrella feature branch and mark the child `merged_to_feature_branch`. |
+| Final umbrella PR | All expected children are either `merged_to_feature_branch` or `complete_without_quay`. | Tick creates or reuses the final umbrella PR from the feature branch into the parent base branch, with a title/body based on the parent issue and links to subtasks. |
+| Final PR merge authority | The final umbrella PR is approved and green. | Quay must not merge the final PR. A human merges it; Quay only observes the merge and marks the umbrella workflow complete. |
+
+For every scenario, capture the Linear issue identifiers, task ids, PR numbers,
+and the relevant `quay task get --json` output so regressions can be compared
+without relying on transient UI state.

docs/user/troubleshooting.md

@@ -104,33 +104,31 @@ Fix one of:
   blockers do not block enqueue.
 - Remove the Linear blocked-by relation if it is not a real dependency.
 
-## `umbrella_not_enqueued`
+## `umbrella_child_direct_enqueue`
 
-`quay enqueue --linear-issue` found that the Linear issue is a child of an
-umbrella parent, but Quay has no persisted umbrella workflow for that parent.
-Quay stops before creating the child task because it would not know the shared
-feature branch or expected child set.
+`quay enqueue --linear-issue` found that the Linear issue is a child of a
+Linear umbrella parent. Quay stops before creating or returning a task because
+the parent issue owns the umbrella flow and materializes child tasks itself.
 
 Fix one of:
 
-- Enqueue the Linear parent issue first, then enqueue the child again.
+- Enqueue the Linear parent issue instead.
 - Pass `--as-normal-task` if this child should intentionally run outside the
   umbrella workflow. This ignores the child's Linear parent membership only;
   Linear blocked-by relations are still processed as normal dependencies.
 
-## `umbrella_subtask_not_expected`
+## `umbrella_dependency_cycle`
 
-The Linear child has a parent umbrella workflow, but its external ref is not in
-the expected child set that Quay persisted when the parent was enqueued.
+Parent enqueue found a cycle among incomplete Linear children connected by
+same-umbrella blocked-by relations. Quay stops before creating tasks because no
+valid execution order exists.
 
 Fix one of:
 
-- Confirm the child is attached to the correct Linear parent.
-- Recreate or manually repair the umbrella workflow if the Linear child set was
-  changed after parent enqueue. Automatic resync is not part of the current
-  tick loop.
-- Pass `--as-normal-task` only if this child issue should run outside the
-  umbrella.
+- Remove or correct one of the Linear blocked-by relations in the cycle.
+- Split the umbrella into smaller parent issues if the work is not actually a
+  strict dependency chain.
+- Mark a blocker complete in Linear if it is already done outside Quay.
 
 ## `umbrella_feature_branch_missing`
 
@@ -142,9 +140,7 @@ integrated work.
 Fix one of:
 
 - Restore the missing feature branch to the expected remote ref.
-- Cancel or repair the umbrella workflow before enqueueing more subtasks.
-- If the child should intentionally run outside the umbrella, enqueue it with
-  `--as-normal-task`.
+- Cancel or repair the umbrella workflow before re-enqueueing the parent.
 
 ## `dependency_cycle`