[zpyoung]

Summary

Logic-spec scenarios can now carry an optional data-state example: the records before, a numbered walkthrough, and the records after. The Then stays the contract, and the example is a checked restatement of it. Spec: logic.md, tech.md.

• render_spec.py validates the example field, and an open [ASK] gap blocks its scenario's sign-off until the answer is in the Then. logic.md renders each example as labelled sub-bullets. Specs without examples render byte-for-byte as before, and the new goldens in tests/test_render_goldens.py hold that.
• The review page shows the example in the scenario focus dialog as three panes. Results, rejections, invented values and gaps are coloured. When the reviewer picks a different outcome, the page fills in the rewrite request so Claude updates the Then and the example together.
• skills/writing-specs/scenario-examples.md is the one copy of the conventions, and both rubrics link to it.
• Not everything is a data state, so an example can also carry a details section: one Markdown block under a one-line title, such as "Screen states". It can replace the data-state parts or sit beside them, and it follows the same rules (the Then is the contract, marks are coloured, an open [ASK] blocks). On the page it sits full-width below the three columns, with tables, lists and code blocks intact and code shown exactly as written. In logic.md it's a sub-bullet labelled with its title. This was added through a dated amendment to the logic spec.

Fixes that apply page-wide, beyond examples:

• A link in any page Markdown renders as a link only for http(s):, mailto: and # targets. Before this, [x](jAvAsCrIp:...) produced a live script link.
• logic.json text fields are capped at 10,000 characters (BUG-13). The Astryx Markdown parser is quadratic per paragraph, and 400k characters of [a]( froze the page for seconds. The cap keeps the worst field to about 24ms.

Review

Five rounds of adversarial review with a cross-family reviewer (correctness, spec and security lenses) ran up to the round cap. Every CRITICAL and HIGH finding is fixed.

• C1 (4*,5* greyed only the first value) and C3 (a lone CR line ending didn't break) were fixed after round 5. Both have tests and passed the full suite, but no further review round looked at them.
• The details sections had one more review round. Security came back clean. Three MEDIUM findings were fixed: a code fence opened on a list-marker line, backslash-escaped backticks, and underscores in link URLs. No further round looked at those fixes. The same link-URL defect in the page-wide SpecMarkdown predates this branch and is logged as BUG-14.
• Known limitation: a literal U+E001 in example text renders as U+E000. The example pane uses those private-use characters internally, and real example text doesn't contain them.

Test plan

• python3 -m pytest -q: 1271 passed
• pnpm run check in skills/writing-specs/interactive/app: typecheck, layout, example and template checks pass, and review-template.html matches a fresh build
• render_spec.py render on a spec with a 400k-character field exits 1 with the field's pointer and writes no review.html. At 10,000 characters it renders.
• Open a rendered review of the examples fixture (tests/fixtures/interactive/v2/examples) and check the three panes and colours in the focus dialog
• Open a rendered review of the details fixture (tests/fixtures/interactive/v2/details) and check the titled pane, the table, and the layout when a scenario has both forms

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.