Repository navigation
Conversation
…ojects Scopes the wrapper to the two things neither create-next-app nor `fsdev init` can produce: a demo flow and the chat page that talks to it. Everything else — detection, config, host wiring, credentials, install, next-steps — stays init's. Settles the init handoff as a library call rather than a subprocess (a subprocess cannot be handed the answers already collected, so it asks for the API key twice), declines to maintain a Next.js skeleton, and unblocks the issue from FIX-1162 by publishing under the scope we already own. Raises one ask: whether the Node API template ships at all, now that FIX-1159 generates no server file and adds no package script. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
| breaks loudly and in public, which is the redeeming feature; we pin a tested major range | ||
| and treat it as a patch-level fix. |
There was a problem hiding this comment.
Scaffolder version pin is undefined
When a newer create-next-app release changes its flags, prompts, or generated layout, the unspecified invocation resolves that untested version, causing project creation to hang, reject the arguments, or write the demo page outside the served layout. Define how the promised tested major range is enforced; the stubbed CI tests cannot detect upstream version drift.
| **cwd-only**. There is no directory scan that would pick a flow up on its own, which is why | ||
| init must be *told* the demo flow's name rather than discovering it. |
There was a problem hiding this comment.
Flow discovery premise is inaccurate
The statement that no directory scan can discover a flow overlooks discoverFlows, which scans conventional flow directories when no config is available. Distinguish that discovery path from the generated-config path, where explicit registration is still required, so implementers do not inherit an inaccurate model of CLI resolution.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
There was a problem hiding this comment.
Simplify review — direction sound, a few seams worth trimming
This is a spec-only PR, so the question is whether the approach is the smallest thing that solves the problem. On that bar: yes, mostly. The spec is unusually honest about its own weakness (two commands almost work; epic theme 1 tripwire; three authored files). Delegating the bare app to create-next-app (install skipped) and everything else to fsdev init is the right decomposition. Decision 5 (no hello-chat UI port) and the ordering invariant (demo content before init) are load-bearing and well argued.
What pushes complexity past "thin wrapper" is mostly cross-package contract and v1 futures, not the product surface:
Where the approach may have gone further than necessary
-
In-process init library call (§6.1 / §7) — The double-prompt problem is real, but the chosen fix expands FIX-1159's public surface (four-row seam + returned next-steps string) before that issue has landed. A lighter alternative worth weighing on #1310: non-interactive
fsdev initvia subprocess with flags/env for provider, key, cwd, supplied-flow path, and-y. Same UX (one prompt collection), smaller API, matches howfsdev uialready delegates vianpx. If library-first is already committed on #1310, fine — but the subprocess path is dismissed without exploring init CLI passthrough. -
--templatein v1 with a single legal value (§6.4, §9) — YAGNI for a one-template release. Hardcode Next.js chat; add the flag whennode-api(or a second host) actually ships. Saves validation, refusal table row, and CI behaviour for a one-value enum. -
Byte-identical next-steps assertion (§10) — Brittle cross-package coupling on presentation bytes. Prefer: same ordered commands/URLs (normalized), or snapshot owned by init with create-fsd-app only asserting init was called once and printed its marker block.
-
Generated layout diverges from published docs (§7) — Spec places the flow at
flows/chat/flow.tsand examples usefsdev run chat send, while quick-start / project-structure usesrc/flows/hello-chat/flow.tsandfsdev run hello-chat chat. A greenfield user will hit the docs immediately after scaffold — this drift is the highest-impact implementer fix. Recommend aligning withsrc/flows/hello-chat/+hello-chat/chatnaming, and citing quick-start §5 as the page source (not hello-chat's page). -
Spec bulk — Decision 4 is argued twice (§6 item 4 + "The ask"). §12 "Verified premises" (~25 lines) re-closes PR #1301 notes the implementer inherits from merged init. Two sub-PRs for "3 files · ~9 tests" may cost more process than it saves unless publish isolation is mandatory.
What I'd keep as-is
- Single install via CNA
--skip-install→ init install once. - Refuse-before-create / no rollback after partial failure.
- Goal check without pre-exported API key.
- One Next.js template recommendation (decision 4) — the FIX-1159 hollowing argument is persuasive.
- Stubbed CI for ordering/seam + real goal check for product proof.
Performance
Not a concern for a one-shot scaffold. Dominant cost is CNA + install; spec already guards against double install.
Verdict
Direction: approve-worthy after a light trim pass — not blocking on prose, but I'd resolve (4) path/naming alignment and either justify (1) library-over-subprocess on #1310 or document why CLI passthrough was rejected. Items (2)–(3) and spec bulk are implementer-friendly cuts that would make the eventual code change smaller.
Happy to converge in round 2 once path alignment and the init seam shape are settled.
Sent by Cursor Automation: Review For Best Approach
|
|
||
| ### 6. Decisions & rules — the sign-off surface | ||
|
|
||
| 1. **`create-fsd-app` calls `fsdev init` as a library, in the same process — not by shelling |
There was a problem hiding this comment.
Simplification fork: subprocess init is rejected because credentials can't be handed across. That's true for a default npx @flow-state-dev/cli init, but not necessarily for init with --provider, --api-key, --cwd, --flow-module, -y (or env equivalents).
Library-in-process is defensible, but it forces four rows of public API on FIX-1159 (#1310) before that seam exists. Worth an explicit "we considered CLI passthrough" sentence with why it loses — otherwise implementers may build the heavier seam when a flagged subprocess would suffice.
| *This one reverses an epic theme and is the ask on this PR — see the framing below.* | ||
| *Rejected:* two templates, as epic theme 2 decided. | ||
| *Locks in:* one starter to keep green on machines we do not control, and one goal-check run | ||
| per release instead of two. The `--template` flag still ships with one value, so adding |
There was a problem hiding this comment.
YAGNI: v1 has one template but still ships --template, a refusal row (§9), and CI coverage for unknown templates. Consider hardcoding Next.js chat in v1 and adding the flag when a second template exists — same product, less surface.
| cd my-app | ||
| npm run dev your app → http://localhost:3000 | ||
| npm exec fsdev dev the FSD DevTool → http://localhost:4200 | ||
| npm exec fsdev run chat send --input '{"userId":"u1","message":"hi"}' |
There was a problem hiding this comment.
Naming drift vs repo/docs: quick-start and project-structure use hello-chat kind + chat action (fsdev run hello-chat chat …). This example uses chat/send. Recommend aligning the generated project with existing docs so the post-scaffold docs path is frictionless.
|
|
||
| | file | what it is | | ||
| |---|---| | ||
| | `flows/chat/flow.ts` | the demo flow — one action, one streaming generator. `examples/hello-chat`'s flow is the reference for shape, not for size | |
There was a problem hiding this comment.
Path drift: published docs use src/flows/hello-chat/flow.ts (quick-start, project-structure, your-first-flow). Spec puts flows/chat/flow.ts at project root. CNA's default src/ layout + docs alignment suggest src/flows/<name>/flow.ts unless FIX-1159 init hard-codes a different path — in which case all three should agree.
| | provider and key | already collected in step 1; a second prompt is decision 1's whole subject | | ||
| | the demo flow's name and module path | init's generated config imports and registers it, **and authors no flow of its own** (epic theme 1). Without this input, init writes `flows/hello/flow.ts` beside the advertised one and the wrapper's only exits are overwriting or deleting a file init just wrote | | ||
| | the package manager | one manager, one lockfile | | ||
| | **returned:** the next-steps block | printed once, by init, byte-identical to a standalone init run (epic theme 5) | |
There was a problem hiding this comment.
Brittle contract: "byte-identical" next-steps (also §10) couples create-fsd-app CI to init wording. Any init copy tweak breaks wrapper tests though behaviour is fine. Consider asserting same commands/URLs in order (normalized whitespace) or owning the snapshot in init's test suite only.
|
|
||
| --- | ||
|
|
||
| #### The ask — does the Node API template ship? |
There was a problem hiding this comment.
Decision 4 is argued here (~40 lines) and again in §6 item 4. Fine for the epic-owner gate in Part I, but Part II could reference the approved outcome once — reduces spec bulk without losing the ask.
| *Depends on:* 1, 2, 3, **and FIX-1159's library seam existing.** | ||
| 5. **Publish configuration and the README that renders on npm.** *Depends on:* 1. | ||
|
|
||
| **PR plan.** Two sub-PRs. |
There was a problem hiding this comment.
Two sub-PRs for a package described as "3 authored files · ~9 tests · 2 PRs" — is the split buying anything beyond publish isolation? If not, one PR (code + README + docs + changeset) may be simpler to review and ship.
| step 2 does for one template and whether §10 records one goal run or two; it changes nothing | ||
| else. | ||
|
|
||
| **Verified premises** (read from the code and from FIX-1159's spec, so a reviewer need not |
There was a problem hiding this comment.
§12 verified premises are reviewer-defense (PR #1301 note closure, hello-chat shape disclaimer). Useful in spec review; consider moving resolved-upstream notes to §13 or trimming to 3–5 bullets the implementer must re-check at merge time (e.g. init has no library export yet, cwd-only config search).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0a031eb7f2
ℹ️ 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".
|
|
||
| | file | what it is | | ||
| |---|---| | ||
| | `flows/chat/flow.ts` | the demo flow — one action, one streaming generator. `examples/hello-chat`'s flow is the reference for shape, not for size | |
There was a problem hiding this comment.
Align the demo model with the selected provider
When a user selects Anthropic or Google, this reference can produce a scaffold that installs and configures that provider but whose first message still fails: examples/hello-chat/src/flows/hello-chat/flow.ts:19 hard-codes openai/gpt-5-mini, while the spec never requires replacing it with intent/chat or a model derived from the selected provider, and the single goal run would not expose the other-provider path. Make provider-neutral model resolution an explicit template contract and verify every offered provider, or restrict the prompt to OpenAI.
Useful? React with 👍 / 👎.
| | a | the package: invocation surface, bare-app step, demo content, init handoff (steps 1–4) | — | | ||
| | b | publish configuration, package README, and the three doc surfaces in §11 (step 5) | a | |
There was a problem hiding this comment.
Keep package implementation and documentation in one PR
When sub-PR a lands, the new public package and command exist without their package README, onboarding docs, or publish configuration because all of those are deferred to sub-PR b. That creates an intentionally stale public surface between merges and violates the repository requirement to update API documentation in the same change set; combine these deliverables or include the required documentation in the package PR.
AGENTS.md reference: AGENTS.md:L197-L205
Useful? React with 👍 / 👎.
| 5. **The demo chat page adds no user-interface dependencies. One file, `@flow-state-dev/react`, | ||
| and nothing else.** |
There was a problem hiding this comment.
Move engineering choices out of owner sign-off
When the product owner reviews §6, they are asked to ratify five decisions, including implementation mechanisms such as in-process invocation, scaffolder flags, and UI dependency selection; those are implementer calls rather than business forks, and only the template/package outcomes need owner sign-off. Move decisions 1, 2, and 5 into the technical design so the sign-off surface stays focused on decisions the owner actually owns.
AGENTS.md reference: AGENTS.md:L54-L58
Useful? React with 👍 / 👎.
|
From FIX-1162 (spec PR #1313) — your decision 3 rests on two things that are not true. Raising while this spec is still in review, since both are cheap to fix now and a re-spec later. The unscoped FIX-1162's decision 2 proposes "the scoped name we already own" is unverified. Nothing under Neither point touches this spec's approach. Decision 3's shape — ship scoped, alias short later — is the one FIX-1162 builds on rather than reverses. Generated by Claude Code |
…end to end Three owner/coordinator decisions landed after this spec was written. Not a review round; re-drafted rather than annotated, and the spec returns to the gate. 1. The greenfield/brownfield split. Brownfield is an agent skill, so the wrapper-over-init architecture this spec was built on is gone and the epic's re-drafted theme 1 gives this issue its template end to end. §6 decision 3 moves the config and the Next mount here as checked-in files; §7's seam to init shrinks to credentials, the AGENTS.md section, the install, and the printed block. 2. One template. The Node API template is cut from v1; the ask is re-argued on the asymmetry (adding later is additive, removing later is not) rather than on file count. Decision 2b drops the `--template` flag with it — a flag with one legal value documents an intention and does nothing. 3. The package is `create-flow-state`, published unscoped, which removes FIX-1162 as a gate by any route rather than by a workaround. A POC settled the shape the re-draft turns on. Owning the template means owning the config file, which has two consumers at once — Turbopack and the CLI's native import() — and nobody had checked the first. Against a real create-next-app@16 project: Turbopack will not resolve an extensionless import to .mts, TypeScript rejects the explicit .mts specifier without allowImportingTsExtensions, and fsdev.config.ts with "type": "module" builds, serves, and loads warning-free. It also found that create-next-app writes its own AGENTS.md (own delimiters, re-added by next dev) and a CLAUDE.md, that its .gitignore already carries .env*, and that unpassed flags resolve from saved preferences. So the greenfield path appends to an agent-instructions file — a case the epic had filed under brownfield. Three earlier findings carried forward rather than lost: the credential hazard became decision 7 plus an executed `git check-ignore` assertion, provider/model alignment became decision 5's intent map with the goal check run per provider on a single key, and every printed command is asserted by running it. Both Greptile findings from the previous round folded inline (factual, no round spent): the create-next-app pin is now concrete, and the flow-discovery premise now states that directory discovery exists and is the no-config fallback. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
create-fsd-app — npx-able scaffolding for new FSD projectscreate-flow-state — one command to a working FSD app
|
Re-drafted against three decisions that landed after this spec was written ( What changed and why
A POC settled the premise the re-draft turns on ( It also found four things nothing in this epic knew: Earlier review findings carried forward, not lost. The credential hazard became decision 7 plus an executed Both Greptile findings from the previous round are folded (factual corrections, no round spent):
The one ask is unchanged in substance and re-argued: does the Node API template ship? It reverses epic theme 2, so it is the epic owner's call. Recommendation: ship one. Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3118cce038
ℹ️ 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".
| **The version is pinned in the spawned specifier, not left to `npx` to resolve.** The command is | ||
| `create-next-app@<tested major>`, held in one constant in this package and bumped as a deliberate | ||
| change with a goal-check run behind it — never a bare `create-next-app`, which resolves whatever |
There was a problem hiding this comment.
Pin create-next-app to the exact tested version
Using create-next-app@<tested major> still resolves the newest release within that major on every invocation. If Next changes a flag or generated layout in a minor or patch release, users immediately receive the untested version, contradicting the stated guarantee that upstream changes cannot reach them until this package is deliberately bumped. Store an exact tested version rather than only the major.
Useful? React with 👍 / 👎.
| case "$BODY" in | ||
| "$MARKER":200) echo " PASS — the route served this run's config module" ;; | ||
| *) echo " FAIL — expected $MARKER:200" ;; | ||
| esac |
There was a problem hiding this comment.
Return failure when the endpoint proof fails
When next dev fails to start or /api/flows returns the wrong response, this branch only prints FAIL; the unconditional exit 0 later still reports a successful POC run. That allows automation or a reviewer relying on the exit status to accept the central served-route claim when it was not proven, so the mismatch and the no-free-port path should terminate unsuccessfully.
Useful? React with 👍 / 👎.
…r provider The per-provider rule in §10 made "one recorded run, or two" wrong: the proof is three runs for one template and six for two. §6's trade-off, §10's opening and §12's open question now all say the same number, which matters because that count is the cost the ask is pricing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
…hen it fails Both from Codex's review of 3118cce, folded into the rework in flight. P1 — the major-range pin did not hold the guarantee the spec makes. Codex is right: `create-next-app@16` re-resolves to the newest 16.x on every invocation, so a Next minor that moves a flag or the generated layout reaches users the day it ships, while §7 claimed upstream changes cannot reach them until we bump. The pin is now an exact release, the argv assertion rejects a range as well as a missing pin, and §9 gains the cost that makes this honest: create-next-app writes an exact `next` version into the manifest it generates, so pinning the scaffolder also pins the Next version new projects start on. Bumping it is scheduled maintenance behind a goal-check run, not a rare event. The probe is pinned exactly for the same reason — it is cited as evidence, so a reader running it later must get the version the findings were measured on. P2 — dropped by the stated contract, taken anyway, because the reasoning is right. The probe printed FAIL and exited 0, which is a check able to report green for a claim it did not prove — the failure BP-003 and tenet 7 name, and the same one the per-run marker and free-port check were added to close. The served-route and AGENTS.md checks are now assertions: exit 0 they held, 1 one failed, 2 could not be checked. Verified in both directions — a full run passes (`probe: PASS`, exit 0), and the verdict logic returns 1 for a stale marker, a non-200, an empty body, a missing FSD section, and a duplicated next block. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
@codex — both folded in P1 (pin an exact version, not a major) — you're right, and it was the spec failing against its own mechanism. §7 claimed upstream changes cannot reach users until we deliberately bump, and
One thing your comment prompted that I'd have otherwise left implicit, and it makes the trade honest rather than free: P2 (probe printed FAIL and exited 0) — dropped by the contract, taken anyway, because your reasoning is right. An exit-0-on-failure in the script that is the evidence for the served-route claim is the same failure class as the two things already fixed in this probe: it uses a fresh marker per run on a port it proves free first, precisely because an earlier version reported green by reaching a stale dev server left over from a previous run. Exiting 0 on a mismatch would have let that back in through the front door. So:
For the record on the contract itself: the "line-level POC feedback is dropped" rule exists so nobody spends attention on code that isn't shipping. A POC whose exit status is load-bearing for a claim in the spec isn't line-level — it's the evidence, and evidence that can't fail is worth what it cost. Fair catch. Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dbda62f06d
ℹ️ 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".
| | `fsdev.config.ts` | default-exports `createFlowState({ flows, models, stores })`. Registers the demo flow explicitly, declares decision 5's intent map with the chosen provider's model as `default`, and declares FIX-1159 decision 5's development file store, qualified as such | | ||
| | `lib/flowstate.ts` | re-exports the config's default as `flowstate`. Reconciles the CLI (which searches the project root for `fsdev.config.*`, cwd-only) with the routes (which import through the `@/` alias). Both in-repo examples do this; the published quick-start does not, and §11 fixes that | | ||
| | `src/flows/chat/flow.ts` | the demo flow — one action, one streaming generator, model `intent/chat`. `examples/hello-chat`'s flow is the reference for shape, not for size. Path matches what the docs teach | | ||
| | `app/api/flows/[...path]/route.ts` | `createNextHandler(flowstate)` from `@flow-state-dev/next` — the platform-agnostic adapter, one line, no Vercel assumption | |
There was a problem hiding this comment.
Preserve dynamic streaming on the catch-all route
When the generated app sends an action, the SSE request goes through this catch-all route, but the specified one-line template omits export const dynamic = "force-dynamic". The canonical packages/next/README.md example includes that export, and examples/hello-chat/app/api/flows/[...path]/route.ts documents it as required to prevent Next.js from buffering streamed tokens. The POC also sets it on the only route it exercises, so its successful result does not validate the route shape specified here; include the canonical route exports and verify a streamed response through the catch-all.
Useful? React with 👍 / 👎.
| npx next build 2>&1 | grep -E "error TS|Module not found|Failed to|Compiled successfully|✓ Compiled|Route \(app\)" | head -5 | ||
| node -e "import('./$2').then(m=>console.log(' native import: OK',m.default.marker)).catch(e=>console.log(' native import: FAIL',e.message))" 2>&1 | grep -E "native import|MODULE_TYPELESS" | head -3 |
There was a problem hiding this comment.
Propagate build and import failures from each probe variant
When next build or the native config import fails, these commands merely print filtered output: the pipeline discards the build's status, and the import's .catch() logs FAIL but resolves successfully. The final RC only reflects the served-route and AGENTS checks, so the probe can exit 0 even when the chosen shape no longer builds or cannot be imported—the two claims the spec cites this POC to establish. Although the final endpoint now updates RC, the current lines are fresh evidence that the build/import half remains non-failing; accumulate these results into the exit status as well.
Useful? React with 👍 / 👎.
| | Target directory exists and is not empty | Refuse, naming the path. | | ||
| | Project name is not a valid npm package name | Refuse, saying which rule failed, and offer the sanitized form. | | ||
| | Node runtime below the floor the generated project needs | Refuse, with the same floor and the same message init uses. Do **not** narrow the package's `engines` below the repo-wide `>=22` — FIX-1159 §9 records why. | | ||
| | `.env.local` would be written and git would not ignore it | Add the ignore entry first; if it cannot be added, refuse before the key is written (decision 7). | |
There was a problem hiding this comment.
Classify ignore verification as a partial-scaffold failure
When the generated .gitignore is absent, unwritable, or cannot be verified, this check can only happen after create-next-app has already created the target and supplied the file being inspected. It therefore cannot satisfy the surrounding requirement that every refusal leaves the disk untouched, while deleting the scaffold would contradict the later no-rollback rule. Move this case into the partial-scaffold failure taxonomy, or define a genuinely pre-creation check, so the implementer is not required to meet mutually exclusive outcomes.
Useful? React with 👍 / 👎.
|
The rework resolves both findings.
No additional changes were necessary, so I did not create a commit or follow-up PR. Checks
|
…tegory, probe accumulates Spec-review round 1 on the reworked document. All three findings folded; none was below the bar. P1 — the catch-all template omitted `export const dynamic = "force-dynamic"`. Verified against both cited files: packages/next/README.md ships createNextHandler alongside `runtime = "nodejs"` and `dynamic = "force-dynamic"`, and examples/hello-chat documents why — without it Next may buffer the response body, which turns token-by-token streaming into one delivery at the end. That is the epic's headline outcome failing while every wiring check passes. Both route files now carry the canonical exports, §10 asserts them, §12 records the premise (including that the Vercel quick-start's `maxDuration` is deployment-shaped and stays out), and the goal check now requires the response to render *incrementally* — the only check anywhere that can catch a missing force-dynamic. The second half of that finding was the sharper one: the POC set force-dynamic on the only route it exercised, so its green did not validate the specified shape. The probe now writes both route files with the canonical exports and asserts the catch-all serves a nested path, not just the bare route. P2 — probe.sh discarded `next build`'s status through a pipeline and let a rejected import() resolve, which are exactly the two claims §7 and §12 cite this POC to establish. Each variant now declares the outcome the README claims for it and a disagreement fails the probe, so "the build failed" is not automatically a failure (two variants are supposed to fail) but "the build did something other than documented" is. That change immediately caught a defect in the probe itself rather than in the finding: the first accumulating run exited 1 on the `.ts, no type field` row, because the import check called process.exit(0) in .then() and cut off MODULE_TYPELESS_PACKAGE_JSON before Node flushed it — the warning is emitted asynchronously. Isolated and confirmed (exit(0): 0 warnings captured; exitCode: 1). Fixed by setting process.exitCode and letting the process drain. A probe that could not fail would have recorded "clean" for the one variant whose whole purpose is to warn. Full run after the fix: all five variants match, both routes serve this run's marker, `probe: PASS`, exit 0. P2 — §9's .gitignore case asked for two mutually exclusive outcomes: it sat under "refusals leave the disk untouched" but can only run after create-next-app has created the target and written the file, and deleting the scaffold to qualify would contradict the no-rollback rule below it. It is now its own category, the credential stop, with the contradiction named so it is not reintroduced: the scaffold stays, the key is not written, and the remediation is printed. §10 gains the matching assertion; the taxonomy paragraph now describes three categories. Not re-done, already folded in dbda62f and confirmed by the reviewer: the exact create-next-app pin, and the probe's endpoint/no-free-port exit paths. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
@codex — all three folded in P1 — The failure mode is why this was above the bar on its own, and it's now written into §10: without Your second half was the sharper point, and it was right. The probe set P2 — build and import statuses now feed the exit code, and doing it caught a defect in the probe rather than in the finding. Each variant declares the outcome the README claims for it, so "the build failed" is not automatically a probe failure (two variants are supposed to fail) but "the build did something other than documented" is. The first accumulating run exited 1 on the Fixed by setting Full run after the fix — five variants all matching, both routes serving, P2 — the
§10 gains the matching assertion, and the taxonomy paragraph now describes three categories and why the middle one exists. Not re-done, per your correction: the exact Generated by Claude Code |
…an inherited ownership claim The spec already said "published unscoped", so the mechanical fix was a no-op — but it argued the name as brand fit, which left the scoped form looking like a harmless fallback. It is not, and that gap is what this fixes. Measured, not assumed: `npm create <name>` resolves to the UNSCOPED `create-<name>` — `npm create flow-state-nonexistent-xyz123` requests registry.npmjs.org/create-flow-state-nonexistent-xyz123. A scoped publish claims nothing outside its scope, so a scoped-only package would leave this spec's headline command resolving to a package that does not exist. Decision 1 now carries that reasoning, and rejects the scoped-plus-unscoped-alias compromise: it works, but nobody would ever be told to type the scoped form, so the second package exists only to be unused (tenet 3). One package. §12 carries the publish as a hard dependency and separates what is established from what is not, because the same assumption has already been wrong once: - Verified against the registry today: create-flow-state, flow-state-app, flow-state, fsdev and @flow-state-dev/cli all 404. Nothing in this project has ever been published. - Asserted, not verified: that the name is ours. npm has no reservation mechanism — a name is claimed by publishing — so this cannot be confirmed from outside until we publish. The coordinator has it with the owner. - Corrected: `create-fsd-app` is NOT ours. create-fsd-app@1.1.2 exists, published 2024-10-18 by an unrelated maintainer (keyready), a React/Vite starter. The brief I was working from said the owner had acquired it; that does not survive checking. FIX-1162's original finding stands, and only the choice of name moved. No fallback is designed for the name being unobtainable, per the coordinator's direction — a contingency there would spread through §5, §6, §7, §9 and §11 to hedge a question that gets answered before anything is built. Also names the one thing an implementer would otherwise get wrong by following convention: this package's manifest `name` is the bare `create-flow-state`, the only unscoped package in the repo, and the directory name does not set it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
OutcomeThe requested follow-up is already fully addressed in
The repository is clean, so I did not create an empty commit or a redundant follow-up PR. This complies with the requirement not to call Testing
|
|
Naming correction folded in The mechanical part was already right; the reasoning was not. The spec has said "published unscoped" since the re-draft, so nothing about the plan changed. What was wrong is that decision 1 argued it as brand fit — which is exactly what leaves a scoped fallback looking harmless to a reviewer or an implementer. It isn't, and now the spec says why, measured rather than asserted:
Also added, because it is the one thing an implementer would get wrong by following convention correctly: this package's manifest The correction going the other way:
So FIX-1162's original finding was right and the later report that we had acquired the name does not survive checking. This changes nothing about the choice — On your caveat, implemented as directed. §12 now separates the two states explicitly rather than blurring them: verified — every relevant name 404s and nothing under this project has ever been published; asserted — that the name is ours. Worth stating plainly since it sharpens your point: npm has no reservation mechanism. A name is claimed by publishing, so "the owner holds One thing I did not do, flagging it rather than acting: New head: Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c67c063661
ℹ️ 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".
| `npm create flow-state my-app` makes a directory, puts a working AI chat feature in it, and | ||
| leaves the developer looking at that feature streaming in their browser. |
There was a problem hiding this comment.
Align the one-command promise with the actual stopping point
The proposed command does not leave the developer viewing a streaming feature: the transcript in §5 stops after scaffolding and tells them to run npm run dev, while §10 likewise requires starting that command and interacting with the browser separately. This makes the headline outcome and acceptance path disagree, so either the scaffolder must start/open the app or the promised outcome should explicitly be a ready-to-run project rather than a visible result.
Useful? React with 👍 / 👎.
…ream Codex flagged §2's "leaves the developer looking at the feature streaming" against §5's transcript, which stops after scaffolding and prints `npm run dev`. Offered two fixes: auto-start the app, or restate the outcome. Neither taken — the mismatch is in the epic, not here, and the epic-agent is folding it. Verified directly rather than inherited: the epic's §1 states the Outcome as "in one step" (line 17) while its Proof for this issue says "the npx command followed by the printed dev command" (line 57). The Proof is the precise statement and was sharpened at epic review round 3, so the Outcome is the loose half. This spec already matches the Proof — §5's transcript is the exact stopping point and §10 measures from it. Auto-start is explicitly ruled out in the note: create-next-app and create-vite both stop and print the dev command, so adopting it would be scope growth bought with a reviewer's phrasing. Recorded with the §1-Outcome-versus-§1-Proof mismatch named so it does not come back a third time, and with the escape hatch pointed at prose (one sentence in §2) rather than at scaffolder behaviour. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
@codex — real finding, but neither proposed fix is the right one, and the mismatch is not in this spec. Recorded in §13 ( Where the contradiction actually lives. Checked the epic directly rather than reasoning from this document:
Two lines in the same section disagreeing. The Proof is the precise one and was deliberately sharpened at epic review round 3, so the Outcome is the loose half — and it is the half being fixed. The epic-agent has it. This spec already matches the Proof. §5's transcript ends after scaffolding and prints On the first option — having the scaffolder start and open the app — no. On the second — restating the outcome — that is the right shape of fix, in the wrong document. Rewording §2 here while the epic still says "in one step" would leave the child tighter than its parent and invite the reverse finding next round. It goes upstream first; if §2 still reads as overclaiming afterwards, §13 points at the fix being one sentence of prose, never a behaviour change in the scaffolder. For what it is worth, this is the third finding of yours on this PR that turned out to be pointing at something real one layer up rather than at the thing it landed on — the pin, the probe's exit status, and now this. That pattern is worth more than the individual catches. New head: Generated by Claude Code |
OutcomeAgreed—the review finding is valid, but the requested change does not belong in this spec.
No additional changes were warranted: the working tree is clean at Testing
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a1c1553e8c
ℹ️ 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".
| local got_build; [ $build_status -eq 0 ] && got_build=pass || got_build=fail | ||
| echo " build: $got_build (expected $want_build)" | ||
| [ "$got_build" = "$want_build" ] || fail "$label: build $got_build, README claims $want_build" |
There was a problem hiding this comment.
Validate the expected build failure reason
When either intentionally failing .mts variant breaks for an unrelated reason—such as a shared route syntax error, dependency failure, or new Next.js regression—this reduces every nonzero build status to fail and accepts it as matching the documented result. The probe can therefore exit successfully without reproducing the specific TS5097 or module-resolution behavior used to justify the chosen config shape; assert the expected diagnostic for each failing variant rather than only the exit status.
Useful? React with 👍 / 👎.
| echo "AGENTS.md delimiters:"; grep -o 'BEGIN:[a-z-]*' AGENTS.md || echo " (none)" | ||
| echo ".gitignore env line:"; grep -n '^\.env' .gitignore || echo " (none)" |
There was a problem hiding this comment.
Make the scaffold discovery checks affect the result
When the pinned scaffolder stops creating AGENTS.md or its .gitignore loses the .env* rule, these commands only print the absence and leave RC unchanged. The later append can recreate AGENTS.md, and next dev can restore Next's block, so the probe may still exit 0 even though the spec cites these as verified scaffold facts; turn the discovery checks, including the claimed CLAUDE.md creation, into assertions that call fail.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dce7a2611f
ℹ️ 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".
| **Step 6 — add the dependencies, which is also the install.** Run the resolved package manager's | ||
| **add** command in the target directory, with the dependency set derived above as its arguments — | ||
| `npm install <pkg> …`, `pnpm add <pkg> …`, `yarn add <pkg> …`, `bun add <pkg> …`. **This is the | ||
| step that writes the dependency entries into `package.json`**, and it resolves them in the same |
There was a problem hiding this comment.
Pin generated dependencies to compatible versions
When an older scaffolder is invoked after any FSD, provider SDK, or Zod release, these bare package names resolve the current registry versions rather than versions tested with the checked-in template. This is especially unsafe because .changeset/config.json has no fixed or linked FSD release group, so a pre-1.0 package can move independently and leave the generated project failing to build or run even though the exact create-next-app pin remains unchanged; include compatible versions in the add arguments while still letting the package manager author the manifest and lockfile.
Useful? React with 👍 / 👎.
| > **The generated app refuses to serve its demo flow in production until real authentication is | ||
| > configured. Once it is, the app serves normally wherever it is deployed — container, platform, | ||
| > or bare host. In development it also binds to the local machine only, which is a development | ||
| > default the developer can change in one word.** |
There was a problem hiding this comment.
Keep authenticated production hosts reachable
When a developer configures real authentication and self-hosts with the generated npm start, the hard-coded next start --hostname 127.0.0.1 from decision 8 remains in effect, so a reverse proxy, container, or remote client still cannot reach the app. The promise that authentication alone makes the app serve normally on a bare host is therefore false; either leave the production bind network-accessible behind the production authentication guard or tell users that they must also change scripts.start.
Useful? React with 👍 / 👎.
| app/page.tsx (replaced — the stock Next.js page) | ||
| Appended AGENTS.md (FSD section) | ||
| Wrote .env.local (OPENAI_API_KEY, already ignored by git) | ||
| Added 7 dependencies via npm (@flow-state-dev/*, @ai-sdk/openai, zod) |
There was a problem hiding this comment.
Report all eight generated dependencies
The exhaustive dependency rule at lines 772–781 contains eight direct dependencies—six @flow-state-dev/* packages, the selected provider SDK, and zod—but this required success transcript reports seven. Because the spec says every transcript line is emitted and the report is compared with the generated diff, a correct implementation must either misreport a successful scaffold or omit a required package; derive the displayed count or change it to eight.
Useful? React with 👍 / 👎.
…l, pin FSD versions, derive the dependency count Three findings on dce7a26. The epic withdrew `start` from theme 6 exception (c) and this spec had not followed — the eighth restatement drift. Narrowing `start` is actively harmful: "a platform deploy never runs next start" is false of Docker/Render/Railway/ Fly/Heroku/App Runner, and Next's -H carries no env binding, so a container binds loopback and reads as dead. scripts.start now keeps create-next-app's value byte for byte, which settles the finding that a self-hosted app could not be reached. The production refusal is not shipped. A POC ran executeServeCommand and found the guard keys on bind address not environment, enforces whole-app not per-flow, refuses a host-authenticated app as a false positive, and never runs on the Next mounted route at all — verified independently: the symbol appears only under packages/node and packages/cli/src/commands/serve.ts. The old wording named a control we had not built. The product statement is withdrawn with it; four versions were false, each derived from our own rules rather than measured. §10 gains the mirror assertion — the built app is reachable from a non-loopback address and scripts.start is unmodified — which asserts the absence of a narrowing rather than the presence of a guard, so it needs no Q7 answer. FSD packages in the add argument set now carry an exact version. changeset config declares fixed:[] and linked:[], so they version independently and bare names resolve whatever latest is rather than what the template was tested against — while create-next-app stays exactly pinned, making the project look reproducible when half of it is not. A fixed release group would collapse the pin to one string; raised with FIX-1162 rather than decided here. The transcript's dependency count is rendered from the add argv rather than typed; it said 7 while the derived table required 8. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
… claim Residual sweep after d34dfa9. Withdrawing the scripts.start narrowing changes the change-set arithmetic everywhere it is stated: four scaffolder-file changes become three (§7's further-changes framing) and five become four (§5's what-the-run-touched framing). Also removed the start row from the change table, the production refusal from the flow-file and step-3 descriptions, the engine-guard premise that described a control no longer specified, and the follow-up asking whether the framework should own that guard — replaced by the Q7 dependency. §10's script assertion now checks both directions: dev carries the flag, start does not. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
…d in the evolution log Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
@codex — all three folded in Direction-level #1 — the production bind. Confirmed, and the fix is a withdrawalYou are right that
The production refusal is withdrawn too, and that is the larger half. A POC ran
So the decision named a control that does not exist and could not be described. Four successive product statements were false, and every one was produced the same way — by deriving behaviour from our own rules rather than measuring it, with the derivation never failing loudly. The statement is withdrawn rather than rewritten a fifth time; what a rail should do is epic §5 Q7. §10 keeps the dev-bind assertion and gains its mirror: the built app is reachable from a non-loopback address and One hazard logged in §12 for whoever writes deployment docs: the sanctioned escape from the false positive is Direction-level #2 — unpinned versions. Confirmed, and checked against the release process
The asymmetry is what makes it worse than an ordinary risk, and it is the part I would not have seen without the finding: this spec pins FSD packages now carry an exact version in the Not decided here: if the release process adopts a Implementer-level — the count, fixed derivedThe transcript said Fixed the second way you offered: the count and the list are rendered from step 6's This one is the class in miniature, and it is worth naming as such: a number stated in one place, derived in another, with nothing keeping them equal. That is exactly the recorded-but-not-enforced shape §13 now opens with — the FIX-1160 edge, the dependency set, sub-PR Generated by Claude Code |
Summary
Testing
|
…ecord the credential asymmetry Cross-spec check against FIX-1159 at 4a110aa and the epic at 673fcd5. FIX-1159 does put a per-flow FSD_DEMO_TOKEN on its demo flow, but that is a different artifact: it writes flows/hello/flow.mts, this template writes src/flows/chat/flow.ts, and FIX-1159's Non-goals disclaim the greenfield template in every part. Epic theme 8's matrix — the statement of record — gives greenfield mounted-route the dev bind and explicitly no credential, because the demo is a browser page and any token it holds is readable from that page. Both descriptions are true of their own flow. §12 now says so with the matrix, since two specs describing "the demo flow" with opposite postures is how a reader believes the wrong one. §12 also gains the plain deployment description: dev binds loopback, production binds wherever Next binds, and the demo flow accepts any caller — so a deployed generated app runs model calls for anyone who finds it, billed to the developer's key. Description, not alarm; it is what Q7 is deciding. Also fixes a defect of the class §13 opens with, in my own text: decision 8 said the description was "in §12" while §12 contained none. A cross-reference to content that does not exist is a requirement nothing enforces. Logged in place rather than quietly corrected. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
… printed transcript Eleventh instance of the shape, and the first on a withdrawal reaching printed output. The generated success transcript still told the user "This app serves on 127.0.0.1 only, and will not serve in production until you configure authentication." Both halves became false when decision 8 withdrew the start narrowing and the production refusal. Replaced with the two things that are true: npm run dev binds loopback, and the demo flow accepts any caller. The larger finding is where that text lives. It is inside FIX-1159's canonical next-steps block, which this package embeds verbatim under a normalized equality assertion — so a withdrawn promise surviving in canonical would be re-shipped to every user of the scaffolder, with the drift check actively preventing the shipper from correcting it. §12 now carries that to FIX-1159 as a required correction rather than a suggestion. §13's note is widened to cover withdrawals, which it did not. A rule about requirements being enforced somewhere does not cover promises that must stop being made in every place they appear, and this epic has now proven the withdrawal direction four times. Both directions are stated, with the embedded-under-equality case called out as the one a shipper cannot complete from its own side. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
… log Residual from the withdrawal sweep. An evolution entry still read "Decision 8 now carries the corrected statement verbatim as the wording to use" and quoted a statement that is false and withdrawn — prescriptive phrasing in a historical log. Marked superseded with a pointer to decision 8, and left in place rather than rewritten, since a run of corrections each looking final is the argument for withdrawing the statement rather than fixing it again. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
Folded in The transcript still promised the refusal I withdrew — confirmed, and the mechanism makes it worse than a stale lineThe generated success transcript told the user:
Both halves are false. The part that is bigger than the wording: that text lives inside FIX-1159's canonical next-steps block. This package embeds it verbatim and §10 asserts normalized equality over the whole block. So a withdrawn promise surviving in canonical would be re-shipped to every user of the scaffolder, with the equality check actively preventing the shipper from correcting it — the mechanism built to stop drift would pin a false security claim in place. §12 now carries this to FIX-1159 as a required correction, not a request, because a shipper cannot fix it from its own side by construction. §13's note did not cover withdrawals. It does nowYou were right to ask. The note read "a requirement recorded in one section and enforced by no other" — which says nothing about a promise that must stop being made everywhere it appears. That direction has now cost this spec four times:
The rule is now stated in both directions. Additions: name the artifact that will execute the requirement. Withdrawals: enumerate every surface that restates the claim before declaring it withdrawn — decision, tables, transcripts, printed output, tests, and anything embedding it verbatim downstream. A promise withdrawn in one section and still printed in another is not withdrawn, and it is worse than before, because the document now disagrees with itself and the surviving copy is the one a user reads. One clause is specific to this case and generalises past the document: when you withdraw a claim, check whether any downstream artifact embeds it under an equality constraint. That is where a withdrawal cannot be completed from your own side. A residual from my own sweep, logged rather than quietly fixed: an evolution entry still read "Decision 8 now carries the corrected statement verbatim as the wording to use" and quoted a statement that is false and withdrawn — prescriptive phrasing in a historical log. Marked superseded, left in place, because four corrections each looking final is the argument for withdrawing the statement rather than fixing it a fifth time. The cross-spec question: distinct artifacts, and the asymmetry is a ruleVerified against FIX-1159 at They are different files. This template writes The asymmetry is epic theme 8's matrix, which is the statement of record:
The generalisation cuts across greenfield/brownfield rather than along it: a path gets the bind when we author the command that starts the server, and the credential when the demo ships no browser client to leak it. This template authors So both statements are true of their own flow. §12 now says so explicitly, with the matrix, because two specs in one epic describing "the demo flow" with opposite postures is how a reader believes the wrong one. And what a developer actually gets, in the spec that ships it§12 now states it as description rather than alarm — dev binds loopback; production binds wherever Next binds; the demo flow accepts any caller, so a deployed generated app is an endpoint that runs model calls for anyone who finds it, billed to the developer's provider key, with no tenant boundary. Process noteTaken, and applied here: the fix for this finding was committed in an environment that could not push, so I treated the report as a finding only and re-derived the edit from the description. That turned out to matter — the described fix is the transcript line, but re-deriving it surfaced that the line is canonical text owned by another issue, which is the constraint that makes it a cross-issue correction rather than a local one. Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eb38deaaa4
ℹ️ 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".
| **The FSD packages in that argument set carry an exact version; the others do not.** `npm install | ||
| @flow-state-dev/core@<v> @flow-state-dev/engine@<v> …` — one version string, held in the same | ||
| constant file as the `create-next-app` pin and bumped with it as scheduled maintenance behind a | ||
| goal-check run. `zod` and the `@ai-sdk/*` package keep their bare names. |
There was a problem hiding this comment.
Pin Zod to the core-compatible major
When the bare zod dependency resolves to Zod 4, the generated flow imports a v4 schema and passes it to @flow-state-dev/core, whose packages/core/package.json still depends on zod ^3.25.76 and exposes v3 ZodTypeAny in its block APIs. A v4 z.object(...) is incompatible with that type (TS2740), so the generated Next project can fail its build immediately. Fresh evidence beyond the earlier dependency-pin comment is that this revision now explicitly leaves Zod floating; pin a compatible Zod 3 release or first make the framework's schema boundary support v4.
Useful? React with 👍 / 👎.
| **The FSD packages in that argument set carry an exact version; the others do not.** `npm install | ||
| @flow-state-dev/core@<v> @flow-state-dev/engine@<v> …` — one version string, held in the same | ||
| constant file as the `create-next-app` pin and bumped with it as scheduled maintenance behind a |
There was a problem hiding this comment.
Version each independently released package separately
After any release where the FSD packages have different versions, this single <v> requests an incorrect or nonexistent version for at least one of core, engine, next, react, CLI, or DevTool. The following paragraph confirms that .changeset/config.json has no fixed or linked group, so these packages version independently. Fresh evidence beyond the earlier bare-dependency finding is that the proposed pinning fix collapses those independent versions into one constant; use a tested per-package version map or make fixed-group adoption a prerequisite.
Useful? React with 👍 / 👎.
| **The FSD packages in that argument set carry an exact version; the others do not.** `npm install | ||
| @flow-state-dev/core@<v> @flow-state-dev/engine@<v> …` — one version string, held in the same |
There was a problem hiding this comment.
Save the dependency pins without range prefixes
When npm or pnpm performs this add, specifying @pkg@<v> selects that exact version for the current install but does not necessarily persist an exact manifest entry: npm install --help lists -E|--save-exact while the default configuration is save-exact=false with save-prefix=^, and pnpm add --help describes -E as “Install exact version.” A later lockfile refresh can therefore drift despite the spec's pinning guarantee. Fresh evidence beyond the earlier pinning comment is that the new add command omits the package-manager-specific exact-save option; include it or verify that the written manifest contains literal versions.
Useful? React with 👍 / 👎.
| | `-y` with no key in the environment | Scaffold completes. `.env.local` carries the empty variable line, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. **There is no key flag** (§5), so `-y` and an unset variable is the only way to reach this state, and it is CI's path rather than the goal check's. | | ||
| | The developer runs `npm run dev` and `fsdev dev` together | Both open the same development file store; concurrent writes to one session can each be accepted. Tolerable for a development default, and the next-steps block says to drive one at a time (§12 raises the wording with FIX-1159, which authors the block). | | ||
| | The developer wants to reach the app from another device | `npm run dev` binds `127.0.0.1` (decision 8), so it will not connect. This is the intended behaviour, not a bug: the flow is unauthenticated and the bind is the only control. The fix is theirs to make — remove `--hostname 127.0.0.1` from `scripts.dev`, a one-word edit in a file we wrote seconds ago — and they should understand what they are removing. | | ||
| | The developer deploys the generated app as-is | The mounted route **refuses before any model invocation**, with an error naming the missing authentication (decision 8). Not a warning, and not a 200 with an error body. | |
There was a problem hiding this comment.
Delete the withdrawn production-refusal row
When an implementer follows this deployment row, they must add an authentication refusal that the current design explicitly excludes: decision 8 says no production rail ships, the generated-flow contract says it declares no production refusal, and §10 deliberately omits that assertion pending Q7. Fresh evidence after the earlier guard and bind comments is that this revision now expressly withdraws the refusal while this row still mandates it; remove or rewrite the row so the build plan has one production contract.
Useful? React with 👍 / 👎.
| node -e "import('./$cfg').then(m=>{ | ||
| if(m.default.marker!=='config-module-loaded'){console.error('WRONG MODULE');process.exitCode=3} | ||
| }).catch(e=>{console.error('IMPORT THREW: '+e.message);process.exitCode=3})" > import.log 2>&1 |
There was a problem hiding this comment.
Neutralize warning suppression before probing imports
When the caller has NODE_NO_WARNINGS=1 or NODE_OPTIONS=--no-warnings, this child inherits it, so the expected MODULE_TYPELESS_PACKAGE_JSON diagnostic is suppressed and the no-type-field variant is classified as clean. The probe then exits 1 and reports a documented Node behavior as disproved even though the environment merely hid the evidence, violating the README's exit-1/exit-2 contract. Clear warning-suppression variables for this invocation or classify such an environment as cannot-verify.
Useful? React with 👍 / 👎.
…with a per-package map, assert the written manifest Five findings on eb38dea, three of them defects in the pinning fix from the previous round. Leaving zod floating aimed the risk at a specific type boundary: core depends on zod ^3.25.76 and types its public block surface as v3 ZodTypeAny, so a bare zod resolving to v4 fails next build on a type error before any model call. Pinned to a compatible v3 range; whether core should accept v4 is raised as a separate framework question. One version placeholder cannot version six independently released packages — changeset config declares fixed:[] and linked:[]. Replaced with a per-package version map. A fixed release group would collapse it to one entry; that is FIX-1162's work and is a note, not a dependency, since the map is correct either way. add pkg@1.2.3 does not persist 1.2.3: npm defaults to save-prefix=^ and pnpm needs -E. The exact flag is specified and §10 now asserts the written manifest rather than the argv, which also catches a changed default and a lockfile refresh. §9's deployment row still mandated the withdrawn production refusal — the third surface for that withdrawal and the fourth table row across all of them. §13's note now names tables and matrices specifically, since a row states a claim in a section organised by a different question and a phrase search never finds it. probe.sh cleared NODE_NO_WARNINGS/NODE_OPTIONS for the import check: inherited suppression made a true claim about Node report as disproved. Second application of the standing unfreeze clause, applied without re-arguing it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
All five folded in P1 — floating Zod. Confirmed, and the shape is worse than "unpinned"Verified: The framing in the finding is the part worth keeping. The previous round pinned the FSD packages and left Zod floating deliberately. That did not leave a general risk in place; it aimed the remaining risk at the one type boundary the generated flow crosses on every run. A partial fix that removes the safe cases and keeps the dangerous one is worse than no fix, because the surviving hazard now looks considered.
P2 — one
|
| withdrawn | surviving surface | kind |
|---|---|---|
scripts.start narrowing |
decision 8, change table, §8, §10 | table row |
| production refusal | file-table row, step 3, §12 premise, follow-up | table row |
| same refusal | the generated success transcript | printed output |
| the §12 description | a cross-reference to content that did not exist | cross-reference |
| same refusal, third time | §9's deployment row | table row |
The mechanism is now stated: prose restates a claim in language a reader recognises as a restatement, while a row states it as a fact, compressed, in a section organised by a different question — §9 by failure case, §7's file table by file, neither by which control ships. So a search for the withdrawn wording never finds it, because the row never used that wording. The rule now says to walk every table and matrix by reading the rows. I ran that sweep on this revision; the remaining rows are consistent.
P2 — probe warning suppression. Applied under the standing clause, not re-argued
Confirmed and fixed: the import check reads stderr to decide whether Node's documented MODULE_TYPELESS_PACKAGE_JSON warning appeared, and suppression is inherited — under NODE_NO_WARNINGS=1 or --no-warnings the no-type-field variant emits nothing, classifies as clean, and the probe exits 1: disproved on a true claim. Both variables are cleared for that invocation.
You are right that the rule already decided this, so I applied it and said so rather than re-litigating: it is under-reporting, not over-assertion, and documenting it would again mean telling a reader a red result might not mean what it says.
Two instances is enough to state the shape, and the README now carries it: this probe reads its evidence from process output, and process output is environment-dependent. Any future check that decides a claim from stdout/stderr clears whatever suppresses the signal it reads, or classifies the environment as cannot-verify (2).
The two dependencies
Both understood and neither anticipated. The withdrawn promise in FIX-1159's canonical block stays routed there as a required correction — this spec cannot close it from its own side. And everything reading "pending Q7" stays pending; nothing here assumes an answer, and §9's deployment row now says explicitly do not implement a production refusal before Q7 answers, since that row is where an implementer would otherwise pick it up.
Generated by Claude Code
Spec approved. Per the owner's direction, no further review rounds. The Zod pin landed in 48cc886 as the one finding that would break an implementer on day one: core depends on zod ^3.25.76 and types its public block surface as v3 ZodTypeAny, so an unpinned zod resolving to v4 fails next build before any model call. The remaining four findings are recorded in §13 as short implementer notes rather than further spec surgery: the version map versus a fixed release group, asserting pinning on the written manifest rather than the argv, the standing prohibition on building a production refusal before Q7 answers, and the probe's environment-dependent evidence. No surviving instruction to build a production refusal remains anywhere in the document; §9's deployment row states the prohibition rather than annotating a withdrawn mandate. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 071e3e915c
ℹ️ 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".
| # A section that is already malformed cannot speak to survival either way. That is | ||
| # "could not verify" (2), never "the claim is false" (1). | ||
| case "$FSD_BEFORE" in *"$FSD_E"*) ;; *) echo " FSD section malformed before next dev — CANNOT VERIFY"; exit 2;; esac | ||
| case "$NXT_BEFORE" in *"$NXT_E"*) ;; *) echo " next's block malformed before next dev — CANNOT VERIFY"; exit 2;; esac |
There was a problem hiding this comment.
Preserve mismatches for a missing Next agent block
When the pinned create-next-app stops writing its nextjs-agent-rules block, the earlier assertion sets RC=1, but the empty NXT_BEFORE value reaches this branch and immediately exits 2. A malformed block with a missing end marker follows the same path. Both cases disprove the README's asserted scaffold shape rather than making the environment unverifiable, so this masks the upstream regression the probe is intended to detect; retain exit 1 for absent or malformed scaffolder output.
Useful? React with 👍 / 👎.
| ``` | ||
| npm install --save-exact \ | ||
| @flow-state-dev/core@<core> @flow-state-dev/engine@<engine> \ | ||
| @flow-state-dev/next@<next> @flow-state-dev/react@<react> \ | ||
| @flow-state-dev/cli@<cli> @flow-state-dev/devtool@<devtool> \ | ||
| @ai-sdk/openai@<sdk> zod@<zod> |
There was a problem hiding this comment.
Install developer tooling as dev dependencies
When a generated app is packaged for production, this ordinary npm install writes @flow-state-dev/cli and @flow-state-dev/devtool into dependencies, so production-only installs cannot omit their CLI, UI assets, and transitive packages. The dependency table establishes that these two packages exist solely for the printed local-development commands, while the generated server imports neither; add them separately as exact dev dependencies so deployments do not carry development tooling.
Useful? React with 👍 / 👎.
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 071e3e915c
ℹ️ 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".
| # `fail`, reporting exit 1 (claim disproved) for a true claim, which is the one | ||
| # direction of wrongness that trains a reader to ignore a red result. | ||
| git init -q . 2>/dev/null || { echo " git init failed — .gitignore claim CANNOT VERIFY"; exit 2; } | ||
| if git check-ignore -q .env.local; then |
There was a problem hiding this comment.
Isolate the ignore check from global Git rules
When the caller's core.excludesFile contains .env.local, git check-ignore succeeds even if the scaffold has no project-owned ignore rule; git check-ignore -v reproduces this while identifying the global file as the source. The probe can therefore keep passing after create-next-app drops its rule, falsely supporting the README/spec premise and allowing the eventual credential step to omit a durable local entry. Neutralize global excludes for this assertion or verify that the verbose match comes from the scaffold.
Useful? React with 👍 / 👎.
| *Not the package's `engines`.* This floor is what the **generated app** needs, checked against | ||
| the Node actually running the command. The scaffolder's own `engines` stays at the repo-wide | ||
| `>=22`; §9 records why narrowing that is a separate mistake. |
There was a problem hiding this comment.
Persist the runtime floor in the generated app
When a project is scaffolded on Node 22.18+ and later cloned or deployed on Node 22.0–22.17, the one-time scaffolder check no longer runs, the FSD packages' >=22 engines still admit that runtime, and the printed CLI commands fail to import fsdev.config.ts. The current revision addresses the earlier runtime-floor issue only during creation; keep the scaffolder's own engine range unchanged, but add node >=22.18 to the generated app's manifest so its stated requirement travels with the project.
Useful? React with 👍 / 👎.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 071e3e915c
ℹ️ 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".
| 2. **One template ships: the Next.js chat app — conditional on a supported minimal-project path | ||
| existing for backend developers.** *This reverses epic theme 2, it is the ask on this PR, and | ||
| this spec asserts no answer to it — see the framing below and epic §5 Q6, which is open and | ||
| blocks implementation.* |
There was a problem hiding this comment.
Apply the resolved one-template decision to the spec
Fresh evidence beyond the earlier option-B comment is the PR description’s explicit declaration that Q6 is answered with one Next.js starter and the spec is closed, while this decision still marks Q6 open and implementation-blocking here and again in §§3 and 12. An implementer following the spec would therefore wait for an already-made decision or reopen the discarded two-template branch; make decision 2 unconditional and remove the stale ask/open-question language.
AGENTS.md reference: AGENTS.md:L58-L58
Useful? React with 👍 / 👎.
| # variant emits nothing, classifies as `clean`, and the probe reports a TRUE | ||
| # claim about Node as DISPROVED — the same false-disproof direction as the | ||
| # `git init` case, from a different cause. Cleared for this invocation only. | ||
| NODE_NO_WARNINGS= NODE_OPTIONS= \ |
There was a problem hiding this comment.
Clear redirected Node warnings before classifying the import
Fresh evidence after the earlier warning-suppression fix is Node’s separate NODE_REDIRECT_WARNINGS environment variable, which this invocation still inherits. node --help describes the corresponding option as “write warnings to file instead of stderr”; with this variable set, the expected MODULE_TYPELESS_PACKAGE_JSON warning goes to that file, import.log remains empty, and the no-type-field variant is misclassified as clean, causing exit 1 for a true claim. Clear NODE_REDIRECT_WARNINGS as well or classify that environment as cannot-verify.
Useful? React with 👍 / 👎.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 071e3e915c
ℹ️ 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".
|
|
||
| | file | what it is | | ||
| |---|---| | ||
| | `fsdev.config.ts` | default-exports `createFlowState({ flows, modelResolver, stores })`. **`createFlowState` and the filesystem store factory both come from `@flow-state-dev/engine`, not `core`** — see the dependency set below. Registers the demo flow explicitly; **statically imports the chosen provider's factory and passes a pre-built `createModelResolver({ providers: { … } })` as `modelResolver`, with no intents** (decision 5); and declares FIX-1159 decision 5's development file store, qualified as such | |
There was a problem hiding this comment.
Ignore the generated filesystem store
Once the user sends a message through the generated app or a printed CLI command, this development store writes session and request data under the local store directory (conventionally .fsdev/data), but the pipeline only verifies an ignore rule for .env.local; create-next-app cannot supply an FSD-specific ignore rule. Consequently, a normal git add . can commit chat contents and execution state—the repository itself avoids this with **/.fsdev/** in its root .gitignore. Add the generated store path to the scaffold's ignore rules and verify it with git check-ignore alongside the credential check.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 071e3e915c
ℹ️ 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".
|
|
||
| | package | why it is in the set — derived from | pnpm-only? | | ||
| |---|---|---| | ||
| | `@flow-state-dev/engine` | `fsdev.config.ts` imports **`createFlowState`** and **`createFilesystemStores`**, both exported from `engine` (`packages/engine/src/index.ts`), not from `core` | **yes** | |
There was a problem hiding this comment.
Use the filesystem store adapter in generated configs
Following this dependency/config contract makes every generated app wire createFilesystemStores(...), which returns a flat StoreRegistry, into createFlowState({ stores }); that option instead requires named profiles containing StoreAdapter values with capabilities and resolve. The generated config therefore fails typechecking (or store resolution if forced through). Specify filesystemStores(...) and the required profile/slot wrapper instead.
Useful? React with 👍 / 👎.
| | Case | Expected | | ||
| |---|---| | ||
| | `.env.local` is about to be written | Ask git whether it would ignore that exact path (`git check-ignore`), never whether `.gitignore` contains a rule that looks right. In a fresh `create-next-app` scaffold the answer is already yes (verified), so this is normally an assertion rather than a write — but it is the assertion the credential stop rests on, so it is made against the path, not the text. | | ||
| | The ignore entry cannot be established | **Stop before the key is written.** The scaffold stays on disk and is left usable; print what is missing, the one line to add to `.gitignore`, **and the two remaining steps by name** — write the key into `.env.local`, then run the install. Never write the key "and warn" — the warning scrolls away and the credential does not. **The recovery is complete because the `AGENTS.md` section already landed in step 4** (§7); had the append still been last, this stop would have left the developer a project silently missing canonical text they cannot author. | |
There was a problem hiding this comment.
Print the dependency-add command on credential stops
When the ignore check cannot be established, execution stops before step 6, so the manifest still has none of the FSD dependencies. Telling the developer merely to “run the install” can lead to npm install, which installs only the existing create-next-app manifest and leaves every generated FSD import unresolved; rerunning the scaffolder is also rejected because the target is now nonempty. Print the full versioned package-manager add command and package list here, as required for the step-6 failure path.
Useful? React with 👍 / 👎.
| 7. **The printed next-steps block** — FIX-1159's canonical block embedded verbatim, rendered for | ||
| the resolved package manager and the `mounted-route` topology. *Test:* normalized equality over | ||
| the whole block including the `second-process` branch this package never renders; every printed | ||
| command runs. *Depends on:* 6, **and FIX-1159's block existing** — see §12. |
There was a problem hiding this comment.
Preserve next-step output on recoverable failures
Step 7 is the only point that prints the canonical dev, DevTool, and CLI commands, but both recoverable stops occur in steps 5 and 6 before reaching it. Even after the developer follows the recovery instructions and finishes the key or dependency work, the nonempty target prevents rerunning the scaffolder, so this package never performs one of the five jobs it explicitly owns. Include the next-steps block in those recovery paths or provide a resumable way to emit it.
Useful? React with 👍 / 👎.
| **Unattended use is still legitimate and still works** — `-y` with the provider's variable already | ||
| exported produces a complete project without a prompt. What is unsupported is a key on the command | ||
| line. |
There was a problem hiding this comment.
Test unattended scaffolding with an environment key
This promises that -y plus the selected provider's environment variable produces a complete unattended scaffold, but the goal runs deliberately remove provider keys and the CI list tests only -y with no key. An implementation that never reads the environment and always writes an empty value would therefore satisfy every specified check while breaking this advertised automation path. Add coverage that exports each supported provider variable, runs with -y, and verifies the resulting credential and usable scaffold.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 071e3e915c
ℹ️ 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".
| every addition): §6 is mostly about keeping the file list short and refusing surface — including a | ||
| `--template` flag with one legal value. | ||
|
|
||
| ### 6. Decisions & rules — the sign-off surface |
There was a problem hiding this comment.
Limit the sign-off surface to three outcome decisions
When the owner reaches the approval gate, this section asks them to certify eight decisions across roughly 4,200 words, including implementation mechanics such as module extensions, provider wiring, dependency handling, and Git commands. The repository's spec template caps this surface at three outcome-shaping calls; move engineer-owned mechanics to Part II so approval is not ambiguous about which product decisions the owner actually made.
AGENTS.md reference: AGENTS.md:L54-L58
Useful? React with 👍 / 👎.
| grep -E "error TS|Module not found|Failed to|Compiled successfully|Route \(app\)|/api/flows" build.log | head -4 | sed 's/^/ /' | ||
| local got_build; [ $build_status -eq 0 ] && got_build=pass || got_build=fail | ||
| echo " build: $got_build (expected $want_build)" | ||
| [ "$got_build" = "$want_build" ] || fail "$label: build $got_build, README claims $want_build" |
There was a problem hiding this comment.
Classify environmental build failures as inconclusive
When next build is killed by an OOM, runs out of temporary-disk space, or otherwise fails for an environmental reason, this branch records a mismatch and the probe exits 1 (“claim disproved”) rather than 2 (“could not verify”). The later diagnostic check only records another mismatch when the expected route output is absent, so infrastructure failures violate the README's load-bearing exit-status contract; recognize such failures as inconclusive instead of treating every nonzero build as evidence against the documented variant.
Useful? React with 👍 / 👎.
|
|
||
| --- | ||
|
|
||
| ## Spec evolution |
There was a problem hiding this comment.
Collapse the superseded spec history
When an implementer searches this artifact for a behavior or decision, the uncollapsed 381-line evolution ledger exposes thousands of words of superseded—and sometimes explicitly false—designs alongside the current contract, increasing the chance that stale instructions are followed. Git and the PR already preserve this history; keep the current requirements visible and place any necessary provenance in a collapsed section as required for human-facing artifacts.
AGENTS.md reference: AGENTS.md:L217-L221
Useful? React with 👍 / 👎.
|
@codex review |
1 similar comment
|
@codex review |
|
Codex Review: Didn't find any major issues. Chef's kiss. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
1 similar comment
|
Codex Review: Didn't find any major issues. Chef's kiss. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |


The problem
Someone who hears about FSD and has no project yet has nowhere to start. Adding FSD to a
repository that already exists is now agent work (FIX-1159's install skill), and that path
assumes a repository. For someone starting fresh there is no path at all short of assembling one
by hand out of our monorepo — the thing this epic exists to stop asking people to do.
Public Launch's front door is a single command, and what a stranger judges FSD by in the first
five minutes is whether that command ends at something that visibly works.
What this spec does
npm create flow-state my-app→ a Next.js app with a working chat page, plus the dev command itprints. Run that command and a real model streams into the page. Two steps, deliberately: no
comparable scaffolder starts a server for you, and the epic's proof is worded to match.
This issue is the greenfield path in every part. There is no
fsdev init— FIX-1159 shipsneither the command nor a library behind it — so alongside the template this package also does the
API key, the ignore entry, the agent-instructions section, the install, and the printed next-steps
block. What stays elsewhere is authorship of two blocks of text, embedded here verbatim.
Steps 3–4 are every deterministic write; 5 and 6 are the two whose failure is recoverable. That
order is why §9 can promise a failed install leaves a project the printed recovery actually
completes. Steps 2 and 4 can fail too and neither is recoverable — both stop the run.
Status
The spec is complete and closed. Epic §5 Q6 is answered — one starter, the Next.js chat app.
The remaining open item is epic §5 Q7 (what the unauthenticated-demo rail should do), which is
the owner's and blocks no part of this document; nothing here anticipates its answer.
Parts worth reviewing closely
§6 decision 3 — the five jobs, and why there is no elsewhere to send them. FIX-1159's
Non-goals disclaim the API key, the ignore entry, the agent-instructions section, the install and
the printed block by handing them here; this spec's Non-goals disclaimed the same five by handing
them back. They were owned by nobody, and so was the epic's greenfield proof. Decision 3 takes
them and prices it: the seam is gone, Size moves Small → Medium, and "byte-identical to a
standalone init run" becomes normalized equality against canonical text.
§12 — the FIX-1160 edge, which this spec did not carry at all. Epic theme 9 (c) and FIX-1160
§7 both state it from their own side. An edge asserted in two documents and enforced by neither
does not exist: built from this spec as it stood, the package would have embedded nothing and
merged before its content had an author. Now recorded, and wired in Linear (it was
related, notblocks). Sub-PRalikewise listed no prerequisites while embedding two other issues' canonicaltext; it now names both.
§12 — the wiring contract is five items, not three. This spec said three and omitted how
the provider is wired and the runtime floor. The omission was not cosmetic: the first is
precisely what decision 5 then specified the opposite of.
§6 decision 5 is reversed, mechanism and argument both. It specified
models: { default, intents, providerPreference }and explicitly rejected a concrete provider/model string; thewiring contract requires a statically imported provider passed as a pre-built
modelResolver,no intents. The old rationale is not weakened but void —
providerPreferenceonly reordersintent candidates, and there are none — which is why it is restated as a changed decision rather
than edited.
§6 decision 8 — what the generated app actually does, stated as description rather than
promise. Four successive product statements about this were false, each derived from our own
rules rather than measured. A POC then ran the real code: the guard keys on bind address not
environment, enforces whole-app not per-flow, refuses a correctly-authenticated app as a false
positive, and is not on this template's path at all — the symbol appears only under
packages/node/andpackages/cli/src/commands/serve.ts, never inpackages/next. So there isno promise here any more, only §12's description:
npm run devbinds127.0.0.1. The app is reachable from that machine andnowhere else, because we set that default in a script we authored.
npm run build && npm startbinds wherever Next binds —0.0.0.0bydefault — because we changed nothing about
scripts.start. Nothing of ours narrows it andnothing of ours refuses a request.
caller-supplied
body.userId. So a deployed generated app is an endpoint that runs modelcalls for anyone who finds it, billed to the developer's provider key, with no tenant
boundary — and
git check-ignorekeeps the key out of version control, which is a differentproblem from keeping it out of a stranger's requests.
AGENTS.mdsectionexists to teach. Until Q7 answers, nothing in the generated project does it for them, and this
spec does not claim otherwise.
This replaces a statement that said the app "does not serve off-host until authentication is
configured — on every path the template ships and every mainstream deploy." That was false: a
hardcoded loopback bind in a
package.jsonscript is not in a platform deploy's path, and thescripts.startnarrowing it assumed has since been withdrawn as actively harmful — Next's-Hcarries no environment binding, so a container binds loopback, health checks never connect, and
the app reads as dead.
§12 — the two demo flows are different artifacts, and the asymmetry is a rule. This template
writes
src/flows/chat/flow.tswith no credential; FIX-1159's brownfield skill writesflows/hello/flow.mtswith one. Epic theme 8's matrix is the statement of record: a path getsthe bind when we author the command that starts the server, and the credential when the
demo ships no browser client to leak it. This template authors
scripts.devand ships a chatpage — first control, not the second.
§7's dependency set is derived, and step 6 is what writes it.
createFlowStateandcreateFilesystemStorescome from@flow-state-dev/engine, which the set omitted; npm hoistsit and pnpm does not, so every install-backed proof was green on a manifest whose config could
not resolve its first call.
@flow-state-dev/devtoolwas also missing and fails on everymanager. Then the list itself turned out to be inert — no step wrote it. Dependencies are now
pinned from a per-package version map, because
.changeset/config.jsondeclares"fixed": []and
"linked": [], so one shared placeholder would request a version that does not exist for atleast one package.
zodis pinned to a Zod 3 range:packages/coredepends onzod ^3.25.76and types its public block surface as v3
ZodTypeAny, so a floatingzodresolving to v4 failsnext buildbefore the app reaches a model.§10 — checks are asserted on outcomes, not incantations. Pinning is asserted on the written
manifest, since
npm install pkg@1.2.3persists^1.2.3without--save-exact. Everyinstalling check runs under pnpm; the headline goal check stays npm because that is the
advertised UX, and the pnpm run beside it is what makes that one trustworthy. The goal check runs
interactively —
-ysuppresses the key prompt and there is no key flag, so the-yformcould never have produced the streamed response §10 requires.
§13 — four implementer notes, and the failure mode this document actually had. The notes cover
the version map versus a fixed release group, asserting pinning on the manifest, the standing
prohibition on building a production refusal before Q7, and the probe's environment-dependent
evidence. They sit under a note about the pattern: a requirement recorded in one section and
enforced by no other — and its mirror, a promise withdrawn in one section and still made in
another. Four of five withdrawal residuals were a table row, not a sentence, because a row
states a claim as a compressed fact in a section organised by a different question, so a search
for the withdrawn wording never finds it. When you withdraw a claim, walk the tables by reading
the rows.
Links
Linear FIX-548 ·
epic FIX-1161 ·
blockers #1310 (FIX-1159) and
#1311 (FIX-1160) ·
spec:
spec/FIX-548.md·POC:
spec-poc/FIX-548-next-template-shape/One open cross-issue correction — the only item where building as-written produces a wrong artifact
The withdrawn security promise still lives in FIX-1159's canonical next-steps block, which this
package embeds verbatim under a normalized-equality assertion. The text tells the user the app
"will not serve in production until you configure authentication." Both halves are false.
If it is not corrected in canonical before this issue builds, the scaffolder re-ships a false
security claim to every user, and the equality check actively prevents the shipper from correcting
it — the mechanism built to stop drift would pin the false claim in place. This cannot be closed
from FIX-548's side by construction; it is routed to FIX-1159 as a required correction.
Review history — what the rounds folded, and the pattern in them
The pinning fix had three defects of its own, one a build break:
zodwas left deliberatelyfloating while the FSD packages were pinned, which aimed the remaining risk at the one type boundary
the generated flow crosses on every run; one placeholder was used for six independently released
packages; and
add pkg@1.2.3was assumed to persist an exact entry, which it does not.Before that: the
scripts.startnarrowing and the production refusal were withdrawn after therail was measured, and the withdrawal had to be chased through decision 8, a change table, the file
table, §8, §10, a §12 premise, a follow-up, §9's deployment row, and the printed success
transcript. The dependency set was listed with no step that wrote it. Sub-PR
alisted noprerequisites. A cross-reference pointed at a §12 that did not contain the thing it named. The
AGENTS.mdappend ran after the install, so a failed install left a project the printed recoverycould not complete — then, once reordered, was allowed to fail and continue, which falsified the
same promises again. The goal check specified
-y, which suppresses the key prompt the same runneeded answered — a check that could not pass, the mirror of the class that dominated every
other round.
Every finding against the POC has been one defect class: a check whose result does not correspond
to the claim it is cited for — in three directions. Cannot fail: a marker count surviving a
truncated section; a green npm install hiding a missing
@flow-state-dev/engine; an orderingassertion staying green when the step it ordered ran and failed. Cannot pass: the
-ygoal check.Fails for the wrong reason:
git init's discarded exit status, and inheritedNODE_NO_WARNINGSsuppressing the very diagnostic a check reads — both reporting a true claim as disproved,
which is the direction that teaches people to stop believing red results.
probe.shis frozen — and the freeze was lifted exactly twice, both under the same standingclause: a finding that the script reports a true claim as disproved is fixed in the script;
everything else is narrowed in the README. The rule covers over-assertion, and both of those were
under-reporting in the one direction that cannot be documented away.
For automated reviewers — what this PR is and how to review it
This is a spec PR. It carries one Markdown file under
spec/(plus a throwaway POC underspec-poc/, which CI ignores) and is never merged — it closes unmerged once the spec isapproved, and the branch is kept so the reviewed copy stays fetchable (BP-037). There is no
production code to review.
This spec is approved and closed. Findings that would change the approach are no longer being
folded; genuine issues belong in §13 as implementer notes.
Review the direction, not the prose:
being wrong stated?
check them.
were requirements stated in one section and enforced by no step, test, or tracker edge — and
promises withdrawn in one section and still made in another. §13 opens with that pattern.
The bar: a spec is approved when it is directionally correct, not when nothing is left to
nitpick (BP-040).
probe.shis frozen — findings against the POC are answered by narrowing a README claim to whatthe frozen script proves, not by changing the script. The one exception, and the reasoning for it,
is recorded in the POC README: a finding that the script reports a true claim as disproved is
fixed in the script.