Relationship to #979
#979 already covers examples/e2e/README.md (5 occurrences) and its verbatim pin in tests/test_e2e_example.py. This issue does not restate that; it is filed because the same defect class survives in 12 further files / 36 further occurrences that #979 does not enumerate, and because two of those groups need handling #979's proposal does not describe.
If #979 is closed by an e2e-only PR, the 36 occurrences below remain. That is why this is a separate issue rather than a comment on #979.
Defect class
Taken verbatim from the fix in 97f2b16c:
A hand-written document's execution example passes --deadlock ignore to the reader, where the referenced spec verifies clean without the flag.
--deadlock ignore uniformly suppresses deadlock checking for all stopping states. docs/LANGUAGE.md:770-776 teaches that terminal { <predicate> } is the precise alternative, and docs/LANGUAGE.md:2287-2294 documents that process sinks auto-generate a terminal { }, so a stage-graph spec normally verifies clean without the flag. #979 measured that for the e2e chain the flag was suppressing a diagnostic that passes — stronger than merely unnecessary.
Enumeration — 36 occurrences / 12 files (e2e excluded; see #979)
"Exec example?" = does the line instruct the reader to run a command, as opposed to reporting a past observation?
"Measured?" is no for every row below. Nothing here has been measured. Listing an occurrence is not a claim that its flag is unnecessary.
| path:line |
Exec example? |
Target spec |
Measured? |
examples/ui_spike/README.md:18 |
yes |
examples/ui_spike/navstack.fsl |
no |
examples/nfr/README.md:29,30 |
yes |
examples/nfr/sla_worker.fsl |
no |
examples/agentic_rag/README.md:86,91,95,101,121 |
yes |
agentic_rag_requirements.fsl and siblings |
no |
examples/agentic_rag/IMPLEMENTATION_CONFORMANCE.md:29 |
yes |
agentic_rag |
no |
examples/agentic_rag/mutation_slices/README.md:24,27,30,33 |
yes |
mutation slices |
no |
examples/agentic_rag/mutation_slices/SURVIVOR_REVIEW.md:73,74,82 |
no — records observed results |
agentic_rag |
no |
examples/pm/README.md:30,33,36 |
yes |
cancel_flow.fsl, cancel_system.fsl |
no |
examples/multi_agent_system/README.md:60,66,73,90 |
yes |
multi_agent_system |
no |
examples/multi_agent_system/IMPLEMENTATION_CONFORMANCE.md:40 |
yes |
multi_agent_system |
no |
examples/refinement_liveness/README.md:29,34,39 |
yes |
policy.fsl, design_{drops,keeps}_liveness.fsl |
no |
examples/layers/README.md:13,14,17 |
yes |
return_policy.fsl, return_system.fsl |
no |
examples/consulting/README.md:41,42 |
yes |
asis_expense.fsl, tobe_expense.fsl |
no |
examples/gallery/README.md:14,15,17,20 |
yes (table column) |
4 gallery specs |
no — machine-pinned, see below |
No per-row fix is proposed. Whether the flag is unnecessary must be measured per spec with the native fslc, cache bypassed (--no-cache), at least twice, produced value recorded beside expected. Removing the flag from a spec that genuinely deadlocks would either break a documented example or hide a missing terminal { } declaration — the same direction of error 97f2b16c was fixing.
Two groups need treatment #979's proposal does not describe:
1. examples/gallery/ is pinned in three places — repair moves all three or none
The same command string is fixed in:
examples/gallery/README.md (table column) — e.g. line 15
- the spec's own
// expected-command: comment — e.g. examples/gallery/valid/small_vending_machine.fsl:4
tests/test_gallery.py — e.g. line 30, GalleryCase("valid/small_vending_machine.fsl", "verify --depth 6 --deadlock ignore", "verified")
expected-command: comments are machine-read by rust/fslc/tests/corpus_expectation_manifest.rs and rust/fslc/tests/corpus_check_sweep.rs, which run inside the required rust workspace job. Editing the README alone makes the document disagree with a gate that still pins the flag. Unlike #979's tests/test_e2e_example.py (exempt tier), this pin is required-gate-reachable, so a partial fix fails CI rather than passing silently.
2. SURVIVOR_REVIEW.md:73,74,82 report results, they do not instruct
These lines state observed verdicts (: verified). Deleting the flag would falsify a record of what was run. They need re-measurement and restatement, not deletion.
Sweep pitfalls — do not judge this class by grep count
rg -- '--deadlock' returns 412 hits; rg -- '--deadlock[= ]ignore' returns 108. Neither is the instance count. Every occurrence outside examples/ was opened individually, and each is a non-instance for a different reason:
docs/intro/quickstart.{en,ja}.html:118 and docs/intro/traces/order_fixed.json:183 — a verbatim quote of the verifier's own hint string inside a displayed JSON envelope. The string is implemented at rust/fsl-runtime/src/lib.rs:2732 (frozen mirror: src/fslc/bmc.py:5175). The callout directly beneath tells the reader to declare a terminal { } block and not to skip warnings unread. A count-driven sweep would edit these and corrupt a verbatim reproduction of real tool output.
docs/intro/errors.{en,ja}.html:61 — --deadlock error, the strictest value. The opposite of suppression.
docs/intro/language.{en,ja}.html — generated. Its sources docs/LANGUAGE.md:774,2291 and docs/LANGUAGE.ja.md:748,2224 argue against the flag ("Whereas --deadlock ignore uniformly ignores all stopping states, terminal lets you select which stops are intentional"; "therefore verifies clean at Rejected/Refunded without --deadlock ignore").
skills/fsl/SKILL.md:300, skills/fsl-business/SKILL.md:60, skills/fsl/references/layers.md:252, skills/fsl/references/syntax.md:919 — all recommend terminal { } and deprecate the flag.
docs/DESIGN-v1.md:401,561, docs/DESIGN-dialects.md:294, docs/DESIGN-ledger.md:56 — definitions of the flag's semantics, not execution examples. DESIGN-dialects.md:294 states it "is no longer required".
tests/*, rust/fslc/tests/* — assertions on the flag's behavior. tests/test_dialect_terminal.py:62,167 and tests/test_self_examples.py:20 say the opposite ("no --deadlock ignore needed").
*.fsl // expected-command: comments, CHANGELOG.md — machine-readable expectation declarations, and history.
docs/intro/ (hand-written and generated) therefore has 0 surviving instances after 97f2b16c. That was established by reading all of the above, not by counting.
Rule for whoever picks this up: open every occurrence. The count is not the finding.
Following #979: no new check
#979 argues that adding a check for "must not contain --deadlock ignore" fails the 4-condition test for a new validator — it bans one option name rather than capturing suppression in general, so the shortest way to pass it diverges from the requirement. That reasoning applies unchanged here. This issue proposes no new validator. For the gallery rows the existing pins (items 1-3 above), once corrected, already fix the right strings.
Why this is filed rather than fixed
Found while integrating origin/main into site/first-correctness-chain. docs/intro/ is that branch's surface and is clean; examples/ is a different surface, the branch's diff is already 3497 lines, and resolving the table needs a per-spec fslc measurement that was not authorized in that task.
Acceptance
- Every row measured with native
fslc, --no-cache, ≥2 runs, produced recorded beside expected
- Flag removed only where measured unnecessary; where a real unintended stop exists, a
terminal { } declaration added instead of a blanket suppression
- Gallery rows: README +
.fsl expected-command: + tests/test_gallery.py moved in one change
SURVIVOR_REVIEW.md rows re-measured and restated, not silently edited
- A negative control showing the deadlock diagnostic still fires for a spec that genuinely deadlocks
Relationship to #979
#979 already covers
examples/e2e/README.md(5 occurrences) and its verbatim pin intests/test_e2e_example.py. This issue does not restate that; it is filed because the same defect class survives in 12 further files / 36 further occurrences that #979 does not enumerate, and because two of those groups need handling #979's proposal does not describe.If #979 is closed by an e2e-only PR, the 36 occurrences below remain. That is why this is a separate issue rather than a comment on #979.
Defect class
Taken verbatim from the fix in
97f2b16c:--deadlock ignoreuniformly suppresses deadlock checking for all stopping states.docs/LANGUAGE.md:770-776teaches thatterminal { <predicate> }is the precise alternative, anddocs/LANGUAGE.md:2287-2294documents that process sinks auto-generate aterminal { }, so a stage-graph spec normally verifies clean without the flag. #979 measured that for the e2e chain the flag was suppressing a diagnostic that passes — stronger than merely unnecessary.Enumeration — 36 occurrences / 12 files (e2e excluded; see #979)
"Exec example?" = does the line instruct the reader to run a command, as opposed to reporting a past observation?
"Measured?" is
nofor every row below. Nothing here has been measured. Listing an occurrence is not a claim that its flag is unnecessary.examples/ui_spike/README.md:18examples/ui_spike/navstack.fslexamples/nfr/README.md:29,30examples/nfr/sla_worker.fslexamples/agentic_rag/README.md:86,91,95,101,121agentic_rag_requirements.fsland siblingsexamples/agentic_rag/IMPLEMENTATION_CONFORMANCE.md:29examples/agentic_rag/mutation_slices/README.md:24,27,30,33examples/agentic_rag/mutation_slices/SURVIVOR_REVIEW.md:73,74,82examples/pm/README.md:30,33,36cancel_flow.fsl,cancel_system.fslexamples/multi_agent_system/README.md:60,66,73,90examples/multi_agent_system/IMPLEMENTATION_CONFORMANCE.md:40examples/refinement_liveness/README.md:29,34,39policy.fsl,design_{drops,keeps}_liveness.fslexamples/layers/README.md:13,14,17return_policy.fsl,return_system.fslexamples/consulting/README.md:41,42asis_expense.fsl,tobe_expense.fslexamples/gallery/README.md:14,15,17,20No per-row fix is proposed. Whether the flag is unnecessary must be measured per spec with the native
fslc, cache bypassed (--no-cache), at least twice, produced value recorded beside expected. Removing the flag from a spec that genuinely deadlocks would either break a documented example or hide a missingterminal { }declaration — the same direction of error97f2b16cwas fixing.Two groups need treatment #979's proposal does not describe:
1.
examples/gallery/is pinned in three places — repair moves all three or noneThe same command string is fixed in:
examples/gallery/README.md(table column) — e.g. line 15// expected-command:comment — e.g.examples/gallery/valid/small_vending_machine.fsl:4tests/test_gallery.py— e.g. line 30,GalleryCase("valid/small_vending_machine.fsl", "verify --depth 6 --deadlock ignore", "verified")expected-command:comments are machine-read byrust/fslc/tests/corpus_expectation_manifest.rsandrust/fslc/tests/corpus_check_sweep.rs, which run inside the requiredrust workspacejob. Editing the README alone makes the document disagree with a gate that still pins the flag. Unlike #979'stests/test_e2e_example.py(exempt tier), this pin is required-gate-reachable, so a partial fix fails CI rather than passing silently.2.
SURVIVOR_REVIEW.md:73,74,82report results, they do not instructThese lines state observed verdicts (
: verified). Deleting the flag would falsify a record of what was run. They need re-measurement and restatement, not deletion.Sweep pitfalls — do not judge this class by grep count
rg -- '--deadlock'returns 412 hits;rg -- '--deadlock[= ]ignore'returns 108. Neither is the instance count. Every occurrence outsideexamples/was opened individually, and each is a non-instance for a different reason:docs/intro/quickstart.{en,ja}.html:118anddocs/intro/traces/order_fixed.json:183— a verbatim quote of the verifier's own hint string inside a displayed JSON envelope. The string is implemented atrust/fsl-runtime/src/lib.rs:2732(frozen mirror:src/fslc/bmc.py:5175). The callout directly beneath tells the reader to declare aterminal { }block and not to skip warnings unread. A count-driven sweep would edit these and corrupt a verbatim reproduction of real tool output.docs/intro/errors.{en,ja}.html:61—--deadlock error, the strictest value. The opposite of suppression.docs/intro/language.{en,ja}.html— generated. Its sourcesdocs/LANGUAGE.md:774,2291anddocs/LANGUAGE.ja.md:748,2224argue against the flag ("Whereas--deadlock ignoreuniformly ignores all stopping states,terminallets you select which stops are intentional"; "therefore verifies clean atRejected/Refundedwithout--deadlock ignore").skills/fsl/SKILL.md:300,skills/fsl-business/SKILL.md:60,skills/fsl/references/layers.md:252,skills/fsl/references/syntax.md:919— all recommendterminal { }and deprecate the flag.docs/DESIGN-v1.md:401,561,docs/DESIGN-dialects.md:294,docs/DESIGN-ledger.md:56— definitions of the flag's semantics, not execution examples.DESIGN-dialects.md:294states it "is no longer required".tests/*,rust/fslc/tests/*— assertions on the flag's behavior.tests/test_dialect_terminal.py:62,167andtests/test_self_examples.py:20say the opposite ("no--deadlock ignoreneeded").*.fsl// expected-command:comments,CHANGELOG.md— machine-readable expectation declarations, and history.docs/intro/(hand-written and generated) therefore has 0 surviving instances after97f2b16c. That was established by reading all of the above, not by counting.Rule for whoever picks this up: open every occurrence. The count is not the finding.
Following #979: no new check
#979 argues that adding a check for "must not contain
--deadlock ignore" fails the 4-condition test for a new validator — it bans one option name rather than capturing suppression in general, so the shortest way to pass it diverges from the requirement. That reasoning applies unchanged here. This issue proposes no new validator. For the gallery rows the existing pins (items 1-3 above), once corrected, already fix the right strings.Why this is filed rather than fixed
Found while integrating
origin/mainintosite/first-correctness-chain.docs/intro/is that branch's surface and is clean;examples/is a different surface, the branch's diff is already 3497 lines, and resolving the table needs a per-specfslcmeasurement that was not authorized in that task.Acceptance
fslc,--no-cache, ≥2 runs, produced recorded beside expectedterminal { }declaration added instead of a blanket suppression.fslexpected-command:+tests/test_gallery.pymoved in one changeSURVIVOR_REVIEW.mdrows re-measured and restated, not silently edited