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 create-next-app exactly, and make the probe fail w…
…hen it fails

Both from Codex's review of 3118cce, folded into the rework in flight.

P1 — the major-range pin did not hold the guarantee the spec makes. Codex is
right: `create-next-app@16` re-resolves to the newest 16.x on every invocation,
so a Next minor that moves a flag or the generated layout reaches users the day
it ships, while §7 claimed upstream changes cannot reach them until we bump. The
pin is now an exact release, the argv assertion rejects a range as well as a
missing pin, and §9 gains the cost that makes this honest: create-next-app
writes an exact `next` version into the manifest it generates, so pinning the
scaffolder also pins the Next version new projects start on. Bumping it is
scheduled maintenance behind a goal-check run, not a rare event. The probe is
pinned exactly for the same reason — it is cited as evidence, so a reader
running it later must get the version the findings were measured on.

P2 — dropped by the stated contract, taken anyway, because the reasoning is
right. The probe printed FAIL and exited 0, which is a check able to report
green for a claim it did not prove — the failure BP-003 and tenet 7 name, and
the same one the per-run marker and free-port check were added to close. The
served-route and AGENTS.md checks are now assertions: exit 0 they held, 1 one
failed, 2 could not be checked. Verified in both directions — a full run passes
(`probe: PASS`, exit 0), and the verdict logic returns 1 for a stale marker, a
non-200, an empty body, a missing FSD section, and a duplicated next block.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
  • Loading branch information
