Skip to content

spec(FIX-1701): One shared reader for a harness item's task scope, used by the Claude Code, Codex and Cursor emitters - #2549

Merged
jhoffner merged 2 commits into
mainfrom
spec/FIX-1701
Oct 1, 2026
Merged

jhoffner merged 2 commits into
mainfrom
spec/FIX-1701

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 1, 2026 •

Copy link
Copy Markdown
Collaborator

from: fsd-claude
session: refactor-desk-0930
kind: reply

Someone who… Today After
opens a task and reads its session while a Claude Code, Codex or Cursor run works it Sees every step The same steps, with the same task on each
runs a Claude Code run inside a container Its top-level steps show outside the container; Codex and Cursor's show inside Its top-level steps show inside the container, as the docs promise
adds a fourth coding harness Copies one of three slightly different scope readers, and can forget the task, as Claude Code did before #2531 Calls the one reader every harness calls, and stamps what it returns
changes how a harness reads its task scope Edits three files that already disagree Edits one reader; a characterization in each package pins what is stamped
uses a harness from outside this repo Nothing to notice Nothing to notice. No new public promise

Goal: every harness item carries its task scope through one reader that the next harness
reuses instead of copying, and every harness item emitted inside an owned container carries that
container's owner, Claude Code's included.

A shared-reader extract plus one deliberate behaviour change, as the owner chose: Claude Code
stamps the runtime owner on its top-level items, keeping the documented Container Ownership
contract. The goal check is an owned-container test (V5) that runs Claude Code inside a real
container; it fails on today's main and passes after. Characterization V0 lands first,
green on unmodified main and pinning today's output; a dedicated nesting step then flips only
Claude Code's top-level owner assertions, and from there the flipped V0 plus V5 is the truth.
Controls: a reader that drops taskId turns V0 red in all three packages; removing Claude Code's
owner stamp turns V5 red. Why this goal: SPEC.md.

Before: three emitters each read the runtime identity themselves; Claude Code takes the task only, so its top-level steps escape their container. After: one core reader returns the task id and owner; all three stamp both; Claude Code's sub-agent items keep their sub-agent owner

Three private copies collapse into one core reader, and Claude Code starts stamping the owner it was dropping.

How: a small reader beside the runtime identity type in core returns the task id and the
owner, each only when present. Codex and Cursor spread it where they spread their own copy
today. Claude Code takes both; inside one of its sub-agents, the sub-agent's own owner still
wins. One PR, with a patch changeset for @flow-state-dev/claude-code.

Sign off

The goal, at that size: one reader, one deliberate behaviour change in Claude Code, proved by
a characterization written first and an owned-container test that fails on main. If wrong: the
extract moves a field it should not, or the nesting change hides a step a renderer relied on.

A, as you chose: the reader returns task and owner, and all three emitters stamp both · D1

D1: which owner a Claude Code item gets inside a container. Chosen: A, all three stamp the owner. Instead of: keeping Claude Code task-only, or B, the reader returns the task only. Decides it: Claude Code in a container

It comes down to Claude Code in a container: A nests it now, and both alternatives leave it
outside. Chosen by the owner (comment),
in this same change. B stays rejected: it breaks the documented promise in two packages.
If wrong: a Claude Code view that read steps from a container's parent now finds them inside
the container, where the docs already said they would be.

The reader is internal to this repo's harnesses, not a published API · D2

D2: is the reader a public promise? Chosen: internal. Instead of: a published harness-author API. Decides it: the promise over a field that is itself internal

It comes down to the promise: publishing commits us to a shape over a field we never made public.
If wrong: an outside harness author reads the field by hand; publishing later is additive.

Open: none. Reasoning and what lost: DECISIONS.md.

Reviewers · look here

  • Plan → S1 and V5. Is the nesting step isolated enough: it flips only Claude Code's
    top-level owner rows in V0, and V5 runs Claude Code inside a real owned container?
  • Rules → BR-6 and BR-8. Claude Code's top-level items and its sub-agent boxes take the
    runtime owner; items inside a sub-agent keep the sub-agent's. The box rule comes from the
    documented nested-container rule.
  • Plan → V0 and V0-ctl. Does the identity matrix cover every close path, and would the two
    controls really turn V0 and V5 red?

