Dependent-spec chains: branch from the parent, link GitHub stacks

[gmickel]

Dependent-spec chains: branch from the parent, link GitHub stacks

A spec that depends on another spec waits today until the parent's pull request has merged. This PR removes that wait: a dependent spec branches from its parent, targets the parent's PR, and on GitHub joins its stack.

Spec: fn-152-make-pr-opt-in-stack-linking-via-github
Branch: fn-152-make-pr-opt-in-stack-linking-via-github → fn-149-land-hardening-survive-stacked-pr-auto
Tasks: 1 completed
R-ID coverage: 14/14 evidenced
Stack: #434, layer 2 of 2

TL;DR

• A dependent spec becomes selectable as soon as its parent's tasks are done and the parent branch is on origin, instead of waiting for the parent's merge; nothing is configured, the dependency graph is the only input.
• One read-only flowctl command owns chain eligibility, and flowctl's own task-admission gate, both flow --auto selectors, the attended ladder, work, and make-pr all call it instead of duplicating the rule.
• Work forks the spec branch from the parent's remote tip; make-pr detects a chain from git history, targets the parent's PR, rewrites a merged parent from the exact boundary on a create run only, and links the layers into a GitHub stack with a one-line degrade when the API refuses.
• Chained layers with nothing open are created ready so a human can merge them from the stack UI; specs with no dependency edges keep the byte-identical cascade, draft matrix, and verdicts.
• This PR is itself the first chain: its base is the fn-149 branch whose PR Land chains and stacks: frontier merge, patch-id carry-over, retarget #432 lands the merge side.

Not in this PR (by design)

• No merge, retarget, rebase-after-merge, branch deletion, or patch-id logic. Landing a chain is fn-149.
• No stack restructuring: reorder, fold, insert, or unstack. A human uses GitHub's UI or the gh-stack extension for those; flow-next never…
• No merge-queue enrolment and no auto-merge arming.
• No local stack-tracking files, no gh-stack dependency, no Graphite or other stacking tool.
• No cross-repository or fork chains.
• …and 3 more (see spec)

The change, top to bottom

Dependent specs chain on their parent's branch instead of waiting for its merge: one flowctl predicate owns eligibility, work forks from the parent tip, make-pr targets the parent PR and links a GitHub stack, and flow --auto parks with the predicate's reason; specs with no dependency edges are untouched.

Proof	Value	Sources
Artifact	fn-152-chain-authoring-2d70e23bdf8c	artifact identity
Base commit	b118f5cac40f1d9e9982dc35b4a3dd12699ddafa	artifact currentness
Head commit	2d70e23bdf8ce3fe33697b0767ec796eafbbfdf2	artifact identity
Human-review lines	1619	deterministic file stats
Canonical files	19	deterministic membership
Total files	37	deterministic membership
Tests	python3 scripts/run_tests_parallel.py: 220 files, 4991 tests, 0 failures on the tree committed as 0989bb4	source:task, source:commit-2
Focused suites	test_spec_chain (13), test_chain_consumer_fixtures (30), test_land_chain_fixtures (38) green	source:task, source:commit-0
Lint	uvx ruff@0.16.0 check . green	source:task
Review	codex gpt-6-astra impl-review: NEEDS_WORK 5 findings, then SHIP	source:task, source:commit-1, source:commit-2
Mirror	sync-codex.sh run twice, mirror committed	source:task, source:commit-0

Legend: WHY PRINCIPLE STEP KEPT VERIFY · NEW MODIFIED DELETED RENAMED COPIED · CANONICAL GENERATED MECHANICAL

WHY 1. Problem — A dependent spec waits for its parent's PR to merge: flow --auto parks it, backlog mode logs it blocked, and a direct work run builds it off the default branch with no dependency check.

Evidence: source:spec, source:rid-R1, source:rid-R3, R-ID:R1, R-ID:R3

PRINCIPLE 2. Principle — One predicate owns chain eligibility in flowctl and every consumer calls it; chain identity is derived from git history, never from a scratch file or a sidecar field; no config key.

Evidence: source:spec, source:rid-R2, source:rid-R10, R-ID:R2, R-ID:R10

