Elements
graph TD;
%% REQVIRE-AUTOGENERATED-DIAGRAM
%% Graph styling
classDef userRequirement fill:#D1C4E9,stroke:#7E57C2,stroke-width:2px;
classDef systemRequirement fill:#E1D8EE,stroke:#673AB7,stroke-width:1.5px;
classDef verification fill:#DCEDC8,stroke:#4CAF50,stroke-width:2px;
classDef folder fill:#FAFAFA,stroke:#9E9E9E,stroke-width:3px;
classDef file fill:#FFF8E1,stroke:#FFCA28,stroke-width:2px;
classDef default fill:#F5F5F5,stroke:#424242,stroke-width:1.5px;
subgraph 8735c0a811307e57["📁 requirements/Functional/Core"]
subgraph d1a073c5dbdc4a00["📄 Behaviors.md"]
3301b4a3dd652151["Attachment Identifier CRUD Update Behavior"];
class 3301b4a3dd652151 default;
click 3301b4a3dd652151 "Behaviors.html#attachment-identifier-crud-update-behavior";
9919cc3402a3c1b9["Attachment Input Auto-Detection Behavior"];
class 9919cc3402a3c1b9 default;
click 9919cc3402a3c1b9 "Behaviors.html#attachment-input-auto-detection-behavior";
c7a7113c11f9175d["Subdirectory Auto-Detection Behavior"];
class c7a7113c11f9175d default;
click c7a7113c11f9175d "Behaviors.html#subdirectory-auto-detection-behavior";
6789e7e9e093c884["Two-Pass Validation Behavior"];
class 6789e7e9e093c884 default;
click 6789e7e9e093c884 "Behaviors.html#two-pass-validation-behavior";
5f843b087a10d61b["Type Validation Error Behavior"];
class 5f843b087a10d61b default;
click 5f843b087a10d61b "Behaviors.html#type-validation-error-behavior";
fc1df5aa988472a["Validation Error Reporting Behavior"];
class fc1df5aa988472a default;
click fc1df5aa988472a "Behaviors.html#validation-error-reporting-behavior";
end
end
Attachment Identifier CRUD Update Behavior
When a Refinement element is moved or renamed through CRUD operations, all attachment identifiers referencing that element must be updated using the same update mechanism as relation target updates.
Details
The update process follows these steps:
- Identify affected attachments: Find all elements that have attachment identifiers pointing to the affected Refinement element
- Update identifier paths: For each affected attachment:
- On move: Update the file path portion of the identifier to reflect the new location
- On rename: Update the element name portion of the identifier (fragment) to reflect the new name
- Preserve link text: The display text of the markdown link is preserved
- File persistence: Modified files are written back to disk with updated attachments
This behavior mirrors the existing relation target update behavior used when moving or renaming elements, ensuring consistency across the model.
Metadata
When attaching or detaching via CLI commands, the system shall auto-detect whether the input refers to a file path or a Refinement element name.
Details
The detection follows this priority order:
-
File Path Check (Priority): Check if the input exists as a file on the filesystem
- Check relative to current working directory
- Check relative to git root directory
- If file exists, treat as file path attachment
-
Element Name Lookup (Fallback): If no file exists, attempt to resolve as element name
- Search for element by display name in the model
- Element must be a Refinement type (constraint, behavior, specification)
- Convert element name to identifier format for storage
-
Error Handling: If neither file nor element found, report clear error message indicating what was attempted
This behavior ensures backward compatibility (existing file attachments work unchanged) while enabling element attachments without requiring explicit flags.
Metadata
Subdirectory Auto-Detection Behavior
Describes how subdirectory scope detection and enforcement works.
Details
Detection Steps:
- Detect git root: Run
git rev-parse --show-toplevel to find repository root
- Determine relative scope: Calculate current working directory path relative to git root
- Limit file processing: Only process specification files within the current subdirectory
- Validate references: References to elements outside the subdirectory scope generate missing target errors
When run from git root:
- Process all files in the repository
- No scope limitations apply
This behavior enables focused work on specific areas of large models while maintaining reference integrity.
Metadata
Relations
Two-Pass Validation Behavior
Two-phase validation process for model parsing.
Details
Pass 1: Element Collection
- Parse all markdown files
- Extract elements with metadata
- Local validation (uniqueness, format, syntax)
- Report errors if found
Pass 2: Graph Validation
- Build in-memory model representation from elements
- Validate relations (existence, type compatibility)
- Cross-component validation
- Report errors if found
Metadata
Relations
Type Validation Error Behavior
Error messages for invalid types shall include the list of valid types.
Details
Element Type Errors:
When an invalid element type is encountered (in metadata or filters):
- Error message shall include the invalid type value
- Error message shall list all valid element types
- Error message shall include the custom type pattern: “For custom types use: other-TYPENAME”
Relation Type Errors:
When an invalid relation type is encountered:
- Error message shall include the invalid relation type
- Error message shall list all valid relation types in sorted order
This enables users to quickly identify and fix type errors without consulting documentation.
Metadata
Relations
Validation Error Reporting Behavior
Error message structure for validation issues.
Details
- File path and line number included
- Element name and relation details shown
- Color coding per Color Scheme Specification
- Actionable suggestions when possible
Metadata
Relations