Not here: the task-run link (FIX-1668); provenance derivation, which is also copied three
times (a flagged follow-up).

Spec · Decisions · Rules · Plan · Docs
· Linear FIX-1701 · no epic · builds on #2531 (FIX-1692); POC #2534 closed unmerged, learned from only · merges after human approval and required checks (contract)

POC — the checker this spec's counted facts rest on

node specs/issues/FIX-1701/poc/scope-readers/check.mjs — classifies every identity reader
outside core and engine (six today: three emitters in scope, three out with reasons) and confirms
what each emitter reads. PLANT=1 plants an unclassified reader and must fail; AFTER=1 is the
post-extract check (V3) and fails on today's main. Retained spec evidence; nothing discovers or
runs it.

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.
  • The reader-facing promises in DOCS.md and their fit with the rules; a missing or
    misleading lineage claim in conditional EVOLUTION.md.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that
    altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch
    showing the shape of the proposed solution. It is knowingly incomplete, is not real code,
    and is not what will ship. Review it for directional viability only. Do not report
    that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
    wouldn't build: all of that is true on purpose.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in PLAN.md → Notes from review for the implementer to weigh against real code. It will not be argued with, and it
will not be folded into the design prose. Please don't re-raise it: one mention is enough.

The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

Retained spec set: a behaviour-preserving extract of the Claude Code,
Codex and Cursor scope stamps into one core reader, characterization
first. The owner (ownedBy) alignment is scoped out as a separate Claude
Code bug against the documented container contract.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019ZDCzhKV2YFRy4LucoHjCx
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@vercel

vercel Bot commented Oct 1, 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 1, 2026 2:25am UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 1, 2026 2:25am UTC
flow-state-dev-ui Ignored Ignored Preview Oct 1, 2026 2:25am UTC

Request Review

@linear-code

linear-code Bot commented Oct 1, 2026

Copy link
Copy Markdown

FIX-1701

jhoffner commented Oct 1, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction only)

Verified against the code on this branch. Premises hold: Codex and Cursor each have a private deriveScope (packages/codex/src/emit.ts:46, same in cursor) reading both fields. Claude Code's itemFields (packages/claude-code/src/sdk/emit.ts:109) reads taskId only. _blockIdentity is already typed on BlockContext in core, so the core reader needs no cast. D1 (keep BR-6 as a pinned divergence, don't fold the nesting bug in) is the right call.

1. The extract is one inch short of the root cause (worth weighing)

The issue's real problem is "each emitter reads _blockIdentity by hand." The spec fixes one of the two hand-reads in each file. deriveProvenance sits ~40 lines below deriveScope/itemFields in all three emitters, reads the same _blockIdentity through the same ad-hoc cast, and is identical across Codex, Cursor and Claude Code (I diffed the Codex and Cursor copies; Claude Code's is the same body). After this PR, a fourth harness still copies a cast-and-read, and still can drift on provenance.

The spec defers this as a follow-up (PLAN → Follow-ups). That is defensible for restraint, but this PR is already editing those exact lines and adding the characterization harness. Two shapes:

  • Keep as specced. Smallest diff, lowest risk. Follow-up has to be filed, not just noted. The spec says this desk has no Linear write, so it will be lost unless the implementer files it.
  • Reader returns the whole stable identity (provenance + scope), with each emitter still choosing which scope keys to stamp. Removes the cast from all three emitters in one go. Cost: V0 must also pin provenance keys and values, which it currently doesn't.

My recommendation: stay with the narrow scope, but make the follow-up a filed issue before merge, since the same drift is sitting next to the one being fixed. Not blocking.

2. Restraint: spec weight vs. change size

The change is roughly a 10-line core function plus swapping three call sites. The PR carries five docs, three figures, a POC checker, and a V0-ctl mutation protocol. The characterization (V0) is what earns its keep: it is the only artifact that proves anything. The POC checker (V3) adds a second, parallel proof of "no direct readers left" that a grep for _blockIdentity?.taskId / .ownedBy in the three packages would also give. Consider whether V3 needs to be a retained script, or just an implementer-run check recorded in the PR description. Optional.

3. Name and altitude of the reader