claude committed Aug 18, 2026
commit dbda62f06dc03973157997e38c50b34ea7093caa
7 changes: 7 additions & 0 deletions spec-poc/FIX-548-next-template-shape/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,13 @@ Run it: `bash probe.sh` (needs network; ~2 minutes). It scaffolds a real `create
project, drops each candidate config shape in, and runs `next build`, `next dev`, and a native
`import()` against each.

**The exit status is the evidence** — `0` the served-route and `AGENTS.md` claims held, `1` one
of them failed, `2` it could not be checked. The variant table below is printed output you read;
the final section is an assertion the script fails on. It uses a fresh marker per run on a port
it proves free first, because an earlier version of this probe reported green by reaching a stale
dev server left over from a previous run — a result from a neighbour of the claim, which is the
whole failure it exists to catch.

## What it settled

| Variant | `next build` | native `import()` | verdict |
Expand Down
27 changes: 20 additions & 7 deletions spec-poc/FIX-548-next-template-shape/probe.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
#
# bash probe.sh [workdir]
#
# Scaffolds a real create-next-app@16 project, then for each candidate shape of
# Scaffolds a real create-next-app@16.3.1 project, then for each candidate shape of
# the FSD config runs `next build` (the bundler + TypeScript half) and a native
# `import()` (the fsdev CLI half). Ends with a `next dev` + curl on the chosen
# shape, so the mounted route is proven to serve, not just to compile.
Expand All @@ -15,7 +15,9 @@ APP="$WORK/probe"
rm -rf "$APP"

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 Refuse a pre-existing probe directory

When the optional workdir already contains a probe/ directory, this unconditional removal silently destroys that directory and all its contents before scaffolding. Since bash probe.sh [workdir] does not document the argument as a disposable directory, create a unique child directory or refuse when $WORK/probe already exists.

Useful? React with 👍 / 👎.

echo "workdir: $WORK"

npx --yes create-next-app@16 "$APP" \
# Exact, not @16 — a range would re-resolve and this script is cited as evidence,
# so a reader running it later must get the version the findings were measured on.
npx --yes create-next-app@16.3.1 "$APP" \
--ts --app --no-tailwind --no-eslint --no-biome --no-src-dir \
--no-react-compiler --no-rspack --import-alias "@/*" \
--agents-md --skip-install --disable-git || exit 1
Expand Down Expand Up @@ -93,7 +95,7 @@ PORT=0
for p in $(seq 3990 3999); do
if ! (exec 3<>"/dev/tcp/127.0.0.1/$p") 2>/dev/null; then PORT=$p; break; fi
done
if [ "$PORT" = 0 ]; then echo " no free port in 3990-3999 — skipped"; exit 0; fi
if [ "$PORT" = 0 ]; then echo " no free port in 3990-3999 — CANNOT VERIFY"; exit 2; fi
echo " port $PORT (verified free)"

printf '\n<!-- BEGIN:fsd -->\nFSD SECTION SENTINEL\n<!-- END:fsd -->\n' >> AGENTS.md
Expand All @@ -102,11 +104,22 @@ DEV_PID=$!
sleep 18
BODY=$(curl -s --max-time 20 --noproxy '*' "http://127.0.0.1:$PORT/api/flows")
echo " GET /api/flows -> $BODY"
RC=0
case "$BODY" in
"$MARKER":200) echo " PASS — the route served this run's config module" ;;
*) echo " FAIL — expected $MARKER:200" ;;
*) echo " FAIL — expected $MARKER:200"; RC=1 ;;
esac
echo " FSD section survived next dev: $(grep -c 'FSD SECTION SENTINEL' AGENTS.md) (expect 1)"
echo " next's own block still there: $(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md) (expect 1)"
FSD_N=$(grep -c 'FSD SECTION SENTINEL' AGENTS.md)
NEXT_N=$(grep -c 'BEGIN:nextjs-agent-rules' AGENTS.md)

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 Remove the Next block before testing restoration

The new post-next dev count starts with Next's rules block already present, so a count of one proves only that the block survived; it cannot support the README and spec claim that next dev re-adds or restores a missing block. Delete just that delimited block before starting the server and require it to return, while separately retaining the FSD-section survival assertion.

Useful? React with 👍 / 👎.

echo " FSD section survived next dev: $FSD_N (expect 1)"
echo " next's own block still there: $NEXT_N (expect 1)"
[ "$FSD_N" = 1 ] || { echo " FAIL — appended FSD section did not survive"; RC=1; }
[ "$NEXT_N" = 1 ] || { echo " FAIL — next's own block is not intact"; RC=1; }
kill "$DEV_PID" 2>/dev/null; wait "$DEV_PID" 2>/dev/null
exit 0

# The exit status is the evidence. This script is cited by the spec and the PR as
# the thing a reader runs, so it must not be able to report green for a claim it
# did not prove: 0 = the served-route and AGENTS.md claims held, 1 = one failed,
# 2 = could not be checked at all.
[ "$RC" = 0 ] && echo " probe: PASS" || echo " probe: FAIL"
exit "$RC"
31 changes: 20 additions & 11 deletions spec/FIX-548.md
Original file line number Diff line number Diff line change
Expand Up @@ -321,14 +321,21 @@ persists saved preferences between runs and silently fills unpassed options from
we omit can resolve differently on a developer's machine than on ours. `--yes` is not a
substitute for passing them.

**The version is pinned in the spawned specifier, not left to `npx` to resolve.** The command is
`create-next-app@<tested major>`, held in one constant in this package and bumped as a deliberate
change with a goal-check run behind it — never a bare `create-next-app`, which resolves whatever
shipped that morning. The pin is what makes §9's flag-drift row a *loud* failure at our next
release rather than a silent one in a stranger's terminal, and the CI argv assertion (§10) reads
the pinned specifier so removing it fails a test. The pin cannot detect upstream drift on its own
— nothing stubbed can — so the goal check is the detector and the pin is what stops the detection
gap reaching users in between.
**The version is pinned to an exact release in the spawned specifier** — `create-next-app@16.3.1`,
not `@16` and not bare — held in one constant in this package and bumped as a deliberate change
with a goal-check run behind it. A major-range pin does not hold the guarantee: `@16` re-resolves
to the newest 16.x on every invocation, so a Next minor that moves a flag or the generated layout
reaches users the day it ships, which is exactly what the pin exists to prevent. The CI argv
assertion (§10) reads the pinned specifier, so both removing it and loosening it to a range fail
a test. The pin cannot *detect* upstream drift — nothing stubbed can — so the goal check is the
detector and the pin is what keeps the gap between drift and detection off users' machines.

**What the exact pin costs, stated plainly:** `create-next-app` writes an *exact* `next` version
into the manifest it generates, so pinning the scaffolder also pins the Next version new projects
start on. Bumping it is therefore **routine scheduled maintenance with a goal-check run**, not a
rare event — a starter a few months behind on Next is a real cost, and the alternative is a
starter that breaks without warning. §9's drift row is the same failure either way; the pin only
decides whose terminal it happens in.

**Step 3 — write the template.** Six files, materialized from `templates/nextjs-chat/`, plus one
manifest key. This is the entire product surface:
Expand Down Expand Up @@ -416,7 +423,8 @@ package generates a project; it changes no framework behaviour.
| Case | Expected |
|---|---|
| `create-next-app` fails, is unreachable, or rejects a flag | Report its output, name the directory as it stands, and print the two commands that finish the job by hand. Do not delete it. |

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 Define a recoverable scaffolder failure path

When create-next-app exits after partially populating the target, the promised two finishing commands cannot use this scaffolder because its non-empty-directory validation refuses the retained target, and fsdev init intentionally does not own the six template files. Since applying the template to an existing repository is also a non-goal, this recovery path strands the user; specify a real resume/repair mechanism or give honest inspect-and-restart instructions instead of claiming the partial directory can be finished by hand.

Useful? React with 👍 / 👎.

| `create-next-app` changes its flag surface or generated layout | The pinned specifier (§7 step 2) means an upstream change does not reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. |
| `create-next-app` changes its flag surface or generated layout | The **exact** pinned version (§7 step 2) means an upstream change cannot reach users until we bump it, so this surfaces as a failing goal check on *our* release rather than as a hang in a stranger's terminal. A major-range pin would not hold that. Treated as a patch-level fix. Nothing stubbed can detect this — the goal check is the only detector. |
| The pinned `create-next-app` falls behind | New projects start on an older Next than current. Bumping the pin is scheduled maintenance gated on a goal-check run, not a reaction to breakage. |
| Init fails after the template was written | The scaffold stays. Print init's own retry command against that directory. Mirrors init's install-failure taxonomy, which also leaves files and prints the retry. |
| Install fails inside init | Init's case, not this one. It reports and this command adds nothing. |
| `-y` with no key in flags or environment | Scaffold completes. `.env.local` carries the empty key line init writes, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. |
Expand Down Expand Up @@ -468,8 +476,9 @@ init, in a temporary directory, with no network and no install, **except the thr
symptom otherwise is a second flow file appearing beside the advertised one
- **the collected provider and key reach init** — asserted on the call, so a regression shows up
as a failing test rather than a second prompt in someone's terminal
- **`create-next-app` is invoked with install skipped, every flag explicit, and the pinned major
in the specifier** — asserted on the argv, since the symptoms otherwise are "the first hour is
- **`create-next-app` is invoked with install skipped, every flag explicit, and an *exact* pinned
version in the specifier** — asserted on the argv, and the assertion rejects a range as well as
a missing pin, since `@16` silently re-resolves. The symptoms otherwise are "the first hour is
slower", "it behaved differently on my machine", and a version nobody tested
- **the printed next-steps block is byte-identical to a standalone init run** (epic theme 5)
- **every printed command runs** — execute the strings the block emitted, in the generated
Expand Down
Loading