STEP 3. The chain predicate and the admission gate — flowctl spec chain evaluates eligibility (parent open, all tasks done, branch on origin, linear only, one ls-remote) and the spec-level admission gate treats the chain parent as satisfied.

Evidence: source:spec, source:rid-R1, source:rid-R2, source:rid-R2a, source:rid-R10, source:rid-R11, source:task, R-ID:R1, R-ID:R2, R-ID:R2a, R-ID:R10, R-ID:R11, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	CANONICAL	plugins/flow-next/scripts/flowctl.py	evaluate_spec_chain, spec_blocked_by_deps, cmd_spec_chain, RemoteHeads, and the optional pilot-log reason.	+235/-44	diff	source:diff, source:task, source:rid-R1, source:rid-R2, source:rid-R2a, source:rid-R9, source:rid-R10, R-ID:R1, R-ID:R2, R-ID:R2a, R-ID:R9, R-ID:R10, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Generated/mechanical files (1)

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	MECHANICAL	plugins/flow-next/scripts/flowctl_tracker/MANIFEST.json	Tracker manifest hash refreshed by the generator.	+1/-1	diff	source:diff, source:task, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

STEP 4. Selection parks with the predicate's reason — flow --auto ready and backlog selection call the predicate, park without a strike, and prefix the verdict and decision-log reason with the chain parent; the attended ladder applies the same command.

Evidence: source:spec, source:rid-R3, source:rid-R9, source:task, R-ID:R3, R-ID:R9, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	CANONICAL	plugins/flow-next/skills/flow-next-flow/auto.md	Dependency conjunct replaced by the predicate; verdict reason prefix.	+15/-6	diff	source:diff, source:task, source:rid-R3, source:rid-R9, R-ID:R3, R-ID:R9, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/skills/flow-next-flow/references/backlog-mode.md	Backlog selection and the blocked row carry the command's reason.	+15/-2	diff	source:diff, source:task, source:rid-R3, source:rid-R9, R-ID:R3, R-ID:R9, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/skills/flow-next-flow/workflow.md	Attended ladder applies the predicate.	+1/-1	diff	source:diff, source:task, source:rid-R3, R-ID:R3, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Generated/mechanical files (3)

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	GENERATED	plugins/flow-next/codex/skills/flow-next-flow/auto.md	Codex mirror.	+15/-6	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	GENERATED	plugins/flow-next/codex/skills/flow-next-flow/references/backlog-mode.md	Codex mirror.	+15/-2	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	GENERATED	plugins/flow-next/codex/skills/flow-next-flow/workflow.md	Codex mirror.	+1/-1	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

STEP 5. Work branches from the parent's remote tip — The spec branch forks from origin/<parent>, the spec base is that merge-base, --branch=current checks ancestry, and spec files are carried across when the parent tip lacks them.

Evidence: source:spec, source:rid-R4, source:task, R-ID:R4, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	CANONICAL	plugins/flow-next/skills/flow-next-work/phases.md	Phase 2 branch step reads the predicate and forks from the parent tip.	+46/-13	diff	source:diff, source:task, source:rid-R4, R-ID:R4, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/skills/flow-next-work/SKILL.md	Branch rule pointer.	+1/-1	diff	source:diff, source:task, source:rid-R4, R-ID:R4, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Generated/mechanical files (2)

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	GENERATED	plugins/flow-next/codex/skills/flow-next-work/phases.md	Codex mirror.	+46/-13	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	GENERATED	plugins/flow-next/codex/skills/flow-next-work/SKILL.md	Codex mirror.	+1/-1	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

STEP 6. Make-pr detects the chain from history and links the stack — The chain rung sets the base to the parent's remote-tracking ref when its PR is open, rewrites a merged parent from the merge-base boundary on a create run only, links the stack with integer-typed REST payloads, degrades in one line, and creates chained layers ready.

