markdown_exec 3.5.1 → 3.5.2

data/architecture-decisions.md

@@ -0,0 +1,190 @@
+# Architecture Decisions
+
+**STDD Methodology Version**: 1.0.0
+
+## Overview
+This document captures the high-level architectural decisions for your project. All decisions are cross-referenced with requirements using semantic tokens `[REQ:*]` and assigned architecture tokens `[ARCH:*]` for traceability.
+
+## 1. Language and Runtime [ARCH:LANGUAGE_SELECTION]
+
+### Decision: [Your Language/Runtime Choice]
+**Rationale:**
+- Reason 1
+- Reason 2
+- Reason 3
+
+**Alternatives Considered:**
+- Alternative 1: Why it was rejected
+- Alternative 2: Why it was rejected
+
+## 2. Project Structure [ARCH:PROJECT_STRUCTURE]
+
+### Decision: [Your Project Structure]
+```
+project-root/
+├── src/                    # Source code
+├── tests/                   # Test files
+├── docs/                    # Documentation
+└── config/                  # Configuration files
+```
+
+**Rationale:**
+- Clear separation of concerns
+- Standard project layout
+- Testable components
+
+## 3. Core Architecture Decision [ARCH:EXAMPLE_DECISION] [REQ:EXAMPLE_FEATURE]
+
+### Decision: [Your Architecture Choice]
+**Rationale:**
+- Matches requirement [REQ:EXAMPLE_FEATURE]
+- Provides benefits X, Y, Z
+- Simpler implementation
+
+**Alternatives Considered:**
+- Alternative approach: More complex, less maintainable
+
+**Implementation:**
+- High-level approach
+- Key components
+- Integration points
+
+## 4. Data Management [ARCH:DATA_MANAGEMENT] [REQ:DATA_REQUIREMENT]
+
+### Decision: [Your Data Management Approach]
+**Rationale:**
+- Reason 1
+- Reason 2
+
+**Implementation:**
+- Storage approach
+- Data access patterns
+- Consistency model
+
+## 5. Error Handling Strategy [ARCH:ERROR_HANDLING] [REQ:ERROR_HANDLING]
+
+### Decision: [Your Error Handling Approach]
+**Rationale:**
+- Idiomatic for chosen language/framework
+- Clear error propagation
+- Easy to test
+
+**Pattern:**
+- Error types
+- Error propagation
+- Error reporting
+
+## 6. Testing Strategy [ARCH:TESTING_STRATEGY]
+
+### Decision: [Your Testing Approach]
+**Rationale:**
+- Comprehensive test coverage
+- Fast unit tests
+- Integration tests for end-to-end scenarios
+- Aligns with validation criteria defined in requirements [REQ:*]
+
+**Structure:**
+- Unit test organization
+- Integration test organization
+- Test fixtures and utilities
+
+**Note**: This testing strategy implements the validation criteria specified in `requirements.md`. Each requirement's validation criteria informs what types of tests are needed (unit, integration, manual verification, etc.).
+
+## 7. Dependency Management [ARCH:DEPENDENCY_MANAGEMENT]
+
+### Decision: [Your Dependency Management Approach]
+**Rationale:**
+- Reduce external dependencies
+- Faster builds
+- Fewer security concerns
+
+**Allowed Dependencies:**
+- Standard library only (or minimal external dependencies)
+- Consider external packages only if standard library is insufficient
+
+## 8. Build and Distribution [ARCH:BUILD_DISTRIBUTION]
+
+### Decision: [Your Build and Distribution Approach]
+**Rationale:**
+- Easy deployment
+- No runtime dependencies
+- Cross-platform support
+
+**Build Targets:**
+- Platform 1
+- Platform 2
+- Platform 3
+
+## 9. Code Organization Principles [ARCH:CODE_ORGANIZATION]
+
+### Decision: [Your Code Organization Approach]
+**Rationale:**
+- Testable components
+- Clear responsibilities
+- Easy to extend
+- Maintainable codebase
+
+**Principles:**
+- Each module has a single, clear responsibility
+- Functions are small and focused
+- Interfaces where appropriate for testability
+- Avoid global state where possible
+
+## 10. Shebang Line Extraction During Cached Nested Read [ARCH:SHEBANG_EXTRACTION] [REQ:SHEBANG_HIDING]
+
+### Decision: Extract shebang lines during the cached nested file read process
+**Rationale:**
+- Matches requirement [REQ:SHEBANG_HIDING] to extract shebang lines during cached nested read
+- Centralizes file processing logic in `CachedNestedFileReader`
+- Ensures consistent behavior across all file reads (including nested imports)
+- Leverages existing file caching mechanism to avoid re-processing
+- Single point of control for shebang handling simplifies maintenance
+
+**Alternatives Considered:**
+- Post-processing filter: More complex, requires additional pass over processed lines
+- Separate shebang extraction pass: Less efficient, duplicates file reading
+- Per-component filtering: Inconsistent behavior, harder to maintain
+
+**Implementation:**
+- Modify `CachedNestedFileReader#readlines` to detect and filter shebang lines inline during segment reading
+- Shebang detection: Lines starting with `#!` at the beginning of file content (first line, index 0)
+- Filtering occurs before segments are processed into `NestedLine` objects, improving efficiency
+- Filtering controlled by CLI option stored as instance variable `@hide_shebang` in `CachedNestedFileReader`
+- Apply filtering recursively to nested imports (same instance variable used in recursive calls)
+
+**Integration Points:**
+- `CachedNestedFileReader` receives option via `hide_shebang` parameter during initialization
+- Option stored as `@hide_shebang` instance variable
+- Filtering applied inline during `File.readlines` loop using `next` to skip shebang segments
+- Filtered segments never enter the processing pipeline, ensuring they don't appear in `processed_lines` array
+
+## 11. CLI Option Design for Shebang Hiding [ARCH:CLI_OPTION_DESIGN] [REQ:SHEBANG_HIDING]
+
+### Decision: Add CLI option `hide_shebang` (default: true) to control shebang line visibility
+**Rationale:**
+- Matches requirement [REQ:SHEBANG_HIDING] for CLI option with default enabled
+- Follows existing CLI option patterns in MDE (see `menu.src.yml`)
+- Default enabled provides better UX (most users don't want shebang in output)
+- Option name `hide_shebang` is clear and descriptive
+- Supports both CLI flag and environment variable (consistent with MDE patterns)
+
+**Alternatives Considered:**
+- `show_shebang` (default: false): Less intuitive, requires negation logic
+- `no_hide_shebang`: Double negative is confusing
+- `include_shebang` (default: false): Less clear about default behavior
+
+**Implementation:**
+- Add option to `menu.src.yml` with:
+  - `opt_name: hide_shebang`
+  - `env_var: MDE_HIDE_SHEBANG`
+  - `default: true`
+  - `procname: val_as_bool`
+- Option accessible via `--hide-shebang` / `--no-hide-shebang` flags
+- Option accessible via `MDE_HIDE_SHEBANG` environment variable
+- Option passed to `CachedNestedFileReader` during initialization or read calls
+
+**Integration Points:**
+- `MarkParse#base_options` includes the option
+- `CachedNestedFileReader` receives option value
+- Option value controls filtering behavior in `readlines` method
+

data/bats/block-hide.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'hide blocks' {
+@test 'hides blocks marked as hidden' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-hide.md \
    'visible'
 }

data/bats/block-type-bash.bats

@@ -2,20 +2,20 @@
 
 load 'test_helper'
 
-@test 'Bash blocks - default' {
+@test 'executes bash block with default shell' {
   BATS_OUTPUT_FILTER=A
   spec_mde_args_expect docs/dev/block-type-bash.md block-with-no-shell-type \
    ' species'
 }
 
-@test 'Bash blocks - specified Bash' {
+@test 'executes bash block with bash shell' {
   BATS_OUTPUT_FILTER=A
   export MDE_BLOCK_TYPE_DEFAULT=bash
   spec_mde_args_expect docs/dev/block-type-bash.md bash \
    ' genus detected_shell: bash'
 }
 
-@test 'Bash blocks - specified Fish' {
+@test 'executes bash block with fish shell' {
   skip 'Fish shell is not testable'
   BATS_OUTPUT_FILTER=A
   export MDE_BLOCK_TYPE_DEFAULT=fish
@@ -23,14 +23,14 @@ load 'test_helper'
    ' family detected_shell: fish'
 }
 
-@test 'Bash blocks - specified Sh' {
+@test 'executes bash block with sh shell' {
   BATS_OUTPUT_FILTER=A
   export MDE_BLOCK_TYPE_DEFAULT=sh
   spec_mde_args_expect docs/dev/block-type-bash.md sh \
    ' family detected_shell: sh'
 }
 
-@test 'Bash blocks - specified nickname' {
+@test 'executes bash block with nickname' {
   BATS_OUTPUT_FILTER=A
   unset MDE_BLOCK_TYPE_DEFAULT
   spec_mde_args_expect docs/dev/block-type-bash.md \[show-shell-version\] \

data/bats/block-type-link.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'Link blocks - set variable in link block; call hidden block' {
+@test 'sets variable in link block and calls hidden block' {
   # __Exit is required as last block is a Link type
   run_mde_specs_md_args_expect_xansi '[VARIABLE1]' $EXIT_MENU ' VARIABLE1: 1'
   run_mde_specs_md_args_expect_xansi '[VARIABLE1]' '(echo-VARIABLE1)' ' VARIABLE1: 1   VARIABLE1: 1'

data/bats/block-type-opts.bats

@@ -4,19 +4,19 @@ load 'test_helper'
 
 # Type: Opts
 
-@test 'Opts block - before' {
+@test 'applies opts block before command execution' {
   skip 'Fails because command executes after the block is processed'
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-opts.md \
    'BEFORE Species_menu_note_format: "AFTER %{line}" '
 }
 
-@test 'Opts block - after' {
+@test 'applies opts block after command execution' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-opts.md \
    '[decorate-note]' \
    'AFTER Species_menu_note_format: "AFTER %{line}"'
 }
 
-@test 'Opts block - show that menu has changed' {
+@test 'shows menu changes from opts block' {
   skip 'Unable to show that menu has changed'
   spec_mde_args_expect docs/dev/block-type-opts.md '[decorate-note]' \
    'AFTER Species'

data/bats/block-type-port.bats

@@ -3,13 +3,13 @@
 load 'test_helper'
 
 # includes output from assignment and from shell block
-@test 'Port block - export variable' {
+@test 'exports variable from port block' {
   BATS_OUTPUT_FILTER=A
   spec_mde_args_expect docs/dev/block-type-port.md '[set_vault_1]' show \
    'VAULT = 1  VAULT: 1'
 }
 
-@test 'Port block - export variable - not set' {
+@test 'reports when exported variable not set' {
   BATS_OUTPUT_FILTER=A
   spec_mde_args_expect docs/dev/block-type-port.md VAULT-is-export show \
    '   VAULT: This variable has not been set.'

data/bats/block-type-shell-require-ux.bats

@@ -2,12 +2,12 @@
 
 load 'test_helper'
 
-@test 'initial' {
+@test 'displays initial values before UX block activation' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-shell-require-ux.md \
    'require-a-UX-block__FULL_NAME='
 }
 
-@test 'activated' {
+@test 'updates values when UX block activated' {
   # 2025-11-13 add a '.' block to force the display to update
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-shell-require-ux.md \
    require-a-UX-block . \

data/bats/block-type-ux-allowed.bats

@@ -2,26 +2,26 @@
 
 load 'test_helper'
 
-@test 'automatic blocks load defaults - constants or first allowed from output of echo or exec' {
+@test 'loads defaults from constants or first allowed value' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-allowed.md \
    'SPECIES=Pongo tapanuliensis_GENUS=Pongo_FAMILY=_ORDER: Click to select..._Click to select..._YEAR_DISCOVERED=_NAME=Tapanuli Orangutan'
 }
 
-@test 'executing a block loads the first allowed value' {
+@test 'loads first allowed value when block executed' {
   skip 'Unable to test the menu presented'
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-allowed.md \
    '[FAMILY]' \
    'SPECIES=Pongo tapanuliensis_GENUS=Pongo_FAMILY=Hominidae_Click to select...Click to select..._YEAR_DISCOVERED=_NAME='
 }
 
-@test 'executing a block loads the first line in the output of exec' {
+@test 'loads first line from exec output when block executed' {
   skip 'Unable to test the menu presented'
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-allowed.md \
    '[YEAR_DISCOVERED]' \
    'SPECIES=Pongo tapanuliensis_GENUS=Pongo_FAMILY=_YEAR_DISCOVERED=2017_NAME='
 }
 
-@test 'executing a block loads the first line in the output of echo' {
+@test 'loads first line from echo output when block executed' {
   skip 'Unable to test the menu presented'
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-allowed.md \
    '[NAME]' \

data/bats/block-type-ux-auto.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'Initial values' {
+@test 'displays initial auto values' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-auto.md \
    'v1 = _v2 = _v3 = 12_v4 = 21_v5 = markdown_exec__v6 = 31'
 }

data/bats/block-type-ux-chained.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'A UX block requires other read-only UX blocks that operate on the computed value.' {
+@test 'requires chained read-only UX blocks for computed value' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-chained.md \
    '[SPECIES]' \
    'SPECIES=Pongo tapanuliensis_NAME=Pongo tapanuliensis - Pongo'

data/bats/block-type-ux-default.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'Initial values' {
+@test 'displays initial variable values' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-default.md \
    'v1 = _v2 = 11_v3 = 12_v4 = 21_v5 = markdown_exec__v6 = 31'
 }

data/bats/block-type-ux-echo-hash-transform.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'Each key in the echo hash is processed.' {
+@test 'processes each key in echo hash with transform' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo-hash-transform.md \
    'Tapanuli Orangutan_Species: PONGO TAPANULIENSIS_Genus: PONGO_Tapanuli Orangutan_Family: H:Hominidae_Order: P:Primates_Psychedelic Frogfish_Species2:  Haccdeeehhiiilnopprsstyy_Genus2: Hehiinoprsty_Family2: Aaadeeiinnnrt'
 }

data/bats/block-type-ux-echo-hash.bats

@@ -2,12 +2,12 @@
 
 load 'test_helper'
 
-@test 'an automatic block sets multiple variables' {
+@test 'automatic block sets multiple variables from echo hash' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo-hash.md \
    'BASENAME=markdown_exec_DOCUMENTS=markdown_OPERATION=exec_Load Tapanuli Orangutan_Load Psychedelic Frogfish_| Variable | Value |_| -------- | ----- |_| Species  |   |_| Genus    |       |_| Family   |   |'
 }
 
-@test 'an activated block sets multiple variables' {
+@test 'activated block sets multiple variables from echo hash' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo-hash.md \
    'Load Tapanuli Orangutan' \
    'BASENAME=markdown_exec_DOCUMENTS=markdown_OPERATION=exec_Load Tapanuli Orangutan_Load Psychedelic Frogfish_| Variable | Value                   |_| -------- | ----------------------- |_| Species  | Pongo tapanuliensis |_| Genus    | Pongo                   |_| Family   | Hominidae           |'

data/bats/block-type-ux-echo.bats

@@ -2,18 +2,18 @@
 
 load 'test_helper'
 
-@test 'automatic block - default' {
+@test 'executes automatic block with default values' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo.md \
    'VAR=markdown_exec_IAB='
 }
 
-@test 'inherited lines' {
+@test 'displays inherited lines in menu' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo.md \
    '(menu_with_inherited_lines)' \
    '[[ -z $VAR ]] && VAR=markdown_exec_VAR=markdown_exec_IAB='
 }
 
-@test 'selected block - output of wc includes whitespace' {
+@test 'includes whitespace in wc output for selected block' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo.md \
    '(VAR_has_count)' '[IAB_has_count]' \
    'VAR=mmaarrkkddoowwnn__eexxeecc_IAB=mmaarrkkddoowwnn__eexxeeccmmaarrkkddoowwnn__eexxeecc'

data/bats/block-type-ux-exec-hash-transform.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'Each key in the exec hash is processed.' {
+@test 'processes each key in exec hash with transform' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-exec-hash-transform.md \
    'Cappuccino Snake_Species_ H  Y  D  R  O  D  Y  N  A  S  T  E  S     B  I_ 48 59 44 52 4F 44 59 4E 41 53 54 45 53 20 42 49_  C  I  N  C  T  U  S  _ _ 43 49 4E 43 54 55 53 0A_Genus_ H  Y  D  R  O  D  Y  N  A  S  T  E  S  _ _ 48 59 44 52 4F 44 59 4E 41 53 54 45 53 0A_Family_ C  O  L  U  B  R  I  D  A  E_ 43 4F 4C 55 42 52 49 44 41 45_Order_ S  u  m  t  _ _ 53 75 6D 74 0A_Class_ R  p  i  i_ 52 70 69 69_Phylum_ C  o  d  t_ 43 6F 64 74'
 }

data/bats/block-type-ux-exec-hash.bats

@@ -2,12 +2,12 @@
 
 load 'test_helper'
 
-@test 'automatic' {
+@test 'sets variables automatically from exec hash' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-exec-hash.md \
    'A single named variable is set automatically as the_output of the exec string._Common_Name=Yeti Crab__Common_Name=Yeti Crab_ Y  e  t  i     C  r  a  b  _ _ 59 65 74 69 20 43 72 61 62 0A__Multiple variables are set automatically as the_output of each exec string._One variable is temporary/not stored to inherited lines_but available for calculations within the block._Domain=ukaryota_____D=_Domain=ukaryota_ u  k  a  r  y  o  t  a  _   _ _ 75 6B 61 72 79 6F 74 61 0A 0A__A single named variable is set interactively as the_output of the exec string._Year_Discovered=_Year_Discovered=_$(hexdump_format "$Year_Discovered")__Multiple variables are set interactively as the_output of the exec string._Genus=_Species=_$(hexdump_format "$Species")_Genus=_$(hexdump_format "$Genus")__A single named variable is set automatically as the_first line of the output of the first element in the echo_hash._Kingdom=Animalia_Kingdom=Animalia_ A  n  i  m  a  l  i  a_ 41 6E 69 6D 61 6C 69 61__A single named variable is set automatically as the_first line of the output of the first element in the exec_hash._Class=Malacostraca_Class=Malacostraca_ M  a  l  a  c  o  s  t  r  a  c  a_ 4D 61 6C 61 63 6F 73 74 72 61 63 61'
 }
 
-@test 'interactive' {
+@test 'sets variables interactively from exec hash' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-exec-hash.md \
    '[Year_Discovered]' \
    '[Genus]' \

data/bats/block-type-ux-exec.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'Output of executed commands as initial value' {
+@test 'uses executed command output as initial value' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-exec.md \
    "ux0=_ux1=Unknown_ux2=markdown_exec__ux3=markdown_exec__ux4=Xform: 'markdown'"
 }

data/bats/block-type-ux-force.bats

@@ -3,7 +3,7 @@
 load 'test_helper'
 
 # UX before VARS although VARS appears first
-@test 'automatic' {
+@test 'forces UX block before VARS block' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-force.md \
   'Common_Name = Tapanuli Orangutan_  inherited_lines_  - : Common_Name="Tapanuli Orangutan"_  - : Common_Name=Ruby\ Seadragon_Common_Name=Ruby Seadragon_| Common_Name | Ruby Seadragon |'
 }

data/bats/block-type-ux-formats.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'UX block appearance' {
+@test 'displays UX block appearance by state' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-formats.md \
    'Demonstrate UX block appearance according to its state.__A simple variable declaration._EDIT VAR1 = value1__A selection from predefined options._ALLOW VAR2 = value2__A computed value using command substitution._ECHO VAR3 = Gemfile__An editable computed value._EDIT VAR4 = Gemfile__A command execution with formatted output._EXEC VAR5 = Gemfile___A read-only value._READONLY VAR6 = Gemfile_'
 }

data/bats/block-type-ux-hidden.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'a UX block requires a shell block and another UX block' {
+@test 'requires shell block and another UX block' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-hidden.md \
    '[SPECIES]' \
    'SPECIES=Pongo tapanuliensis_NAME=Pongo tapanuliensis - Pongo'

data/bats/block-type-ux-invalid.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'automatic block is invalid YAML' {
+@test 'reports error when automatic block has invalid YAML' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-invalid.md \
    '_Error: HashDelegator.ItrBlkFrmNstFls:1¤./docs/dev/block-type-ux-invalid.md:1 - --- !ruby/object:NullResult_message: Invalid YAML_data: invalid_ --  -- '
 }

data/bats/block-type-ux-readonly.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'automatic block - disabled' {
+@test 'disables automatic block when readonly' {
   spec_mde_args_expect \
    docs/dev/block-type-ux-readonly.md \
    --blocks readonly \

data/bats/block-type-ux-require-chained.bats

@@ -2,8 +2,8 @@
 
 load 'test_helper'
 
-@test 'initial value, inherited lines' {
+@test 'displays initial value and inherited lines' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-require-chained.md \
    '[SPECIES]' \
-   'ENTITY = Pongo tapanuliensis,Pongo_ENTITY="Pongo tapanuliensis,Pongo"_SPECIES=Pongo\ tapanuliensis_GENUS=Pongo_NAME=Pongo\ tapanuliensis\ -\ Pongo_NAME2=Pongo\ tapanuliensis\ -\ Pongo_SPECIES=Pongo tapanuliensis_GENUS=Pongo_NAME=Pongo tapanuliensis - Pongo_NAME2=Pongo tapanuliensis - Pongo'
+   'ENTITY = Pongo tapanuliensis,Pongo_ENTITY="Pongo tapanuliensis,Pongo"_SPECIES=Pongo tapanuliensis_GENUS=Pongo_NAME=Pongo tapanuliensis - Pongo_NAME2=Pongo tapanuliensis - Pongo'
 }

data/bats/block-type-ux-require-context.bats

@@ -2,12 +2,12 @@
 
 load 'test_helper'
 
-@test 'initial' {
+@test 'displays initial values before activation' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-require-context.md \
    'Get the common name..._Entity: _ENTITY2: _UX1: _Common name: '
 }
 
-@test 'activated' {
+@test 'updates values when block activated' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-require-context.md \
    \[ux1\] \
    'Get the common name..._Entity: _ENTITY2: Mythical Monkey_UX1: Mythical Monkey_Common name: Mythical Monkey'

data/bats/block-type-ux-require.bats

@@ -2,12 +2,12 @@
 
 load 'test_helper'
 
-@test 'Output of executed commands as initial value' {
+@test 'uses executed command output as initial value' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-require.md \
    'SPECIES=Pongo tapanuliensis_GENUS=Pongo_NAME=Pongo tapanuliensis - Pongo_NAME2=Pongo tapanuliensis - Pongo'
 }
 
-@test 'inherited lines' {
+@test 'displays inherited lines in menu' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-require.md \
    '(menu_with_inherited_lines)' \
    'SPECIES=Pongo\ tapanuliensis_GENUS=Pongo_NAME=Pongo\ tapanuliensis\ -\ Pongo_NAME2=Pongo\ tapanuliensis\ -\ Pongo_SPECIES=Pongo tapanuliensis_GENUS=Pongo_NAME=Pongo tapanuliensis - Pongo_NAME2=Pongo tapanuliensis - Pongo'

data/bats/block-type-ux-required-variables.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'An undefined variable is a precondition - initial' {
+@test 'displays undefined variable as precondition' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-required-variables.md \
    'SPECIES='
 }

data/bats/block-type-ux-row-format.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'Row format merges with prior table' {
+@test 'merges row format with prior table' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-row-format.md \
    "   | Variable    | Value                 | Prompt                 |_   | ----------- | --------------------- | ---------------------- |_   | Species     | Pongo tapanuliensis   | New species?       |_   | Name: Genus | Value: Xform: 'Pongo' | Prompt: New genus? |_   | Family      | Hominidae             | Enter a value:     |"
 }

data/bats/block-type-ux-sources.bats

@@ -2,25 +2,25 @@
 
 load 'test_helper'
 
-@test 'dname' {
+@test 'displays dname source values' {
   spec_mde_xansi_message_doc_blocks_expect docs/dev/block-type-ux-sources.md \
    dname \
    'USER_NAME=Guest_CURRENT_DIR=markdown_exec_SHELL_VERSION=/bin/bash_ENVIRONMENT=development_USER_EMAIL=_VERSION='
 }
 
-@test 'init_source' {
+@test 'displays init_source values' {
   spec_mde_xansi_message_doc_blocks_expect docs/dev/block-type-ux-sources.md \
    export_init \
    'Guest_exec_echo_allow_false_false'
 }
 
-@test 'act_source' {
+@test 'displays act_source values' {
   spec_mde_xansi_message_doc_blocks_expect docs/dev/block-type-ux-sources.md \
    export_act \
    'edit_edit_edit_allow_edit_edit'
 }
 
-@test 'is_disabled?' {
+@test 'checks is_disabled status' {
   spec_mde_xansi_message_doc_blocks_expect docs/dev/block-type-ux-sources.md \
    is_disabled? \
    'false_false_false_false_false_false'

data/bats/block-type-ux-transform.bats

@@ -2,7 +2,7 @@
 
 load 'test_helper'
 
-@test 'Transformed output of executed commands' {
+@test 'transforms output of executed commands' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-transform.md \
   '_Execution output has a trailing newline._Var0=markdown_exec__ 6d 61 72 6b 64 6f 77 6e 5f 65 78 65 63 0a      __With validate and transform, output has no newline._Var1=markdown_exec_ 6d 61 72 6b 64 6f 77 6e 5f 65 78 65 63         __With transform :chomp, output has no newline._Var2=markdown_exec_ 6d 61 72 6b 64 6f 77 6e 5f 65 78 65 63         __With transform :upcase, output is in upper case w/ newline._Var3=MARKDOWN_EXEC__ 4d 41 52 4b 44 4f 57 4e 5f 45 58 45 43 0a      '
 }

data/bats/block-type-vars.bats

@@ -5,21 +5,21 @@ load 'test_helper'
 # Type: Vars
 
 # includes output from automatic vars blocks
-@test 'Vars block - auto load' {
+@test 'loads vars block automatically' {
   BATS_OUTPUT_FILTER=A
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-vars.md show \
    'Species = Not specified_Genus = Not specified__Species: Not specified_VAULT: '
 }
 
 # includes output from assignment and from shell block
-@test 'Vars block - set variable' {
+@test 'sets variable in vars block' {
   BATS_OUTPUT_FILTER=A
   spec_mde_args_expect docs/dev/block-type-vars.md '[set_vault_1]' show \
    'Species = Not specified Genus = Not specified VAULT = 1  Species: Not specified VAULT: 1'
 }
 
 # handles invalid YAML in block
-@test 'Vars block - invalid YAML' {
+@test 'handles invalid YAML in vars block' {
   BATS_OUTPUT_FILTER=A
   spec_mde_args_expect docs/dev/block-type-vars.md '[invalid_yaml]' show \
    'Species = Not specified Genus = Not specified  Species: Not specified VAULT: '