Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
0a031eb
spec(FIX-548): `create-fsd-app` — npx-able scaffolding for new FSD pr…
claude Aug 15, 2026
3118cce
spec(FIX-548): re-draft — `create-flow-state`, one template, owns it …
claude Aug 18, 2026
c2579de
spec(FIX-548): make the goal-run count consistent — per template x pe…
claude Aug 18, 2026
dbda62f
spec(FIX-548): pin create-next-app exactly, and make the probe fail w…
claude Aug 18, 2026
ecce07d
spec(FIX-548): canonical route exports, credential stop as its own ca…
claude Aug 18, 2026
c67c063
spec(FIX-548): make the unscoped publish a prerequisite, and correct …
claude Aug 18, 2026
a1c1553
spec(FIX-548): record the one-command finding in §13 as resolved upst…
claude Aug 18, 2026
4c2e396
spec-poc(FIX-548): assert the failure reason and the scaffold facts, …
claude Aug 18, 2026
836a305
spec-poc(FIX-548): make every README claim assertion-backed or delete it
claude Aug 18, 2026
eee403f
spec(FIX-548): close the evidence contract on both sides, and fix a c…
claude Aug 18, 2026
af5fd0d
spec-poc(FIX-548): freeze the probe, after two last checks that could…
claude Aug 18, 2026
c19b834
spec(FIX-548): conform to FIX-1159's wiring contract, and fix two def…
claude Aug 18, 2026
2ecd4fa
spec(FIX-548): settle the import form the POC never tested, and three…
claude Aug 18, 2026
404e82c
spec(FIX-548): make the deliverable, the summary categories and the f…
claude Aug 18, 2026
48d2a52
spec(FIX-548): take the five jobs nobody owned, wire the FIX-1160 edg…
claude Aug 19, 2026
a3fc694
spec(FIX-548): fix three residuals the rewrite created
claude Aug 19, 2026
3480183
spec(FIX-548): derive the dependency set from imports, and fix a guar…
claude Aug 19, 2026
30f6399
spec(FIX-548): name pnpm on the two real CI specs that install
claude Aug 19, 2026
2aebb40
spec(FIX-548): order the deterministic writes ahead of the fallible o…
claude Aug 19, 2026
4a400d0
spec(FIX-548): put the transcript summary in execution order
claude Aug 19, 2026
b0b5754
spec(FIX-548): make a failed AGENTS.md append stop the run, and corre…
claude Aug 19, 2026
dce7a26
spec(FIX-548): add the step that writes the dependencies, block sub-P…
claude Aug 19, 2026
d34dfa9
spec(FIX-548): withdraw the start narrowing and the production refusa…
claude Aug 19, 2026
a2dcb53
spec(FIX-548): propagate the start withdrawal through every count and…
claude Aug 19, 2026
4552da7
spec(FIX-548): repair the Next-specific sentence and record this roun…
claude Aug 19, 2026
64227dd
spec(FIX-548): write the §12 description decision 8 pointed at, and r…
claude Aug 19, 2026
28c2d08
spec(FIX-548): stop promising the withdrawn production refusal in the…
claude Aug 19, 2026
eb38dea
spec(FIX-548): mark the superseded product statement in the evolution…
claude Aug 19, 2026
48cc886
spec(FIX-548): pin zod to v3, replace the single version placeholder …
claude Aug 19, 2026
071e3e9
spec(FIX-548): add the four implementer notes and close the spec
claude Aug 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
spec(FIX-548): pin zod to v3, replace the single version placeholder …
…with a per-package map, assert the written manifest

Five findings on eb38dea, three of them defects in the pinning fix from the
previous round.

Leaving zod floating aimed the risk at a specific type boundary: core depends
on zod ^3.25.76 and types its public block surface as v3 ZodTypeAny, so a bare
zod resolving to v4 fails next build on a type error before any model call.
Pinned to a compatible v3 range; whether core should accept v4 is raised as a
separate framework question.