Evidence: source:spec, source:rid-R5, source:rid-R6, source:rid-R7, source:rid-R8, source:task, R-ID:R5, R-ID:R6, R-ID:R7, R-ID:R8, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	CANONICAL	plugins/flow-next/skills/flow-next-make-pr/workflow.md	chain-detect and chain-rewrite fences in the base cascade.	+137/-9	diff	source:diff, source:task, source:rid-R5, R-ID:R5, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/skills/flow-next-make-pr/create-and-finalize.md	draft-matrix exception, stack-link call, Stack line refresh.	+85/-0	diff	source:diff, source:task, source:rid-R6, source:rid-R7, source:rid-R8, R-ID:R6, R-ID:R7, R-ID:R8, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/skills/flow-next-make-pr/SKILL.md	Cascade description gains the chain rung.	+2/-2	diff	source:diff, source:task, source:rid-R5, R-ID:R5, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Generated/mechanical files (3)

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	GENERATED	plugins/flow-next/codex/skills/flow-next-make-pr/workflow.md	Codex mirror.	+137/-9	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	GENERATED	plugins/flow-next/codex/skills/flow-next-make-pr/create-and-finalize.md	Codex mirror.	+85/-0	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	GENERATED	plugins/flow-next/codex/skills/flow-next-make-pr/SKILL.md	Codex mirror.	+2/-2	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

STEP 7. Fixtures over a bare origin and a stubbed gh — flowctl chain states and admission gates, plus fence fixtures for every consumer under set -e with a recording gh stub.

Evidence: source:spec, source:rid-R13, source:task, R-ID:R13, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Change	Attention	File	Purpose	+/-	Diff	Evidence
NEW	CANONICAL	plugins/flow-next/tests/test_spec_chain.py	Predicate states, sibling refusal, remote failure, admission gate.	+225/-0	diff	source:diff, source:task, source:rid-R13, R-ID:R13, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
NEW	CANONICAL	plugins/flow-next/tests/test_chain_consumer_fixtures.py	Consumer fences: work ancestry, make-pr detection and rewrite, dry-run and update guards, stack payload types and degrades.	+524/-0	diff	source:diff, source:task, source:rid-R13, R-ID:R13, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/tests/fixtures/land_chain_gh_stub.py	Stub extended with stack create and add responses.	+42/-1	diff	source:diff, source:task, source:rid-R13, R-ID:R13, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/tests/test_flowctl_surface.py	Surface list gains spec chain.	+1/-0	diff	source:diff, source:task, source:rid-R13, R-ID:R13, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/tests/test_review_prompt_constraints.py	Constraint pins for the new fences.	+5/-0	diff	source:diff, source:task, source:rid-R13, R-ID:R13, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

STEP 8. Documentation, glossary, changelog, and spec state — flowctl reference rows, orchestration and teams pages, four glossary terms, the changelog entry, the 2026-08-27 memory entry superseded by the chain rules, and the spec state this branch carries.

Evidence: source:spec, source:rid-R12, source:task, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	CANONICAL	plugins/flow-next/docs/flowctl.md	spec chain and pilot-log append --reason rows.	+31/-3	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/docs/orchestration.md	Chains and stacks in the orchestration page.	+2/-0	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	plugins/flow-next/docs/teams.md	Chains in the teams page.	+1/-0	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	GLOSSARY.md	Chain, Stack, Layer, Frontier.	+168/-0	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	CANONICAL	CHANGELOG.md	Unreleased entry beside the fn-149 entry.	+1/-0	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Generated/mechanical files (9)

Change	Attention	File	Purpose	+/-	Diff	Evidence
MODIFIED	GENERATED	plugins/flow-next/codex/docs/flow-next/flowctl.md	Codex mirror.	+31/-3	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	GENERATED	plugins/flow-next/codex/docs/flow-next/orchestration.md	Codex mirror.	+2/-0	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	GENERATED	plugins/flow-next/codex/docs/flow-next/teams.md	Codex mirror.	+1/-0	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	MECHANICAL	.flow/memory/knowledge/workflow/stacked-pr-squash-close-recovery-2026-08-27.md	Recovery entry now points at the chain rules.	+9/-2	diff	source:diff, source:task, source:rid-R12, R-ID:R12, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
NEW	MECHANICAL	.flow/memory/bug/runtime-errors/skill-fences-that-degrade-only-without-2026-09-13.md	Bug memory captured from the review round.	+24/-0	diff	source:diff, source:task, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	MECHANICAL	.flow/specs/fn-152-make-pr-opt-in-stack-linking-via-github.md	Spec body: dogfooding note.	+1/-1	diff	source:diff, source:task, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
MODIFIED	MECHANICAL	.flow/specs/fn-152-make-pr-opt-in-stack-linking-via-github.json	Spec sidecar: readiness, title, completion status, dependency edge lifted for this run.	+190/-9	diff	source:diff, source:task, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
NEW	MECHANICAL	.flow/tasks/fn-152-make-pr-opt-in-stack-linking-via-github.1.md	Direct-route task with its done summary.	+26/-0	diff	source:diff, source:task, task:fn-152-make-pr-opt-in-stack-linking-via-github.1
NEW	MECHANICAL	.flow/tasks/fn-152-make-pr-opt-in-stack-linking-via-github.1.json	Task sidecar.	+15/-0	diff	source:diff, source:task, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

