vision.fdml

metadata:
  version: '1.4'
  author: owner
  description: 'FDML itself: the language and the tool, as two products on one repository'
  created: 2026-09-15T00:00:00Z
system:
  id: fdml
  name: FDML
  description: 'Feature-driven modelling: a spec language for what a product does, and a tool that keeps the spec, the code and the evidence in one graph'
  components:
  - parser
  - project
  - index
  - research
  - evidence
  - cli
  - core
  relationships: []
features:
- id: lang
  title: A spec language for what a product does
  description: Features with value, scenarios as given/when/then, traceability to code and tests; human-readable, diffable YAML
  scenarios: []
  layer: product
  value:
    beneficiary: user
    statement: One document says what the product does and why, and stays true against the code
    metric:
      name: features_declared
      unit: features with value in vision files
    for:
    - author
- id: lang.parse
  title: Parse and validate a document
  description: A YAML document becomes an AST; ids resolve, closed enums reject unknown values; via parse_fdml_yaml, validate_references, check_traceability_in
  scenarios:
  - id: lang.parse.s1
    title: An unknown enum value is a parse error
    given:
    - 'a feature with layer: mechanic'
    when:
    - the document is parsed
    then:
    - parsing fails naming the field
    - nothing is silently accepted
  realizes:
  - lang
- id: lang.value_graph
  title: Value graph and the gap
  description: Every feature reaches a value-bearing root by realizes; the gap compares what the vision declares with what the scan observed; via value_graph, gap
  scenarios:
  - id: lang.value_graph.s1
    title: A root without value is an error
    given:
    - a vision root feature without a value block
    when:
    - the value graph is checked
    then:
    - an error names the feature and the rule
  realizes:
  - lang
- id: lang.document_set
  title: A project is a set of documents
  description: vision files and scanned specs load as one set; accepted operations from the journal overlay it; via around, overlay_accepted, product_doc
  scenarios:
  - id: lang.document_set.s1
    title: An accepted operation reaches every reader and the exported file
    given:
    - a vision document and a pending test plan in the journal
    when:
    - the operation is accepted, then exported
    then:
    - the loaded set proves the scenario before export
    - the exported file proves it too and the operation is marked exported
    - an operation that would not apply is refused at accept
  realizes:
  - lang
- id: tool
  title: A tool that answers where, what and whether it is proven
  description: Index-first navigation, research over the product model, an operations journal for changes, evidence for scenarios, one page for all of it
  scenarios: []
  layer: product
  value:
    beneficiary: user
    statement: 'Fewer blind reads and greps: the tool answers where the code is, what the product does there, and whether a run has proven it'
    metric:
      name: blind_navigation_actions
      unit: reads and greps whose result never reaches the answer, per task
      baseline: 7.0
      target: 3.0
    for:
    - developer
    - agent
- id: tool.index
  title: Index and search
  description: Symbols, references, a micro-map per symbol; one query returns where, with marks and notes; via search, index, locate, llm_fallback
  scenarios:
  - id: tool.index.s1
    title: A concept query finds the symbol
    given:
    - an indexed repository
    when:
    - a developer searches a concept in words
    then:
    - the symbol is in the first three hits
    - a miss is reported honestly
  realizes:
  - tool
- id: tool.research
  title: 'Research: a question answered from the model'
  description: The packet from the index and the document set, coverage by layer, gaps with drafts, an answer citing packet numbers; via research, aspect, recite, plain_answer
  scenarios:
  - id: tool.research.s1
    title: Citations by id become packet numbers
    given:
    - a model answer citing features and functions by id
    when:
    - the answer is reconciled with the packet
    then:
    - known ids become numbers
    - unknown ids lose their brackets
  - id: tool.research.s2
    title: A history row without usage shows no numbers
    given:
    - a stored answer from a model, recorded before usage was captured
    when:
    - the research history is listed in the terminal
    then:
    - the row names the model and says usage is unknown
    - it prints no 0→0
    - the total counts only rows with usage
  - id: tool.research.s3
    title: Research answers from the code as it is now
    given:
    - an indexed repository with a vision
    - a function renamed after the index was built
    when:
    - a question about that function is researched
    then:
    - the packet names the function by its new name
    - the old name is not cited
  realizes:
  - tool
