feat(lang): spec-level kind tag (metadata classification badge)#99
Merged
Conversation
Add an optional string tag right after the spec name that classifies the
whole spec, e.g. `spec ReturnUI "ui: screen flow" { … }`. Metadata only — it
desugars to nothing and is never verified (corpus snapshot unchanged) —
surfaced by `fslc explain` (`skeleton.spec_kind = {id, text}` + a `Kind:` line
in `--readable`) and by `fslc html` (a neutral badge next to the spec title).
Delivers the machine-readable and at-a-glance "this is a UI spec"
classification the fsl-ui spike (#9) identified, without the expand_ui dialect.
The surfaced field is `spec_kind`, not `kind`, because the enveloped result
tree reserves `kind` for the diagnostic discriminator scanned by
with_faithfulness / trace_type_for on every nested dict.
Files moved together: grammar.py + model.py (feature), explain.py +
html_report.py (surfacing), examples/ui_spike/return_ui.fsl (live example),
docs/LANGUAGE.md + skills/fsl/reference.md + docs/DESIGN-ui.md, CHANGELOG, and
regression tests. LSP + VSCode tmLanguage need no change (verified: shared
parser + generic string highlighting).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an optional spec-level tag classifying a whole spec:
Metadata only — desugars to nothing, never verified. Surfaced in three places:
fslc explainJSON →skeleton.spec_kind = {id, text}fslc explain --readable→Kind: …linefslc html→ neutral badge next to the spec titleWhy
The fsl-ui spike (#9) established that screen flows are expressible in plain FSL. The open question was whether a dedicated UI syntax adds value. Conclusion: no formal-semantics gain (a dialect desugars to the same kernel), but a machine-readable + at-a-glance "this is a UI spec" classification does. This is the cheap Tier-1 purchase of that benefit — spec-unit classification without the lossy
expand_uidialect (screen/navigateline-level vocabulary, deferred until demand; that is where cost jumps discontinuously and the F-UI-2/3/4 expander risk lives). Seedocs/DESIGN-ui.md.Design note
The surfaced field is
spec_kind, notkind: the enveloped result tree reserveskindfor the string diagnostic discriminator thatwith_faithfulness/trace_type_forscan on every nested dict. Akinddict there crashes the walker (unhashable type: 'dict'); a regression test pins the CLI envelope path.Verification
return_ui.fsl: stillproved+refines.parse_src/build_spec;_TOP_LEVEL_NAMEcaptures the name before the tag; generic string highlighting covers the tag).11 files, +116/−8. bmc/runtime untouched (no concrete semantics); no new files (no SPDX); corpus snapshot not regenerated (unchanged).
🤖 Generated with Claude Code