KEPT 9. Kept — No configuration key; the gh-stack extension is never required; a spec with no dependency edges takes the byte-identical cascade, draft matrix, and verdict output.

Evidence: source:spec, source:rid-R10, source:rid-R11, R-ID:R10, R-ID:R11

VERIFY 10. Verify — Full suite 220 files, 4991 tests, 0 failures on the committed tree; ruff clean; codex impl-review NEEDS_WORK with 5 findings then SHIP.

Evidence: source:task, task:fn-152-make-pr-opt-in-stack-linking-via-github.1

Critical changes

• High-churn: plugins/flow-next/tests/test_chain_consumer_fixtures.py (+524/-0 lines)
• High-churn: plugins/flow-next/scripts/flowctl.py (+235/-44 lines)
• High-churn: plugins/flow-next/tests/test_spec_chain.py (+225/-0 lines)
• High-churn: .flow/specs/fn-152-make-pr-opt-in-stack-linking-via-github.json (+190/-9 lines)
• High-churn: GLOSSARY.md (+168/-0 lines)

How to review this PR

The pipeline already verified this — you don't re-check it from scratch:

• Tests / gates: python3 scripts/run_tests_parallel.py on the committed tree, 220 files, 4991 tests, 0 failures; the three focused chain and land suites green; uvx ruff@0.16.0 check . green; the Codex mirror regenerated twice.
• R-ID coverage: 14/14 acceptance criteria evidenced (walkthrough above).
• Cross-model review: codex gpt-6-astra impl-review reached SHIP after one NEEDS_WORK round with 5 findings, with a stated focus on overengineering, YAGNI, and a single predicate owner.

Your job — the calls the pipeline can't make:

• Line-review the Must review bucket below — the ~25% that carries real judgment risk.
• Spot-check the verified claims above; sample, don't re-run everything.
• Own what machines can't judge: whether the predicate's refusals match the shapes you want parked, and whether the merged-parent rewrite in make-pr is as bounded as the spec promised.

Review plan

Must review (~25%)

• 🔴 plugins/flow-next/scripts/flowctl.py — second highest-churn file (+235/-44) and the only Python in the change — Does the chain predicate refuse every non-linear shape and treat a remote failure as failure rather than as an absent branch, and does the admission gate admit only the chain parent? — open evaluate_spec_chain and spec_blocked_by_deps
• 🔴 plugins/flow-next/skills/flow-next-make-pr/workflow.md — the base cascade changes (+137/-9) in the fence make-pr runs on every create — Is the merge-base test the only chain detector, and can the rewrite run under --dry-run or --update? — open the chain-detect and chain-rewrite fences
• 🔴 plugins/flow-next/skills/flow-next-make-pr/create-and-finalize.md — the stack link and the draft exception (+85) — Are the stack payloads integer-typed and does every non-2xx degrade to a plain chain layer without failing the create? — open the stack-link and draft-matrix fences
• 🔴 plugins/flow-next/skills/flow-next-work/phases.md — work's branch step now forks from a parent (+46/-13) — Does a --branch=current run without the parent tip in its ancestry stop before any task starts? — open the work-branch fence

Spot-check

