From 0a031eb7f25fe2f6f629d980568a9e10c782fdcc Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 15 Aug 2026 12:52:11 +0000 Subject: [PATCH 01/30] =?UTF-8?q?spec(FIX-548):=20`create-fsd-app`=20?= =?UTF-8?q?=E2=80=94=20npx-able=20scaffolding=20for=20new=20FSD=20projects?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 487 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 487 insertions(+) create mode 100644 spec/FIX-548.md diff --git a/spec/FIX-548.md b/spec/FIX-548.md new file mode 100644 index 0000000000..3acce27566 --- /dev/null +++ b/spec/FIX-548.md @@ -0,0 +1,487 @@ +# FIX-548: `create-fsd-app` — npx-able scaffolding for new FSD projects — Implementation Spec + +## Part I — The Case *(for the human)* + +### 1. Problem — why it matters, why now + +Someone who hears about FSD and has no project yet has nowhere to start. `fsdev init` +(FIX-1159) solves the case where a project already exists; it does not create one, and it +deliberately writes no user interface. So the empty-directory path today is: create an app with +somebody else's tool, run our init, and then write the code that actually calls a flow — three +steps and a blank page at the end of them. + +**Why now** — Public Launch's front door is a single command, and the thing a stranger +judges FSD by in the first five minutes is whether that command ends at something that +*visibly works*. A scaffold that produces correct wiring and a stock "Welcome to Next.js" page +has not shown them anything. + +**The honest size of the gap.** It is one command and one screen, not a workstream. The epic +says so plainly: `create-fsd-app` is the weakest of its three issues, `npx create-next-app && +npx @flow-state-dev/cli init` already reaches the outcome in two commands, and this issue +survives scoped down to a thin wrapper. This spec holds that line, and §6's fourth decision +asks whether one half of it should be cut further. + +*Linear **FIX-548** · Epic **FIX-1161** (`epic/building-with-fsd`, PR +[#1301](https://github.com/fixpoint-labs/flow-state-dev/pull/1301)) · depends on **FIX-1159** +(spec PR [#1310](https://github.com/fixpoint-labs/flow-state-dev/pull/1310)).* + +### 2. Solution in plain terms + +One command that makes a directory, puts a working AI feature in it, and leaves the developer +looking at that feature running in their browser. + +Almost none of the work is ours. The bare app comes from the host framework's own scaffolder; +the wiring, the credentials, the dependencies, the install, and the "what to run next" +instructions all come from `fsdev init`. What this package adds is the two things neither of +those can supply: **the demo flow, and the page that talks to it.** That is the whole product. + +**Philosophy** — tenet 2 (composition over features): this command is a sequence of three +things that already exist, and its value is the ordering, not the parts. Tenet 3 (earn every +addition): every file it writes that init could have written is a file that now has two +owners, which is why the file list is three files long and §6 is mostly about keeping it there. + +### 6. Decisions & rules — the sign-off surface + +1. **`create-fsd-app` calls `fsdev init` as a library, in the same process — not by shelling + out to a second command.** + *Rejected:* running `npx @flow-state-dev/cli init` as a subprocess, which is how a + scaffolder normally chains tools. + *Locks in:* the developer answers each question once. A subprocess cannot be handed the + provider and key the wrapper just collected, so it asks for them again — being asked for + your API key twice by one command is the kind of first-hour detail people quietly conclude + things from. It also pins the wrapper to the exact init it was tested against instead of + whatever `npx` resolves that day, and it makes the shared next-steps block shared by + construction rather than by agreement. **The cost is a constraint on an issue currently in + spec review**: four things that would otherwise be internal to init become its public + surface (see §7). That note goes on PR #1310, and this spec cannot be built until it is + accepted there. + +2. **The Next.js app comes from `create-next-app`, run with installation skipped. We do not + maintain a Next.js skeleton.** + *Rejected:* bundling our own minimal Next.js app in the package, which is what this issue's + original body proposed and what `create-vite` and `create-remix` do. + *Locks in:* we never own the aging half of a Next.js app — the framework version, the + TypeScript and lint configuration, the App Router conventions that shift between releases. + A developer gets whatever Next.js currently considers correct, on the day they run it. + Skipping that scaffolder's install matters as much as using it: the project then installs + exactly once, when init installs, instead of twice with the second run rewriting the + lockfile the first just wrote. **The cost is a real dependency on someone else's flag + surface** — when `create-next-app` changes its flags, our most important command breaks. It + breaks loudly and in public, which is the redeeming feature; we pin a tested major range + and treat it as a patch-level fix. + +3. **v1 publishes under the scoped name we already own, `@flow-state-dev/create-fsd-app`. The + unscoped `create-fsd-app` becomes an alias if and when FIX-1162 secures it.** + *Rejected:* waiting for the short name before this spec commits to a headline command, + which is what the epic's running index currently assumes. + *Locks in:* this issue stops being blocked by a credential task nothing in the epic holds — + the same move FIX-1159 made for the same reason, so both entry paths are unblocked by the + same reasoning rather than one of them waiting on registration. The cost is that v1's + documented command is `npx @flow-state-dev/create-fsd-app my-app`, which is longer than the + one the epic's transcripts show. Cheap to revise: adding the alias later changes the docs + and a package name, not any code this spec describes. + +4. **Ship the Next.js chat template in v1. Do not ship the Node API template.** + *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 + `node-api` later breaks no existing invocation. + +5. **The demo chat page adds no user-interface dependencies. One file, `@flow-state-dev/react`, + and nothing else.** + *Rejected:* porting `examples/hello-chat`'s page, which is the obvious source and brings a + component library, an icon set, and a session sidebar with it. + *Locks in:* the template's dependency list is exactly init's, so what gets installed is + explainable in one sentence, and the first FSD code a newcomer reads is one file they can + follow top to bottom. The cost is that the generated app looks plainer than our own example + app — which is the right trade for a file whose job is to be read, not admired. + +**Non-goals** — anything `fsdev init` does (detection, config, host wiring, credentials, +dependency installation, the next-steps block: all FIX-1159's, and none of it exists twice +here), the content of the agent-instructions file (FIX-1160), an `--upgrade` mode that +regenerates config in an existing project (the issue body already recommends against it; it is +a different tool), and any template beyond the one decision 4 settles. + +**Size:** Small — 3 authored demo files · 1 package entry · ~9 test behaviours · 3 doc +surfaces · 2 PRs. *Deliberately small: if this grows scaffolding logic that `fsdev init` does +not have, epic theme 1 says that is the signal it should have been dropped.* + +--- + +#### The ask — does the Node API template ship? + +**The fork.** Ship one starter template (a Next.js chat app), or two (that, plus a +framework-neutral Node API)? + +**Plain terms.** A template is the working project someone gets from our one command. The +Next.js one ends at a chat page they can type into. The Node one ends at a server with no +screen — you prove it works by making a request to it. + +**What changed since the epic decided two.** FIX-1159 settled two things that hollowed the Node +template out. It generates no server file for non-Next projects (FSD runs there as a second +process started by our own tooling), and it adds no scripts to the project's manifest. So +everything the Node template would ship is now: a `package.json`, a `tsconfig.json`, and a demo +flow with a better name than the one init writes anyway. Init does the rest — and FIX-1159's +own goal check already runs that exact path, on a real machine, with a real model, into a real +Node project. The Next.js template is not in the same position: a chat page is a genuine thing +only this package can produce, because init is forbidden from writing one. + +**The trade-off.** Two templates cost a second recorded goal check on machines we do not +control, on every release, forever — the epic named that as an accepted cost when the Node +template still carried a server file. One template costs backend-first developers a starter +with their name on it; they get `npm init -y` and then our init command, which is two commands +instead of one and gives them the same files. + +**My recommendation: ship one.** The Node template's entire remaining delta is two files that +`npm init -y` writes, and the epic's own tripwire points the same way — a wrapper that adds +nothing init does not have is a wrapper that should be smaller. + +**What would change my mind:** if the launch plan points backend developers at a Node starter +*by name* — in a landing page, a comparison table, an announcement. A template that exists to +be linked to is worth more than the files it writes, and that is a business fact I do not have. + +**What being wrong costs.** Wrong on shipping one: we add `node-api` in a later release; the +`--template` flag is already there, no existing command changes, and nobody is stranded — the +two-command path works the whole time. Wrong on shipping two: a starter we keep permanently +green and prove on every release, for a path init already proves, and a slower release loop +for as long as it lives. + +**Whose call.** This reverses epic theme 2, so it belongs to the epic's owner rather than to +this spec. Noted on epic PR #1301 as well. The spec is written so either answer is cheap: the +per-template seam in §7 exists regardless, and only whether `node-api` ships in v1 changes. + +--- + +### 3. Tradeoffs & alternatives + +**Alternative: drop this issue entirely.** It has to be on the list, because the epic itself +raises it — `npx create-next-app && npx @flow-state-dev/cli init` reaches the outcome in two +commands, and FIX-1162 will remove the other half of the argument by securing a short name a +stranger can type. What keeps the issue alive is decision 5's file: **init cannot write a chat +page**, because epic theme 6 forbids it from overwriting `app/page.tsx`, and without one the +two-command path ends on Next.js's stock welcome screen. The command saved is worth little; the +screen at the end of it is the deliverable. + +**Alternative: the wrapper writes the config and the wiring itself**, and calls init only for +dependencies. This is the version that would let this package ship before FIX-1159, which is +tempting given the dependency. Rejected because it is exactly the duplication epic theme 1 +names as the tripwire: two things generating `fsdev.config.ts` disagree the first time one of +them changes, and the disagreement surfaces in a stranger's project rather than in our tests. + +**Alternative: bundle the templates and fetch nothing** (the issue body's pattern audit, which +recommended it). Half-adopted. The demo content is bundled — it is ours and it is three files. +The *app* is not, because a bundled Next.js app is a second Next.js app for us to keep current, +and we already keep two in this repo. + +**Where the complexity is:** not in any file this package writes. It is in the **handoff to +init** — ordering the demo content before init runs so init never authors a competing flow, +carrying the collected answers across so nothing is asked twice, and making sure the one +install that happens is init's. Everything else here is a file copy. + +### 4. Focus practices (1–5) + +1. **Tenet 3 (earn every addition)** — the file list is the spec. Three authored files for the + Next.js template (a flow, a page, and whatever the flow imports). A fourth file is a design + review, not an implementation detail. +2. **Tenet 2 (composition over features)** — every capability this command appears to have + belongs to something else. The test for a new code path here is: *could init do this?* If + yes, it goes there. +3. **Tenet 7 (prove the goal, not the mock)** — the goal check runs the published invocation in + an empty directory with **no provider key in the environment**, and ends at a streamed + response rendered in the browser. A test that stubs `create-next-app` and stubs init proves + the ordering and nothing about the product. +4. **BP-035 (second-path checklist)** — the second path here is **failure after a partial + scaffold**. `create-next-app` failing, or init failing after it succeeded, both leave a real + directory on someone's disk; §9 says what each one prints and neither rolls back. + +### 5. What using it looks like (1–5 examples) + +**The whole product** *(what this spec proposes; no such command exists today)*: + +``` +$ npx @flow-state-dev/create-fsd-app@latest my-app + +? Project name › my-app +? Model provider › OpenAI +? OPENAI_API_KEY › sk-•••••••• + + Creating my-app with create-next-app … + Adding the demo flow and chat page … + Running fsdev init … + + Created app/api/flows/[...path]/route.ts + app/api/flows/route.ts + fsdev.config.ts + AGENTS.md + Wrote .env.local (OPENAI_API_KEY) .gitignore (FSD ignore entries) + Added flows/chat/flow.ts app/page.tsx the template's demo content + Installed via npm + + Next steps + + 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"}' + + Storage is on-disk for development. Pick a real store before you deploy. + AGENTS.md tells your coding assistant how to write FSD flows. +``` + +Everything from `Created` down is **init's output, printed by init** (epic theme 5). The three +lines above it are this package's. + +**Non-interactively**, which is how it runs in the goal check and in CI: + +``` +$ npx @flow-state-dev/create-fsd-app my-app --provider openai --package-manager pnpm -y +``` + +**When the directory is already taken** — the refusal happens before anything is created: + +``` +$ npx @flow-state-dev/create-fsd-app my-app + ✗ ./my-app already exists and is not empty. Pick another name or remove it. +``` + +## Part II — The Build Plan *(for the implementing agent)* + +### 7. Technical design + +A new published package, `packages/create-fsd-app/`, whose entry point is a four-step pipeline. +It has no runtime dependency on this monorepo beyond the published `@flow-state-dev/cli` it +imports, and nothing it writes into the generated project imports anything of ours that is not +on npm (epic theme 4). + +```mermaid +flowchart TB + A[resolve invocation
name · template · provider · key · package manager] --> B[create the bare app
create-next-app, install skipped] + B --> C[write demo content
flows/chat/flow.ts · app/page.tsx] + C --> D[call fsdev init as a library
answers passed in · flow already supplied] + D --> E[init installs once
and prints the next-steps block] +``` + +**Step 1 — resolve the invocation.** Flags first, prompts for whatever is missing, `-y` to take +defaults for everything unflagged. Validation (project name is a legal npm package name, target +directory absent or empty, template is one that exists) happens **here**, before any directory +is created, so a refusal never leaves debris. The package manager is detected from +`npm_config_user_agent` and passed on to both later steps, so exactly one manager owns the +lockfile. + +**Step 2 — create the bare app.** Spawn `create-next-app` with explicit non-interactive flags +and installation skipped. Its own prompts must all be answered by flags; an unanswered one hangs +the command, which is the failure mode that makes this step worth a test on the argv it builds. + +**Step 3 — write demo content.** Three files, and this is the entire product surface: + +| 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 | +| `app/page.tsx` | the chat page. `FlowProvider` + `useFlow` + `useSession` + `ItemsRenderer` from `@flow-state-dev/react`, no other imports (decision 5). Overwrites `create-next-app`'s stock page — permitted, because this is a greenfield directory this package created; epic theme 6 binds init, not the wrapper | +| `.env.local` *(not written here)* | listed to be explicit: init writes it. So does the config, the routes, the ignore entries, and the agent-instructions file | + +**Step 4 — hand off to init.** The load-bearing step. What crosses the seam: + +| passed in | why it cannot be skipped | +|---|---| +| the target directory | init otherwise runs against the cwd, which is the parent | +| 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) | + +**This is a constraint on FIX-1159, and it is this spec's only cross-issue ask.** All four rows +are satisfied by one change of shape: *init is a library, and the CLI command is a thin caller +of it.* Note that PR #1310 carries a reviewer note calling the reusable next-steps module +premature — "authoring a reusable next-steps module for FIX-548 before that issue exists". That +issue now exists, needs three more things from the same seam, and cannot be built without it; +the note is answered by this spec rather than by an argument. + +**Ordering, and why it is not incidental.** Demo content is written *before* init runs, so +init's config generation sees the flow that will actually be there. Reverse the two and init +authors `hello`, and every way out of that is a file operation on something init just wrote. +And `create-next-app` must skip its install, or the project installs twice and the second +install rewrites a lockfile the first one wrote. + +**Untouched:** the engine, the adapters, the CLI's existing commands, every block kind. This +package generates a project; it changes no framework behaviour. + +### 8. Implementation sequence + +1. **The package skeleton and its invocation surface** — flags, prompts, `-y`, package-manager + detection, and all of §9's validation refusals. + *Test:* every refusal in §9's first block, and that each refusal happens before any directory + is created. *Depends on:* nothing. +2. **The bare-app step** — spawn `create-next-app` with install skipped, surface its failure. + *Test:* the argv built (flags complete enough that nothing prompts; install skipped), and the + failure path's output. *Depends on:* 1. +3. **The demo content** — the flow and the chat page. + *Test:* the generated flow type-checks and its action runs against a stubbed model; the page + compiles. *Depends on:* nothing. +4. **The init handoff** — call init with the collected answers and the supplied flow, print what + it returns. *Test:* the call ordering (content before init), the arguments crossing the seam, + and that the printed block matches a standalone init run. + *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. + +| sub-PR | deliverables | depends_on | +|---|---|---| +| 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 | + +### 9. Edge cases & error handling + +**Refusals — before anything is created:** + +| Case | Expected | +|---|---| +| 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. | +| `--template` names one that does not exist | Refuse and list the ones that do. | +| Node runtime below the CLI's declared floor | Refuse, with the same floor and the same message init uses. The wrapper's engines range matches the CLI's, so this is caught at install where possible. | + +**Failures after work has started — nothing rolls back:** + +| Case | Expected | +|---|---| +| `create-next-app` fails or is unreachable | Report its output, name the directory as it stands, and print the two commands that finish the job by hand. Do not delete it. | +| Init fails after the app was created | The scaffold stays. Print init's own retry command against that directory. Mirrors init's install-failure taxonomy, which also leaves files and prints the retry. | +| Install fails inside init | Init's case, not this one. It reports and this command adds nothing. | +| `-y` with no key in flags or environment | Scaffold completes. `.env.local` carries the empty key line init writes, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is a legitimate use. | + +**Taxonomy:** the refusals leave the disk untouched; the failures leave a directory the +developer can inspect and finish by hand. There is no partial state this command cleans up +behind the user, because deleting a directory a stranger may have put something in is worse +than leaving one they can `rm`. + +### 10. Testing strategy + +**Goal & goal check** (the epic's proof for this issue). One recorded run under +`goals/create-fsd-app/` — or two, if decision 4 is overturned: + +- In an **empty directory, with no provider key in the environment**, run the published + invocation, supply the key at its prompt, then run the printed dev command and send a message + in the browser: a streamed model response renders in the page. +- The key is deliberately *not* pre-exported. The epic's original wording for this check + supplied it in the environment, and PR #1301's review note 8 called that out: pre-supplying it + skips the credential path entirely, so the check would pass while a real user's first command + failed. FIX-1159's goal checks were corrected the same way. +- **The bare `/api/flows` is exercised by construction here**, because the page's + `FlowProvider` calls `listFlows()` against it. That is worth stating rather than leaving + implicit: if that route is wrong the page is simply dead, with nothing in it pointing at a + route file. + +**CI specs** (the behaviours, not the test names) — all against a stubbed `create-next-app` and +a stubbed init, in a temporary directory, with no network and no install: + +- one behaviour per decision in §6 +- **demo content is written before init is called** — asserted on the call ordering, not the end + state, because a wrapper that wrote content afterwards and deleted init's flow would leave an + identical directory +- **the collected provider and key reach init** — asserted on the call, so a regression shows up + as a failing test rather than as a second prompt in someone's terminal +- **`create-next-app` is invoked with install skipped** — asserted on the argv, since the + symptom otherwise is only "the first hour is slower" +- **the argv answers every prompt `create-next-app` would ask** — an unanswered one hangs +- **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5) — + asserted, because "reused verbatim" is a promise that decays silently +- every refusal in §9's first block, each asserting nothing was created +- `-y` with no key: scaffold completes and the output says the key is missing + +**Where each lives.** The goal check is a real-machine run under `goals/create-fsd-app/` — real +network, real `create-next-app`, real model, real browser — and is never part of the vitest +suite. Everything in the CI list runs in a temp directory against stubs. Both halves are needed +and neither substitutes for the other: the stubs prove the ordering and the seam, and only the +real run proves the product. + +**Discipline:** `tdd`. The seam is the pipeline against a temporary directory with the two +subprocesses stubbed; every CI behaviour above is reachable from a vitest spec. + +### 11. Documentation plan + +- **EXTEND** `apps/docs/docs/getting-started/quick-start.md` — lead with this command for + someone starting fresh, and point across to init's `existing-project.md` page (created by + FIX-1159) for someone who already has a project. One example: the command and what they see + when it finishes. + *Voice risks:* a scaffolding command attracts "instantly", "zero-config", and "just works" — + none of them. Say what it creates and what it does not (decision 4's boundary, and that the + development store is not a deployment store). +- **CREATE** `packages/create-fsd-app/README.md` — the npm landing page. Install snippet, the + flag table, what the generated project contains, and a link to the docs site. Must render + correctly on npmjs.com. +- **EXTEND** the root `README.md` — the quick-start section. **FIX-1159 also edits this + section** (it leads with init for existing projects) and lands first, so this issue edits the + version FIX-1159 leaves rather than the one on `main` today. Worth checking at implementation + time rather than assuming. +- **No blog post.** This ships as part of Public Launch; the announcement is that project's. +- **A changeset is required** (BP-022) — a new published package is as user-facing as it gets. + +### 12. Dependencies, open questions & follow-ups + +**Dependencies — two, and one of them is hard.** + +- **FIX-1159 (`fsdev init`) blocks implementation, not specification.** The two specs are being + written in parallel, as the epic intends, but this package cannot be built until init's + library seam exists and cannot merge before init merges (epic theme 1). §7's four-row table + is the exact interface required; it is going on PR #1310 while that spec is still in review, + which is the cheap moment to place it. +- **FIX-1162 (npm names) does not block this issue** — decision 3 removes it, publishing under + the scope we already own. The epic's running index currently shows FIX-548 as blocked by + FIX-1162; that row is stale once this spec is approved. + +**Open questions:** one, and it is §6's decision 4 — does the Node API template ship? It is +raised as a decision with a recommendation rather than left open, because leaving it open would +block a spec on a question the spec itself can answer either way. The answer changes what §7 +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 +re-derive them): + +- `packages/cli` has no `init` command today (`src/commands/` holds `run`, `dev`, `serve`, + `chat`, `block`, `ui`, `benchmark`), and its exports are `main`/`exports` on `src/index.ts` — + so exposing init as a library is an addition to that surface, not a change to it. +- The generated config **registers flows explicitly**: `loadFsdevConfig` imports a module that + default-exports the `createFlowState({ flows, stores })` handle, and config search is + **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. +- FIX-1159 settled that a non-Next project gets **no generated server file** (decision 1) and + **no package script** (decision 3). Both are why §6's decision 4 reads differently than epic + theme 2 did — the Node template's contents were mostly those two things. +- The three PR #1301 review notes about a generated Node entrypoint (unauthenticated bind on + all interfaces, `.env.local` never loaded, and preferring the existing `fsdev serve`) are + **all resolved upstream by that decision** — there is no generated entrypoint left to get + wrong. They are recorded here so a reviewer does not re-raise them against this spec. +- The two PR #1301 review notes about missing dependencies — the provider SDK (`@ai-sdk/openai` + is a dev dependency of `core` and never reaches a consumer) and `@flow-state-dev/devtool` (an + optional peer of the CLI, satisfied only inside this monorepo) — are **resolved by init's + install step**, which installs both. This package inherits that and adds nothing. +- `examples/hello-chat` is the shape reference for the demo flow and page, not the content + reference: its page pulls in a component library, an icon set, and a session sidebar + (`components/ui/*`, `lucide-react`), which decision 5 declines. + +**Follow-ups (flagged, not built):** + +- **The `node-api` template**, if decision 4 goes the other way later. Additive — the + `--template` flag ships with the seam in place. +- **The unscoped package name as an alias**, once FIX-1162 secures it (decision 3). + +### 13. Review notes for the implementer + +*Below-the-bar spec-PR feedback lands here verbatim once review runs. Empty at drafting.* + +--- + +## Spec evolution + +- **Spec drafted** — scoped to the two things neither `create-next-app` nor `fsdev init` can + produce (a demo flow and the page that talks to it), and everything else delegated. Settled + the init handoff as a library call rather than a subprocess, because a subprocess cannot be + handed the answers already collected and would ask for the API key twice. Declined to + maintain a Next.js skeleton. Unblocked the issue from FIX-1162 by publishing under the scope + we already own, mirroring FIX-1159's reasoning. Raised the Node API template as the spec's + one ask: FIX-1159's decisions to generate no server file and add no package script removed + almost everything that template would have contained. From 3118cce03892f73ec63c0c063c72eb2176b3a7da Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 00:19:53 +0000 Subject: [PATCH 02/30] =?UTF-8?q?spec(FIX-548):=20re-draft=20=E2=80=94=20`?= =?UTF-8?q?create-flow-state`,=20one=20template,=20owns=20it=20end=20to=20?= =?UTF-8?q?end?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 47 ++ spec-poc/FIX-548-next-template-shape/probe.sh | 112 +++ spec/FIX-548.md | 791 +++++++++++------- 3 files changed, 625 insertions(+), 325 deletions(-) create mode 100644 spec-poc/FIX-548-next-template-shape/README.md create mode 100644 spec-poc/FIX-548-next-template-shape/probe.sh diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md new file mode 100644 index 0000000000..349eb04bc8 --- /dev/null +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -0,0 +1,47 @@ +# POC — what shape does the Next.js template actually have to be? + +Throwaway. Lives on the spec branch, never merges, CI ignores `spec-poc/`. + +FIX-548's template has to satisfy two consumers of the same config file at once: the **Next.js +bundler** (the mounted route imports it) and the **`fsdev` CLI** (a native `import()` loads it). +FIX-1159 decision 4 settles the CLI half by using `.mts`. Nobody had checked the bundler half, +and the whole product — a streamed response rendered in a browser — runs through it. + +Run it: `bash probe.sh` (needs network; ~2 minutes). It scaffolds a real `create-next-app@16` +project, drops each candidate config shape in, and runs `next build`, `next dev`, and a native +`import()` against each. + +## What it settled + +| Variant | `next build` | native `import()` | verdict | +|---|---|---|---| +| `fsdev.config.mts`, imported as `../fsdev.config.mts` | Turbopack compiles; **TypeScript fails** — `TS5097: An import path can only end with a '.mts' extension when 'allowImportingTsExtensions' is enabled` | clean | needs a `tsconfig.json` edit | +| `fsdev.config.mts`, imported as `../fsdev.config` | **module not found** — Turbopack does not resolve extensionless to `.mts` | clean | dead | +| `fsdev.config.mts` + `allowImportingTsExtensions: true` | passes | clean | works, costs two edits to files `create-next-app` wrote | +| **`fsdev.config.ts` + `"type": "module"` in the manifest** | **passes** | **clean, no warning** | **chosen (§6 decision 4)** | +| `fsdev.config.ts`, no `type` field | passes | loads, but emits `MODULE_TYPELESS_PACKAGE_JSON` on every CLI command | rejected | + +The chosen variant was also run end to end: `next dev` served `GET /api/flows`, and the route +returned the marker proving the config module was the one that loaded. + +## Four things it found that nothing in the epic or the sibling specs knew + +1. **`create-next-app@16` writes `AGENTS.md` itself**, with its own delimited block + (``), and **`next dev` re-adds that block on every run**. So + the greenfield Next path is an *append* to an existing `AGENTS.md`, never a create — the case + everyone assumed was brownfield-only. An appended FSD section survived a `next dev` run intact. +2. **`create-next-app@16` also writes `CLAUDE.md`.** +3. **Its `.gitignore` already contains `.env*`**, so the credential-ignore entry the template + depends on is supplied by the host scaffold — a fact to *assert*, not to assume, because it is + someone else's file. +4. **`--agents-md` defaults on and the tool says so** (`Using defaults for unprovided options`). + `create-next-app` persists saved preferences between runs, so any flag we leave off can resolve + differently on a machine that has run it before. Every flag has to be passed explicitly; + `--yes` is not a substitute. + +## Not settled here + +Whether a provider SDK that `@flow-state-dev/core` imports **dynamically by package name** +resolves inside the Next.js server bundle. `createModelResolver` carries a `directLoadFailed` +fallback for exactly this case, so it is a known hazard. Only a real run with a real key reaches +it — §10's goal check does, through the mounted route rather than through `fsdev run`. diff --git a/spec-poc/FIX-548-next-template-shape/probe.sh b/spec-poc/FIX-548-next-template-shape/probe.sh new file mode 100644 index 0000000000..9f6ccdf83f --- /dev/null +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -0,0 +1,112 @@ +#!/usr/bin/env bash +# Reproduces every row of README.md's table. Needs network. ~2 minutes. +# +# bash probe.sh [workdir] +# +# Scaffolds a real create-next-app@16 project, then for each candidate shape of +# the FSD config runs `next build` (the bundler + TypeScript half) and a native +# `import()` (the fsdev CLI half). Ends with a `next dev` + curl on the chosen +# shape, so the mounted route is proven to serve, not just to compile. +set -u + +WORK="${1:-$(mktemp -d)}" +mkdir -p "$WORK" || exit 1 +APP="$WORK/probe" +rm -rf "$APP" +echo "workdir: $WORK" + +npx --yes create-next-app@16 "$APP" \ + --ts --app --no-tailwind --no-eslint --no-biome --no-src-dir \ + --no-react-compiler --no-rspack --import-alias "@/*" \ + --agents-md --skip-install --disable-git || exit 1 + +cd "$APP" || exit 1 + +echo "=== what create-next-app wrote (findings 1-4) ===" +ls -a | tr '\n' ' '; echo +echo "AGENTS.md delimiters:"; grep -o 'BEGIN:[a-z-]*' AGENTS.md || echo " (none)" +echo ".gitignore env line:"; grep -n '^\.env' .gitignore || echo " (none)" +echo "manifest type field: $(node -p "require('./package.json').type ?? '(absent)'")" +echo "tsconfig include: $(node -p "JSON.stringify(require('./tsconfig.json').include)")" + +mkdir -p lib "app/api/flows" +cat > app/api/flows/route.ts <<'EOF' +import { flowstate } from "@/lib/flowstate"; +export const dynamic = "force-dynamic"; +export async function GET() { + const router = await flowstate.getRouter(); + return new Response(`${flowstate.marker}:${(await router.GET()).status}`); +} +EOF + +# Stands in for createFlowState({ flows, stores }). The question under test is +# module resolution and parsing, not FSD behaviour, so it has no FSD imports. +CONFIG_BODY='const flowstate = { + marker: "config-module-loaded", + async getRouter() { + return { GET: () => new Response("ok") }; + }, +}; +export default flowstate;' + +npm install --no-audit --no-fund || exit 1 + +set_tsconfig_flag() { # $1 = true|false + node -e "const f='tsconfig.json',fs=require('fs');const j=JSON.parse(fs.readFileSync(f,'utf8')); + if ('$1'==='true') j.compilerOptions.allowImportingTsExtensions=true; else delete j.compilerOptions.allowImportingTsExtensions; + fs.writeFileSync(f,JSON.stringify(j,null,2)+'\n')" +} +set_pkg_type() { # $1 = module|none + node -e "const f='package.json',fs=require('fs');const j=JSON.parse(fs.readFileSync(f,'utf8')); + if ('$1'==='module') j.type='module'; else delete j.type; + fs.writeFileSync(f,JSON.stringify(j,null,2)+'\n')" +} +variant() { # $1 = label, $2 = config filename, $3 = import specifier + rm -f fsdev.config.ts fsdev.config.mts + printf '%s\n' "$CONFIG_BODY" > "$2" + printf 'export { default as flowstate } from "%s";\n' "$3" > lib/flowstate.ts + echo + echo "=== variant: $1 ===" + 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 +} + +set_pkg_type none +set_tsconfig_flag false +variant ".mts, explicit .mts extension" fsdev.config.mts "../fsdev.config.mts" +variant ".mts, extensionless import" fsdev.config.mts "../fsdev.config" +set_tsconfig_flag true +variant ".mts + allowImportingTsExtensions" fsdev.config.mts "../fsdev.config.mts" +set_tsconfig_flag false +variant ".ts, no type field" fsdev.config.ts "../fsdev.config" +set_pkg_type module +variant ".ts + type:module <-- CHOSEN" fsdev.config.ts "../fsdev.config" + +echo +echo "=== chosen shape, served for real ===" +# A unique marker per run, on a port proven free first. Without both, this check +# can pass by reaching a stale dev server left over from an earlier run — a green +# result from a neighbour of the claim, which is the failure it exists to catch. +MARKER="served-$$-$(date +%s)" +sed -i "s/config-module-loaded/$MARKER/" fsdev.config.ts +PORT=0 +for p in $(seq 3990 3999); do + if ! (exec 3<>"/dev/tcp/127.0.0.1/$p") 2>/dev/null; then PORT=$p; break; fi +done +if [ "$PORT" = 0 ]; then echo " no free port in 3990-3999 — skipped"; exit 0; fi +echo " port $PORT (verified free)" + +printf '\n\nFSD SECTION SENTINEL\n\n' >> AGENTS.md +npx next dev --port "$PORT" > dev.log 2>&1 & +DEV_PID=$! +sleep 18 +BODY=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows") +echo " GET /api/flows -> $BODY" +case "$BODY" in + "$MARKER":200) echo " PASS — the route served this run's config module" ;; + *) echo " FAIL — expected $MARKER:200" ;; +esac +echo " FSD section survived next dev: $(grep -c 'FSD SECTION SENTINEL' AGENTS.md) (expect 1)" +echo " next's own block still there: $(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md) (expect 1)" +kill "$DEV_PID" 2>/dev/null; wait "$DEV_PID" 2>/dev/null +exit 0 diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 3acce27566..dfec6edfe9 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -1,247 +1,294 @@ -# FIX-548: `create-fsd-app` — npx-able scaffolding for new FSD projects — Implementation Spec +# FIX-548: `create-flow-state` — one command to a working FSD app — Implementation Spec ## Part I — The Case *(for the human)* ### 1. Problem — why it matters, why now -Someone who hears about FSD and has no project yet has nowhere to start. `fsdev init` -(FIX-1159) solves the case where a project already exists; it does not create one, and it -deliberately writes no user interface. So the empty-directory path today is: create an app with -somebody else's tool, run our init, and then write the code that actually calls a flow — three -steps and a blank page at the end of them. +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 — which is the thing the epic exists to stop asking people to do. -**Why now** — Public Launch's front door is a single command, and the thing a stranger -judges FSD by in the first five minutes is whether that command ends at something that -*visibly works*. A scaffold that produces correct wiring and a stock "Welcome to Next.js" page -has not shown them anything. +**Why now** — Public Launch's front door is a single command, and what a stranger judges FSD by +in their first five minutes is whether that command ends at something that *visibly works*. A +scaffold that produces correct wiring and a stock "Welcome to Next.js" page has shown them +nothing. -**The honest size of the gap.** It is one command and one screen, not a workstream. The epic -says so plainly: `create-fsd-app` is the weakest of its three issues, `npx create-next-app && -npx @flow-state-dev/cli init` already reaches the outcome in two commands, and this issue -survives scoped down to a thin wrapper. This spec holds that line, and §6's fourth decision -asks whether one half of it should be cut further. +**The honest size of the gap, restated.** The epic used to call this the weakest of its issues, +because `npx create-next-app && npx @flow-state-dev/cli init` reached the same outcome in two +commands. **That alternative no longer exists** — after the greenfield/brownfield split there is +no deterministic command that wires FSD into a directory somebody else's scaffolder just filled. +This is now the only deterministic path to a running FSD app, and §3 records what is left of the +case against it. *Linear **FIX-548** · Epic **FIX-1161** (`epic/building-with-fsd`, PR -[#1301](https://github.com/fixpoint-labs/flow-state-dev/pull/1301)) · depends on **FIX-1159** -(spec PR [#1310](https://github.com/fixpoint-labs/flow-state-dev/pull/1310)).* +[#1301](https://github.com/fixpoint-labs/flow-state-dev/pull/1301)) · spec PR +[#1312](https://github.com/fixpoint-labs/flow-state-dev/pull/1312) · relates to **FIX-1159** +(spec PR [#1310](https://github.com/fixpoint-labs/flow-state-dev/pull/1310), approved) · +Project **Public Launch**.* ### 2. Solution in plain terms -One command that makes a directory, puts a working AI feature in it, and leaves the developer -looking at that feature running in their browser. +`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. -Almost none of the work is ours. The bare app comes from the host framework's own scaffolder; -the wiring, the credentials, the dependencies, the install, and the "what to run next" -instructions all come from `fsdev init`. What this package adds is the two things neither of -those can supply: **the demo flow, and the page that talks to it.** That is the whole product. +Three things happen in order. The bare Next.js app comes from Next's own scaffolder. **Then this +package writes its template** — the config, the route that serves flows, the demo flow, and the +page that talks to it. Then `fsdev init` is called in-process for the parts that must not exist +twice anywhere: the API key, the ignore entry that keeps it out of git, the agent-instructions +section, the dependency install, and the block of next steps that gets printed. -**Philosophy** — tenet 2 (composition over features): this command is a sequence of three -things that already exist, and its value is the ordering, not the parts. Tenet 3 (earn every -addition): every file it writes that init could have written is a file that now has two -owners, which is why the file list is three files long and §6 is mostly about keeping it there. +**This package owns the template end to end** (epic theme 1, re-drafted). That is a change from +this spec's previous draft, which had init generate the config and the host wiring while this +package supplied only demo content. That boundary existed to stop two deterministic writers +duplicating scaffolding logic; after the split there is one, so the line moved. What replaces it +is a **drift** tripwire: the template is the reference shape, checked in as real files, and the +install skill's instructions point at it rather than restating its contents. + +**Philosophy** — tenet 2 (composition over features): the command's value is the ordering of +three things that already exist. Tenet 3 (earn 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 -1. **`create-fsd-app` calls `fsdev init` as a library, in the same process — not by shelling - out to a second command.** - *Rejected:* running `npx @flow-state-dev/cli init` as a subprocess, which is how a - scaffolder normally chains tools. - *Locks in:* the developer answers each question once. A subprocess cannot be handed the - provider and key the wrapper just collected, so it asks for them again — being asked for - your API key twice by one command is the kind of first-hour detail people quietly conclude - things from. It also pins the wrapper to the exact init it was tested against instead of - whatever `npx` resolves that day, and it makes the shared next-steps block shared by - construction rather than by agreement. **The cost is a constraint on an issue currently in - spec review**: four things that would otherwise be internal to init become its public - surface (see §7). That note goes on PR #1310, and this spec cannot be built until it is - accepted there. - -2. **The Next.js app comes from `create-next-app`, run with installation skipped. We do not - maintain a Next.js skeleton.** - *Rejected:* bundling our own minimal Next.js app in the package, which is what this issue's - original body proposed and what `create-vite` and `create-remix` do. - *Locks in:* we never own the aging half of a Next.js app — the framework version, the - TypeScript and lint configuration, the App Router conventions that shift between releases. - A developer gets whatever Next.js currently considers correct, on the day they run it. - Skipping that scaffolder's install matters as much as using it: the project then installs - exactly once, when init installs, instead of twice with the second run rewriting the - lockfile the first just wrote. **The cost is a real dependency on someone else's flag - surface** — when `create-next-app` changes its flags, our most important command breaks. It - breaks loudly and in public, which is the redeeming feature; we pin a tested major range - and treat it as a patch-level fix. - -3. **v1 publishes under the scoped name we already own, `@flow-state-dev/create-fsd-app`. The - unscoped `create-fsd-app` becomes an alias if and when FIX-1162 secures it.** - *Rejected:* waiting for the short name before this spec commits to a headline command, - which is what the epic's running index currently assumes. - *Locks in:* this issue stops being blocked by a credential task nothing in the epic holds — - the same move FIX-1159 made for the same reason, so both entry paths are unblocked by the - same reasoning rather than one of them waiting on registration. The cost is that v1's - documented command is `npx @flow-state-dev/create-fsd-app my-app`, which is longer than the - one the epic's transcripts show. Cheap to revise: adding the alias later changes the docs - and a package name, not any code this spec describes. - -4. **Ship the Next.js chat template in v1. Do not ship the Node API template.** - *This one reverses an epic theme and is the ask on this PR — see the framing below.* +1. **The package is `create-flow-state`, published unscoped.** Invoked as `npm create + flow-state my-app`, or `npx create-flow-state my-app`. + *Rejected:* `create-fsd-app` and `create-fsdev-app` (both considered by FIX-1162), and + publishing under the `@flow-state-dev/` scope as this spec's previous draft proposed. + *Locks in:* the headline command matches the published brand and reads as a sentence. The + owner holds `create-flow-state`, `create-fsd-app` and `flow-state-app` on npm as of today, so + **FIX-1162 no longer gates this issue by any route** — not just the one the previous draft + worked around. It also makes FIX-1162's recorded finding stale: `create-fsd-app` was reported + unobtainable and it is now ours, so the epic's `create-fsdev-app` prose and FIX-1162's own + proposal both need correcting (§12). + +2. **One template ships: the Next.js chat app. The framework-neutral Node API template is cut + from v1.** *This reverses epic theme 2 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 - `node-api` later breaks no existing invocation. - -5. **The demo chat page adds no user-interface dependencies. One file, `@flow-state-dev/react`, + *Locks in:* one starter to keep green on machines we do not control, and one recorded goal + run per release rather than two. + + 2b. **No `--template` flag in v1.** *Rejected:* shipping the flag with one legal value to + signal the plan. A flag whose only argument was a template decision 2 just cut is surface + that documents an intention and does nothing else; someone who types `--template node-api` + gets a refusal listing a single value, which reads worse than no such flag. The seam that + makes a second template cheap is the `templates//` directory in §7, not the flag — + and adding a flag nobody could have been passing breaks no invocation. If decision 2 is + overturned, the flag arrives with the template it selects between. + +3. **`create-flow-state` writes the whole FSD half of the template as real checked-in files — + config, mount, flow, page — and calls `fsdev init` only for the parts that must not exist + twice.** + *Rejected:* the previous draft's split, where init generated `fsdev.config.*` and the Next + route pair and this package supplied only the demo flow and the page. + *Locks in:* the template is a directory a person can read, diff, and point instructions at, + which is what epic theme 1's drift tripwire needs — a shape assembled at runtime from + `create-next-app` output plus init's generator is not readable anywhere. It also means init's + Next-host branch is no longer on this path (§12 raises that with FIX-1159 rather than + deciding it). The cost is that a config generator now exists in two places and can drift; + the epic accepted exactly that trade when it replaced "no two writers" with "watch for + drift", and §10 spends a CI check on it. + +4. **The template's config is `fsdev.config.ts`, and the template adds `"type": "module"` to the + manifest `create-next-app` just wrote.** Measured, not assumed — see the POC in §7. + *Rejected:* `fsdev.config.mts` (FIX-1159 decision 4), and `.ts` with no `type` field. + *Locks in:* the config loads cleanly in both consumers at once — Turbopack builds it and the + CLI's native `import()` takes it with no warning — and the template matches the extension + every published doc page and both in-repo examples already use. `.mts` costs **two** edits to + files `create-next-app` wrote (`allowImportingTsExtensions` in `tsconfig.json`, plus an + explicit `../fsdev.config.mts` specifier that reads like a typo) because Turbopack does not + resolve extensionless imports to `.mts`; `.ts` with no `type` field prints + `MODULE_TYPELESS_PACKAGE_JSON` on every CLI command a beginner runs. The cost is that we edit + a manifest — see the rule below — and that the generated project is ESM-only, which for a + fresh Next 16 TypeScript app is the default posture anyway. + + *Rule this bends, deliberately:* FIX-1159 decision 3 says the package manager owns + `package.json`. That rule protects a manifest **in a repository we did not create**. Here the + directory is one this command made seconds earlier, no lockfile exists yet, the install has + not run, and we add one key. Dependencies and the lockfile still belong entirely to the + package manager. Stated out loud because a reviewer should see the exception, not find it. + +5. **The demo flow reaches whichever provider the developer has a key for, through an intent — + it never hard-codes one provider's model.** The config declares + `models: { default: , intents: { chat: [anthropic, openai, + google] } }`, and only the chosen provider's `@ai-sdk/*` package is installed. + *Rejected:* a hard-coded `openai/gpt-5.4-mini` in the flow, which is what the reference + example does. + *Locks in:* the prompt offers three providers and all three work, because the resolver picks + the first candidate with both a key and an installed SDK package. A hard-coded model plus an + Anthropic key is a first-run failure with a confusing error, and it is the failure a + three-way prompt makes most likely. + +6. **The demo chat page adds no user-interface dependencies. One file, `@flow-state-dev/react`, and nothing else.** - *Rejected:* porting `examples/hello-chat`'s page, which is the obvious source and brings a - component library, an icon set, and a session sidebar with it. - *Locks in:* the template's dependency list is exactly init's, so what gets installed is - explainable in one sentence, and the first FSD code a newcomer reads is one file they can - follow top to bottom. The cost is that the generated app looks plainer than our own example - app — which is the right trade for a file whose job is to be read, not admired. - -**Non-goals** — anything `fsdev init` does (detection, config, host wiring, credentials, -dependency installation, the next-steps block: all FIX-1159's, and none of it exists twice -here), the content of the agent-instructions file (FIX-1160), an `--upgrade` mode that -regenerates config in an existing project (the issue body already recommends against it; it is -a different tool), and any template beyond the one decision 4 settles. - -**Size:** Small — 3 authored demo files · 1 package entry · ~9 test behaviours · 3 doc -surfaces · 2 PRs. *Deliberately small: if this grows scaffolding logic that `fsdev init` does -not have, epic theme 1 says that is the signal it should have been dropped.* + *Rejected:* porting `examples/hello-chat`'s page, which brings a component library, an icon + set, and a session sidebar. + *Locks in:* what gets installed is explainable in one sentence, and the first FSD code a + newcomer reads is one file they can follow top to bottom. The cost is that the generated app + looks plainer than our own example — the right trade for a file whose job is to be read. + +7. **No path writes the API key before it has proven git will not publish it.** The template's + host scaffold happens to supply the ignore entry (`create-next-app`'s `.gitignore` already + carries `.env*` — verified), so this is an assertion, not a code branch: check, add ours if + absent, and only then let init write the key. + *Rejected:* assuming the entry is there because we saw it once. It is someone else's file. + *Locks in:* the guarantee the epic now states generally — a credential in version control is + the one failure a diff review does not catch, because it looks like every other added line. + §10 asserts it by running `git check-ignore`, not by reading the file. + +**Non-goals** — anything `fsdev init` does for credentials, the agent-instructions section, the +install, and the next-steps block (FIX-1159's, and none of it exists twice here); the *content* +of the agent-instructions file (FIX-1160); the brownfield path in any form; an `--upgrade` mode +that regenerates config in an existing project; and any template beyond the one decision 2 +settles. + +**Size:** Small — 6 template files · 1 package entry · ~10 test behaviours · 3 doc surfaces · +2 PRs. *Deliberately small: if this grows detection or merge logic, epic theme 1 says that is +the signal it belongs in the skill, not here.* --- #### The ask — does the Node API template ship? -**The fork.** Ship one starter template (a Next.js chat app), or two (that, plus a -framework-neutral Node API)? +**The fork.** One starter template (a Next.js chat app), or two (that, plus a framework-neutral +Node API)? **Plain terms.** A template is the working project someone gets from our one command. The Next.js one ends at a chat page they can type into. The Node one ends at a server with no screen — you prove it works by making a request to it. -**What changed since the epic decided two.** FIX-1159 settled two things that hollowed the Node -template out. It generates no server file for non-Next projects (FSD runs there as a second -process started by our own tooling), and it adds no scripts to the project's manifest. So -everything the Node template would ship is now: a `package.json`, a `tsconfig.json`, and a demo -flow with a better name than the one init writes anyway. Init does the rest — and FIX-1159's -own goal check already runs that exact path, on a real machine, with a real model, into a real -Node project. The Next.js template is not in the same position: a chat page is a genuine thing -only this package can produce, because init is forbidden from writing one. - -**The trade-off.** Two templates cost a second recorded goal check on machines we do not -control, on every release, forever — the epic named that as an accepted cost when the Node -template still carried a server file. One template costs backend-first developers a starter -with their name on it; they get `npm init -y` and then our init command, which is two commands -instead of one and gives them the same files. - -**My recommendation: ship one.** The Node template's entire remaining delta is two files that -`npm init -y` writes, and the epic's own tripwire points the same way — a wrapper that adds -nothing init does not have is a wrapper that should be smaller. +**What changed since the epic decided two.** FIX-1159 settled that a plain-Node project gets no +generated server file (FSD runs there as a second process started by our own CLI) and no package +script. So everything a Node template would ship is now a `package.json`, a `tsconfig.json`, and +a demo flow with a better name than the one init writes anyway — and `fsdev init` in an empty +directory already produces that, on a path FIX-1159's own goal check runs with a real model. The +Next.js template is not in that position: the chat page and the mounted route can only come from +here, and they are what turn the ending from a stock welcome screen into something working. + +**The trade-off.** Two templates cost a second recorded goal run, on machines we do not control, +on every release, forever — the epic named that as an accepted cost when the Node template still +carried a server file. One template costs backend-first developers a starter with their name on +it; they get `mkdir my-api && npx @flow-state-dev/cli init`, which is two commands instead of +one and produces the same files. + +**My recommendation: ship one.** The asymmetry is the argument. Adding `node-api` later is +additive — it breaks no invocation and strands nobody, because the two-command path works the +whole time. Removing it later is not. Two independent reviewers reached the same conclusion +before this was folded. **What would change my mind:** if the launch plan points backend developers at a Node starter -*by name* — in a landing page, a comparison table, an announcement. A template that exists to -be linked to is worth more than the files it writes, and that is a business fact I do not have. +*by name* — in a landing page, a comparison table, an announcement. A template that exists to be +linked to is worth more than the files it writes, and that is a business fact I do not have. -**What being wrong costs.** Wrong on shipping one: we add `node-api` in a later release; the -`--template` flag is already there, no existing command changes, and nobody is stranded — the -two-command path works the whole time. Wrong on shipping two: a starter we keep permanently -green and prove on every release, for a path init already proves, and a slower release loop -for as long as it lives. +**What being wrong costs.** Wrong on shipping one: we add `node-api` in a later release and +nobody was blocked meanwhile. Wrong on shipping two: a starter we keep permanently green and +prove on every release, for a path init already proves, and a slower release loop for as long as +it lives. -**Whose call.** This reverses epic theme 2, so it belongs to the epic's owner rather than to -this spec. Noted on epic PR #1301 as well. The spec is written so either answer is cheap: the -per-template seam in §7 exists regardless, and only whether `node-api` ships in v1 changes. +**Whose call.** This reverses epic theme 2, so it belongs to the epic's owner rather than to this +spec. Noted on epic PR #1301 as well. Either answer is cheap here: §7's `templates//` +layout exists regardless, and only whether `node-api` ships in v1 — and with it decision 2b's +flag — changes. --- ### 3. Tradeoffs & alternatives -**Alternative: drop this issue entirely.** It has to be on the list, because the epic itself -raises it — `npx create-next-app && npx @flow-state-dev/cli init` reaches the outcome in two -commands, and FIX-1162 will remove the other half of the argument by securing a short name a -stranger can type. What keeps the issue alive is decision 5's file: **init cannot write a chat -page**, because epic theme 6 forbids it from overwriting `app/page.tsx`, and without one the -two-command path ends on Next.js's stock welcome screen. The command saved is worth little; the -screen at the end of it is the deliverable. - -**Alternative: the wrapper writes the config and the wiring itself**, and calls init only for -dependencies. This is the version that would let this package ship before FIX-1159, which is -tempting given the dependency. Rejected because it is exactly the duplication epic theme 1 -names as the tripwire: two things generating `fsdev.config.ts` disagree the first time one of -them changes, and the disagreement surfaces in a stranger's project rather than in our tests. - -**Alternative: bundle the templates and fetch nothing** (the issue body's pattern audit, which -recommended it). Half-adopted. The demo content is bundled — it is ours and it is three files. -The *app* is not, because a bundled Next.js app is a second Next.js app for us to keep current, -and we already keep two in this repo. - -**Where the complexity is:** not in any file this package writes. It is in the **handoff to -init** — ordering the demo content before init runs so init never authors a competing flow, -carrying the collected answers across so nothing is asked twice, and making sure the one -install that happens is init's. Everything else here is a file copy. +**Alternative: drop this issue entirely.** It belonged on the list while the two-command path +existed. It does not any more: after the greenfield/brownfield split there is no second command +to run, so dropping this issue means a stranger with no project has no deterministic way in at +all. What is left of the case against it is the saved keystrokes and the package name, which is +what the epic now says too. + +**Alternative: bundle the Next.js app as well and call `create-next-app` never.** This is what +`create-vite` and `create-remix` do, and decision 3 makes it tempting — if we are checking in +template files anyway, why not all of them? Rejected because the aging half of a Next.js app is +the half we would then own: the framework version, the TypeScript and lint configuration, the +App Router conventions that shift between releases. Deferring to Next's own scaffolder means a +developer gets whatever Next considers correct on the day they run it. The price is a real +dependency on someone else's flag surface, and §9 says how that fails. + +**Alternative: keep the previous draft's split** — init generates the config and the mount, this +package supplies only the demo content. Rejected by decision 3, but it deserves naming because +it is what the approved sibling spec still describes. The deciding argument is not duplication; +it is that the epic's replacement tripwire needs a template that can be *read*, and a runtime +assembly cannot be. + +**Where the complexity is:** not in any file this package writes — five of the six are static. +It is in the **three-way handoff**: `create-next-app`'s flags (which drift, and which resolve +from saved preferences when unpassed), the manifest edit that has to land between the scaffolder +and the install, and the seam to init, which must be handed a directory whose shape is fully +declared so init writes nothing this template already wrote. ### 4. Focus practices (1–5) -1. **Tenet 3 (earn every addition)** — the file list is the spec. Three authored files for the - Next.js template (a flow, a page, and whatever the flow imports). A fourth file is a design - review, not an implementation detail. -2. **Tenet 2 (composition over features)** — every capability this command appears to have - belongs to something else. The test for a new code path here is: *could init do this?* If - yes, it goes there. +1. **Tenet 3 (earn every addition)** — the file list is the spec. Six template files, one of + which carries a substituted model string. A seventh file is a design review. +2. **Tenet 2 (composition over features)** — the test for a new code path here is: *is this a + fact about a repository we did not create?* If yes it belongs in the skill, and if it is a + fact about credentials, install, or the printed block it belongs in init. 3. **Tenet 7 (prove the goal, not the mock)** — the goal check runs the published invocation in an empty directory with **no provider key in the environment**, and ends at a streamed - response rendered in the browser. A test that stubs `create-next-app` and stubs init proves - the ordering and nothing about the product. -4. **BP-035 (second-path checklist)** — the second path here is **failure after a partial - scaffold**. `create-next-app` failing, or init failing after it succeeded, both leave a real - directory on someone's disk; §9 says what each one prints and neither rolls back. + response rendered in the browser **through the mounted route** — not through `fsdev run`, + which does not exercise the Next.js server bundle where the provider SDK is dynamically + imported (§12). +4. **BP-003 (execute the claim, don't read it)** — every printed command is asserted by running + it, and the ignore guarantee by `git check-ignore`. A plausible-looking transcript has hidden + a broken command three times across this epic. +5. **BP-035 (second-path checklist)** — the second path is **failure after a partial scaffold**. + `create-next-app` failing, or init failing after it succeeded, both leave a real directory on + someone's disk; §9 says what each prints, and neither rolls back. ### 5. What using it looks like (1–5 examples) **The whole product** *(what this spec proposes; no such command exists today)*: ``` -$ npx @flow-state-dev/create-fsd-app@latest my-app +$ npm create flow-state my-app -? Project name › my-app ? Model provider › OpenAI ? OPENAI_API_KEY › sk-•••••••• Creating my-app with create-next-app … - Adding the demo flow and chat page … + Writing the chat template … Running fsdev init … - Created app/api/flows/[...path]/route.ts - app/api/flows/route.ts - fsdev.config.ts - AGENTS.md - Wrote .env.local (OPENAI_API_KEY) .gitignore (FSD ignore entries) - Added flows/chat/flow.ts app/page.tsx the template's demo content + Created fsdev.config.ts lib/flowstate.ts + src/flows/chat/flow.ts app/page.tsx + app/api/flows/route.ts app/api/flows/[...path]/route.ts + Wrote .env.local (OPENAI_API_KEY, already ignored by git) + Appended AGENTS.md (FSD section) Installed via npm Next steps 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"}' + 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"}' Storage is on-disk for development. Pick a real store before you deploy. + The app and the DevTool are two processes over one development store — + drive one at a time. AGENTS.md tells your coding assistant how to write FSD flows. ``` Everything from `Created` down is **init's output, printed by init** (epic theme 5). The three -lines above it are this package's. +lines above it are this package's. Two details in the block are load-bearing rather than +cosmetic: `npm exec` needs the `--` separator or npm consumes `--input` as its own configuration +and the command fails, and the two-process caveat is real because both printed servers open the +same development store. §10 asserts the first by running it. -**Non-interactively**, which is how it runs in the goal check and in CI: +**Non-interactively**, which is how the goal check and CI run it: ``` -$ npx @flow-state-dev/create-fsd-app my-app --provider openai --package-manager pnpm -y +$ npm create flow-state my-app -- --provider openai --package-manager pnpm -y ``` **When the directory is already taken** — the refusal happens before anything is created: ``` -$ npx @flow-state-dev/create-fsd-app my-app +$ npm create flow-state my-app ✗ ./my-app already exists and is not empty. Pick another name or remove it. ``` @@ -249,60 +296,79 @@ $ npx @flow-state-dev/create-fsd-app my-app ### 7. Technical design -A new published package, `packages/create-fsd-app/`, whose entry point is a four-step pipeline. -It has no runtime dependency on this monorepo beyond the published `@flow-state-dev/cli` it -imports, and nothing it writes into the generated project imports anything of ours that is not -on npm (epic theme 4). +A new published package, `create-flow-state`, whose entry point is a four-step pipeline. It has +no runtime dependency on this monorepo beyond the published `@flow-state-dev/cli` it imports, and +nothing it writes into the generated project imports anything of ours that is not on npm (epic +theme 4). ```mermaid flowchart TB - A[resolve invocation
name · template · provider · key · package manager] --> B[create the bare app
create-next-app, install skipped] - B --> C[write demo content
flows/chat/flow.ts · app/page.tsx] - C --> D[call fsdev init as a library
answers passed in · flow already supplied] - D --> E[init installs once
and prints the next-steps block] + A[resolve invocation
name · provider · key · package manager] --> B[create the bare app
create-next-app, install skipped, every flag explicit] + B --> C[write the template
6 files · + the module-type key in the manifest] + C --> D[call fsdev init as a library
shape fully declared · answers passed in] + D --> E[init: key · ignore entry · AGENTS.md section
install · next-steps block] ``` **Step 1 — resolve the invocation.** Flags first, prompts for whatever is missing, `-y` to take defaults for everything unflagged. Validation (project name is a legal npm package name, target -directory absent or empty, template is one that exists) happens **here**, before any directory -is created, so a refusal never leaves debris. The package manager is detected from -`npm_config_user_agent` and passed on to both later steps, so exactly one manager owns the -lockfile. - -**Step 2 — create the bare app.** Spawn `create-next-app` with explicit non-interactive flags -and installation skipped. Its own prompts must all be answered by flags; an unanswered one hangs -the command, which is the failure mode that makes this step worth a test on the argv it builds. - -**Step 3 — write demo content.** Three files, and this is the entire product surface: +directory absent or empty, Node at or above the runtime floor) happens **here**, before any +directory is created, so a refusal never leaves debris. + +**Step 2 — create the bare app.** Spawn `create-next-app` with **every** flag passed explicitly, +installation skipped, git left enabled. Explicit matters more than it looks: `create-next-app` +persists saved preferences between runs and silently fills unpassed options from them, so a flag +we omit can resolve differently on a developer's machine than on ours. `--yes` is not a +substitute for passing them. + +**The version is pinned in the spawned specifier, not left to `npx` to resolve.** The command is +`create-next-app@`, 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 +shipped that morning. The pin is what makes §9's flag-drift row a *loud* failure at our next +release rather than a silent one in a stranger's terminal, and the CI argv assertion (§10) reads +the pinned specifier so removing it fails a test. The pin cannot detect upstream drift on its own +— nothing stubbed can — so the goal check is the detector and the pin is what stops the detection +gap reaching users in between. + +**Step 3 — write the template.** Six files, materialized from `templates/nextjs-chat/`, plus one +manifest key. This is the entire product surface: | 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 | -| `app/page.tsx` | the chat page. `FlowProvider` + `useFlow` + `useSession` + `ItemsRenderer` from `@flow-state-dev/react`, no other imports (decision 5). Overwrites `create-next-app`'s stock page — permitted, because this is a greenfield directory this package created; epic theme 6 binds init, not the wrapper | -| `.env.local` *(not written here)* | listed to be explicit: init writes it. So does the config, the routes, the ignore entries, and the agent-instructions file | - -**Step 4 — hand off to init.** The load-bearing step. What crosses the seam: - -| passed in | why it cannot be skipped | +| `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 | +| `app/api/flows/route.ts` | the sibling bare route. `list_flows` is registered as `GET /` on the mount base and the client's `listFlows()` requests it, but a required catch-all cannot match zero segments. `@flow-state-dev/next` exports no bare handler (only `@flow-state-dev/vercel` does), so this one forwards by hand with a comment saying why | +| `app/page.tsx` | the chat page. `FlowProvider` + `useFlow` + `useSession` + `ItemsRenderer` from `@flow-state-dev/react`, no other imports (decision 6). Overwrites `create-next-app`'s stock page — permitted, because this is a directory this command created seconds ago | +| *manifest* | `"type": "module"` added — decision 4. Nothing else; dependencies and the lockfile are the package manager's | + +**Why the config shape is what it is — measured.** The template's config has two consumers at +once: Turbopack, because the route imports it, and the CLI's native `import()`. Nobody had +checked the first. The POC at [`spec-poc/FIX-548-next-template-shape/`](../spec-poc/FIX-548-next-template-shape/) +scaffolds a real `create-next-app@16` project and runs both against every candidate shape — run +it with `bash spec-poc/FIX-548-next-template-shape/probe.sh`. It settled decision 4 and turned up +four facts nothing in this epic knew: `create-next-app` writes its **own** `AGENTS.md` (with its +own delimiters, re-added by `next dev`) and a `CLAUDE.md`; its `.gitignore` already carries +`.env*`; and `--agents-md` defaults on from saved preferences. The first of those matters most — +**the greenfield Next path appends to an existing `AGENTS.md`, it never creates one**, which is +the case everyone had filed under brownfield. + +**Step 4 — hand off to init.** What crosses the seam, and nothing more: + +| passed in | why | |---|---| | the target directory | init otherwise runs against the cwd, which is the parent | -| 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 declared host (`next`) | selects the Next shape of the next-steps block. **Not** a request to write the mount — decision 3 already wrote it | +| the declaration that config, flows and wiring are present | init must author none of them, and must not treat a non-empty directory as undeclared (FIX-1159 decision 2 turns on *declared*, not *empty*) | +| provider and key | collected in step 1; a second prompt for the same key is the thing this seam exists to prevent | | 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) | -**This is a constraint on FIX-1159, and it is this spec's only cross-issue ask.** All four rows -are satisfied by one change of shape: *init is a library, and the CLI command is a thin caller -of it.* Note that PR #1310 carries a reviewer note calling the reusable next-steps module -premature — "authoring a reusable next-steps module for FIX-548 before that issue exists". That -issue now exists, needs three more things from the same seam, and cannot be built without it; -the note is answered by this spec rather than by an argument. - -**Ordering, and why it is not incidental.** Demo content is written *before* init runs, so -init's config generation sees the flow that will actually be there. Reverse the two and init -authors `hello`, and every way out of that is a file operation on something init just wrote. -And `create-next-app` must skip its install, or the project installs twice and the second -install rewrites a lockfile the first one wrote. +**Ordering, and why it is not incidental.** The template is written *before* init runs, so init +sees a fully declared shape and authors nothing that competes. `create-next-app` must skip its +install, or the project installs twice and the second run rewrites the lockfile the first wrote. +And the manifest's `"type": "module"` must land before the install, because the package manager +rewrites that file. **Untouched:** the engine, the adapters, the CLI's existing commands, every block kind. This package generates a project; it changes no framework behaviour. @@ -310,26 +376,27 @@ package generates a project; it changes no framework behaviour. ### 8. Implementation sequence 1. **The package skeleton and its invocation surface** — flags, prompts, `-y`, package-manager - detection, and all of §9's validation refusals. - *Test:* every refusal in §9's first block, and that each refusal happens before any directory - is created. *Depends on:* nothing. -2. **The bare-app step** — spawn `create-next-app` with install skipped, surface its failure. - *Test:* the argv built (flags complete enough that nothing prompts; install skipped), and the - failure path's output. *Depends on:* 1. -3. **The demo content** — the flow and the chat page. - *Test:* the generated flow type-checks and its action runs against a stubbed model; the page - compiles. *Depends on:* nothing. -4. **The init handoff** — call init with the collected answers and the supplied flow, print what - it returns. *Test:* the call ordering (content before init), the arguments crossing the seam, - and that the printed block matches a standalone init run. - *Depends on:* 1, 2, 3, **and FIX-1159's library seam existing.** + detection, the runtime-floor gate, and all of §9's validation refusals. + *Test:* every refusal in §9's first block, each asserting nothing was created. *Depends on:* + nothing. +2. **The bare-app step** — spawn `create-next-app` with every flag explicit and install skipped; + surface its failure. *Test:* the argv built (complete enough that no option resolves from + saved preferences; install skipped), and the failure path's output. *Depends on:* 1. +3. **The template** — the six files and the manifest key. + *Test:* the generated project builds and its mounted route serves; the config loads under a + native `import()` with no warning; `.env.local` is ignored by git before the key is written. + *Depends on:* nothing. +4. **The init handoff** — call init with the declared shape and collected answers, print what it + returns. *Test:* the call ordering (template before init), the arguments crossing the seam, + that init authored no config or flow of its own, and that the printed block matches a + standalone init run. *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. | sub-PR | deliverables | depends_on | |---|---|---| -| a | the package: invocation surface, bare-app step, demo content, init handoff (steps 1–4) | — | +| a | the package: invocation surface, bare-app step, the template, init handoff (steps 1–4) | — | | b | publish configuration, package README, and the three doc surfaces in §11 (step 5) | a | ### 9. Edge cases & error handling @@ -340,134 +407,188 @@ package generates a project; it changes no framework behaviour. |---|---| | 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. | -| `--template` names one that does not exist | Refuse and list the ones that do. | -| Node runtime below the CLI's declared floor | Refuse, with the same floor and the same message init uses. The wrapper's engines range matches the CLI's, so this is caught at install where possible. | +| 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). | **Failures after work has started — nothing rolls back:** | Case | Expected | |---|---| -| `create-next-app` fails or is unreachable | Report its output, name the directory as it stands, and print the two commands that finish the job by hand. Do not delete it. | -| Init fails after the app was created | The scaffold stays. Print init's own retry command against that directory. Mirrors init's install-failure taxonomy, which also leaves files and prints the retry. | +| `create-next-app` fails, is unreachable, or rejects a flag | Report its output, name the directory as it stands, and print the two commands that finish the job by hand. Do not delete it. | +| `create-next-app` changes its flag surface or generated layout | The pinned specifier (§7 step 2) means an upstream change does not reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | +| Init fails after the template was written | The scaffold stays. Print init's own retry command against that directory. Mirrors init's install-failure taxonomy, which also leaves files and prints the retry. | | Install fails inside init | Init's case, not this one. It reports and this command adds nothing. | -| `-y` with no key in flags or environment | Scaffold completes. `.env.local` carries the empty key line init writes, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is a legitimate use. | +| `-y` with no key in flags or environment | Scaffold completes. `.env.local` carries the empty key line init writes, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. | +| 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 owns the block). | -**Taxonomy:** the refusals leave the disk untouched; the failures leave a directory the -developer can inspect and finish by hand. There is no partial state this command cleans up -behind the user, because deleting a directory a stranger may have put something in is worse -than leaving one they can `rm`. +**Taxonomy:** refusals leave the disk untouched; failures leave a directory the developer can +inspect and finish by hand. Nothing is cleaned up behind the user, because deleting a directory +a stranger may have put something in is worse than leaving one they can `rm`. ### 10. Testing strategy **Goal & goal check** (the epic's proof for this issue). One recorded run under -`goals/create-fsd-app/` — or two, if decision 4 is overturned: +`goals/create-flow-state/` — or two, if decision 2 is overturned: - In an **empty directory, with no provider key in the environment**, run the published invocation, supply the key at its prompt, then run the printed dev command and send a message in the browser: a streamed model response renders in the page. -- The key is deliberately *not* pre-exported. The epic's original wording for this check - supplied it in the environment, and PR #1301's review note 8 called that out: pre-supplying it - skips the credential path entirely, so the check would pass while a real user's first command - failed. FIX-1159's goal checks were corrected the same way. -- **The bare `/api/flows` is exercised by construction here**, because the page's - `FlowProvider` calls `listFlows()` against it. That is worth stating rather than leaving - implicit: if that route is wrong the page is simply dead, with nothing in it pointing at a - route file. - -**CI specs** (the behaviours, not the test names) — all against a stubbed `create-next-app` and -a stubbed init, in a temporary directory, with no network and no install: +- **Through the mounted route, not through `fsdev run`.** The provider SDK is imported + dynamically by package name inside the Next.js server bundle, where `createModelResolver` + carries an explicit fallback for it failing to resolve (§12). A CLI-only check passes with + that path broken. +- **Run once per advertised provider, single key only** — an OpenAI-key run, an Anthropic-key + run, a Google-key run, each with the other two absent. Decision 5 is the reason: a prompt + offering three providers where only one works is a first-hour failure, and one run with the + most-likely key would not find it. +- The key is deliberately *not* pre-exported. PR #1301's review note 8 called that out: + pre-supplying it skips the credential path, so the check passes while a real user's first + command fails. + +**CI specs** (behaviours, not test names) — all against a stubbed `create-next-app` and a stubbed +init, in a temporary directory, with no network and no install, **except the three marked +*real*, which build a scaffolded project once**: - one behaviour per decision in §6 -- **demo content is written before init is called** — asserted on the call ordering, not the end - state, because a wrapper that wrote content afterwards and deleted init's flow would leave an - identical directory +- ***real*: the generated project builds and its mounted route serves** — the check that decision + 4 keeps passing when Next's resolution behaviour moves under us. This is the drift tripwire + decision 3 owes; it is the only assertion that covers the template's contents rather than its + file names +- ***real*: the config loads under a native `import()` with no warning** — asserted on stderr, + because `MODULE_TYPELESS_PACKAGE_JSON` is a first-hour wart that no functional test fails on +- ***real*: `git check-ignore .env.local` succeeds before the key is written** — executed, not + read, and specifically before, because ordering is the whole guarantee (decision 7) +- **the template is written before init is called** — asserted on call ordering, not end state, + since a package that wrote afterwards and deleted init's files would leave an identical + directory +- **init authored no config and no flow** — asserted on what crossed the seam, because the + symptom otherwise is a second flow file appearing beside the advertised one - **the collected provider and key reach init** — asserted on the call, so a regression shows up - as a failing test rather than as a second prompt in someone's terminal -- **`create-next-app` is invoked with install skipped** — asserted on the argv, since the - symptom otherwise is only "the first hour is slower" -- **the argv answers every prompt `create-next-app` would ask** — an unanswered one hangs -- **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5) — - asserted, because "reused verbatim" is a promise that decays silently + as a failing test rather than a second prompt in someone's terminal +- **`create-next-app` is invoked with install skipped, every flag explicit, and the pinned major + in the specifier** — asserted on the argv, since the symptoms otherwise are "the first hour is + slower", "it behaved differently on my machine", and a version nobody tested +- **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5) +- **every printed command runs** — execute the strings the block emitted, in the generated + project, and assert the process starts. This is where npm's `--` separator is caught - every refusal in §9's first block, each asserting nothing was created -- `-y` with no key: scaffold completes and the output says the key is missing +- `-y` with no key: the scaffold completes and the output says the key is missing -**Where each lives.** The goal check is a real-machine run under `goals/create-fsd-app/` — real -network, real `create-next-app`, real model, real browser — and is never part of the vitest -suite. Everything in the CI list runs in a temp directory against stubs. Both halves are needed -and neither substitutes for the other: the stubs prove the ordering and the seam, and only the -real run proves the product. +**Where each lives.** The goal checks are real-machine runs under `goals/create-flow-state/` — +real network, real `create-next-app`, real model, real browser — and are never part of the vitest +suite. The three *real* CI specs scaffold once and are the slowest thing in the suite; they earn +it, because everything else in the list would pass against a template that does not compile. -**Discipline:** `tdd`. The seam is the pipeline against a temporary directory with the two -subprocesses stubbed; every CI behaviour above is reachable from a vitest spec. +**Discipline:** `tdd`. The seam is the pipeline against a temporary directory with both +subprocesses stubbed. ### 11. Documentation plan - **EXTEND** `apps/docs/docs/getting-started/quick-start.md` — lead with this command for - someone starting fresh, and point across to init's `existing-project.md` page (created by - FIX-1159) for someone who already has a project. One example: the command and what they see - when it finishes. - *Voice risks:* a scaffolding command attracts "instantly", "zero-config", and "just works" — - none of them. Say what it creates and what it does not (decision 4's boundary, and that the - development store is not a deployment store). -- **CREATE** `packages/create-fsd-app/README.md` — the npm landing page. Install snippet, the - flag table, what the generated project contains, and a link to the docs site. Must render - correctly on npmjs.com. -- **EXTEND** the root `README.md` — the quick-start section. **FIX-1159 also edits this - section** (it leads with init for existing projects) and lands first, so this issue edits the - version FIX-1159 leaves rather than the one on `main` today. Worth checking at implementation - time rather than assuming. + someone starting fresh, and point across to the existing-project page (FIX-1159) for someone + who already has one. **It also needs correcting:** it teaches `lib/flowstate.ts` holding + `createFlowState(...)` with no root `fsdev.config.ts`, which produces a project the CLI cannot + drive (config search is cwd-only and wants a default export). The template's shape — root + config, `lib/flowstate.ts` re-export — is the one to teach. + *Voice risks:* a scaffolding command attracts "instantly", "zero-config", "just works" — none + of them. Say what it creates and what it does not (the development store is not a deployment + store; there is no authentication). +- **CREATE** `packages/create-flow-state/README.md` — the npm landing page. Install snippet, the + flag table, what the generated project contains, a link to the docs site. Must render on + npmjs.com. +- **EXTEND** the root `README.md` — the quick-start section. **FIX-1159 also edits this section** + and lands first, so this issue edits the version FIX-1159 leaves rather than the one on `main`. + Worth checking at implementation time rather than assuming. - **No blog post.** This ships as part of Public Launch; the announcement is that project's. - **A changeset is required** (BP-022) — a new published package is as user-facing as it gets. ### 12. Dependencies, open questions & follow-ups -**Dependencies — two, and one of them is hard.** - -- **FIX-1159 (`fsdev init`) blocks implementation, not specification.** The two specs are being - written in parallel, as the epic intends, but this package cannot be built until init's - library seam exists and cannot merge before init merges (epic theme 1). §7's four-row table - is the exact interface required; it is going on PR #1310 while that spec is still in review, - which is the cheap moment to place it. -- **FIX-1162 (npm names) does not block this issue** — decision 3 removes it, publishing under - the scope we already own. The epic's running index currently shows FIX-548 as blocked by - FIX-1162; that row is stale once this spec is approved. - -**Open questions:** one, and it is §6's decision 4 — does the Node API template ship? It is -raised as a decision with a recommendation rather than left open, because leaving it open would -block a spec on a question the spec itself can answer either way. The answer changes what §7 -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 -re-derive them): - -- `packages/cli` has no `init` command today (`src/commands/` holds `run`, `dev`, `serve`, - `chat`, `block`, `ui`, `benchmark`), and its exports are `main`/`exports` on `src/index.ts` — - so exposing init as a library is an addition to that surface, not a change to it. -- The generated config **registers flows explicitly**: `loadFsdevConfig` imports a module that - default-exports the `createFlowState({ flows, stores })` handle, and config search is - **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. -- FIX-1159 settled that a non-Next project gets **no generated server file** (decision 1) and - **no package script** (decision 3). Both are why §6's decision 4 reads differently than epic - theme 2 did — the Node template's contents were mostly those two things. -- The three PR #1301 review notes about a generated Node entrypoint (unauthenticated bind on - all interfaces, `.env.local` never loaded, and preferring the existing `fsdev serve`) are - **all resolved upstream by that decision** — there is no generated entrypoint left to get - wrong. They are recorded here so a reviewer does not re-raise them against this spec. -- The two PR #1301 review notes about missing dependencies — the provider SDK (`@ai-sdk/openai` - is a dev dependency of `core` and never reaches a consumer) and `@flow-state-dev/devtool` (an - optional peer of the CLI, satisfied only inside this monorepo) — are **resolved by init's - install step**, which installs both. This package inherits that and adds nothing. -- `examples/hello-chat` is the shape reference for the demo flow and page, not the content - reference: its page pulls in a component library, an icon set, and a session sidebar - (`components/ui/*`, `lucide-react`), which decision 5 declines. +**Dependencies.** + +- **FIX-1159 blocks implementation, not specification.** This package cannot be built until + init's library seam exists, and cannot merge before init merges. §7's step-4 table is the + required interface; it is **smaller than the previous draft's**, because decision 3 moved the + config and the mount here. +- **FIX-1162 no longer gates this issue at all** (decision 1). The owner holds the name. + +**Cross-issue notes — raised, not decided here.** + +- **FIX-1159's Next-host branch is no longer on this path.** Its write mode authors + `fsdev.config.mts`, `flows/hello/flow.mts` and the Next route pair for a declared Next host; + decision 3 means the only Next caller writes all three itself. Whether that branch keeps + earning its place, or write mode narrows to the plain-Node shape it is actually used for, is + FIX-1159's call. Nothing here is blocked either way. +- **Decision 4 differs from FIX-1159 decision 4 on the same file.** Init writes + `fsdev.config.mts`; this template writes `fsdev.config.ts` plus `"type": "module"`. That is not + a contradiction — init's rule covers a directory whose manifest it does not control, and this + one covers a manifest we created — but the two outputs now differ, so FIX-1159's "align the + corpus on `.mts`" follow-up should weigh that the greenfield flagship went the other way, with + measurements. +- **The next-steps block owes a two-process line.** Both commands it prints for a Next host open + the same development file store (§9). FIX-1159 owns the block's wording. +- **The epic's prose and FIX-1162's proposal are stale on the name.** Both say + `create-fsdev-app` on the strength of `create-fsd-app` being unobtainable. The owner now holds + `create-flow-state`, `create-fsd-app` and `flow-state-app`; decision 1 picks the first. +- **`create-next-app` writes `AGENTS.md` and `CLAUDE.md` itself**, and `next dev` re-adds its + own block. Epic Q1's append-never-overwrite guarantee therefore binds the *greenfield* path + too, which the epic files under brownfield. The POC confirmed an appended FSD section survives + a `next dev` run. + +**Open questions:** one, and it is §6's decision 2 — does the Node API template ship? Raised as a +decision with a recommendation rather than left open, because leaving it open would block a spec +on a question the spec can answer either way. The answer changes whether §10 records one goal run +or three-per-template, and whether decision 2b's flag exists. Nothing else. + +**Verified premises** (measured or read from the code, so a reviewer need not re-derive them): + +- **Module loading in a real `create-next-app@16` project, probed** (the POC in §7): Turbopack + does **not** resolve an extensionless import to a `.mts` file (`Module not found`); an explicit + `.mts` specifier fails TypeScript with `TS5097` unless `allowImportingTsExtensions` is set; + `.mts` with that flag builds; `fsdev.config.ts` with `"type": "module"` builds **and** loads + under a native `import()` with no warning; without the `type` field the same file loads but + emits `MODULE_TYPELESS_PACKAGE_JSON`. Confirmed end to end: `next dev` served `GET /api/flows` + through the config module. +- `packages/cli` has **no `init` command today** (`src/commands/` holds `run`, `dev`, `serve`, + `chat`, `block`, `ui`, `benchmark`), so exposing init as a library is an addition to that + surface, not a change to it. +- The config loader's filename precedence is `fsdev.config.{ts,mts,js,mjs}`, searched **cwd-only**. + The CLI *does* have a directory scan (`src/flows/`, `flows/`), but it is the **fallback for + projects with no config** — once a config resolves, `fsdev dev` and `fsdev run` serve that + config's own `FlowState` and its explicit registry. The template ships a config, so the demo + flow must be registered in it; a flow file alone would not be found. +- `fsdev serve` defaults to `$HOST ?? 0.0.0.0` and `$PORT ?? 3000` — **not 8787, as the epic's + Node transcript shows** — and `assertNetworkBindIsAuthenticated` refuses a network bind for an + unauthenticated flow. This template's next steps never print `fsdev serve`; the hazard is + recorded because the epic's transcript is wrong and the Node template it belongs to is what + decision 2 cuts. +- `fsdev dev` binds `127.0.0.1:4200`, so the bind guard is not in play; with a config present it + serves the app's **own** `FlowState` (its stores, its flows) rather than the SQLite discovery + path, which is why the two-process store note in §9 applies. +- Provider detection maps exactly three providers to env vars: `anthropic`/`ANTHROPIC_API_KEY`, + `openai`/`OPENAI_API_KEY`, `google`/`GOOGLE_GENERATIVE_AI_API_KEY`. +- Provider SDKs are **dynamically imported by package name** (`@ai-sdk/openai`, + `@ai-sdk/anthropic`, `@ai-sdk/google`); `@ai-sdk/openai` is only a *dev* dependency of `core`, + so none reaches a consumer. `createModelResolver` carries a `directLoadFailed` set for the case + where a provider package "cannot be resolved on disk (bundled Next.js)" — an acknowledged + hazard on exactly this template's path, and why §10's goal check goes through the route. +- `@flow-state-dev/devtool` is an *optional peer* of the CLI, satisfied only inside this + monorepo. Init's install covers both it and the provider SDK; this package adds nothing. +- `@flow-state-dev/next` exports only `createNextHandler` (catch-all); the bare-path handler + exists only in `@flow-state-dev/vercel`. Both in-repo mounts hand-write the bare forwarder, + with a comment saying why. +- Both in-repo Next apps reconcile the root config with the routes through a `lib/` re-export; + the published quick-start does not, and §11 corrects it. +- `examples/hello-chat` is the shape reference for the flow and page, not the content reference: + its page pulls in a component library, an icon set, and a session sidebar, which decision 6 + declines. **Follow-ups (flagged, not built):** -- **The `node-api` template**, if decision 4 goes the other way later. Additive — the - `--template` flag ships with the seam in place. -- **The unscoped package name as an alias**, once FIX-1162 secures it (decision 3). +- **The `node-api` template**, if decision 2 goes the other way later. Additive; arrives with + the `--template` flag (decision 2b). +- **A bare-path handler in `@flow-state-dev/next`**, matching `createVercelBareHandler`. Would + turn one hand-written template file into a one-liner. FIX-1159 flags the same gap. ### 13. Review notes for the implementer @@ -477,11 +598,31 @@ re-derive them): ## Spec evolution -- **Spec drafted** — scoped to the two things neither `create-next-app` nor `fsdev init` can - produce (a demo flow and the page that talks to it), and everything else delegated. Settled - the init handoff as a library call rather than a subprocess, because a subprocess cannot be - handed the answers already collected and would ask for the API key twice. Declined to - maintain a Next.js skeleton. Unblocked the issue from FIX-1162 by publishing under the scope - we already own, mirroring FIX-1159's reasoning. Raised the Node API template as the spec's - one ask: FIX-1159's decisions to generate no server file and add no package script removed - almost everything that template would have contained. +- **Spec drafted** — scoped to the two things neither `create-next-app` nor `fsdev init` could + produce (a demo flow and the page that talks to it), everything else delegated. Settled the + init handoff as a library call rather than a subprocess, so the API key is asked for once. + Declined to maintain a Next.js skeleton. Raised the Node API template as the spec's one ask. +- **Re-drafted against three decisions that landed after drafting** — not a review round. + (1) *The greenfield/brownfield split.* Brownfield is an agent skill and the deterministic + wrapper relationship this spec was built on is gone; the epic's re-drafted theme 1 gives this + issue its template end to end, so §6 decision 3 moves the config and the Next mount here and + §7's seam to init shrinks to credentials, the agent-instructions section, the install, and the + printed block. (2) *One template.* The Node template's remaining delta is two files `npm init` + writes, and the ask is re-argued on the asymmetry rather than on file count; decision 2b drops + the `--template` flag with it, since a flag with one legal value documents an intention and + does nothing. (3) *The package name is `create-flow-state`*, which also removes FIX-1162 as a + gate by any route rather than by a workaround. +- **A POC settled the shape the re-draft depends on.** Owning the template end to end means + owning the config file, which has two consumers — Turbopack and the CLI's native `import()` — + and nobody had checked the first. A real `create-next-app@16` project showed that `.mts` costs + two edits to files the scaffolder wrote (Turbopack will not resolve it extensionless, and + TypeScript rejects the explicit specifier without `allowImportingTsExtensions`), while + `fsdev.config.ts` with `"type": "module"` builds, serves, and loads warning-free. It also + turned up that `create-next-app` writes its own `AGENTS.md` and `CLAUDE.md`, that `next dev` + re-adds its block, and that its `.gitignore` already ignores `.env*` — 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 and an executed `git check-ignore` assertion instead of an assumption about someone + else's file. Provider/model alignment became decision 5's intent map, with the goal check run + per provider on a single key. And the printed commands are asserted by execution, which is what + catches npm's `--` separator. From c2579def4696f34339fe491b81f3d6cbe8b1db73 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 00:22:55 +0000 Subject: [PATCH 03/30] =?UTF-8?q?spec(FIX-548):=20make=20the=20goal-run=20?= =?UTF-8?q?count=20consistent=20=E2=80=94=20per=20template=20x=20per=20pro?= =?UTF-8?q?vider?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index dfec6edfe9..3238dfc0b1 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -165,8 +165,9 @@ directory already produces that, on a path FIX-1159's own goal check runs with a Next.js template is not in that position: the chat page and the mounted route can only come from here, and they are what turn the ending from a stock welcome screen into something working. -**The trade-off.** Two templates cost a second recorded goal run, on machines we do not control, -on every release, forever — the epic named that as an accepted cost when the Node template still +**The trade-off.** The proof runs per template *times* per advertised provider (§10), so one +template is three recorded runs and two templates are six — on machines we do not control, on +every release, forever. The epic named that as an accepted cost when the Node template still carried a server file. One template costs backend-first developers a starter with their name on it; they get `mkdir my-api && npx @flow-state-dev/cli init`, which is two commands instead of one and produces the same files. @@ -427,8 +428,10 @@ a stranger may have put something in is worse than leaving one they can `rm`. ### 10. Testing strategy -**Goal & goal check** (the epic's proof for this issue). One recorded run under -`goals/create-flow-state/` — or two, if decision 2 is overturned: +**Goal & goal check** (the epic's proof for this issue). Recorded runs under +`goals/create-flow-state/` — **three for the one template**, one per advertised provider, and +three more per additional template if decision 2 is overturned. That count is the real cost the +ask above is pricing: it is per template *times* per provider, not per template: - In an **empty directory, with no provider key in the environment**, run the published invocation, supply the key at its prompt, then run the printed dev command and send a message @@ -537,8 +540,8 @@ subprocesses stubbed. **Open questions:** one, and it is §6's decision 2 — does the Node API template ship? Raised as a decision with a recommendation rather than left open, because leaving it open would block a spec -on a question the spec can answer either way. The answer changes whether §10 records one goal run -or three-per-template, and whether decision 2b's flag exists. Nothing else. +on a question the spec can answer either way. The answer changes whether §10 records three goal +runs or six, and whether decision 2b's flag exists. Nothing else. **Verified premises** (measured or read from the code, so a reviewer need not re-derive them): From dbda62f06dc03973157997e38c50b34ea7093caa Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 00:25:47 +0000 Subject: [PATCH 04/30] spec(FIX-548): pin create-next-app exactly, and make the probe fail when it fails MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 7 +++++ spec-poc/FIX-548-next-template-shape/probe.sh | 27 +++++++++++----- spec/FIX-548.md | 31 ++++++++++++------- 3 files changed, 47 insertions(+), 18 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index 349eb04bc8..4dda9c8140 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -11,6 +11,13 @@ Run it: `bash probe.sh` (needs network; ~2 minutes). It scaffolds a real `create project, drops each candidate config shape in, and runs `next build`, `next dev`, and a native `import()` against each. +**The exit status is the evidence** — `0` the served-route and `AGENTS.md` claims held, `1` one +of them failed, `2` it could not be checked. The variant table below is printed output you read; +the final section is an assertion the script fails on. It uses a fresh marker per run on a port +it proves free first, because an earlier version of this probe reported green by reaching a stale +dev server left over from a previous run — a result from a neighbour of the claim, which is the +whole failure it exists to catch. + ## What it settled | Variant | `next build` | native `import()` | verdict | diff --git a/spec-poc/FIX-548-next-template-shape/probe.sh b/spec-poc/FIX-548-next-template-shape/probe.sh index 9f6ccdf83f..bd26e1c965 100644 --- a/spec-poc/FIX-548-next-template-shape/probe.sh +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -3,7 +3,7 @@ # # bash probe.sh [workdir] # -# Scaffolds a real create-next-app@16 project, then for each candidate shape of +# Scaffolds a real create-next-app@16.3.1 project, then for each candidate shape of # the FSD config runs `next build` (the bundler + TypeScript half) and a native # `import()` (the fsdev CLI half). Ends with a `next dev` + curl on the chosen # shape, so the mounted route is proven to serve, not just to compile. @@ -15,7 +15,9 @@ APP="$WORK/probe" rm -rf "$APP" echo "workdir: $WORK" -npx --yes create-next-app@16 "$APP" \ +# Exact, not @16 — a range would re-resolve and this script is cited as evidence, +# so a reader running it later must get the version the findings were measured on. +npx --yes create-next-app@16.3.1 "$APP" \ --ts --app --no-tailwind --no-eslint --no-biome --no-src-dir \ --no-react-compiler --no-rspack --import-alias "@/*" \ --agents-md --skip-install --disable-git || exit 1 @@ -93,7 +95,7 @@ PORT=0 for p in $(seq 3990 3999); do if ! (exec 3<>"/dev/tcp/127.0.0.1/$p") 2>/dev/null; then PORT=$p; break; fi done -if [ "$PORT" = 0 ]; then echo " no free port in 3990-3999 — skipped"; exit 0; fi +if [ "$PORT" = 0 ]; then echo " no free port in 3990-3999 — CANNOT VERIFY"; exit 2; fi echo " port $PORT (verified free)" printf '\n\nFSD SECTION SENTINEL\n\n' >> AGENTS.md @@ -102,11 +104,22 @@ DEV_PID=$! sleep 18 BODY=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows") echo " GET /api/flows -> $BODY" +RC=0 case "$BODY" in "$MARKER":200) echo " PASS — the route served this run's config module" ;; - *) echo " FAIL — expected $MARKER:200" ;; + *) echo " FAIL — expected $MARKER:200"; RC=1 ;; esac -echo " FSD section survived next dev: $(grep -c 'FSD SECTION SENTINEL' AGENTS.md) (expect 1)" -echo " next's own block still there: $(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md) (expect 1)" +FSD_N=$(grep -c 'FSD SECTION SENTINEL' AGENTS.md) +NEXT_N=$(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md) +echo " FSD section survived next dev: $FSD_N (expect 1)" +echo " next's own block still there: $NEXT_N (expect 1)" +[ "$FSD_N" = 1 ] || { echo " FAIL — appended FSD section did not survive"; RC=1; } +[ "$NEXT_N" = 1 ] || { echo " FAIL — next's own block is not intact"; RC=1; } kill "$DEV_PID" 2>/dev/null; wait "$DEV_PID" 2>/dev/null -exit 0 + +# The exit status is the evidence. This script is cited by the spec and the PR as +# the thing a reader runs, so it must not be able to report green for a claim it +# did not prove: 0 = the served-route and AGENTS.md claims held, 1 = one failed, +# 2 = could not be checked at all. +[ "$RC" = 0 ] && echo " probe: PASS" || echo " probe: FAIL" +exit "$RC" diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 3238dfc0b1..dbd82fe65e 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -321,14 +321,21 @@ persists saved preferences between runs and silently fills unpassed options from we omit can resolve differently on a developer's machine than on ours. `--yes` is not a substitute for passing them. -**The version is pinned in the spawned specifier, not left to `npx` to resolve.** The command is -`create-next-app@`, 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 -shipped that morning. The pin is what makes §9's flag-drift row a *loud* failure at our next -release rather than a silent one in a stranger's terminal, and the CI argv assertion (§10) reads -the pinned specifier so removing it fails a test. The pin cannot detect upstream drift on its own -— nothing stubbed can — so the goal check is the detector and the pin is what stops the detection -gap reaching users in between. +**The version is pinned to an exact release in the spawned specifier** — `create-next-app@16.3.1`, +not `@16` and not bare — held in one constant in this package and bumped as a deliberate change +with a goal-check run behind it. A major-range pin does not hold the guarantee: `@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, which is exactly what the pin exists to prevent. The CI argv +assertion (§10) reads the pinned specifier, so both removing it and loosening it to a range fail +a test. The pin cannot *detect* upstream drift — nothing stubbed can — so the goal check is the +detector and the pin is what keeps the gap between drift and detection off users' machines. + +**What the exact pin costs, stated plainly:** `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 therefore **routine scheduled maintenance with a goal-check run**, not a +rare event — a starter a few months behind on Next is a real cost, and the alternative is a +starter that breaks without warning. §9's drift row is the same failure either way; the pin only +decides whose terminal it happens in. **Step 3 — write the template.** Six files, materialized from `templates/nextjs-chat/`, plus one manifest key. This is the entire product surface: @@ -416,7 +423,8 @@ package generates a project; it changes no framework behaviour. | Case | Expected | |---|---| | `create-next-app` fails, is unreachable, or rejects a flag | Report its output, name the directory as it stands, and print the two commands that finish the job by hand. Do not delete it. | -| `create-next-app` changes its flag surface or generated layout | The pinned specifier (§7 step 2) means an upstream change does not reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | +| `create-next-app` changes its flag surface or generated layout | The **exact** pinned version (§7 step 2) means an upstream change cannot reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. A major-range pin would not hold that. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | +| The pinned `create-next-app` falls behind | New projects start on an older Next than current. Bumping the pin is scheduled maintenance gated on a goal-check run, not a reaction to breakage. | | Init fails after the template was written | The scaffold stays. Print init's own retry command against that directory. Mirrors init's install-failure taxonomy, which also leaves files and prints the retry. | | Install fails inside init | Init's case, not this one. It reports and this command adds nothing. | | `-y` with no key in flags or environment | Scaffold completes. `.env.local` carries the empty key line init writes, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. | @@ -468,8 +476,9 @@ init, in a temporary directory, with no network and no install, **except the thr symptom otherwise is a second flow file appearing beside the advertised one - **the collected provider and key reach init** — asserted on the call, so a regression shows up as a failing test rather than a second prompt in someone's terminal -- **`create-next-app` is invoked with install skipped, every flag explicit, and the pinned major - in the specifier** — asserted on the argv, since the symptoms otherwise are "the first hour is +- **`create-next-app` is invoked with install skipped, every flag explicit, and an *exact* pinned + version in the specifier** — asserted on the argv, and the assertion rejects a range as well as + a missing pin, since `@16` silently re-resolves. The symptoms otherwise are "the first hour is slower", "it behaved differently on my machine", and a version nobody tested - **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5) - **every printed command runs** — execute the strings the block emitted, in the generated From ecce07d1deca3a0b0652694fcc644676ae9cc851 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 00:36:18 +0000 Subject: [PATCH 05/30] spec(FIX-548): canonical route exports, credential stop as its own category, probe accumulates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 41 +++++- spec-poc/FIX-548-next-template-shape/probe.sh | 137 +++++++++++++----- spec/FIX-548.md | 49 ++++++- 3 files changed, 177 insertions(+), 50 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index 4dda9c8140..c122748fe8 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -11,12 +11,36 @@ Run it: `bash probe.sh` (needs network; ~2 minutes). It scaffolds a real `create project, drops each candidate config shape in, and runs `next build`, `next dev`, and a native `import()` against each. -**The exit status is the evidence** — `0` the served-route and `AGENTS.md` claims held, `1` one -of them failed, `2` it could not be checked. The variant table below is printed output you read; -the final section is an assertion the script fails on. It uses a fresh marker per run on a port -it proves free first, because an earlier version of this probe reported green by reaching a stale -dev server left over from a previous run — a result from a neighbour of the claim, which is the -whole failure it exists to catch. +**The exit status is the evidence, and every claim below feeds it** — `0` every row of the table +behaved as documented *and* the served-route and `AGENTS.md` assertions held, `1` something +disagreed with what this file claims, `2` the run could not be completed. Each variant declares +the outcome this 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 what we +documented" is. + +Two earlier versions of this probe could report green for claims they had not proved, which is +why the status is wired this way: + +- it reached a **stale dev server** left over from a previous run, so it now uses a fresh marker + per run on a port it proves free first; +- it **discarded `next build`'s status** through a pipeline and let a rejected `import()` resolve, + so those two — the exact claims the spec cites this POC for — sat outside the exit code. + +Wiring those in immediately earned its keep: the first run of the accumulating version exited `1` +on the `.ts, no type field` row, and the cause was the probe, not the finding. Its `import()` check +called `process.exit(0)` in the `.then()`, which cut off `MODULE_TYPELESS_PACKAGE_JSON` before Node +flushed it — the warning is emitted asynchronously. The check now sets `process.exitCode` and lets +the process drain. A probe that could not fail would have recorded "clean" for the one variant +whose entire purpose is to warn. + +It also serves **both route files with the canonical route exports** (`runtime = "nodejs"`, +`dynamic = "force-dynamic"`) rather than a hand-made bare route, because an earlier version +exercised a shape the spec does not specify. + +**What this does not prove:** that `force-dynamic` prevents response buffering. That is Next's +documented behaviour and it needs a real streamed model response to observe — §10's goal check +owns it, by requiring the response to render *incrementally*. This probe establishes only that +the specified route shape builds and serves the config module. ## What it settled @@ -28,8 +52,9 @@ whole failure it exists to catch. | **`fsdev.config.ts` + `"type": "module"` in the manifest** | **passes** | **clean, no warning** | **chosen (§6 decision 4)** | | `fsdev.config.ts`, no `type` field | passes | loads, but emits `MODULE_TYPELESS_PACKAGE_JSON` on every CLI command | rejected | -The chosen variant was also run end to end: `next dev` served `GET /api/flows`, and the route -returned the marker proving the config module was the one that loaded. +The chosen variant is also run end to end against the shape the spec specifies: `next dev` serves +both `GET /api/flows` (the bare route) and `GET /api/flows/sessions/abc` (the catch-all), and each +returns this run's unique marker, proving the config module that loaded is the one this run wrote. ## Four things it found that nothing in the epic or the sibling specs knew diff --git a/spec-poc/FIX-548-next-template-shape/probe.sh b/spec-poc/FIX-548-next-template-shape/probe.sh index bd26e1c965..b319f1b9e7 100644 --- a/spec-poc/FIX-548-next-template-shape/probe.sh +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -1,16 +1,30 @@ #!/usr/bin/env bash -# Reproduces every row of README.md's table. Needs network. ~2 minutes. +# Reproduces every row of README.md's table. Needs network. ~3 minutes. # # bash probe.sh [workdir] # -# Scaffolds a real create-next-app@16.3.1 project, then for each candidate shape of -# the FSD config runs `next build` (the bundler + TypeScript half) and a native -# `import()` (the fsdev CLI half). Ends with a `next dev` + curl on the chosen -# shape, so the mounted route is proven to serve, not just to compile. +# Scaffolds a real create-next-app@16.3.1 project, then for each candidate shape +# of the FSD config runs `next build` (the bundler + TypeScript half) and a native +# `import()` (the fsdev CLI half). Ends by serving the shape the spec specifies — +# both route files, with the canonical route exports — and asserting the mounted +# route returns this run's config module. +# +# EXIT STATUS IS THE EVIDENCE. Every check below feeds it: +# 0 every variant matched its expected outcome AND the served-route and +# AGENTS.md assertions held +# 1 at least one check disagreed with what the README claims +# 2 the run could not be completed (scaffold/install failed, no free port) +# Each variant declares the outcome README.md claims for it, and a variant that +# behaves differently fails the probe — including the two that are EXPECTED to +# fail to build. "The build broke" is not automatically a probe failure here; +# "the build did something other than what we documented" is. set -u +RC=0 +fail() { echo " MISMATCH — $1"; RC=1; } + WORK="${1:-$(mktemp -d)}" -mkdir -p "$WORK" || exit 1 +mkdir -p "$WORK" || exit 2 APP="$WORK/probe" rm -rf "$APP" echo "workdir: $WORK" @@ -20,9 +34,9 @@ echo "workdir: $WORK" npx --yes create-next-app@16.3.1 "$APP" \ --ts --app --no-tailwind --no-eslint --no-biome --no-src-dir \ --no-react-compiler --no-rspack --import-alias "@/*" \ - --agents-md --skip-install --disable-git || exit 1 + --agents-md --skip-install --disable-git || exit 2 -cd "$APP" || exit 1 +cd "$APP" || exit 2 echo "=== what create-next-app wrote (findings 1-4) ===" ls -a | tr '\n' ' '; echo @@ -31,10 +45,33 @@ echo ".gitignore env line:"; grep -n '^\.env' .gitignore || echo " (none)" echo "manifest type field: $(node -p "require('./package.json').type ?? '(absent)'")" echo "tsconfig include: $(node -p "JSON.stringify(require('./tsconfig.json').include)")" -mkdir -p lib "app/api/flows" +# The route shape the spec specifies: a catch-all plus a sibling bare route, both +# carrying the canonical exports from packages/next/README.md. An earlier version +# of this probe exercised only a hand-made bare route, so its green said nothing +# about the shape the spec actually asks for. +mkdir -p lib "app/api/flows/[...path]" +cat > "app/api/flows/[...path]/route.ts" <<'EOF' +import { flowstate } from "@/lib/flowstate"; + +// Stands in for `export const { GET, POST, PATCH, DELETE } = createNextHandler(flowstate)`. +// The adapter is not installed here (no FSD deps in this probe), but the exports +// beside it are the specified shape and are what this file exists to exercise. +export const runtime = "nodejs"; +export const dynamic = "force-dynamic"; + +export async function GET(_req: Request, ctx: { params: Promise<{ path: string[] }> }) { + const { path } = await ctx.params; + const router = await flowstate.getRouter(); + return new Response(`${flowstate.marker}:catchall:${path.join("/")}:${(await router.GET()).status}`); +} +EOF cat > app/api/flows/route.ts <<'EOF' import { flowstate } from "@/lib/flowstate"; + +// The sibling bare route: a required catch-all cannot match zero segments. +export const runtime = "nodejs"; export const dynamic = "force-dynamic"; + export async function GET() { const router = await flowstate.getRouter(); return new Response(`${flowstate.marker}:${(await router.GET()).status}`); @@ -51,7 +88,7 @@ CONFIG_BODY='const flowstate = { }; export default flowstate;' -npm install --no-audit --no-fund || exit 1 +npm install --no-audit --no-fund || exit 2 set_tsconfig_flag() { # $1 = true|false node -e "const f='tsconfig.json',fs=require('fs');const j=JSON.parse(fs.readFileSync(f,'utf8')); @@ -63,26 +100,56 @@ set_pkg_type() { # $1 = module|none if ('$1'==='module') j.type='module'; else delete j.type; fs.writeFileSync(f,JSON.stringify(j,null,2)+'\n')" } -variant() { # $1 = label, $2 = config filename, $3 = import specifier + +# $1 label · $2 config filename · $3 import specifier +# $4 expected build: pass|fail · $5 expected import: clean|warn +variant() { + local label="$1" cfg="$2" spec="$3" want_build="$4" want_import="$5" rm -f fsdev.config.ts fsdev.config.mts - printf '%s\n' "$CONFIG_BODY" > "$2" - printf 'export { default as flowstate } from "%s";\n' "$3" > lib/flowstate.ts + printf '%s\n' "$CONFIG_BODY" > "$cfg" + printf 'export { default as flowstate } from "%s";\n' "$spec" > lib/flowstate.ts echo - echo "=== variant: $1 ===" - 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 + echo "=== variant: $label ===" + + # Status via a temp file, not a pipeline — a pipe would report grep's status. + npx next build > build.log 2>&1 + local build_status=$? + grep -E "error TS|Module not found|Failed to|Compiled successfully|Route \(app\)" 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" + + # A rejected import must fail the probe; an expected warning must be present. + # Set exitCode and return — never process.exit() here. Node emits + # MODULE_TYPELESS_PACKAGE_JSON asynchronously, and an immediate exit() cuts it + # off before it reaches stderr, which made this probe report "clean" for the + # variant whose whole point is that it warns. + 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 + local import_status=$? + local got_import + if [ $import_status -ne 0 ]; then + got_import=error + elif grep -q MODULE_TYPELESS_PACKAGE_JSON import.log; then + got_import=warn + else + got_import=clean + fi + echo " native import: $got_import (expected $want_import)" + [ "$got_import" = "$want_import" ] || fail "$label: import $got_import, README claims $want_import" } set_pkg_type none set_tsconfig_flag false -variant ".mts, explicit .mts extension" fsdev.config.mts "../fsdev.config.mts" -variant ".mts, extensionless import" fsdev.config.mts "../fsdev.config" +variant ".mts, explicit .mts extension" fsdev.config.mts "../fsdev.config.mts" fail clean +variant ".mts, extensionless import" fsdev.config.mts "../fsdev.config" fail clean set_tsconfig_flag true -variant ".mts + allowImportingTsExtensions" fsdev.config.mts "../fsdev.config.mts" +variant ".mts + allowImportingTsExtensions" fsdev.config.mts "../fsdev.config.mts" pass clean set_tsconfig_flag false -variant ".ts, no type field" fsdev.config.ts "../fsdev.config" +variant ".ts, no type field" fsdev.config.ts "../fsdev.config" pass warn set_pkg_type module -variant ".ts + type:module <-- CHOSEN" fsdev.config.ts "../fsdev.config" +variant ".ts + type:module <-- CHOSEN" fsdev.config.ts "../fsdev.config" pass clean echo echo "=== chosen shape, served for real ===" @@ -102,24 +169,24 @@ printf '\n\nFSD SECTION SENTINEL\n\n' >> AGENT npx next dev --port "$PORT" > dev.log 2>&1 & DEV_PID=$! sleep 18 -BODY=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows") -echo " GET /api/flows -> $BODY" -RC=0 -case "$BODY" in - "$MARKER":200) echo " PASS — the route served this run's config module" ;; - *) echo " FAIL — expected $MARKER:200"; RC=1 ;; -esac + +BARE=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows") +echo " GET /api/flows -> $BARE" +[ "$BARE" = "$MARKER:200" ] || fail "bare route: expected $MARKER:200" + +CATCH=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows/sessions/abc") +echo " GET /api/flows/sessions/abc -> $CATCH" +[ "$CATCH" = "$MARKER:catchall:sessions/abc:200" ] || fail "catch-all route: expected $MARKER:catchall:sessions/abc:200" + FSD_N=$(grep -c 'FSD SECTION SENTINEL' AGENTS.md) NEXT_N=$(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md) echo " FSD section survived next dev: $FSD_N (expect 1)" echo " next's own block still there: $NEXT_N (expect 1)" -[ "$FSD_N" = 1 ] || { echo " FAIL — appended FSD section did not survive"; RC=1; } -[ "$NEXT_N" = 1 ] || { echo " FAIL — next's own block is not intact"; RC=1; } +[ "$FSD_N" = 1 ] || fail "appended FSD section did not survive next dev" +[ "$NEXT_N" = 1 ] || fail "next's own block is not intact" + kill "$DEV_PID" 2>/dev/null; wait "$DEV_PID" 2>/dev/null -# The exit status is the evidence. This script is cited by the spec and the PR as -# the thing a reader runs, so it must not be able to report green for a claim it -# did not prove: 0 = the served-route and AGENTS.md claims held, 1 = one failed, -# 2 = could not be checked at all. -[ "$RC" = 0 ] && echo " probe: PASS" || echo " probe: FAIL" +echo +[ "$RC" = 0 ] && echo "probe: PASS" || echo "probe: FAIL" exit "$RC" diff --git a/spec/FIX-548.md b/spec/FIX-548.md index dbd82fe65e..70bc74a49a 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -345,8 +345,8 @@ manifest key. This is the entire product surface: | `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 | -| `app/api/flows/route.ts` | the sibling bare route. `list_flows` is registered as `GET /` on the mount base and the client's `listFlows()` requests it, but a required catch-all cannot match zero segments. `@flow-state-dev/next` exports no bare handler (only `@flow-state-dev/vercel` does), so this one forwards by hand with a comment saying why | +| `app/api/flows/[...path]/route.ts` | `createNextHandler(flowstate)` from `@flow-state-dev/next` — the platform-agnostic adapter, no Vercel assumption. **Carries the canonical route exports beside it: `runtime = "nodejs"` and `dynamic = "force-dynamic"`.** Not decoration — `packages/next/README.md` ships exactly those three lines, and `examples/hello-chat` documents why: without `force-dynamic` Next may buffer the response body, and a buffered body turns token-by-token streaming into one delivery at the end. That is the epic's headline outcome failing while every wiring check passes | +| `app/api/flows/route.ts` | the sibling bare route. `list_flows` is registered as `GET /` on the mount base and the client's `listFlows()` requests it, but a required catch-all cannot match zero segments. `@flow-state-dev/next` exports no bare handler (only `@flow-state-dev/vercel` does), so this one forwards by hand with a comment saying why — carrying the same route exports as its sibling | | `app/page.tsx` | the chat page. `FlowProvider` + `useFlow` + `useSession` + `ItemsRenderer` from `@flow-state-dev/react`, no other imports (decision 6). Overwrites `create-next-app`'s stock page — permitted, because this is a directory this command created seconds ago | | *manifest* | `"type": "module"` added — decision 4. Nothing else; dependencies and the lockfile are the package manager's | @@ -416,7 +416,18 @@ package generates a project; it changes no framework behaviour. | 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). | + +**The credential stop — after the scaffold exists, before the key is written.** Its own +category, because it is neither of the other two and putting it in either produced a +contradiction in an earlier draft of this section: the check can only run once +`create-next-app` has made the directory and written `.gitignore`, so it cannot be a refusal +that "leaves the disk untouched", and deleting the scaffold to make it one would contradict the +no-rollback rule directly below. + +| Case | Expected | +|---|---| +| `.env.local` is about to be written and git would not ignore it | Add the ignore entry, then write the key. This is the ordinary path, not an error — `create-next-app`'s own `.gitignore` already carries `.env*` (verified), so the entry is usually already there and this is an assertion that it is. | +| 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 command to finish. Never write the key "and warn" — the warning scrolls away and the credential does not. | **Failures after work has started — nothing rolls back:** @@ -430,9 +441,13 @@ package generates a project; it changes no framework behaviour. | `-y` with no key in flags or environment | Scaffold completes. `.env.local` carries the empty key line init writes, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. | | 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 owns the block). | -**Taxonomy:** refusals leave the disk untouched; failures leave a directory the developer can -inspect and finish by hand. Nothing is cleaned up behind the user, because deleting a directory -a stranger may have put something in is worse than leaving one they can `rm`. +**Taxonomy — three categories, and the middle one exists because the first two could not hold +it.** Refusals happen before anything is created and leave the disk untouched. The credential +stop happens after the scaffold exists and leaves it there, minus the key. Failures leave a +directory the developer can inspect and finish by hand. Nothing is ever cleaned up behind the +user, because deleting a directory a stranger may have put something in is worse than leaving +one they can `rm` — which is also why the credential stop does not "undo" the scaffold to +qualify as a refusal. ### 10. Testing strategy @@ -443,7 +458,10 @@ ask above is pricing: it is per template *times* per provider, not per template: - In an **empty directory, with no provider key in the environment**, run the published invocation, supply the key at its prompt, then run the printed dev command and send a message - in the browser: a streamed model response renders in the page. + in the browser: a streamed model response renders in the page — and **renders + incrementally**, token by token, not as one block when the response completes. The second half + is the only check anywhere that would catch a missing `force-dynamic`; everything else passes + with a buffered body. - **Through the mounted route, not through `fsdev run`.** The provider SDK is imported dynamically by package name inside the Next.js server bundle, where `createModelResolver` carries an explicit fallback for it failing to resolve (§12). A CLI-only check passes with @@ -467,8 +485,18 @@ init, in a temporary directory, with no network and no install, **except the thr file names - ***real*: the config loads under a native `import()` with no warning** — asserted on stderr, because `MODULE_TYPELESS_PACKAGE_JSON` is a first-hour wart that no functional test fails on +- **both route files carry `runtime = "nodejs"` and `dynamic = "force-dynamic"`** — asserted on + the generated files against `packages/next/README.md`'s canonical shape. Cheap and worth it + because the failure it guards is invisible to every other check here: without `force-dynamic` + the wiring is correct, the response is correct, and only the *timing* is wrong — tokens arrive + in one lump at the end instead of streaming. A CI stub cannot see that, and a human demoing it + might not either - ***real*: `git check-ignore .env.local` succeeds before the key is written** — executed, not read, and specifically before, because ordering is the whole guarantee (decision 7) +- **the credential stop leaves a usable scaffold and no key** — run it against a scaffold whose + ignore entry cannot be established, and assert the directory is intact, `.env.local` holds no + key, and the output names the missing line. This is the §9 case that is neither a refusal nor + a failure, so nothing else in this list covers it - **the template is written before init is called** — asserted on call ordering, not end state, since a package that wrote afterwards and deleted init's files would leave an identical directory @@ -589,6 +617,13 @@ runs or six, and whether decision 2b's flag exists. Nothing else. - `@flow-state-dev/next` exports only `createNextHandler` (catch-all); the bare-path handler exists only in `@flow-state-dev/vercel`. Both in-repo mounts hand-write the bare forwarder, with a comment saying why. +- **The canonical mount is three exports, not one.** `packages/next/README.md` ships + `createNextHandler(flowstate)` alongside `runtime = "nodejs"` and `dynamic = "force-dynamic"`, + and `examples/hello-chat`'s catch-all carries `force-dynamic` with the reason in a comment: + without it Next may buffer the response body and defeat token-by-token delivery. The published + Vercel quick-start adds `maxDuration = 300` on top; that one is deployment-shaped rather than + correctness-shaped, so the template takes the two from the platform-agnostic README and leaves + `maxDuration` to whoever deploys. - Both in-repo Next apps reconcile the root config with the routes through a `lib/` re-export; the published quick-start does not, and §11 corrects it. - `examples/hello-chat` is the shape reference for the flow and page, not the content reference: From c67c0636618d0808f5391653c3443db03aac20a3 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 00:40:49 +0000 Subject: [PATCH 06/30] spec(FIX-548): make the unscoped publish a prerequisite, and correct an inherited ownership claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 ` resolves to the UNSCOPED `create-` — `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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 87 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 74 insertions(+), 13 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 70bc74a49a..ee109880cc 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -51,16 +51,24 @@ file list short and refusing surface — including a `--template` flag with one ### 6. Decisions & rules — the sign-off surface -1. **The package is `create-flow-state`, published unscoped.** Invoked as `npm create +1. **One package, `create-flow-state`, published unscoped.** Invoked as `npm create flow-state my-app`, or `npx create-flow-state my-app`. - *Rejected:* `create-fsd-app` and `create-fsdev-app` (both considered by FIX-1162), and - publishing under the `@flow-state-dev/` scope as this spec's previous draft proposed. - *Locks in:* the headline command matches the published brand and reads as a sentence. The - owner holds `create-flow-state`, `create-fsd-app` and `flow-state-app` on npm as of today, so - **FIX-1162 no longer gates this issue by any route** — not just the one the previous draft - worked around. It also makes FIX-1162's recorded finding stale: `create-fsd-app` was reported - unobtainable and it is now ours, so the epic's `create-fsdev-app` prose and FIX-1162's own - proposal both need correcting (§12). + *Rejected:* publishing under the `@flow-state-dev/` scope (this spec's previous draft), **and + the two-package shape** — a scoped package plus an unscoped alias — which was the natural + compromise while the short name was believed unobtainable. Also rejected: `create-fsd-app` + and `create-fsdev-app` (both considered by FIX-1162). + *Locks in:* **the unscoped name is load-bearing, not cosmetic.** `npm create ` resolves + to the *unscoped* `create-`; a scoped publish claims nothing outside its scope, exactly + as publishing `@flow-state-dev/cli` would not claim `fsdev`. Measured rather than assumed: + `npm create flow-state-nonexistent-xyz123` requests + `registry.npmjs.org/create-flow-state-nonexistent-xyz123`. So a scoped-only publish leaves + this spec's headline command — the one thing a stranger types — resolving to a package that + does not exist. The two-package shape would work but buys nothing: nobody would be told to + type the scoped form, so the second package exists only to be unused (tenet 3). One package + makes the documented command and the published artifact the same thing. + **This is now a hard prerequisite rather than a preference, and §12 carries it as a + dependency** — the previous draft treated the name as a convenience that removed a blocker, + which is what let a scoped fallback look harmless. 2. **One template ships: the Next.js chat app. The framework-neutral Node API template is cut from v1.** *This reverses epic theme 2 and is the ask on this PR — see the framing below.* @@ -302,6 +310,12 @@ no runtime dependency on this monorepo beyond the published `@flow-state-dev/cli nothing it writes into the generated project imports anything of ours that is not on npm (epic theme 4). +**Its manifest `name` is the bare `create-flow-state` — the one package in this repository that +is not `@flow-state-dev/*`.** Called out because every other package here is scoped and the +convention is otherwise right to follow (BP-008 conformance): scoping this one would silently +break `npm create flow-state`, and the directory being `packages/create-flow-state/` does not +by itself set the published name. + ```mermaid flowchart TB A[resolve invocation
name · provider · key · package manager] --> B[create the bare app
create-next-app, install skipped, every flag explicit] @@ -550,7 +564,26 @@ subprocesses stubbed. init's library seam exists, and cannot merge before init merges. §7's step-4 table is the required interface; it is **smaller than the previous draft's**, because decision 3 moved the config and the mount here. -- **FIX-1162 no longer gates this issue at all** (decision 1). The owner holds the name. +- **Publishing the unscoped `create-flow-state` is a hard prerequisite** (decision 1). Not a + naming preference: without it the headline command resolves to nothing, and there is no + in-scope workaround, because a scoped publish cannot serve `npm create flow-state`. What is + and is not established, stated separately because the difference matters: + - **Verified today against the registry:** `create-flow-state` returns 404, as do + `flow-state-app`, `flow-state`, `fsdev`, and every `@flow-state-dev/*` package. 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, and nothing is published — so "the owner holds it" cannot yet be + confirmed from outside. The epic coordinator has the ownership question with the owner. + - **Verified, and it corrects a claim this spec previously repeated:** `create-fsd-app` is + **not** ours. `create-fsd-app@1.1.2` exists, published 2024-10-18 by an unrelated maintainer + (`keyready`), and is a React/Vite starter. FIX-1162's original finding was right; the later + report that we had acquired it does not survive checking. This does not affect the chosen + name, and it is the reason the bullet above distinguishes verified from asserted at all — + the same assumption was already wrong once. + - **Deliberately not designed around.** No fallback name, no scoped alias, no conditional + branch. If the name turns out not to be obtainable, that is a different spec, and inventing + a fallback here would spread a contingency through §5, §6, §7, §9 and §11 to hedge a + question that will be answered before anything is built. **Cross-issue notes — raised, not decided here.** @@ -567,9 +600,17 @@ subprocesses stubbed. measurements. - **The next-steps block owes a two-process line.** Both commands it prints for a Next host open the same development file store (§9). FIX-1159 owns the block's wording. -- **The epic's prose and FIX-1162's proposal are stale on the name.** Both say - `create-fsdev-app` on the strength of `create-fsd-app` being unobtainable. The owner now holds - `create-flow-state`, `create-fsd-app` and `flow-state-app`; decision 1 picks the first. +- **The epic's prose is stale on the name; FIX-1162's original finding was not.** The epic says + `create-fsdev-app`, adopted because `create-fsd-app` was unobtainable — and that premise is + **correct** (verified: held by a third party since 2024). What changed is the choice, not the + finding: decision 1 takes `create-flow-state`, which is unpublished and available. FIX-1162's + work is therefore superseded on *which* name, not corrected on its facts. +- **The unscoped-vs-scoped point applies beyond this issue.** `npm create ` and a bare + `fsdev` on the path both need unscoped names, and nothing under `@flow-state-dev/` is + published either. FIX-1159's printed commands (`npm exec fsdev …`) depend on the CLI package + resolving a `fsdev` bin, which is a different question from owning the `fsdev` *package* name + — worth FIX-1162 stating explicitly which names the launch actually requires, since this + issue only needs one of them. - **`create-next-app` writes `AGENTS.md` and `CLAUDE.md` itself**, and `next dev` re-adds its own block. Epic Q1's append-never-overwrite guarantee therefore binds the *greenfield* path too, which the epic files under brownfield. The POC confirmed an appended FSD section survives @@ -589,6 +630,14 @@ runs or six, and whether decision 2b's flag exists. Nothing else. under a native `import()` with no warning; without the `type` field the same file loads but emits `MODULE_TYPELESS_PACKAGE_JSON`. Confirmed end to end: `next dev` served `GET /api/flows` through the config module. +- **`npm create ` resolves to the unscoped `create-`**, measured: + `npm create flow-state-nonexistent-xyz123` requests + `registry.npmjs.org/create-flow-state-nonexistent-xyz123`. A scoped package cannot serve that + invocation form, which is why decision 1's unscoped publish is a prerequisite rather than a + preference. +- **Registry state, checked today:** `create-flow-state`, `flow-state-app`, `flow-state`, + `fsdev` and `@flow-state-dev/cli` all return 404; `create-fsd-app@1.1.2` exists and belongs to + an unrelated maintainer since 2024-10-18. - `packages/cli` has **no `init` command today** (`src/commands/` holds `run`, `dev`, `serve`, `chat`, `block`, `ui`, `benchmark`), so exposing init as a library is an addition to that surface, not a change to it. @@ -668,6 +717,18 @@ runs or six, and whether decision 2b's flag exists. Nothing else. turned up that `create-next-app` writes its own `AGENTS.md` and `CLAUDE.md`, that `next dev` re-adds its block, and that its `.gitignore` already ignores `.env*` — so the greenfield path *appends* to an agent-instructions file, a case the epic had filed under brownfield. +- **The unscoped name became a prerequisite, and one inherited fact was corrected.** The previous + draft said "published unscoped" but argued it as brand fit, which left the scoped form looking + like a harmless fallback — it is not: `npm create ` resolves to the *unscoped* + `create-`, so a scoped publish would leave the headline command pointing at nothing. + Decision 1 now says so with the measurement, and rejects the scoped-plus-alias compromise as + a second package nobody would be told to type. §12 carries the publish as a hard dependency, + separating what is verified (every relevant name 404s; nothing has ever been published under + this project) from what is asserted (that the name is ours). While checking, the claim that we + had acquired `create-fsd-app` turned out to be false — it has belonged to an unrelated + maintainer since 2024, so FIX-1162's original finding stands and only the *choice* of name + moved. No fallback is designed for the name not being obtainable; that would spread a + contingency through five sections to hedge a question answered before anything is built. - **Three earlier findings carried forward rather than lost.** The credential hazard became decision 7 and an executed `git check-ignore` assertion instead of an assumption about someone else's file. Provider/model alignment became decision 5's intent map, with the goal check run From a1c1553e8cac73ff6ec40d331007c21ddc030742 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 00:47:02 +0000 Subject: [PATCH 07/30] =?UTF-8?q?spec(FIX-548):=20record=20the=20one-comma?= =?UTF-8?q?nd=20finding=20in=20=C2=A713=20as=20resolved=20upstream?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index ee109880cc..1f86512625 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -688,7 +688,29 @@ runs or six, and whether decision 2b's flag exists. Nothing else. ### 13. Review notes for the implementer -*Below-the-bar spec-PR feedback lands here verbatim once review runs. Empty at drafting.* +Spec-PR feedback recorded rather than folded. These are inputs, not instructions. + +- **"The one-command promise disagrees with the stopping point"** — codex, on §2. The finding: + §2 says the command leaves the developer looking at the feature streaming, while §5's + transcript ends after scaffolding and prints `npm run dev`, and §10 starts it separately. Two + ways out were offered — have the scaffolder start and open the app, or restate the outcome as + a ready-to-run project. + + **Neither was taken; the mismatch is upstream and is being fixed there.** Checked directly: + 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** yields a streamed model + response" (line 57). The Proof is the precise statement and was deliberately sharpened at epic + review round 3, so §1's Outcome is the loose half — the epic-agent is folding it. This spec + already matches the Proof: §5's transcript is the exact stopping point and §10 measures from + it. + + **Do not add auto-start or auto-open.** `create-next-app` and `create-vite` both stop and + print the dev command, and taking the first option would be scope growth bought with a + reviewer's phrasing rather than a requirement. Recorded here so it does not return a third + time. + + *If §2's compression still reads as overclaiming once the epic lands, the fix is one sentence + in §2 — never a behaviour change in the scaffolder.* --- From 4c2e3969f971524bd26b8155e00d31df3060dbf8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 00:53:16 +0000 Subject: [PATCH 08/30] spec-poc(FIX-548): assert the failure reason and the scaffold facts, not just the status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Spec-review round 2. Both findings are the same class that has now paid off three times on this branch: a check that cannot fail, guarding a fact the spec cites. 1. The failing .mts variants were accepted on ANY nonzero exit, so a shared route-file typo, a dependency problem, or a future Next regression would all reduce to `fail` and read as "matched the documented result" — the probe could exit 0 without ever reproducing TS5097 or the module-resolution behaviour that is the entire justification for choosing fsdev.config.ts + "type": "module". Each variant now declares the diagnostic the README claims for it: /error TS5097/ and /Module not found.*fsdev\.config/ for the two documented failures, and //api/flows/ for the pass rows, so a pass proves the route compiled rather than that the process exited 0. 2. The scaffold-discovery checks only printed. Worse, they were self-concealing: this script's own later append recreates AGENTS.md and `next dev` restores Next's block, so a check placed at the end would go green exactly when the pinned scaffolder had stopped writing the files. All four are now assertions, and they run BEFORE this script writes anything — AGENTS.md exists, it carries the nextjs-agent-rules block, CLAUDE.md exists, and .gitignore ignores .env*. The first matters most: the spec's append-not-create design rests on it, and nothing would have told us if it stopped being true. Verified both directions rather than only the happy one. Full run: five variants match on status AND diagnostic, both routes serve this run's marker, probe: PASS, exit 0. Negative check on the six new assertions — AGENTS.md missing, CLAUDE.md missing, .gitignore rule gone, nextjs block absent, a build that fails for the wrong reason, and a "pass" that emitted no route — all six return 1. Pass rows now also show both routes compiling (/api/flows and /api/flows/[...path]), which the earlier single-route probe could not show. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 22 ++++++-- spec-poc/FIX-548-next-template-shape/probe.sh | 54 +++++++++++++++---- 2 files changed, 62 insertions(+), 14 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index c122748fe8..ed82443682 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -12,11 +12,17 @@ project, drops each candidate config shape in, and runs `next build`, `next dev` `import()` against each. **The exit status is the evidence, and every claim below feeds it** — `0` every row of the table -behaved as documented *and* the served-route and `AGENTS.md` assertions held, `1` something -disagreed with what this file claims, `2` the run could not be completed. Each variant declares -the outcome this 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 what we -documented" is. +behaved as documented *and* the scaffold-discovery and served-route assertions held, `1` +something disagreed with what this file claims, `2` the run could not be completed. + +Each variant declares both the outcome **and the diagnostic** this README claims for it, so +**"the build failed" is not automatically a probe failure** — two variants are supposed to fail — +and equally, a failure for the *wrong reason* is not a pass. A shared route-file typo, a +dependency problem, or a future Next regression would otherwise reduce to `fail` and be read as +"matched the documented result", letting the probe go green without ever reproducing `TS5097` or +the module-resolution behaviour that is the whole justification for the chosen shape. Pass rows +assert the route compiled (`/api/flows` in the build output), not merely that the process +exited 0. Two earlier versions of this probe could report green for claims they had not proved, which is why the status is wired this way: @@ -58,6 +64,12 @@ returns this run's unique marker, proving the config module that loaded is the o ## Four things it found that nothing in the epic or the sibling specs knew +All four are **asserted, and asserted before this script writes anything** — not printed for a +reader to eyeball. Ordering is the whole point: the probe later appends its own FSD section to +`AGENTS.md`, and `next dev` restores Next's block, so a check placed at the end would report +green exactly when the pinned scaffolder had stopped writing these files. Finding 1 especially, +because the spec's append-not-create design rests on it. + 1. **`create-next-app@16` writes `AGENTS.md` itself**, with its own delimited block (``), and **`next dev` re-adds that block on every run**. So the greenfield Next path is an *append* to an existing `AGENTS.md`, never a create — the case diff --git a/spec-poc/FIX-548-next-template-shape/probe.sh b/spec-poc/FIX-548-next-template-shape/probe.sh index b319f1b9e7..79a897d03b 100644 --- a/spec-poc/FIX-548-next-template-shape/probe.sh +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -40,11 +40,28 @@ cd "$APP" || exit 2 echo "=== what create-next-app wrote (findings 1-4) ===" ls -a | tr '\n' ' '; echo -echo "AGENTS.md delimiters:"; grep -o 'BEGIN:[a-z-]*' AGENTS.md || echo " (none)" -echo ".gitignore env line:"; grep -n '^\.env' .gitignore || echo " (none)" echo "manifest type field: $(node -p "require('./package.json').type ?? '(absent)'")" echo "tsconfig include: $(node -p "JSON.stringify(require('./tsconfig.json').include)")" +# ASSERTED, NOT PRINTED — and asserted HERE, before this script writes anything. +# The greenfield-appends design rests on create-next-app writing its own AGENTS.md, +# and this check is self-concealing if it runs later: the append near the end +# recreates AGENTS.md, and `next dev` restores Next's own block. A probe that +# checked at the end would go green exactly when the pinned scaffolder had stopped +# doing the thing the spec depends on. +[ -f AGENTS.md ] \ + && echo " AGENTS.md: present" \ + || fail "create-next-app no longer writes AGENTS.md — the spec's append-not-create premise is dead" +grep -q 'BEGIN:nextjs-agent-rules' AGENTS.md 2>/dev/null \ + && echo " AGENTS.md: carries next's own delimited block" \ + || fail "AGENTS.md has no nextjs-agent-rules block — the append target is not what the spec describes" +[ -f CLAUDE.md ] \ + && echo " CLAUDE.md: present" \ + || fail "create-next-app no longer writes CLAUDE.md — README finding 2 is stale" +grep -qE '^\.env' .gitignore 2>/dev/null \ + && echo " .gitignore: ignores .env* ($(grep -nE '^\.env' .gitignore | head -1))" \ + || fail "create-next-app's .gitignore no longer ignores .env* — spec decision 7 loses its host-supplied entry" + # The route shape the spec specifies: a catch-all plus a sibling bare route, both # carrying the canonical exports from packages/next/README.md. An earlier version # of this probe exercised only a hand-made bare route, so its green said nothing @@ -103,8 +120,16 @@ set_pkg_type() { # $1 = module|none # $1 label · $2 config filename · $3 import specifier # $4 expected build: pass|fail · $5 expected import: clean|warn +# $6 grep -E pattern that MUST appear in build.log for this variant +# +# $6 is what makes a `fail` row mean something. Without it any nonzero exit — +# a typo in the shared route files, a dependency failure, a future Next +# regression — reads as "matched the documented result", and the probe could go +# green without ever reproducing TS5097 or the module-resolution behaviour that +# is the entire justification for decision 4. Pass rows assert the route +# compiled, not merely that the process exited 0. variant() { - local label="$1" cfg="$2" spec="$3" want_build="$4" want_import="$5" + local label="$1" cfg="$2" spec="$3" want_build="$4" want_import="$5" want_diag="$6" rm -f fsdev.config.ts fsdev.config.mts printf '%s\n' "$CONFIG_BODY" > "$cfg" printf 'export { default as flowstate } from "%s";\n' "$spec" > lib/flowstate.ts @@ -114,11 +139,17 @@ variant() { # Status via a temp file, not a pipeline — a pipe would report grep's status. npx next build > build.log 2>&1 local build_status=$? - grep -E "error TS|Module not found|Failed to|Compiled successfully|Route \(app\)" build.log | head -4 | sed 's/^/ /' + 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" + if grep -qE "$want_diag" build.log; then + echo " diagnostic: matched /$want_diag/" + else + fail "$label: build was '$got_build' but /$want_diag/ never appeared — the documented cause is unproven" + fi + # A rejected import must fail the probe; an expected warning must be present. # Set exitCode and return — never process.exit() here. Node emits # MODULE_TYPELESS_PACKAGE_JSON asynchronously, and an immediate exit() cuts it @@ -142,14 +173,19 @@ variant() { set_pkg_type none set_tsconfig_flag false -variant ".mts, explicit .mts extension" fsdev.config.mts "../fsdev.config.mts" fail clean -variant ".mts, extensionless import" fsdev.config.mts "../fsdev.config" fail clean +variant ".mts, explicit .mts extension" fsdev.config.mts "../fsdev.config.mts" fail clean \ + "error TS5097" +variant ".mts, extensionless import" fsdev.config.mts "../fsdev.config" fail clean \ + "Module not found.*fsdev\.config" set_tsconfig_flag true -variant ".mts + allowImportingTsExtensions" fsdev.config.mts "../fsdev.config.mts" pass clean +variant ".mts + allowImportingTsExtensions" fsdev.config.mts "../fsdev.config.mts" pass clean \ + "/api/flows" set_tsconfig_flag false -variant ".ts, no type field" fsdev.config.ts "../fsdev.config" pass warn +variant ".ts, no type field" fsdev.config.ts "../fsdev.config" pass warn \ + "/api/flows" set_pkg_type module -variant ".ts + type:module <-- CHOSEN" fsdev.config.ts "../fsdev.config" pass clean +variant ".ts + type:module <-- CHOSEN" fsdev.config.ts "../fsdev.config" pass clean \ + "/api/flows" echo echo "=== chosen shape, served for real ===" From 836a30569b9b3271c82063f081cb1575ba70c907 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 01:21:09 +0000 Subject: [PATCH 09/30] spec-poc(FIX-548): make every README claim assertion-backed or delete it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Conditional third review round. Applied as a principle rather than as four patches, because patching instances is what produced four rounds of the same finding: a check that cannot fail the claim it is cited for. Went through the README claim by claim; each is now either backed by an assertion that fails the run, or gone. FIXED, because the design rests on it: - The .env check accepted any line starting with `.env`, including `.env.example` — which does NOT ignore `.env.local`. The credential stop (decision 7) could therefore rest on a premise the probe reported as true. It now asks `git check-ignore` about `.env.local` itself, in a throwaway repo (the scaffold runs with --disable-git), which is the same question the real command has to answer before writing the key. Decision 7 and §9 now specify the check that way rather than by the presence of a rule that looks right. DELETED, because the probe does not establish them: - "`--agents-md` defaults on." The invocation passes the flag explicitly, as the spec requires of every flag, so nothing here speaks to the default. What the design actually needs — AGENTS.md is written WHEN ASKED — stays asserted. The determinism argument that mattered (unprovided options resolve from saved preferences) is kept and attributed to the tool's own output, marked as not re-established by this script. - "`next dev` re-adds that block on every run." Next's block is present before the server starts, so a count of one proves it was left alone, not restored. Restoration is irrelevant to the design; the survival assertion is what matters and it is now worded as survival. - Two smaller ones: "Turbopack compiles" as a sub-claim of the TS5097 row, and "on every CLI command" attached to MODULE_TYPELESS_PACKAGE_JSON — one import is what was run. Also a data-loss hazard, not the same class: `rm -rf "$WORK/probe"` destroyed a pre-existing directory and the usage line did not document the argument as disposable. It now refuses with exit 2 and leaves the directory alone. Verified both directions. Full run: five variants matching on status and diagnostic, both routes serving this run's marker, probe: PASS, exit 0. Negative checks on the two new guards: a pre-existing workdir exits 2 with its contents intact, and the corrected ignore check fails on a .gitignore listing only `.env.example` where the old grep passed. The README now carries an explicit "what this POC does not establish" list, so the spec's citations and the probe's assertions are one-to-one by construction rather than by review. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 142 ++++++++---------- spec-poc/FIX-548-next-template-shape/probe.sh | 48 ++++-- spec/FIX-548.md | 66 ++++---- 3 files changed, 142 insertions(+), 114 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index ed82443682..feefc8b5af 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -7,85 +7,75 @@ bundler** (the mounted route imports it) and the **`fsdev` CLI** (a native `impo FIX-1159 decision 4 settles the CLI half by using `.mts`. Nobody had checked the bundler half, and the whole product — a streamed response rendered in a browser — runs through it. -Run it: `bash probe.sh` (needs network; ~2 minutes). It scaffolds a real `create-next-app@16` -project, drops each candidate config shape in, and runs `next build`, `next dev`, and a native -`import()` against each. - -**The exit status is the evidence, and every claim below feeds it** — `0` every row of the table -behaved as documented *and* the scaffold-discovery and served-route assertions held, `1` -something disagreed with what this file claims, `2` the run could not be completed. - -Each variant declares both the outcome **and the diagnostic** this README claims for it, so -**"the build failed" is not automatically a probe failure** — two variants are supposed to fail — -and equally, a failure for the *wrong reason* is not a pass. A shared route-file typo, a -dependency problem, or a future Next regression would otherwise reduce to `fail` and be read as -"matched the documented result", letting the probe go green without ever reproducing `TS5097` or -the module-resolution behaviour that is the whole justification for the chosen shape. Pass rows -assert the route compiled (`/api/flows` in the build output), not merely that the process -exited 0. - -Two earlier versions of this probe could report green for claims they had not proved, which is -why the status is wired this way: - -- it reached a **stale dev server** left over from a previous run, so it now uses a fresh marker - per run on a port it proves free first; -- it **discarded `next build`'s status** through a pipeline and let a rejected `import()` resolve, - so those two — the exact claims the spec cites this POC for — sat outside the exit code. - -Wiring those in immediately earned its keep: the first run of the accumulating version exited `1` -on the `.ts, no type field` row, and the cause was the probe, not the finding. Its `import()` check -called `process.exit(0)` in the `.then()`, which cut off `MODULE_TYPELESS_PACKAGE_JSON` before Node -flushed it — the warning is emitted asynchronously. The check now sets `process.exitCode` and lets -the process drain. A probe that could not fail would have recorded "clean" for the one variant -whose entire purpose is to warn. - -It also serves **both route files with the canonical route exports** (`runtime = "nodejs"`, -`dynamic = "force-dynamic"`) rather than a hand-made bare route, because an earlier version -exercised a shape the spec does not specify. - -**What this does not prove:** that `force-dynamic` prevents response buffering. That is Next's -documented behaviour and it needs a real streamed model response to observe — §10's goal check -owns it, by requiring the response to render *incrementally*. This probe establishes only that -the specified route shape builds and serves the config module. +Run it: `bash probe.sh [workdir]` (needs network; ~3 minutes). It scaffolds a real +`create-next-app@16.3.1` project, drops each candidate config shape in, and runs `next build`, +`next dev`, and a native `import()` against each. It refuses to run if `/probe` already +exists rather than deleting it. + +## The contract between this file and the script + +**Every claim below is backed by an assertion that fails the run if the claim becomes false.** +That is the point of the file, and it has been the source of every review finding against this +POC — four rounds of "this check cannot fail the thing it is cited for." So the rule now is: +a claim is either asserted, or it is not made here. + +Exit status: `0` every claim below held · `1` one of them did not · `2` the run could not be +completed (scaffold or install failed, no free port, workdir occupied). + +Each variant asserts both its **outcome** and its **diagnostic**, so "the build failed" is not +automatically a pass for a row documented as failing — a route-file typo, a dependency problem, +or a future Next regression would otherwise be read as "matched the documented result". Rows +documented as passing assert the route actually compiled (`/api/flows` in the build output), +not merely that the process exited 0. + +**What this POC does not establish** — stated because the spec cites it and the boundary matters: + +- **That `force-dynamic` prevents response buffering.** It needs a real streamed model response + to observe. §10's goal check owns it, by requiring the response to render *incrementally*. +- **That `--agents-md` is on by default.** The invocation passes it explicitly, as the spec + requires of every flag, so nothing here speaks to the default. What is asserted is that + `create-next-app` still writes `AGENTS.md` **when asked** — which is what the design rests on. +- **That `next dev` re-creates a missing `AGENTS.md` block.** Next's block is present before the + server starts, so the check proves it was left alone, not that it would be restored. +- **Whether a provider SDK that `@flow-state-dev/core` imports dynamically by package name + resolves inside the Next.js server bundle.** `createModelResolver` carries a `directLoadFailed` + fallback for exactly this case, so it is a known hazard. Only a real run with a real key + reaches it — §10's goal check does, through the mounted route rather than through `fsdev run`. ## What it settled | Variant | `next build` | native `import()` | verdict | |---|---|---|---| -| `fsdev.config.mts`, imported as `../fsdev.config.mts` | Turbopack compiles; **TypeScript fails** — `TS5097: An import path can only end with a '.mts' extension when 'allowImportingTsExtensions' is enabled` | clean | needs a `tsconfig.json` edit | -| `fsdev.config.mts`, imported as `../fsdev.config` | **module not found** — Turbopack does not resolve extensionless to `.mts` | clean | dead | -| `fsdev.config.mts` + `allowImportingTsExtensions: true` | passes | clean | works, costs two edits to files `create-next-app` wrote | +| `fsdev.config.mts`, imported as `../fsdev.config.mts` | fails — `TS5097: An import path can only end with a '.mts' extension when 'allowImportingTsExtensions' is enabled` | clean | needs a `tsconfig.json` edit | +| `fsdev.config.mts`, imported as `../fsdev.config` | fails — `Module not found`; Turbopack does not resolve extensionless to `.mts` | clean | dead | +| `fsdev.config.mts`, with `allowImportingTsExtensions: true` added to the tsconfig | passes | clean | works, at the cost of both edits this row names | | **`fsdev.config.ts` + `"type": "module"` in the manifest** | **passes** | **clean, no warning** | **chosen (§6 decision 4)** | -| `fsdev.config.ts`, no `type` field | passes | loads, but emits `MODULE_TYPELESS_PACKAGE_JSON` on every CLI command | rejected | - -The chosen variant is also run end to end against the shape the spec specifies: `next dev` serves -both `GET /api/flows` (the bare route) and `GET /api/flows/sessions/abc` (the catch-all), and each -returns this run's unique marker, proving the config module that loaded is the one this run wrote. - -## Four things it found that nothing in the epic or the sibling specs knew - -All four are **asserted, and asserted before this script writes anything** — not printed for a -reader to eyeball. Ordering is the whole point: the probe later appends its own FSD section to -`AGENTS.md`, and `next dev` restores Next's block, so a check placed at the end would report -green exactly when the pinned scaffolder had stopped writing these files. Finding 1 especially, -because the spec's append-not-create design rests on it. - -1. **`create-next-app@16` writes `AGENTS.md` itself**, with its own delimited block - (``), and **`next dev` re-adds that block on every run**. So - the greenfield Next path is an *append* to an existing `AGENTS.md`, never a create — the case - everyone assumed was brownfield-only. An appended FSD section survived a `next dev` run intact. -2. **`create-next-app@16` also writes `CLAUDE.md`.** -3. **Its `.gitignore` already contains `.env*`**, so the credential-ignore entry the template - depends on is supplied by the host scaffold — a fact to *assert*, not to assume, because it is - someone else's file. -4. **`--agents-md` defaults on and the tool says so** (`Using defaults for unprovided options`). - `create-next-app` persists saved preferences between runs, so any flag we leave off can resolve - differently on a machine that has run it before. Every flag has to be passed explicitly; - `--yes` is not a substitute. - -## Not settled here - -Whether a provider SDK that `@flow-state-dev/core` imports **dynamically by package name** -resolves inside the Next.js server bundle. `createModelResolver` carries a `directLoadFailed` -fallback for exactly this case, so it is a known hazard. Only a real run with a real key reaches -it — §10's goal check does, through the mounted route rather than through `fsdev run`. +| `fsdev.config.ts`, no `type` field | passes | loads, but emits `MODULE_TYPELESS_PACKAGE_JSON` | rejected | + +The chosen variant is also run end to end against the shape the spec specifies — both route +files, with the canonical `runtime = "nodejs"` and `dynamic = "force-dynamic"` exports. `next dev` +serves `GET /api/flows` (the bare route) and `GET /api/flows/sessions/abc` (the catch-all), and +each returns this run's unique marker, proving the config module that answered is the one this +run wrote rather than a stale server. + +## What it found that nothing in the epic or the sibling specs knew + +Asserted **before the script writes anything**, because the checks are otherwise self-concealing: +the script later appends its own section to `AGENTS.md`, so a check at the end would go green +exactly when the pinned scaffolder had stopped producing these files. + +1. **`create-next-app@16.3.1` writes `AGENTS.md`**, carrying its own delimited block + (``). So the greenfield Next path is an **append to an + existing file, never a create** — the case everyone had filed as brownfield-only. Our appended + FSD section is still intact after a `next dev` run, and so is Next's block. +2. **It also writes `CLAUDE.md`.** +3. **Git ignores `.env.local` in a fresh scaffold.** Asserted with `git check-ignore`, not by + grepping `.gitignore` — a text match on `^\.env` also passes for a file that only lists + `.env.example`, which would leave `.env.local` publishable. The credential stop (spec + decision 7) rests on this, so it is checked the way the real command has to check it: ask git + about the path, before the key is written. +4. **`create-next-app` fills unprovided options from saved preferences**, printing + `Using defaults for unprovided options`. This is why the spec requires every flag to be passed + explicitly and rules out `--yes`: an option we leave off can resolve differently on a machine + that has run the tool before. *(Observed in the tool's output and documented in its `--help`; + this script passes every flag, so it does not re-establish it.)* diff --git a/spec-poc/FIX-548-next-template-shape/probe.sh b/spec-poc/FIX-548-next-template-shape/probe.sh index 79a897d03b..972856be45 100644 --- a/spec-poc/FIX-548-next-template-shape/probe.sh +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -26,7 +26,12 @@ fail() { echo " MISMATCH — $1"; RC=1; } WORK="${1:-$(mktemp -d)}" mkdir -p "$WORK" || exit 2 APP="$WORK/probe" -rm -rf "$APP" +# Never delete a directory the caller may care about. The argument is a workdir, +# not a scratch space we own, and `rm -rf` on it was a data-loss hazard. +if [ -e "$APP" ]; then + echo "refusing to run: $APP already exists — remove it or pass a different workdir" >&2 + exit 2 +fi echo "workdir: $WORK" # Exact, not @16 — a range would re-resolve and this script is cited as evidence, @@ -44,11 +49,16 @@ echo "manifest type field: $(node -p "require('./package.json').type ?? '(absent echo "tsconfig include: $(node -p "JSON.stringify(require('./tsconfig.json').include)")" # ASSERTED, NOT PRINTED — and asserted HERE, before this script writes anything. -# The greenfield-appends design rests on create-next-app writing its own AGENTS.md, +# The greenfield-appends design rests on AGENTS.md existing in the scaffold output, # and this check is self-concealing if it runs later: the append near the end -# recreates AGENTS.md, and `next dev` restores Next's own block. A probe that -# checked at the end would go green exactly when the pinned scaffolder had stopped -# doing the thing the spec depends on. +# recreates AGENTS.md itself. A probe that checked at the end would go green +# exactly when the pinned scaffolder had stopped writing these files. +# +# Note what this does and does not establish. The invocation above passes +# --agents-md explicitly (as the spec requires of every flag), so these assertions +# guard "create-next-app still writes AGENTS.md WHEN ASKED" — which is what the +# design depends on. They say nothing about the flag's default, and the README +# does not claim they do. [ -f AGENTS.md ] \ && echo " AGENTS.md: present" \ || fail "create-next-app no longer writes AGENTS.md — the spec's append-not-create premise is dead" @@ -58,9 +68,18 @@ grep -q 'BEGIN:nextjs-agent-rules' AGENTS.md 2>/dev/null \ [ -f CLAUDE.md ] \ && echo " CLAUDE.md: present" \ || fail "create-next-app no longer writes CLAUDE.md — README finding 2 is stale" -grep -qE '^\.env' .gitignore 2>/dev/null \ - && echo " .gitignore: ignores .env* ($(grep -nE '^\.env' .gitignore | head -1))" \ - || fail "create-next-app's .gitignore no longer ignores .env* — spec decision 7 loses its host-supplied entry" +# Ask git, not the text. A `grep '^\.env'` passes on a .gitignore that only lists +# `.env.example`, which does NOT ignore .env.local — so the credential stop +# (spec decision 7) could rest on a premise the probe reported as true. The +# scaffold runs with --disable-git, so init a throwaway repo just to evaluate the +# rules. check-ignore works on a path that does not exist yet, which is the state +# the real command is in when it decides whether it may write the key. +git init -q . 2>/dev/null +if git check-ignore -q .env.local; then + echo " .gitignore: git would ignore .env.local ($(git check-ignore -v .env.local | awk '{print $1":"$2}'))" +else + fail "git would NOT ignore .env.local in a fresh scaffold — spec decision 7 loses its host-supplied entry" +fi # The route shape the spec specifies: a catch-all plus a sibling bare route, both # carrying the canonical exports from packages/next/README.md. An earlier version @@ -214,12 +233,17 @@ CATCH=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows/se echo " GET /api/flows/sessions/abc -> $CATCH" [ "$CATCH" = "$MARKER:catchall:sessions/abc:200" ] || fail "catch-all route: expected $MARKER:catchall:sessions/abc:200" +# SURVIVAL, not restoration. Next's block was already present before the server +# started, so a count of one proves it was left alone — it does not prove `next dev` +# would re-create a missing block, and the README no longer claims it does. +# Restoration is irrelevant to the design: what matters is that our appended +# section is still there afterwards. FSD_N=$(grep -c 'FSD SECTION SENTINEL' AGENTS.md) NEXT_N=$(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md) -echo " FSD section survived next dev: $FSD_N (expect 1)" -echo " next's own block still there: $NEXT_N (expect 1)" -[ "$FSD_N" = 1 ] || fail "appended FSD section did not survive next dev" -[ "$NEXT_N" = 1 ] || fail "next's own block is not intact" +echo " our appended FSD section, after next dev: $FSD_N (expect 1)" +echo " next's own block, left intact: $NEXT_N (expect 1)" +[ "$FSD_N" = 1 ] || fail "our appended FSD section did not survive next dev" +[ "$NEXT_N" = 1 ] || fail "next's own block was altered or duplicated by next dev" kill "$DEV_PID" 2>/dev/null; wait "$DEV_PID" 2>/dev/null diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 1f86512625..8b0d1b6deb 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -136,10 +136,14 @@ file list short and refusing surface — including a `--template` flag with one looks plainer than our own example — the right trade for a file whose job is to be read. 7. **No path writes the API key before it has proven git will not publish it.** The template's - host scaffold happens to supply the ignore entry (`create-next-app`'s `.gitignore` already - carries `.env*` — verified), so this is an assertion, not a code branch: check, add ours if - absent, and only then let init write the key. - *Rejected:* assuming the entry is there because we saw it once. It is someone else's file. + host scaffold happens to cover this already (verified: git ignores `.env.local` in a fresh + `create-next-app` scaffold), so this is an assertion, not a code branch: check, add our own + entry if the check fails, and only then let init write the key. + *Rejected:* assuming the entry is there because we saw it once — it is someone else's file — + **and checking it by reading `.gitignore` for a rule that looks right.** The check must ask + git about `.env.local` itself (`git check-ignore`), because a `.gitignore` that lists only + `.env.example` matches a naive text search while leaving `.env.local` publishable. The POC + made exactly that mistake before it was caught. *Locks in:* the guarantee the epic now states generally — a credential in version control is the one failure a diff review does not catch, because it looks like every other added line. §10 asserts it by running `git check-ignore`, not by reading the file. @@ -367,13 +371,14 @@ manifest key. This is the entire product surface: **Why the config shape is what it is — measured.** The template's config has two consumers at once: Turbopack, because the route imports it, and the CLI's native `import()`. Nobody had checked the first. The POC at [`spec-poc/FIX-548-next-template-shape/`](../spec-poc/FIX-548-next-template-shape/) -scaffolds a real `create-next-app@16` project and runs both against every candidate shape — run -it with `bash spec-poc/FIX-548-next-template-shape/probe.sh`. It settled decision 4 and turned up -four facts nothing in this epic knew: `create-next-app` writes its **own** `AGENTS.md` (with its -own delimiters, re-added by `next dev`) and a `CLAUDE.md`; its `.gitignore` already carries -`.env*`; and `--agents-md` defaults on from saved preferences. The first of those matters most — -**the greenfield Next path appends to an existing `AGENTS.md`, it never creates one**, which is -the case everyone had filed under brownfield. +scaffolds a real `create-next-app@16.3.1` project and runs both against every candidate shape — +run it with `bash spec-poc/FIX-548-next-template-shape/probe.sh`. It settled decision 4 and turned +up three facts nothing in this epic knew: `create-next-app` writes its **own** `AGENTS.md`, with +its own delimiters, and a `CLAUDE.md`; git ignores `.env.local` in a fresh scaffold; and the tool +fills unprovided options from saved preferences. The first matters most — **the greenfield Next +path appends to an existing `AGENTS.md`, it never creates one**, which is the case everyone had +filed under brownfield. Each of those is an assertion in the probe, and its README states what +the probe deliberately does *not* establish, so the citation and the evidence stay one-to-one. **Step 4 — hand off to init.** What crosses the seam, and nothing more: @@ -440,7 +445,7 @@ no-rollback rule directly below. | Case | Expected | |---|---| -| `.env.local` is about to be written and git would not ignore it | Add the ignore entry, then write the key. This is the ordinary path, not an error — `create-next-app`'s own `.gitignore` already carries `.env*` (verified), so the entry is usually already there and this is an assertion that it is. | +| `.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 command to finish. Never write the key "and warn" — the warning scrolls away and the credential does not. | **Failures after work has started — nothing rolls back:** @@ -611,10 +616,10 @@ subprocesses stubbed. resolving a `fsdev` bin, which is a different question from owning the `fsdev` *package* name — worth FIX-1162 stating explicitly which names the launch actually requires, since this issue only needs one of them. -- **`create-next-app` writes `AGENTS.md` and `CLAUDE.md` itself**, and `next dev` re-adds its - own block. Epic Q1's append-never-overwrite guarantee therefore binds the *greenfield* path - too, which the epic files under brownfield. The POC confirmed an appended FSD section survives - a `next dev` run. +- **`create-next-app` writes `AGENTS.md` and `CLAUDE.md` itself**, with its own delimited block + in the former. Epic Q1's append-never-overwrite guarantee therefore binds the *greenfield* path + too, which the epic files under brownfield. The POC confirmed an appended FSD section, and + Next's own block, both survive a `next dev` run intact. **Open questions:** one, and it is §6's decision 2 — does the Node API template ship? Raised as a decision with a recommendation rather than left open, because leaving it open would block a spec @@ -623,13 +628,13 @@ runs or six, and whether decision 2b's flag exists. Nothing else. **Verified premises** (measured or read from the code, so a reviewer need not re-derive them): -- **Module loading in a real `create-next-app@16` project, probed** (the POC in §7): Turbopack - does **not** resolve an extensionless import to a `.mts` file (`Module not found`); an explicit - `.mts` specifier fails TypeScript with `TS5097` unless `allowImportingTsExtensions` is set; - `.mts` with that flag builds; `fsdev.config.ts` with `"type": "module"` builds **and** loads - under a native `import()` with no warning; without the `type` field the same file loads but - emits `MODULE_TYPELESS_PACKAGE_JSON`. Confirmed end to end: `next dev` served `GET /api/flows` - through the config module. +- **Module loading in a real `create-next-app@16.3.1` project, probed** (the POC in §7): + Turbopack does **not** resolve an extensionless import to a `.mts` file (`Module not found`); + an explicit `.mts` specifier fails TypeScript with `TS5097` unless `allowImportingTsExtensions` + is set; `.mts` with that flag builds; `fsdev.config.ts` with `"type": "module"` builds **and** + loads under a native `import()` with no warning; without the `type` field the same file loads + but emits `MODULE_TYPELESS_PACKAGE_JSON`. Confirmed end to end: `next dev` served both + `GET /api/flows` and a nested catch-all path through the config module. - **`npm create ` resolves to the unscoped `create-`**, measured: `npm create flow-state-nonexistent-xyz123` requests `registry.npmjs.org/create-flow-state-nonexistent-xyz123`. A scoped package cannot serve that @@ -736,9 +741,18 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions two edits to files the scaffolder wrote (Turbopack will not resolve it extensionless, and TypeScript rejects the explicit specifier without `allowImportingTsExtensions`), while `fsdev.config.ts` with `"type": "module"` builds, serves, and loads warning-free. It also - turned up that `create-next-app` writes its own `AGENTS.md` and `CLAUDE.md`, that `next dev` - re-adds its block, and that its `.gitignore` already ignores `.env*` — so the greenfield path - *appends* to an agent-instructions file, a case the epic had filed under brownfield. + turned up that `create-next-app` writes its own `AGENTS.md` and `CLAUDE.md`, and that git + ignores `.env.local` in a fresh scaffold — so the greenfield path *appends* to an + agent-instructions file, a case the epic had filed under brownfield. +- **The POC was narrowed to what it actually proves.** Four review rounds found the same defect + class — a check that could not fail the claim it was cited for — so the last pass went through + its README claim by claim and required each to be either assertion-backed or deleted. Deleted: + that `--agents-md` is on by default (the probe passes the flag explicitly, so it establishes + only that the file is written *when asked* — which is what the design needs), and that + `next dev` re-creates a missing block (its block is present beforehand, so the check proves it + was left alone). Fixed rather than narrowed, because decision 7 rests on it: the ignore check + now asks `git check-ignore` about `.env.local` instead of grepping `.gitignore` for `^\.env`, + which also passes for a file listing only `.env.example`. - **The unscoped name became a prerequisite, and one inherited fact was corrected.** The previous draft said "published unscoped" but argued it as brand fit, which left the scoped form looking like a harmless fallback — it is not: `npm create ` resolves to the *unscoped* From eee403ff0eae2cf15895f60c1243ec7edfbab235 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 02:26:39 +0000 Subject: [PATCH 10/30] spec(FIX-548): close the evidence contract on both sides, and fix a check that failed when the claim was true MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §2 stated a one-step outcome the scaffolder does not deliver. The epic has since landed the precise wording — one scaffolding command plus the dev command it prints — so §2 now says that and §13's note is closed rather than pending. All that survives of the note is the standing instruction not to add auto-start. The one-to-one claim was still false in two places. The saved-preference fact is externally sourced, not asserted, so it moves out of the POC's findings into its "does not establish" list and out of §7's asserted list; both lists are now declared exhaustive so nothing can sit between them. The survival check counted one sentinel and one opening delimiter, which passes on a section truncated after its sentinel or a block rewritten around its BEGIN marker. It now captures both sections whole beforehand and compares them byte-for-byte, keeping an occurrence count because equality cannot see a duplicate through an extraction that stops at the first END. And the served-route check failed in the wrong direction: a fixed 18s sleep meant a slow `next dev` produced connection-refused and exit 1, reporting a true claim as disproved. It now polls for the bind against a deadline and separates "never started" (2) from "answered wrongly" (1). Not hypothetical — on this machine the bind took 50s and 33s across two runs, past the old sleep-plus-timeout window. Verified: probe re-run clean twice, exit 0 both times. The 1/2 split exercised directly — dev-exits-early and never-binds both yield 2, bind-late-answer-wrong still yields 1. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 39 ++++++--- spec-poc/FIX-548-next-template-shape/probe.sh | 79 ++++++++++++++++--- spec/FIX-548.md | 63 ++++++++------- 3 files changed, 129 insertions(+), 52 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index feefc8b5af..ed230bbfe0 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -14,13 +14,21 @@ exists rather than deleting it. ## The contract between this file and the script -**Every claim below is backed by an assertion that fails the run if the claim becomes false.** +**Every claim in this file is backed by an assertion that fails the run if the claim becomes +false — except the ones in *What this POC does not establish*, which is the list of facts the +spec cites and this script deliberately does not back.** Those two sections are exhaustive: +asserted, or named as unasserted. Nothing sits between them. + That is the point of the file, and it has been the source of every review finding against this -POC — four rounds of "this check cannot fail the thing it is cited for." So the rule now is: -a claim is either asserted, or it is not made here. +POC — rounds of "this check cannot fail the thing it is cited for," including one against an +earlier version of this very contract, which claimed everything below it was asserted while an +externally-sourced fact sat in the asserted list. -Exit status: `0` every claim below held · `1` one of them did not · `2` the run could not be -completed (scaffold or install failed, no free port, workdir occupied). +Exit status: `0` every asserted claim held · `1` one of them did not · `2` the run could not be +completed (scaffold or install failed, no free port, workdir occupied, dev server never bound). +The `1`/`2` split is load-bearing: a machine too slow to have bound the port yet is not a +disproved claim, and the script polls for the bind against a deadline rather than sleeping a +fixed interval so it cannot report one as the other. Each variant asserts both its **outcome** and its **diagnostic**, so "the build failed" is not automatically a pass for a row documented as failing — a route-file typo, a dependency problem, @@ -36,7 +44,16 @@ not merely that the process exited 0. requires of every flag, so nothing here speaks to the default. What is asserted is that `create-next-app` still writes `AGENTS.md` **when asked** — which is what the design rests on. - **That `next dev` re-creates a missing `AGENTS.md` block.** Next's block is present before the - server starts, so the check proves it was left alone, not that it would be restored. + server starts, so the check proves it was left alone, not that it would be restored. (Next's + own block says it re-adds itself; nothing here tests that, and nothing in the design needs it.) +- **That `create-next-app` fills unprovided options from saved preferences.** It prints `Using + defaults for unprovided options`, and its `--help` documents the behaviour — this is why the + spec requires every flag to be passed explicitly and rules out `--yes`: an option we leave off + can resolve differently on a machine that has run the tool before. **The script passes every + flag, so it never reproduces this and cannot fail on it.** Establishing it would need a second + scaffold run with an option deliberately withheld, which buys a fact the spec already acts on + at the cost of doubling the probe's slowest step. Stated here, outside the asserted list, + rather than dropped, because the spec cites it for the bare-app step's flag discipline. - **Whether a provider SDK that `@flow-state-dev/core` imports dynamically by package name resolves inside the Next.js server bundle.** `createModelResolver` carries a `directLoadFailed` fallback for exactly this case, so it is a known hazard. Only a real run with a real key @@ -67,15 +84,13 @@ exactly when the pinned scaffolder had stopped producing these files. 1. **`create-next-app@16.3.1` writes `AGENTS.md`**, carrying its own delimited block (``). So the greenfield Next path is an **append to an existing file, never a create** — the case everyone had filed as brownfield-only. Our appended - FSD section is still intact after a `next dev` run, and so is Next's block. + FSD section is still intact after a `next dev` run, and so is Next's block: both are captured + whole before the server starts and compared byte-for-byte afterwards, plus an occurrence count + that a comparison alone cannot see a duplicate through. A marker count on its own would pass + on a section truncated after its sentinel. 2. **It also writes `CLAUDE.md`.** 3. **Git ignores `.env.local` in a fresh scaffold.** Asserted with `git check-ignore`, not by grepping `.gitignore` — a text match on `^\.env` also passes for a file that only lists `.env.example`, which would leave `.env.local` publishable. The credential stop (spec decision 7) rests on this, so it is checked the way the real command has to check it: ask git about the path, before the key is written. -4. **`create-next-app` fills unprovided options from saved preferences**, printing - `Using defaults for unprovided options`. This is why the spec requires every flag to be passed - explicitly and rules out `--yes`: an option we leave off can resolve differently on a machine - that has run the tool before. *(Observed in the tool's output and documented in its `--help`; - this script passes every flag, so it does not re-establish it.)* diff --git a/spec-poc/FIX-548-next-template-shape/probe.sh b/spec-poc/FIX-548-next-template-shape/probe.sh index 972856be45..57a473fad2 100644 --- a/spec-poc/FIX-548-next-template-shape/probe.sh +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -13,7 +13,10 @@ # 0 every variant matched its expected outcome AND the served-route and # AGENTS.md assertions held # 1 at least one check disagreed with what the README claims -# 2 the run could not be completed (scaffold/install failed, no free port) +# 2 the run could not be completed (scaffold/install failed, no free port, +# workdir occupied, dev server never bound) +# The 1/2 split is load-bearing, not cosmetic: a slow machine on which `next dev` +# has not bound yet must never be reported as a disproved claim. # Each variant declares the outcome README.md claims for it, and a variant that # behaves differently fails the probe — including the two that are EXPECTED to # fail to build. "The build broke" is not automatically a probe failure here; @@ -221,29 +224,79 @@ if [ "$PORT" = 0 ]; then echo " no free port in 3990-3999 — CANNOT VERIFY"; e echo " port $PORT (verified free)" printf '\n\nFSD SECTION SENTINEL\n\n' >> AGENTS.md + +# Both AGENTS.md sections, captured COMPLETE and before the server starts, so the +# survival check below can compare rather than count. See the check itself. +FSD_B=''; FSD_E='' +NXT_B=''; NXT_E='' +section() { # $1 file · $2 begin marker · $3 end marker -> the whole block, inclusive + awk -v b="$2" -v e="$3" 'index($0,b){inside=1} inside{print; if(index($0,e)) exit}' "$1" +} +FSD_BEFORE=$(section AGENTS.md "$FSD_B" "$FSD_E") +NXT_BEFORE=$(section AGENTS.md "$NXT_B" "$NXT_E") +# 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 + npx next dev --port "$PORT" > dev.log 2>&1 & DEV_PID=$! -sleep 18 -BARE=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows") +# Poll for the bind against a bounded deadline; do NOT sleep a fixed interval. +# A cold or loaded machine can take far longer than any constant to bind, and the +# request then gets connection-refused — which a fixed sleep reports as a FAILED +# ROUTE CLAIM (1) when the claim is fine and the machine was just slow. Startup +# that never completes is "could not verify" (2). Readiness is the TCP bind, not a +# 200 from the route: a route that answers wrongly must still fail as 1, so it is +# asserted separately below. +READY=0 +DEADLINE=$((SECONDS + 180)) +while [ "$SECONDS" -lt "$DEADLINE" ]; do + if ! kill -0 "$DEV_PID" 2>/dev/null; then + echo " next dev exited before binding port $PORT — CANNOT VERIFY"; tail -20 dev.log | sed 's/^/ /'; exit 2 + fi + if (exec 3<>"/dev/tcp/127.0.0.1/$PORT") 2>/dev/null; then READY=1; break; fi + sleep 1 +done +if [ "$READY" != 1 ]; then + echo " next dev did not bind port $PORT within 180s — CANNOT VERIFY"; tail -20 dev.log | sed 's/^/ /' + kill "$DEV_PID" 2>/dev/null; wait "$DEV_PID" 2>/dev/null; exit 2 +fi +echo " next dev bound port $PORT after ${SECONDS}s" + +# Generous per-request timeout: the bind precedes compilation, and the FIRST +# request is what triggers Turbopack to compile the route. +BARE=$(curl -s --max-time 120 --noproxy '*' "http://127.0.0.1:$PORT/api/flows") echo " GET /api/flows -> $BARE" [ "$BARE" = "$MARKER:200" ] || fail "bare route: expected $MARKER:200" -CATCH=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows/sessions/abc") +CATCH=$(curl -s --max-time 120 --noproxy '*' "http://127.0.0.1:$PORT/api/flows/sessions/abc") echo " GET /api/flows/sessions/abc -> $CATCH" [ "$CATCH" = "$MARKER:catchall:sessions/abc:200" ] || fail "catch-all route: expected $MARKER:catchall:sessions/abc:200" # SURVIVAL, not restoration. Next's block was already present before the server -# started, so a count of one proves it was left alone — it does not prove `next dev` -# would re-create a missing block, and the README no longer claims it does. -# Restoration is irrelevant to the design: what matters is that our appended -# section is still there afterwards. -FSD_N=$(grep -c 'FSD SECTION SENTINEL' AGENTS.md) +# started, so this proves it was left alone — it does not prove `next dev` would +# re-create a missing block, and the README does not claim it does. Restoration is +# irrelevant to the design: what matters is that our appended section is still +# there afterwards. +# +# COMPARE THE WHOLE SECTION, do not count markers. The previous version counted one +# sentinel line and one opening delimiter, which still passes if `next dev` truncates +# our section after its sentinel, drops the closing delimiter, or rewrites next's +# block while keeping its BEGIN line — all while the README claims both sections are +# intact. Byte equality of the complete block is the claim. The occurrence counts are +# kept alongside it because equality alone cannot see a duplicate: the extraction +# stops at the first END, so a second appended copy would compare equal. +FSD_AFTER=$(section AGENTS.md "$FSD_B" "$FSD_E") +NXT_AFTER=$(section AGENTS.md "$NXT_B" "$NXT_E") +FSD_N=$(grep -c 'BEGIN:fsd' AGENTS.md) NEXT_N=$(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md) -echo " our appended FSD section, after next dev: $FSD_N (expect 1)" -echo " next's own block, left intact: $NEXT_N (expect 1)" -[ "$FSD_N" = 1 ] || fail "our appended FSD section did not survive next dev" -[ "$NEXT_N" = 1 ] || fail "next's own block was altered or duplicated by next dev" +echo " our appended FSD section: $([ "$FSD_AFTER" = "$FSD_BEFORE" ] && echo 'byte-identical' || echo 'CHANGED'), $FSD_N copy/copies (expect 1)" +echo " next's own block: $([ "$NXT_AFTER" = "$NXT_BEFORE" ] && echo 'byte-identical' || echo 'CHANGED'), $NEXT_N copy/copies (expect 1)" +[ "$FSD_AFTER" = "$FSD_BEFORE" ] || fail "our appended FSD section did not survive next dev intact" +[ "$NXT_AFTER" = "$NXT_BEFORE" ] || fail "next's own block was altered by next dev" +[ "$FSD_N" = 1 ] || fail "our appended FSD section was duplicated by next dev ($FSD_N copies)" +[ "$NEXT_N" = 1 ] || fail "next's own block was duplicated by next dev ($NEXT_N copies)" kill "$DEV_PID" 2>/dev/null; wait "$DEV_PID" 2>/dev/null diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 8b0d1b6deb..cfd403c3ee 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -30,7 +30,8 @@ Project **Public Launch**.* ### 2. Solution in plain terms `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. +prints the dev command that serves it; running that command is what puts the feature, streaming, +in the developer's browser. Three things happen in order. The bare Next.js app comes from Next's own scaffolder. **Then this package writes its template** — the config, the route that serves flows, the demo flow, and the @@ -373,12 +374,16 @@ once: Turbopack, because the route imports it, and the CLI's native `import()`. checked the first. The POC at [`spec-poc/FIX-548-next-template-shape/`](../spec-poc/FIX-548-next-template-shape/) scaffolds a real `create-next-app@16.3.1` project and runs both against every candidate shape — run it with `bash spec-poc/FIX-548-next-template-shape/probe.sh`. It settled decision 4 and turned -up three facts nothing in this epic knew: `create-next-app` writes its **own** `AGENTS.md`, with -its own delimiters, and a `CLAUDE.md`; git ignores `.env.local` in a fresh scaffold; and the tool -fills unprovided options from saved preferences. The first matters most — **the greenfield Next -path appends to an existing `AGENTS.md`, it never creates one**, which is the case everyone had -filed under brownfield. Each of those is an assertion in the probe, and its README states what -the probe deliberately does *not* establish, so the citation and the evidence stay one-to-one. +up two facts nothing in this epic knew, **each asserted in the probe**: `create-next-app` writes +its **own** `AGENTS.md`, with its own delimiters, and a `CLAUDE.md`; and git ignores `.env.local` +in a fresh scaffold. The first matters most — **the greenfield Next path appends to an existing +`AGENTS.md`, it never creates one**, which is the case everyone had filed under brownfield. + +A third observation is **not** asserted, and the README says so rather than listing it as +evidence: `create-next-app` fills unprovided options from saved preferences, which is step 2's +reason for passing every flag explicitly and refusing `--yes`. The probe passes every flag, so it +never reproduces it. The README's two lists — what is asserted, and what is deliberately not — +are exhaustive, which is what keeps the citation and the evidence one-to-one. **Step 4 — hand off to init.** What crosses the seam, and nothing more: @@ -695,27 +700,16 @@ runs or six, and whether decision 2b's flag exists. Nothing else. Spec-PR feedback recorded rather than folded. These are inputs, not instructions. -- **"The one-command promise disagrees with the stopping point"** — codex, on §2. The finding: - §2 says the command leaves the developer looking at the feature streaming, while §5's - transcript ends after scaffolding and prints `npm run dev`, and §10 starts it separately. Two - ways out were offered — have the scaffolder start and open the app, or restate the outcome as - a ready-to-run project. - - **Neither was taken; the mismatch is upstream and is being fixed there.** Checked directly: - 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** yields a streamed model - response" (line 57). The Proof is the precise statement and was deliberately sharpened at epic - review round 3, so §1's Outcome is the loose half — the epic-agent is folding it. This spec - already matches the Proof: §5's transcript is the exact stopping point and §10 measures from - it. - - **Do not add auto-start or auto-open.** `create-next-app` and `create-vite` both stop and - print the dev command, and taking the first option would be scope growth bought with a - reviewer's phrasing rather than a requirement. Recorded here so it does not return a third - time. +- **"The one-command promise disagrees with the stopping point"** — codex, on §2. **Closed, not + pending.** §2 used to say the command leaves the developer looking at the feature streaming, + while §5's transcript ends at the printed `npm run dev` and §10 starts it separately. The epic + has since landed the precise wording — greenfield is one scaffolding command *plus the dev + command it prints* — and §2 now states that two-step outcome, which is the whole of the fix. - *If §2's compression still reads as overclaiming once the epic lands, the fix is one sentence - in §2 — never a behaviour change in the scaffolder.* + **Do not add auto-start or auto-open.** `create-next-app` and `create-vite` both stop and print + the dev command; a scaffolder that leaves a server running behind a finished prompt is worse + ergonomics, not better. Taking that option would be scope growth bought with a reviewer's + phrasing rather than a requirement. Kept here as the live instruction, so it does not return. --- @@ -770,3 +764,18 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions else's file. Provider/model alignment became decision 5's intent map, with the goal check run per provider on a single key. And the printed commands are asserted by execution, which is what catches npm's `--` separator. +- **The evidence contract was closed on both sides, and one check was inverted.** §2 now states + the two-step outcome the epic settled — the scaffolding command *plus the dev command it + prints* — so the §13 note tracking that mismatch is closed rather than pending; all that + survives of it is the standing instruction not to add auto-start. The one-to-one claim was + still false in two places: the saved-preferences fact is externally sourced, not asserted, so + it moved out of the POC's findings into its *does not establish* list and out of §7's asserted + list, and the two lists are now declared exhaustive. The survival check counted one sentinel + and one opening delimiter, which passes on a section truncated after its sentinel or a block + rewritten around its `BEGIN` marker; it now captures both sections whole beforehand and + compares them byte-for-byte, keeping an occurrence count because equality cannot see a + duplicate. **And the served-route check was failing in the wrong direction** — a fixed 18s + sleep meant a slow `next dev` produced a connection-refused and exit 1, reporting a true claim + as disproved. It now polls for the bind against a deadline and separates "never started" (2) + from "answered wrongly" (1). Not hypothetical: on the machine this was re-run on, `next dev` + took 50s to bind, past the old sleep-plus-timeout window. From af5fd0ddfd8b457017d70fa4d8fb5ff848e29c97 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 02:35:19 +0000 Subject: [PATCH 11/30] spec-poc(FIX-548): freeze the probe, after two last checks that could not fail MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `clean` accepted warnings that were not clean. The import branch rejected only MODULE_TYPELESS_PACKAGE_JSON, so any new loader or deprecation warning was classified clean and the probe exited 0 while the README claims "no warning". Clean now means an empty log — measured, not assumed: a healthy run of this import writes 0 bytes. Anything else is `noisy`, which matches no documented row. The served-route check still discarded curl's exit status. Polling the bind fixed only half the inversion: a first compile past the timeout, or a connection lost after the bind, left an empty body that compared as a MISMATCH (1) rather than an incomplete probe (2). Both requests now go through one helper that checks curl first. It assigns to a global rather than echoing into $( ) deliberately — an `exit 2` inside a command substitution would end only the subshell and the caller would carry on with an empty body, which is the bug it exists to prevent. probe.sh is now FROZEN. The design question was settled three rounds ago; every round since has been the script's evidence quality on a throwaway attached to a PR that never merges. Any later finding is answered by narrowing a README claim to what the frozen script proves, never by editing the script. The README carries the reasoning, not just the rule: a probe that keeps earning rounds is asserting more than its job requires. Also corrects §12. It claimed `npm create ` and a bare `fsdev` on the path both need unscoped names. Only the first is true — a command name comes from the package's `bin` key, and `@flow-state-dev/cli` already declares one, so `fsdev` resolves while scoped. Verified by execution (scoped package packed, installed into a fresh consumer, command resolved with no unscoped package present), not by relaying the claim. Decision 1 is unaffected. Verified: probe re-run clean, exit 0, bind at 37s. Classification exercised directly — empty/typeless/new-warning/throw give clean/warn/noisy/error, and a transport failure gives 2 without reaching the body comparison. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 28 ++++++++-- spec-poc/FIX-548-next-template-shape/probe.sh | 52 ++++++++++++++++--- spec/FIX-548.md | 36 ++++++++++--- 3 files changed, 97 insertions(+), 19 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index ed230bbfe0..f13852691c 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -24,11 +24,31 @@ POC — rounds of "this check cannot fail the thing it is cited for," including earlier version of this very contract, which claimed everything below it was asserted while an externally-sourced fact sat in the asserted list. +### `probe.sh` is frozen. The README is the only moving part. + +**Do not edit `probe.sh` again** — not for a finding, not for a cleanup, whoever you are. The +design question this POC existed to answer was settled three rounds ago; every round since has +been about the script's evidence quality, on a throwaway attached to a PR that never merges. + +So the rule from here: **any further finding is answered by narrowing a claim in this README to +what the frozen script actually proves — never by changing the script.** Move the claim into +*What this POC does not establish*, or delete it. + +The reasoning, not just the rule: a probe that keeps earning review rounds is a probe asserting +more than its job requires. The cheapest way to end that loop is to stop claiming so much, which +is the same move that closed round 3 — and unlike growing the script, it cannot introduce a new +check that fails for its own reasons. + Exit status: `0` every asserted claim held · `1` one of them did not · `2` the run could not be -completed (scaffold or install failed, no free port, workdir occupied, dev server never bound). -The `1`/`2` split is load-bearing: a machine too slow to have bound the port yet is not a -disproved claim, and the script polls for the bind against a deadline rather than sleeping a -fixed interval so it cannot report one as the other. +completed (scaffold or install failed, no free port, workdir occupied, dev server never bound, a +request that never completed). The `1`/`2` split is load-bearing: a machine too slow to have +bound the port, or a request that died in transport, is not a disproved claim. The script polls +for the bind against a deadline instead of sleeping a fixed interval, and checks `curl`'s exit +status before comparing any body, so neither can be reported as the other. + +"Clean" in the table below means **nothing on stdout or stderr**, asserted as an empty log rather +than as the absence of the one warning we expected — otherwise a new loader or deprecation +warning would be silently classified clean. Each variant asserts both its **outcome** and its **diagnostic**, so "the build failed" is not automatically a pass for a row documented as failing — a route-file typo, a dependency problem, diff --git a/spec-poc/FIX-548-next-template-shape/probe.sh b/spec-poc/FIX-548-next-template-shape/probe.sh index 57a473fad2..e17f0b6ae1 100644 --- a/spec-poc/FIX-548-next-template-shape/probe.sh +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -182,15 +182,26 @@ variant() { }).catch(e=>{console.error('IMPORT THREW: '+e.message);process.exitCode=3})" > import.log 2>&1 local import_status=$? local got_import + # `clean` means NOTHING on stdout or stderr — not merely "no MODULE_TYPELESS". + # Testing only for the one warning we expect classifies any NEW diagnostic (a + # future loader or deprecation warning) as clean, so the probe would exit 0 + # while the README says "clean, no warning". Measured: a healthy run of this + # import writes 0 bytes, so empty is the honest bar. Anything else is `noisy`, + # which matches no documented row and therefore fails. if [ $import_status -ne 0 ]; then got_import=error + elif [ ! -s import.log ]; then + got_import=clean elif grep -q MODULE_TYPELESS_PACKAGE_JSON import.log; then got_import=warn else - got_import=clean + got_import=noisy fi echo " native import: $got_import (expected $want_import)" - [ "$got_import" = "$want_import" ] || fail "$label: import $got_import, README claims $want_import" + if [ "$got_import" != "$want_import" ]; then + fail "$label: import $got_import, README claims $want_import" + sed 's/^/ /' import.log + fi } set_pkg_type none @@ -266,13 +277,38 @@ echo " next dev bound port $PORT after ${SECONDS}s" # Generous per-request timeout: the bind precedes compilation, and the FIRST # request is what triggers Turbopack to compile the route. -BARE=$(curl -s --max-time 120 --noproxy '*' "http://127.0.0.1:$PORT/api/flows") -echo " GET /api/flows -> $BARE" -[ "$BARE" = "$MARKER:200" ] || fail "bare route: expected $MARKER:200" +# +# CHECK CURL'S STATUS BEFORE COMPARING THE BODY. Polling the bind fixed only half +# of this: a first compile that outruns the timeout, or a connection that drops +# after the bind, leaves an empty or partial body, and comparing that to the marker +# records a TRANSPORT failure as a DISPROVED CLAIM (1) when it is an incomplete +# probe (2). Both requests go through here so the two paths cannot drift apart. +# +# Assigns to a global instead of echoing into $( ) on purpose: command substitution +# runs in a subshell, so an `exit 2` inside one would end only that subshell and +# the caller would carry on with an empty body — reintroducing the exact +# misclassification this exists to prevent. +REQ_BODY="" +request() { # $1 = path · $2 = label + local rc + REQ_BODY=$(curl -sS --max-time 120 --noproxy '*' "http://127.0.0.1:$PORT$1" 2>curl.err) + rc=$? + if [ $rc -ne 0 ]; then + echo " GET $1 -> curl exit $rc — CANNOT VERIFY ($2 is untested, not disproved)" + sed 's/^/ /' curl.err + tail -20 dev.log | sed 's/^/ /' + kill "$DEV_PID" 2>/dev/null; wait "$DEV_PID" 2>/dev/null + exit 2 + fi +} + +request /api/flows "the bare route" +echo " GET /api/flows -> $REQ_BODY" +[ "$REQ_BODY" = "$MARKER:200" ] || fail "bare route: expected $MARKER:200" -CATCH=$(curl -s --max-time 120 --noproxy '*' "http://127.0.0.1:$PORT/api/flows/sessions/abc") -echo " GET /api/flows/sessions/abc -> $CATCH" -[ "$CATCH" = "$MARKER:catchall:sessions/abc:200" ] || fail "catch-all route: expected $MARKER:catchall:sessions/abc:200" +request /api/flows/sessions/abc "the catch-all route" +echo " GET /api/flows/sessions/abc -> $REQ_BODY" +[ "$REQ_BODY" = "$MARKER:catchall:sessions/abc:200" ] || fail "catch-all route: expected $MARKER:catchall:sessions/abc:200" # SURVIVAL, not restoration. Next's block was already present before the server # started, so this proves it was left alone — it does not prove `next dev` would diff --git a/spec/FIX-548.md b/spec/FIX-548.md index cfd403c3ee..66e3d9e6c4 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -615,12 +615,16 @@ subprocesses stubbed. **correct** (verified: held by a third party since 2024). What changed is the choice, not the finding: decision 1 takes `create-flow-state`, which is unpublished and available. FIX-1162's work is therefore superseded on *which* name, not corrected on its facts. -- **The unscoped-vs-scoped point applies beyond this issue.** `npm create ` and a bare - `fsdev` on the path both need unscoped names, and nothing under `@flow-state-dev/` is - published either. FIX-1159's printed commands (`npm exec fsdev …`) depend on the CLI package - resolving a `fsdev` bin, which is a different question from owning the `fsdev` *package* name - — worth FIX-1162 stating explicitly which names the launch actually requires, since this - issue only needs one of them. +- **The unscoped-vs-scoped point is narrower than this spec previously claimed.** `npm create + ` needs the unscoped name — that half stands, and decision 1 rests on it. **A bare + `fsdev` on the path does not.** A command name comes from the package's `bin` key, not from + its package name: `@flow-state-dev/cli` already declares `"bin": {"fsdev": …}`, and a scoped + package carrying that key puts `fsdev` in `node_modules/.bin/`, where `npx fsdev`, `npm exec + fsdev` and project scripts all find it with **no unscoped package existing anywhere**. + Verified by execution, not argument — FIX-1162 records the runnable recipe in its §10, and it + reproduces here. The only case that needs the unscoped `fsdev` is `npx fsdev` typed in a + directory where nothing is installed. So this issue's unscoped requirement is **`create-flow-state` + and nothing else**; FIX-1162 still owns stating which names the launch as a whole requires. - **`create-next-app` writes `AGENTS.md` and `CLAUDE.md` itself**, with its own delimited block in the former. Epic Q1's append-never-overwrite guarantee therefore binds the *greenfield* path too, which the epic files under brownfield. The POC confirmed an appended FSD section, and @@ -778,4 +782,22 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions sleep meant a slow `next dev` produced a connection-refused and exit 1, reporting a true claim as disproved. It now polls for the bind against a deadline and separates "never started" (2) from "answered wrongly" (1). Not hypothetical: on the machine this was re-run on, `next dev` - took 50s to bind, past the old sleep-plus-timeout window. + took 50s, 33s and 37s to bind across three runs, past the old sleep-plus-timeout window. +- **The probe is frozen, and one npm claim was corrected.** Two last checks were tightened. A + native `import()` now counts as *clean* only when it writes nothing at all, rather than merely + avoiding the one warning we expected — otherwise a future loader or deprecation warning would + be classified clean against a README that says "no warning". And `curl`'s exit status is + checked before its body is compared, so a request that dies in transport is an incomplete probe + (2) rather than a disproved claim (1) — the same inversion as the sleep, one step further on. + **`probe.sh` is now closed to further edits.** The design question was settled three rounds ago + and every round since has been the script's own evidence quality, on a throwaway attached to a + PR that never merges, so any later finding is answered by narrowing a README claim to what the + frozen script proves. The reasoning is on the POC README rather than just the rule: a probe + that keeps earning rounds is one asserting more than its job requires. +- **§12 overstated the npm mechanism, and it is corrected.** The spec said `npm create ` + *and* a bare `fsdev` on the path both need unscoped names. Only the first is true. A command + name comes from the package's `bin` key, so `@flow-state-dev/cli` — already declaring + `"bin": {"fsdev": …}` — puts `fsdev` on the path while scoped. Verified by execution rather + than argument (a scoped package packed, installed into a fresh consumer, the command resolved + with no unscoped package present), which is how FIX-1162 settled it. Decision 1 is unaffected: + `create-flow-state` still needs the unscoped name, and it is now the only thing that does. From c19b834b7ffed2fbf40ca8f60767700a71b51b36 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 02:44:09 +0000 Subject: [PATCH 12/30] spec(FIX-548): conform to FIX-1159's wiring contract, and fix two defects that shipped a broken app MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Epic theme 9: the install skill can never reach this template — a brownfield developer installs the plugin and nothing else, theme 4 forbids reading our monorepo, and the template ships inside the published scaffolder. So the template stops being the reference shape the skill points at. FIX-1159 authors a wiring contract and this template conforms to it: the Next.js mount pair, fsdev.config.ts's shape with its store profile, and the dependency set. Recorded as a CONSTRAINT, not a deliverable. Same six files, no new package, artifact or dependency, still the set's only deterministic writer. What moved is authorship of three shapes it was already writing. §2's drift tripwire is re-aimed (both sides cite the contract, rather than the skill citing the template), decision 3's justification shifts from "instructions can point at it" to "conformance can be checked against it", and the FIX-1159 edge is firmer than recorded: it was the library seam plus the printed next-steps block, neither of which touched this template's own files. Node floor. The CLI loads fsdev.config.ts through a native import(), and native type stripping arrives in 22.18 — load-config.ts names it in its runtime-floor note and in the remediation it prints. On 22.0–22.17 the scaffold SUCCEEDED and every printed fsdev command then failed to load the config: the headline outcome breaking silently on a range we advertise. Step 1 now refuses before creating anything. The reasoning is narrower than it looked, and is stated rather than the number alone: the POC settled the shape GIVEN a TypeScript config and never tested the .mjs escape the loader documents. What rules that escape out is a JS config losing type checking on the most error-prone file in the template, FIX-1159 decision 4, and theme 9 making the config's shape a contract — not the POC. The Created summary moves to the wrapper. §5 had init print it while §7's seam hands init no file list, so an implementer had to widen the seam or print a list init cannot verify. The wrapper wrote the files and knows them; this keeps the seam at decision 3's width and is what lets the epic's report-versus-diff check for this issue pass at all. §10 gains two behaviours: the Created summary compared against the actual diff in both directions, and the sub-22.18 refusal leaving the directory untouched. probe.sh is untouched — it stays frozen; this round is prose only. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 119 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 106 insertions(+), 13 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 66e3d9e6c4..0005db89de 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -43,8 +43,11 @@ section, the dependency install, and the block of next steps that gets printed. this spec's previous draft, which had init generate the config and the host wiring while this package supplied only demo content. That boundary existed to stop two deterministic writers duplicating scaffolding logic; after the split there is one, so the line moved. What replaces it -is a **drift** tripwire: the template is the reference shape, checked in as real files, and the -install skill's instructions point at it rather than restating its contents. +is a **drift** tripwire, and epic theme 9 has since re-aimed it. The template is no longer the +reference shape the install skill points at — that skill ships in a plugin and can never reach a +template published inside this scaffolder. Instead **both conform to a wiring contract FIX-1159 +authors**, and the tripwire watches for either one restating the wiring instead of citing it. +This package still writes the shape; it no longer defines it. **Philosophy** — tenet 2 (composition over features): the command's value is the ordering of three things that already exist. Tenet 3 (earn every addition): §6 is mostly about keeping the @@ -90,9 +93,10 @@ file list short and refusing surface — including a `--template` flag with one twice.** *Rejected:* the previous draft's split, where init generated `fsdev.config.*` and the Next route pair and this package supplied only the demo flow and the page. - *Locks in:* the template is a directory a person can read, diff, and point instructions at, - which is what epic theme 1's drift tripwire needs — a shape assembled at runtime from - `create-next-app` output plus init's generator is not readable anywhere. It also means init's + *Locks in:* the template is a directory a person can read and diff, which is what checking it + against **FIX-1159's wiring contract** requires (epic theme 9) — a shape assembled at runtime + from `create-next-app` output plus init's generator is readable nowhere, so nothing could be + held to the contract at all. It also means init's Next-host branch is no longer on this path (§12 raises that with FIX-1159 rather than deciding it). The cost is that a config generator now exists in two places and can drift; the epic accepted exactly that trade when it replaced "no two writers" with "watch for @@ -117,6 +121,28 @@ file list short and refusing surface — including a `--template` flag with one not run, and we add one key. Dependencies and the lockfile still belong entirely to the package manager. Stated out loud because a reviewer should see the exception, not find it. + *Consequence — the generated app needs **Node 22.18+**, and step 1 refuses below it.* The CLI + loads a TypeScript config through a native `import()`, and native type stripping arrives in + **22.18** — `packages/cli/src/load-config.ts` says so in its runtime-floor note and in the + remediation text it prints. Below that the scaffold would finish, print its next steps, and + then **every printed `fsdev` command would fail to load `fsdev.config.ts`**: the epic's + headline outcome breaking silently, on a Node range we advertise as supported. So the check + belongs in step 1's validation, refusing **before any directory is created**, with the floor + and the message init uses — not late, as a config-load error, after a project exists. + + *What actually forces this, stated precisely, because the POC does not.* The POC settled the + config's shape **given that it is TypeScript**; it never tested a `.mjs` config, and the + loader documents `.mjs`/`.js` as a universal escape that would work across all of 22.x. That + escape is rejected on other grounds: a JavaScript config in an otherwise TypeScript template + drops type checking on the most error-prone file in it, contradicts FIX-1159 decision 4 + (TypeScript for the CLI half), and — after epic theme 9 — `fsdev.config.ts`'s shape belongs to + a contract FIX-1159 authors, not to something this template may reformat to widen a Node + range. 22.18 is old enough by now that requiring it costs approximately nobody. + + *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. + 5. **The demo flow reaches whichever provider the developer has a key for, through an intent — it never hard-codes one provider's model.** The config declares `models: { default: , intents: { chat: [anthropic, openai, @@ -287,9 +313,21 @@ $ npm create flow-state my-app AGENTS.md tells your coding assistant how to write FSD flows. ``` -Everything from `Created` down is **init's output, printed by init** (epic theme 5). The three -lines above it are this package's. Two details in the block are load-bearing rather than -cosmetic: `npm exec` needs the `--` separator or npm consumes `--input` as its own configuration +**Who prints what.** The `Created` block is **this package's**, along with the three lines above +it. Everything from `Wrote` down is **init's output, printed by init** (epic theme 5) — that is +where the byte-identical-to-a-standalone-run guarantee applies, and the next-steps block is the +part theme 5 actually binds. + +*This corrects an earlier draft that put `Created` on init's side of the line.* It could not +hold: §7's step-4 table hands init broad declarations that config, flows and wiring exist and +**never a file list**, so init cannot name six files it did not author and was not told about. +The two ways out were widening the seam — giving back the narrowness decision 3 bought — or +printing a summary nobody can know is correct. Neither is needed, because the wrapper wrote those +files and knows exactly what they are. It also matters more than a formatting nit: the epic's +goal check for this issue **compares the run's report against the actual diff**, so a summary +that cannot name what was written is a check that cannot pass. + +Two details in the block are load-bearing rather than cosmetic: `npm exec` needs the `--` separator or npm consumes `--input` as its own configuration and the command fails, and the two-process caveat is real because both printed servers open the same development store. §10 asserts the first by running it. @@ -396,6 +434,11 @@ are exhaustive, which is what keeps the citation and the evidence one-to-one. | 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) | +**Not** crossing the seam: the list of template files. This package prints its own `Created` +summary (§5) because it is the only side that knows what it wrote — init receives declarations, +not filenames. Keeping it out is what holds the seam at the width decision 3 chose, and it is +what lets the run's report be compared against the actual diff (§10). + **Ordering, and why it is not incidental.** The template is written *before* init runs, so init sees a fully declared shape and authors nothing that competes. `create-next-app` must skip its install, or the project installs twice and the second run rewrites the lockfile the first wrote. @@ -439,7 +482,7 @@ package generates a project; it changes no framework behaviour. |---|---| | 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. | +| Node runtime below the floor the generated project needs | Refuse in step 1, before anything is created, with the same floor and the same message init uses. The floor is **22.18** — native type stripping, without which every printed `fsdev` command fails to load `fsdev.config.ts` (decision 4). Do **not** narrow the package's `engines` below the repo-wide `>=22` — that is the scaffolder's own runtime, a different question; FIX-1159 §9 records why. | **The credential stop — after the scaffold exists, before the key is written.** Its own category, because it is neither of the other two and putting it in either produced a @@ -533,6 +576,14 @@ init, in a temporary directory, with no network and no install, **except the thr a missing pin, since `@16` silently re-resolves. The symptoms otherwise are "the first hour is slower", "it behaved differently on my machine", and a version nobody tested - **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5) +- **the `Created` summary names exactly the files the run wrote** — compare the reported list + against the actual diff of the generated directory, in both directions, so a file written but + not reported fails as loudly as one reported but not written. The epic's proof for this issue + requires that comparison; it also pins the seam, since a summary that drifts from the diff is + the first sign the file list has crossed into init +- **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the + message naming the floor, and an untouched target directory. Without it the failure moves to + every printed `fsdev` command, after a project exists (decision 4) - **every printed command runs** — execute the strings the block emitted, in the generated project, and assert the process starts. This is where npm's `--` separator is caught - every refusal in §9's first block, each asserting nothing was created @@ -570,10 +621,27 @@ subprocesses stubbed. **Dependencies.** -- **FIX-1159 blocks implementation, not specification.** This package cannot be built until - init's library seam exists, and cannot merge before init merges. §7's step-4 table is the - required interface; it is **smaller than the previous draft's**, because decision 3 moved the - config and the mount here. +- **FIX-1159 blocks implementation, and now constrains part of this specification.** This package + cannot be built until init's library seam exists, and cannot merge before init merges. §7's + step-4 table is the required interface; it is **smaller than the previous draft's**, because + decision 3 moved the config and the mount here. + + **The edge is firmer than this spec previously recorded it.** It used to be the library seam + plus the shared next-steps block — both about what crosses the seam at runtime and what gets + printed, neither about this template's own files. Epic theme 9 adds the **wiring contract**, + which does constrain them. Specification can still proceed in parallel, but not as far as + before: the shapes below are conformance targets, not local calls. +- **This template conforms to FIX-1159's wiring contract (epic theme 9).** The contract is the + part both entry paths share, and it covers exactly three things: **the Next.js mount pair** + (`app/api/flows/route.ts` + `app/api/flows/[...path]/route.ts`), **`fsdev.config.ts`'s shape** + including its required store profile, and **the dependency set**. This package writes them; + FIX-1159 specifies them. Everything else in §7 — the demo flow, the chat page, the + agent-instructions section, the manifest edit — is this issue's own and is outside the + contract. Recorded so an implementer conforms rather than inventing the mount shape a second + time; the check is theme 8's parity requirement, that this template and the brownfield Next + path deliver the same mounted-route shape. **No new artifact, package or dependency comes with + this**: the contract travels as skill content on the path skill content already takes + (FIX-1159 authors → FIX-1160 packages → the plugin ships). - **Publishing the unscoped `create-flow-state` is a hard prerequisite** (decision 1). Not a naming preference: without it the headline command resolves to nothing, and there is no in-scope workaround, because a scoped publish cannot serve `npm create flow-state`. What is @@ -794,6 +862,31 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions PR that never merges, so any later finding is answered by narrowing a README claim to what the frozen script proves. The reasoning is on the POC README rather than just the rule: a probe that keeps earning rounds is one asserting more than its job requires. +- **Epic theme 9 lands as a constraint, not a deliverable.** The install skill can never reach + this template — a brownfield developer installs the plugin and nothing else — so the template + stopped being the reference shape the skill points at. **FIX-1159 now authors a wiring + contract and this template conforms to it**, covering the Next.js mount pair, + `fsdev.config.ts`'s shape with its store profile, and the dependency set. Nothing is added or + removed: the same six files, no new package, artifact or dependency, and this package remains + the set's only deterministic writer. What moved is authorship of three shapes it was already + writing — it is the contract's consumer, not its source. §2's drift tripwire is re-aimed (both + sides now cite the contract instead of the skill citing the template), decision 3's + justification shifts from "instructions can point at it" to "conformance can be checked + against it", and the FIX-1159 edge is recorded as firmer: it used to be the library seam and + the printed next-steps block, neither of which touched this template's own files. +- **Two defects that would have shipped a broken app.** The generated project needs **Node + 22.18+** — the native type-stripping floor `packages/cli/src/load-config.ts` names twice — + because the CLI loads `fsdev.config.ts` through a native `import()`. Below it the scaffold + *succeeded* and every printed `fsdev` command then failed, which is the headline outcome + breaking silently on a range we advertise. Step 1 now refuses before creating anything. The + reasoning is recorded rather than just the number, and it is narrower than it first looked: + the POC settled the shape *given a TypeScript config* and never tested the `.mjs` escape the + loader documents, so what rules that escape out is a JS config losing type checking on the + most error-prone file, FIX-1159 decision 4, and theme 9 making the config's shape a contract — + not the POC. Separately, §5 had **init** print the `Created` summary while §7's seam hands it + no file list, so an implementer had to widen the seam or print a list init cannot verify. The + summary moves to the wrapper, which wrote the files; that keeps the seam at decision 3's width + and is what lets the epic's report-versus-diff check pass at all. - **§12 overstated the npm mechanism, and it is corrected.** The spec said `npm create ` *and* a bare `fsdev` on the path both need unscoped names. Only the first is true. A command name comes from the package's `bin` key, so `@flow-state-dev/cli` — already declaring From 2ecd4fa98d7f9659ff36eaafed84f4d32960f870 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 11:41:45 +0000 Subject: [PATCH 13/30] spec(FIX-548): settle the import form the POC never tested, and three checks that could not pass MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1 — the POC proved a shape the template does not ship. Its config was self-contained; the real fsdev.config.ts imports src/flows/chat/flow.ts, which is a second resolution question: Turbopack infers a missing extension, native Node does not. As specified the file set had NO import form working for both consumers, so every printed fsdev command would fail while the build stayed green. Settled by execution on a real scaffold, not by argument: ./flow + flag off -> Node ERR_MODULE_NOT_FOUND | next build passes ./flow.ts + flag off -> Node loads | next build TS5097 ./flow.ts + flag ON -> Node loads | next build passes ./flow.js + flag off -> Node ERR_MODULE_NOT_FOUND | Module not found The template now writes allowImportingTsExtensions into the generated tsconfig and uses the .ts specifier. That is a SEVENTH materialised change, and it voids one of decision 4's two stated costs against .mts — flagged in the decision rather than quietly re-decided, since decision 4 is a sign-off surface and it moved after its reasoning was approved. probe.sh was NOT reopened; its README now names this as something it never established. P2 — the selected provider could be ignored. With AI_GATEWAY_API_KEY or OPENROUTER_API_KEY in the environment, providerDetection phase 3 marks every gateway-supported provider available and the intent's fixed order lets the first entry win through the gateway, so the direct key just collected goes unused. Decision 5 now declares providerPreference — existing framework surface that stable-reorders candidates before availability filtering. P2 — §10's Created comparison, which I added last round, could never have passed: the generated directory also holds create-next-app's scaffold, init's files and the lockfile. It now names a baseline — the window between create-next-app returning and init being called — and separately requires the run to report its two edits to files it did not create. §5's transcript gains an Updated block. P2 — §9 told the developer two commands would finish a partly populated directory. Step 1 refuses a non-empty target, init cannot author the template, and brownfield is a non-goal, so no such path exists. It now says inspect and restart, and says why a resume mode is not being added. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 8 ++ spec/FIX-548.md | 107 ++++++++++++++++-- 2 files changed, 104 insertions(+), 11 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index f13852691c..82873ed1ec 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -74,6 +74,14 @@ not merely that the process exited 0. scaffold run with an option deliberately withheld, which buys a fact the spec already acts on at the cost of doubling the probe's slowest step. Stated here, outside the asserted list, rather than dropped, because the spec cites it for the bare-app step's flag discipline. +- **Any import form for a config that imports *another module*.** The config this script drops in + is **self-contained** — it imports nothing. The real `fsdev.config.ts` imports the demo flow, + and that is a second resolution question this probe never asked: Turbopack infers a missing + extension, native Node does not. So every row above speaks to the config's *own* extension and + nothing else. Settled separately, by execution, and recorded in the spec's decision 4: the + relative specifier must carry `.ts` and the generated `tsconfig.json` must set + `allowImportingTsExtensions`. **This is the gap that mattered most** — the probe passed while + the shape the template actually ships had no working import form at all. - **Whether a provider SDK that `@flow-state-dev/core` imports dynamically by package name resolves inside the Next.js server bundle.** `createModelResolver` carries a `directLoadFailed` fallback for exactly this case, so it is a known hazard. Only a real run with a real key diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 0005db89de..d19231a596 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -115,6 +115,33 @@ file list short and refusing surface — including a `--template` flag with one a manifest — see the rule below — and that the generated project is ESM-only, which for a fresh Next 16 TypeScript app is the default posture anyway. + *Amended — the template also sets `allowImportingTsExtensions` in the generated + `tsconfig.json`, and relative TypeScript imports carry `.ts`.* The POC measured the config's + own extension against a **self-contained** config. The real one imports the demo flow, which + is a second resolution question: **Turbopack infers a missing extension, native Node does + not.** Measured on a real scaffold, the four candidate forms: + + | specifier in `fsdev.config.ts` | `allowImportingTsExtensions` | native `import()` | `next build` | + |---|---|---|---| + | `./src/flows/chat/flow` | off | `ERR_MODULE_NOT_FOUND` | passes | + | `./src/flows/chat/flow.ts` | off | loads | `error TS5097` | + | **`./src/flows/chat/flow.ts`** | **on** | **loads** | **passes** | + | `./src/flows/chat/flow.js` | off | `ERR_MODULE_NOT_FOUND` | `Module not found` | + + Only the third satisfies both consumers, so it is what the template ships. Without this the + file set as previously specified had **no working import form at all**: every printed `fsdev` + command would fail to load the config while the build stayed green. + + *This changes the file set and weakens one argument above.* The tsconfig key is a **seventh + materialised change** (§7), not a free one. And `allowImportingTsExtensions` was cited above as + a cost of `.mts`; it is now required either way, so that half of the comparison is void. + Decision 4 still stands on its other grounds — `.ts` is the extension every published doc page + and both in-repo examples use, and `.ts` with no `type` field warns on every CLI command — but + the honest margin against `.mts` is **narrower than this decision first claimed**, and `.mts` + would avoid the manifest edit entirely since it is unambiguously ESM. Flagged rather than + re-decided: this is a sign-off surface, and it moved after the reviewer who approved its + reasoning read it. + *Rule this bends, deliberately:* FIX-1159 decision 3 says the package manager owns `package.json`. That rule protects a manifest **in a repository we did not create**. Here the directory is one this command made seconds earlier, no lockfile exists yet, the install has @@ -146,7 +173,18 @@ file list short and refusing surface — including a `--template` flag with one 5. **The demo flow reaches whichever provider the developer has a key for, through an intent — it never hard-codes one provider's model.** The config declares `models: { default: , intents: { chat: [anthropic, openai, - google] } }`, and only the chosen provider's `@ai-sdk/*` package is installed. + google] }, providerPreference: [] }`, and only the chosen provider's + `@ai-sdk/*` package is installed. + + **`providerPreference` is required, not decoration.** Without it the developer's choice can be + silently discarded: if `AI_GATEWAY_API_KEY` or `OPENROUTER_API_KEY` is already in the + environment, `providerDetection`'s phase 3 marks **every** gateway-supported provider + available, the intent's fixed candidate order stands, and the first entry wins through the + gateway while the direct key just collected goes unused. A developer with a gateway key in + their shell is common, not an edge case, and no clean-environment run can see it — which is + why it is stated here rather than left to the goal check. `providerPreference` stable-reorders + each intent's candidates before availability filtering, so the chosen provider is tried first + and the fallback order behind it is unchanged. Existing framework surface; nothing new. *Rejected:* a hard-coded `openai/gpt-5.4-mini` in the flow, which is what the reference example does. *Locks in:* the prompt offers three providers and all three work, because the resolver picks @@ -296,6 +334,8 @@ $ npm create flow-state my-app Created fsdev.config.ts lib/flowstate.ts src/flows/chat/flow.ts app/page.tsx app/api/flows/route.ts app/api/flows/[...path]/route.ts + Updated package.json ("type": "module") + tsconfig.json (allowImportingTsExtensions) Wrote .env.local (OPENAI_API_KEY, already ignored by git) Appended AGENTS.md (FSD section) Installed via npm @@ -313,8 +353,10 @@ $ npm create flow-state my-app AGENTS.md tells your coding assistant how to write FSD flows. ``` -**Who prints what.** The `Created` block is **this package's**, along with the three lines above -it. Everything from `Wrote` down is **init's output, printed by init** (epic theme 5) — that is +**Who prints what.** The `Created` and `Updated` blocks are **this package's**, along with the +three lines above them. `Updated` is not cosmetic: those two keys are edits to files +`create-next-app` wrote, so a summary listing only new paths would silently omit the two changes +a reader is most likely to want flagged. Everything from `Wrote` down is **init's output, printed by init** (epic theme 5) — that is where the byte-identical-to-a-standalone-run guarantee applies, and the next-steps block is the part theme 5 actually binds. @@ -394,8 +436,10 @@ rare event — a starter a few months behind on Next is a real cost, and the alt starter that breaks without warning. §9's drift row is the same failure either way; the pin only decides whose terminal it happens in. -**Step 3 — write the template.** Six files, materialized from `templates/nextjs-chat/`, plus one -manifest key. This is the entire product surface: +**Step 3 — write the template.** Six files, materialized from `templates/nextjs-chat/`, plus +**two keys in files `create-next-app` wrote** — `"type": "module"` in the manifest and +`allowImportingTsExtensions` in `tsconfig.json`. Both are decision 4's, and the second is what +makes the config loadable by the CLI at all. This is the entire product surface: | file | what it is | |---|---| @@ -406,6 +450,7 @@ manifest key. This is the entire product surface: | `app/api/flows/route.ts` | the sibling bare route. `list_flows` is registered as `GET /` on the mount base and the client's `listFlows()` requests it, but a required catch-all cannot match zero segments. `@flow-state-dev/next` exports no bare handler (only `@flow-state-dev/vercel` does), so this one forwards by hand with a comment saying why — carrying the same route exports as its sibling | | `app/page.tsx` | the chat page. `FlowProvider` + `useFlow` + `useSession` + `ItemsRenderer` from `@flow-state-dev/react`, no other imports (decision 6). Overwrites `create-next-app`'s stock page — permitted, because this is a directory this command created seconds ago | | *manifest* | `"type": "module"` added — decision 4. Nothing else; dependencies and the lockfile are the package manager's | +| *tsconfig* | `allowImportingTsExtensions: true` added — decision 4. Required, not stylistic: the config imports the demo flow, native Node will not infer the extension, and the `.ts` specifier that satisfies Node is a `TS5097` error without this key. Nothing else in the file is touched | **Why the config shape is what it is — measured.** The template's config has two consumers at once: Turbopack, because the route imports it, and the CLI's native `import()`. Nobody had @@ -498,9 +543,19 @@ no-rollback rule directly below. **Failures after work has started — nothing rolls back:** +*Why the `create-next-app` row promises a restart and not a repair.* The previous wording told +the developer two commands would finish a partly-populated directory. Nothing in this spec makes +that true: step 1 **refuses a non-empty target**, so re-running the command on it is rejected; +init does not author the six template files, so it cannot complete the shape; and applying the +template to a directory somebody else's tool partly filled is the brownfield case, which is an +explicit non-goal. A resume mode would need all three of those to change, and it would be a +deterministic writer merging into a directory of unknown state — the exact shape the epic removed +from this set. So the honest instruction is restart, and it is cheap here in a way it is not +elsewhere: the directory is seconds old and contains nothing the developer authored. + | Case | Expected | |---|---| -| `create-next-app` fails, is unreachable, or rejects a flag | Report its output, name the directory as it stands, and print the two commands that finish the job by hand. Do not delete it. | +| `create-next-app` fails, is unreachable, or rejects a flag | Report its output and **name the target as partially populated and not resumable**. Do not delete it — it is the developer's directory and it may hold their evidence. Print inspect-and-restart instructions: review what is there, then remove it (or pick a new name) and re-run the command. **Do not print "two commands that finish the job by hand"** — see below. | | `create-next-app` changes its flag surface or generated layout | The **exact** pinned version (§7 step 2) means an upstream change cannot reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. A major-range pin would not hold that. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | | The pinned `create-next-app` falls behind | New projects start on an older Next than current. Bumping the pin is scheduled maintenance gated on a goal-check run, not a reaction to breakage. | | Init fails after the template was written | The scaffold stays. Print init's own retry command against that directory. Mirrors init's install-failure taxonomy, which also leaves files and prints the retry. | @@ -576,11 +631,18 @@ init, in a temporary directory, with no network and no install, **except the thr a missing pin, since `@16` silently re-resolves. The symptoms otherwise are "the first hour is slower", "it behaved differently on my machine", and a version nobody tested - **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5) -- **the `Created` summary names exactly the files the run wrote** — compare the reported list - against the actual diff of the generated directory, in both directions, so a file written but - not reported fails as loudly as one reported but not written. The epic's proof for this issue - requires that comparison; it also pins the seam, since a summary that drifts from the diff is - the first sign the file list has crossed into init +- **the `Created` summary names exactly the template files this package materialised** — compare + in both directions, so a template file written but not reported fails as loudly as one reported + but not written. **The baseline is what makes this checkable**: snapshot the directory after + `create-next-app` returns and before step 3, and compare against the snapshot taken after step + 3 but before init is called. That window contains exactly this package's writes. Everything + outside it is somebody else's and is not in this list — `create-next-app`'s own scaffold before + it, and init's `.env.local`, `AGENTS.md` append, dependencies and lockfile after it. +- **the run reports every change it makes to a file it did not create** — the two decision-4 keys, + in `package.json` and `tsconfig.json`. They are edits to `create-next-app`'s files rather than + new paths, so a filename-only summary misses them entirely, and they are precisely the changes + a reader would be surprised by. The epic's proof compares the run's report against the actual + diff; a report that omits its own edits fails that comparison for a real reason - **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the message naming the floor, and an untouched target directory. Without it the failure moves to every printed `fsdev` command, after a project exists (decision 4) @@ -887,6 +949,29 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions no file list, so an implementer had to widen the seam or print a list init cannot verify. The summary moves to the wrapper, which wrote the files; that keeps the seam at decision 3's width and is what lets the epic's report-versus-diff check pass at all. +- **The POC had proved a shape the template does not ship, and it changed a decision.** Its config + was **self-contained**; the real one imports the demo flow, which is a second resolution + question nobody had asked — Turbopack infers a missing extension, native Node does not. As + specified, the file set had **no import form that worked for both consumers**: every printed + `fsdev` command would have failed while the build stayed green. Measured on a real scaffold: + extensionless fails Node, `.ts` fails the build with `TS5097`, `.js` fails both, and only `.ts` + **plus `allowImportingTsExtensions`** satisfies both. The template now writes that key, which + makes it a **seventh materialised change** and voids one of decision 4's two stated costs + against `.mts` — flagged in the decision rather than quietly re-decided, since that decision is + a sign-off surface and it moved after the reasoning was approved. The frozen probe was not + reopened; its README now names this as something it never established. +- **Three more, each a case a clean-environment run cannot see.** With a gateway key already in + the environment, phase 3 of provider detection marks every provider available and the intent's + fixed order hands the request to the first entry — so the provider the developer just chose + went unused. Decision 5 now declares `providerPreference`, existing framework surface that + stable-reorders candidates. §10's `Created` comparison, added last round, could never have + passed: the generated directory also holds `create-next-app`'s scaffold, init's files and the + lockfile, so the check now names a **baseline** — the window between `create-next-app` + returning and init being called — and separately requires the run to report its two edits to + files it did not create. And §9 told a developer that two commands would finish a partly + populated directory; step 1 refuses a non-empty target, init cannot author the template, and + brownfield is a non-goal, so it promised a repair path that does not exist. It now says + restart, which is honest and cheap on a directory seconds old. - **§12 overstated the npm mechanism, and it is corrected.** The spec said `npm create ` *and* a bare `fsdev` on the path both need unscoped names. Only the first is true. A command name comes from the package's `bin` key, so `@flow-state-dev/cli` — already declaring From 404e82c6925c864634b98b88d7a4d030d644f58e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 14:30:12 +0000 Subject: [PATCH 14/30] spec(FIX-548): make the deliverable, the summary categories and the failure copy agree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 3 of the implementation sequence still scoped the template to six files plus the manifest key, so an implementer could complete the listed deliverable exactly as written and still ship a config whose .ts import of the demo flow fails with TS5097. It now names both edits to create-next-app's files, and its test asserts the config loads with the flow imported THROUGH it rather than as a self-contained module — the gap that produced the P1 in the first place. app/page.tsx was listed under Created while Updated was defined as edits to scaffolder-owned files, and page.tsx replaces the stock Next.js page. A successful run therefore misreported one of the wrapper's own changes. The categories are now defined by what the run did to the developer's directory: Created is a path that did not exist, Updated is any change to a file create-next-app wrote — two added keys and one wholesale replacement. §10 asserts all three and asserts the category, not just the name. The failure taxonomy still said every failure leaves a directory the developer can finish by hand, which contradicts §9's now-explicit position that a partly-populated create-next-app target is not resumable. Split: an init failure can be finished by init's own retry command, a failed create-next-app cannot and gets inspect-and-restart. POC README gains a stated precondition: Node 22.18+. Below the type-stripping floor the native imports cannot produce the documented clean result, so the probe exits 1 when it should exit 2. Answered in the README under the file's own rule rather than by reopening the frozen script — a closed artifact with a documented requirement is smaller than one that keeps growing environment handling, and the failure is loud (every variant mismatches at once) rather than subtle. probe.sh untouched. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 10 ++++ spec/FIX-548.md | 46 +++++++++++++------ 2 files changed, 42 insertions(+), 14 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index 82873ed1ec..b14c2479d9 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -7,6 +7,16 @@ bundler** (the mounted route imports it) and the **`fsdev` CLI** (a native `impo FIX-1159 decision 4 settles the CLI half by using `.mts`. Nobody had checked the bundler half, and the whole product — a streamed response rendered in a browser — runs through it. +**Precondition: Node 22.18 or newer.** Native TypeScript type stripping arrives in 22.18, and +every variant here loads a TypeScript config through a native `import()`. On 22.0–22.17 those +imports cannot produce the clean result the table documents, so the script reports mismatches and +**exits 1 — which on that runtime means nothing at all.** Read a run on older Node as *not +performed*, never as a claim disproved. This is a stated precondition rather than a check inside +the script, because the script is frozen (below) and a closed artifact with a documented +requirement is smaller and more honest than one that keeps growing environment handling. The +failure is also loud rather than subtle: every variant mismatches at once, which reads as a +broken environment, not as a finding. + Run it: `bash probe.sh [workdir]` (needs network; ~3 minutes). It scaffolds a real `create-next-app@16.3.1` project, drops each candidate config shape in, and runs `next build`, `next dev`, and a native `import()` against each. It refuses to run if `/probe` already diff --git a/spec/FIX-548.md b/spec/FIX-548.md index d19231a596..2f128969f2 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -332,10 +332,11 @@ $ npm create flow-state my-app Running fsdev init … Created fsdev.config.ts lib/flowstate.ts - src/flows/chat/flow.ts app/page.tsx - app/api/flows/route.ts app/api/flows/[...path]/route.ts + src/flows/chat/flow.ts app/api/flows/route.ts + app/api/flows/[...path]/route.ts Updated package.json ("type": "module") tsconfig.json (allowImportingTsExtensions) + app/page.tsx (replaced — the stock Next.js page) Wrote .env.local (OPENAI_API_KEY, already ignored by git) Appended AGENTS.md (FSD section) Installed via npm @@ -354,9 +355,12 @@ $ npm create flow-state my-app ``` **Who prints what.** The `Created` and `Updated` blocks are **this package's**, along with the -three lines above them. `Updated` is not cosmetic: those two keys are edits to files -`create-next-app` wrote, so a summary listing only new paths would silently omit the two changes -a reader is most likely to want flagged. Everything from `Wrote` down is **init's output, printed by init** (epic theme 5) — that is +three lines above them. The split is by **what the run did to the developer's directory**, not by +which of our steps did it: `Created` is a path that did not exist, `Updated` is any change to a +file `create-next-app` wrote — two added keys and one wholesale replacement. `app/page.tsx` sits +in `Updated` for that reason. It is a template file, but reporting it as *created* would +misdescribe the one change most likely to surprise someone who had glanced at the stock page, +and a summary listing only new paths would omit all three of the run's edits. Everything from `Wrote` down is **init's output, printed by init** (epic theme 5) — that is where the byte-identical-to-a-standalone-run guarantee applies, and the next-steps block is the part theme 5 actually binds. @@ -502,9 +506,14 @@ package generates a project; it changes no framework behaviour. 2. **The bare-app step** — spawn `create-next-app` with every flag explicit and install skipped; surface its failure. *Test:* the argv built (complete enough that no option resolves from saved preferences; install skipped), and the failure path's output. *Depends on:* 1. -3. **The template** — the six files and the manifest key. - *Test:* the generated project builds and its mounted route serves; the config loads under a - native `import()` with no warning; `.env.local` is ignored by git before the key is written. +3. **The template** — the six files **and both edits to files `create-next-app` wrote**: + `"type": "module"` in `package.json` and `allowImportingTsExtensions` in `tsconfig.json`. + Neither is optional and the second is not cosmetic — without it the config's `.ts` import of + the demo flow is a `TS5097` build error, and with an extensionless import instead the CLI + cannot load the config at all (decision 4). + *Test:* the generated project builds and its mounted route serves; **the config loads under a + native `import()` with the demo flow imported through it**, not as a self-contained module, + with no warning; `.env.local` is ignored by git before the key is written. *Depends on:* nothing. 4. **The init handoff** — call init with the declared shape and collected answers, print what it returns. *Test:* the call ordering (template before init), the arguments crossing the seam, @@ -566,7 +575,13 @@ elsewhere: the directory is seconds old and contains nothing the developer autho **Taxonomy — three categories, and the middle one exists because the first two could not hold it.** Refusals happen before anything is created and leave the disk untouched. The credential stop happens after the scaffold exists and leaves it there, minus the key. Failures leave a -directory the developer can inspect and finish by hand. Nothing is ever cleaned up behind the +directory the developer can **inspect** — and only some of them leave one that can be *finished*. +**An init failure can**: the six template files and all three edits are already on disk, so +init's own retry command against that directory completes it. **A failed `create-next-app` +cannot**: the target is partly populated by a tool we do not control, step 1 refuses a non-empty +target, init does not author the template, and brownfield is a non-goal — so there the +instruction is inspect and restart (§9). Promising "finish by hand" across both is the +contradiction this taxonomy used to carry. Nothing is ever cleaned up behind the user, because deleting a directory a stranger may have put something in is worse than leaving one they can `rm` — which is also why the credential stop does not "undo" the scaffold to qualify as a refusal. @@ -638,11 +653,14 @@ init, in a temporary directory, with no network and no install, **except the thr 3 but before init is called. That window contains exactly this package's writes. Everything outside it is somebody else's and is not in this list — `create-next-app`'s own scaffold before it, and init's `.env.local`, `AGENTS.md` append, dependencies and lockfile after it. -- **the run reports every change it makes to a file it did not create** — the two decision-4 keys, - in `package.json` and `tsconfig.json`. They are edits to `create-next-app`'s files rather than - new paths, so a filename-only summary misses them entirely, and they are precisely the changes - a reader would be surprised by. The epic's proof compares the run's report against the actual - diff; a report that omits its own edits fails that comparison for a real reason +- **the run reports every change it makes to a file it did not create** — all **three**: the two + decision-4 keys in `package.json` and `tsconfig.json`, and the wholesale replacement of + `app/page.tsx`. None is a new path, so a filename-only summary misses every one of them, and + they are precisely the changes a reader would be surprised by. Assert the category too, not + just the presence of the name: a run that reports `app/page.tsx` as *created* has misdescribed + what it did to a file the developer may have already opened. The epic's proof compares the + run's report against the actual diff; a report that omits or miscategorises its own edits fails + that comparison for a real reason - **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the message naming the floor, and an untouched target directory. Without it the failure moves to every printed `fsdev` command, after a project exists (decision 4) From 48d2a52d98856c69d180914eba35bff413e92ea0 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 00:19:38 +0000 Subject: [PATCH 15/30] spec(FIX-548): take the five jobs nobody owned, wire the FIX-1160 edge, reverse decision 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three defects a cross-spec sweep found, plus the epic's pending re-approval batch. FIX-1159 decision 1 ships no `fsdev init` — not the command and not a library behind it — and disclaims 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, while seven sections still described a seam to a command that will not exist. Decision 3 takes them and states the cost: no seam, Medium not Small, and normalized equality against canonical text in place of "byte-identical to a standalone init run". Epic theme 9 (c) and FIX-1160 §7 both assert a FIX-1160 -> FIX-548 merge edge and §12 carried no FIX-1160 dependency at all, so a package built from this spec would have embedded nothing and merged before its content had an author. Recorded and wired in Linear. Decision 5 specified the `models` shorthand with an intent ladder; the wiring contract requires a statically imported provider passed as a pre-built modelResolver. Restated as the reversal it is, because the argument reversed with the mechanism: providerPreference reorders intent candidates and there are no intents, and a declared provider never reaches the availability map the gateway hijack needed. §12 also corrects the contract's surface from three items to five. The ask argued for a withdrawn recommendation resting on a two-command path that does not exist and a goal check FIX-1159 deleted. Rewritten as a three-way fork recommending one starter plus a specified minimal-project brownfield path, falling back to shipping both. Also folded, one round: theme 9 devolution (both blocks embedded verbatim including unrendered branches, shipper-side comparison, digest marker deleted), theme 6 exception (c) and theme 8 (dev and start narrowed to loopback, production refusal, both proved by negative assertions), the pnpm-isolated install, the 22.18 floor wording, and the transcript's userId key. §12's registry premise is corrected: create-flow-state is published at 0.0.0 and ours. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 934 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 658 insertions(+), 276 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 2f128969f2..aa0f0d372e 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -35,9 +35,17 @@ in the developer's browser. Three things happen in order. The bare Next.js app comes from Next's own scaffolder. **Then this package writes its template** — the config, the route that serves flows, the demo flow, and the -page that talks to it. Then `fsdev init` is called in-process for the parts that must not exist -twice anywhere: the API key, the ignore entry that keeps it out of git, the agent-instructions -section, the dependency install, and the block of next steps that gets printed. +page that talks to it. **Then this package finishes the project itself**: the API key, the ignore +entry that keeps it out of git, the agent-instructions section, the dependency install, and the +block of next steps that gets printed. + +**Those last five used to be somebody else's, and they are not any more.** An earlier draft handed +them to `fsdev init`, called in-process. **There is no `fsdev init`** — FIX-1159 decision 1 ships +neither the command nor a library entry point behind it, and the epic's objective hands this issue +the template *"end to end … the agent-instructions file"*. So this package is the greenfield path +in every part, and §6 decision 3 says what that costs. What must not exist twice is not the *work* +but the **text**: two of those five print or write a block authored by another issue, and this +package embeds each verbatim rather than restating it (§7). **This package owns the template end to end** (epic theme 1, re-drafted). That is a change from this spec's previous draft, which had init generate the config and the host wiring while this @@ -74,11 +82,16 @@ file list short and refusing surface — including a `--template` flag with one dependency** — the previous draft treated the name as a convenience that removed a blocker, which is what let a scoped fallback look harmless. -2. **One template ships: the Next.js chat app. The framework-neutral Node API template is cut - from v1.** *This reverses epic theme 2 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 recorded goal - run per release rather than two. +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.* Everything else in this document is written against one template and + changes only in `templates//` if the answer is two. + *Rejected:* two templates, as epic theme 2 decided — **conditionally**, and the condition is + the point: the fallback if the minimal-project path is not taken up is to ship both, not to + ship one anyway. + *Locks in:* one starter to keep green on machines we do not control, and three recorded goal + runs per release rather than six. 2b. **No `--template` flag in v1.** *Rejected:* shipping the flag with one legal value to signal the plan. A flag whose only argument was a template decision 2 just cut is surface @@ -88,19 +101,45 @@ file list short and refusing surface — including a `--template` flag with one and adding a flag nobody could have been passing breaks no invocation. If decision 2 is overturned, the flag arrives with the template it selects between. -3. **`create-flow-state` writes the whole FSD half of the template as real checked-in files — - config, mount, flow, page — and calls `fsdev init` only for the parts that must not exist - twice.** +3. **`create-flow-state` is the greenfield path in every part.** It writes the whole FSD half of + the template as real checked-in files — config, mount, flow, page — **and it also does the + five jobs an earlier draft routed to `fsdev init`: the API key, the ignore entry, the + agent-instructions section, the dependency install, and the printed next-steps block.** *Rejected:* the previous draft's split, where init generated `fsdev.config.*` and the Next - route pair and this package supplied only the demo flow and the page. + route pair and this package supplied only the demo flow and the page. **Also rejected: keeping + the five jobs behind an init library call** — see below; that is not a preference this spec + holds, it is an option that no longer exists. *Locks in:* the template is a directory a person can read and diff, which is what checking it against **FIX-1159's wiring contract** requires (epic theme 9) — a shape assembled at runtime from `create-next-app` output plus init's generator is readable nowhere, so nothing could be - held to the contract at all. It also means init's - Next-host branch is no longer on this path (§12 raises that with FIX-1159 rather than - deciding it). The cost is that a config generator now exists in two places and can drift; - the epic accepted exactly that trade when it replaced "no two writers" with "watch for - drift", and §10 spends a CI check on it. + held to the contract at all. + + **Why the five jobs are here, and why there is no elsewhere to send them.** FIX-1159 decision + 1: *"This issue ships no `fsdev init` — not the command, and not a library entry point behind + it. The only artifact that crosses to FIX-548 is the next-steps block."* It names the same five + jobs and routes them here, citing the epic's objective (this issue gets the template *"end to + end … the agent-instructions file"*) and the epic's greenfield transcript, which has no init + step in it. **Checked from the other side too, because that is where an unowned job survives a + review:** FIX-1159's §3 hears the library option and rejects it on its own merits — brownfield + is instructions plus scripts and instructions make no in-process calls, so the library would be + a single-use abstraction in another issue's package, adding a build-and-merge edge between two + issues the epic wants running in parallel. **Both ends now name this issue, so the jobs have an + owner and the epic's greenfield proof has an implementer.** This spec previously disclaimed + them in its Non-goals while depending on them everywhere else, which left five jobs and one + goal check owned by nobody. + + **What that costs, stated rather than absorbed.** The narrow seam this decision used to buy is + gone — there is no seam. §8 gains the credential write, the install, and the printed block as + this package's own steps; §10 gains their behaviours; and the "byte-identical to a standalone + init run" check is meaningless, replaced by normalized equality against FIX-1159's canonical + text (epic theme 9 (a)). **Single authorship survives the change and is the part that + mattered**: FIX-1159 still authors the next-steps text and FIX-1160 the agent-instructions + text; this package embeds each verbatim and asserts it with the author's exported comparison. + What is lost is only the claim that another command was doing the work. + + The remaining cost is unchanged: a config generator exists in two places and can drift. The + epic accepted exactly that trade when it replaced "no two writers" with "watch for drift", and + §10 spends a CI check on it. 4. **The template's config is `fsdev.config.ts`, and the template adds `"type": "module"` to the manifest `create-next-app` just wrote.** Measured, not assumed — see the POC in §7. @@ -132,8 +171,8 @@ file list short and refusing surface — including a `--template` flag with one file set as previously specified had **no working import form at all**: every printed `fsdev` command would fail to load the config while the build stayed green. - *This changes the file set and weakens one argument above.* The tsconfig key is a **seventh - materialised change** (§7), not a free one. And `allowImportingTsExtensions` was cited above as + *This changes the file set and weakens one argument above.* The tsconfig key is a **materialised + change in its own right** (§7's table of four), not a free one. And `allowImportingTsExtensions` was cited above as a cost of `.mts`; it is now required either way, so that half of the comparison is void. Decision 4 still stands on its other grounds — `.ts` is the extension every published doc page and both in-repo examples use, and `.ts` with no `type` field warns on every CLI command — but @@ -155,7 +194,9 @@ file list short and refusing surface — including a `--template` flag with one then **every printed `fsdev` command would fail to load `fsdev.config.ts`**: the epic's headline outcome breaking silently, on a Node range we advertise as supported. So the check belongs in step 1's validation, refusing **before any directory is created**, with the floor - and the message init uses — not late, as a config-load error, after a project exists. + and the wording the wiring contract's runtime-floor rule fixes (epic theme 9 (b), which binds + both entry paths to the same number and the same guidance) — not late, as a config-load error, + after a project exists. *What actually forces this, stated precisely, because the POC does not.* The POC settled the config's shape **given that it is TypeScript**; it never tested a `.mjs` config, and the @@ -170,27 +211,60 @@ file list short and refusing surface — including a `--template` flag with one 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. -5. **The demo flow reaches whichever provider the developer has a key for, through an intent — - it never hard-codes one provider's model.** The config declares - `models: { default: , intents: { chat: [anthropic, openai, - google] }, providerPreference: [] }`, and only the chosen provider's - `@ai-sdk/*` package is installed. - - **`providerPreference` is required, not decoration.** Without it the developer's choice can be - silently discarded: if `AI_GATEWAY_API_KEY` or `OPENROUTER_API_KEY` is already in the - environment, `providerDetection`'s phase 3 marks **every** gateway-supported provider - available, the intent's fixed candidate order stands, and the first entry wins through the - gateway while the direct key just collected goes unused. A developer with a gateway key in - their shell is common, not an edge case, and no clean-environment run can see it — which is - why it is stated here rather than left to the goal check. `providerPreference` stable-reorders - each intent's candidates before availability filtering, so the chosen provider is tried first - and the fallback order behind it is unchanged. Existing framework surface; nothing new. - *Rejected:* a hard-coded `openai/gpt-5.4-mini` in the flow, which is what the reference - example does. - *Locks in:* the prompt offers three providers and all three work, because the resolver picks - the first candidate with both a key and an installed SDK package. A hard-coded model plus an - Anthropic key is a first-run failure with a confusing error, and it is the failure a - three-way prompt makes most likely. +5. **The config statically imports the chosen provider, passes it as a pre-built `modelResolver`, + and the demo flow names that provider's exact model string. No intents, no + `providerPreference`, no `models` shorthand.** The generated `fsdev.config.ts` carries + `import { createOpenAI } from "@ai-sdk/openai"` (or the sibling for the provider chosen at the + prompt), builds `createModelResolver({ providers: { openai } })`, and passes the result as + `modelResolver`. Only that provider's `@ai-sdk/*` package is installed. The three + provider/factory/env-var/model rows come from **FIX-1159's provider table**, which the wiring + contract fixes; this template does not pick them: + + | provider chosen | statically imported | env var | model string the demo flow names | + |---|---|---|---| + | `openai` | `createOpenAI` from `@ai-sdk/openai` | `OPENAI_API_KEY` | `openai/gpt-5.4-mini` | + | `anthropic` | `createAnthropic` from `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY` | `anthropic/claude-haiku-4-5` | + | `google` | `createGoogle` from `@ai-sdk/google` | `GOOGLE_GENERATIVE_AI_API_KEY` | `google/gemini-3.1-flash-lite` | + + *Rejected:* **the `models: { default, intents, providerPreference }` shorthand this decision + previously specified** — see the reversal below. Also rejected: a fixed `openai/gpt-5.4-mini` + regardless of the provider chosen, which is what the reference example does and which fails on + an Anthropic key. + *Locks in:* the first browser request works. `createModelResolver` reaches an *un*-declared + provider through `createRequire` and a dynamic `import()`, and **Next bundles server code, + which breaks that path** — our own published guide says so and gives this exact fix + (`apps/docs/guides/deploying-to-vercel.md`: *"Next.js bundles server code, breaking the model + resolver's dynamic `require()` path. Pass a pre-built `modelResolver` with static provider + imports instead of the `models` shorthand."*). Read in the resolver source: an explicit + provider entry is invoked directly, so `isPackageProviderAvailable`, the `directLoadFailed` + set and the gateway fall-through are **never reached at all** on this path. + + *No intents, and that is a decision rather than an omission.* `defaultModel` is **required** + the moment `intents` is non-empty and `createModelResolver` throws at construction otherwise — + which in a generated project means `createFlowState` fails and every printed command dies + before it runs. A demo flow needs one model, so it names one. + + **This reverses the decision it replaces, and the reversal is the point rather than an edit.** + The previous decision 5 declared the `models` shorthand with an intent ladder over all three + providers, and it was argued on a real hazard: with `AI_GATEWAY_API_KEY` in the developer's + shell, `providerDetection`'s phase 3 marks every gateway-supported provider available, the + intent's fixed candidate order stands, and the first entry wins through the gateway while the + direct key just collected goes unused. `providerPreference` was there to stable-reorder the + candidates and stop that. **All of that argument is void under the wiring contract, and void is + the honest word — not "superseded".** `providerPreference` reorders *intent candidates*, and + there are no intents. The gateway hijack it guarded needs the availability map, which an + explicit provider entry never consults. The "prompt offers three providers and all three work" + argument survives, but for a different mechanism: the template emits a **different config per + provider** — different import, different factory, different model string — rather than one + config with a fallback ladder. **A reviewer who approved the old decision approved a mechanism + and an argument that have both reversed**, which is why this is restated as a changed decision + on the sign-off surface rather than folded quietly. + + *What the reversal costs.* The generated project no longer falls back to a second provider if + the first has no key — it has exactly one, chosen at the prompt. That is the right trade for a + demo (the fallback ladder was solving a problem a one-provider prompt does not have), but it is + a real behaviour change and §10's per-provider goal runs get *more* load-bearing because of it: + three runs now exercise three genuinely different emitted files rather than one file's ladder. 6. **The demo chat page adds no user-interface dependencies. One file, `@flow-state-dev/react`, and nothing else.** @@ -203,7 +277,7 @@ file list short and refusing surface — including a `--template` flag with one 7. **No path writes the API key before it has proven git will not publish it.** The template's host scaffold happens to cover this already (verified: git ignores `.env.local` in a fresh `create-next-app` scaffold), so this is an assertion, not a code branch: check, add our own - entry if the check fails, and only then let init write the key. + entry if the check fails, and only then write the key. *Rejected:* assuming the entry is there because we saw it once — it is someone else's file — **and checking it by reading `.gitignore` for a rule that looks right.** The check must ask git about `.env.local` itself (`git check-ignore`), because a `.gitignore` that lists only @@ -213,60 +287,129 @@ file list short and refusing surface — including a `--template` flag with one the one failure a diff review does not catch, because it looks like every other added line. §10 asserts it by running `git check-ignore`, not by reading the file. -**Non-goals** — anything `fsdev init` does for credentials, the agent-instructions section, the -install, and the next-steps block (FIX-1159's, and none of it exists twice here); the *content* -of the agent-instructions file (FIX-1160); the brownfield path in any form; an `--upgrade` mode -that regenerates config in an existing project; and any template beyond the one decision 2 -settles. - -**Size:** Small — 6 template files · 1 package entry · ~10 test behaviours · 3 doc surfaces · -2 PRs. *Deliberately small: if this grows detection or merge logic, epic theme 1 says that is +8. **The generated project is never reachable off the developer's own machine without + authentication — and the control is the bind, not a credential.** Two parts, both this + template's: + - **`scripts.dev` and `scripts.start` are narrowed to loopback** — `next dev --hostname + 127.0.0.1` and `next start --hostname 127.0.0.1`. The printed commands do not change; the + developer still types `npm run dev`. + - **The demo flow refuses to serve outside development on the default resolver.** Declared on + the flow itself, so a request in production mode is refused **before any model invocation**, + with an error naming the missing authentication. + + *Rejected:* **a credential, which is what protects the brownfield path.** It cannot work here + and the reason is the client, not the effort: the chat page is a client component using + `@flow-state-dev/react`, which fetches and opens SSE against `/api/flows/*` **from the + browser**. Any token that page can present is one an attacker can read by loading the same + page, and on a dev server bound to every interface they can load it. Also rejected: printing + `npm run dev -- --hostname 127.0.0.1` in the next-steps block, which leaves the plain `npm run + dev` that `create-next-app` itself advertises live and exposed; and a second script under a key + we own, which does the same and puts two dev commands in a four-second-old project. + *Locks in:* `next dev` **and** `next start` default to `0.0.0.0`, and this template never goes + through `@flow-state-dev/node`, so the loopback rail + `docs/architecture/authentication.md` names as the protection for default-resolver apps is not + in the path at all. Without the bind, `npm run dev` puts an unauthenticated flow that calls a + real model on the developer's key onto whatever network they are on. `start` is the worse of + the two — someone running `npm run build && npm start` is by definition not on their laptop. + And binding scripts closes only self-hosting: a platform deploy runs neither script, which is + why the second part exists and is adapter-independent. + + *Rule this bends, deliberately — and it is the epic's exception, not this spec's.* + `scripts.dev` and `scripts.start` are keys `create-next-app` wrote, and theme 6 (b) says every + unowned key keeps its value. Epic **theme 6 exception (c)** carves out exactly these two, for + exactly this path: greenfield only, on keys whose stock value we caused to exist seconds + earlier, an edit that only ever *narrows* a bind and reverts in one word. It does not reach + brownfield. §5's transcript reports the change and §10 asserts it, because a + `scripts` edit would otherwise read as a violation of the additive guarantee. + + *This is a product statement, not a footnote:* **the generated app does not serve off-host + until its authentication is configured.** For a demo scaffold that is the right default, and + the owner should see it as a promise about what the thing does rather than as an + implementation note. + +**Non-goals** — the *content* of the agent-instructions block (FIX-1160 authors it; this package +places it) and of the next-steps block (FIX-1159 authors it; this package prints it); the +brownfield path in any form, including the wiring contract this template conforms to (FIX-1159 +specifies it, this package writes it); an `--upgrade` mode that regenerates config in an existing +project; and any template beyond the one decision 2 settles. + +*This section previously disclaimed the API key, the ignore entry, the agent-instructions section, +the install and the printed block as "anything `fsdev init` does". There is no `fsdev init`, and +FIX-1159 disclaims the same five in its own Non-goals — so as written they were owned by nobody +while the epic's greenfield proof named every one of them. Decision 3 takes them.* + +**Size:** Medium — 6 template files · 4 changes to files `create-next-app` wrote · 2 verbatim +embedded blocks + their comparison assertions · 1 package entry doing its own credential write, +install and print · ~20 test behaviours · 3 doc surfaces · 2 PRs. *This was "Small" while five +jobs sat on the other side of a seam that does not exist; the seam's removal is where the size +went. It is still bounded by epic theme 1's test: if this grows detection or merge logic, that is the signal it belongs in the skill, not here.* --- #### The ask — does the Node API template ship? -**The fork.** One starter template (a Next.js chat app), or two (that, plus a framework-neutral -Node API)? - -**Plain terms.** A template is the working project someone gets from our one command. The -Next.js one ends at a chat page they can type into. The Node one ends at a server with no -screen — you prove it works by making a request to it. - -**What changed since the epic decided two.** FIX-1159 settled that a plain-Node project gets no -generated server file (FSD runs there as a second process started by our own CLI) and no package -script. So everything a Node template would ship is now a `package.json`, a `tsconfig.json`, and -a demo flow with a better name than the one init writes anyway — and `fsdev init` in an empty -directory already produces that, on a path FIX-1159's own goal check runs with a real model. The -Next.js template is not in that position: the chat page and the mounted route can only come from -here, and they are what turn the ending from a stock welcome screen into something working. - -**The trade-off.** The proof runs per template *times* per advertised provider (§10), so one -template is three recorded runs and two templates are six — on machines we do not control, on -every release, forever. The epic named that as an accepted cost when the Node template still -carried a server file. One template costs backend-first developers a starter with their name on -it; they get `mkdir my-api && npx @flow-state-dev/cli init`, which is two commands instead of -one and produces the same files. - -**My recommendation: ship one.** The asymmetry is the argument. Adding `node-api` later is -additive — it breaks no invocation and strands nobody, because the two-command path works the -whole time. Removing it later is not. Two independent reviewers reached the same conclusion -before this was folded. - -**What would change my mind:** if the launch plan points backend developers at a Node starter -*by name* — in a landing page, a comparison table, an announcement. A template that exists to be -linked to is worth more than the files it writes, and that is a business fact I do not have. - -**What being wrong costs.** Wrong on shipping one: we add `node-api` in a later release and -nobody was blocked meanwhile. Wrong on shipping two: a starter we keep permanently green and -prove on every release, for a path init already proves, and a slower release loop for as long as -it lives. - -**Whose call.** This reverses epic theme 2, so it belongs to the epic's owner rather than to this -spec. Noted on epic PR #1301 as well. Either answer is cheap here: §7's `templates//` -layout exists regardless, and only whether `node-api` ships in v1 — and with it decision 2b's -flag — changes. +**The fork.** Do backend developers get a starter of their own at launch? + +Three answers, not two: **(A)** ship the Next.js chat starter only, and commit to a supported +minimal-project path for backend developers; **(B)** ship both starters; **(C)** ship the Next.js +starter only and leave backend developers with nothing named. + +**Plain terms.** A starter is the working project someone gets from our one command. The Next.js +one ends at a chat page they can type into. The Node one would end at a server with no screen — +you prove it works by making a request to it. A backend developer who gets neither has to start +by creating a web app they did not want. + +**Read this part first, because the previous version of this ask was wrong about it.** This ask +used to say a backend developer could get the same files with `mkdir my-api && npx +@flow-state-dev/cli init` — two commands instead of one — and that shipping one starter was +therefore safe because "init already proves that path". **None of that is true any more.** There +is no `init` command and there will not be one (FIX-1159 decision 1). FIX-1159 deleted its +empty-directory worked example *and the goal check that ran it* when the command went. So the +substitute the old recommendation leaned on does not exist and is not proved by anything. + +**What actually remains for a backend developer.** FIX-1159's brownfield path is a coding-assistant +skill that runs against a project that already exists, and its plain-Node branch reads a +`package.json` to identify the host. A directory holding nothing but `npm init -y` output very +likely satisfies that — but **"very likely" is the whole problem**: nothing in FIX-1159 specifies +a bare directory as a supported case, and both of its goal checks are recorded runs against real +repositories. So today, option (C) means we tell backend developers to run an agent skill on a +case nobody specified and nobody has run. + +**The trade-off.** The proof runs per starter *times* per advertised provider (§10), so one +starter is three recorded runs and two are six — on machines we do not control, on every release, +forever. That is the real cost of (B), and it is ongoing. (A) costs one specification and one goal +check **in FIX-1159, not here** — cheaper than a starter, but it is work in another issue's scope +and it needs that issue's owner to accept it. (C) costs nothing now and spends the launch's +credibility with backend developers instead: the first thing they hit is a scaffolder that only +makes web apps. + +**My recommendation: (A) — ship one starter, and get the minimal-project path specified and proved +in FIX-1159.** The asymmetry that made "ship one" right still holds: adding `node-api` later is +additive and strands nobody, while removing it later is not. What changed is that the asymmetry +only works **if the alternative path genuinely exists**, and right now it does not. So the +recommendation is the same shape as before with the missing half restored, and it is deliberately +not the bare "ship one" this section used to argue — that now means cutting the Node starter with +nothing in its place. **If FIX-1159's owner will not take the minimal-project case, fall back to +(B) and ship both.** Do not fall through to (C) by default. + +**What would change my mind:** if the launch plan points backend developers at a Node starter *by +name* — in a landing page, a comparison table, an announcement — go straight to (B). A starter that +exists to be linked to is worth more than the files it writes, and that is a business fact I do not +have. Equally, if backend developers are simply not a launch audience, (C) becomes honest and +cheap, and that is also a fact I do not have. + +**What being wrong costs.** Wrong on (A): we add `node-api` in a later release, and meanwhile +backend developers had a documented path that worked. Wrong on (B): a starter we keep permanently +green and prove on every release, and a slower release loop for as long as it lives. **Wrong on +(C) is the expensive one and it is the one that happens silently** — a backend developer's first +five minutes with FSD ends in "this is a Next.js thing", and we would not hear about it. + +**Whose call.** This reverses epic theme 2 and adds scope to FIX-1159, so it belongs to the epic's +owner rather than to this spec — it is epic **§5 Q6**, which the epic records as open and blocking +this issue's *implementation* while explicitly allowing its re-approval to proceed. Either answer +is cheap in this document: §7's `templates//` layout exists regardless, and only whether +`node-api` ships in v1 — and with it decision 2b's flag — changes here. --- @@ -287,24 +430,29 @@ developer gets whatever Next considers correct on the day they run it. The price dependency on someone else's flag surface, and §9 says how that fails. **Alternative: keep the previous draft's split** — init generates the config and the mount, this -package supplies only the demo content. Rejected by decision 3, but it deserves naming because -it is what the approved sibling spec still describes. The deciding argument is not duplication; -it is that the epic's replacement tripwire needs a template that can be *read*, and a runtime -assembly cannot be. - -**Where the complexity is:** not in any file this package writes — five of the six are static. -It is in the **three-way handoff**: `create-next-app`'s flags (which drift, and which resolve -from saved preferences when unpassed), the manifest edit that has to land between the scaffolder -and the install, and the seam to init, which must be handed a directory whose shape is fully -declared so init writes nothing this template already wrote. +package supplies only the demo content. Rejected by decision 3 on its own merits (the epic's +replacement tripwire needs a template that can be *read*, and a runtime assembly cannot be) — but +it is worth being clear that **this alternative is now unavailable rather than merely rejected**. +FIX-1159 ships no init command and no library behind one, so there is no second writer to split +with. An earlier version of this paragraph said the split "is what the approved sibling spec still +describes"; that sibling spec has since been re-specced and describes the opposite. + +**Where the complexity is:** not in any file this package writes — four of the six are static. +It is in the **ordering**: `create-next-app`'s flags (which drift, and which resolve from saved +preferences when unpassed), three edits to files it wrote that have to land between the scaffolder +and the install, a credential that must not be written before git will ignore it, and two blocks +of text authored by other issues that have to be embedded byte-for-byte and rendered for the +package manager in use. ### 4. Focus practices (1–5) -1. **Tenet 3 (earn every addition)** — the file list is the spec. Six template files, one of - which carries a substituted model string. A seventh file is a design review. +1. **Tenet 3 (earn every addition)** — the file list is the spec. Six template files, **two** of + which vary by the provider chosen: the config (the static import and the factory) and the demo + flow (the model string). A seventh file is a design review. 2. **Tenet 2 (composition over features)** — the test for a new code path here is: *is this a - fact about a repository we did not create?* If yes it belongs in the skill, and if it is a - fact about credentials, install, or the printed block it belongs in init. + fact about a repository we did not create?* If yes it belongs in the skill. Credentials, the + install and the printed block are **not** that test any more: they are this package's, and the + only thing that stays elsewhere is who *authors* the two blocks of text. 3. **Tenet 7 (prove the goal, not the mock)** — the goal check runs the published invocation in an empty directory with **no provider key in the environment**, and ends at a streamed response rendered in the browser **through the mounted route** — not through `fsdev run`, @@ -314,8 +462,11 @@ declared so init writes nothing this template already wrote. it, and the ignore guarantee by `git check-ignore`. A plausible-looking transcript has hidden a broken command three times across this epic. 5. **BP-035 (second-path checklist)** — the second path is **failure after a partial scaffold**. - `create-next-app` failing, or init failing after it succeeded, both leave a real directory on - someone's disk; §9 says what each prints, and neither rolls back. + `create-next-app` failing, or the install failing after the template landed, both leave a real + directory on someone's disk; §9 says what each prints, and neither rolls back. The second path + for decision 8 is the **absent** control: a check that only exercises `localhost` passes + identically whether the bind flag is there or was never implemented, so §10 asserts the + refusals, not the happy case. ### 5. What using it looks like (1–5 examples) @@ -329,12 +480,12 @@ $ npm create flow-state my-app Creating my-app with create-next-app … Writing the chat template … - Running fsdev init … + Finishing up … Created fsdev.config.ts lib/flowstate.ts src/flows/chat/flow.ts app/api/flows/route.ts app/api/flows/[...path]/route.ts - Updated package.json ("type": "module") + Updated package.json ("type": "module"; dev and start bound to 127.0.0.1) tsconfig.json (allowImportingTsExtensions) app/page.tsx (replaced — the stock Next.js page) Wrote .env.local (OPENAI_API_KEY, already ignored by git) @@ -346,36 +497,48 @@ $ npm create flow-state my-app 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"}' + npm exec -- fsdev run chat send --input '{"message":"hi"}' Storage is on-disk for development. Pick a real store before you deploy. The app and the DevTool are two processes over one development store — drive one at a time. + This app serves on 127.0.0.1 only, and will not serve in production + until you configure authentication. AGENTS.md tells your coding assistant how to write FSD flows. ``` -**Who prints what.** The `Created` and `Updated` blocks are **this package's**, along with the -three lines above them. The split is by **what the run did to the developer's directory**, not by -which of our steps did it: `Created` is a path that did not exist, `Updated` is any change to a -file `create-next-app` wrote — two added keys and one wholesale replacement. `app/page.tsx` sits -in `Updated` for that reason. It is a template file, but reporting it as *created* would -misdescribe the one change most likely to surprise someone who had glanced at the stock page, -and a summary listing only new paths would omit all three of the run's edits. Everything from `Wrote` down is **init's output, printed by init** (epic theme 5) — that is -where the byte-identical-to-a-standalone-run guarantee applies, and the next-steps block is the -part theme 5 actually binds. - -*This corrects an earlier draft that put `Created` on init's side of the line.* It could not -hold: §7's step-4 table hands init broad declarations that config, flows and wiring exist and -**never a file list**, so init cannot name six files it did not author and was not told about. -The two ways out were widening the seam — giving back the narrowness decision 3 bought — or -printing a summary nobody can know is correct. Neither is needed, because the wrapper wrote those -files and knows exactly what they are. It also matters more than a formatting nit: the epic's -goal check for this issue **compares the run's report against the actual diff**, so a summary -that cannot name what was written is a check that cannot pass. - -Two details in the block are load-bearing rather than cosmetic: `npm exec` needs the `--` separator or npm consumes `--input` as its own configuration -and the command fails, and the two-process caveat is real because both printed servers open the -same development store. §10 asserts the first by running it. +**Every line of this is printed by this package** — there is no second command in the run and +nothing is handed back to be printed by someone else. What is *authored* elsewhere is the text +below `Next steps`: that is FIX-1159's canonical next-steps block, embedded verbatim in this +package's source and rendered here for npm and the `mounted-route` topology (§7). + +**The `Created` / `Updated` split is by what the run did to the developer's directory**, not by +which step did it: `Created` is a path that did not exist, `Updated` is any change to a file +`create-next-app` wrote. There are **five** such changes across three files — two added keys +(`"type": "module"`, `allowImportingTsExtensions`), two rewritten `scripts` values, and one +wholesale replacement. `app/page.tsx` sits in `Updated` for that reason: it is a template file, +but reporting it as *created* would misdescribe the one change most likely to surprise someone who +had glanced at the stock page. + +*The two counts in this document are different questions and both are right.* §7 step 3 says +**four** changes *in addition to* the six template files, because `app/page.tsx` is already one of +the six. This section says **five**, because it counts every change to a file the developer did not +watch us create — which is what the report is for. + +**The `scripts` line is not cosmetic and must not be softened.** `Updated package.json` reading +`dependency keys only` — which an earlier draft had — would be a false report the moment decision +8 lands, and the epic's goal check for this issue **compares the run's report against the actual +diff**. A transcript is a promise that check reads. + +Three details in the block are load-bearing rather than cosmetic: + +- **`npm exec` needs the `--` separator** or npm consumes `--input` as its own configuration and + the command fails. §10 asserts it by running it. +- **`--input` carries no `userId`.** `fsdev run` takes the caller identity as its own parameter + (hard-coded `cli-user` in `packages/cli/src/commands/run.ts`) and never from `--input`. An + earlier version of this transcript printed `{"userId":"u1","message":"hi"}`, where the `userId` + key set nothing and taught a first-hour reader a wrong mental model. +- **The two-process caveat is real** — both printed servers open the same development file store. **Non-interactively**, which is how the goal check and CI run it: @@ -394,7 +557,7 @@ $ npm create flow-state my-app ### 7. Technical design -A new published package, `create-flow-state`, whose entry point is a four-step pipeline. It has +A new published package, `create-flow-state`, whose entry point is a five-step pipeline. It has no runtime dependency on this monorepo beyond the published `@flow-state-dev/cli` it imports, and nothing it writes into the generated project imports anything of ours that is not on npm (epic theme 4). @@ -407,10 +570,10 @@ by itself set the published name. ```mermaid flowchart TB - A[resolve invocation
name · provider · key · package manager] --> B[create the bare app
create-next-app, install skipped, every flag explicit] - B --> C[write the template
6 files · + the module-type key in the manifest] - C --> D[call fsdev init as a library
shape fully declared · answers passed in] - D --> E[init: key · ignore entry · AGENTS.md section
install · next-steps block] + A[resolve invocation
name · provider · key · package manager
Node ≥ 22.18] --> B[create the bare app
create-next-app, install skipped, every flag explicit] + B --> C[write the template
6 files · + 4 changes to files create-next-app wrote] + C --> D[credential stop
git check-ignore .env.local, then write the key] + D --> E[install · append AGENTS.md · print next steps
both blocks embedded verbatim] ``` **Step 1 — resolve the invocation.** Flags first, prompts for whatever is missing, `-y` to take @@ -441,20 +604,38 @@ starter that breaks without warning. §9's drift row is the same failure either decides whose terminal it happens in. **Step 3 — write the template.** Six files, materialized from `templates/nextjs-chat/`, plus -**two keys in files `create-next-app` wrote** — `"type": "module"` in the manifest and -`allowImportingTsExtensions` in `tsconfig.json`. Both are decision 4's, and the second is what -makes the config loadable by the CLI at all. This is the entire product surface: +**four further changes to files `create-next-app` wrote** — "further" because one of the six, +`app/page.tsx`, is itself a replacement of a file it wrote (§5 counts five for that reason): + +| change | file | whose rule | +|---|---|---| +| `"type": "module"` added | `package.json` | decision 4 | +| `scripts.dev` → `next dev --hostname 127.0.0.1` | `package.json` | decision 8 · epic theme 6 exception (c) | +| `scripts.start` → `next start --hostname 127.0.0.1` | `package.json` | decision 8 · epic theme 6 exception (c) | +| `allowImportingTsExtensions: true` added | `tsconfig.json` | decision 4 | + +Dependencies and the lockfile remain entirely the package manager's; nothing else in either file +is touched. This is the entire product surface: | file | what it is | |---|---| -| `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 | +| `fsdev.config.ts` | default-exports `createFlowState({ flows, modelResolver, stores })`. 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 | | `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 | +| `src/flows/chat/flow.ts` | the demo flow — one action, one streaming generator, naming **the concrete `provider/model` string** for the provider chosen (decision 5's table), never an intent. Declares the production refusal on itself (decision 8), so a request outside development is refused before any model invocation. Imports `z` from `zod` for its input schema — a direct dependency, per the contract's dependency rule. `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, no Vercel assumption. **Carries the canonical route exports beside it: `runtime = "nodejs"` and `dynamic = "force-dynamic"`.** Not decoration — `packages/next/README.md` ships exactly those three lines, and `examples/hello-chat` documents why: without `force-dynamic` Next may buffer the response body, and a buffered body turns token-by-token streaming into one delivery at the end. That is the epic's headline outcome failing while every wiring check passes | | `app/api/flows/route.ts` | the sibling bare route. `list_flows` is registered as `GET /` on the mount base and the client's `listFlows()` requests it, but a required catch-all cannot match zero segments. `@flow-state-dev/next` exports no bare handler (only `@flow-state-dev/vercel` does), so this one forwards by hand with a comment saying why — carrying the same route exports as its sibling | | `app/page.tsx` | the chat page. `FlowProvider` + `useFlow` + `useSession` + `ItemsRenderer` from `@flow-state-dev/react`, no other imports (decision 6). Overwrites `create-next-app`'s stock page — permitted, because this is a directory this command created seconds ago | -| *manifest* | `"type": "module"` added — decision 4. Nothing else; dependencies and the lockfile are the package manager's | -| *tsconfig* | `allowImportingTsExtensions: true` added — decision 4. Required, not stylistic: the config imports the demo flow, native Node will not infer the extension, and the `.ts` specifier that satisfies Node is a `TS5097` error without this key. Nothing else in the file is touched | +| *manifest* | the three changes tabled above — decisions 4 and 8 | +| *tsconfig* | `allowImportingTsExtensions: true` added — decision 4. Required, not stylistic: the config imports the demo flow, native Node will not infer the extension, and the `.ts` specifier that satisfies Node is a `TS5097` error without this key | + +**The dependency set is a rule, not a list** (the wiring contract): *every package the generated +files import directly is a direct dependency of the generated manifest.* Under the shape above +that reaches `@flow-state-dev/core`, `@flow-state-dev/next`, `@flow-state-dev/react`, +`@flow-state-dev/cli`, **`zod`** (the flow's input schema imports `z` directly, and +`@flow-state-dev/core` carrying `zod` in its own dependencies does nothing for a consumer under +pnpm's strict isolation), and **the AI SDK package for the provider chosen** — never a fixed one. +Stated as a rule because two review rounds across this epic each found one member missing from a +list. §10 proves it by an isolated pnpm install rather than by reading the manifest. **Why the config shape is what it is — measured.** The template's config has two consumers at once: Turbopack, because the route imports it, and the CLI's native `import()`. Nobody had @@ -472,24 +653,45 @@ reason for passing every flag explicitly and refusing `--yes`. The probe passes never reproduces it. The README's two lists — what is asserted, and what is deliberately not — are exhaustive, which is what keeps the citation and the evidence one-to-one. -**Step 4 — hand off to init.** What crosses the seam, and nothing more: +**Step 4 — the credential stop.** Before `.env.local` is written, ask **git** whether it would +ignore that exact path (`git check-ignore`). In a fresh `create-next-app` scaffold the answer is +already yes (verified by the POC), so this is normally an assertion rather than a write. If it is +not, append the rule and re-verify; if it still cannot be established, **stop before the key is +written** (§9). Only then write `.env.local` with the chosen provider's variable name and the +value collected in step 1. -| passed in | why | +**Step 5 — finish the project.** Three things, in this order: + +| what | detail | |---|---| -| the target directory | init otherwise runs against the cwd, which is the parent | -| the declared host (`next`) | selects the Next shape of the next-steps block. **Not** a request to write the mount — decision 3 already wrote it | -| the declaration that config, flows and wiring are present | init must author none of them, and must not treat a non-empty directory as undeclared (FIX-1159 decision 2 turns on *declared*, not *empty*) | -| provider and key | collected in step 1; a second prompt for the same key is the thing this seam exists to prevent | -| 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) | - -**Not** crossing the seam: the list of template files. This package prints its own `Created` -summary (§5) because it is the only side that knows what it wrote — init receives declarations, -not filenames. Keeping it out is what holds the seam at the width decision 3 chose, and it is -what lets the run's report be compared against the actual diff (§10). - -**Ordering, and why it is not incidental.** The template is written *before* init runs, so init -sees a fully declared shape and authors nothing that competes. `create-next-app` must skip its +| **install** | run the resolved package manager's install in the target directory. One manager, one lockfile. The manifest's `"type": "module"` must already be in place, because the package manager rewrites that file | +| **append the agent-instructions section to `AGENTS.md`** | `create-next-app` writes its own `AGENTS.md` (and a `CLAUDE.md`), so this **appends** — it never creates, and never touches Next's own delimited block. The section's text is **FIX-1160's canonical block, embedded verbatim** in this package's source | +| **print the next-steps block** | **FIX-1159's canonical block, embedded verbatim**, rendered for the resolved package manager and the `mounted-route` topology | + +**Both blocks are embedded verbatim, every branch included — including the one this package can +never render.** They are epic theme 9 *source blocks*: one canonical text, embedded in each +shipper's own source, checked by normalized text equality. FIX-1159's next-steps block carries two +conditional sections keyed on host topology; this scaffolder ships greenfield Next.js and renders +only `mounted-route`, **but the `second-process` branch must still sit in its source byte-identical +to canonical**, because that is what the comparison reads. Trimming an unreachable branch breaks +the check and looks exactly like tidying, which is why it is stated here rather than left to the +authors' specs — it binds the shipper. + +**This package invokes the authors' comparisons; it does not write its own.** FIX-1159 and +FIX-1160 each export the normalization and equality comparison for the block they author, and +**this package's own test suite calls each against its own embedded copy** (epic theme 9 (a)). +That split exists because the authors land *before* this issue: an author-side check over this +package's copy could not tell *not yet* from *never*. Assert **equality over the whole block**, not +presence and not a substring — a presence check passes on exactly the shipper-side damage the rule +exists to prevent. No digest, no marker, no hashing: the stored-value mechanisms are deleted. + +**No new package and no new dependency between packages comes with any of this.** The comparisons +are test-time imports inside this monorepo, where every shipper already lives. + +**Ordering, and why it is not incidental.** The template is written *before* the install, so the +manifest is complete when the package manager reads it. The credential stop runs *before* the key +is written and *after* the scaffold exists, because git cannot answer about a directory that does +not exist yet. `create-next-app` must skip its install, or the project installs twice and the second run rewrites the lockfile the first wrote. And the manifest's `"type": "module"` must land before the install, because the package manager rewrites that file. @@ -506,27 +708,36 @@ package generates a project; it changes no framework behaviour. 2. **The bare-app step** — spawn `create-next-app` with every flag explicit and install skipped; surface its failure. *Test:* the argv built (complete enough that no option resolves from saved preferences; install skipped), and the failure path's output. *Depends on:* 1. -3. **The template** — the six files **and both edits to files `create-next-app` wrote**: - `"type": "module"` in `package.json` and `allowImportingTsExtensions` in `tsconfig.json`. - Neither is optional and the second is not cosmetic — without it the config's `.ts` import of - the demo flow is a `TS5097` build error, and with an extensionless import instead the CLI - cannot load the config at all (decision 4). +3. **The template** — the six files **and all four changes to files `create-next-app` wrote**: + `"type": "module"` and the two loopback-narrowed `scripts` values in `package.json`, and + `allowImportingTsExtensions` in `tsconfig.json`. None is optional. Without the tsconfig key the + config's `.ts` import of the demo flow is a `TS5097` build error, and with an extensionless + import instead the CLI cannot load the config at all (decision 4); without the script edits the + generated app serves an unauthenticated model-backed route on every interface (decision 8). + The config carries the static provider import and the pre-built `modelResolver`, and the flow + names the concrete model string and declares the production refusal (decisions 5 and 8). *Test:* the generated project builds and its mounted route serves; **the config loads under a native `import()` with the demo flow imported through it**, not as a self-contained module, - with no warning; `.env.local` is ignored by git before the key is written. + with no warning; both `scripts` values carry `--hostname 127.0.0.1`. *Depends on:* nothing. -4. **The init handoff** — call init with the declared shape and collected answers, print what it - returns. *Test:* the call ordering (template before init), the arguments crossing the seam, - that init authored no config or flow of its own, and that the printed block matches a - standalone init run. *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. +4. **The credential stop** — `git check-ignore` against `.env.local`, the append-and-re-verify + path, the stop, then the key write. *Test:* the ordering (the check precedes the write, + executed rather than read), and the stop leaving a usable scaffold with no key in it. + *Depends on:* 2. +5. **Finishing the project** — the install, the `AGENTS.md` append, and the printed next-steps + block, with both canonical blocks embedded verbatim and asserted by the authors' exported + comparisons. *Test:* normalized equality over each whole block including unrendered branches; + the append leaves Next's own `AGENTS.md` block and `CLAUDE.md` intact; every printed command + runs. *Depends on:* 1, 2, 3, 4, **and FIX-1159's next-steps block and FIX-1160's + agent-instructions block existing** — see §12. +6. **Publish configuration and the README that renders on npm.** *Depends on:* 1. **PR plan.** Two sub-PRs. | sub-PR | deliverables | depends_on | |---|---|---| -| a | the package: invocation surface, bare-app step, the template, init handoff (steps 1–4) | — | -| b | publish configuration, package README, and the three doc surfaces in §11 (step 5) | a | +| a | the package: invocation surface, bare-app step, the template, the credential stop, and finishing the project (steps 1–5) | — | +| b | publish configuration, package README, and the three doc surfaces in §11 (step 6) | a | ### 9. Edge cases & error handling @@ -536,7 +747,7 @@ package generates a project; it changes no framework behaviour. |---|---| | 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 in step 1, before anything is created, with the same floor and the same message init uses. The floor is **22.18** — native type stripping, without which every printed `fsdev` command fails to load `fsdev.config.ts` (decision 4). Do **not** narrow the package's `engines` below the repo-wide `>=22` — that is the scaffolder's own runtime, a different question; FIX-1159 §9 records why. | +| Node runtime below the floor the generated project needs | Refuse in step 1, before anything is created. The floor is **22.18** and the message names 22.18 — native type stripping, without which every printed `fsdev` command fails to load `fsdev.config.ts` (decision 4). **22.0–22.17 is the interval that matters**: it passes a `>=22` check and then fails every printed command, which is the same failure as Node 20.9–21 one interval higher, not a different one. The wiring contract fixes the number and the guidance for both entry paths (epic theme 9 (b)). Do **not** narrow the package's `engines` below the repo-wide `>=22` — that is the scaffolder's own runtime, a different question; FIX-1159 §9 records why. | **The credential stop — after the scaffold exists, before the key is written.** Its own category, because it is neither of the other two and putting it in either produced a @@ -555,9 +766,9 @@ no-rollback rule directly below. *Why the `create-next-app` row promises a restart and not a repair.* The previous wording told the developer two commands would finish a partly-populated directory. Nothing in this spec makes that true: step 1 **refuses a non-empty target**, so re-running the command on it is rejected; -init does not author the six template files, so it cannot complete the shape; and applying the -template to a directory somebody else's tool partly filled is the brownfield case, which is an -explicit non-goal. A resume mode would need all three of those to change, and it would be a +no other command of ours authors the six template files, so nothing else can complete the shape; +and applying the template to a directory somebody else's tool partly filled is the brownfield +case, which is an explicit non-goal. A resume mode would need all three of those to change, and it would be a deterministic writer merging into a directory of unknown state — the exact shape the epic removed from this set. So the honest instruction is restart, and it is cheap here in a way it is not elsewhere: the directory is seconds old and contains nothing the developer authored. @@ -567,19 +778,21 @@ elsewhere: the directory is seconds old and contains nothing the developer autho | `create-next-app` fails, is unreachable, or rejects a flag | Report its output and **name the target as partially populated and not resumable**. Do not delete it — it is the developer's directory and it may hold their evidence. Print inspect-and-restart instructions: review what is there, then remove it (or pick a new name) and re-run the command. **Do not print "two commands that finish the job by hand"** — see below. | | `create-next-app` changes its flag surface or generated layout | The **exact** pinned version (§7 step 2) means an upstream change cannot reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. A major-range pin would not hold that. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | | The pinned `create-next-app` falls behind | New projects start on an older Next than current. Bumping the pin is scheduled maintenance gated on a goal-check run, not a reaction to breakage. | -| Init fails after the template was written | The scaffold stays. Print init's own retry command against that directory. Mirrors init's install-failure taxonomy, which also leaves files and prints the retry. | -| Install fails inside init | Init's case, not this one. It reports and this command adds nothing. | -| `-y` with no key in flags or environment | Scaffold completes. `.env.local` carries the empty key line init writes, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. | -| 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 owns the block). | +| The install fails after the template was written | The scaffold stays and is **finishable**: every file and every edit is already on disk, so the developer's own package-manager install completes it. Report the manager's own output and print that command against that directory. | +| The `AGENTS.md` append fails (unwritable, or the file vanished) | The scaffold stays and is usable — this is the one job whose absence costs the developer nothing that stops the app running. Report it and print the next-steps block anyway, naming the section as not added. | +| `-y` with no key in flags or 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. | +| 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. | **Taxonomy — three categories, and the middle one exists because the first two could not hold it.** Refusals happen before anything is created and leave the disk untouched. The credential stop happens after the scaffold exists and leaves it there, minus the key. Failures leave a directory the developer can **inspect** — and only some of them leave one that can be *finished*. -**An init failure can**: the six template files and all three edits are already on disk, so -init's own retry command against that directory completes it. **A failed `create-next-app` +**A failed install can**: the six template files and all four edits are already on disk, so the +developer's own install command against that directory completes it. **A failed `create-next-app` cannot**: the target is partly populated by a tool we do not control, step 1 refuses a non-empty -target, init does not author the template, and brownfield is a non-goal — so there the +target, nothing else of ours authors the template, and brownfield is a non-goal — so there the instruction is inspect and restart (§9). Promising "finish by hand" across both is the contradiction this taxonomy used to carry. Nothing is ever cleaned up behind the user, because deleting a directory a stranger may have put something in is worse than leaving @@ -588,7 +801,8 @@ qualify as a refusal. ### 10. Testing strategy -**Goal & goal check** (the epic's proof for this issue). Recorded runs under +**Goal & goal check** (the epic's proof for this issue — and this issue is the implementer of +every part of it, including the five jobs an earlier draft had disclaimed). Recorded runs under `goals/create-flow-state/` — **three for the one template**, one per advertised provider, and three more per additional template if decision 2 is overturned. That count is the real cost the ask above is pricing: it is per template *times* per provider, not per template: @@ -599,20 +813,45 @@ ask above is pricing: it is per template *times* per provider, not per template: incrementally**, token by token, not as one block when the response completes. The second half is the only check anywhere that would catch a missing `force-dynamic`; everything else passes with a buffered body. -- **Through the mounted route, not through `fsdev run`.** The provider SDK is imported - dynamically by package name inside the Next.js server bundle, where `createModelResolver` - carries an explicit fallback for it failing to resolve (§12). A CLI-only check passes with - that path broken. +- **Through the mounted route, not through `fsdev run`.** The CLI runs in-process and resolves + providers through a path that works there, so a CLI-only check passes with the product's actual + path broken. Decision 5's static wiring is what *prevents* that failure; this check is what + *detects* it, and the two are separate obligations (§12). - **Run once per advertised provider, single key only** — an OpenAI-key run, an Anthropic-key - run, a Google-key run, each with the other two absent. Decision 5 is the reason: a prompt - offering three providers where only one works is a first-hour failure, and one run with the - most-likely key would not find it. + run, a Google-key run, each with the other two absent. Decision 5 is the reason, and it is a + stronger reason than it was: the template emits a **different config per provider** — different + import, different factory, different model string — so these are three different files, not one + file's fallback ladder. A single run with the most-likely key would leave two emitted shapes + entirely unexercised, including two model strings nothing in the system validates. +- **The same run asserts what the scaffold did *not* destroy** — `create-next-app`'s own + `AGENTS.md` block and its `CLAUDE.md` survive intact, captured whole beforehand and compared + byte-for-byte. **Must not be dropped:** a streaming chat page proves nothing about what the + scaffolder overwrote on the way there, and greenfield is the one path where we author both + sides, so it is where the epic's additive guarantee is exercised end to end. +- **And the run's report is compared against the actual diff**, including all five changes to + files `create-next-app` wrote. +- **A pnpm-isolated install of the emitted template.** After the scaffold, install the generated + app's own `package.json` with **pnpm** and run the generated flow from that install. This is the + only thing that can fail the dependency rule: npm's flat `node_modules` hoists transitives and + resolves an import the manifest never declared, so an npm-only proof passes on an incomplete + manifest. **A static import-versus-manifest scan does not substitute** — the provider SDK is + never statically imported by *our* code, it is named in the manifest and reached at run time, and + it is one of exactly two members of the rule that a review round already missed once. The + headline command stays `npm create flow-state my-app`; that is the advertised UX and is not the + thing under test. +- **Two negative assertions, because every control here is otherwise proved only by its happy + case.** A check that exercises only `localhost` passes identically whether the bind flag is + present or was never implemented at all. + - **A request from a non-loopback address fails to connect** against the running `npm run dev`. + - **With the app built and started in production mode on the default resolver, a request to the + mounted route is refused before any model invocation**, returning an error that names the + missing authentication rather than a stream. A 200 carrying an error body is not a refusal. - The key is deliberately *not* pre-exported. PR #1301's review note 8 called that out: pre-supplying it skips the credential path, so the check passes while a real user's first command fails. **CI specs** (behaviours, not test names) — all against a stubbed `create-next-app` and a stubbed -init, in a temporary directory, with no network and no install, **except the three marked +package-manager install, in a temporary directory, with no network, **except the three marked *real*, which build a scaffolded project once**: - one behaviour per decision in §6 @@ -634,33 +873,52 @@ init, in a temporary directory, with no network and no install, **except the thr ignore entry cannot be established, and assert the directory is intact, `.env.local` holds no key, and the output names the missing line. This is the §9 case that is neither a refusal nor a failure, so nothing else in this list covers it -- **the template is written before init is called** — asserted on call ordering, not end state, - since a package that wrote afterwards and deleted init's files would leave an identical - directory -- **init authored no config and no flow** — asserted on what crossed the seam, because the - symptom otherwise is a second flow file appearing beside the advertised one -- **the collected provider and key reach init** — asserted on the call, so a regression shows up - as a failing test rather than a second prompt in someone's terminal +- **the template is written before the install runs** — asserted on call ordering, not end state, + since a package that installed first and re-wrote afterwards would leave an identical directory + and a lockfile built from an incomplete manifest - **`create-next-app` is invoked with install skipped, every flag explicit, and an *exact* pinned version in the specifier** — asserted on the argv, and the assertion rejects a range as well as a missing pin, since `@16` silently re-resolves. The symptoms otherwise are "the first hour is slower", "it behaved differently on my machine", and a version nobody tested -- **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5) +- **each embedded block equals canonical**, asserted by **invoking the author's exported + comparison** — FIX-1159's over the next-steps block, FIX-1160's over the agent-instructions + block — against this package's own embedded copy. Normalized **equality over the whole block**, + never presence and never a substring +- **every conditional branch is present, including `second-process`, which this package never + renders** — this is what the equality assertion above is *for*, and it is called out separately + because trimming an unreachable branch reads as tidying rather than as damage +- **the rendered next-steps block substitutes the resolved package manager** — the block genuinely + differs between an npm and a pnpm run, so a test asserting two rendered outputs are identical is + wrong; what must not vary is the canonical text behind them +- **the `AGENTS.md` append is additive** — `create-next-app`'s own delimited block and its + `CLAUDE.md` are captured whole beforehand and compared byte-for-byte afterwards, with an + occurrence count kept because equality cannot see a duplicate. The greenfield Next path + **appends to an existing `AGENTS.md` and never creates one** - **the `Created` summary names exactly the template files this package materialised** — compare in both directions, so a template file written but not reported fails as loudly as one reported but not written. **The baseline is what makes this checkable**: snapshot the directory after `create-next-app` returns and before step 3, and compare against the snapshot taken after step - 3 but before init is called. That window contains exactly this package's writes. Everything - outside it is somebody else's and is not in this list — `create-next-app`'s own scaffold before - it, and init's `.env.local`, `AGENTS.md` append, dependencies and lockfile after it. -- **the run reports every change it makes to a file it did not create** — all **three**: the two - decision-4 keys in `package.json` and `tsconfig.json`, and the wholesale replacement of - `app/page.tsx`. None is a new path, so a filename-only summary misses every one of them, and - they are precisely the changes a reader would be surprised by. Assert the category too, not - just the presence of the name: a run that reports `app/page.tsx` as *created* has misdescribed - what it did to a file the developer may have already opened. The epic's proof compares the - run's report against the actual diff; a report that omits or miscategorises its own edits fails - that comparison for a real reason + 3 but before step 4. That window contains exactly this package's template writes. Everything + outside it is not in this list — `create-next-app`'s own scaffold before it, and `.env.local`, + the `AGENTS.md` append, the dependencies and the lockfile after it +- **the run reports every change it makes to a file it did not create** — all **five**: the two + decision-4 keys in `package.json` and `tsconfig.json`, **the two rewritten `scripts` values**, + and the wholesale replacement of `app/page.tsx`. None is a new path, so a filename-only summary + misses every one of them, and they are precisely the changes a reader would be surprised by. + Assert the category too, not just the presence of the name: a run that reports `app/page.tsx` as + *created* has misdescribed what it did to a file the developer may have already opened, and a + run that reports `package.json` as "dependency keys only" has misdescribed a security-relevant + edit. The epic's proof compares the run's report against the actual diff +- **both `scripts.dev` and `scripts.start` carry `--hostname 127.0.0.1` in the generated + manifest** — asserted on the emitted file. Cheap, and it is the only CI-visible evidence of + decision 8's first half; the goal check's non-loopback assertion is the behavioural one +- **the generated config passes a pre-built `modelResolver` built from a *static* import, and + declares no `intents` and no `models` shorthand** — asserted on the emitted config's source for + each of the three providers, against decision 5's table. A stub cannot reach the bundler, so + this is the assertion that keeps the wiring from regressing between goal-check runs +- **the emitted model string matches the contract's table for the provider chosen** — asserted per + provider, because nothing between the config and the provider's API validates a model id, so an + invented one survives construction, install and every check that does not call a provider - **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the message naming the floor, and an untouched target directory. Without it the failure moves to every printed `fsdev` command, after a project exists (decision 4) @@ -674,8 +932,8 @@ real network, real `create-next-app`, real model, real browser — and are never suite. The three *real* CI specs scaffold once and are the slowest thing in the suite; they earn it, because everything else in the list would pass against a template that does not compile. -**Discipline:** `tdd`. The seam is the pipeline against a temporary directory with both -subprocesses stubbed. +**Discipline:** `tdd`. The seam is the pipeline against a temporary directory with +`create-next-app` and the package-manager install stubbed. ### 11. Documentation plan @@ -701,37 +959,66 @@ subprocesses stubbed. **Dependencies.** -- **FIX-1159 blocks implementation, and now constrains part of this specification.** This package - cannot be built until init's library seam exists, and cannot merge before init merges. §7's - step-4 table is the required interface; it is **smaller than the previous draft's**, because - decision 3 moved the config and the mount here. - - **The edge is firmer than this spec previously recorded it.** It used to be the library seam - plus the shared next-steps block — both about what crosses the seam at runtime and what gets - printed, neither about this template's own files. Epic theme 9 adds the **wiring contract**, - which does constrain them. Specification can still proceed in parallel, but not as far as - before: the shapes below are conformance targets, not local calls. -- **This template conforms to FIX-1159's wiring contract (epic theme 9).** The contract is the - part both entry paths share, and it covers exactly three things: **the Next.js mount pair** - (`app/api/flows/route.ts` + `app/api/flows/[...path]/route.ts`), **`fsdev.config.ts`'s shape** - including its required store profile, and **the dependency set**. This package writes them; - FIX-1159 specifies them. Everything else in §7 — the demo flow, the chat page, the - agent-instructions section, the manifest edit — is this issue's own and is outside the - contract. Recorded so an implementer conforms rather than inventing the mount shape a second - time; the check is theme 8's parity requirement, that this template and the brownfield Next - path deliver the same mounted-route shape. **No new artifact, package or dependency comes with - this**: the contract travels as skill content on the path skill content already takes - (FIX-1159 authors → FIX-1160 packages → the plugin ships). -- **Publishing the unscoped `create-flow-state` is a hard prerequisite** (decision 1). Not a - naming preference: without it the headline command resolves to nothing, and there is no - in-scope workaround, because a scoped publish cannot serve `npm create flow-state`. What is - and is not established, stated separately because the difference matters: - - **Verified today against the registry:** `create-flow-state` returns 404, as do - `flow-state-app`, `flow-state`, `fsdev`, and every `@flow-state-dev/*` package. 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, and nothing is published — so "the owner holds it" cannot yet be - confirmed from outside. The epic coordinator has the ownership question with the owner. +**This issue lands last of the four. Both edges into it are real, and one of them was missing +from this document entirely.** + +- **FIX-1159 blocks implementation.** Two things come from it and **neither is a library seam** — + that seam is deleted (FIX-1159 decision 1), which is why decision 3 takes the five jobs it used + to carry: + - **the next-steps block** — canonical text, its declared value substitutions and conditional + sections, and the exported comparison. It is FIX-1159's sub-PR b, which has no dependencies of + its own and can land first. + - **the wiring contract**, authored alongside the skill in FIX-1159's sub-PR c. + + *This spec previously recorded the edge as "cannot be built until init's library seam exists, + and cannot merge before init merges", and pointed at a step-4 handoff table as the required + interface. Both are gone. The edge is not weaker for it — it is the same ordering for two + different reasons.* +- **FIX-1160 blocks implementation, and this spec carried no such dependency at all.** FIX-1160 + authors the **agent-instructions block** this template appends to `AGENTS.md`, and exports the + comparison this package's suite invokes against its embedded copy. **Both sibling documents + already state this edge from their own side** — epic theme 9 (c) (*"FIX-1160 authors the + agent-instructions content the template ships, so FIX-1160 lands before FIX-548; without that + edge a template landing first ships a draft that drifts"*) and FIX-1160 §7 (*"FIX-548 lands + last, after this issue, so it embeds the canonical text directly and never needs a + placeholder"*). **An edge asserted in two documents and enforced by neither does not exist**: + built from this spec as it stood, this package would have embedded nothing, depended on nothing, + and merged before its content had an author. Now recorded here and wired in Linear. + + *The dependency direction across the set is `FIX-1159 → FIX-1160 → FIX-548`, and this issue is + the terminal node. That is why it embeds both canonical texts directly rather than carrying a + placeholder: only an artifact flowing against the ordering needs one.* +- **This template conforms to FIX-1159's wiring contract (epic theme 9 (b)).** The contract is + the part both entry paths share, and it covers **five** things: + 1. **the Next.js mount pair** — `app/api/flows/route.ts` + `app/api/flows/[...path]/route.ts`; + 2. **`fsdev.config.ts`'s shape**, including its required store profile; + 3. **how the provider is wired, down to the model string** — statically imported, passed as a + pre-built `modelResolver`, never the `models` shorthand (decision 5); + 4. **the dependency set**, as a rule rather than a list (§7); + 5. **the runtime floor**, which is `22.18` and not `22` (§9). + + *This spec previously said the contract covered "exactly three things" and omitted items 3 and + 5. The omission was not cosmetic: item 3 is the one decision 5 then specified the opposite of.* + This package writes all five; FIX-1159 specifies them. Everything else in §7 — the demo flow, + the chat page, the module-type key — is this issue's own and outside the contract. The check is + behavioural, because the shippers' outputs genuinely differ: theme 8's parity requirement, that + this template and the brownfield Next path deliver the same mounted-route shape. **No new + artifact, package or dependency comes with this**: the contract travels as skill content on the + path skill content already takes (FIX-1159 authors → FIX-1160 packages → the plugin ships), and + the block comparisons are test-time imports inside this monorepo. +- **The unscoped `create-flow-state` is a hard prerequisite (decision 1), and it is now + satisfied.** Without it the headline command resolves to nothing, and there is no in-scope + workaround, because a scoped publish cannot serve `npm create flow-state`. + - **Verified against the registry, and this supersedes what this spec said before:** + `create-flow-state` **exists and is ours** — version `0.0.0`, sole maintainer `jnhoffner`, + created 2026-08-18. The name is claimed. *This document previously recorded the package as + returning 404 and the ownership as "asserted, not verified", with the question open with the + owner. Both were true when written and neither is true now; a premise that moved under a spec + is exactly what a re-read is for.* + - **What that changes:** the prerequisite is discharged rather than pending, so the "deliberately + not designed around" bullet below is no longer hedging a live risk. Nothing else moves — + decision 1's reasoning about why the name must be unscoped is unaffected, and the placeholder + publish is a claim on the name, not a released package. - **Verified, and it corrects a claim this spec previously repeated:** `create-fsd-app` is **not** ours. `create-fsd-app@1.1.2` exists, published 2024-10-18 by an unrelated maintainer (`keyready`), and is a React/Vite starter. FIX-1162's original finding was right; the later @@ -739,29 +1026,30 @@ subprocesses stubbed. name, and it is the reason the bullet above distinguishes verified from asserted at all — the same assumption was already wrong once. - **Deliberately not designed around.** No fallback name, no scoped alias, no conditional - branch. If the name turns out not to be obtainable, that is a different spec, and inventing - a fallback here would spread a contingency through §5, §6, §7, §9 and §11 to hedge a - question that will be answered before anything is built. + branch — and with the name now held, no reason for one. Inventing a fallback would have + spread a contingency through §5, §6, §7, §9 and §11 to hedge a question that has since been + answered by claiming the name. **Cross-issue notes — raised, not decided here.** -- **FIX-1159's Next-host branch is no longer on this path.** Its write mode authors - `fsdev.config.mts`, `flows/hello/flow.mts` and the Next route pair for a declared Next host; - decision 3 means the only Next caller writes all three itself. Whether that branch keeps - earning its place, or write mode narrows to the plain-Node shape it is actually used for, is - FIX-1159's call. Nothing here is blocked either way. -- **Decision 4 differs from FIX-1159 decision 4 on the same file.** Init writes +- **Decision 4 differs from FIX-1159's on the same filename.** The brownfield path writes `fsdev.config.mts`; this template writes `fsdev.config.ts` plus `"type": "module"`. That is not - a contradiction — init's rule covers a directory whose manifest it does not control, and this - one covers a manifest we created — but the two outputs now differ, so FIX-1159's "align the + a contradiction — the brownfield rule covers a directory whose manifest it does not control, and + this one covers a manifest we created — but the two outputs differ, so FIX-1159's "align the corpus on `.mts`" follow-up should weigh that the greenfield flagship went the other way, with - measurements. + measurements. *This note previously described the difference as against "init's rule"; there is + no init, and the rule is the brownfield skill's.* - **The next-steps block owes a two-process line.** Both commands it prints for a Next host open - the same development file store (§9). FIX-1159 owns the block's wording. + the same development file store (§9). FIX-1159 authors the block's wording; this package prints + it and cannot add to it, since the embedded copy must equal canonical. +- **The block also owes the loopback line.** §5's transcript shows one, and it has to come from + canonical for the same reason. If FIX-1159 declines it, the line moves outside the delimiters as + this package's own prose — which is worse (theme 5 exists to stop unowned per-host prose), so it + is raised rather than assumed. - **The epic's prose is stale on the name; FIX-1162's original finding was not.** The epic says `create-fsdev-app`, adopted because `create-fsd-app` was unobtainable — and that premise is **correct** (verified: held by a third party since 2024). What changed is the choice, not the - finding: decision 1 takes `create-flow-state`, which is unpublished and available. FIX-1162's + finding: decision 1 takes `create-flow-state`, which is now claimed and ours. FIX-1162's work is therefore superseded on *which* name, not corrected on its facts. - **The unscoped-vs-scoped point is narrower than this spec previously claimed.** `npm create ` needs the unscoped name — that half stands, and decision 1 rests on it. **A bare @@ -778,10 +1066,13 @@ subprocesses stubbed. too, which the epic files under brownfield. The POC confirmed an appended FSD section, and Next's own block, both survive a `next dev` run intact. -**Open questions:** one, and it is §6's decision 2 — does the Node API template ship? Raised as a -decision with a recommendation rather than left open, because leaving it open would block a spec -on a question the spec can answer either way. The answer changes whether §10 records three goal -runs or six, and whether decision 2b's flag exists. Nothing else. +**Open questions:** one, and it is §6's decision 2 — do backend developers get a starter of their +own at launch? It is epic **§5 Q6**, which the epic records as **open and blocking this issue's +implementation** while explicitly allowing its re-approval to proceed. Raised as a fork with a +recommendation rather than left blank, because the spec is written to work under any of the three +answers. The answer changes whether §10 records three goal runs or six, whether decision 2b's flag +exists, and — under the recommended answer — adds a specified minimal-project case to FIX-1159. +Nothing else. **Verified premises** (measured or read from the code, so a reviewer need not re-derive them): @@ -797,12 +1088,13 @@ runs or six, and whether decision 2b's flag exists. Nothing else. `registry.npmjs.org/create-flow-state-nonexistent-xyz123`. A scoped package cannot serve that invocation form, which is why decision 1's unscoped publish is a prerequisite rather than a preference. -- **Registry state, checked today:** `create-flow-state`, `flow-state-app`, `flow-state`, - `fsdev` and `@flow-state-dev/cli` all return 404; `create-fsd-app@1.1.2` exists and belongs to - an unrelated maintainer since 2024-10-18. -- `packages/cli` has **no `init` command today** (`src/commands/` holds `run`, `dev`, `serve`, - `chat`, `block`, `ui`, `benchmark`), so exposing init as a library is an addition to that - surface, not a change to it. +- **Registry state, re-checked at this revision:** `create-flow-state` **exists at `0.0.0`, sole + maintainer `jnhoffner`, created 2026-08-18** — the name is claimed and ours. + `flow-state-app`, `flow-state`, `fsdev` and `@flow-state-dev/cli` return 404; + `create-fsd-app@1.1.2` exists and belongs to an unrelated maintainer since 2024-10-18. +- `packages/cli` has **no `init` command** (`src/commands/` holds `run`, `dev`, `serve`, + `chat`, `block`, `ui`, `benchmark`), **and none is coming** — FIX-1159 decision 1 ships neither + the command nor a library entry point. That is what makes decision 3's five jobs this issue's. - The config loader's filename precedence is `fsdev.config.{ts,mts,js,mjs}`, searched **cwd-only**. The CLI *does* have a directory scan (`src/flows/`, `flows/`), but it is the **fallback for projects with no config** — once a config resolves, `fsdev dev` and `fsdev run` serve that @@ -811,20 +1103,48 @@ runs or six, and whether decision 2b's flag exists. Nothing else. - `fsdev serve` defaults to `$HOST ?? 0.0.0.0` and `$PORT ?? 3000` — **not 8787, as the epic's Node transcript shows** — and `assertNetworkBindIsAuthenticated` refuses a network bind for an unauthenticated flow. This template's next steps never print `fsdev serve`; the hazard is - recorded because the epic's transcript is wrong and the Node template it belongs to is what - decision 2 cuts. + recorded because the epic's transcript is wrong, and it would matter to a `node-api` template if + decision 2 lands on shipping one. - `fsdev dev` binds `127.0.0.1:4200`, so the bind guard is not in play; with a config present it serves the app's **own** `FlowState` (its stores, its flows) rather than the SQLite discovery path, which is why the two-process store note in §9 applies. +- **The framework's loopback rail does not cover this template, which is what decision 8 exists + for.** `assertNetworkBindIsAuthenticated` (`packages/node/src/bind-guard.ts`) returns early for + a loopback host and otherwise refuses a network bind for a flow whose + `authentication?.resolvePrincipal` is absent or the default body-`userId` resolver — **it is + per-flow, and it lives in `@flow-state-dev/node`.** This template mounts through + `createNextHandler` inside the developer's own Next server and never touches that adapter, so + the rail `docs/architecture/authentication.md:123-127` names as the protection for + default-resolver apps is not in the path at all. Both `next dev` and `next start` default to + `0.0.0.0` (verified by the epic against `next@16.3.1`; §10's non-loopback assertion is what + proves the narrowing on our side). +- **No adapter-independent production guard exists in the engine today** — nothing in + `packages/engine/src/routes/` keys on `NODE_ENV`. Decision 8's second half is therefore new + behaviour in the *generated project*, declared on the demo flow, not a framework change. Placing + it on the flow rather than host-level is deliberate: both the bind guard and + `docs/architecture/authentication.md` key on the **governing flow's** resolver, so a host-level + declaration would leave the two guards disagreeing silently. **Whether the framework should own + this guard instead is a real question and it is not this issue's** — raised below. - Provider detection maps exactly three providers to env vars: `anthropic`/`ANTHROPIC_API_KEY`, `openai`/`OPENAI_API_KEY`, `google`/`GOOGLE_GENERATIVE_AI_API_KEY`. -- Provider SDKs are **dynamically imported by package name** (`@ai-sdk/openai`, - `@ai-sdk/anthropic`, `@ai-sdk/google`); `@ai-sdk/openai` is only a *dev* dependency of `core`, - so none reaches a consumer. `createModelResolver` carries a `directLoadFailed` set for the case - where a provider package "cannot be resolved on disk (bundled Next.js)" — an acknowledged - hazard on exactly this template's path, and why §10's goal check goes through the route. +- **An *un*declared provider is reached by package resolution and a dynamic `import()`, and that + path does not survive Next's bundling** — which is what decision 5's static wiring avoids. Read + in `packages/core/src/models/createModelResolver.ts`: `isPackageProviderAvailable` calls + `isModuleResolvable(pkg)` through a `createRequire`, and on failure adds the provider to a + `directLoadFailed` set for the case where a package "cannot be resolved on disk (bundled + Next.js)" — after which the provider is filtered out of intent candidates and the only remaining + route is a gateway, or `No provider available`. **A *declared* provider takes none of that + path:** the explicit entry is invoked directly and `isPackageProviderAvailable`, + `directLoadFailed` and the gateway fall-through are never consulted. Our published guide states + the same conclusion and prescribes the same fix + (`apps/docs/guides/deploying-to-vercel.md:147`). +- **`providerPreference` and `providerDetection`'s gateway phase have no role under decision 5.** + `providerPreference` stable-reorders *intent candidates*, and the template declares no intents; + the gateway-marking phase feeds the availability map, which a declared provider never consults. + Recorded because the previous decision 5 rested entirely on both, and a reader who remembers + that argument should be able to see exactly why it no longer applies. - `@flow-state-dev/devtool` is an *optional peer* of the CLI, satisfied only inside this - monorepo. Init's install covers both it and the provider SDK; this package adds nothing. + monorepo. This package's install covers it alongside the provider SDK. - `@flow-state-dev/next` exports only `createNextHandler` (catch-all); the bare-path handler exists only in `@flow-state-dev/vercel`. Both in-repo mounts hand-write the bare forwarder, with a comment saying why. @@ -847,6 +1167,16 @@ runs or six, and whether decision 2b's flag exists. Nothing else. the `--template` flag (decision 2b). - **A bare-path handler in `@flow-state-dev/next`**, matching `createVercelBareHandler`. Would turn one hand-written template file into a one-liner. FIX-1159 flags the same gap. +- **Should the production refusal live in the framework rather than in generated code?** Decision + 8 puts it on the generated demo flow because that is where it can land in this issue's scope and + where the existing guards key. But *every* app on the default resolver has the same exposure, + and a guard in the engine would close them all at once instead of only the ones our scaffolder + wrote. Deliberately not decided here: it is a framework change with its own blast radius, + and shipping the generated-code version does not foreclose it. +- **A specified, proved minimal-project brownfield case in FIX-1159** — the substitute a backend + developer needs if decision 2 ships one starter. Named as a follow-up as well as in the ask, + because it is the half of the recommendation that lives in another issue and could otherwise be + agreed in principle and never written down. ### 13. Review notes for the implementer @@ -997,3 +1327,55 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions than argument (a scoped package packed, installed into a fresh consumer, the command resolved with no unscoped package present), which is how FIX-1162 settled it. Decision 1 is unaffected: `create-flow-state` still needs the unscoped name, and it is now the only thing that does. + +- **Five jobs that were disclaimed at both ends, and an edge asserted in two documents and + enforced by neither.** FIX-1159 decision 1 ships no `fsdev init` — not the command and not a + library behind it — and its 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, while §2, §5, §7, §8, §9, §10 and §12 + all still described a seam to a command that will not exist. **So five jobs and the whole of the + epic's greenfield proof were owned by nobody.** Decision 3 takes them, and says what that costs: + the seam is gone, the size is Medium rather than Small, and "byte-identical to a standalone init + run" is replaced by normalized equality against canonical text. Separately, epic theme 9 (c) and + FIX-1160 §7 both state a `FIX-1160 → FIX-548` merge edge — FIX-1160 authors the + agent-instructions block, this issue lands last and embeds it verbatim — and **§12 carried no + FIX-1160 dependency at all**, so a package built from this spec would have embedded nothing and + merged before its content had an author. Now recorded and wired in Linear. +- **Decision 5 is reversed, and restated as a reversal rather than edited.** It specified the + `models: { default, intents, providerPreference }` shorthand and explicitly *rejected* a + concrete provider/model string. Epic theme 9 (b)'s wiring contract requires the opposite — a + statically imported provider passed as a pre-built `modelResolver`, no intents, the model string + fixed by FIX-1159's provider table — because `createModelResolver` reaches an undeclared + provider through `createRequire` and a dynamic `import()` and **Next bundles server code, which + breaks that path**; our own published guide says so and prescribes this fix. What matters for a + sign-off surface is that the *argument* reversed with the mechanism: `providerPreference` existed + only to reorder intent candidates against `providerDetection`'s gateway behaviour, and with a + declared provider and no intents, neither is reached at all — verified by reading the resolver, + where an explicit entry is invoked directly and the `directLoadFailed` and gateway paths are + never consulted. The decision therefore says so out loud instead of quietly acquiring new text. + §12 also corrects the contract's surface from three items to **five**; the two that were missing + were the provider wiring and the runtime floor, and the first is precisely what decision 5 + contradicted. +- **The ask was arguing for a recommendation that had been withdrawn.** It priced one-template + against `mkdir my-api && npx @flow-state-dev/cli init` — "two commands instead of one" — and + said the cost of being wrong was small because it was "a path init already proves". There is no + `init` command, and FIX-1159 deleted its empty-directory worked example *and the goal check that + ran it* when the command went, so the substitute did not exist and nothing proved it. Rewritten + as a three-way fork with the recommendation the state of the world now supports: **ship one + starter plus a specified minimal-project brownfield path, falling back to shipping both** — + explicitly not the bare "ship one", which now means cutting the Node starter with nothing in its + place. Decision 2 is restated as conditional to match, and the premise was swept for rather than + the wording, which is what turned up §12's registry bullet: `create-flow-state` no longer + returns 404, it is published at `0.0.0` and ours, so the "asserted, not verified" ownership + caveat is discharged. +- **The rest of the epic's pending re-approval batch, folded in the same pass** — five comments on + this PR postdating the approved head, all cumulative to one re-take. **Theme 9 devolution:** both + shared blocks are embedded verbatim including branches this scaffolder never renders, and this + package's suite invokes each author's exported comparison against its own copy; the digest marker + is deleted. **Theme 6 exception (c) and theme 8:** `scripts.dev` and `scripts.start` are narrowed + to `127.0.0.1` — keys `create-next-app` wrote, carved out by name because a credential cannot + protect a browser client — and the demo flow refuses to serve outside development, with both + proved by negative assertions rather than by the happy case. **The dependency rule** is proved by + a pnpm-isolated install, because npm's flat `node_modules` would resolve an import the manifest + never declared. **The runtime floor** message names 22.18. And the transcript's `--input` drops + its `userId` key, which set nothing: `fsdev run` takes the caller identity as its own parameter. From a3fc69426a9032e980cef0b0a2c38c8f2104d807 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 00:24:26 +0000 Subject: [PATCH 16/30] spec(FIX-548): fix three residuals the rewrite created MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An edit-versus-neighbours pass over the sections changed in 48d2a52. The Updated-category count was stated as four while listing five items; "changes to files create-next-app wrote" is five (page.tsx included) while §7's "further changes" beside the six template files is four. Both counts are now stated with the question each answers. Non-goals disclaimed the wiring contract itself rather than only its authorship, which read as declining to conform to it. And the tenet 2 line still argued the command was "the ordering of three things that already exist" — with no init to call, the third is work this package does. Restated on what is actually composed, which is the knowledge. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index aa0f0d372e..42591865fb 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -57,9 +57,15 @@ template published inside this scaffolder. Instead **both conform to a wiring co authors**, and the tripwire watches for either one restating the wiring instead of citing it. This package still writes the shape; it no longer defines it. -**Philosophy** — tenet 2 (composition over features): the command's value is the ordering of -three things that already exist. Tenet 3 (earn every addition): §6 is mostly about keeping the -file list short and refusing surface — including a `--template` flag with one legal value. +**Philosophy** — tenet 2 (composition over features): the command's value is still mostly +*ordering* — Next's scaffolder, the package manager's install, and git's own answer about what it +would ignore, arranged so each runs when its inputs exist. **But it is less pure than this spec +used to claim.** The line read "the ordering of three things that already exist"; with no init to +call, the third is work this package does rather than a thing it sequences. What keeps the tenet +honest is that the *knowledge* is still composed — the wiring contract, the next-steps text and +the agent-instructions text are all authored elsewhere and embedded, not restated. Tenet 3 (earn +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 @@ -327,11 +333,16 @@ file list short and refusing surface — including a `--template` flag with one the owner should see it as a promise about what the thing does rather than as an implementation note. -**Non-goals** — the *content* of the agent-instructions block (FIX-1160 authors it; this package -places it) and of the next-steps block (FIX-1159 authors it; this package prints it); the -brownfield path in any form, including the wiring contract this template conforms to (FIX-1159 -specifies it, this package writes it); an `--upgrade` mode that regenerates config in an existing -project; and any template beyond the one decision 2 settles. +**Non-goals** — **authoring** any of the shared text or shapes: the agent-instructions block's +content (FIX-1160 authors it; this package places it verbatim), the next-steps block's content +(FIX-1159 authors it; this package prints it verbatim), and the wiring contract itself (FIX-1159 +specifies it; this package conforms to it and writes the shapes). Also: the brownfield path in any +form; an `--upgrade` mode that regenerates config in an existing project; and any template beyond +the one decision 2 settles. + +*Doing all three of those jobs **is** in scope — only authoring them is not, and the distinction is +load-bearing rather than pedantic: it is what keeps a single source per artifact once there is no +second command doing the work.* *This section previously disclaimed the API key, the ignore entry, the agent-instructions section, the install and the printed block as "anything `fsdev init` does". There is no `fsdev init`, and From 34801838470b4fdd345d379561dc368a0dff166d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 00:33:10 +0000 Subject: [PATCH 17/30] spec(FIX-548): derive the dependency set from imports, and fix a guard that refused its own printed command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two findings from codex on a3fc694, both confirmed against the code. The dependency set omitted @flow-state-dev/engine, where createFlowState and createFilesystemStores are exported. The generated config's first call was therefore unresolvable under pnpm — and resolvable under npm, which hoists, so any proof run under npm returned green on the broken manifest. §10 now names pnpm specifically and says why the word is load-bearing. It also omitted @flow-state-dev/devtool. That one is not a hoisting question: an optional peer is installed by no manager, so `fsdev dev` failed everywhere. It survived because the rule covered what the generated files import, and nothing generated imports the CLI or the DevTool. The rule gains a second clause for what a printed command needs at run time, and the set is now shown as derived per row from the imports and the printed commands rather than kept by hand. Decision 8's refusal was written as "outside development". NODE_ENV is unset in an ordinary shell and packages/cli/src never sets it, so the guard would have refused the printed `fsdev run` on the developer's own laptop. Predicate is now === "production", fail-open on unset and stated as such, with the complement assertion added so the pair cannot pass on a guard that refuses everything. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 166 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 142 insertions(+), 24 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 42591865fb..2330d17739 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -299,9 +299,38 @@ every addition): §6 is mostly about keeping the file list short and refusing su - **`scripts.dev` and `scripts.start` are narrowed to loopback** — `next dev --hostname 127.0.0.1` and `next start --hostname 127.0.0.1`. The printed commands do not change; the developer still types `npm run dev`. - - **The demo flow refuses to serve outside development on the default resolver.** Declared on - the flow itself, so a request in production mode is refused **before any model invocation**, - with an error naming the missing authentication. + - **The demo flow refuses to serve when `process.env.NODE_ENV === "production"`**, on the + default resolver. Declared on the flow itself, so the request is refused **before any model + invocation**, with an error naming the missing authentication. + + **The predicate is `=== "production"`, not "outside development", and the difference is the + whole decision.** `NODE_ENV` is **unset** in an ordinary shell, and the CLI never sets it — + `packages/cli/src/commands/run.ts` contains no `NODE_ENV` assignment, and neither does anything + else under `packages/cli/src`. So a guard reading *refuse unless development* would refuse + **`npm exec -- fsdev run chat send …`, a command this scaffold prints**, on a developer's own + laptop, before any model call. The guard would fire on the scenario it exists to permit. + + *Named because it keeps happening:* state the scenario a guard exists for, then state the + scenario it will actually meet most often, and check they are different. Here they were the + same, and the earlier "outside development" wording is what made it invisible. + + *The codebase has both conventions and this picks one deliberately rather than averaging.* + `packages/engine`'s block-trace default keys on `NODE_ENV !== "production"`; its store-factory + default keys on `=== "development"`. For a guard on the printed path the first is the only one + that works, and it is the one taken. + + *What `=== "production"` costs, stated because it narrows the promise.* It is **fail-open on an + unset variable**. It fires where it matters — `next start` and every mainstream platform deploy + set `NODE_ENV=production`, and §10's negative assertion runs `npm run build && npm start` and is + what proves the mechanism rather than assuming it. It does **not** fire in a hand-rolled host + that runs neither of the template's scripts and leaves `NODE_ENV` unset. That path ships no file + of ours, but the gap is real and is not papered over. + *Rejected for closing it:* having the CLI set `NODE_ENV=development` — that is a change to + `packages/cli`, which §7 declares untouched, and it would alter behaviour for every existing + `fsdev run` caller to fix a generated project. Also rejected: a template-written marker variable + in `.env.local` as the development signal — fail-closed, but it invents a mechanism, adds a + variable to explain in the first five minutes, and breaks on a developer who copies `.env.local` + into a deployment dashboard. *Rejected:* **a credential, which is what protects the brownfield path.** It cannot work here and the reason is the client, not the effort: the chat page is a client component using @@ -630,9 +659,9 @@ is touched. This is the entire product surface: | file | what it is | |---|---| -| `fsdev.config.ts` | default-exports `createFlowState({ flows, modelResolver, stores })`. 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 | +| `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 | | `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, naming **the concrete `provider/model` string** for the provider chosen (decision 5's table), never an intent. Declares the production refusal on itself (decision 8), so a request outside development is refused before any model invocation. Imports `z` from `zod` for its input schema — a direct dependency, per the contract's dependency rule. `examples/hello-chat`'s flow is the reference for shape, not for size. Path matches what the docs teach | +| `src/flows/chat/flow.ts` | the demo flow — one action, one streaming generator, naming **the concrete `provider/model` string** for the provider chosen (decision 5's table), never an intent. Declares the production refusal on itself (decision 8), keyed on `NODE_ENV === "production"`, so such a request is refused before any model invocation. Imports `defineFlow` from `@flow-state-dev/core` and `z` from `zod` — both direct dependencies, per the contract's dependency rule. `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, no Vercel assumption. **Carries the canonical route exports beside it: `runtime = "nodejs"` and `dynamic = "force-dynamic"`.** Not decoration — `packages/next/README.md` ships exactly those three lines, and `examples/hello-chat` documents why: without `force-dynamic` Next may buffer the response body, and a buffered body turns token-by-token streaming into one delivery at the end. That is the epic's headline outcome failing while every wiring check passes | | `app/api/flows/route.ts` | the sibling bare route. `list_flows` is registered as `GET /` on the mount base and the client's `listFlows()` requests it, but a required catch-all cannot match zero segments. `@flow-state-dev/next` exports no bare handler (only `@flow-state-dev/vercel` does), so this one forwards by hand with a comment saying why — carrying the same route exports as its sibling | | `app/page.tsx` | the chat page. `FlowProvider` + `useFlow` + `useSession` + `ItemsRenderer` from `@flow-state-dev/react`, no other imports (decision 6). Overwrites `create-next-app`'s stock page — permitted, because this is a directory this command created seconds ago | @@ -640,13 +669,43 @@ is touched. This is the entire product surface: | *tsconfig* | `allowImportingTsExtensions: true` added — decision 4. Required, not stylistic: the config imports the demo flow, native Node will not infer the extension, and the `.ts` specifier that satisfies Node is a `TS5097` error without this key | **The dependency set is a rule, not a list** (the wiring contract): *every package the generated -files import directly is a direct dependency of the generated manifest.* Under the shape above -that reaches `@flow-state-dev/core`, `@flow-state-dev/next`, `@flow-state-dev/react`, -`@flow-state-dev/cli`, **`zod`** (the flow's input schema imports `z` directly, and -`@flow-state-dev/core` carrying `zod` in its own dependencies does nothing for a consumer under -pnpm's strict isolation), and **the AI SDK package for the provider chosen** — never a fixed one. -Stated as a rule because two review rounds across this epic each found one member missing from a -list. §10 proves it by an isolated pnpm install rather than by reading the manifest. +files import directly, **and every package a printed command needs at run time**, is a direct +dependency of the generated manifest.* **The list below is derived from the imports and the +printed commands — it is not maintained by hand, and an implementer re-derives it rather than +copying it**, because three review rounds across this epic have each found a different member +missing from a hand-kept list. + +| 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** | +| `@flow-state-dev/core` | `src/flows/chat/flow.ts` imports `defineFlow` | **yes** | +| `@flow-state-dev/next` | both route files import `createNextHandler` | no — nothing else provides it | +| `@flow-state-dev/react` | `app/page.tsx` imports the hooks and renderer | no | +| `zod` | the flow's input schema imports `z` directly | **yes** | +| the AI SDK for the chosen provider | `fsdev.config.ts` statically imports the factory (decision 5) | no | +| `@flow-state-dev/cli` | **executed, not imported** — every `fsdev` command the next-steps block prints | no | +| `@flow-state-dev/devtool` | **executed transitively** — `fsdev dev` resolves its assets by `import("@flow-state-dev/devtool")`, and the CLI declares it only as an **optional** peer, which no package manager installs on its own | no — **missing under npm too** | + +**Two of these were absent from the previous revision's list, and the reasons they survived are +different — which is why the rule now has two clauses.** + +- **`@flow-state-dev/engine` is the expensive one.** `createFlowState` is the generated config's + first call, so without it the project does not run at all. **It survived because npm and Yarn + hoist and pnpm does not**: `@flow-state-dev/next` and `@flow-state-dev/cli` both depend on + `engine`, so under npm it lands in a flat `node_modules` and the undeclared import resolves. Any + proof executed under npm returns green on the broken manifest. **The package manager the proof + runs under decides whether the defect exists** — which is why §10 names pnpm explicitly rather + than saying "isolated". +- **`@flow-state-dev/devtool` is not a hoisting problem at all**, and calling it one would put the + fix in the wrong place. An **optional** peer is installed by no manager, npm included, so + `fsdev dev` — a command the block prints — fails on every path with `DevTool assets not found` + (`packages/cli/src/commands/dev.ts` throws a `CliError`; its only fallback scans + `process.cwd()/apps/devtool/dist`, which exists solely inside this monorepo). It survived because + the **rule** had one clause: it covered what the generated files *import*, and nothing generated + imports the CLI or the DevTool. Hence the second clause above. + +§10 proves the whole set by an isolated **pnpm** install that runs the flow, and separately by +executing the printed commands against a real install. **Why the config shape is what it is — measured.** The template's config has two consumers at once: Turbopack, because the route imports it, and the CLI's native `import()`. Nobody had @@ -841,15 +900,23 @@ ask above is pricing: it is per template *times* per provider, not per template: sides, so it is where the epic's additive guarantee is exercised end to end. - **And the run's report is compared against the actual diff**, including all five changes to files `create-next-app` wrote. -- **A pnpm-isolated install of the emitted template.** After the scaffold, install the generated - app's own `package.json` with **pnpm** and run the generated flow from that install. This is the - only thing that can fail the dependency rule: npm's flat `node_modules` hoists transitives and - resolves an import the manifest never declared, so an npm-only proof passes on an incomplete - manifest. **A static import-versus-manifest scan does not substitute** — the provider SDK is - never statically imported by *our* code, it is named in the manifest and reached at run time, and - it is one of exactly two members of the rule that a review round already missed once. The - headline command stays `npm create flow-state my-app`; that is the advertised UX and is not the - thing under test. +- **A pnpm-isolated install of the emitted template — and the word `pnpm` is load-bearing, not a + synonym for "isolated".** After the scaffold, install the generated app's own `package.json` + with **pnpm specifically** and run the generated flow from that install. npm and Yarn hoist + transitives into a flat `node_modules`, so they resolve imports the manifest never declared; + **under npm this check returns green on a manifest missing `@flow-state-dev/engine`, which is + the package the generated config's very first call comes from.** A proof whose package manager + decides whether the defect is visible is not a proof. **A static import-versus-manifest scan does + not substitute either** — the provider SDK is named in the manifest and reached at run time, not + statically imported by our code. The headline command stays `npm create flow-state my-app`; that + is the advertised UX and is not the thing under test. +- **Every printed command runs against that real install — `fsdev dev` included.** Executing the + block's strings is the only check that reaches the second clause of the dependency rule: nothing + generated *imports* the CLI or the DevTool, so no import scan and no config load sees them. `fsdev + dev` resolves its assets through `import("@flow-state-dev/devtool")`, an **optional** peer that + no package manager installs on its own, and fails with `DevTool assets not found` when it is + absent from the generated manifest — **on npm as well as pnpm**, since this one is not a hoisting + question. - **Two negative assertions, because every control here is otherwise proved only by its happy case.** A check that exercises only `localhost` passes identically whether the bind flag is present or was never implemented at all. @@ -857,6 +924,13 @@ ask above is pricing: it is per template *times* per provider, not per template: - **With the app built and started in production mode on the default resolver, a request to the mounted route is refused before any model invocation**, returning an error that names the missing authentication rather than a stream. A 200 carrying an error body is not a refusal. + Run it as `npm run build && npm start` — **this is also what proves the guard's predicate is + right**, since it establishes that the real path actually sets `NODE_ENV=production` rather + than assuming it (decision 8). + - **And the complement, on the same run: `npm exec -- fsdev run chat send …` succeeds.** The + guard must *not* fire on the command the scaffold prints, where `NODE_ENV` is unset. Without + this assertion the pair above passes on a guard that refuses everything, which is precisely + the shape the "outside development" wording would have shipped. - The key is deliberately *not* pre-exported. PR #1301's review note 8 called that out: pre-supplying it skips the credential path, so the check passes while a real user's first command fails. @@ -934,7 +1008,15 @@ package-manager install, in a temporary directory, with no network, **except the message naming the floor, and an untouched target directory. Without it the failure moves to every printed `fsdev` command, after a project exists (decision 4) - **every printed command runs** — execute the strings the block emitted, in the generated - project, and assert the process starts. This is where npm's `--` separator is caught + project, and assert the process starts. This is where npm's `--` separator is caught. **The + stubbed form of this check cannot see a missing dependency** (nothing is installed), which is why + the executed-against-a-real-install version sits in the goal check above; keep both and do not + let the cheap one stand in for the other +- **the generated manifest declares every member of the dependency rule, derived rather than + compared to a fixed list** — assert it by resolving each package the generated files import + *from the generated files themselves*, plus `@flow-state-dev/cli` and `@flow-state-dev/devtool` + for the printed commands. A test that hard-codes the expected list drifts the moment a template + file gains an import, which is the failure this assertion exists to prevent - every refusal in §9's first block, each asserting nothing was created - `-y` with no key: the scaffold completes and the output says the key is missing @@ -1154,8 +1236,18 @@ Nothing else. the gateway-marking phase feeds the availability map, which a declared provider never consults. Recorded because the previous decision 5 rested entirely on both, and a reader who remembers that argument should be able to see exactly why it no longer applies. -- `@flow-state-dev/devtool` is an *optional peer* of the CLI, satisfied only inside this - monorepo. This package's install covers it alongside the provider SDK. +- **`createFlowState` and `createFilesystemStores` are exported from `@flow-state-dev/engine`** + (`packages/engine/src/index.ts`), while `defineFlow` comes from `@flow-state-dev/core` + (`packages/core/src/index.ts`). Both are direct dependencies of the generated manifest; naming + only `core` — as an earlier revision of the dependency set did — leaves the config's first call + unresolvable under pnpm and resolvable under npm by hoisting. +- **`@flow-state-dev/devtool` is an `optional: true` peer of the CLI** (`packages/cli/package.json` + `peerDependenciesMeta`), so **no package manager installs it automatically — npm included.** + `resolveDevToolAssets` in `packages/cli/src/commands/dev.ts` tries + `import("@flow-state-dev/devtool")`, then falls back to `process.cwd()/apps/devtool/dist` and + `packages/devtool/dist-client` — monorepo-only paths — and otherwise throws `CliError("DevTool + assets not found…")`. A generated project must therefore declare it directly, or `fsdev dev` + fails for every user on every manager. - `@flow-state-dev/next` exports only `createNextHandler` (catch-all); the bare-path handler exists only in `@flow-state-dev/vercel`. Both in-repo mounts hand-write the bare forwarder, with a comment saying why. @@ -1390,3 +1482,29 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions a pnpm-isolated install, because npm's flat `node_modules` would resolve an import the manifest never declared. **The runtime floor** message names 22.18. And the transcript's `--input` drops its `userId` key, which set nothing: `fsdev run` takes the caller identity as its own parameter. + +- **Two defects in the previous revision, both of which a proof would have reported green.** The + dependency set omitted **`@flow-state-dev/engine`** — where `createFlowState` and + `createFilesystemStores` actually live — so the generated config could not resolve its first call + under pnpm, while **npm's hoisting resolved it and passed**. That is the check-that-cannot-fail + shape at its most expensive: the package manager the proof runs under decided whether the defect + existed, so §10 now says **pnpm** rather than "isolated" and explains why the word carries weight. + It also omitted **`@flow-state-dev/devtool`**, and that one is *not* about hoisting — an optional + peer is installed by nobody, so `fsdev dev` failed on every manager. It survived because the + dependency **rule** had one clause covering what the generated files *import*, and nothing + generated imports the CLI or the DevTool. The rule now has a second clause for what a printed + command needs at run time, and the set is presented as **derived from the imports and the printed + commands** — with the derivation shown per row — rather than as a list to keep in step by hand. +- **Decision 8's guard fired on the command the scaffold prints.** It was written as refusing + "outside development", and `NODE_ENV` is unset in an ordinary shell — `packages/cli/src` contains + no `NODE_ENV` assignment anywhere — so `npm exec -- fsdev run chat send …` would have been + refused on the developer's own laptop, before any model call. The predicate is now + `NODE_ENV === "production"`, which is fail-open on an unset variable and is stated as such: + it fires on `next start` and mainstream platform deploys, not on a hand-rolled host that leaves + the variable unset. §10 gains the complement assertion — the printed `fsdev run` must *succeed* — + because the production refusal alone passes on a guard that refuses everything. Rejected for + closing the gap: having the CLI set `NODE_ENV`, which is a framework change §7 declares out of + scope, and a template-written marker variable, which invents a mechanism to explain in the first + five minutes. **This is the third guard in this epic to fire on its own intended state**, so the + test is recorded beside the decision: name the scenario the guard exists for, name the scenario it + will actually meet most often, and check they are different. From 30f63998635e94a04f766bdf1222535e618640d4 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 00:33:58 +0000 Subject: [PATCH 18/30] spec(FIX-548): name pnpm on the two real CI specs that install MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sweep the dependency fix implied, run across §10 rather than stopping at the check that failed. Two of the three real CI specs install a scaffolded project and named no package manager, so they would have inherited the same hoisting blindness the goal check was just changed to remove — the config-load spec especially, since it imports the config, which imports engine. Both now specify pnpm, with the rule stated once for the whole suite. The headline goal check stays npm on purpose: it is the advertised UX, and the pnpm run beside it is what makes it trustworthy. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 2330d17739..e6a6879700 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -937,15 +937,26 @@ ask above is pricing: it is per template *times* per provider, not per template: **CI specs** (behaviours, not test names) — all against a stubbed `create-next-app` and a stubbed package-manager install, in a temporary directory, with no network, **except the three marked -*real*, which build a scaffolded project once**: +*real*, which build a scaffolded project once**. + +**Every check in this suite that installs anything installs with pnpm**, for the reason the goal +check gives: npm and Yarn hoist transitives, so an npm-backed check resolves imports the manifest +never declared and returns green on a manifest that is missing a package. Two of the three *real* +specs below install, and an earlier revision left their manager unnamed — which would have let the +suite inherit exactly the blindness the goal check was changed to remove. The only npm-backed run +anywhere in this spec is the headline goal check, deliberately, because `npm create flow-state +my-app` is the advertised UX; the pnpm run beside it is what makes that one safe to trust. - one behaviour per decision in §6 -- ***real*: the generated project builds and its mounted route serves** — the check that decision - 4 keeps passing when Next's resolution behaviour moves under us. This is the drift tripwire - decision 3 owes; it is the only assertion that covers the template's contents rather than its - file names -- ***real*: the config loads under a native `import()` with no warning** — asserted on stderr, - because `MODULE_TYPELESS_PACKAGE_JSON` is a first-hour wart that no functional test fails on +- ***real*, pnpm: the generated project builds and its mounted route serves** — the check that + decision 4 keeps passing when Next's resolution behaviour moves under us. This is the drift + tripwire decision 3 owes; it is the only assertion that covers the template's contents rather + than its file names +- ***real*, pnpm: the config loads under a native `import()` with no warning** — asserted on + stderr, because `MODULE_TYPELESS_PACKAGE_JSON` is a first-hour wart that no functional test fails + on. **Under pnpm specifically**: this check imports the config, which imports + `@flow-state-dev/engine` and the demo flow, so an npm-backed version of it passes on the same + incomplete manifest the goal check used to pass on - **both route files carry `runtime = "nodejs"` and `dynamic = "force-dynamic"`** — asserted on the generated files against `packages/next/README.md`'s canonical shape. Cheap and worth it because the failure it guards is invisible to every other check here: without `force-dynamic` @@ -1508,3 +1519,14 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions five minutes. **This is the third guard in this epic to fire on its own intended state**, so the test is recorded beside the decision: name the scenario the guard exists for, name the scenario it will actually meet most often, and check they are different. + +- **The manager-blindness sweep, run across every proof rather than only the one that failed.** + Fixing the dependency set is not the same as fixing the class, so §10 was walked check by check + asking *would this pass under npm and fail under pnpm?* One more did: **two of the three *real* + CI specs install a scaffolded project and their package manager was never named**, so the suite + would have inherited the blindness the goal check had just been changed to remove — the config- + load spec in particular imports the config, which imports `@flow-state-dev/engine`. Both now say + pnpm, and the rule is stated once for the whole suite. The headline goal check remains **npm** + deliberately, because `npm create flow-state my-app` is the advertised UX; what makes that safe + is the pnpm run standing beside it, not the npm run itself. Nothing in the reverse direction + exists — pnpm is the stricter resolver, so no check here passes under pnpm and fails under npm. From 2aebb4040ff6b2c9950bd80efe4615db9888774d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 00:46:02 +0000 Subject: [PATCH 19/30] spec(FIX-548): order the deterministic writes ahead of the fallible ones, and fix a goal check that could not pass MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three findings from codex on 30f6399, all confirmed. Step 5 installed before appending AGENTS.md, so a failed install left a project missing the agent-instructions section and the printed recovery — an install — could not restore it. The same hole sat under the credential stop, which the finding did not name. Fixed by ordering: the append is now step 4, ahead of both fallible steps, and §7 carries the general rule as a table asking what each printed recovery actually restores. §5 labelled the -y invocation as how the goal check runs, while §10 required a streamed response from a key typed at the prompt. -y suppresses that prompt and there is no key flag, so the goal check could not pass. It now runs interactively; CI keeps -y because the empty-key path is what CI asserts. §10 records once that a check which cannot pass and a check which cannot fail are the same defect. Decision 2 claimed shipping both starters would change only templates//. It would not, and that under-priced the fallback this spec recommends. Decision 2 now enumerates what that branch needs and the ask says it buys another spec round. Q6 stays in front of implementation, not approval. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 269 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 211 insertions(+), 58 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index e6a6879700..432393de0f 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -91,21 +91,50 @@ every addition): §6 is mostly about keeping the file list short and refusing su 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.* Everything else in this document is written against one template and - changes only in `templates//` if the answer is two. + blocks implementation.* *Rejected:* two templates, as epic theme 2 decided — **conditionally**, and the condition is the point: the fallback if the minimal-project path is not taken up is to ship both, not to ship one anyway. *Locks in:* one starter to keep green on machines we do not control, and three recorded goal runs per release rather than six. + **This document is written against one template throughout, and shipping two is not a + `templates//` change.** An earlier revision of this decision said it was; that was wrong, + and it under-priced the branch this spec recommends as its own fallback. Everything from §7 + step 2 down assumes Next.js: the pipeline spawns `create-next-app` unconditionally, three of + the four changes it makes are Next-specific (`allowImportingTsExtensions`, and the `next dev` / + `next start` script values decision 8 narrows), the mount pair and the chat page are Next files, + the wiring contract's item this template satisfies is *the Next.js mount pair*, and §10's proof + is a browser rendering a streamed response through that mount. + + **So the "ship both" branch cannot be implemented from this text.** What it would take is + scope, not design, and it is named here so the fork is priced honestly rather than specified by + implication — deciding it is epic §5 Q6's, not this spec's: + - a scaffolder step for a project with no framework (or none, if the template writes the + manifest itself), replacing step 2; + - its own file set and its own `create-next-app`-equivalent change list, since none of the four + current changes applies; + - **its own security posture**, because decision 8 does not transfer: there are no `next dev` / + `next start` scripts to narrow, the second process is `fsdev serve`, which defaults to + `0.0.0.0` and is governed by `assertNetworkBindIsAuthenticated` rather than by a script value + (§12) — a different control with a different failure mode; + - its own verification path, since there is no browser and no mounted route: the epic's + `second-process` topology, proved by a request rather than by a rendered page; + - and the `--template` flag decision 2b currently declines. + + **Concretely: choosing to ship both buys another specification round on this issue.** That is a + real cost on that branch and it was not on the ledger when the fork was first priced. It does + not change the recommendation — see the ask — because the recommended answer does not incur it. + 2b. **No `--template` flag in v1.** *Rejected:* shipping the flag with one legal value to signal the plan. A flag whose only argument was a template decision 2 just cut is surface that documents an intention and does nothing else; someone who types `--template node-api` - gets a refusal listing a single value, which reads worse than no such flag. The seam that - makes a second template cheap is the `templates//` directory in §7, not the flag — - and adding a flag nobody could have been passing breaks no invocation. If decision 2 is - overturned, the flag arrives with the template it selects between. + gets a refusal listing a single value, which reads worse than no such flag. Adding a flag + nobody could have been passing breaks no invocation, so it costs nothing to defer. If decision 2 + is overturned, the flag arrives with the template it selects between — **and it is the smallest + part of that work, not the seam that makes it cheap.** An earlier revision said the + `templates//` directory was that seam; it holds the *files*, and decision 2 above lists + everything outside it that a second template needs. 3. **`create-flow-state` is the greenfield path in every part.** It writes the whole FSD half of the template as real checked-in files — config, mount, flow, page — **and it also does the @@ -445,11 +474,30 @@ green and prove on every release, and a slower release loop for as long as it li (C) is the expensive one and it is the one that happens silently** — a backend developer's first five minutes with FSD ends in "this is a Next.js thing", and we would not hear about it. -**Whose call.** This reverses epic theme 2 and adds scope to FIX-1159, so it belongs to the epic's -owner rather than to this spec — it is epic **§5 Q6**, which the epic records as open and blocking -this issue's *implementation* while explicitly allowing its re-approval to proceed. Either answer -is cheap in this document: §7's `templates//` layout exists regardless, and only whether -`node-api` ships in v1 — and with it decision 2b's flag — changes here. +**One correction to how this fork was priced, because it lands on the fallback.** This section +previously said either answer was cheap here — that §7's `templates//` layout absorbed the +difference. **It does not.** Everything from §7 step 2 down is Next-specific: the pipeline spawns +`create-next-app` unconditionally, three of its four changes to scaffolder-written files are Next +keys, and the proof is a browser rendering through a mounted route. **Shipping both starters +therefore buys another specification round on this issue** — a Node scaffolding step, its own file +set, its own security posture (decision 8 does not transfer; the plain-Node control is +`fsdev serve`'s bind guard, not a script value), its own verification path, and the `--template` +flag. Decision 2 lists it in full. That is a real cost on **(B)**, it was not on the ledger when +this fork was first put, and it belongs in front of whoever answers. + +It does **not** change the recommendation: **(A)** incurs none of it, and its cost — one +specification and one goal check — lands in FIX-1159 rather than here. It does mean **(B)** is +slower than "add a directory", and that (C) remains the only free-today answer, which is exactly +why it is the one most likely to be chosen by drift rather than on purpose. + +**Whose call, and when.** This reverses epic theme 2 and adds scope to FIX-1159, so it belongs to +the epic's owner rather than to this spec — it is epic **§5 Q6**, which the epic records as open +and blocking this issue's *implementation* while explicitly allowing its re-approval to proceed. +**That split still holds and this spec does not ask to move it.** Approving this document approves +the one-starter spec, which is complete and internally consistent; if the answer comes back (B), +the spec returns for the round decision 2 enumerates. Blocking approval on Q6 would buy nothing — +nobody can build under either answer until it is settled — and would spend the owner's attention on +sequencing rather than on the question itself. --- @@ -580,12 +628,28 @@ Three details in the block are load-bearing rather than cosmetic: key set nothing and taught a first-hour reader a wrong mental model. - **The two-process caveat is real** — both printed servers open the same development file store. -**Non-interactively**, which is how the goal check and CI run it: +**Non-interactively**, which is how **CI** runs it — **not the goal check**, for the reason below: ``` $ npm create flow-state my-app -- --provider openai --package-manager pnpm -y ``` +**There is no key flag, and that is what makes the goal check interactive.** A secret on argv lands +in shell history and in every process listing on the machine, so the key is collected **at the +prompt, or from the environment, and never from a flag**. `-y` therefore suppresses the key prompt +and — with nothing in the environment — produces the empty-variable scaffold §9 describes, which +cannot make a model call. + +*So the goal check runs this command **without `-y`** and drives the prompt.* An earlier revision +labelled this non-interactive form as "how the goal check and CI run it" while §10 required a real +streamed response from a key supplied at the prompt. Those cannot both hold: **the goal check as +written could not pass.** CI keeps the non-interactive form, because what CI asserts is the +empty-key path itself. + +**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. + **When the directory is already taken** — the refusal happens before anything is created: ``` @@ -597,7 +661,7 @@ $ npm create flow-state my-app ### 7. Technical design -A new published package, `create-flow-state`, whose entry point is a five-step pipeline. It has +A new published package, `create-flow-state`, whose entry point is a seven-step pipeline. It has no runtime dependency on this monorepo beyond the published `@flow-state-dev/cli` it imports, and nothing it writes into the generated project imports anything of ours that is not on npm (epic theme 4). @@ -610,12 +674,18 @@ by itself set the published name. ```mermaid flowchart TB - A[resolve invocation
name · provider · key · package manager
Node ≥ 22.18] --> B[create the bare app
create-next-app, install skipped, every flag explicit] - B --> C[write the template
6 files · + 4 changes to files create-next-app wrote] - C --> D[credential stop
git check-ignore .env.local, then write the key] - D --> E[install · append AGENTS.md · print next steps
both blocks embedded verbatim] + A[1 · resolve invocation
name · provider · key · package manager
Node ≥ 22.18] --> B[2 · create the bare app
create-next-app, install skipped, every flag explicit] + B --> C[3 · write the template
6 files · + 4 changes to files create-next-app wrote] + C --> D[4 · append AGENTS.md section
FIX-1160's block, verbatim] + D --> E[5 · credential stop
git check-ignore .env.local, then write the key] + E --> F[6 · install
resolved package manager] + F --> G[7 · print next steps
FIX-1159's block, verbatim] ``` +*Every deterministic local write is steps 3–4, before the two steps that can fail (5 and 6), so a +failure leaves a project the printed recovery genuinely completes. The table below step 7 says what +each recovery restores.* + **Step 1 — resolve the invocation.** Flags first, prompts for whatever is missing, `-y` to take defaults for everything unflagged. Validation (project name is a legal npm package name, target directory absent or empty, Node at or above the runtime floor) happens **here**, before any @@ -723,20 +793,40 @@ reason for passing every flag explicitly and refusing `--yes`. The probe passes never reproduces it. The README's two lists — what is asserted, and what is deliberately not — are exhaustive, which is what keeps the citation and the evidence one-to-one. -**Step 4 — the credential stop.** Before `.env.local` is written, ask **git** whether it would +**Step 4 — append the agent-instructions section to `AGENTS.md`.** `create-next-app` writes its +own `AGENTS.md` (and a `CLAUDE.md`), so this **appends** — it never creates, and never touches +Next's own delimited block. The section's text is **FIX-1160's canonical block, embedded verbatim** +in this package's source. + +**Step 5 — the credential stop.** Before `.env.local` is written, ask **git** whether it would ignore that exact path (`git check-ignore`). In a fresh `create-next-app` scaffold the answer is already yes (verified by the POC), so this is normally an assertion rather than a write. If it is not, append the rule and re-verify; if it still cannot be established, **stop before the key is written** (§9). Only then write `.env.local` with the chosen provider's variable name and the value collected in step 1. -**Step 5 — finish the project.** Three things, in this order: +**Step 6 — install.** Run the resolved package manager's install in the target directory. One +manager, one lockfile. The manifest's `"type": "module"` and its dependency set must already be in +place, because the package manager reads that file and rewrites it. -| what | detail | -|---|---| -| **install** | run the resolved package manager's install in the target directory. One manager, one lockfile. The manifest's `"type": "module"` must already be in place, because the package manager rewrites that file | -| **append the agent-instructions section to `AGENTS.md`** | `create-next-app` writes its own `AGENTS.md` (and a `CLAUDE.md`), so this **appends** — it never creates, and never touches Next's own delimited block. The section's text is **FIX-1160's canonical block, embedded verbatim** in this package's source | -| **print the next-steps block** | **FIX-1159's canonical block, embedded verbatim**, rendered for the resolved package manager and the `mounted-route` topology | +**Step 7 — print the next-steps block.** **FIX-1159's canonical block, embedded verbatim**, +rendered for the resolved package manager and the `mounted-route` topology. + +**Every deterministic local write happens before the two steps that can fail, and that ordering +is a promise §9 makes rather than a preference.** The rule: *for each step, ask what the printed +recovery actually restores.* Applied here, it moved the `AGENTS.md` append from last to fourth. + +| fallible step | what is already on disk when it fails | what the printed recovery restores | +|---|---|---| +| step 2, `create-next-app` | nothing of ours | nothing — the target is somebody else's partial output, so the instruction is inspect and restart (§9) | +| step 5, the credential stop | the six template files, all four changes, **and the `AGENTS.md` section** | the developer adds the ignore line, writes the key, and installs — three named steps, and nothing is missing that they would have to author | +| step 6, the install | everything above, plus the key | `npm install` in that directory. **Exactly the promise §9 makes** | + +*An earlier revision ran the install first and appended `AGENTS.md` last. A failed install then left +a project missing the agent-instructions section, and the recovery command — an install — could not +restore it: the only text that would have completed it is canonical content this package embeds and +the developer cannot be asked to hand-write. **So the "finishable scaffold" promise was false in +precisely the case it exists for.** The fix is ordering, not a longer error message.* **Both blocks are embedded verbatim, every branch included — including the one this package can never render.** They are epic theme 9 *source blocks*: one canonical text, embedded in each @@ -758,13 +848,12 @@ exists to prevent. No digest, no marker, no hashing: the stored-value mechanisms **No new package and no new dependency between packages comes with any of this.** The comparisons are test-time imports inside this monorepo, where every shipper already lives. -**Ordering, and why it is not incidental.** The template is written *before* the install, so the -manifest is complete when the package manager reads it. The credential stop runs *before* the key -is written and *after* the scaffold exists, because git cannot answer about a directory that does -not exist yet. `create-next-app` must skip its -install, or the project installs twice and the second run rewrites the lockfile the first wrote. -And the manifest's `"type": "module"` must land before the install, because the package manager -rewrites that file. +**The remaining ordering constraints, beyond the recovery rule above.** `create-next-app` must skip +its install, or the project installs twice and the second run rewrites the lockfile the first +wrote. The manifest's `"type": "module"` and its dependency set must land before the install, +because the package manager reads and rewrites that file. And the credential stop runs *after* the +scaffold exists, because git cannot answer about a directory that does not exist yet — which is why +it is the one deterministic step that cannot be hoisted above `create-next-app`. **Untouched:** the engine, the adapters, the CLI's existing commands, every block kind. This package generates a project; it changes no framework behaviour. @@ -790,24 +879,32 @@ package generates a project; it changes no framework behaviour. native `import()` with the demo flow imported through it**, not as a self-contained module, with no warning; both `scripts` values carry `--hostname 127.0.0.1`. *Depends on:* nothing. -4. **The credential stop** — `git check-ignore` against `.env.local`, the append-and-re-verify +4. **The `AGENTS.md` append** — FIX-1160's canonical block embedded verbatim and appended, never + creating the file and never touching Next's own delimited block. **Sequenced here, before the + two fallible steps, so a later failure leaves nothing the developer would have to author** + (§7). *Test:* normalized equality against canonical via FIX-1160's exported comparison, every + branch included; Next's own block and `CLAUDE.md` intact byte-for-byte afterwards. + *Depends on:* 2, **and FIX-1160's block existing** — see §12. +5. **The credential stop** — `git check-ignore` against `.env.local`, the append-and-re-verify path, the stop, then the key write. *Test:* the ordering (the check precedes the write, - executed rather than read), and the stop leaving a usable scaffold with no key in it. - *Depends on:* 2. -5. **Finishing the project** — the install, the `AGENTS.md` append, and the printed next-steps - block, with both canonical blocks embedded verbatim and asserted by the authors' exported - comparisons. *Test:* normalized equality over each whole block including unrendered branches; - the append leaves Next's own `AGENTS.md` block and `CLAUDE.md` intact; every printed command - runs. *Depends on:* 1, 2, 3, 4, **and FIX-1159's next-steps block and FIX-1160's - agent-instructions block existing** — see §12. -6. **Publish configuration and the README that renders on npm.** *Depends on:* 1. + executed rather than read), and the stop leaving a usable scaffold with no key in it — **and + with the `AGENTS.md` section already present**, since that is what makes its recovery a list of + steps rather than an unrecoverable gap. *Depends on:* 2, 4. +6. **The install** — run the resolved package manager, surface its failure, and print the recovery + that genuinely completes the project. *Test:* the failure path leaves every file and every edit + on disk and prints the install command against that directory. *Depends on:* 3, 5. +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. +8. **Publish configuration and the README that renders on npm.** *Depends on:* 1. **PR plan.** Two sub-PRs. | sub-PR | deliverables | depends_on | |---|---|---| -| a | the package: invocation surface, bare-app step, the template, the credential stop, and finishing the project (steps 1–5) | — | -| b | publish configuration, package README, and the three doc surfaces in §11 (step 6) | a | +| a | the package: invocation surface, bare-app step, the template, the `AGENTS.md` append, the credential stop, the install, and the printed block (steps 1–7) | — | +| b | publish configuration, package README, and the three doc surfaces in §11 (step 8) | a | ### 9. Edge cases & error handling @@ -829,7 +926,7 @@ no-rollback rule directly below. | 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 command to finish. Never write the key "and warn" — the warning scrolls away and the credential does not. | +| 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. | **Failures after work has started — nothing rolls back:** @@ -848,9 +945,9 @@ elsewhere: the directory is seconds old and contains nothing the developer autho | `create-next-app` fails, is unreachable, or rejects a flag | Report its output and **name the target as partially populated and not resumable**. Do not delete it — it is the developer's directory and it may hold their evidence. Print inspect-and-restart instructions: review what is there, then remove it (or pick a new name) and re-run the command. **Do not print "two commands that finish the job by hand"** — see below. | | `create-next-app` changes its flag surface or generated layout | The **exact** pinned version (§7 step 2) means an upstream change cannot reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. A major-range pin would not hold that. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | | The pinned `create-next-app` falls behind | New projects start on an older Next than current. Bumping the pin is scheduled maintenance gated on a goal-check run, not a reaction to breakage. | -| The install fails after the template was written | The scaffold stays and is **finishable**: every file and every edit is already on disk, so the developer's own package-manager install completes it. Report the manager's own output and print that command against that directory. | -| The `AGENTS.md` append fails (unwritable, or the file vanished) | The scaffold stays and is usable — this is the one job whose absence costs the developer nothing that stops the app running. Report it and print the next-steps block anyway, naming the section as not added. | -| `-y` with no key in flags or 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. | +| The install fails (step 6) | The scaffold stays and is **genuinely finishable**: the six template files, all four changes, the `AGENTS.md` section and the key are already on disk, so the developer's own package-manager install is the *only* thing outstanding and it completes the project. Report the manager's own output and print that command against that directory. **This row is why the append is step 4** — it was step 5's last item in an earlier revision, so it had not run when the install failed, and an install cannot restore canonical text (§7). | +| The `AGENTS.md` append fails (step 4 — unwritable, or the file vanished) | The scaffold stays and is usable: this is the one job whose absence stops nothing from running. Continue to the remaining steps rather than aborting, and name the section as not added in the summary. **Do not** print instructions to paste the block by hand — it is canonical text this package embeds, and a hand copy is exactly the drift theme 9 exists to prevent; point at the docs page instead. | +| `-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. | @@ -859,12 +956,20 @@ elsewhere: the directory is seconds old and contains nothing the developer autho it.** Refusals happen before anything is created and leave the disk untouched. The credential stop happens after the scaffold exists and leaves it there, minus the key. Failures leave a directory the developer can **inspect** — and only some of them leave one that can be *finished*. -**A failed install can**: the six template files and all four edits are already on disk, so the -developer's own install command against that directory completes it. **A failed `create-next-app` +**A failed install can**: the six template files, all four changes, the `AGENTS.md` section and the +key are already on disk, so the developer's own install command against that directory completes +it. **A failed `create-next-app` cannot**: the target is partly populated by a tool we do not control, step 1 refuses a non-empty target, nothing else of ours authors the template, and brownfield is a non-goal — so there the instruction is inspect and restart (§9). Promising "finish by hand" across both is the -contradiction this taxonomy used to carry. Nothing is ever cleaned up behind the +contradiction this taxonomy used to carry. + +**"Finishable" is a claim about ordering, and it has to be re-checked whenever a step moves.** It +held only because every deterministic write precedes the fallible install; an earlier revision put +the `AGENTS.md` append after it and the word silently became false. The general form is in §7's +recovery table: *for each step, ask what the printed recovery actually restores* — and recovery +instructions that ask the developer to reproduce canonical text do not count, because the whole +point of a single authored source is that nobody hand-copies it. Nothing is ever cleaned up behind the user, because deleting a directory a stranger may have put something in is worse than leaving one they can `rm` — which is also why the credential stop does not "undo" the scaffold to qualify as a refusal. @@ -877,12 +982,16 @@ every part of it, including the five jobs an earlier draft had disclaimed). Reco three more per additional template if decision 2 is overturned. That count is the real cost the ask above is pricing: it is per template *times* per provider, not per template: -- In an **empty directory, with no provider key in the environment**, run the published - invocation, supply the key at its prompt, then run the printed dev command and send a message - in the browser: a streamed model response renders in the page — and **renders - incrementally**, token by token, not as one block when the response completes. The second half - is the only check anywhere that would catch a missing `force-dynamic`; everything else passes - with a buffered body. +- In an **empty directory, with no provider key in the environment**, run the published invocation + **interactively — without `-y`** — and supply the key at its prompt. Then run the printed dev + command and send a message in the browser: a streamed model response renders in the page — and + **renders incrementally**, token by token, not as one block when the response completes. The + second half is the only check anywhere that would catch a missing `force-dynamic`; everything + else passes with a buffered body. + *The `-y` in §5's non-interactive example is CI's, not this run's.* There is no key flag (§5), + so `-y` here would suppress the prompt, leave the provider variable empty, and make the streamed + response impossible — **a check that could not pass**, which is the same defect as a check that + cannot fail and is called out as such below. - **Through the mounted route, not through `fsdev run`.** The CLI runs in-process and resolves providers through a path that works there, so a CLI-only check passes with the product's actual path broken. Decision 5's static wiring is what *prevents* that failure; this check is what @@ -1018,6 +1127,10 @@ my-app` is the advertised UX; the pnpm run beside it is what makes that one safe - **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the message naming the floor, and an untouched target directory. Without it the failure moves to every printed `fsdev` command, after a project exists (decision 4) +- **the `AGENTS.md` section is on disk before the install runs** — asserted on ordering, because + this is what makes §9's "finishable" promise true rather than merely stated. A test on end state + cannot see it: a run that appended afterwards leaves an identical directory on the *success* + path, and the difference only appears when the install fails - **every printed command runs** — execute the strings the block emitted, in the generated project, and assert the process starts. This is where npm's `--` separator is caught. **The stubbed form of this check cannot see a missing dependency** (nothing is installed), which is why @@ -1036,6 +1149,19 @@ real network, real `create-next-app`, real model, real browser — and are never suite. The three *real* CI specs scaffold once and are the slowest thing in the suite; they earn it, because everything else in the list would pass against a template that does not compile. +**One defect class, two directions — read them together, because meeting them apart is what let +both through.** Nearly every finding against this spec and its POC has been *a check that cannot +fail the claim it is cited for*: a marker count that survives a truncated section, a green result +from an npm install hiding a manifest missing `@flow-state-dev/engine`, a control exercised only on +the path it protects. The goal check's `-y` was the **mirror image** — *a check that cannot pass*, +because the run it specified suppressed the key prompt the same run needed answered. **They are the +same defect.** In both, the check's outcome is decoupled from the thing it claims to measure, so it +reports a constant. The test is one question asked in both directions: **name the scenario where +this check comes out the other way, and confirm that scenario is reachable.** If nothing makes it +fail, it proves nothing; if nothing makes it pass, it is not a check but an obstacle. Recorded here +rather than in a review thread because a reader who meets these separately files them as unrelated +mistakes and re-derives the lesson each time. + **Discipline:** `tdd`. The seam is the pipeline against a temporary directory with `create-next-app` and the package-manager install stubbed. @@ -1277,8 +1403,11 @@ Nothing else. **Follow-ups (flagged, not built):** -- **The `node-api` template**, if decision 2 goes the other way later. Additive; arrives with - the `--template` flag (decision 2b). +- **The `node-api` template**, if decision 2 goes the other way — now or later. **Additive in the + sense that it breaks no invocation and strands nobody, *not* in the sense that it is a small + change here**: decision 2 enumerates what it needs beyond the files (a scaffolder step, its own + change list, its own security posture, its own verification path, the `--template` flag), and it + is a specification round on this issue rather than a directory. - **A bare-path handler in `@flow-state-dev/next`**, matching `createVercelBareHandler`. Would turn one hand-written template file into a one-liner. FIX-1159 flags the same gap. - **Should the production refusal live in the framework rather than in generated code?** Decision @@ -1530,3 +1659,27 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions deliberately, because `npm create flow-state my-app` is the advertised UX; what makes that safe is the pnpm run standing beside it, not the npm run itself. Nothing in the reverse direction exists — pnpm is the stricter resolver, so no check here passes under pnpm and fails under npm. + +- **Three more, and two were introduced by the round that fixed the last three.** *(1)* Step 5 + ordered the install **before** the `AGENTS.md` append, so when the install failed the append had + never run — and §9's recovery, an install command, could not restore it. **The "finishable + scaffold" promise was false in exactly the case it exists for**, and the same hole sat under the + credential stop, which precedes both. Fixed by ordering rather than by a longer error message: + every deterministic write is now steps 3–4, ahead of the two fallible steps, and §7 carries the + rule as a table — *for each step, ask what the printed recovery actually restores*, with recovery + instructions that ask the developer to reproduce canonical text explicitly not counting. + *(2)* §5 labelled the `-y` invocation as "how the goal check and CI run it" while §10 required a + real streamed response from a key typed at the prompt. `-y` suppresses that prompt and there is + no key flag — deliberately, since a secret on argv lands in shell history — so **the goal check + as written could not pass.** It now runs interactively; CI keeps `-y`, because the empty-key path + is what CI asserts. **This is the mirror of the class that has dominated every other round**: a + check that cannot pass and a check that cannot fail are the same defect, and §10 now says so once + rather than leaving a reader to meet them as unrelated mistakes. + *(3)* Decision 2 claimed shipping both starters would change only `templates//`. It would + not — the pipeline spawns `create-next-app` unconditionally, three of its four scaffolder-file + changes are Next keys, decision 8's control is a Next script value, and the proof is a browser on + a mounted route. **That claim under-priced the fallback this spec's own ask recommends.** Decision + 2 now enumerates what the branch would need, and the ask states plainly that choosing it buys + another specification round here. Q6 is *not* moved in front of approval: approving this document + approves the one-starter spec, blocking on Q6 buys nothing because neither answer is buildable + until it is settled, and the recommended answer incurs none of the added cost. From 4a400d057058cb21519e7172307f7e6ccfb8b9ef Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 00:46:36 +0000 Subject: [PATCH 20/30] spec(FIX-548): put the transcript summary in execution order MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Residual from the step reorder: the summary listed .env.local before AGENTS.md while the append is now step 4 and the credential stop step 5. Grouping by verb reads fine and quietly misdescribes the ordering §9's recovery promise rests on. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 432393de0f..3e657aa77a 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -576,8 +576,8 @@ $ npm create flow-state my-app Updated package.json ("type": "module"; dev and start bound to 127.0.0.1) tsconfig.json (allowImportingTsExtensions) app/page.tsx (replaced — the stock Next.js page) - Wrote .env.local (OPENAI_API_KEY, already ignored by git) Appended AGENTS.md (FSD section) + Wrote .env.local (OPENAI_API_KEY, already ignored by git) Installed via npm Next steps @@ -618,6 +618,10 @@ watch us create — which is what the report is for. 8 lands, and the epic's goal check for this issue **compares the run's report against the actual diff**. A transcript is a promise that check reads. +**The summary's lines are in execution order**, which is why `AGENTS.md` precedes `.env.local`: +the append is step 4 and the credential stop is step 5 (§7). Grouping by verb instead would read +fine and quietly misdescribe the ordering that §9's recovery promise depends on. + Three details in the block are load-bearing rather than cosmetic: - **`npm exec` needs the `--` separator** or npm consumes `--input` as its own configuration and From b0b57541bb5c061a2e8b1f2018acdd693cc59095 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 00:53:12 +0000 Subject: [PATCH 21/30] spec(FIX-548): make a failed AGENTS.md append stop the run, and correct the product statement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex P2 on 4a400d0, confirmed. The reorder last round fixed a step that had not run yet; it said nothing about a step that ran and failed, and §9 explicitly let the append fail and continue. Both recovery promises beneath it then asserted the section was on disk, so both were false on a path this document described. The append is now a stopping failure, which keeps every later promise unconditional rather than conditioning five messages on whether step 4 worked. §9 puts it beside create-next-app as the second non-finishable failure, since the only thing that would complete it is canonical text nobody may hand-copy. The ordering assertion could not have caught this — "the append ran before the install" stays green when the append ran and failed. §10 now asserts the stop directly, and records the attempted-vs-succeeded gap as the fourth instance of the check-cannot-fail class. Separately: the product statement in decision 8 was false in two directions and it was mine. A hardcoded loopback bind is not in a platform deploy's path, and the control is the flow's production refusal rather than a bind — which the old wording mis-attributed and made sound like a permanent restriction on where the app may run. Replaced with the corrected wording verbatim. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 182 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 142 insertions(+), 40 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 3e657aa77a..3a8e245246 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -386,10 +386,29 @@ every addition): §6 is mostly about keeping the file list short and refusing su brownfield. §5's transcript reports the change and §10 asserts it, because a `scripts` edit would otherwise read as a violation of the additive guarantee. - *This is a product statement, not a footnote:* **the generated app does not serve off-host - until its authentication is configured.** For a demo scaffold that is the right default, and - the owner should see it as a promise about what the thing does rather than as an - implementation note. + *This is a product statement, not a footnote — and it is the wording to use, because a looser + one was wrong twice:* + + > **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.** + + *An earlier revision of this spec, and the PR description built from it, said instead that the + app "does not serve off-host until authentication is configured — on every path the template + ships and every mainstream deploy."* **That is false in two directions at once**, and both + matter for what the owner is being asked to approve: + - **It promises more than the mechanism can deliver.** A hardcoded `--hostname 127.0.0.1` in a + `package.json` script is not in the path of a platform deploy at all, so no bind of ours + governs "off-host" there. + - **It describes the wrong control, and thereby understates the product.** The thing that + protects a deployed app is the flow's **refusal to serve in production without + authentication**, not a bind — and once the developer configures authentication the app is + meant to serve off-host normally. The old wording reads as though the scaffold permanently + restricts where the app can run, which would be a worse product than the one being specified. + + For a demo scaffold this is the right default, and the owner should see it as a promise about + what the thing does rather than as an implementation note. **Non-goals** — **authoring** any of the shared text or shapes: the agent-instructions block's content (FIX-1160 authors it; this package places it verbatim), the next-steps block's content @@ -686,9 +705,10 @@ flowchart TB F --> G[7 · print next steps
FIX-1159's block, verbatim] ``` -*Every deterministic local write is steps 3–4, before the two steps that can fail (5 and 6), so a -failure leaves a project the printed recovery genuinely completes. The table below step 7 says what -each recovery restores.* +*Every deterministic local write is steps 3–4, before the two steps whose failure is **recoverable** +(5 and 6), so either of those leaves a project the printed recovery genuinely completes. Steps 2 and +4 can fail too, and neither is recoverable — both stop the run with inspect-and-restart. The table +below step 7 says what each recovery restores, including the ones that restore nothing.* **Step 1 — resolve the invocation.** Flags first, prompts for whatever is missing, `-y` to take defaults for everything unflagged. Validation (project name is a legal npm package name, target @@ -802,6 +822,26 @@ own `AGENTS.md` (and a `CLAUDE.md`), so this **appends** — it never creates, a Next's own delimited block. The section's text is **FIX-1160's canonical block, embedded verbatim** in this package's source. +**If the append fails, the run stops here** (§9). It does not continue and report the section as +missing. Two reasons, and the second is the one that decides it: + +- **The environment is already broken.** The only ways this fails are a filesystem refusing a write + to a file that exists in a directory this command created seconds ago — permissions, a full disk, + the file removed mid-run. The next two steps write a credential and unpack a dependency tree into + the same directory. Continuing past this is optimism, not resilience. +- **Continuing makes every downstream recovery message conditional, and the conditions are what + went wrong last time.** If the run proceeds, then the credential stop's recovery and the install + failure's recovery each have to know whether step 4 succeeded and say something different if it + did not. That is state threaded through five messages, each of which is a promise about what is + on disk. **Stopping keeps every later promise unconditionally true**, which is what makes them + assertable at all. + +*Restart is cheap here in the way it is for `create-next-app` and not otherwise:* the directory is +seconds old, holds nothing the developer authored, and a fresh run produces a complete project. And +the section is not decoration — the epic's second clause is that a coding assistant writes FSD code +that runs, so a scaffold that silently omits it fails half the objective quietly. Failing loudly is +the smaller cost. + **Step 5 — the credential stop.** Before `.env.local` is written, ask **git** whether it would ignore that exact path (`git check-ignore`). In a fresh `create-next-app` scaffold the answer is already yes (verified by the POC), so this is normally an assertion rather than a write. If it is @@ -816,16 +856,26 @@ place, because the package manager reads that file and rewrites it. **Step 7 — print the next-steps block.** **FIX-1159's canonical block, embedded verbatim**, rendered for the resolved package manager and the `mounted-route` topology. -**Every deterministic local write happens before the two steps that can fail, and that ordering -is a promise §9 makes rather than a preference.** The rule: *for each step, ask what the printed -recovery actually restores.* Applied here, it moved the `AGENTS.md` append from last to fourth. +**Every deterministic local write happens before the two steps whose failure is recoverable, and +that ordering is a promise §9 makes rather than a preference.** The rule: *for each step, ask what +the printed recovery actually restores.* Applied here, it moved the `AGENTS.md` append from last to +fourth — and then, applied a second time to the append's **own** failure, made that failure a stop. -| fallible step | what is already on disk when it fails | what the printed recovery restores | +| fallible step | what is on disk when it fails | what the printed recovery restores | |---|---|---| | step 2, `create-next-app` | nothing of ours | nothing — the target is somebody else's partial output, so the instruction is inspect and restart (§9) | -| step 5, the credential stop | the six template files, all four changes, **and the `AGENTS.md` section** | the developer adds the ignore line, writes the key, and installs — three named steps, and nothing is missing that they would have to author | +| **step 4, the `AGENTS.md` append** | the six template files and all four changes; **no key, no dependencies** | nothing, and it does not try — **the run stops**, so there is no recovery message making a claim about a section that is not there | +| step 5, the credential stop | everything above **and the `AGENTS.md` section, because step 4 succeeded or the run ended** | the developer adds the ignore line, writes the key, and installs — three named steps, nothing missing that they would have to author | | step 6, the install | everything above, plus the key | `npm install` in that directory. **Exactly the promise §9 makes** | +**The middle row is what makes the two below it unconditional**, and it is worth saying why the +table needed a second pass. An earlier revision let step 4 fail and continue. The rows beneath then +read "the `AGENTS.md` section is on disk" while §9 explicitly permitted a run where it was not — so +both recovery promises were false on a path the spec itself described. **The ordering fix addressed +a step that had not run yet; it said nothing about a step that ran and failed.** Same rule, second +application, and the rule only holds when it is applied to every step rather than to the one that +was reported. + *An earlier revision ran the install first and appended `AGENTS.md` last. A failed install then left a project missing the agent-instructions section, and the recovery command — an install — could not restore it: the only text that would have completed it is canonical content this package embeds and @@ -885,9 +935,12 @@ package generates a project; it changes no framework behaviour. *Depends on:* nothing. 4. **The `AGENTS.md` append** — FIX-1160's canonical block embedded verbatim and appended, never creating the file and never touching Next's own delimited block. **Sequenced here, before the - two fallible steps, so a later failure leaves nothing the developer would have to author** - (§7). *Test:* normalized equality against canonical via FIX-1160's exported comparison, every - branch included; Next's own block and `CLAUDE.md` intact byte-for-byte afterwards. + two recoverable-failure steps, so a later failure leaves nothing the developer would have to + author — and it stops the run if it fails itself**, since every promise below it asserts the + section is on disk (§7). + *Test:* normalized equality against canonical via FIX-1160's exported comparison, every branch + included; Next's own block and `CLAUDE.md` intact byte-for-byte afterwards; **and the failure + path — an injected write error exits non-zero with no `.env.local` and no install.** *Depends on:* 2, **and FIX-1160's block existing** — see §12. 5. **The credential stop** — `git check-ignore` against `.env.local`, the append-and-re-verify path, the stop, then the key write. *Test:* the ordering (the check precedes the write, @@ -949,8 +1002,8 @@ elsewhere: the directory is seconds old and contains nothing the developer autho | `create-next-app` fails, is unreachable, or rejects a flag | Report its output and **name the target as partially populated and not resumable**. Do not delete it — it is the developer's directory and it may hold their evidence. Print inspect-and-restart instructions: review what is there, then remove it (or pick a new name) and re-run the command. **Do not print "two commands that finish the job by hand"** — see below. | | `create-next-app` changes its flag surface or generated layout | The **exact** pinned version (§7 step 2) means an upstream change cannot reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. A major-range pin would not hold that. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | | The pinned `create-next-app` falls behind | New projects start on an older Next than current. Bumping the pin is scheduled maintenance gated on a goal-check run, not a reaction to breakage. | -| The install fails (step 6) | The scaffold stays and is **genuinely finishable**: the six template files, all four changes, the `AGENTS.md` section and the key are already on disk, so the developer's own package-manager install is the *only* thing outstanding and it completes the project. Report the manager's own output and print that command against that directory. **This row is why the append is step 4** — it was step 5's last item in an earlier revision, so it had not run when the install failed, and an install cannot restore canonical text (§7). | -| The `AGENTS.md` append fails (step 4 — unwritable, or the file vanished) | The scaffold stays and is usable: this is the one job whose absence stops nothing from running. Continue to the remaining steps rather than aborting, and name the section as not added in the summary. **Do not** print instructions to paste the block by hand — it is canonical text this package embeds, and a hand copy is exactly the drift theme 9 exists to prevent; point at the docs page instead. | +| The install fails (step 6) | The scaffold stays and is **genuinely finishable**: the six template files, all four changes, the `AGENTS.md` section and the key are already on disk, so the developer's own package-manager install is the *only* thing outstanding and it completes the project. Report the manager's own output and print that command against that directory. **Two earlier revisions made this claim falsely**, and both are why the pipeline reads as it does: the first appended `AGENTS.md` *after* the install, so the section had not been written; the second appended it before but let that append fail and continue, so the section might not exist. The claim holds now because step 4 precedes this **and** a failed step 4 ends the run (§7). | +| The `AGENTS.md` append fails (step 4 — unwritable, or the file vanished) | **Stop. Do not continue to the credential stop or the install.** Report the write error and give inspect-and-restart guidance: review the directory, then remove it (or pick a new name) and re-run. No key has been written and nothing has been installed, so there is nothing to clean up beyond the directory itself. **Do not** print instructions to paste the block by hand — it is canonical text this package embeds, and a hand copy is exactly the drift theme 9 exists to prevent. *An earlier revision continued past this and named the section as not added; that made the two recovery promises below it false, because both assert the section is on disk (§7).* | | `-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. | @@ -962,18 +1015,24 @@ stop happens after the scaffold exists and leaves it there, minus the key. Failu directory the developer can **inspect** — and only some of them leave one that can be *finished*. **A failed install can**: the six template files, all four changes, the `AGENTS.md` section and the key are already on disk, so the developer's own install command against that directory completes -it. **A failed `create-next-app` -cannot**: the target is partly populated by a tool we do not control, step 1 refuses a non-empty -target, nothing else of ours authors the template, and brownfield is a non-goal — so there the -instruction is inspect and restart (§9). Promising "finish by hand" across both is the -contradiction this taxonomy used to carry. - -**"Finishable" is a claim about ordering, and it has to be re-checked whenever a step moves.** It -held only because every deterministic write precedes the fallible install; an earlier revision put -the `AGENTS.md` append after it and the word silently became false. The general form is in §7's -recovery table: *for each step, ask what the printed recovery actually restores* — and recovery -instructions that ask the developer to reproduce canonical text do not count, because the whole -point of a single authored source is that nobody hand-copies it. Nothing is ever cleaned up behind the +it. **Two failures cannot, and both end in inspect-and-restart.** A failed `create-next-app`: the +target is partly populated by a tool we do not control, step 1 refuses a non-empty target, nothing +else of ours authors the template, and brownfield is a non-goal. **A failed `AGENTS.md` append**: +the only thing that would complete it is canonical text this package embeds and the developer +cannot be asked to reproduce, so there is no instruction to give that would work. Promising "finish +by hand" across these is the contradiction this taxonomy used to carry. + +**"Finishable" is a claim about what is on disk, and it broke twice in two different ways.** First +on **ordering** — an earlier revision put the `AGENTS.md` append after the install, so the section +had not been written when the install failed. Then on **outcome** — the append was moved earlier +but allowed to fail and continue, so the section might not be there even though its step had run. +The second is not a variant of the first: fixing the order says nothing about a step that ran and +failed, which is why the same rule had to be applied twice. It is in §7's recovery table: *for each +step, ask what the printed recovery actually restores* — with two clauses this pair added. Recovery +that asks the developer to reproduce canonical text does not count, because the point of a single +authored source is that nobody hand-copies it. And **a step whose failure would falsify a later +promise is a stopping step**, because the alternative is conditioning every later message on it. +Nothing is ever cleaned up behind the user, because deleting a directory a stranger may have put something in is worse than leaving one they can `rm` — which is also why the credential stop does not "undo" the scaffold to qualify as a refusal. @@ -1135,6 +1194,13 @@ my-app` is the advertised UX; the pnpm run beside it is what makes that one safe this is what makes §9's "finishable" promise true rather than merely stated. A test on end state cannot see it: a run that appended afterwards leaves an identical directory on the *success* path, and the difference only appears when the install fails +- **a failing `AGENTS.md` append stops the run** — inject a write failure at step 4 and assert the + process exits non-zero, that **no `.env.local` exists**, and that **no lockfile or `node_modules` + exists**. **This is the assertion the previous revision could not make.** The ordering check + above establishes that the append was *attempted* first; on its own it stays green on a run where + the append was attempted, failed, and execution carried on to make §7's recovery promises false. + *Attempted is not succeeded, and a check that cannot tell them apart cannot fail on the path it + is cited for* — the same class as the four other findings §10 collects below - **every printed command runs** — execute the strings the block emitted, in the generated project, and assert the process starts. This is where npm's `--` separator is caught. **The stubbed form of this check cannot see a missing dependency** (nothing is installed), which is why @@ -1154,17 +1220,28 @@ suite. The three *real* CI specs scaffold once and are the slowest thing in the it, because everything else in the list would pass against a template that does not compile. **One defect class, two directions — read them together, because meeting them apart is what let -both through.** Nearly every finding against this spec and its POC has been *a check that cannot -fail the claim it is cited for*: a marker count that survives a truncated section, a green result -from an npm install hiding a manifest missing `@flow-state-dev/engine`, a control exercised only on -the path it protects. The goal check's `-y` was the **mirror image** — *a check that cannot pass*, -because the run it specified suppressed the key prompt the same run needed answered. **They are the -same defect.** In both, the check's outcome is decoupled from the thing it claims to measure, so it -reports a constant. The test is one question asked in both directions: **name the scenario where -this check comes out the other way, and confirm that scenario is reachable.** If nothing makes it -fail, it proves nothing; if nothing makes it pass, it is not a check but an obstacle. Recorded here -rather than in a review thread because a reader who meets these separately files them as unrelated -mistakes and re-derives the lesson each time. +each one through.** Nearly every finding against this spec and its POC has been *a check that +cannot fail the claim it is cited for*: + +- a marker count that survives a section truncated after its sentinel; +- a green npm install hiding a manifest missing `@flow-state-dev/engine`; +- a control exercised only on the path it protects; +- **an ordering assertion that reads "the append ran before the install" and therefore stays green + on a run where the append ran, *failed*, and execution continued** — *attempted is not + succeeded*, and that gap is the whole distance between a true recovery promise and a false one. + +The goal check's `-y` was the **mirror image** — *a check that cannot pass*, because the run it +specified suppressed the key prompt the same run needed answered. **They are the same defect.** In +both, the check's outcome is decoupled from the thing it claims to measure, so it reports a +constant. + +The test is one question asked in both directions: **name the scenario where this check comes out +the other way, and confirm that scenario is reachable.** If nothing makes it fail, it proves +nothing; if nothing makes it pass, it is not a check but an obstacle. **The fourth item above is +the one that shows why the question has to be asked of the *predicate*, not the intent** — "assert +the ordering" sounds like it covers the failure path, and it does not; only "assert the run stops" +does. Recorded here rather than in a review thread because a reader who meets these separately +files them as unrelated mistakes and re-derives the lesson each time. **Discipline:** `tdd`. The seam is the pipeline against a temporary directory with `create-next-app` and the package-manager install stubbed. @@ -1687,3 +1764,28 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions another specification round here. Q6 is *not* moved in front of approval: approving this document approves the one-starter spec, blocking on Q6 buys nothing because neither answer is buildable until it is settled, and the recommended answer incurs none of the added cost. + +- **The recovery rule, applied a second time — to the step that carries it.** The reorder fixed a + step that had *not run yet* when a later one failed. It said nothing about a step that **ran and + failed**, and §9 explicitly permitted exactly that: the `AGENTS.md` append was allowed to fail + and continue. So both promises beneath it — the credential stop's recovery and the install + failure's *"the install is the only thing outstanding"* — were false on a path this document + itself described. **The append is now a stopping failure**, which keeps every later promise + unconditional instead of conditioning five messages on whether step 4 worked; §9 puts it beside + `create-next-app` as the second failure that ends in inspect-and-restart, since the only thing + that would complete it is canonical text nobody may hand-copy. + **And the assertion could not have caught it**: "the append ran before the install" is green on a + run where the append ran, failed, and execution carried on. *Attempted is not succeeded.* §10 now + asserts the **stop** — an injected write error exits non-zero with no `.env.local` and no install + — and the fourth bullet of its defect-class list is this case, because it is the one that shows + the question has to be asked of the predicate rather than of the intent. +- **The product statement was false in two directions, and it was mine.** This spec, and the PR + description built from it, said the generated app *"does not serve off-host until authentication + is configured — on every path the template ships and every mainstream deploy."* A hardcoded + loopback bind in a `package.json` script is not in a platform deploy's path at all, so it cannot + deliver that; **and the control that does the work is the flow's production refusal, not a + bind** — which the old wording both mis-attributed and, worse, made sound like a permanent + restriction on where the app may run. Decision 8 now carries the corrected statement verbatim as + the wording to use: the app refuses to serve its demo flow in production until real + authentication is configured, serves normally anywhere once it is, and separately binds to the + local machine in development as a default the developer can change in one word. From dce7a2611f3161dec76d6b2c6bffaf6d4f6bea14 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 00:58:12 +0000 Subject: [PATCH 22/30] spec(FIX-548): add the step that writes the dependencies, block sub-PR a, and fix the probe's false disproof MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four findings on 4a400d0 as one round; the pattern across them is recorded in §13. P1: the dependency set was listed in §7 with no step that wrote it. Step 3's change table is exhaustive and has no dependency edit, create-next-app skips its install, and a bare install resolves only the manifest it is given — so every FSD, provider, CLI and DevTool import would have been unresolved, and the pnpm-isolated install cited as proof was specified against a manifest nobody authored. Step 6 is now a package-manager `add` with the derived list, which writes and resolves in one operation and keeps decision 4's exception at one key. Recovery and summary contracts move with it: the printed recovery is the add command, never a bare install. P2: sub-PR a listed no prerequisites while embedding FIX-1159's and FIX-1160's canonical blocks, so it could have merged before either existed. Table now names both. Blocking set stated as those two only — FIX-1162 is not a blocker and its Linear edge is gone. P2: probe.sh discarded git init's status, reporting the ignore claim as disproved when it could not be tested. Freeze lifted deliberately for this one fix and put back, with the reasoning recorded in the POC README: the rule covers over-assertion, and this was under-reporting in the direction that cannot be documented away. §10 now names a third direction of the defect class — a check that fails for the wrong reason — since a wrongly-red check hides every defect it would have caught rather than one. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 23 +++ spec-poc/FIX-548-next-template-shape/probe.sh | 6 +- spec/FIX-548.md | 173 +++++++++++++++--- 3 files changed, 176 insertions(+), 26 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index b14c2479d9..1e46153d25 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -49,6 +49,29 @@ more than its job requires. The cheapest way to end that loop is to stop claimin is the same move that closed round 3 — and unlike growing the script, it cannot introduce a new check that fails for its own reasons. +**The freeze was lifted once, deliberately, and this is the record of it.** A review found that +`git init` discarded its exit status before the `.gitignore` check, so a machine where git is +missing or init fails would fall through to `fail` and report **exit 1 — the ignore claim +disproved** — when the truth was that it could not be tested. The scaffold runs with +`--disable-git`, so that environment is independently reachable. + +That was fixed in the script rather than narrowed in this README, and the distinction is the +reason the rule survives intact: + +- **The rule covers over-assertion.** A probe claiming more than it proves is answered by moving + the claim into *What this POC does not establish*. Every round the freeze was written for was + that shape. +- **This was under-reporting, in the one direction that cannot be documented away.** Narrowing the + README here would mean writing "if the ignore check exits 1, it might instead mean git failed" — + which does not remove the false disproof, it teaches the reader to distrust exit 1 *everywhere* + in this script. A red result nobody believes is worse than no check. +- **The fix added no assertion surface.** It routes one already-existing failure mode into the + `2` the script already uses in ten other places. It closes a gap in this contract rather than + extending it. + +**The freeze is back on**, unchanged, with one clause added by the case: a finding that the script +reports a *true* claim as **disproved** is fixed in the script; everything else is narrowed here. + Exit status: `0` every asserted claim held · `1` one of them did not · `2` the run could not be completed (scaffold or install failed, no free port, workdir occupied, dev server never bound, a request that never completed). The `1`/`2` split is load-bearing: a machine too slow to have diff --git a/spec-poc/FIX-548-next-template-shape/probe.sh b/spec-poc/FIX-548-next-template-shape/probe.sh index e17f0b6ae1..3b16256454 100644 --- a/spec-poc/FIX-548-next-template-shape/probe.sh +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -77,7 +77,11 @@ grep -q 'BEGIN:nextjs-agent-rules' AGENTS.md 2>/dev/null \ # scaffold runs with --disable-git, so init a throwaway repo just to evaluate the # rules. check-ignore works on a path that does not exist yet, which is the state # the real command is in when it decides whether it may write the key. -git init -q . 2>/dev/null +# If git itself is unavailable or init fails, this claim CANNOT BE TESTED — it is +# not disproved. Without this guard the check-ignore below falls through to +# `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 echo " .gitignore: git would ignore .env.local ($(git check-ignore -v .env.local | awk '{print $1":"$2}'))" else diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 3a8e245246..3b6c6b9dd1 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -597,7 +597,7 @@ $ npm create flow-state my-app app/page.tsx (replaced — the stock Next.js page) Appended AGENTS.md (FSD section) Wrote .env.local (OPENAI_API_KEY, already ignored by git) - Installed via npm + Added 7 dependencies via npm (@flow-state-dev/*, @ai-sdk/openai, zod) Next steps @@ -701,7 +701,7 @@ flowchart TB B --> C[3 · write the template
6 files · + 4 changes to files create-next-app wrote] C --> D[4 · append AGENTS.md section
FIX-1160's block, verbatim] D --> E[5 · credential stop
git check-ignore .env.local, then write the key] - E --> F[6 · install
resolved package manager] + E --> F[6 · add the dependencies
package manager add — writes the entries and resolves them] F --> G[7 · print next steps
FIX-1159's block, verbatim] ``` @@ -849,9 +849,34 @@ not, append the rule and re-verify; if it still cannot be established, **stop be written** (§9). Only then write `.env.local` with the chosen provider's variable name and the value collected in step 1. -**Step 6 — install.** Run the resolved package manager's install in the target directory. One -manager, one lockfile. The manifest's `"type": "module"` and its dependency set must already be in -place, because the package manager reads that file and rewrites it. +**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 …`, `pnpm add …`, `yarn add …`, `bun add …`. **This is the +step that writes the dependency entries into `package.json`**, and it resolves them in the same +operation. One manager, one lockfile. + +*This step exists because the previous revision did not have one, and the gap is worth naming +rather than quietly closing.* The dependency set was added to §7 in response to a review finding +that `@flow-state-dev/engine` was missing from it — but **a list is not a step**. Step 3's change +table is exhaustive and contains no dependency edit; `create-next-app` runs with its install +skipped; and a bare install resolves only the manifest it was given. So every FSD, provider, CLI +and DevTool import in the generated project would have been unresolved, and the check that would +have caught it — the pnpm-isolated install — was itself specified against a manifest nobody wrote. +**A requirement recorded in one section and enforced by no step is not a requirement**, which is +the same shape as the FIX-1160 edge two rounds earlier. + +**Why `add` rather than authoring the entries in step 3.** Decision 4 bends the "package manager +owns `package.json`" rule for exactly one key and says so; widening that to the whole dependency +block would mean this package authoring and maintaining a version range for every entry, which is +a second place for the corpus's versions to drift and the thing that rule exists to prevent. +Letting the manager write them keeps the exception at one key, and — because `add` writes and +resolves atomically — there is no intermediate state where the manifest lists a dependency the +lockfile has never seen. + +**The manifest's state when this step runs:** `create-next-app`'s original manifest, plus +`"type": "module"` and the two loopback-narrowed scripts from step 3, and **no FSD dependencies +yet**. This step adds them. Everything step 3 wrote must already be in place, because the manager +reads and rewrites the same file. **Step 7 — print the next-steps block.** **FIX-1159's canonical block, embedded verbatim**, rendered for the resolved package manager and the `mounted-route` topology. @@ -866,7 +891,7 @@ fourth — and then, applied a second time to the append's **own** failure, made | step 2, `create-next-app` | nothing of ours | nothing — the target is somebody else's partial output, so the instruction is inspect and restart (§9) | | **step 4, the `AGENTS.md` append** | the six template files and all four changes; **no key, no dependencies** | nothing, and it does not try — **the run stops**, so there is no recovery message making a claim about a section that is not there | | step 5, the credential stop | everything above **and the `AGENTS.md` section, because step 4 succeeded or the run ended** | the developer adds the ignore line, writes the key, and installs — three named steps, nothing missing that they would have to author | -| step 6, the install | everything above, plus the key | `npm install` in that directory. **Exactly the promise §9 makes** | +| step 6, the dependency add | everything above, plus the key — but **the manifest may or may not yet carry the dependency entries**, since `add` writes and resolves in one operation | **the same `add` command, printed verbatim with its package list**, not a bare install. A bare `npm install` would resolve whatever the manifest happens to hold, which on a failure part-way through is exactly the state we cannot assume | **The middle row is what makes the two below it unconditional**, and it is worth saying why the table needed a second pass. An earlier revision let step 4 fail and continue. The rows beneath then @@ -947,9 +972,14 @@ package generates a project; it changes no framework behaviour. executed rather than read), and the stop leaving a usable scaffold with no key in it — **and with the `AGENTS.md` section already present**, since that is what makes its recovery a list of steps rather than an unrecoverable gap. *Depends on:* 2, 4. -6. **The install** — run the resolved package manager, surface its failure, and print the recovery - that genuinely completes the project. *Test:* the failure path leaves every file and every edit - on disk and prints the install command against that directory. *Depends on:* 3, 5. +6. **The dependency add** — run the resolved package manager's `add` with the derived package list, + surface its failure, and print the recovery that genuinely completes the project. **This is the + step that writes the dependency entries; nothing before it does** (§7). + *Test:* the emitted `add` argv contains every member of the derived set for the provider chosen + — **derived from the generated files and the printed commands, not compared to a fixed list**; + the manifest carries those entries afterwards; and the failure path leaves every file and every + edit on disk and prints **the `add` command with its package list**, not a bare install. + *Depends on:* 3, 5. 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 @@ -960,9 +990,23 @@ package generates a project; it changes no framework behaviour. | sub-PR | deliverables | depends_on | |---|---|---| -| a | the package: invocation surface, bare-app step, the template, the `AGENTS.md` append, the credential stop, the install, and the printed block (steps 1–7) | — | +| a | the package: invocation surface, bare-app step, the template, the `AGENTS.md` append, the credential stop, the dependency add, and the printed block (steps 1–7) | **FIX-1159 and FIX-1160 — both merged** | | b | publish configuration, package README, and the three doc surfaces in §11 (step 8) | a | +**Sub-PR `a`'s prerequisites are issues, not sub-PRs, and the table said `—` until this round.** +That was wrong in the way that matters: `a` embeds FIX-1159's next-steps block and FIX-1160's +agent-instructions block verbatim and invokes each author's exported comparison, so starting or +merging it before those exist means embedding a draft — **recreating exactly the drift the +comparison scheme exists to prevent**, and doing it inside the artifact that ships to npm. §8's +steps 4 and 7 and §12 both carried the edge; the PR table did not, and the PR table is what a +multi-PR run reads. *Third instance this round of a requirement recorded in one section and +enforced by no other.* + +**The live blocking set is exactly FIX-1159 and FIX-1160.** **FIX-1162 is not a blocker** — +decision 1's name is published and held (§12), so nothing here waits on the naming issue by any +route, and the Linear edge that said otherwise has been removed. Linear also carries a closed edge +from **FIX-598**, which is `Done`; it is historical and blocks nothing. + ### 9. Edge cases & error handling **Refusals — before anything is created:** @@ -1002,7 +1046,7 @@ elsewhere: the directory is seconds old and contains nothing the developer autho | `create-next-app` fails, is unreachable, or rejects a flag | Report its output and **name the target as partially populated and not resumable**. Do not delete it — it is the developer's directory and it may hold their evidence. Print inspect-and-restart instructions: review what is there, then remove it (or pick a new name) and re-run the command. **Do not print "two commands that finish the job by hand"** — see below. | | `create-next-app` changes its flag surface or generated layout | The **exact** pinned version (§7 step 2) means an upstream change cannot reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. A major-range pin would not hold that. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | | The pinned `create-next-app` falls behind | New projects start on an older Next than current. Bumping the pin is scheduled maintenance gated on a goal-check run, not a reaction to breakage. | -| The install fails (step 6) | The scaffold stays and is **genuinely finishable**: the six template files, all four changes, the `AGENTS.md` section and the key are already on disk, so the developer's own package-manager install is the *only* thing outstanding and it completes the project. Report the manager's own output and print that command against that directory. **Two earlier revisions made this claim falsely**, and both are why the pipeline reads as it does: the first appended `AGENTS.md` *after* the install, so the section had not been written; the second appended it before but let that append fail and continue, so the section might not exist. The claim holds now because step 4 precedes this **and** a failed step 4 ends the run (§7). | +| The dependency add fails (step 6) | The scaffold stays and is **genuinely finishable**: the six template files, all four changes, the `AGENTS.md` section and the key are already on disk, so dependencies are the *only* thing outstanding. Report the manager's own output and **print the `add` command with its full package list** against that directory — **not a bare install**, which would resolve whatever the manifest currently holds and leave the FSD imports unresolved exactly as this failure did. **Three earlier revisions made the "finishable" claim falsely**, each for a different reason, and together they are why the pipeline reads as it does: the first appended `AGENTS.md` *after* the install; the second appended it before but let that append fail and continue; the third listed the dependencies in §7 with no step that wrote them, so the printed bare install could never have completed the project. | | The `AGENTS.md` append fails (step 4 — unwritable, or the file vanished) | **Stop. Do not continue to the credential stop or the install.** Report the write error and give inspect-and-restart guidance: review the directory, then remove it (or pick a new name) and re-run. No key has been written and nothing has been installed, so there is nothing to clean up beyond the directory itself. **Do not** print instructions to paste the block by hand — it is canonical text this package embeds, and a hand copy is exactly the drift theme 9 exists to prevent. *An earlier revision continued past this and named the section as not added; that made the two recovery promises below it false, because both assert the section is on disk (§7).* | | `-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). | @@ -1013,16 +1057,18 @@ elsewhere: the directory is seconds old and contains nothing the developer autho it.** Refusals happen before anything is created and leave the disk untouched. The credential stop happens after the scaffold exists and leaves it there, minus the key. Failures leave a directory the developer can **inspect** — and only some of them leave one that can be *finished*. -**A failed install can**: the six template files, all four changes, the `AGENTS.md` section and the -key are already on disk, so the developer's own install command against that directory completes -it. **Two failures cannot, and both end in inspect-and-restart.** A failed `create-next-app`: the +**A failed dependency add can**: the six template files, all four changes, the `AGENTS.md` section +and the key are already on disk, so re-running **the printed `add` command with its package list** +completes it. **Two failures cannot, and both end in inspect-and-restart.** A failed `create-next-app`: the target is partly populated by a tool we do not control, step 1 refuses a non-empty target, nothing else of ours authors the template, and brownfield is a non-goal. **A failed `AGENTS.md` append**: the only thing that would complete it is canonical text this package embeds and the developer cannot be asked to reproduce, so there is no instruction to give that would work. Promising "finish by hand" across these is the contradiction this taxonomy used to carry. -**"Finishable" is a claim about what is on disk, and it broke twice in two different ways.** First +**"Finishable" is a claim about what is on disk, and it broke three times in three different +ways** — the third being that the recovery command itself was wrong: a bare install cannot add +dependencies the manifest never carried, so the printed recovery is the `add` command. First on **ordering** — an earlier revision put the `AGENTS.md` append after the install, so the section had not been written when the install failed. Then on **outcome** — the append was moved earlier but allowed to fail and continue, so the section might not be there even though its step had run. @@ -1108,8 +1154,9 @@ ask above is pricing: it is per template *times* per provider, not per template: command fails. **CI specs** (behaviours, not test names) — all against a stubbed `create-next-app` and a stubbed -package-manager install, in a temporary directory, with no network, **except the three marked -*real*, which build a scaffolded project once**. +package-manager invocation (the step-6 `add`, whose argv several of these assert on), in a +temporary directory, with no network, **except the three marked *real*, which build a scaffolded +project once**. **Every check in this suite that installs anything installs with pnpm**, for the reason the goal check gives: npm and Yarn hoist transitives, so an npm-backed check resolves imports the manifest @@ -1190,6 +1237,11 @@ my-app` is the advertised UX; the pnpm run beside it is what makes that one safe - **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the message naming the floor, and an untouched target directory. Without it the failure moves to every printed `fsdev` command, after a project exists (decision 4) +- **the dependency set is actually written, not merely listed** — assert the `add` argv contains + every derived member, and that the generated `package.json` carries those entries afterwards. + **A spec-level list with no step behind it is what this assertion exists to catch**: the previous + revision named the packages in §7 and had no step that wrote them, so the pnpm-isolated install + below was specified against a manifest nobody authored - **the `AGENTS.md` section is on disk before the install runs** — asserted on ordering, because this is what makes §9's "finishable" promise true rather than merely stated. A test on end state cannot see it: a run that appended afterwards leaves an identical directory on the *success* @@ -1235,16 +1287,27 @@ specified suppressed the key prompt the same run needed answered. **They are the both, the check's outcome is decoupled from the thing it claims to measure, so it reports a constant. -The test is one question asked in both directions: **name the scenario where this check comes out -the other way, and confirm that scenario is reachable.** If nothing makes it fail, it proves -nothing; if nothing makes it pass, it is not a check but an obstacle. **The fourth item above is -the one that shows why the question has to be asked of the *predicate*, not the intent** — "assert -the ordering" sounds like it covers the failure path, and it does not; only "assert the run stops" -does. Recorded here rather than in a review thread because a reader who meets these separately -files them as unrelated mistakes and re-derives the lesson each time. +**A third direction, and it is the one that does lasting damage: a check that fails for the wrong +reason.** The POC's `git init` discarded its exit status, so a machine without git reported the +scaffold's ignore rule as **disproved** rather than untested — a false *negative*, where every +other instance here is a false pass. It deserves separate naming because the failure modes are not +symmetric in consequence: a check that wrongly passes hides one defect, while **a check that +wrongly fails teaches people to stop believing red results**, and after that it hides every defect +it would ever have caught. Fixed in the probe rather than documented around it, for exactly that +reason (the POC README records why the freeze was lifted for it). + +The test is one question asked in all three directions: **name the scenario where this check comes +out the other way, and confirm that scenario is reachable — and that the reason it comes out that +way is the reason claimed.** If nothing makes it fail, it proves nothing; if nothing makes it pass, +it is not a check but an obstacle; if it can fail for a reason other than the claim, its red is +noise. **The fourth item above is the one that shows why the question has to be asked of the +*predicate*, not the intent** — "assert the ordering" sounds like it covers the failure path, and +it does not; only "assert the run stops" does. Recorded here rather than in a review thread because +a reader who meets these separately files them as unrelated mistakes and re-derives the lesson each +time. **Discipline:** `tdd`. The seam is the pipeline against a temporary directory with -`create-next-app` and the package-manager install stubbed. +`create-next-app` and the package-manager `add` stubbed. ### 11. Documentation plan @@ -1506,6 +1569,27 @@ Nothing else. Spec-PR feedback recorded rather than folded. These are inputs, not instructions. +**Read this first: the failure mode this document actually has, stated because it will be yours +too.** Four review rounds in a row found real defects, and **three of them were introduced by the +fix for the round before**. They share one shape — *a requirement recorded in one section and +enforced by no other*: + +| round | what was recorded | what enforced it | +|---|---|---| +| the FIX-1160 edge | §12 and two sibling specs named the dependency | nothing — the Linear relation said `related` | +| the dependency set | §7 listed the packages, added in response to a missing one | nothing — no step wrote them, and step 3's change table is exhaustive | +| sub-PR `a`'s prerequisites | §8 and §12 both named FIX-1159 and FIX-1160 | nothing — the PR table said `—`, and the PR table is what a multi-PR run reads | + +**The lesson is not "be more careful."** It is that answering a gap by *adding a statement* feels +like closing it and usually is not: a spec has several places that each look authoritative, and +the one a machine or a person actually executes is often not the one edited. So when you close a +gap during implementation, **name the artifact that will execute the fix** — a step, a test, a +manifest entry, a tracker edge — and not merely the paragraph that describes it. If the answer is +"the spec now says so", the gap is still open. + +The same discipline applies to the checks: §10 collects three directions this has gone wrong +(cannot fail, cannot pass, fails for the wrong reason) and the one question that catches all three. + - **"The one-command promise disagrees with the stopping point"** — codex, on §2. **Closed, not pending.** §2 used to say the command leaves the developer looking at the feature streaming, while §5's transcript ends at the printed `npm run dev` and §10 starts it separately. The epic @@ -1789,3 +1873,42 @@ Spec-PR feedback recorded rather than folded. These are inputs, not instructions the wording to use: the app refuses to serve its demo flow in production until real authentication is configured, serves normally anywhere once it is, and separately binds to the local machine in development as a default the developer can change in one word. + +- **A list is not a step, and that is the third round in a row whose defect was created by the + previous round's fix.** The dependency set was added to §7 after a review found + `@flow-state-dev/engine` missing from it — but **no step wrote it**: step 3's change table is + exhaustive and carries no dependency edit, `create-next-app` runs with its install skipped, and a + bare install resolves only the manifest it is given. Every FSD, provider, CLI and DevTool import + in the generated project would have been unresolved, and the pnpm-isolated install cited as the + proof was specified against a manifest nobody authored. **Step 6 is now a package-manager `add` + with the derived list** — it writes the entries and resolves them in one operation, which keeps + decision 4's exception at one key rather than making this package author and maintain a version + range per dependency. The recovery contracts move with it: the printed recovery is the `add` + command with its package list, never a bare install, which could not add what the manifest never + carried. +- **Sub-PR `a` listed no prerequisites while embedding two other issues' canonical blocks.** §8's + steps 4 and 7 and §12 all carried the FIX-1159 and FIX-1160 edges; the PR table said `—`, and the + PR table is what a multi-PR run reads — so `a` could have started or merged before either + canonical source existed, embedding a draft into the artifact that ships to npm and recreating + the drift the comparison scheme exists to prevent. Fixed, and the blocking set is stated + explicitly as **FIX-1159 and FIX-1160 only**: FIX-1162 is not a blocker now that decision 1's + name is published and held, and Linear's edge to it has been removed. +- **The POC's freeze was lifted once, deliberately, and put back.** `git init` discarded its exit + status, so a machine where git is missing reported the scaffold's ignore rule as **disproved** + rather than untested — and the scaffold runs with `--disable-git`, so that environment is + reachable. This was fixed in the script rather than narrowed in the README, against the standing + rule, because the rule covers **over-assertion** and this was **under-reporting in the one + direction that cannot be documented away**: narrowing here would have meant writing "a red on + this check might not mean what it says", which teaches a reader to distrust every red the script + produces. The fix adds no assertion surface — it routes an existing failure mode into the `2` the + script already uses in ten places. The freeze is back on with one clause added: *a finding that + the script reports a true claim as disproved is fixed in the script; everything else is narrowed + in the README.* §10 records the general form as a third direction of the same defect class, + because a check that wrongly reports failure is worse than one that wrongly passes — it hides + every defect it would ever have caught, not just one. +- **The pattern across these rounds is now §13's opening note**, because it is the thing most + likely to recur during implementation: three of the last four defects were *a requirement + recorded in one section and enforced by no other* — the FIX-1160 edge, the dependency set, and + sub-PR `a`'s prerequisites. Answering a gap by adding a statement feels like closing it and + usually is not, because a spec has several places that each look authoritative and the executed + one is often not the one edited. From d34dfa9e06a672af156e52782aade5f059de5b39 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 01:09:10 +0000 Subject: [PATCH 23/30] spec(FIX-548): withdraw the start narrowing and the production refusal, pin FSD versions, derive the dependency count MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 228 +++++++++++++++++++++++++++++------------------- 1 file changed, 136 insertions(+), 92 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 3b6c6b9dd1..ae98b63a94 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -322,44 +322,55 @@ every addition): §6 is mostly about keeping the file list short and refusing su the one failure a diff review does not catch, because it looks like every other added line. §10 asserts it by running `git check-ignore`, not by reading the file. -8. **The generated project is never reachable off the developer's own machine without - authentication — and the control is the bind, not a credential.** Two parts, both this - template's: - - **`scripts.dev` and `scripts.start` are narrowed to loopback** — `next dev --hostname - 127.0.0.1` and `next start --hostname 127.0.0.1`. The printed commands do not change; the - developer still types `npm run dev`. - - **The demo flow refuses to serve when `process.env.NODE_ENV === "production"`**, on the - default resolver. Declared on the flow itself, so the request is refused **before any model - invocation**, with an error naming the missing authentication. - - **The predicate is `=== "production"`, not "outside development", and the difference is the - whole decision.** `NODE_ENV` is **unset** in an ordinary shell, and the CLI never sets it — - `packages/cli/src/commands/run.ts` contains no `NODE_ENV` assignment, and neither does anything - else under `packages/cli/src`. So a guard reading *refuse unless development* would refuse - **`npm exec -- fsdev run chat send …`, a command this scaffold prints**, on a developer's own - laptop, before any model call. The guard would fire on the scenario it exists to permit. - - *Named because it keeps happening:* state the scenario a guard exists for, then state the - scenario it will actually meet most often, and check they are different. Here they were the - same, and the earlier "outside development" wording is what made it invisible. - - *The codebase has both conventions and this picks one deliberately rather than averaging.* - `packages/engine`'s block-trace default keys on `NODE_ENV !== "production"`; its store-factory - default keys on `=== "development"`. For a guard on the printed path the first is the only one - that works, and it is the one taken. - - *What `=== "production"` costs, stated because it narrows the promise.* It is **fail-open on an - unset variable**. It fires where it matters — `next start` and every mainstream platform deploy - set `NODE_ENV=production`, and §10's negative assertion runs `npm run build && npm start` and is - what proves the mechanism rather than assuming it. It does **not** fire in a hand-rolled host - that runs neither of the template's scripts and leaves `NODE_ENV` unset. That path ships no file - of ours, but the gap is real and is not papered over. - *Rejected for closing it:* having the CLI set `NODE_ENV=development` — that is a change to - `packages/cli`, which §7 declares untouched, and it would alter behaviour for every existing - `fsdev run` caller to fix a generated project. Also rejected: a template-written marker variable - in `.env.local` as the development signal — fail-closed, but it invents a mechanism, adds a - variable to explain in the first five minutes, and breaks on a developer who copies `.env.local` - into a deployment dashboard. +8. **In development the generated app binds to the developer's machine only. What happens on a + *deployed* app is epic §5 Q7's, and this spec no longer answers it.** One part stands; the + second is withdrawn. + - **`scripts.dev` is narrowed to loopback** — `next dev --hostname 127.0.0.1`. The printed + command does not change; the developer still types `npm run dev`. + - **`scripts.start` keeps the value `create-next-app` wrote, byte for byte. It is not narrowed, + and no production refusal ships.** + + **Both halves of that changed this round, and the second is a withdrawal rather than an edit.** + + ***`start` narrowing: withdrawn, and it was actively harmful.*** Epic theme 6 exception (c) now + covers **`dev` only**. Narrowing `start` was tried and struck because *"a platform deploy never + runs `next start`"* is false of Docker, Render, Railway, Fly, Heroku and App Runner — and Next's + `-H` carries **no environment binding**, so `HOST=0.0.0.0` cannot override a hard-coded flag. + The container binds loopback, health checks never connect, and **the app reads as dead**. That + is a worse outcome than the hazard it was aimed at. + + ***The production refusal: not shipped, and the reason is measurement rather than caution.*** A + previous revision had the demo flow refuse when `NODE_ENV === "production"`, described as an + adapter-independent guard that lifts once authentication is configured. **A POC has since run the + real code — `executeServeCommand`, the function `fsdev serve` invokes — and neither property + holds of anything that exists.** What was measured: + + | claim the old wording rested on | what the code does | + |---|---| + | the guard keys on deployment/environment | it keys on the **bind address**; there is no `NODE_ENV` check anywhere on the path | + | it is per-flow, so a correct flow keeps serving | **enforcement is whole-app** — a host resolver plus one inheriting flow refuses everything, naming only the inheriting one | + | configuring authentication lifts it | **no host-level configuration satisfies it.** A host-authenticated app is refused as a **false positive** — with `--allow-unauthenticated` the same app binds and still rejects uncredentialed requests correctly (500 without, 202 with) | + | it protects this template | **it never runs here.** `serve()` does not invoke it; only the CLI does — and the symbol is referenced solely under `packages/node/` and `packages/cli/src/commands/serve.ts`, never in `packages/next` (verified independently of the POC) | + + **So this template has no rail in production, and stating that plainly is the decision.** The + generated app mounts through `createNextHandler` inside the developer's own Next server; nothing + of ours is in that bind path. Whether a rail *should* exist is epic **§5 Q7**, the owner's, and + this spec does not pre-empt it — but the description above is of behaviour that ships today, so + it is true under every answer Q7 can give. + + ***And the product statement is withdrawn.*** Four successive versions of it were false, each + produced the same way — **by deriving behaviour from our own rules rather than measuring it, and + the derivation never once failed loudly.** The epic stopped making one for the same reason. What + replaces it is not a promise but a description, in §12: in development the app binds to the local + machine because we set that default; in production it binds wherever Next binds, because we + changed nothing; and the demo flow accepts any caller, because it is on the framework default + resolver. A developer who wants otherwise configures authentication, which is what the + agent-instructions section is for. + + **What survives, and why it survives Q7's answer whatever it is.** The `dev` bind stands on its + own: its justifying condition never clears, because nobody configures production authentication + and then keeps running `npm run dev`. It is one key, greenfield only, on a stock value we caused + to exist seconds earlier, it only ever *narrows* a bind, and it reverts in one word. *Rejected:* **a credential, which is what protects the brownfield path.** It cannot work here and the reason is the client, not the effort: the chat page is a client component using @@ -369,46 +380,19 @@ every addition): §6 is mostly about keeping the file list short and refusing su `npm run dev -- --hostname 127.0.0.1` in the next-steps block, which leaves the plain `npm run dev` that `create-next-app` itself advertises live and exposed; and a second script under a key we own, which does the same and puts two dev commands in a four-second-old project. - *Locks in:* `next dev` **and** `next start` default to `0.0.0.0`, and this template never goes - through `@flow-state-dev/node`, so the loopback rail - `docs/architecture/authentication.md` names as the protection for default-resolver apps is not - in the path at all. Without the bind, `npm run dev` puts an unauthenticated flow that calls a - real model on the developer's key onto whatever network they are on. `start` is the worse of - the two — someone running `npm run build && npm start` is by definition not on their laptop. - And binding scripts closes only self-hosting: a platform deploy runs neither script, which is - why the second part exists and is adapter-independent. - - *Rule this bends, deliberately — and it is the epic's exception, not this spec's.* - `scripts.dev` and `scripts.start` are keys `create-next-app` wrote, and theme 6 (b) says every - unowned key keeps its value. Epic **theme 6 exception (c)** carves out exactly these two, for - exactly this path: greenfield only, on keys whose stock value we caused to exist seconds - earlier, an edit that only ever *narrows* a bind and reverts in one word. It does not reach - brownfield. §5's transcript reports the change and §10 asserts it, because a - `scripts` edit would otherwise read as a violation of the additive guarantee. - - *This is a product statement, not a footnote — and it is the wording to use, because a looser - one was wrong twice:* - - > **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.** - - *An earlier revision of this spec, and the PR description built from it, said instead that the - app "does not serve off-host until authentication is configured — on every path the template - ships and every mainstream deploy."* **That is false in two directions at once**, and both - matter for what the owner is being asked to approve: - - **It promises more than the mechanism can deliver.** A hardcoded `--hostname 127.0.0.1` in a - `package.json` script is not in the path of a platform deploy at all, so no bind of ours - governs "off-host" there. - - **It describes the wrong control, and thereby understates the product.** The thing that - protects a deployed app is the flow's **refusal to serve in production without - authentication**, not a bind — and once the developer configures authentication the app is - meant to serve off-host normally. The old wording reads as though the scaffold permanently - restricts where the app can run, which would be a worse product than the one being specified. - - For a demo scaffold this is the right default, and the owner should see it as a promise about - what the thing does rather than as an implementation note. + + *Rule this bends, deliberately — and it is the epic's exception, not this spec's.* `scripts.dev` + is a key `create-next-app` wrote, and theme 6 (b) says every unowned key keeps its value. Epic + **theme 6 exception (c)** carves out exactly **one** key for exactly this path. §5's transcript + reports the change and §10 asserts it, because a `scripts` edit would otherwise read as a + violation of the additive guarantee. + + **The hazard the withdrawal leaves uncovered, stated rather than papered over.** `next start` + defaults to `0.0.0.0`, and someone running `npm run build && npm start` is by definition not on + their laptop — an unauthenticated model-backed route on a real host, billed to them. **That + hazard is currently open.** The withdrawal stands on its own harm regardless of whether a + replacement control ever lands, and Q7 is where the replacement is decided. Saying this plainly + is better than implying cover we do not have. **Non-goals** — **authoring** any of the shared text or shapes: the agent-instructions block's content (FIX-1160 authors it; this package places it verbatim), the next-steps block's content @@ -597,7 +581,8 @@ $ npm create flow-state my-app 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) + Added 8 dependencies via npm (@flow-state-dev/{core,engine,next,react,cli,devtool}, + @ai-sdk/openai, zod) Next steps @@ -650,6 +635,16 @@ Three details in the block are load-bearing rather than cosmetic: earlier version of this transcript printed `{"userId":"u1","message":"hi"}`, where the `userId` key set nothing and taught a first-hour reader a wrong mental model. - **The two-process caveat is real** — both printed servers open the same development file store. +- **The `Added` line's count and list are *rendered from step 6's `add` argument set*, never typed.** + The `8` above is what that rendering produces for an OpenAI scaffold; it is an illustration of a + computed value, not a number this document maintains. **This mattered immediately**: an earlier + revision of this transcript said `7` while §7's derived table required 8, and since §10 compares + every emitted line against the generated diff, an implementation building from that transcript + would have had to either misreport a successful scaffold or omit a package. A literal would pass + one round and drift at the next change to the set. Deriving it makes the transcript unable to + disagree with the table. *This is §13's recorded-but-not-enforced shape in miniature — a number + stated in one place, derived in another, with nothing keeping them equal — and it is the smallest + worked example of it in the document.* **Non-interactively**, which is how **CI** runs it — **not the goal check**, for the reason below: @@ -865,6 +860,37 @@ have caught it — the pnpm-isolated install — was itself specified against a **A requirement recorded in one section and enforced by no step is not a requirement**, which is the same shape as the FIX-1160 edge two rounds earlier. +**The FSD packages in that argument set carry an exact version; the others do not.** `npm install +@flow-state-dev/core@ @flow-state-dev/engine@ …` — 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. + +*Why this is a decision and not a detail.* `.changeset/config.json` declares **`"fixed": []` and +`"linked": []`**, so every FSD package versions independently, and pre-1.0 a `minor` is a breaking +change by convention. Bare names resolve whatever `latest` is at the moment a stranger runs the +command — **not what the checked-in template was tested against** — so `create-flow-state@1.2.0` +could scaffold a project pulling `engine` and `core` from different release trains that were never +built together. **The asymmetry is what makes it worse than an ordinary risk**: this spec pins +`create-next-app` to an exact release and argues at length that a range would let upstream drift +reach users, which makes the generated project *look* reproducible while its FSD half is not +pinned at all. The same argument applies to our own packages with more force, since we ship the +breaking changes. + +*Why exact rather than a range.* A caret on `0.x` allows only patches, which sounds sufficient — +but the release train is pre-1.0 precisely because minors still break, and a range re-resolves on +every invocation, which is the property §7 already rejected for the scaffolder. + +*What it costs, and it is the same cost already accepted once:* bumping the pin is routine +maintenance rather than a rare event, and a starter a few months behind on FSD is a real cost. The +alternative is a starter that breaks without warning, on someone else's machine, in the first five +minutes. §9's drift row is the same failure either way. + +*Not decided here — raised with FIX-1162.* If the release process adopts a **`fixed` group** for +`@flow-state-dev/*`, every package moves in lockstep and this pin collapses from N version strings +to one, with the changeset release itself keeping them consistent. That is a repo-wide release +decision that belongs to whoever owns publishing, not to this template; §12 carries it as a +cross-issue note rather than a dependency, because the exact pin above works under either answer. + **Why `add` rather than authoring the entries in step 3.** Decision 4 bends the "package manager owns `package.json`" rule for exactly one key and says so; widening that to the whole dependency block would mean this package authoring and maintaining a version range for every entry, which is @@ -1135,20 +1161,21 @@ ask above is pricing: it is per template *times* per provider, not per template: no package manager installs on its own, and fails with `DevTool assets not found` when it is absent from the generated manifest — **on npm as well as pnpm**, since this one is not a hoisting question. -- **Two negative assertions, because every control here is otherwise proved only by its happy - case.** A check that exercises only `localhost` passes identically whether the bind flag is - present or was never implemented at all. +- **Two assertions about the bind, one in each direction — and the second is the one nothing else + here asks.** A check that exercises only `localhost` passes identically whether the dev bind is + present or was never implemented; and every other check asks whether a control is *present*, none + asked whether it *releases*. - **A request from a non-loopback address fails to connect** against the running `npm run dev`. - - **With the app built and started in production mode on the default resolver, a request to the - mounted route is refused before any model invocation**, returning an error that names the - missing authentication rather than a stream. A 200 carrying an error body is not a refusal. - Run it as `npm run build && npm start` — **this is also what proves the guard's predicate is - right**, since it establishes that the real path actually sets `NODE_ENV=production` rather - than assuming it (decision 8). - - **And the complement, on the same run: `npm exec -- fsdev run chat send …` succeeds.** The - guard must *not* fire on the command the scaffold prints, where `NODE_ENV` is unset. Without - this assertion the pair above passes on a guard that refuses everything, which is precisely - the shape the "outside development" wording would have shipped. + This is the dev bind, and it stands on its own. + - **The built app started in production mode is reachable from a non-loopback address, and + `scripts.start` is byte-identical to what `create-next-app` wrote.** Run `npm run build && npm + start` and connect from another interface. **This asserts the *absence* of a narrowing we + withdrew**, which is why it needs no answer from §5 Q7: it does not test a guard we have not + built. It is also the check that would have caught the withdrawn `start` narrowing — a + container binding loopback, health checks never connecting, and the app reading as dead. + - **No production-refusal assertion is specified**, because no such control ships (decision 8). + It returns as a written assertion once Q7 says what the behaviour should be — named here so + its absence is a recorded decision rather than an oversight. - The key is deliberately *not* pre-exported. PR #1301's review note 8 called that out: pre-supplying it skips the credential path, so the check passes while a real user's first command fails. @@ -1545,6 +1572,23 @@ Nothing else. its page pulls in a component library, an icon set, and a session sidebar, which decision 6 declines. +**A hazard for whoever writes the deployment docs, recorded because it is the sharpest thing the +rail measurement found.** The sanctioned escape from `assertNetworkBindIsAuthenticated` is a flag +named **`--allow-unauthenticated`**, and it **disables the guard wholesale** — not for the one flow +that tripped it. A developer told to add that flag so their *correctly authenticated* app can bind +has also silently switched off the protection for every flow they add afterwards. It is a real +false positive (a host-authenticated app is refused, and with the flag it binds and still rejects +uncredentialed requests correctly), so the advice to use it will be tempting. **If §11's docs or a +generated `start` script ever recommend it, they must say what it turns off.** This template does +not print `fsdev serve` and the guard is not on its path, so nothing here reaches the flag today — +recorded so it does not arrive later without the warning. **The framework defect is filed +separately; do not design around it.** + +*Three gaps in that measurement are unmeasured and should be treated as unknown rather than safe:* +a flow declaring `authentication` with `defaultUserId`/`requireUser` but **no** `resolvePrincipal`; +non-HTTP transports under `fsdev serve`; and that every run was against TypeScript source via +`tsx` rather than built output. + **Follow-ups (flagged, not built):** - **The `node-api` template**, if decision 2 goes the other way — now or later. **Additive in the From a2dcb53f53b79cafcaf2b3b974817052e018b1b4 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 01:10:17 +0000 Subject: [PATCH 24/30] spec(FIX-548): propagate the start withdrawal through every count and claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 82 ++++++++++++++++++++++++------------------------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index ae98b63a94..9babf3b2c6 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -102,7 +102,7 @@ every addition): §6 is mostly about keeping the file list short and refusing su `templates//` change.** An earlier revision of this decision said it was; that was wrong, and it under-priced the branch this spec recommends as its own fallback. Everything from §7 step 2 down assumes Next.js: the pipeline spawns `create-next-app` unconditionally, three of - the four changes it makes are Next-specific (`allowImportingTsExtensions`, and the `next dev` / + the three changes it makes are Next-specific (`allowImportingTsExtensions`, and the `next dev` `next start` script values decision 8 narrows), the mount pair and the chat page are Next files, the wiring contract's item this template satisfies is *the Next.js mount pair*, and §10's proof is a browser rendering a streamed response through that mount. @@ -410,7 +410,7 @@ the install and the printed block as "anything `fsdev init` does". There is no ` FIX-1159 disclaims the same five in its own Non-goals — so as written they were owned by nobody while the epic's greenfield proof named every one of them. Decision 3 takes them.* -**Size:** Medium — 6 template files · 4 changes to files `create-next-app` wrote · 2 verbatim +**Size:** Medium — 6 template files · 3 changes to files `create-next-app` wrote · 2 verbatim embedded blocks + their comparison assertions · 1 package entry doing its own credential write, install and print · ~20 test behaviours · 3 doc surfaces · 2 PRs. *This was "Small" while five jobs sat on the other side of a seam that does not exist; the seam's removal is where the size @@ -480,7 +480,7 @@ five minutes with FSD ends in "this is a Next.js thing", and we would not hear a **One correction to how this fork was priced, because it lands on the fallback.** This section previously said either answer was cheap here — that §7's `templates//` layout absorbed the difference. **It does not.** Everything from §7 step 2 down is Next-specific: the pipeline spawns -`create-next-app` unconditionally, three of its four changes to scaffolder-written files are Next +`create-next-app` unconditionally, its changes to scaffolder-written files are Next keys, and the proof is a browser rendering through a mounted route. **Shipping both starters therefore buys another specification round on this issue** — a Node scaffolding step, its own file set, its own security posture (decision 8 does not transfer; the plain-Node control is @@ -576,7 +576,7 @@ $ npm create flow-state my-app Created fsdev.config.ts lib/flowstate.ts src/flows/chat/flow.ts app/api/flows/route.ts app/api/flows/[...path]/route.ts - Updated package.json ("type": "module"; dev and start bound to 127.0.0.1) + Updated package.json ("type": "module"; dev bound to 127.0.0.1) tsconfig.json (allowImportingTsExtensions) app/page.tsx (replaced — the stock Next.js page) Appended AGENTS.md (FSD section) @@ -606,15 +606,15 @@ package's source and rendered here for npm and the `mounted-route` topology (§7 **The `Created` / `Updated` split is by what the run did to the developer's directory**, not by which step did it: `Created` is a path that did not exist, `Updated` is any change to a file -`create-next-app` wrote. There are **five** such changes across three files — two added keys -(`"type": "module"`, `allowImportingTsExtensions`), two rewritten `scripts` values, and one -wholesale replacement. `app/page.tsx` sits in `Updated` for that reason: it is a template file, +`create-next-app` wrote. There are **four** such changes across three files — two added keys +(`"type": "module"`, `allowImportingTsExtensions`), **one** rewritten `scripts` value (`dev`), and +one wholesale replacement. `app/page.tsx` sits in `Updated` for that reason: it is a template file, but reporting it as *created* would misdescribe the one change most likely to surprise someone who had glanced at the stock page. *The two counts in this document are different questions and both are right.* §7 step 3 says -**four** changes *in addition to* the six template files, because `app/page.tsx` is already one of -the six. This section says **five**, because it counts every change to a file the developer did not +**three** changes *in addition to* the six template files, because `app/page.tsx` is already one of +the six. This section says **four**, because it counts every change to a file the developer did not watch us create — which is what the report is for. **The `scripts` line is not cosmetic and must not be softened.** `Updated package.json` reading @@ -693,7 +693,7 @@ by itself set the published name. ```mermaid flowchart TB A[1 · resolve invocation
name · provider · key · package manager
Node ≥ 22.18] --> B[2 · create the bare app
create-next-app, install skipped, every flag explicit] - B --> C[3 · write the template
6 files · + 4 changes to files create-next-app wrote] + B --> C[3 · write the template
6 files · + 3 changes to files create-next-app wrote] C --> D[4 · append AGENTS.md section
FIX-1160's block, verbatim] D --> E[5 · credential stop
git check-ignore .env.local, then write the key] E --> F[6 · add the dependencies
package manager add — writes the entries and resolves them] @@ -733,14 +733,13 @@ starter that breaks without warning. §9's drift row is the same failure either decides whose terminal it happens in. **Step 3 — write the template.** Six files, materialized from `templates/nextjs-chat/`, plus -**four further changes to files `create-next-app` wrote** — "further" because one of the six, +**three further changes to files `create-next-app` wrote** — "further" because one of the six, `app/page.tsx`, is itself a replacement of a file it wrote (§5 counts five for that reason): | change | file | whose rule | |---|---|---| | `"type": "module"` added | `package.json` | decision 4 | | `scripts.dev` → `next dev --hostname 127.0.0.1` | `package.json` | decision 8 · epic theme 6 exception (c) | -| `scripts.start` → `next start --hostname 127.0.0.1` | `package.json` | decision 8 · epic theme 6 exception (c) | | `allowImportingTsExtensions: true` added | `tsconfig.json` | decision 4 | Dependencies and the lockfile remain entirely the package manager's; nothing else in either file @@ -750,7 +749,7 @@ is touched. This is the entire product surface: |---|---| | `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 | | `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, naming **the concrete `provider/model` string** for the provider chosen (decision 5's table), never an intent. Declares the production refusal on itself (decision 8), keyed on `NODE_ENV === "production"`, so such a request is refused before any model invocation. Imports `defineFlow` from `@flow-state-dev/core` and `z` from `zod` — both direct dependencies, per the contract's dependency rule. `examples/hello-chat`'s flow is the reference for shape, not for size. Path matches what the docs teach | +| `src/flows/chat/flow.ts` | the demo flow — one action, one streaming generator, naming **the concrete `provider/model` string** for the provider chosen (decision 5's table), never an intent. **Declares no production refusal** — decision 8 withdrew it; the flow is on the framework default resolver and accepts any caller, which is what epic §5 Q7 is about. Imports `defineFlow` from `@flow-state-dev/core` and `z` from `zod` — both direct dependencies, per the contract's dependency rule. `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, no Vercel assumption. **Carries the canonical route exports beside it: `runtime = "nodejs"` and `dynamic = "force-dynamic"`.** Not decoration — `packages/next/README.md` ships exactly those three lines, and `examples/hello-chat` documents why: without `force-dynamic` Next may buffer the response body, and a buffered body turns token-by-token streaming into one delivery at the end. That is the epic's headline outcome failing while every wiring check passes | | `app/api/flows/route.ts` | the sibling bare route. `list_flows` is registered as `GET /` on the mount base and the client's `listFlows()` requests it, but a required catch-all cannot match zero segments. `@flow-state-dev/next` exports no bare handler (only `@flow-state-dev/vercel` does), so this one forwards by hand with a comment saying why — carrying the same route exports as its sibling | | `app/page.tsx` | the chat page. `FlowProvider` + `useFlow` + `useSession` + `ItemsRenderer` from `@flow-state-dev/react`, no other imports (decision 6). Overwrites `create-next-app`'s stock page — permitted, because this is a directory this command created seconds ago | @@ -900,7 +899,7 @@ resolves atomically — there is no intermediate state where the manifest lists lockfile has never seen. **The manifest's state when this step runs:** `create-next-app`'s original manifest, plus -`"type": "module"` and the two loopback-narrowed scripts from step 3, and **no FSD dependencies +`"type": "module"` and the loopback-narrowed `scripts.dev` from step 3, and **no FSD dependencies yet**. This step adds them. Everything step 3 wrote must already be in place, because the manager reads and rewrites the same file. @@ -915,7 +914,7 @@ fourth — and then, applied a second time to the append's **own** failure, made | fallible step | what is on disk when it fails | what the printed recovery restores | |---|---|---| | step 2, `create-next-app` | nothing of ours | nothing — the target is somebody else's partial output, so the instruction is inspect and restart (§9) | -| **step 4, the `AGENTS.md` append** | the six template files and all four changes; **no key, no dependencies** | nothing, and it does not try — **the run stops**, so there is no recovery message making a claim about a section that is not there | +| **step 4, the `AGENTS.md` append** | the six template files and all three changes; **no key, no dependencies** | nothing, and it does not try — **the run stops**, so there is no recovery message making a claim about a section that is not there | | step 5, the credential stop | everything above **and the `AGENTS.md` section, because step 4 succeeded or the run ended** | the developer adds the ignore line, writes the key, and installs — three named steps, nothing missing that they would have to author | | step 6, the dependency add | everything above, plus the key — but **the manifest may or may not yet carry the dependency entries**, since `add` writes and resolves in one operation | **the same `add` command, printed verbatim with its package list**, not a bare install. A bare `npm install` would resolve whatever the manifest happens to hold, which on a failure part-way through is exactly the state we cannot assume | @@ -972,17 +971,18 @@ package generates a project; it changes no framework behaviour. 2. **The bare-app step** — spawn `create-next-app` with every flag explicit and install skipped; surface its failure. *Test:* the argv built (complete enough that no option resolves from saved preferences; install skipped), and the failure path's output. *Depends on:* 1. -3. **The template** — the six files **and all four changes to files `create-next-app` wrote**: - `"type": "module"` and the two loopback-narrowed `scripts` values in `package.json`, and +3. **The template** — the six files **and all three changes to files `create-next-app` wrote**: + `"type": "module"` and the loopback-narrowed `scripts.dev` value in `package.json`, and `allowImportingTsExtensions` in `tsconfig.json`. None is optional. Without the tsconfig key the config's `.ts` import of the demo flow is a `TS5097` build error, and with an extensionless - import instead the CLI cannot load the config at all (decision 4); without the script edits the - generated app serves an unauthenticated model-backed route on every interface (decision 8). + import instead the CLI cannot load the config at all (decision 4); without the `dev` edit the + generated app serves an unauthenticated model-backed route on every interface in development + (decision 8). The config carries the static provider import and the pre-built `modelResolver`, and the flow - names the concrete model string and declares the production refusal (decisions 5 and 8). + names the concrete model string (decision 5). **No production refusal** — decision 8. *Test:* the generated project builds and its mounted route serves; **the config loads under a native `import()` with the demo flow imported through it**, not as a self-contained module, - with no warning; both `scripts` values carry `--hostname 127.0.0.1`. + with no warning; `scripts.dev` carries `--hostname 127.0.0.1` and `scripts.start` is unmodified. *Depends on:* nothing. 4. **The `AGENTS.md` append** — FIX-1160's canonical block embedded verbatim and appended, never creating the file and never touching Next's own delimited block. **Sequenced here, before the @@ -1072,7 +1072,7 @@ elsewhere: the directory is seconds old and contains nothing the developer autho | `create-next-app` fails, is unreachable, or rejects a flag | Report its output and **name the target as partially populated and not resumable**. Do not delete it — it is the developer's directory and it may hold their evidence. Print inspect-and-restart instructions: review what is there, then remove it (or pick a new name) and re-run the command. **Do not print "two commands that finish the job by hand"** — see below. | | `create-next-app` changes its flag surface or generated layout | The **exact** pinned version (§7 step 2) means an upstream change cannot reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. A major-range pin would not hold that. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. | | The pinned `create-next-app` falls behind | New projects start on an older Next than current. Bumping the pin is scheduled maintenance gated on a goal-check run, not a reaction to breakage. | -| The dependency add fails (step 6) | The scaffold stays and is **genuinely finishable**: the six template files, all four changes, the `AGENTS.md` section and the key are already on disk, so dependencies are the *only* thing outstanding. Report the manager's own output and **print the `add` command with its full package list** against that directory — **not a bare install**, which would resolve whatever the manifest currently holds and leave the FSD imports unresolved exactly as this failure did. **Three earlier revisions made the "finishable" claim falsely**, each for a different reason, and together they are why the pipeline reads as it does: the first appended `AGENTS.md` *after* the install; the second appended it before but let that append fail and continue; the third listed the dependencies in §7 with no step that wrote them, so the printed bare install could never have completed the project. | +| The dependency add fails (step 6) | The scaffold stays and is **genuinely finishable**: the six template files, all three changes, the `AGENTS.md` section and the key are already on disk, so dependencies are the *only* thing outstanding. Report the manager's own output and **print the `add` command with its full package list** against that directory — **not a bare install**, which would resolve whatever the manifest currently holds and leave the FSD imports unresolved exactly as this failure did. **Three earlier revisions made the "finishable" claim falsely**, each for a different reason, and together they are why the pipeline reads as it does: the first appended `AGENTS.md` *after* the install; the second appended it before but let that append fail and continue; the third listed the dependencies in §7 with no step that wrote them, so the printed bare install could never have completed the project. | | The `AGENTS.md` append fails (step 4 — unwritable, or the file vanished) | **Stop. Do not continue to the credential stop or the install.** Report the write error and give inspect-and-restart guidance: review the directory, then remove it (or pick a new name) and re-run. No key has been written and nothing has been installed, so there is nothing to clean up beyond the directory itself. **Do not** print instructions to paste the block by hand — it is canonical text this package embeds, and a hand copy is exactly the drift theme 9 exists to prevent. *An earlier revision continued past this and named the section as not added; that made the two recovery promises below it false, because both assert the section is on disk (§7).* | | `-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). | @@ -1083,7 +1083,7 @@ elsewhere: the directory is seconds old and contains nothing the developer autho it.** Refusals happen before anything is created and leave the disk untouched. The credential stop happens after the scaffold exists and leaves it there, minus the key. Failures leave a directory the developer can **inspect** — and only some of them leave one that can be *finished*. -**A failed dependency add can**: the six template files, all four changes, the `AGENTS.md` section +**A failed dependency add can**: the six template files, all three changes, the `AGENTS.md` section and the key are already on disk, so re-running **the printed `add` command with its package list** completes it. **Two failures cannot, and both end in inspect-and-restart.** A failed `create-next-app`: the target is partly populated by a tool we do not control, step 1 refuses a non-empty target, nothing @@ -1142,7 +1142,7 @@ ask above is pricing: it is per template *times* per provider, not per template: byte-for-byte. **Must not be dropped:** a streaming chat page proves nothing about what the scaffolder overwrote on the way there, and greenfield is the one path where we author both sides, so it is where the epic's additive guarantee is exercised end to end. -- **And the run's report is compared against the actual diff**, including all five changes to +- **And the run's report is compared against the actual diff**, including all four changes to files `create-next-app` wrote. - **A pnpm-isolated install of the emitted template — and the word `pnpm` is load-bearing, not a synonym for "isolated".** After the scaffold, install the generated app's own `package.json` @@ -1243,17 +1243,19 @@ my-app` is the advertised UX; the pnpm run beside it is what makes that one safe 3 but before step 4. That window contains exactly this package's template writes. Everything outside it is not in this list — `create-next-app`'s own scaffold before it, and `.env.local`, the `AGENTS.md` append, the dependencies and the lockfile after it -- **the run reports every change it makes to a file it did not create** — all **five**: the two - decision-4 keys in `package.json` and `tsconfig.json`, **the two rewritten `scripts` values**, +- **the run reports every change it makes to a file it did not create** — all **four**: the two + decision-4 keys in `package.json` and `tsconfig.json`, **the rewritten `scripts.dev` value**, and the wholesale replacement of `app/page.tsx`. None is a new path, so a filename-only summary misses every one of them, and they are precisely the changes a reader would be surprised by. Assert the category too, not just the presence of the name: a run that reports `app/page.tsx` as *created* has misdescribed what it did to a file the developer may have already opened, and a run that reports `package.json` as "dependency keys only" has misdescribed a security-relevant edit. The epic's proof compares the run's report against the actual diff -- **both `scripts.dev` and `scripts.start` carry `--hostname 127.0.0.1` in the generated - manifest** — asserted on the emitted file. Cheap, and it is the only CI-visible evidence of - decision 8's first half; the goal check's non-loopback assertion is the behavioural one +- **`scripts.dev` carries `--hostname 127.0.0.1` and `scripts.start` does not — asserted in both + directions on the generated manifest.** Cheap, and it is the only CI-visible evidence of decision + 8 either way. **The `start` half is the one that matters most**, because it asserts we left a key + alone: the withdrawn narrowing would pass every other check here and only surface as a container + that never answers its health check. - **the generated config passes a pre-built `modelResolver` built from a *static* import, and declares no `intents` and no `models` shorthand** — asserted on the emitted config's source for each of the three providers, against decision 5's table. A stub cannot reach the bundler, so @@ -1520,12 +1522,12 @@ Nothing else. `0.0.0.0` (verified by the epic against `next@16.3.1`; §10's non-loopback assertion is what proves the narrowing on our side). - **No adapter-independent production guard exists in the engine today** — nothing in - `packages/engine/src/routes/` keys on `NODE_ENV`. Decision 8's second half is therefore new - behaviour in the *generated project*, declared on the demo flow, not a framework change. Placing - it on the flow rather than host-level is deliberate: both the bind guard and - `docs/architecture/authentication.md` key on the **governing flow's** resolver, so a host-level - declaration would leave the two guards disagreeing silently. **Whether the framework should own - this guard instead is a real question and it is not this issue's** — raised below. + `packages/engine/src/routes/` keys on `NODE_ENV` — **and none is specified any more.** Decision 8 + withdrew the production refusal after the rail was measured: the guard that does exist keys on the + **bind address**, enforces **whole-app**, refuses a host-authenticated app as a false positive, + and is referenced only under `packages/node/` and `packages/cli/src/commands/serve.ts` — never in + `packages/next`, so it is not on this template's path at all. What a rail should do is epic + **§5 Q7**, the owner's. - Provider detection maps exactly three providers to env vars: `anthropic`/`ANTHROPIC_API_KEY`, `openai`/`OPENAI_API_KEY`, `google`/`GOOGLE_GENERATIVE_AI_API_KEY`. - **An *un*declared provider is reached by package resolution and a dynamic `import()`, and that @@ -1598,12 +1600,10 @@ non-HTTP transports under `fsdev serve`; and that every run was against TypeScri is a specification round on this issue rather than a directory. - **A bare-path handler in `@flow-state-dev/next`**, matching `createVercelBareHandler`. Would turn one hand-written template file into a one-liner. FIX-1159 flags the same gap. -- **Should the production refusal live in the framework rather than in generated code?** Decision - 8 puts it on the generated demo flow because that is where it can land in this issue's scope and - where the existing guards key. But *every* app on the default resolver has the same exposure, - and a guard in the engine would close them all at once instead of only the ones our scaffolder - wrote. Deliberately not decided here: it is a framework change with its own blast radius, - and shipping the generated-code version does not foreclose it. +- **What the unauthenticated-demo rail should do — epic §5 Q7, the owner's, and it blocks any + production-refusal work in every issue.** Decision 8 ships none, and §10 records the missing + assertion rather than pretending the gap is covered. The measurement that produced Q7 is in + §12's premises; the framework false positive it exposed is filed separately. - **A specified, proved minimal-project brownfield case in FIX-1159** — the substitute a backend developer needs if decision 2 ships one starter. Named as a follow-up as well as in the ask, because it is the half of the recommendation that lives in another issue and could otherwise be From 4552da7fab334f0776c5b959987a4850c0f3bca1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 01:10:48 +0000 Subject: [PATCH 25/30] spec(FIX-548): repair the Next-specific sentence and record this round in the evolution log Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 9babf3b2c6..fbbce7488e 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -101,9 +101,10 @@ every addition): §6 is mostly about keeping the file list short and refusing su **This document is written against one template throughout, and shipping two is not a `templates//` change.** An earlier revision of this decision said it was; that was wrong, and it under-priced the branch this spec recommends as its own fallback. Everything from §7 - step 2 down assumes Next.js: the pipeline spawns `create-next-app` unconditionally, three of - the three changes it makes are Next-specific (`allowImportingTsExtensions`, and the `next dev` - `next start` script values decision 8 narrows), the mount pair and the chat page are Next files, + step 2 down assumes Next.js: the pipeline spawns `create-next-app` unconditionally, two of the + three changes it makes to scaffolder-written files are Next-specific (`allowImportingTsExtensions`, + which exists because Turbopack and native Node disagree on extensions, and the `next dev` script + value decision 8 narrows), the mount pair and the chat page are Next files, the wiring contract's item this template satisfies is *the Next.js mount pair*, and §10's proof is a browser rendering a streamed response through that mount. @@ -1956,3 +1957,35 @@ The same discipline applies to the checks: §10 collects three directions this h sub-PR `a`'s prerequisites. Answering a gap by adding a statement feels like closing it and usually is not, because a spec has several places that each look authoritative and the executed one is often not the one edited. + +- **The `start` narrowing withdrawn, the production refusal withdrawn, and the product statement + withdrawn with them — all three because the rail was measured instead of derived.** Epic theme 6 + exception (c) now covers **`dev` only**: narrowing `start` is *harmful*, since *"a platform deploy + never runs `next start`"* is false of Docker, Render, Railway, Fly, Heroku and App Runner, and + Next's `-H` carries no environment binding, so `HOST=0.0.0.0` cannot override a hard-coded flag — + the container binds loopback, health checks never connect, and the app reads as dead. That was + withdrawn at epic level and **this spec had not followed**, which is the eighth restatement drift + in this epic and the reason §13's note exists. Separately, a POC ran `executeServeCommand` and + found the guard keys on the **bind address** rather than the environment, enforces **whole-app** + rather than per-flow, refuses a **host-authenticated app as a false positive**, and is not on the + Next mounted route's path at all — confirmed independently here: the symbol appears only under + `packages/node/` and `packages/cli/src/commands/serve.ts`. So the old decision named a control + that does not exist and could not be described. **Four successive product statements were false, + every one of them derived from our own rules rather than measured, and the derivation never once + failed loudly** — so the statement is withdrawn rather than rewritten a fifth time, and what a + rail should do is epic **§5 Q7**. §10 keeps the dev-bind assertion, adds its mirror (**the built + app is reachable from a non-loopback address and `scripts.start` is byte-identical**, which + asserts the *absence* of a narrowing and so needs no Q7 answer), and records the missing + production assertion as a decision rather than an oversight. The `--allow-unauthenticated` escape + is logged in §12 as a hazard for whoever writes deployment docs: it is the sanctioned workaround + for the false positive and it **disables the guard wholesale**, so anyone recommending it owes + the reader that sentence. +- **FSD dependencies are pinned to an exact version in the `add` arguments.** `.changeset/config.json` + declares `"fixed": []` and `"linked": []`, so every FSD package versions independently and, pre-1.0, + a minor is breaking by convention — meaning bare names resolve whatever `latest` is when a stranger + runs the command rather than what the checked-in template was built against. **The asymmetry is what + made it worse than an ordinary risk:** this spec pins `create-next-app` exactly and argues at length + that a range lets upstream drift reach users, which made the generated project look reproducible + while its FSD half was not pinned at all. Raised with **FIX-1162** rather than decided alone: a + `fixed` release group would collapse the pin from N version strings to one, and the exact pin works + under either answer. From 64227dd1ec4445401e4f99bf1ae5aa20c45b8702 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 01:14:12 +0000 Subject: [PATCH 26/30] =?UTF-8?q?spec(FIX-548):=20write=20the=20=C2=A712?= =?UTF-8?q?=20description=20decision=208=20pointed=20at,=20and=20record=20?= =?UTF-8?q?the=20credential=20asymmetry?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 52 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 47 insertions(+), 5 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index fbbce7488e..77aa3ef6ec 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -362,11 +362,19 @@ every addition): §6 is mostly about keeping the file list short and refusing su ***And the product statement is withdrawn.*** Four successive versions of it were false, each produced the same way — **by deriving behaviour from our own rules rather than measuring it, and the derivation never once failed loudly.** The epic stopped making one for the same reason. What - replaces it is not a promise but a description, in §12: in development the app binds to the local - machine because we set that default; in production it binds wherever Next binds, because we - changed nothing; and the demo flow accepts any caller, because it is on the framework default - resolver. A developer who wants otherwise configures authentication, which is what the - agent-instructions section is for. + replaces it is a **description, written out in §12** — what the developer gets in development, + what they get in production, and that the demo flow accepts any caller because it is on the + framework default resolver. §12 also records why this template carries **no credential** while + FIX-1159's demo flow carries one: the two are different files, and epic theme 8's matrix makes + the asymmetry a rule rather than an inconsistency. + + *A note on how this paragraph read one revision ago, because it is the pattern this spec keeps + producing:* it said the description was "in §12" while §12 contained no such thing — the + description existed only here, in the sentence pointing elsewhere. **A cross-reference to + content that does not exist is the same defect as a requirement nothing enforces**, and it + appeared one round after §13's note was written, in the text of the person who wrote it. It is + logged rather than quietly corrected, because a note that its own author violates immediately is + evidence about how much the note is worth. **What survives, and why it survives Q7's answer whatever it is.** The `dev` bind stands on its own: its justifying condition never clears, because nobody configures production authentication @@ -1522,6 +1530,40 @@ Nothing else. default-resolver apps is not in the path at all. Both `next dev` and `next start` default to `0.0.0.0` (verified by the epic against `next@16.3.1`; §10's non-loopback assertion is what proves the narrowing on our side). +- **What a developer actually gets, stated as description rather than as alarm.** This is the + behaviour decision 8 stopped promising about, written out here because it is what epic §5 Q7 is + deciding and it should be legible in the spec that ships it: + - **In development**, `npm run dev` binds `127.0.0.1`. The app is reachable from that machine and + nowhere else, because we set that default in a script we authored. + - **In production**, `npm run build && npm start` binds wherever Next binds — `0.0.0.0` by + default — because we changed nothing about `scripts.start`. Nothing of ours narrows it and + nothing of ours refuses a request. + - **The demo flow accepts any caller.** It is on the framework's default resolver, which trusts a + caller-supplied `body.userId`. 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** — and `git check-ignore` keeps the key out of version control, which is a different + problem from keeping it out of a stranger's requests. + - **What closes it** is configuring real authentication, which is what the `AGENTS.md` section + exists to teach and what the docs surfaces in §11 point at. Until Q7 answers, nothing in the + generated project does it for them, and this spec does not claim otherwise. +- **The greenfield demo flow carries no credential, and FIX-1159's demo flow does. Both are + correct, and they are different files.** Stated explicitly because two specs in one epic + describing "the demo flow" with opposite authentication postures is how a reader ends up + believing the wrong one. This template writes `src/flows/chat/flow.ts`; the brownfield skill + writes `flows/hello/flow.mts`, and FIX-1159's Non-goals disclaim "the greenfield command and its + template in every part". **The asymmetry is a rule, not an oversight** — epic theme 8's matrix is + the statement of record, and it turns on two questions that cut *across* greenfield/brownfield + rather than along it: + + | | loopback bind | credential | why | + |---|---|---|---| + | **greenfield, mounted-route** (this issue) | `dev` only; **production unresolved, §5 Q7** | **no** | the demo is a browser page, so any token it holds an attacker reads from the same page | + | brownfield, mounted-route | no — their dev script, theme 6 forbids editing it | yes | the only control available | + | brownfield, second-process | yes — our printed `fsdev serve --host 127.0.0.1` | yes | both: we author the start command *and* ship no browser client | + + 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 + `scripts.dev` and ships a chat page, which is exactly why it has the first and not the second. - **No adapter-independent production guard exists in the engine today** — nothing in `packages/engine/src/routes/` keys on `NODE_ENV` — **and none is specified any more.** Decision 8 withdrew the production refusal after the rail was measured: the guard that does exist keys on the From 28c2d08000aa652b8a758a41892cb057c8bd05dc Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 01:15:27 +0000 Subject: [PATCH 27/30] spec(FIX-548): stop promising the withdrawn production refusal in the printed transcript MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 76 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 63 insertions(+), 13 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 77aa3ef6ec..010afeeaa3 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -603,13 +603,26 @@ $ npm create flow-state my-app Storage is on-disk for development. Pick a real store before you deploy. The app and the DevTool are two processes over one development store — drive one at a time. - This app serves on 127.0.0.1 only, and will not serve in production - until you configure authentication. + `npm run dev` serves on 127.0.0.1 only. The demo flow accepts any caller, + so configure authentication before you deploy this anywhere. AGENTS.md tells your coding assistant how to write FSD flows. ``` **Every line of this is printed by this package** — there is no second command in the run and -nothing is handed back to be printed by someone else. What is *authored* elsewhere is the text +nothing is handed back to be printed by someone else. + +**The two security lines above changed this round, and *where they live* is the part that matters.** +They previously read *"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: `scripts.start` keeps `create-next-app`'s value, so the app +does not serve on loopback only, and nothing refuses a production request. The replacement says the +two things that are true — `npm run dev` binds loopback, and the demo flow accepts any caller. + +**But this text is inside FIX-1159's canonical block, so this spec cannot fix it alone**, and that +is a bigger finding than the wording. The block is embedded verbatim and §10 asserts normalized +equality against canonical, which means **a withdrawn promise left in canonical would be re-shipped +by this template to every user, and the equality check would force it to stay there.** §12 carries +it to FIX-1159 as a required change rather than a suggestion. What is *authored* elsewhere is the text below `Next steps`: that is FIX-1159's canonical next-steps block, embedded verbatim in this package's source and rendered here for npm and the `mounted-route` topology (§7). @@ -1454,10 +1467,22 @@ from this document entirely.** - **The next-steps block owes a two-process line.** Both commands it prints for a Next host open the same development file store (§9). FIX-1159 authors the block's wording; this package prints it and cannot add to it, since the embedded copy must equal canonical. -- **The block also owes the loopback line.** §5's transcript shows one, and it has to come from - canonical for the same reason. If FIX-1159 declines it, the line moves outside the delimiters as - this package's own prose — which is worse (theme 5 exists to stop unowned per-host prose), so it - is raised rather than assumed. +- **The next-steps block's security lines are FIX-1159's to author, and one of them must change — + this is a required correction, not a request.** §5's transcript renders two lines that describe + the bind and the demo flow's openness. An earlier version said *"This app serves on 127.0.0.1 + only, and will not serve in production until you configure authentication."* **Both halves are + now false** (decision 8 withdrew the `start` narrowing and the production refusal), and the + replacement is *"`npm run dev` serves on 127.0.0.1 only. The demo flow accepts any caller, so + configure authentication before you deploy this anywhere."* + + **The mechanism is why this cannot wait.** This package embeds canonical **verbatim** and §10 + asserts normalized equality over the whole block. So if the withdrawn promise survives in + canonical, **this template re-ships it to every user of the scaffolder, and the equality check + actively prevents us from correcting it** — the check designed to stop drift would pin a false + security claim in place. A shipper cannot fix this from its own side by construction. + *If FIX-1159 declines the wording, the alternative is moving the lines outside the delimiters as + this package's own prose, which is worse (theme 5 exists to stop unowned per-host prose) — so it + is raised as a change FIX-1159 owes rather than something assumed or worked around.* - **The epic's prose is stale on the name; FIX-1162's original finding was not.** The epic says `create-fsdev-app`, adopted because `create-fsd-app` was unobtainable — and that premise is **correct** (verified: held by a third party since 2024). What changed is the choice, not the @@ -1667,12 +1692,37 @@ enforced by no other*: | the dependency set | §7 listed the packages, added in response to a missing one | nothing — no step wrote them, and step 3's change table is exhaustive | | sub-PR `a`'s prerequisites | §8 and §12 both named FIX-1159 and FIX-1160 | nothing — the PR table said `—`, and the PR table is what a multi-PR run reads | -**The lesson is not "be more careful."** It is that answering a gap by *adding a statement* feels -like closing it and usually is not: a spec has several places that each look authoritative, and -the one a machine or a person actually executes is often not the one edited. So when you close a -gap during implementation, **name the artifact that will execute the fix** — a step, a test, a -manifest entry, a tracker edge — and not merely the paragraph that describes it. If the answer is -"the spec now says so", the gap is still open. +**It runs in the other direction too, and that half was missing until it had cost us twice.** A +*withdrawal* has the same blast radius as an addition: when a promise stops being true, it has to +stop being made **everywhere it appears**, and the surfaces that restate it are exactly the ones +nobody re-reads. + +| round | what was withdrawn | where it survived | +|---|---|---| +| `scripts.start` narrowing | epic theme 6 exception (c) dropped `start` | this spec's decision 8, change table, §8, §10 — for a full round | +| the production refusal | decision 8, after the rail was measured | the flow-file description, step 3, a §12 premise, a follow-up | +| the same refusal again | decision 8 | **the generated success transcript**, which promises it to the user | +| the §12 description | — | decision 8 pointed at a §12 that did not contain it | + +**So the rule is one rule with two directions.** *Additions:* name the artifact that will execute +the requirement — a step, a test, a manifest entry, a tracker edge — not merely the paragraph +describing it. *Withdrawals:* enumerate every surface that **restates** the claim before declaring +it withdrawn — the decision, the tables, the transcripts, the printed output, the tests, and +anything downstream embedding it verbatim. **A promise withdrawn in one section and still printed in +another is not withdrawn**; it is worse than before, because the document now disagrees with itself +and the surviving copy is usually the one a user reads. + +**The lesson in neither direction is "be more careful."** It is that editing the *statement* feels +like closing the loop and usually is not: a spec has several places that each look authoritative, +and the one a machine or a person actually executes — or reads — is often not the one edited. If +the answer to "is it closed?" is "the spec now says so", it is still open. + +**The transcript case is the sharpest, and it generalises past this document.** The withdrawn +promise survived in text this package embeds **verbatim from another issue**, under an equality +check. Left there, the scaffolder would re-ship a false security claim to every user *and the drift +check would prevent the shipper from correcting it*. **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. The same discipline applies to the checks: §10 collects three directions this has gone wrong (cannot fail, cannot pass, fails for the wrong reason) and the one question that catches all three. From eb38deaaa494877a75ca5eb7b54d25c2a9930afd Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 01:15:54 +0000 Subject: [PATCH 28/30] spec(FIX-548): mark the superseded product statement in the evolution log MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 010afeeaa3..fbf72a460a 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -2006,10 +2006,14 @@ The same discipline applies to the checks: §10 collects three directions this h loopback bind in a `package.json` script is not in a platform deploy's path at all, so it cannot deliver that; **and the control that does the work is the flow's production refusal, not a bind** — which the old wording both mis-attributed and, worse, made sound like a permanent - restriction on where the app may run. Decision 8 now carries the corrected statement verbatim as - the wording to use: the app refuses to serve its demo flow in production until real - authentication is configured, serves normally anywhere once it is, and separately binds to the - local machine in development as a default the developer can change in one word. + restriction on where the app may run. Decision 8 took a corrected statement — *the app refuses to + serve its demo flow in production until real authentication is configured, serves normally + anywhere once it is, and binds locally in development.* **That correction was itself false and is + superseded**: the production refusal it named did not exist, as the rail measurement two entries + below established, and `scripts.start` contradicted the "serves normally anywhere" half. **Read + decision 8, not this entry** — it now makes no product statement at all. *Left in place rather + than rewritten, because four successive corrections each looking final is the evidence for why + the statement was withdrawn instead of fixed a fifth time.* - **A list is not a step, and that is the third round in a row whose defect was created by the previous round's fix.** The dependency set was added to §7 after a review found From 48cc886332a4cea515536660d753f69d3ec930ad Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 11:42:09 +0000 Subject: [PATCH 29/30] spec(FIX-548): pin zod to v3, replace the single version placeholder with a per-package map, assert the written manifest MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- .../FIX-548-next-template-shape/README.md | 16 ++ spec-poc/FIX-548-next-template-shape/probe.sh | 7 + spec/FIX-548.md | 140 ++++++++++++++---- 3 files changed, 133 insertions(+), 30 deletions(-) diff --git a/spec-poc/FIX-548-next-template-shape/README.md b/spec-poc/FIX-548-next-template-shape/README.md index 1e46153d25..914c28603b 100644 --- a/spec-poc/FIX-548-next-template-shape/README.md +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -72,6 +72,22 @@ reason the rule survives intact: **The freeze is back on**, unchanged, with one clause added by the case: a finding that the script reports a *true* claim as **disproved** is fixed in the script; everything else is narrowed here. +**That clause has since fired a second time, which is the point of writing it down.** The native +`import()` check reads stderr to decide whether Node's documented +`MODULE_TYPELESS_PACKAGE_JSON` warning appeared — and Node's warning suppression is inherited from +the environment. With `NODE_NO_WARNINGS=1` or `--no-warnings` in `NODE_OPTIONS`, the +no-`type`-field variant emits nothing, classifies as `clean`, and the probe exits **1: claim +disproved**, when the environment had merely hidden the evidence. Same direction as the `git init` +case, different cause. Fixed in the script — both variables are cleared for that invocation — and +**not re-argued**, because the rule already decided it: this is under-reporting, not +over-assertion, and documenting it would again mean telling a reader that a red result might not +mean what it says. + +*Two instances is enough to state the underlying shape:* **this probe's evidence is read from +process output, and process output is environment-dependent.** Any future check that decides a +claim by looking at stdout/stderr inherits the same failure mode, so it clears whatever suppresses +the signal it reads, or classifies the environment as cannot-verify (`2`). + Exit status: `0` every asserted claim held · `1` one of them did not · `2` the run could not be completed (scaffold or install failed, no free port, workdir occupied, dev server never bound, a request that never completed). The `1`/`2` split is load-bearing: a machine too slow to have diff --git a/spec-poc/FIX-548-next-template-shape/probe.sh b/spec-poc/FIX-548-next-template-shape/probe.sh index 3b16256454..94731759e1 100644 --- a/spec-poc/FIX-548-next-template-shape/probe.sh +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -181,6 +181,13 @@ variant() { # MODULE_TYPELESS_PACKAGE_JSON asynchronously, and an immediate exit() cuts it # off before it reaches stderr, which made this probe report "clean" for the # variant whose whole point is that it warns. + # Node's warning suppression is inherited from the environment, and this check + # reads stderr to decide whether a documented warning appeared. With + # NODE_NO_WARNINGS=1 or --no-warnings in NODE_OPTIONS, the no-`type`-field + # 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= \ 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 diff --git a/spec/FIX-548.md b/spec/FIX-548.md index fbf72a460a..5b219fab21 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -881,38 +881,62 @@ have caught it — the pnpm-isolated install — was itself specified against a **A requirement recorded in one section and enforced by no step is not a requirement**, which is the same shape as the FIX-1160 edge two rounds earlier. -**The FSD packages in that argument set carry an exact version; the others do not.** `npm install -@flow-state-dev/core@ @flow-state-dev/engine@ …` — 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. - -*Why this is a decision and not a detail.* `.changeset/config.json` declares **`"fixed": []` and -`"linked": []`**, so every FSD package versions independently, and pre-1.0 a `minor` is a breaking -change by convention. Bare names resolve whatever `latest` is at the moment a stranger runs the -command — **not what the checked-in template was tested against** — so `create-flow-state@1.2.0` -could scaffold a project pulling `engine` and `core` from different release trains that were never -built together. **The asymmetry is what makes it worse than an ordinary risk**: this spec pins -`create-next-app` to an exact release and argues at length that a range would let upstream drift -reach users, which makes the generated project *look* reproducible while its FSD half is not -pinned at all. The same argument applies to our own packages with more force, since we ship the -breaking changes. +**Every package in that argument set carries an exact version, and the versions come from a +per-package map rather than one string.** The scaffolder holds a **version map** — one entry per +package, beside the `create-next-app` pin — and step 6 renders it into the `add` arguments: + +``` +npm install --save-exact \ + @flow-state-dev/core@ @flow-state-dev/engine@ \ + @flow-state-dev/next@ @flow-state-dev/react@ \ + @flow-state-dev/cli@ @flow-state-dev/devtool@ \ + @ai-sdk/openai@ zod@ +``` + +**One placeholder cannot version six independently released packages**, and an earlier revision of +this paragraph used one. `.changeset/config.json` declares **`"fixed": []` and `"linked": []`**, so +`core`, `engine`, `next`, `react`, `cli` and `devtool` each move on their own — after any release +where two of them differ, a single `` requests a version that is wrong for one and very likely +does not exist for another, and the scaffolder fails on its own install. *The map is not a +workaround for the missing release group; it is what independent versioning requires.* **A `fixed` +group would collapse it to one entry, and that is FIX-1162's release work — §12 carries it as a +cross-issue note and this spec does not depend on it**, because the map is correct either way. + +**`zod` is pinned to a Zod 3 range compatible with `@flow-state-dev/core`, and this is the entry +that breaks a build if it floats.** `packages/core/package.json` depends on `zod: ^3.25.76`, and +core's public block surface types schemas as v3 `ZodTypeAny` — `packages/core/src/types/block.ts` +imports it for `stateSchema` and the connector targets, and `types/agent.ts` for `outputSchema`. +The generated flow imports `z` directly and hands its `z.object(...)` to those APIs. **A bare `zod` +resolves to Zod 4, whose schema types are not assignable to v3 `ZodTypeAny`, so the generated Next +project fails `next build` on a type error before it ever reaches a model.** An earlier revision +left `zod` deliberately floating while pinning the FSD packages, which did not leave the risk +general — it aimed it precisely at the one type boundary the generated flow crosses on every run. + +*Whether core's schema boundary should accept Zod 4 is a real question and it is not this +spec's.* Raised as a separate issue rather than carried here: this template must work against the +framework as it ships, and pinning v3 costs nothing if the boundary later widens. + +**The exactness is asserted on the written manifest, not on the flag.** `npm install pkg@1.2.3` +does **not** persist `1.2.3` — npm defaults to `save-exact=false` with `save-prefix=^`, so it +writes `^1.2.3`; pnpm behaves the same without `-E`. So the `add` command carries the +manager-appropriate exact flag (`--save-exact` / `-E`), **and §10 asserts the outcome**: every FSD +entry and `zod` in the generated `package.json` is a literal version with no range operator. +Checking the manifest rather than the argv is deliberate — it catches a wrong flag, a manager whose +default changes, and a later lockfile refresh that re-resolves a caret, none of which an argv +assertion sees. *Without this the spec's pinning guarantee would be prose: the argument would say +`1.2.3` and the manifest would say `^1.2.3`, and the drift the pin exists to prevent would arrive +on the developer's next install.* *Why exact rather than a range.* A caret on `0.x` allows only patches, which sounds sufficient — but the release train is pre-1.0 precisely because minors still break, and a range re-resolves on every invocation, which is the property §7 already rejected for the scaffolder. -*What it costs, and it is the same cost already accepted once:* bumping the pin is routine +*What it costs, and it is the same cost already accepted once:* bumping the map is routine maintenance rather than a rare event, and a starter a few months behind on FSD is a real cost. The alternative is a starter that breaks without warning, on someone else's machine, in the first five minutes. §9's drift row is the same failure either way. -*Not decided here — raised with FIX-1162.* If the release process adopts a **`fixed` group** for -`@flow-state-dev/*`, every package moves in lockstep and this pin collapses from N version strings -to one, with the changeset release itself keeping them consistent. That is a repo-wide release -decision that belongs to whoever owns publishing, not to this template; §12 carries it as a -cross-issue note rather than a dependency, because the exact pin above works under either answer. - -**Why `add` rather than authoring the entries in step 3.** Decision 4 bends the "package manager +*Why `add` rather than authoring the entries in step 3.** Decision 4 bends the "package manager owns `package.json`" rule for exactly one key and says so; widening that to the whole dependency block would mean this package authoring and maintaining a version range for every entry, which is a second place for the corpus's versions to drift and the thing that rule exists to prevent. @@ -1099,7 +1123,7 @@ elsewhere: the directory is seconds old and contains nothing the developer autho | `-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. | +| The developer deploys the generated app as-is | **Nothing of ours stops them, and nothing of ours refuses the request.** `scripts.start` is unmodified so the app binds wherever Next binds, and the demo flow is on the framework default resolver, so the deployed endpoint runs model calls for any caller, billed to the developer's provider key (§12). This is the state epic **§5 Q7** is deciding; decision 8 withdrew the production refusal an earlier revision of this row mandated. **Do not implement one before Q7 answers** — the epic's rule is explicit and this row is where an implementer would otherwise pick it up. | **Taxonomy — three categories, and the middle one exists because the first two could not hold it.** Refusals happen before anything is created and leave the disk untouched. The credential @@ -1288,6 +1312,17 @@ my-app` is the advertised UX; the pnpm run beside it is what makes that one safe - **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the message naming the floor, and an untouched target directory. Without it the failure moves to every printed `fsdev` command, after a project exists (decision 4) +- **every pinned entry in the generated `package.json` is a literal version, with no range + operator** — asserted on the **written manifest**, not on the `add` argv. `npm install pkg@1.2.3` + persists `^1.2.3` unless `--save-exact` is passed, and pnpm behaves the same without `-E`, so an + argv assertion passes while the manifest drifts on the developer's next install. Checking the + outcome also catches a manager whose default changes and a lockfile refresh that re-resolves a + caret. **Assert `zod` specifically**: it is the entry whose drift is a build break rather than a + version skew (§7) +- **the version map has an entry per package, and the emitted `add` uses it** — assert that the six + `@flow-state-dev/*` arguments do not all carry the same version string when the map says they + differ. The failure this guards is a single placeholder rendered into six independently released + packages, which requests a nonexistent version and fails the scaffolder's own install - **the dependency set is actually written, not merely listed** — assert the `add` argv contains every derived member, and that the generated `package.json` carries those entries afterwards. **A spec-level list with no step behind it is what this assertion exists to catch**: the previous @@ -1697,12 +1732,21 @@ enforced by no other*: stop being made **everywhere it appears**, and the surfaces that restate it are exactly the ones nobody re-reads. -| round | what was withdrawn | where it survived | -|---|---|---| -| `scripts.start` narrowing | epic theme 6 exception (c) dropped `start` | this spec's decision 8, change table, §8, §10 — for a full round | -| the production refusal | decision 8, after the rail was measured | the flow-file description, step 3, a §12 premise, a follow-up | -| the same refusal again | decision 8 | **the generated success transcript**, which promises it to the user | -| the §12 description | — | decision 8 pointed at a §12 that did not contain it | +| round | what was withdrawn | where it survived | kind of surface | +|---|---|---|---| +| `scripts.start` narrowing | epic theme 6 exception (c) dropped `start` | decision 8, the **change table**, §8, §10 | table row | +| the production refusal | decision 8, after the rail was measured | the **file table** row, step 3, a §12 premise, a follow-up | table row | +| the same refusal again | decision 8 | **the generated success transcript** | printed output | +| the §12 description | — | decision 8 pointed at a §12 that did not contain it | cross-reference | +| the same refusal, a third time | decision 8 | **§9's deployment row**, still mandating it | table row | + +**Look at the last column: four of the five were a row, not a sentence.** That is not a +coincidence and it is the most actionable thing in this note. Prose restates a claim in language a +reader recognises as a restatement; **a table row states it as a fact, in a compressed form, in a +section organised by a different question** — §9 is organised by *failure case*, §7's file table by +*file*, neither by *which control ships*. So a `Ctrl-F` for the withdrawn wording misses them, +because the row never used that wording. **When you withdraw a claim, walk every table and matrix +whose rows could assert it, by reading the rows — not by searching for the phrase.** **So the rule is one rule with two directions.** *Additions:* name the artifact that will execute the requirement — a step, a test, a manifest entry, a tracker edge — not merely the paragraph @@ -2085,3 +2129,39 @@ The same discipline applies to the checks: §10 collects three directions this h while its FSD half was not pinned at all. Raised with **FIX-1162** rather than decided alone: a `fixed` release group would collapse the pin from N version strings to one, and the exact pin works under either answer. + +- **The pinning fix had three defects of its own, one of them a build break.** *(1)* It pinned the + FSD packages and **deliberately left `zod` floating** — which did not leave the risk general, it + aimed it at the one type boundary the generated flow crosses on every run. `packages/core` depends + on `zod ^3.25.76` and types its public block surface as v3 `ZodTypeAny` (`types/block.ts` for + `stateSchema` and connector targets, `types/agent.ts` for `outputSchema`), while a bare `zod` + resolves to Zod 4, whose schemas are not assignable to it — **so the generated project fails + `next build` on a type error before reaching a model.** `zod` is now pinned to a compatible v3 + range; whether core's boundary should accept v4 is a framework question raised separately rather + than carried here. *(2)* It used **one version placeholder for six independently released + packages**, which `.changeset/config.json` (`"fixed": []`, `"linked": []`) makes impossible — + after any release where two differ, the single string requests a version that is wrong for one and + nonexistent for another. Replaced with a **per-package version map**; a `fixed` release group would + collapse it to one entry, which is FIX-1162's work and a note rather than a dependency, since the + map is correct either way. *(3)* It assumed `add pkg@1.2.3` persists `1.2.3`. **It does not** — npm + defaults to `save-prefix=^` and pnpm needs `-E` — so the guarantee was prose while the manifest + said `^1.2.3`. The exact flag is now specified **and §10 asserts the written manifest**, which is + the stronger check: it catches a wrong flag, a changed default, and a later lockfile refresh, none + of which an argv assertion sees. +- **§13's note is sharpened to name tables, because the data says the surface matters.** Four of + the five withdrawal residuals were a **table row**, not a sentence — including §9's deployment row, + which still instructed an implementer to build the production refusal decision 8 had withdrawn, + three surfaces after the withdrawal. Prose restates a claim in language a reader recognises as a + restatement; **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. The rule now says to walk every table and matrix + by **reading the rows**, not by searching for the phrase. +- **The POC's unfreeze clause fired a second time, and was applied without re-arguing it.** The + native `import()` check reads stderr to decide whether Node's documented + `MODULE_TYPELESS_PACKAGE_JSON` warning appeared, and warning suppression is inherited: under + `NODE_NO_WARNINGS=1` or `--no-warnings`, the no-`type`-field variant emits nothing, classifies as + `clean`, and the probe reports a **true claim as disproved**. Same direction as the `git init` + case, different cause, so the standing clause decided it. Two instances are enough to state the + shape the README now carries: **this probe reads its evidence from process output, and process + output is environment-dependent** — any check deciding a claim from stdout/stderr clears what + suppresses the signal it reads, or classifies the environment as cannot-verify. From 071e3e915cdfe0307f4dfa92526308ef5e9df1ab Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 11:43:50 +0000 Subject: [PATCH 30/30] spec(FIX-548): add the four implementer notes and close the spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m --- spec/FIX-548.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/spec/FIX-548.md b/spec/FIX-548.md index 5b219fab21..8953a58cca 100644 --- a/spec/FIX-548.md +++ b/spec/FIX-548.md @@ -1784,6 +1784,39 @@ The same discipline applies to the checks: §10 collects three directions this h --- +**Four traps to resolve at the keyboard.** The spec is approved and closed; these are the things a +review found that you settle while building, not by re-opening it. Each is real, each is a +one-sitting decision, and none changes the approach. + +- **The version map, or a fixed release group — decide it with FIX-1162's release work in front of + you.** §7 specifies a per-package version map because `.changeset/config.json` has `"fixed": []` + and `"linked": []`, so the six `@flow-state-dev/*` packages version independently and one shared + placeholder would request a version that does not exist for at least one of them. **If FIX-1162 + has adopted a `fixed` group by the time you build, the map collapses to a single entry** and you + should take that — it is strictly less to maintain. If it has not, ship the map. Do not block on + the question; both are correct. + +- **Pinning is asserted on the written manifest, not on the command you typed.** `npm install + pkg@1.2.3` persists `^1.2.3` — npm defaults to `save-exact=false` with `save-prefix=^`, and pnpm + needs `-E`. Pass the manager's exact flag **and** assert that the generated `package.json` + contains literal versions with no range operator. Check the file, not the argv: that also catches + a manager whose default changes and a lockfile refresh that re-resolves a caret. + +- **Do not build a production refusal, whatever you find in older text.** Epic **§5 Q7** is open and + no issue implements one until it is answered. Earlier revisions of this spec mandated a + `NODE_ENV === "production"` refusal on the demo flow; it is withdrawn, the rail it assumed does + not exist on this template's path, and §9's deployment row now says so explicitly. **If you find a + surviving instruction to add one, it is stale — delete it rather than implement it.** + +- **`probe.sh` reads its evidence from process output, and process output is environment-dependent.** + If you touch it: any check that decides a claim by looking at stdout or stderr must clear whatever + suppresses the signal it reads — `NODE_NO_WARNINGS` and `NODE_OPTIONS` for Node warnings — or + classify the environment as cannot-verify (exit `2`). Twice now a hidden signal made the probe + report a **true** claim as **disproved**, which is the one failure direction that teaches people + to stop believing a red result. + +--- + ## Spec evolution - **Spec drafted** — scoped to the two things neither `create-next-app` nor `fsdev init` could