feat(linear): parent/sub-issue orchestration with dependency-aware child tasks

[krokoko]

Component

API or orchestration, Scripts / CLI

Describe the feature

Support Linear parent/sub-issue orchestration: when a parent Linear issue has sub-issues (or a defined dependency graph), ABCA creates and manages child tasks in dependency order, rolls up progress to the parent issue, and respects blocking relationships — enabling PM-native multi-step work without manual per-sub-issue label triggers.

Today Linear integration is one issue → one task (label trigger on a single issue). ADR-001 and ADR-003 describe sub-issue linking and blocked by / blocking graphs for GitHub stacked work, but Linear has no equivalent orchestration path.

Use case

• Epics with sub-tasks: A parent Linear issue decomposes into implementable slices; agents pick up unblocked sub-issues automatically.
• Stacked delivery: Sub-issues express dependency order (mirrors ADR-001 stack semantics); parent issue shows aggregate status.
• Fire-and-forget at epic scale: Submitters label the parent (or a designated orchestrator issue) once; the platform drives the subgraph.
• Attribution: Each child task retains its own task_id and correlation context (#TBD identity issue); parent comments link to child tasks and PRs.

Proposed solution

Phase 0 — Discovery

• On parent trigger (label or explicit task_type / capability ref), fetch sub-issues via Linear API (subIssues, blockedBy / blocking relations per ADR-003 graph maintenance).
• Build a DAG; reject cycles with a clear terminal error on the parent issue.

Phase 1 — Child task creation

• Create platform tasks for eligible sub-issues in topological order.
• Store parent ↔ child mapping on task records (and/or a lightweight mapping table).
• Only start children whose predecessors are terminal-success (or explicitly allow parallel siblings).

Phase 2 — Progress rollup

• Post structured progress on the parent Linear issue: child started / completed / failed, links to PRs and bgagent status.
• Terminal parent state when all children terminal (or operator cancels parent → cascade cancel children).

Phase 3 — PR strategy (design choice in implementation PR)

• Option A: One PR per sub-issue (ADR-001 stack-friendly).
• Option B: Single consolidated PR (closer to Agent swarm roadmap item) — likely a follow-up issue.

Out of scope for MVP

• Full Agent swarm planner-worker architecture (platform-level DAG beyond Linear).
• Auto-merge when all children complete.
• Multi-workspace parent/child graphs spanning org boundaries.

Acceptance criteria

• Parent Linear issue with sub-issues can trigger orchestrated child task creation (documented trigger mechanism).
• Dependency order respected; blocked sub-issues not started until predecessors succeed.
• Parent issue receives rollup comments for child lifecycle milestones.
• Each child task is independently cancellable; parent cancel propagates (or documented opt-out).
• Mapping durable across orchestrator retries; idempotent on webhook replay.
• Docs: Linear setup guide + roadmap row for Linear subtasks; Starlight sync.

Other information

• Roadmap gap: Not yet listed in docs/guides/ROADMAP.md — add when implementation starts.
• Related: Shipped Linear label integration (LINEAR_SETUP_GUIDE.md), ADR-001 (sub-issue linking), ADR-003 (graph maintenance), Agent swarm (roadmap), feat(notifications): platform-side final-status Linear comment with cost/turns/duration #239 (Linear final-status comment — complementary).
• Depends on (soft): Identity propagation for clean parent/child attribution in comments and audit.

Acknowledgements

• I may be able to implement this feature
• This might be a breaking change

[isadeks]

Implementation plan — Mode A (orchestration executor)

#247 is scoped to the orchestration executor exactly as the body describes: consume an existing parent/sub-issue + blockedBy graph authored in Linear, create child tasks in dependency order, gate blocked children, and roll up to the parent. The agent runtime is essentially unchanged (one small base-branch widening).

Auto-decomposition (ABCA generating the graph, plan-approval, cost estimates) is a separate, stacked issue (#299) that builds on this executor and supersedes the "planner-worker out of scope" line with its own approval. Keeps #247's approved scope frozen (ADR-003) and ships value incrementally.

Decisions

• Substrate: reconciler Lambda + OrchestrationTable (DynamoDB DAG). No new orchestration engine; children are ordinary createTaskCore tasks.
• PR strategy: stacked PRs per ADR-001 — dependent child branches from its predecessor's branch; roots target main.
• Failure: halt transitive dependents, finish independent siblings, partial-failure rollup on the parent. Release gate = COMPLETED && build_passed !== false (a built-but-broken child does not release dependents). Stuck children are reaped by the existing reconcile-stranded-tasks sweep — no new timeout logic. Auto-retry, mid-flight graph re-sync, and orphaned-base-branch handling are explicit follow-ups.
• Labels: Mode A needs no special label — a plain bgagent on a parent that already has sub-issues executes the graph. The :decompose/:auto suffixes are a feat(linear): auto-decompose issues into a dependency-aware sub-issue graph (plan + approval) #299 (Mode B) concern and are no-ops when sub-issues already exist.
• Rollup comments: emitted by this executor, rendered by the feat(notifications): Linear dispatcher in fanout consumer (cost/turns/duration) #243 fan-out plane — not the agent prompt.
• Auth: per-workspace OAuth via resolveLinearOauthToken for the graph fetch.

Open design question (call it in the impl PR)

TaskEventsTable's DynamoDB Stream is at its 2-consumer limit (FanOutConsumer + approval-metrics). The reconciler's terminal-state trigger must source from the TaskTable stream or piggyback FanOutConsumer instead. Leaning TaskTable.

Sequencing (stacked PRs)

1. A1 — Orchestration data model (OrchestrationTable + TaskRecord fields)
2. A2 — Graph discovery + cycle rejection
3. A3 — Reconciler + child creation/gating ← deploy-gate PR
4. A4 — Stacked base-branch targeting (small agent change: honor base_branch for new_task in repo.py/post_hooks.py)
5. A5 — Parent rollup (via feat(notifications): Linear dispatcher in fanout consumer (cost/turns/duration) #243) + cancel propagation + docs

Failure semantics (A3 test matrix)

#	Edge case	Handling (MVP)
1	Child COMPLETED but build_passed=false	Not success — don't release dependents. Gate = COMPLETED && build_passed !== false.
2	Diamond (D depends on B+C; B ok, C fails)	D blocked — gate is all preds succeeded, not any.
3	Reconciler double-fire (stream redelivery / simultaneous preds)	Idempotent create — conditional write keyed orchestration_id#sub_issue_id.
4	Child hangs / never terminal	No new logic — existing stranded-task + heartbeat reaper fails it eventually.
5	Predecessor PR human-closed after dependent branched off it	Out of scope MVP — document; follow-up.
6	Parent cancelled while child mid-FINALIZING	Existing per-task cancel handles child; reconciler must not re-release dependents post-cancel.
7	Linear graph mutated mid-flight	Freeze graph at discovery for MVP — no re-sync (follow-up).
8	Rollup event write fails after last child terminal	Best-effort (matches task_created pattern); parent state derivable from child rows.

[isadeks]

Starting implementation (Mode A executor).

Beginning with A1 — orchestration data model on branch feat/247-orchestration-data-model (off main): the OrchestrationTable construct (PK orchestration_id, SK sub_issue_id, GSI ChildTaskIndex for child-task → orchestration resolution) plus three optional TaskRecord fields (orchestration_id, parent_task_id, depends_on). No behavior change and the table is not yet stack-wired — deploy-safe foundational slice per ADR-001. Subsequent stacked PRs: A2 (graph discovery + cycle rejection), A3 (reconciler + gating — deploy gate), A4 (stacked base-branch targeting), A5 (rollup via #243 + cancel + docs).

[isadeks]

Build sequence update (post dev-smoke)

First dev smoke of A1–A3 validated the core gating end-to-end (roots release, dependents gate on predecessor success, reconciler creates the unblocked child) but surfaced 3 bugs (idempotency-key #→400, reconciler 256MB OOM, orchestration_id read top-level vs. nested channel_metadata) — all fixed, plus an orchestration-debug.sh helper + response-body logging added.

Two gaps the smoke exposed are now sequenced before resuming the A-series:

1. test(linear): add orchestration integration test against real createTaskCore (unit mocks hid 3 dev bugs) #304 — integration test against the real createTaskCore (unit mocks hid all 3 bugs). Built first so it harnesses the rest.
2. fix(linear): orchestration reconciler loses terminal events during outages (no stranded-orchestration backstop) #303 — stranded-orchestration backstop (terminal events lost during a reconciler outage are never recovered — hit live).

Then the remaining executor work:

• A4 — stacked base-branch targeting (child PR base = predecessor branch; roots → main).
• A5 — parent rollup via feat(notifications): Linear dispatcher in fanout consumer (cost/turns/duration) #243 + cancel propagation + docs.
• feat(linear): re-integrate dependent child PRs when a predecessor changes (#247 A6) #305 (A6) — auto-restack dependent PRs on merge; conflicts resolved by spawning an agent task, not escalated to a human (PR review is the safety net).
• Later — auto-merge the stack (separate issue; gated on approvals + CI via merge queue).

Merge-flow research (GitHub auto-retarget-on-branch-delete, bottom-up sequential merges, downstream PRs see upstream code via branch lineage without waiting for merge) is captured in docs/research/stacked-pr-merge-practices.md. Note: ADR-001 is ambiguous on the merge model ("PR N targets PR N-1" vs "final PR merges the stack") and should be amended to the bottom-up reading.

Sequence: #304 → #303 → A4 → A5 → #305.