• 🟡 plugins/flow-next/tests/test_chain_consumer_fixtures.py (+524) and plugins/flow-next/tests/test_spec_chain.py (+225) — the fixtures are the proof for R13; sample one scenario per consumer against the spec's error cases.
• 🟡 plugins/flow-next/tests/fixtures/land_chain_gh_stub.py, plugins/flow-next/tests/test_flowctl_surface.py, plugins/flow-next/tests/test_review_prompt_constraints.py — stub extension and surface pins.
• 🟡 Selection prose: plugins/flow-next/skills/flow-next-flow/auto.md, plugins/flow-next/skills/flow-next-flow/references/backlog-mode.md, plugins/flow-next/skills/flow-next-flow/workflow.md — the dependency conjunct is replaced by the predicate call and the reason prefix; confirm no jq copy of the rule remains.
• 🟡 plugins/flow-next/skills/flow-next-make-pr/SKILL.md and plugins/flow-next/skills/flow-next-work/SKILL.md — pointer edits.
• 🟡 5 docs files (GLOSSARY.md, CHANGELOG.md, plugins/flow-next/docs/flowctl.md, plugins/flow-next/docs/orchestration.md, plugins/flow-next/docs/teams.md) — glossary terms, flowctl rows, changelog; prose only.

Safe to skim (~30%)

• ⚪ 11 files under plugins/flow-next/codex/ — regenerated by sync-codex.sh, guard-verified — skim.
• ⚪ 7 state files under .flow/ plus the tracker MANIFEST.json hash — spec, task, and memory state, not hand-written code — skim.

Structural changes

The change adds no new module and no new import edge; every changed area already existed. plugins/flow-next/scripts/flowctl.py gains the chain predicate that the skill prose under plugins/flow-next/skills/flow-next-flow/, flow-next-work/, and flow-next-make-pr/ now calls, and the tests under plugins/flow-next/tests/ gain test_spec_chain.py and test_chain_consumer_fixtures.py. The Codex mirror under plugins/flow-next/codex/ is regenerated for each changed skill and docs file, and GLOSSARY.md, the docs pages, and the .flow/ state round it out.

graph TB
  spec["fn-152 chain authoring"]
  spec --> ctl["plugins/flow-next/scripts/flowctl.py"]
  spec --> skills["flow, work, make-pr skill prose (9 files)"]
  spec --> tests["plugins/flow-next/tests (5 files)"]
  spec --> docs["GLOSSARY, CHANGELOG, docs (5 files)"]
  spec --> mirror["plugins/flow-next/codex mirror (11 files)"]
  spec --> state[".flow specs, tasks, memory (6 files)"]

Loading

Decisions made

• Bugbot pre-push stage: won't-do - patch-ID dedup falsified live (knowledge/decisions/bugbot-pre-push-stage-wont-do-patch-id-2026-08-07) — fn-167 proposed a Bugbot pre-push review pilot stage, premised on Cursor Bugbot's documented patch-ID dedup: review locally via /review-bugbot, and the later PR review skips as already-reviewed - relocating the review pre-push at no extra…
• Pilot strike recovery is a CLI verb, not board-native transition detection (knowledge/decisions/pilot-strike-recovery-is-a-cli-verb-not-2026-08-11) — Pilot strike recovery under an armed tracker.readyState is a deterministic CLI verb (flowctl pilot strikes clear <spec-id>), NOT board-native transition detection.
• Ralph guard reverts its delegation amendment; bridge safety is prose-only (knowledge/decisions/ralph-guard-reverts-its-delegation-2026-08-14) — The Ralph guard's codex-delegation amendment reverts with the packaged delegation subsystem (flow-98, R8). Alternatives considered: Widen the guard to recognize prose-routed bridge invocations (rejected: Ralph is deprecated and bridge command shapes are agent-authored, so an allowlist would be a race against the next spelling).
• Review stall detection reads resolution; the trend heuristics are deleted (fn-168) (knowledge/decisions/review-stall-detection-reads-resolution-2026-08-05) — Non-compliance now produces expensive answers instead of wrong ones. That is the whole trade, and the direction of the flip is the point: Alternatives considered: |.
• Tracked-vs-runtime durability contract - done crosses it, validate respects it (knowledge/decisions/tracked-vs-runtime-durability-contract-2026-08-14) — Tracked files (.flow/specs, .flow/tasks) hold definition + narrative receipts; runtime state (git common-dir) holds lifecycle status and never travels with git.