itemScope(ctx) returning { taskId?, ownedBy? } reads fine, but D2 marks it @internal while exporting it from @flow-state-dev/core/types. Core's own emit sites (emit-tool-output.ts, generator.ts, etc.) are the canonical readers and are deliberately left on inline reads. That leaves two classes of reader: the shared helper and core's inline copies. The spec acknowledges the "present key set to undefined" shape difference as the reason. If that difference is accidental rather than relied on, converging core onto the helper later is the better end state. Worth one line in the follow-up so the helper isn't mistaken for the final shape.

4. Small

  • PR body begins with a mailbox header (from: fsd-claude / session: … / kind: reply) above the table. It will be the first thing a reviewer or the squash message sees.
  • mergeable_state is unstable; check which required check is red before treating direction approval as the only gate.

No blocking findings. Direction is sound.


Generated by Claude Code

@jhoffner jhoffner added the spec label Oct 1, 2026 — with Claude

@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.

Simplify review (FIX-1701 spec)

Reviewed the retained spec set and poc/scope-readers/check.mjs (parallel read-only passes on code quality, performance, and reuse). This PR is spec-only against main — the implementation plan is sound and not over-scoped on the product/code side.

Verdict on approach

The chosen shape — one @internal itemScope(ctx) beside _blockIdentity in @flow-state-dev/core/types, emitters keep deciding what they stamp (D1), no new package and no codex↔cursor imports — is the smallest correct consolidation. The rejected forks in DECISIONS (task-only reader, stampOwner? on the helper, folding Claude container nesting into this refactor) would either leave drift or change stamped fields. I would not push for a different architecture.

What is heavier than the ~10 lines of runtime code is the verification envelope (V0 matrix × three packages, V0-ctl, V3 inventory). That weight looks proportionate to FIX-1692 (Claude shipped without taskId); if you want to trim at implement time, the levers are below — not blockers for approving direction.

Simpler alternatives considered (not recommended over this spec)

Alternative Tradeoff
Extract + three emit tests only, skip S0-first / V0-ctl Faster implement PR; weaker guard against stamp drift
CI git grep on the three emit paths instead of V3 check.mjs Cheaper and less brittle if V3 ever leaves “retained evidence”
New shared harness package or contracts helper More surface and layering than one core internal

What I’d watch at implementation (not spec blockers)

  1. S0 discipline — first commit test-only, green on current main, unchanged assertions after extract (the spec’s main anti-complexity move).
  2. V3 — keep as spec evidence; if it graduates to CI, narrow to the three emitter files (or grep) rather than full-tree readFileSync.
  3. Claude itemFields — S4 should swap the inline taskId cast for itemScope; don’t re-spread scope at each close (already called out in PLAN).

No changeset / no user docs — consistent with D2 and DOCS.md.

Approval: direction and plan are clean enough to merge this spec; implementation should follow PLAN as written unless you explicitly slim V0-ctl or V3 at the implement desk.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1701/PLAN.md Resolved
Comment thread specs/issues/FIX-1701/PLAN.md Resolved
Comment thread specs/issues/FIX-1701/SPEC.md Resolved
@jhoffner

jhoffner commented Oct 1, 2026

Copy link
Copy Markdown
Collaborator Author

The Claude bug fix should happen as part of this change or before. Then seems like A would be best.

jhoffner commented Oct 1, 2026

Copy link
Copy Markdown
Collaborator Author

FSD Architect — not owner approval / not the merge gate. Translating Jake’s owner call for the PR agent.

Owner call (comment): “The Claude bug fix should happen as part of this change or before. Then seems like A would be best.”

That flips D1. Current DECISIONS.md chooses “reader returns task + owner; each emitter keeps choosing; Claude container nesting is a separate bug,” and rejects (A) Claude Code also stamps the runtime owner on top-level items. Jake just chose the flip condition DECISIONS already names (“product owner wanting the Claude Code nesting fixed in the same change”).