One version placeholder cannot version six independently released packages —
changeset config declares fixed:[] and linked:[]. Replaced with a per-package
version map. A fixed release group would collapse it to one entry; that is
FIX-1162's work and is a note, not a dependency, since the map is correct
either way.

add pkg@1.2.3 does not persist 1.2.3: npm defaults to save-prefix=^ and pnpm
needs -E. The exact flag is specified and §10 now asserts the written manifest
rather than the argv, which also catches a changed default and a lockfile
refresh.

§9's deployment row still mandated the withdrawn production refusal — the third
surface for that withdrawal and the fourth table row across all of them. §13's
note now names tables and matrices specifically, since a row states a claim in a
section organised by a different question and a phrase search never finds it.

probe.sh cleared NODE_NO_WARNINGS/NODE_OPTIONS for the import check: inherited
suppression made a true claim about Node report as disproved. Second application
of the standing unfreeze clause, applied without re-arguing it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
  • Loading branch information
claude committed Aug 19, 2026
commit 48cc886332a4cea515536660d753f69d3ec930ad
16 changes: 16 additions & 0 deletions spec-poc/FIX-548-next-template-shape/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,22 @@ reason the rule survives intact:
**The freeze is back on**, unchanged, with one clause added by the case: a finding that the script
reports a *true* claim as **disproved** is fixed in the script; everything else is narrowed here.

**That clause has since fired a second time, which is the point of writing it down.** The native
`import()` check reads stderr to decide whether Node's documented
`MODULE_TYPELESS_PACKAGE_JSON` warning appeared — and Node's warning suppression is inherited from
the environment. With `NODE_NO_WARNINGS=1` or `--no-warnings` in `NODE_OPTIONS`, the
no-`type`-field variant emits nothing, classifies as `clean`, and the probe exits **1: claim
disproved**, when the environment had merely hidden the evidence. Same direction as the `git init`
case, different cause. Fixed in the script — both variables are cleared for that invocation — and
**not re-argued**, because the rule already decided it: this is under-reporting, not
over-assertion, and documenting it would again mean telling a reader that a red result might not
mean what it says.

*Two instances is enough to state the underlying shape:* **this probe's evidence is read from
process output, and process output is environment-dependent.** Any future check that decides a
claim by looking at stdout/stderr inherits the same failure mode, so it clears whatever suppresses
the signal it reads, or classifies the environment as cannot-verify (`2`).