Memory left behind

Bugs captured during this spec:

• bug/build-errors/canonical-3c-edits-vanish-from-codex-2026-08-28 — fn-208.2 added FORBIDDEN and TIMEBOX lines to the canonical work phases.md 3c worker dispatch template.
• bug/build-errors/changelog-entry-landed-in-a-released-2026-08-01 — A worker appended an ## Unreleased CHANGELOG entry that actually landed inside the most recent RELEASED version section (## [flow-next 3.13.1]), retroactively attributing unreleased work to a shipped release.
• bug/build-errors/codex-home-rewrite-both-spellings-2026-08-02 — Replacing a hardcoded $HOME/.codex with ${CODEX_HOME:-$HOME/.codex} across a generated artifact tree looks like a blanket substitution.
• bug/build-errors/concurrent-gating-draws-soft-terms-2026-08-21 — The fn-203 rolling-frontier eval pre-registration froze "all three arms launched same-second on one machine (contention hits all arms equally)" as its batch plan, plus soft terms ("~3x", "with margin", "borderline") and an unbounded batch-…
• bug/build-errors/concurrent-loop-skill-prose-linear-2026-08-22 — The fn-203.4 beta scheduler reference (rolling-frontier work variant) shipped its Phase-3 loop as "handle all of 3d (integrate + review + fix loop + done), then recompute admission" - which silently serializes admission behind each task's…
• bug/build-errors/delegating-cli-wrapper-inherits-2026-08-30 — The first cut of flowctl memory upsert (fn-212) drew four review findings, all the same shape: a delegating wrapper inherits the delegate's assumptions unless each one is re-checked against the wrapper's own contract.
• bug/build-errors/prose-tick-lock-claim-before-read-2026-08-28 — A prose-level tick lock added to the land conductor (fn-208.1) drew four review findings in one round: the ledger snapshot was read before the claim was taken (stale-snapshot gating), age-only stale clearing could evict a live long tick an…
• bug/build-errors/skill-flag-gating-a-durable-write-needs-2026-08-31 — Capture's new --no-plan flag (fn-214 R5) was parsed with the same substring idiom as the file's other flags ([[ "$RAW_ARGS" == *"--no-plan"* ]]).
• bug/test-failures/test-asserted-a-public-envelope-that-2026-08-01 — A spec criterion said per-briefing status in chart show --json "remains the single source of truth for capture-readiness".
• bug/test-failures/test-runner-timeout-must-kill-a-process-2026-08-04 — A file-level test runner that shards with subprocess.run(cmd, timeout=N) has TWO unbounded hang paths, and both hide behind a passing local suite:
• bug/test-failures/two-independent-resolve-calls-faked-a-2026-08-04 — leaf_is_safe (flowctl_tracker/lifecycle/helpers.py) proved containment by resolving base and leaf INDEPENDENTLY and comparing (base_real not in target_real.parents).
• bug/test-failures/windows-83-path-test-failures-were-2026-08-04 — Two Windows-only test failures were recorded in the fn-120 characterization as "CLI --file args fail from 8.3 short paths".
• bug/runtime-errors/land-chain-fences-a-failed-read-is-2026-09-13 — fn-149.1 added chain/stack landing to the land skill as prose fences.
• bug/runtime-errors/one-shot-keyed-to-an-earlier-captured-2026-08-19 — fn-200.2 added a one-shot-per-head Phase 3 action to the land workflow (request-reviewers): atomic mkdir claim keyed to (PR, HEAD_OID), then remote mutations, then a ledger write.
• bug/runtime-errors/same-owner-alias-re-registration-must-2026-08-02 — validate_and_build_initial_map runs twice per chart create --initial-map-file: a provisional pass under a sentinel chart id (fn-999999999) and a real pass after allocation.
• bug/runtime-errors/skill-fences-that-degrade-only-without-2026-09-13 — The make-pr stack-link fence captured a failing gh api POST as LINK_OUT=$(gh api ...); LINK_RC=$? and then branched on LINK_RC to print the documented one-line degrade.
• bug/security/managed-review-transport-must-bound-2026-09-08 — A valid local review provider failure could echo its scoped credential through ordinary CLI diagnostics.
• bug/integration/backend-special-case-in-a-shared-helper-2026-09-05 — Adding the flowctl claude review subcommands (fn-221.2), the primary commands rejected a foreign --spec through _resolve_claude_review_spec, but validate and deep-pass route through the shared _resolve_session_pass_spec, whose…
• bug/integration/ci-path-classification-must-include-2026-09-05 — Git diff --name-only can report only the destination of a detected rename.
• bug/integration/cross-family-review-claims-key-on-the-2026-09-05 — Documenting the claude review backend (fn-221.4), every overview passage called the review "cross-family" from Codex, Cursor, Grok Build, Droid and OpenCode and "same-family" from Claude Code - keyed on the host name.
• bug/integration/headless-review-backend-error-envelope-2026-09-05 — Adding the claude -p review backend (fn-221.1), the runner shared cursor's lenient result parser and returned an error envelope's result text as reviewer output with only the exit code flipped to 1.
• bug/integration/installer-must-own-what-it-deletes-2026-08-21 — PR Route-aware next-step guidance in capture and plan closers (fn-202) #363's docs-install stage (round-3 fix) recursively deleted $CODEX_HOME/docs/reach and copied loose generic names (README.md) into the shared $CODEX_HOME/docs/ — destroying non-flow-next user data on every install.
• bug/integration/land-evidence-field-defaulted-to-off-on-2026-08-19 — The land workflow initialized the per-PR evidence field REVIEWERS_STATE=off unconditionally and only overwrote it inside the §2.6b predicate branch.
• bug/integration/scheduler-prose-asserted-wrong-config-2026-08-22 — Review (fn-203.6, codex) caught two P1s in the rolling-scheduler beta prose: (1) the plan-sync gate claimed planSync.enabled off "(null/false/missing - the default)", but the SHIPPED default is true (get_default_config() in flowctl.p…
• bug/data/adding-a-key-to-a-content-hash-orphans-2026-08-01 — chart briefing is idempotent on a content fingerprint.
• bug/data/docs-for-a-hash-identity-fix-inherit-2026-08-01 — The docs task for a content-hash fix (fn-154: reopen epoch folded into _briefing_fingerprint) shipped prose that was true in spirit and wrong in scope, twice in a row.

Glossary / strategy notes

Glossary: added Chain, Frontier, Layer, Stack.

---

Generated by /flow-next:make-pr from fn-152-make-pr-opt-in-stack-linking-via-github against fn-149-land-hardening-survive-stacked-pr-auto on 2026-09-13.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[cursor]

PR Summary

Medium Risk
Touches spec admission, autonomous selection, and make-pr git rewrites plus GitHub stack API calls; non-dependent specs stay on the old path, but wrong chain or fence behavior could park or rewrite branches incorrectly.

Overview
Dependent specs no longer wait for a parent merge. When the parent’s tasks are done and its branch is on origin, the child becomes selectable through a single read-only flowctl spec chain predicate wired into ready/next/ready --all, flow --auto (ready and backlog), attended flow, work (branch from origin/<parent>), and make-pr (history-based chain rung, PR base on the parent, optional GitHub stack link).

flowctl adds evaluate_spec_chain / spec_blocked_by_deps (one shared git ls-remote), pilot-log append --reason for chained on <parent>; … verdict rows, and glossary/docs/changelog coverage for chain/stack/layer/frontier.

make-pr gains merged-parent rebase --onto on create-only runs (leased push), §4.6c stack REST linking with one-line degrade on failure, chained layers ready under autonomy when nothing is open, and --update Stack line preservation. Review fixes harden bash fences for set -e (stack link, chain-base fetch, ls-remote) and run consumer fixtures with the same shell options.

Tests: test_spec_chain.py, test_chain_consumer_fixtures.py, extended gh stub; .flow task/spec state and memory notes document the impl and supersede the manual stacked-PR recovery playbook.

^{Reviewed by Cursor Bugbot for commit 2d70e23. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 2d70e23. Configure here.}