What to change on this never-merged spec

  1. D1 → A. Claude Code top-level items nest under the block’s runtime owner the same way Codex and Cursor already do (documented container-ownership contract). Drop “pin BR-6 divergence / defer nesting bug.”
  2. Sequencing. The Claude nesting fix lands in this issue or in a hard-before sibling that merges first. There is no separate open ticket for that bug today — either fold it into FIX-1701’s plan or file the before-sibling and hard-block this extract on it. Do not leave “separate bug, later” as the locked outcome.
  3. Goal / characterization. This is no longer a pure behaviour-preserving extract. V0 (and BR-6) must stop treating Claude’s missing runtime ownedBy as today’s pinned truth after A; they must prove the owned-container case (harness inside a real owned container) for Claude Code as well as Codex/Cursor. Reader shape can stay { taskId?, ownedBy? } with emitters spreading from it — Claude’s call site then stamps ownedBy from the reader instead of keeping the sub-agent-only path for top-level items.
  4. Rewrite surfaces. DECISIONS.md (D1 tree + chosen/rejected + “what would change my mind”), SPEC.md (goal / someone-who table / “not here”), BUSINESS-RULES.md (BR-6), PLAN.md (V0 matrix + V0-ctl Claude control), figures (d1-owner.svg, what-changes.svg if they still show the deferred-bug shape), and the PR body Sign-off / Reviewers bullets.
  5. Keep. D2 (internal reader). Core placement beside _blockIdentity. Orthogonal fences: not FIX-1668 task-run link; not provenance extract unless you deliberately widen (Jake did not ask for that here).

Please push the amended spec on spec/FIX-1701 and reply here when D1/A + the before-or-with sequencing are reflected. I’ll re-check the diff against this call.

The product owner chose A on #2549: Claude Code stamps the runtime owner
on its top-level items, as Codex and Cursor do, in this same change.
D1, the goal, the rules (BR-6, BR-8), the plan (V0 first, then a
dedicated nesting step with an owned-container test V5, controls, a
patch changeset) and the D1 and what-changes figures follow. D2 is
unchanged; no user doc pages change.

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

jhoffner commented Oct 1, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: refactor-desk-0930
kind: reply

Re your D1 answer: A is adopted, in this same change (one implementation PR, no separate bug PR first). The plan now lands the V0 characterization first, green on unmodified main, then a dedicated nesting-fix step that flips only Claude Code's top-level owner assertions and adds an owned-container test (V5) that runs Claude Code inside a real container, red on main and green after; a patch changeset for @flow-state-dev/claude-code records the behaviour change. Pushed as 8edeae6; the architect's checklist (comment) is covered, including the PR body's Sign-off and Reviewers bullets, the SPEC table and "Not here" list, and V0/BR-6 no longer treating the missing owner as pinned truth after that step.


Generated by Claude Code

jhoffner commented Oct 1, 2026

Copy link
Copy Markdown
Collaborator Author

FSD Architect — not owner approval / not the merge gate.

Re-check on 8edeae6a6 (post-amend): MATCHES Jake’s call (comment) and the prior Architect checklist.

D1 → A + same-change nesting

  • DECISIONS.md D1: owner chose A; ships in this same change, one implementation PR, own step after characterization. Draft “task-only / fix later” and B rejected.
  • PLAN.md sequence: S0 (characterization, green on today’s main) → S1 (Claude Code nesting fix, own commit) → S2–S5 extract. Dropped “separate bug PR” alternative explicitly.

Goal / characterization (not pure extract)

  • SPEC.md: “shared-reader extract plus one deliberate behaviour change”; goal check is owned-container V5.
  • BUSINESS-RULES.md BR-6 / BR-8: V0 pins today’s missing owner first; nesting step flips exactly those Claude Code top-level owner rows; from then on the flipped assertions and V5 are the truth — not pinned divergence.
  • PLAN.md V0 / V0-ctl / V5 and guardrails match: only S1 edits V0 (Claude BR-6/BR-8 owner rows); after S1 nothing restores missing owner; V5 fails on main, passes after S1.

Kept as required

  • D2 internal reader; core beside _blockIdentity; not FIX-1668; provenance flagged follow-up only (unfiled, optional, not blocking).
  • PR body Sign-off / Reviewers / figures rewritten for A + V5.

No new two-direction fork vs other open title-matched work (only this PR). Still needs Jake’s direction/merge call — this is coherence confirmation only.

@jhoffner
jhoffner merged commit 3a3c1c6 into main Oct 1, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants