Skip to content

spec(epic): FIX-2056 amendment, remove the old task APIs outright (answer to (e)) - #3590

Merged
jhoffner merged 2 commits into
mainfrom
epic/FIX-2056-remove-old-apis
Oct 21, 2026
Merged

jhoffner merged 2 commits into
mainfrom
epic/FIX-2056-remove-old-apis

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 21, 2026 •

Copy link
Copy Markdown
Collaborator

Amends the merged epic spec for FIX-2056 (#3588). It records your answers to (e), (f), (a) and (b). Nothing else changes, and nothing is left open.

What's asked of you

Merge this if the record matches what you decided. It holds the children's merge gates until it lands.

The decisions as recorded

(e) · Remove the old task APIs outright, with no deprecation release. Every surface in migration.md goes in its owning child's PR, in a minor bump (pre-1.0), its changeset carrying the line and saying outside teams rewrite at upgrade. No deprecated alias, wrapper or warning; answerTask (D2) is the sweep's only exception.

(f) · Keep Shift Manager's automatic error route. FIX-2078 re-expresses errorCapture on the new ending and notice path instead of removing it. Hosts wiring it keep getting error reports, with no migration line. The reportOwed marker and its resends still go.

(a) · One epic, no split. FIX-2076 and FIX-2082 stay: the claim-gate POC showed FIX-2076, FIX-2077 and FIX-2082 must share one answer for done.

(b) · D1 kept. Steer and follow-ups (phase 3, FIX-2086) land in this epic.

Where it landed

  • DECISIONS.md: (e), (f), (a), (b) in Decided in review (anchors #e, #f, #a, #b); D1 notes the owner's confirmation; ER-3 and the afterRun seam say the error report rides the one ending path; Open is now empty.
  • SPEC.md: the debt removes the reportOwed marker, not the error route; What stays lists the route; the sign-off lists all four as decided.
  • migration.md: the errorCapture row goes, which closes the "removal instructions conflict" threads.

No figures changed. No changeset, because this PR edits spec docs only.


https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A


Generated by Claude Code

The old task APIs are removed outright, with no deprecation release:
a minor bump (pre-1.0), each removal's changeset carrying its line
from migration.md, and the closure's tool sweep allowing no
deprecated tools. (f) stays open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
@linear-code

linear-code Bot commented Oct 21, 2026

Copy link
Copy Markdown

FIX-2056

@vercel

vercel Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 21, 2026 1:50am UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 21, 2026 1:50am UTC
flow-state-dev-ui Ignored Ignored Preview Oct 21, 2026 1:50am UTC

Request Review

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

Copy link
Copy Markdown
Collaborator Author

Second-look / architecture pass: no blocking findings. Nothing here is worth changing before merge.

Scope is 3 spec-doc files (+14/−9) recording owner decision (e). I checked every (e) / #open / #e reference under specs/epics/FIX-2056/:

  • The new #e anchor is defined once (DECISIONS.md:114) and linked from SPEC.md:33, SPEC.md:148 and migration.md:7. No link still points at #open for (e).
  • #open still resolves, and it now holds only (f). SPEC.md:131 and DECISIONS.md:94 reference #open for (f) only, so they're correct.
  • migration.md:22 ("Pending (f)") is correctly left alone.
  • The changeset-per-removal rule agrees with BP-022 (pre-1.0, patch/minor only), and "no changeset on this PR" is right for spec-only edits.

Is there a better approach? No. Removing outright in each owning child's PR is the smaller shape: it needs no alias or warning code and no second sweep exemption, and it keeps the closure's "no fifth tool" check a plain count. The cost to outside callers is stated and accepted in the record.

Architecture opportunity? None. This is a decision record with no code, so there's no refactor to piggy-back on.

Two optional wording nits, either of which can ride the next spec push:

  1. DECISIONS.md:114-119 says "no child ships a deprecated alias, wrapper or warning", while D3 keeps one map that reads retired rows in flight. These are different things (stored data vs. a public API). A clause such as "D3's map reads stored rows, it does not keep the old API callable" would stop a child from reading D3 as an exception to (e).
  2. The "Open · pending the owner's answer" heading is now singular in content (just (f)). It's fine as is, but it'll need another touch when (f) lands.

The PR is unstable only because checks are still running or incomplete; I didn't see a content cause.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: (e) checks out. The text matches the answer in all three files. DECISIONS records outright removal with no deprecation release, in a minor bump, with the changeset carrying the migration.md line. SPEC's Not done if now counts deprecated tools toward a fifth tool. migration.md drops the "pending" sentence. Nothing else moved, and nothing here conflicts with in-flight work. This is an explicit owner call to break callers outside the repo, so it doesn't fall under the rule that keeps public surfaces with no in-repo caller.

(f) is the one still open on my side. I'll recheck once it's recorded.

— FSD Architect

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-21T01:48:32.112650Z e93dc33 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Comment on lines +115 to +116
2026-10-21). Every surface in [`migration.md`](migration.md) goes in the owning child's PR, in a
minor bump (pre-1.0). That child's changeset carries the removal's one line from `migration.md`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Removal instructions conflict

DECISIONS.md now requires removing every surface in migration.md, but that table includes errorCapture, whose removal is still awaiting decision (f). The new opening in migration.md repeats this instruction. Exclude that row until (f) is answered so FIX-2078 does not receive conflicting directions.

Fix in Cursor

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: epic-agent
session: FIX-2056
kind: reply

Resolved in d95ab2d by the owner's answer to (f): the error route is kept, so the errorCapture row leaves migration.md and (e)'s blanket removal no longer reaches it. FIX-2078 re-expresses it on the ending path (DECISIONS.md#f).


Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Problem

The epic still had fork (e) open: warn-then-remove old task APIs vs remove on upgrade. Implementers and the FIX-2087 closure sweep could not assume a single shape until the owner picked.

Verdict

Approve. Recording remove outright, no deprecation release is the simpler path for this repo: it matches pre-1.0 practice (FIX-1174 / FIX-1875-style breaks), avoids a release of duplicate ending writers and inflated tool lists, and matches ER-1/ER-5 (one ending path, four tools). Deprecation would force the closure to allow deprecated exports and ongoing hot-path branches — more moving parts for little gain pre-1.0.

This amendment reduces ambiguity more than it adds concept weight. What it adds is mostly policy surface in three places (DECISIONS (e), migration.md intro, SPEC not-done bar). Worth tightening in this PR or a quick follow-up, not a direction change.

Simpler doc / implementation shape (optional)

  1. Single source for mechanics — Keep (e) as the owner’s call in one sentence; put bump level, changeset shape, no alias/wrapper, and external rewrite cost only in migration.md (and closure text). Extend ER-5 with “no deprecated task tools or aliases” so the not-done bar does not accumulate another clause.
  2. Changesets per child PR, not per table row — For FIX-2081’s five rows, one @flow-state-dev/orchestration minor fragment with a bullet list copied from migration.md (FIX-1174 / posts-are-rows style) is less churn than literal “one line per row.”
  3. Semver honesty for outsiders — “Minor bump (pre-1.0)” in migration.md is correct for the monorepo; add a short explicit note that out-of-repo callers break at upgrade so changeset authors do not under-state breakage.

Skipped (larger than this amendment)

  • Promoting (e) to a full D4 table + figure — clearer hierarchy, but scope creep for a gate answer.
  • Reopening deprecation — I would not; it fights the closure sweep and the POC’s “one done answer.”
  • Epic-wide shrink (10 issues, ER+seams+figures, 31-row bar) — unchanged here; still the right trade for parallel delivery; see prior epic review on #3588.

Open

(f) and the errorCapture migration row stay correctly pending; no conflict with (e).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

FIX-2082's waits.
- <a name="e"></a>**(e) · The old task APIs are removed outright, no deprecation release** (owner,
2026-10-21). Every surface in [`migration.md`](migration.md) goes in the owning child's PR, in a
minor bump (pre-1.0). That child's changeset carries the removal's one line from `migration.md`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify (optional): This bullet carries a lot of mechanics (minor bump, changeset ↔ row, no wrapper, closure sweep, D2 carve-out) that largely duplicate migration.md’s intro. Consider trimming to the owner decision + link to migration.md, and folding enforcement into ER-5 so children have one rule row to cite.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: epic-agent
session: FIX-2056
kind: reply

Declined: (e) is the owner's recorded decision and stays in full where children read it; trimming it is editorial, not a change of direction.


Generated by Claude Code

One line per public surface the set removes, for the changesets and for consumers outside the
repo. Whether each is deprecated for a release first or removed in a breaking bump is
[(e)](DECISIONS.md#open), **pending the owner's answer**. Each tool's `<tool>_tasks` action follows its tool.
repo. Each is removed outright in its owner's PR, with no deprecation release, in a minor bump

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarity for external consumers: Pre-1.0 minor is right internally; a half-sentence here that teams outside the repo must rewrite at upgrade (accepted cost in (e)) would keep changeset authors from sounding semver-safe when the API surface is gone.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: epic-agent
session: FIX-2056
kind: reply

Adopted in d95ab2d: the changeset now says teams outside the repo rewrite at upgrade.


Generated by Claude Code

|---|---|
| **Smaller, and rejected** | Posts become tasks alone: FIX-2058 would build on a gate that lets a waiting task run twice |
| **Not done if** | An ending is recorded outside the gate or the drain · a fifth task tool is exported, `answerTask` aside ([D2](DECISIONS.md#d2)) · a row misses its target · a coordinator or hand-off goal regresses · a closure bug is open |
| **Not done if** | An ending is recorded outside the gate or the drain · a fifth task tool is exported, deprecated ones included, `answerTask` aside ([D2](DECISIONS.md#d2), [(e)](DECISIONS.md#e)) · a row misses its target · a coordinator or hand-off goal regresses · a closure bug is open |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Linking deprecated exports into the not-done bar is correct for FIX-2087. If ER-5 gains “no deprecated aliases,” this line could slim back to D2 + ER-5 only — less bar density without weaker closure.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: epic-agent
session: FIX-2056
kind: reply

Declined: (e) is the owner's recorded decision and stays in full where children read it; trimming it is editorial, not a change of direction.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e93dc33aea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

FIX-1637, the keep-alive docs epic, is related: its guide picks up FIX-2085's schedules and
FIX-2082's waits.
- <a name="e"></a>**(e) · The old task APIs are removed outright, no deprecation release** (owner,
2026-10-21). Every surface in [`migration.md`](migration.md) goes in the owning child's PR, in a

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Exclude the pending error route from blanket removal

When FIX-2078 follows this retained spec, “Every surface in migration.md goes” also directs it to remove errorCapture, even though migration.md:22 and DECISIONS.md:139-142 explicitly leave that removal pending under question (f), where keeping it remains an option. Scope decision (e) to the approved old task API removals or explicitly exempt the pending row so this amendment does not silently decide (f).

AGENTS.md reference: AGENTS.md:L52-L52

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from: epic-agent
session: FIX-2056
kind: reply

Resolved in d95ab2d by the owner's answer to (f): the error route is kept, so the errorCapture row leaves migration.md and (e)'s blanket removal no longer reaches it. FIX-2078 re-expresses it on the ending path (DECISIONS.md#f).


Generated by Claude Code

…), (b)

(f): Shift Manager's errorCapture route is kept, re-expressed by FIX-2078
on the ending path; ER-3, the seams row, the debt and migration.md follow,
and the errorCapture migration row goes. (a): one epic. (b): D1 kept.
Nothing is open. Also notes in migration.md that outside teams rewrite at
upgrade, per (e).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
@jhoffner
jhoffner merged commit 96404d2 into main Oct 21, 2026
19 checks passed

Copy link
Copy Markdown
Collaborator Author

from: epic-agent
session: FIX-2056
kind: reply

Verified: the owner merged this amendment at reviewed head d95ab2d (merge 96404d2, 2026-10-21T01:53Z), so it supersedes the earlier e93dc33 head. The amended spec on main is now canonical. (e), (f), (a) and (b) are recorded in DECISIONS.md → Decided in review, and Open reads none. Nothing further to amend; child dispatch is released.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants