Skip to content

fix(examples): --deadlock ignore を教える実行例が examples 配下の12ファイル・36箇所に残っている(#979 の e2e 以外の全数) #998

Description

@rizumita

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:

  1. examples/gallery/README.md (table column) — e.g. line 15
  2. the spec's own // expected-command: comment — e.g. examples/gallery/valid/small_vending_machine.fsl:4
  3. 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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ai-discoveredIssues created from scoped follow-up discoverybugSomething isn't working

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions