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..914c28603b --- /dev/null +++ b/spec-poc/FIX-548-next-template-shape/README.md @@ -0,0 +1,173 @@ +# 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. + +**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 +exists rather than deleting it. + +## The contract between this file and the script + +**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 — 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. + +### `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. + +**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. + +**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 +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, +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. (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. +- **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 + 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` | 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` | 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: 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. 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..94731759e1 --- /dev/null +++ b/spec-poc/FIX-548-next-template-shape/probe.sh @@ -0,0 +1,352 @@ +#!/usr/bin/env bash +# 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 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, +# 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; +# "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 2 +APP="$WORK/probe" +# 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, +# 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 2 + +cd "$APP" || exit 2 + +echo "=== what create-next-app wrote (findings 1-4) ===" +ls -a | tr '\n' ' '; echo +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 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 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" +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" +# 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. +# 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 + 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 +# 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}`); +} +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 2 + +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')" +} + +# $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" 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 + echo + 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\)|/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 + # 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 + 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=noisy + fi + echo " native import: $got_import (expected $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 +set_tsconfig_flag false +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 \ + "/api/flows" +set_tsconfig_flag false +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 \ + "/api/flows" + +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 — CANNOT VERIFY"; exit 2; fi +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=$! + +# 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. +# +# 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" + +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 +# 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: $([ "$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 + +echo +[ "$RC" = 0 ] && echo "probe: PASS" || echo "probe: FAIL" +exit "$RC" diff --git a/spec/FIX-548.md b/spec/FIX-548.md new file mode 100644 index 0000000000..8953a58cca --- /dev/null +++ b/spec/FIX-548.md @@ -0,0 +1,2200 @@ +# 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. 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 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, 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)) · 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 + +`npm create flow-state my-app` makes a directory, puts a working AI chat feature in it, and +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 +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 +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, 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 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 + +1. **One package, `create-flow-state`, published unscoped.** Invoked as `npm create + flow-state my-app`, or `npx create-flow-state my-app`. + *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 — 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.* + *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, 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. + + **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. 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 + 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. **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. + + **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. + *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. + + *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 **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 + 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 + 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 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 + 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 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.** + *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 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 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. + +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 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 + 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 + `@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. + + *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 +(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 +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 · 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 +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.** 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. + +**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, 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 +`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. + +--- + +### 3. Tradeoffs & alternatives + +**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 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, **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. 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`, + 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 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) + +**The whole product** *(what this spec proposes; no such command exists today)*: + +``` +$ npm create flow-state my-app + +? Model provider › OpenAI +? OPENAI_API_KEY › sk-•••••••• + + Creating my-app with create-next-app … + Writing the chat template … + 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"; dev bound to 127.0.0.1) + tsconfig.json (allowImportingTsExtensions) + 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 8 dependencies via npm (@flow-state-dev/{core,engine,next,react,cli,devtool}, + @ai-sdk/openai, zod) + + 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 '{"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. + `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. + +**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). + +**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 **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 +**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 +`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. + +**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 + 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. +- **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: + +``` +$ 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: + +``` +$ npm create flow-state 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, `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). + +**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[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 · + 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] + F --> G[7 · print next steps
FIX-1159's block, verbatim] +``` + +*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 +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 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 +**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) | +| `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, 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 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 | +| *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, **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 +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 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 — 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. + +**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 +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 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. + +**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 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. + +*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 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. + +**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 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 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 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 | + +**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 +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 +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. + +**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. + +### 8. Implementation sequence + +1. **The package skeleton and its invocation surface** — flags, prompts, `-y`, package-manager + 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 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 `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 (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; `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 + 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, + 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 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 + 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 `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:** + +| 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. | +| 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 +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 | Ask git whether it would ignore that exact path (`git check-ignore`), never whether `.gitignore` contains a rule that looks right. In a fresh `create-next-app` scaffold the answer is already yes (verified), so this is normally an assertion rather than a write — but it is the assertion the credential stop rests on, so it is made against the path, not the text. | +| The ignore entry cannot be established | **Stop before the key is written.** The scaffold stays on disk and is left usable; print what is missing, the one line to add to `.gitignore`, **and the two remaining steps by name** — write the key into `.env.local`, then run the install. Never write the key "and warn" — the warning scrolls away and the credential does not. **The recovery is complete because the `AGENTS.md` section already landed in step 4** (§7); had the append still been last, this stop would have left the developer a project silently missing canonical text they cannot author. | + +**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; +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. + +| Case | Expected | +|---|---| +| `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 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). | +| 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 | **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 +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 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 +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 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. +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. + +### 10. Testing strategy + +**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: + +- 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 + *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, 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 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` + 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 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`. + 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. + +**CI specs** (behaviours, not test names) — all against a stubbed `create-next-app` and a stubbed +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 +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*, 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` + 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 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 +- **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 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 **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 +- **`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 + 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) +- **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 + 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* + 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 + 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 + +**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. + +**One defect class, two directions — read them together, because meeting them apart is what let +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. + +**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 `add` 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 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.** + +**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 + 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 — 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.** + +- **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 — 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. *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 authors the block's wording; this package prints + it and cannot add to it, since the embedded copy must equal canonical. +- **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 + 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 + `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 + Next's own block, both survive a `next dev` run intact. + +**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): + +- **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 + invocation form, which is why decision 1's unscoped publish is a prerequisite rather than a + preference. +- **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 + 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 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). +- **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 + **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 + 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. +- **`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. +- **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: + 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 + 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. +- **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 + agreed in principle and never written down. + +### 13. Review notes for the implementer + +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 | + +**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 | 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 +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. + +- **"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. + + **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. + +--- + +**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 + 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`, 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* + `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 + 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, 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. +- **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. +- **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 + `"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. + +- **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. + +- **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. + +- **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. + +- **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. + +- **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 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 + `@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. + +- **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. + +- **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.