Exit status: `0` every asserted claim held · `1` one of them did not · `2` the run could not be
completed (scaffold or install failed, no free port, workdir occupied, dev server never bound, a
request that never completed). The `1`/`2` split is load-bearing: a machine too slow to have
Expand Down
7 changes: 7 additions & 0 deletions spec-poc/FIX-548-next-template-shape/probe.sh
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,13 @@ variant() {
# MODULE_TYPELESS_PACKAGE_JSON asynchronously, and an immediate exit() cuts it
# off before it reaches stderr, which made this probe report "clean" for the
# variant whose whole point is that it warns.
# Node's warning suppression is inherited from the environment, and this check
# reads stderr to decide whether a documented warning appeared. With
# NODE_NO_WARNINGS=1 or --no-warnings in NODE_OPTIONS, the no-`type`-field
# variant emits nothing, classifies as `clean`, and the probe reports a TRUE
# claim about Node as DISPROVED — the same false-disproof direction as the
# `git init` case, from a different cause. Cleared for this invocation only.
NODE_NO_WARNINGS= NODE_OPTIONS= \

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Clear redirected Node warnings before classifying the import

Fresh evidence after the earlier warning-suppression fix is Node’s separate NODE_REDIRECT_WARNINGS environment variable, which this invocation still inherits. node --help describes the corresponding option as “write warnings to file instead of stderr”; with this variable set, the expected MODULE_TYPELESS_PACKAGE_JSON warning goes to that file, import.log remains empty, and the no-type-field variant is misclassified as clean, causing exit 1 for a true claim. Clear NODE_REDIRECT_WARNINGS as well or classify that environment as cannot-verify.

Useful? React with 👍 / 👎.

node -e "import('./$cfg').then(m=>{

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Gate the probe on Node 22.18+

When this probe runs on Node 22.0–22.17, the native imports cannot satisfy the expected clean TypeScript-import result because packages/cli/src/load-config.ts identifies 22.18 as the native type-stripping floor. The script consequently exits 1 and reports the config claims as disproved instead of classifying the environment as exit 2/cannot-verify; add an upfront runtime check before running the variants.

Useful? React with 👍 / 👎.

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
Comment on lines +191 to +193

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Neutralize warning suppression before probing imports

When the caller has NODE_NO_WARNINGS=1 or NODE_OPTIONS=--no-warnings, this child inherits it, so the expected MODULE_TYPELESS_PACKAGE_JSON diagnostic is suppressed and the no-type-field variant is classified as clean. The probe then exits 1 and reports a documented Node behavior as disproved even though the environment merely hid the evidence, violating the README's exit-1/exit-2 contract. Clear warning-suppression variables for this invocation or classify such an environment as cannot-verify.

Useful? React with 👍 / 👎.

Expand Down
140 changes: 110 additions & 30 deletions spec/FIX-548.md
Original file line number Diff line number Diff line change
Expand Up @@ -881,38 +881,62 @@ have caught it — the pnpm-isolated install — was itself specified against a
**A requirement recorded in one section and enforced by no step is not a requirement**, which is
the same shape as the FIX-1160 edge two rounds earlier.

**The FSD packages in that argument set carry an exact version; the others do not.** `npm install
@flow-state-dev/core@<v> @flow-state-dev/engine@<v> …` — one version string, held in the same
constant file as the `create-next-app` pin and bumped with it as scheduled maintenance behind a
goal-check run. `zod` and the `@ai-sdk/*` package keep their bare names.

*Why this is a decision and not a detail.* `.changeset/config.json` declares **`"fixed": []` and
`"linked": []`**, so every FSD package versions independently, and pre-1.0 a `minor` is a breaking
change by convention. Bare names resolve whatever `latest` is at the moment a stranger runs the
command — **not what the checked-in template was tested against** — so `create-flow-state@1.2.0`
could scaffold a project pulling `engine` and `core` from different release trains that were never
built together. **The asymmetry is what makes it worse than an ordinary risk**: this spec pins
`create-next-app` to an exact release and argues at length that a range would let upstream drift
reach users, which makes the generated project *look* reproducible while its FSD half is not
pinned at all. The same argument applies to our own packages with more force, since we ship the
breaking changes.
**Every package in that argument set carries an exact version, and the versions come from a
per-package map rather than one string.** The scaffolder holds a **version map** — one entry per
package, beside the `create-next-app` pin — and step 6 renders it into the `add` arguments:

```
npm install --save-exact \
@flow-state-dev/core@<core> @flow-state-dev/engine@<engine> \
@flow-state-dev/next@<next> @flow-state-dev/react@<react> \
@flow-state-dev/cli@<cli> @flow-state-dev/devtool@<devtool> \
@ai-sdk/openai@<sdk> zod@<zod>
Comment on lines +888 to +893

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Install developer tooling as dev dependencies

When a generated app is packaged for production, this ordinary npm install writes @flow-state-dev/cli and @flow-state-dev/devtool into dependencies, so production-only installs cannot omit their CLI, UI assets, and transitive packages. The dependency table establishes that these two packages exist solely for the printed local-development commands, while the generated server imports neither; add them separately as exact dev dependencies so deployments do not carry development tooling.

Useful? React with 👍 / 👎.

```

**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 `<v>` requests a version that is wrong for one and very likely
does not exist for another, and the scaffolder fails on its own install. *The map is not a
workaround for the missing release group; it is what independent versioning requires.* **A `fixed`
group would collapse it to one entry, and that is FIX-1162's release work — §12 carries it as a
cross-issue note and this spec does not depend on it**, because the map is correct either way.

**`zod` is pinned to a Zod 3 range compatible with `@flow-state-dev/core`, and this is the entry
that breaks a build if it floats.** `packages/core/package.json` depends on `zod: ^3.25.76`, and
core's public block surface types schemas as v3 `ZodTypeAny` — `packages/core/src/types/block.ts`
imports it for `stateSchema` and the connector targets, and `types/agent.ts` for `outputSchema`.
The generated flow imports `z` directly and hands its `z.object(...)` to those APIs. **A bare `zod`
resolves to Zod 4, whose schema types are not assignable to v3 `ZodTypeAny`, so the generated Next
project fails `next build` on a type error before it ever reaches a model.** An earlier revision
left `zod` deliberately floating while pinning the FSD packages, which did not leave the risk
general — it aimed it precisely at the one type boundary the generated flow crosses on every run.

*Whether core's schema boundary should accept Zod 4 is a real question and it is not this
spec's.* Raised as a separate issue rather than carried here: this template must work against the
framework as it ships, and pinning v3 costs nothing if the boundary later widens.

**The exactness is asserted on the written manifest, not on the flag.** `npm install pkg@1.2.3`
does **not** persist `1.2.3` — npm defaults to `save-exact=false` with `save-prefix=^`, so it
writes `^1.2.3`; pnpm behaves the same without `-E`. So the `add` command carries the
manager-appropriate exact flag (`--save-exact` / `-E`), **and §10 asserts the outcome**: every FSD
entry and `zod` in the generated `package.json` is a literal version with no range operator.
Checking the manifest rather than the argv is deliberate — it catches a wrong flag, a manager whose
default changes, and a later lockfile refresh that re-resolves a caret, none of which an argv
assertion sees. *Without this the spec's pinning guarantee would be prose: the argument would say
`1.2.3` and the manifest would say `^1.2.3`, and the drift the pin exists to prevent would arrive
on the developer's next install.*

*Why exact rather than a range.* A caret on `0.x` allows only patches, which sounds sufficient —
but the release train is pre-1.0 precisely because minors still break, and a range re-resolves on
every invocation, which is the property §7 already rejected for the scaffolder.

*What it costs, and it is the same cost already accepted once:* bumping the pin is routine
*What it costs, and it is the same cost already accepted once:* bumping the map is routine
maintenance rather than a rare event, and a starter a few months behind on FSD is a real cost. The
alternative is a starter that breaks without warning, on someone else's machine, in the first five
minutes. §9's drift row is the same failure either way.

*Not decided here — raised with FIX-1162.* If the release process adopts a **`fixed` group** for
`@flow-state-dev/*`, every package moves in lockstep and this pin collapses from N version strings
to one, with the changeset release itself keeping them consistent. That is a repo-wide release
decision that belongs to whoever owns publishing, not to this template; §12 carries it as a
cross-issue note rather than a dependency, because the exact pin above works under either answer.

**Why `add` rather than authoring the entries in step 3.** Decision 4 bends the "package manager
*Why `add` rather than authoring the entries in step 3.** Decision 4 bends the "package manager
owns `package.json`" rule for exactly one key and says so; widening that to the whole dependency
block would mean this package authoring and maintaining a version range for every entry, which is
a second place for the corpus's versions to drift and the thing that rule exists to prevent.
Expand Down Expand Up @@ -1099,7 +1123,7 @@ elsewhere: the directory is seconds old and contains nothing the developer autho
| `-y` with no key in the environment | Scaffold completes. `.env.local` carries the empty variable line, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. **There is no key flag** (§5), so `-y` and an unset variable is the only way to reach this state, and it is CI's path rather than the goal check's. |
| The developer runs `npm run dev` and `fsdev dev` together | Both open the same development file store; concurrent writes to one session can each be accepted. Tolerable for a development default, and the next-steps block says to drive one at a time (§12 raises the wording with FIX-1159, which authors the block). |
| The developer wants to reach the app from another device | `npm run dev` binds `127.0.0.1` (decision 8), so it will not connect. This is the intended behaviour, not a bug: the flow is unauthenticated and the bind is the only control. The fix is theirs to make — remove `--hostname 127.0.0.1` from `scripts.dev`, a one-word edit in a file we wrote seconds ago — and they should understand what they are removing. |
| The developer deploys the generated app as-is | The mounted route **refuses before any model invocation**, with an error naming the missing authentication (decision 8). Not a warning, and not a 200 with an error body. |
| The developer deploys the generated app as-is | **Nothing of ours stops them, and nothing of ours refuses the request.** `scripts.start` is unmodified so the app binds wherever Next binds, and the demo flow is on the framework default resolver, so the deployed endpoint runs model calls for any caller, billed to the developer's provider key (§12). This is the state epic **§5 Q7** is deciding; decision 8 withdrew the production refusal an earlier revision of this row mandated. **Do not implement one before Q7 answers** — the epic's rule is explicit and this row is where an implementer would otherwise pick it up. |

**Taxonomy — three categories, and the middle one exists because the first two could not hold
it.** Refusals happen before anything is created and leave the disk untouched. The credential
Expand Down Expand Up @@ -1288,6 +1312,17 @@ my-app` is the advertised UX; the pnpm run beside it is what makes that one safe
- **the scaffold refuses on Node below 22.18, before creating anything** — assert the exit, the
message naming the floor, and an untouched target directory. Without it the failure moves to
every printed `fsdev` command, after a project exists (decision 4)
- **every pinned entry in the generated `package.json` is a literal version, with no range
operator** — asserted on the **written manifest**, not on the `add` argv. `npm install pkg@1.2.3`
persists `^1.2.3` unless `--save-exact` is passed, and pnpm behaves the same without `-E`, so an
argv assertion passes while the manifest drifts on the developer's next install. Checking the
outcome also catches a manager whose default changes and a lockfile refresh that re-resolves a
caret. **Assert `zod` specifically**: it is the entry whose drift is a build break rather than a
version skew (§7)
- **the version map has an entry per package, and the emitted `add` uses it** — assert that the six
`@flow-state-dev/*` arguments do not all carry the same version string when the map says they
differ. The failure this guards is a single placeholder rendered into six independently released
packages, which requests a nonexistent version and fails the scaffolder's own install
- **the dependency set is actually written, not merely listed** — assert the `add` argv contains
every derived member, and that the generated `package.json` carries those entries afterwards.
**A spec-level list with no step behind it is what this assertion exists to catch**: the previous
Expand Down Expand Up @@ -1697,12 +1732,21 @@ enforced by no other*:
stop being made **everywhere it appears**, and the surfaces that restate it are exactly the ones
nobody re-reads.

| round | what was withdrawn | where it survived |
|---|---|---|
| `scripts.start` narrowing | epic theme 6 exception (c) dropped `start` | this spec's decision 8, change table, §8, §10 — for a full round |
| the production refusal | decision 8, after the rail was measured | the flow-file description, step 3, a §12 premise, a follow-up |
| the same refusal again | decision 8 | **the generated success transcript**, which promises it to the user |
| the §12 description | — | decision 8 pointed at a §12 that did not contain it |
| round | what was withdrawn | where it survived | kind of surface |
|---|---|---|---|
| `scripts.start` narrowing | epic theme 6 exception (c) dropped `start` | decision 8, the **change table**, §8, §10 | table row |
| the production refusal | decision 8, after the rail was measured | the **file table** row, step 3, a §12 premise, a follow-up | table row |
| the same refusal again | decision 8 | **the generated success transcript** | printed output |
| the §12 description | — | decision 8 pointed at a §12 that did not contain it | cross-reference |
| the same refusal, a third time | decision 8 | **§9's deployment row**, still mandating it | table row |

**Look at the last column: four of the five were a row, not a sentence.** That is not a
coincidence and it is the most actionable thing in this note. Prose restates a claim in language a
reader recognises as a restatement; **a table row states it as a fact, in a compressed form, in a
section organised by a different question** — §9 is organised by *failure case*, §7's file table by
*file*, neither by *which control ships*. So a `Ctrl-F` for the withdrawn wording misses them,
because the row never used that wording. **When you withdraw a claim, walk every table and matrix
whose rows could assert it, by reading the rows — not by searching for the phrase.**

**So the rule is one rule with two directions.** *Additions:* name the artifact that will execute
the requirement — a step, a test, a manifest entry, a tracker edge — not merely the paragraph
Expand Down Expand Up @@ -2085,3 +2129,39 @@ The same discipline applies to the checks: §10 collects three directions this h
while its FSD half was not pinned at all. Raised with **FIX-1162** rather than decided alone: a
`fixed` release group would collapse the pin from N version strings to one, and the exact pin works
under either answer.

- **The pinning fix had three defects of its own, one of them a build break.** *(1)* It pinned the
FSD packages and **deliberately left `zod` floating** — which did not leave the risk general, it
aimed it at the one type boundary the generated flow crosses on every run. `packages/core` depends
on `zod ^3.25.76` and types its public block surface as v3 `ZodTypeAny` (`types/block.ts` for
`stateSchema` and connector targets, `types/agent.ts` for `outputSchema`), while a bare `zod`
resolves to Zod 4, whose schemas are not assignable to it — **so the generated project fails
`next build` on a type error before reaching a model.** `zod` is now pinned to a compatible v3
range; whether core's boundary should accept v4 is a framework question raised separately rather
than carried here. *(2)* It used **one version placeholder for six independently released
packages**, which `.changeset/config.json` (`"fixed": []`, `"linked": []`) makes impossible —
after any release where two differ, the single string requests a version that is wrong for one and
nonexistent for another. Replaced with a **per-package version map**; a `fixed` release group would
collapse it to one entry, which is FIX-1162's work and a note rather than a dependency, since the
map is correct either way. *(3)* It assumed `add pkg@1.2.3` persists `1.2.3`. **It does not** — npm
defaults to `save-prefix=^` and pnpm needs `-E` — so the guarantee was prose while the manifest
said `^1.2.3`. The exact flag is now specified **and §10 asserts the written manifest**, which is
the stronger check: it catches a wrong flag, a changed default, and a later lockfile refresh, none
of which an argv assertion sees.
- **§13's note is sharpened to name tables, because the data says the surface matters.** Four of
the five withdrawal residuals were a **table row**, not a sentence — including §9's deployment row,
which still instructed an implementer to build the production refusal decision 8 had withdrawn,
three surfaces after the withdrawal. Prose restates a claim in language a reader recognises as a
restatement; **a row states it as a fact, compressed, in a section organised by a different
question** — §9 by failure case, §7's file table by file, neither by which control ships — so a
search for the withdrawn wording never finds it. The rule now says to walk every table and matrix
by **reading the rows**, not by searching for the phrase.
- **The POC's unfreeze clause fired a second time, and was applied without re-arguing it.** The
native `import()` check reads stderr to decide whether Node's documented
`MODULE_TYPELESS_PACKAGE_JSON` warning appeared, and warning suppression is inherited: under
`NODE_NO_WARNINGS=1` or `--no-warnings`, the no-`type`-field variant emits nothing, classifies as
`clean`, and the probe reports a **true claim as disproved**. Same direction as the `git init`
case, different cause, so the standing clause decided it. Two instances are enough to state the
shape the README now carries: **this probe reads its evidence from process output, and process
output is environment-dependent** — any check deciding a claim from stdout/stderr clears what
suppresses the signal it reads, or classifies the environment as cannot-verify.
Loading