Problem
examples/e2e/README.md teaches the reader to invoke the frozen Python compatibility reference as if it were the product, and a required-tier test pins those exact strings so the wording cannot drift back on its own.
examples/e2e/README.md:32 ./.venv/bin/python -m fslc verify examples/e2e/1_business.fsl --engine induction --deadlock ignore
examples/e2e/README.md:35 ./.venv/bin/python -m fslc verify examples/e2e/2_requirements.fsl --deadlock ignore
examples/e2e/README.md:38 ./.venv/bin/python -m fslc verify examples/e2e/2_requirements.fsl --engine induction --deadlock ignore
examples/e2e/README.md:41 ./.venv/bin/python -m fslc scenarios examples/e2e/2_requirements.fsl --deadlock ignore
examples/e2e/README.md:44 ./.venv/bin/python -m fslc verify examples/e2e/3_design.fsl --engine induction --deadlock ignore
tests/test_e2e_example.py:78-82 asserts those five command strings verbatim.
Why this is a defect
AGENTS.md ("Project and authority") states:
The native Rust workspace under rust/ is the authoritative implementation and distribution surface. The Python package under src/fslc/ is a frozen compatibility reference; do not add product behavior there unless a compatibility change explicitly requires it.
and the generated CLI reference page already says the frozen reference "mirrors a subset for parity tests only — it is not the distribution surface".
So the flagship end-to-end walkthrough — the most likely first thing a new reader runs — documents the non-distribution surface as the way to use FSL. docs/intro/business-layer.{en,ja}.html already prints the same chain as native:
$ fslc verify examples/e2e/1_business.fsl --engine induction
$ fslc verify examples/e2e/2_requirements.fsl --engine induction
$ fslc refine examples/e2e/3_design.fsl examples/e2e/2_requirements.fsl examples/e2e/3_refines_2.fsl --depth 8
The site and the example README now disagree about which binary is authoritative for the same chain.
This is an authority defect, not a spec-weakening one, which is why it is filed separately from #979.
Coupling — the two issues collide in one file
#979 wants the --deadlock ignore flag re-measured and likely removed from these same five lines. This issue wants the invocation moved to native fslc. Both edit examples/e2e/README.md:32-44 and both force tests/test_e2e_example.py:78-82 to move. Doing them in separate passes means rewriting the same five lines and the same test block twice.
Whoever takes either issue should check the other first; they may be cheaper as one change. They are filed separately because the classes differ (suppression-flag teaching vs. authority surface) and because either could be accepted without the other.
Scope question for the assignee
tests/test_e2e_example.py is a Python-driven test whose purpose is partly to exercise the frozen reference. Two readings:
- The README should show native
fslc and the test should assert the native commands (the test's parity role moves elsewhere, e.g. an existing rust/fslc/tests/ contract).
- The test legitimately pins Python invocations for parity, and the README is the only thing that should change — the test then stops being a verbatim mirror of the README.
Reading 2 is smaller but leaves the test asserting strings that no document shows. This needs a decision before implementation; do not pick silently.
Note also that .venv/bin/python embeds an assumption about a developer's local virtualenv layout that the repository does not otherwise require.
Why this is filed rather than fixed
Found while integrating origin/main into site/first-correctness-chain. That branch's surface is docs/intro/; examples/ and tests/ are a different surface, its diff is already 3497 lines, and the scope question above is not the integrating task's call to make.
Acceptance
examples/e2e/README.md presents the flagship chain on the authoritative native surface, matching what docs/intro/business-layer.{en,ja}.html prints- The scope question above is answered explicitly in the PR, not decided by omission
tests/test_e2e_example.py and the README do not disagree about which commands are canonical- Every command shown is executed and its produced result recorded, not carried over from the old text
Problem
examples/e2e/README.mdteaches the reader to invoke the frozen Python compatibility reference as if it were the product, and a required-tier test pins those exact strings so the wording cannot drift back on its own.tests/test_e2e_example.py:78-82asserts those five command strings verbatim.Why this is a defect
AGENTS.md("Project and authority") states:and the generated CLI reference page already says the frozen reference "mirrors a subset for parity tests only — it is not the distribution surface".
So the flagship end-to-end walkthrough — the most likely first thing a new reader runs — documents the non-distribution surface as the way to use FSL.
docs/intro/business-layer.{en,ja}.htmlalready prints the same chain as native:The site and the example README now disagree about which binary is authoritative for the same chain.
This is an authority defect, not a spec-weakening one, which is why it is filed separately from #979.
Coupling — the two issues collide in one file
#979wants the--deadlock ignoreflag re-measured and likely removed from these same five lines. This issue wants the invocation moved to nativefslc. Both editexamples/e2e/README.md:32-44and both forcetests/test_e2e_example.py:78-82to move. Doing them in separate passes means rewriting the same five lines and the same test block twice.Whoever takes either issue should check the other first; they may be cheaper as one change. They are filed separately because the classes differ (suppression-flag teaching vs. authority surface) and because either could be accepted without the other.
Scope question for the assignee
tests/test_e2e_example.pyis a Python-driven test whose purpose is partly to exercise the frozen reference. Two readings:fslcand the test should assert the native commands (the test's parity role moves elsewhere, e.g. an existingrust/fslc/tests/contract).Reading 2 is smaller but leaves the test asserting strings that no document shows. This needs a decision before implementation; do not pick silently.
Note also that
.venv/bin/pythonembeds an assumption about a developer's local virtualenv layout that the repository does not otherwise require.Why this is filed rather than fixed
Found while integrating
origin/mainintosite/first-correctness-chain. That branch's surface isdocs/intro/;examples/andtests/are a different surface, its diff is already 3497 lines, and the scope question above is not the integrating task's call to make.Acceptance
examples/e2e/README.mdpresents the flagship chain on the authoritative native surface, matching whatdocs/intro/business-layer.{en,ja}.htmlprintstests/test_e2e_example.pyand the README do not disagree about which commands are canonical