- id: tool.journal
  title: The operations journal
  description: Typed operations proposed, accepted by a human, overlaid on every load, exported to the file; via add_op, accept_op, export_products, apply, validate
  scenarios:
  - id: tool.journal.s1
    title: An accepted scenario is visible before export
    given:
    - a pending add_scenario operation
    when:
    - a human accepts it
    then:
    - every reader sees the scenario
    - the file is unchanged until export
  realizes:
  - tool
- id: tool.evidence
  title: Evidence for scenarios
  description: A runner's output becomes evidence entries; scenarios linked to tests become verified, failed or unknown; via translate, scenario_states, report, load_all
  scenarios:
  - id: tool.evidence.s1
    title: One run gives four scenario states
    given:
    - scenarios linked to tests, and a run payload with a verified, a failed and a missing result
    when:
    - evidence is joined with the spec
    then:
    - proven, failed, unknown and not verified are reported per scenario
    - the conditions of the run are printed with the verdict
  realizes:
  - tool
- id: tool.serve
  title: One page for the product and the work
  description: Features traced to code, research, the queue; rebuilt on every load; via run_serve_v2, product_data, report_page
  scenarios: []
  realizes:
  - tool
- id: tool.history
  title: What was built and why
  description: Commits joined to the session prompts that led to them; via history_rows, sessions
  scenarios:
  - id: tool.history.s1
    title: A commit names the ask that led to it
    given:
    - one long session with several asks and a commit after each
    when:
    - the history is listed
    then:
    - each commit shows the last ask made before it in that session
    - two commits after different asks show different asks
  - id: tool.history.s2
    title: A message sent while working is shown with the ask, never instead of it
    given:
    - a typed ask, then a remark sent while the agent works, then a commit
    when:
    - the history is listed
    then:
    - the commit shows the typed ask
    - the remark follows it marked as said while working
  realizes:
  - tool
traceability:
- from: t.research.citations
  to: tool.research.s1
  relation: verifies
- from: t.value_graph.strict
  to: lang.value_graph.s1
  relation: verifies
- from: t.evidence.four_states
  to: tool.evidence.s1
  relation: verifies
- from: t.document_set.journal_to_proof
  to: lang.document_set.s1
  relation: verifies
- from: t.parse.unknown_enum
  to: lang.parse.s1
  relation: verifies
- from: t.research.history_unknown_usage
  to: tool.research.s2
  relation: verifies
- from: t.research.fresh_index
  to: tool.research.s3
  relation: verifies
- from: t.history.nearest_ask
  to: tool.history.s1
  relation: verifies
- from: t.history.while_working
  to: tool.history.s2
  relation: verifies
tests:
- id: t.research.citations
  reference: research::tests::citations_by_id_become_packet_numbers_and_unknown_ones_lose_their_brackets
  runner: cargo-test
- id: t.value_graph.strict
  reference: project::document_set::tests::value_graph_strict_on_vision_advisory_on_generated
  runner: cargo-test
- id: t.evidence.four_states
  reference: evidence::tests::four_states_from_one_payload
  runner: cargo-test
- id: t.document_set.journal_to_proof
  reference: evidence::tests::journal_test_plan_reaches_proof
  runner: cargo-test
- id: t.parse.unknown_enum
  reference: parser::tests::an_unknown_enum_value_is_a_parse_error_naming_the_field
  runner: cargo-test
- id: t.research.history_unknown_usage
  reference: research::tests::a_history_row_without_usage_shows_no_numbers
  runner: cargo-test
- id: t.research.fresh_index
  reference: research_answers_from_the_code_as_it_is_now
  runner: cargo-test
- id: t.history.nearest_ask
  reference: index::tests::a_commit_is_joined_to_the_last_ask_before_it
  runner: cargo-test
- id: t.history.while_working
  reference: index::tests::a_commit_is_joined_to_the_last_ask_before_it
  runner: cargo-test
consumers:
- id: author
  kind: author
  description: 'Writes vision.fdml: features, scenarios, value; reads gaps and coverage'
- id: developer
  kind: user
  description: 'Navigates and changes the code: search, research, the operations journal'
- id: agent
  kind: user
  description: 'An assistant working in the repository: dossier, search, research, proposals as operations'