cli-usereq 0.68.0__py3-none-any.whl

usereq/generate_markdown.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""!
+@file generate_markdown.py
+@brief Generate concatenated markdown from arbitrary source files.
+@details Analyzes each input file with source_analyzer and produces a single markdown output concatenating all results. Prints pack summary to stderr.
+@author GitHub Copilot
+@version 0.0.70
+"""
+
+import os
+import sys
+from pathlib import Path
+
+from .source_analyzer import SourceAnalyzer, format_markdown
+
+# Map file extensions to languages
+EXT_LANG_MAP = {
+    ".py": "python",
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".ts": "typescript",
+    ".rs": "rust",
+    ".go": "go",
+    ".c": "c",
+    ".cpp": "cpp",
+    ".h": "c",
+    ".hpp": "cpp",
+    ".java": "java",
+    ".rb": "ruby",
+    ".php": "php",
+    ".swift": "swift",
+    ".kt": "kotlin",
+    ".scala": "scala",
+    ".lua": "lua",
+    ".sh": "shell",
+    ".pl": "perl",
+    ".hs": "haskell",
+    ".zig": "zig",
+    ".ex": "elixir",
+    ".cs": "csharp",
+}
+"""! @brief Extension-to-language normalization map for markdown generation."""
+
+
+def detect_language(filepath: str) -> str | None:
+    """! @brief Detect language from file extension.
+    @param filepath Path to the source file.
+    @return Language identifier string or None if unknown.
+    @details Uses EXT_LANG_MAP for extension lookup (case-insensitive).
+    """
+    _, ext = os.path.splitext(filepath)
+    return EXT_LANG_MAP.get(ext.lower())
+
+
+def _format_output_path(filepath: str, output_base: Path | None) -> str:
+    """!
+    @brief Build the markdown-visible path for one source file.
+        @param filepath Absolute or relative source file path.
+        @param output_base Project-home base used to relativize output paths.
+        @return Original filepath when output_base is None; otherwise POSIX relative path from output_base.
+    @details Implements the _format_output_path function behavior with deterministic control flow.
+    """
+    if output_base is None:
+        return filepath
+    absolute_path = Path(filepath).resolve()
+    return Path(os.path.relpath(absolute_path, output_base)).as_posix()
+
+
+def generate_markdown(
+    filepaths: list[str],
+    verbose: bool = False,
+    output_base: Path | None = None,
+) -> str:
+    """! @brief Analyze source files and return concatenated markdown.
+    @param filepaths List of source file paths to analyze.
+    @param verbose If True, emits progress status messages on stderr.
+    @param output_base Project-home base used to render file paths in markdown as relative paths.
+    @return Concatenated markdown string with all file analyses.
+    @throws ValueError If no valid source files are found.
+    @details Iterates through files, detecting language, analyzing constructs, and formatting output. Disables legacy comment/exit annotation traces in rendered markdown, emitting only construct references plus Doxygen field bullets when available.
+    """
+    analyzer = SourceAnalyzer()
+    md_parts = []
+    ok_count = 0
+    fail_count = 0
+    resolved_output_base = output_base.resolve() if output_base is not None else None
+
+    for fpath in filepaths:
+        if not os.path.isfile(fpath):
+            if verbose:
+                print(f"  SKIP  {fpath} (file not found)", file=sys.stderr)
+            continue
+
+        lang = detect_language(fpath)
+        if not lang:
+            if verbose:
+                print(f"  SKIP  {fpath} (unsupported extension)", file=sys.stderr)
+            continue
+
+        try:
+            elements = analyzer.analyze(fpath, lang)
+            lang_key = lang.lower().strip().lstrip(".")
+            spec = analyzer.specs[lang_key]
+            analyzer.enrich(elements, lang_key, filepath=fpath)
+
+            with open(fpath, "r", encoding="utf-8", errors="replace") as f:
+                total_lines = sum(1 for _ in f)
+
+            md_output = format_markdown(
+                elements,
+                _format_output_path(fpath, resolved_output_base),
+                lang_key,
+                spec.name,
+                total_lines,
+                include_legacy_annotations=False,
+            )
+
+            md_parts.append(md_output)
+            ok_count += 1
+            if verbose:
+                print(f"  OK    {fpath}", file=sys.stderr)
+
+        except Exception as e:
+            if verbose:
+                print(f"  FAIL  {fpath} ({e})", file=sys.stderr)
+            fail_count += 1
+
+    if not md_parts:
+        raise ValueError("No valid source files processed")
+
+    if verbose:
+        print(f"\n  Processed: {ok_count} ok, {fail_count} failed",
+              file=sys.stderr)
+
+    return "\n\n---\n\n".join(md_parts)
+
+
+def main():
+    """!
+    @brief Execute the standalone markdown generation CLI command.
+        @details Expects file paths as command-line arguments. Prints generated markdown to stdout.
+    @return {None} Function return value.
+    """
+    if len(sys.argv) < 2:
+        print("Usage: python generate_markdown.py file1 [file2 ...]",
+              file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        md = generate_markdown(sys.argv[1:])
+        print(md)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

usereq/resources/docs/Document_Source_Code_in_Doxygen_Style.md

@@ -0,0 +1,130 @@
+# Role: AI Code Documentation Specialist & QA Enforcer
+
+## 1) Primary Objective
+You are the definitive authority on generating, regenerating, updating, and maintaining source-code documentation. Your output is consumed exclusively by **Doxygen parsers** and **downstream LLM Agents**, never by humans.
+
+All documentation and comments inside source code MUST:
+-   Document **ALL** code components (functions, classes, objects, structures, modules, variables).
+-   Strictly adhere to the **Tag Taxonomy** defined in Section 4.
+-   Use **Atomic Syntax** designed for machine logic inference.
+-   Be formatted using standard Doxygen syntax (`/** ... */` for C/C++ or `""" ... """` for Python) leveraging Markdown within the comments.
+
+## 2) Language & Format Constraints
+* **Format:** Standard Doxygen with Markdown support.
+* **Language:** English (Strict US English).
+* **Target Audience:** LLM Agents, Automated Parsers, Static Analysis Tools.
+
+## 3) "LLM-Native" Documentation Strategy
+**CRITICAL:** Formulate all new or edited requirements and all source code information using a highly structured, machine-interpretable format (Markdown within Doxygen) with unambiguous, atomic syntax to ensure maximum reliability for downstream LLM agentic reasoning.
+* **Avoid:** Conversational filler, subjective adjectives, ambiguity, flowery prose.
+* **Enforce:** High semantic density, logical causality, explicit constraints.
+* **Goal:** Optimize context to enable an LLM to perform future refactoring, extension, or test generation without analyzing the function body.
+
+## 4) Tag Taxonomy & Content Standards
+You must strictly adhere to the following classification of Doxygen tags. Missing a **Mandatory** tag is a critical failure.
+
+### A. MANDATORY TAGS (Must appear in every functional block)
+These tags define the core interface contract.
+* **`@brief`**: Mandatory, a short single-line technical description of its specific action.
+    * *Ex:* `@brief Initializes sensor array.`
+* **`@details`**: Mandatory, detailed logical description. Must provide a high-density technical summary detailing critical algorithmic logic, complexity and side effects. Write description for other LLM **Agents**, NOT humans. Must be optimized for machine comprehension. Do not write flowery prose. Use high semantic density, optimized to contextually enable an **LLM Agent** to perform future refactoring or extension.
+* **`@param`**: Mandatory if params are defined, input definition. Must include type constraints if the language is dynamic.
+    * *Ex:* `@param[in] id Unique identifier (UUIDv4 format).`
+* **`@return`** (or **`@retval`**): Mandatory, output definition. Describe the data structure returned in a single block or list specific return values.
+    * *Ex:* `@return {bool} True if connection established; structure {x,y} otherwise.`
+
+### B. CONTEXT-MANDATORY TAGS (Required based on logic)
+You must analyze the code logic. If these conditions exist, the tag is **Mandatory**.
+* **`@param[out]`**: MANDATORY if a reference/pointer argument is mutated inside the function (C/C++).
+* **`@exception`** (or **`@throws`**): MANDATORY if the function can raise an exception or error state. List specific error classes.
+* **`@satisfies`**: If applicable, link to requirements (e.g., @satisfies REQ-026, REQ-045).
+
+### C. OPTIONAL TAGS (Semantic Enrichment)
+Use these to increase context window efficiency for future agents.
+* **`@pre`**: Pre-conditions. What must be true *before* calling. Use logical notation.
+* **`@post`**: Post-conditions. System state *after* execution.
+* **`@warning`**: Critical usage hazards (e.g., non-thread-safe).
+* **`@note`**: Vital implementation details not fitting in `@details`.
+* **`@see`** (or **`@sa`**): Links to related functions/classes for context linkage.
+* **`@deprecated`**: If applicable, link to the replacement API.
+
+
+## 5) Operational Rules
+
+### Rule A: The "Update" Imperative
+If you modify code, you must **immediately** verify and update the associated documentation. Stale documentation is a hallucination trigger and is strictly forbidden.
+
+### Rule B: 100% Coverage
+Every exportable symbol must be documented. New code does not exist until it is documented according to the **Tag Taxonomy**.
+
+### Rule C: Content Heuristics (LLM-Optimized)
+1.  **Type Precision:** If Python/JS, explicit types are mandatory in `@param` (e.g., `Dict[str, Any]`).
+2.  **Complexity:** In `@details`, state Time/Space complexity (e.g., `O(n log n)`).
+3.  **Side Effects:** Explicitly state mutations in `@details` or `@post` (e.g., "Resets global timer").
+
+## 6) Examples of Expected Output
+
+### Example A: C++ (BAD - Human Readable - AVOID)
+```cpp
+/**
+ * This function basically checks if the user is valid.
+ * It connects to the db and returns true/false.
+ * Be careful not to pass a null user!
+ */
+bool check_user(User u);
+```
+
+### Example B: C++ (GOOD - LLM Optimized)
+```cpp
+/**
+ * @brief Validates User credentials against local cache.
+ * @details Performs SHA-256 hash comparison. Short-circuits on empty fields.
+ * Implementation uses constant-time comparison to prevent timing attacks.
+ * @pre Input User object must be initialized.
+ * @param[in] u {UserStruct} target_user - Entity to validate. Must contain non-null 'password_hash'.
+ * @return {bool} True if credentials match; False if invalid or cache miss.
+ * @throws {AuthError} If internal hashing service is unreachable.
+ * @note Complexity: O(1) - Constant time lookup.
+ * @warning Thread-Safety: Read-only, safe for concurrent calls.
+ * @see User::login
+ */
+bool check_user(User u);
+```
+
+### Example C: Python (BAD - Human Readable - AVOID)
+
+```python
+def process_telemetry(data, threshold=10):
+    """
+    Takes some data and cleans it up.
+    Removes the old keys and returns a list of numbers.
+    Might crash if data is bad.
+    """
+    # ...
+```
+
+### Example D: Python (GOOD - LLM Optimized)
+
+```python
+def process_telemetry(data: Dict[str, Any], threshold: int = 10) -> List[float]:
+    """
+    @brief Filters and normalizes input telemetry stream.
+    @details Applies Z-score normalization. Drops keys matching 'legacy_*' pattern.
+    Uses list comprehension for memory efficiency.
+    @pre 'data' dictionary must not be empty.
+    @param data {Dict[str, Any]} Raw JSON payload from sensor.
+    @param threshold {int} Noise cutoff value. Defaults to 10.
+    @return {List[float]} Normalized value sequence in range [0.0, 1.0].
+    @throws {ValueError} If calculated standard deviation is zero.
+    @complexity O(N) where N is the number of keys in 'data'.
+    @side_effect Logs warning if >50% of data is filtered out.
+    """
+    # Implementation...
+```
+
+## 7) Minimal Agent-Focused Reference
+
+- Keep this guide strictly parser-first and policy-focused.
+- Include only repository-relevant Doxygen rules, tags, and compact examples.
+- Exclude generic Doxygen handbook/tutorial material that does not change repository behavior.
+- Prefer atomic constraints and deterministic examples over narrative explanations.

usereq/resources/docs/HDT_Test_Authoring_Guide.md

@@ -0,0 +1,318 @@
+# HDT Unit Test Authoring Guide (for LLM Agents)
+**Version:** 1.0  
+**Audience:** LLM agents that *author or modify* unit tests in the HDT style  
+**Source Prompt Cards:** Generator + Refactorer modes  
+
+---
+
+## 1) Purpose and Non‑Negotiables
+When you decide you must **write new unit tests** or **modify existing tests**, this document is the single reference for *how* to do so.
+
+All HDT unit tests MUST be:
+
+- **Deterministic**: 100% reproducible across runs and environments.
+- **Isolated**: no real network / filesystem / database / clock / unseeded randomness.
+- **Dependency‑aware**: tests are organized and executed by **levels** (Level 0 → Level N) derived from the call graph.
+- **Framework‑native**: no custom gating logic embedded in test bodies.
+- **CI‑gated**: higher levels are blocked if lower levels fail (via CI stages, not `if/return` in tests).
+- **Signal‑rich for developers**: support dev runs that collect multiple failures when useful.
+
+Guiding principle: **maximize diagnostic value and maintainability without proceduralizing the suite.**
+
+---
+
+## 2) Choose the Mode: Generator vs Refactorer
+You MUST explicitly choose one of these modes before authoring.
+
+### Mode A — **Generator** (Create New Tests)
+Use **Generator** when:
+- No tests exist for the target scope, OR
+- You are adding coverage for **new units** / **new behavior**, OR
+- You are building a suite from source code (or a new module) and need a baseline.
+
+Primary deliverable shape:
+1) Static analysis (UUTs + call graph + levels + deps)
+2) Test matrix (happy/boundary/error)
+3) New test code (level‑ordered)
+4) Execution plan (CI gating + dev signal)
+5) Quality checklist
+
+### Mode B — **Refactorer** (Improve Existing Tests)
+Use **Refactorer** when:
+- A test suite already exists, and you must **fix flakiness**, **reduce brittleness**, **restructure levels**, or **improve coverage**.
+- You are modifying tests to align with HDT rules (determinism, isolation, leveling, CI gating).
+
+Primary deliverable shape:
+1) Audit (what’s wrong & why)
+2) Static analysis (UUTs + call graph + levels + deps)
+3) Refactor plan (stepwise)
+4) Updated test matrix
+5) Refactored test code (or patches)
+6) Execution plan (CI gating + dev signal)
+7) Quality checklist
+
+---
+
+## 3) Mode Selection Heuristic (Decision Checklist)
+If ANY of the following is true, pick **Refactorer**:
+- Tests exist for the scope.
+- Failures are flaky/intermittent.
+- Tests touch real I/O or time.
+- Tests rely on order or shared state.
+- Assertions are brittle (implementation details, snapshots that break frequently).
+
+Pick **Generator** only when you are genuinely producing **new tests** from source (or for uncovered code).
+
+If ambiguous, default to **Refactorer** (changing existing suites is higher risk; start by auditing).
+
+---
+
+## 4) Universal HDT Test Principles (apply in BOTH modes)
+
+### 4.1 Determinism Requirements
+Tests MUST NOT depend on:
+- Real wall clock time (use time freezing, dependency injection, or fakes)
+- Unseeded randomness (seed or inject deterministic generators)
+- Unordered collection iteration (normalize or compare as sets where appropriate)
+- Locale/timezone/environment (explicitly set or normalize)
+- Global mutable state shared across tests
+
+### 4.2 Isolation Requirements
+You MUST isolate:
+- **Network** calls (mock/stub)
+- **Filesystem** access (use temp fakes or mock; never touch real user paths)
+- **Databases** (use in‑memory fakes or mocks; never real DB)
+- **External services** (always mock)
+- **OS / process** state (env vars, cwd, etc.) where relevant
+
+No test may rely on state left behind by another test.
+
+### 4.3 Behavior over Implementation
+- Prefer **behavioral assertions** (inputs → outputs / observable effects).
+- Avoid asserting internal calls unless that is the behavior contract.
+- Avoid brittle snapshot asserts unless the snapshot is *truly* a stable contract.
+- Prefer explicit expected values/exceptions.
+
+### 4.4 AAA Structure
+Use **Arrange – Act – Assert** in every test. Make the Act step obvious.
+
+### 4.5 Explicit Expected Outcomes
+Every test MUST declare either:
+- `expected_output`, OR
+- `expected_exception` (type; message only if stable and intentional)
+
+---
+
+## 5) Dependency Awareness: Levels and the Call Graph
+HDT uses levels to ensure fast, reliable diagnosis and CI gating.
+
+### 5.1 Definitions
+- **UUT (Unit Under Test):** a function/class/module boundary you are testing.
+- **Level 0 (Atomic):** leaf units with no internal dependencies (or only trivial pure helpers).
+- **Level 1..N (Composed):** units that depend on lower-level units (directly or indirectly).
+
+### 5.2 Required Static Analysis Artifact
+Before writing or refactoring tests, you MUST produce:
+1) **UUT list**
+2) **Call graph** (approximate is acceptable; must be explicit)
+3) **Level classification table**
+4) **External dependencies to isolate**
+
+### 5.3 Leveling Rules of Thumb
+- If a unit calls another project unit: it is *higher level* than the callee.
+- If a unit calls an external dependency: it is higher level, and that dependency must be isolated.
+- Keep Level 0 tests small and precise; they are your CI gate.
+
+---
+
+## 6) Repo Layout and Naming Conventions
+### 6.1 Recommended Layout
+```
+tests/
+  unit/
+    atomic/
+    composed/
+    module/        # optional; only if your project meaningfully benefits
+```
+
+### 6.2 Naming Convention
+Use clear test names:
+- `test_<scenario>_<expected_behavior>`
+- Prefer descriptive scenario labels (happy/boundary/error).
+
+---
+
+## 7) Generator Mode: Required Workflow and Output Contract
+When in **Generator** mode, you MUST deliver the following artifacts **in this exact order**.
+
+### 7.1 Static Analysis Artifact
+Include:
+- UUT list
+- Call graph
+- Levels table
+- External deps to isolate
+
+### 7.2 Test Matrix Artifact (minimum cases per UUT)
+For each UUT, define at least:
+- **Happy path**
+- **Boundary case(s)**
+- **Error case(s)** (if applicable)
+
+Matrix columns SHOULD include:
+- UUT, Level, Scenario, Arrange (inputs), Act, Assert (expected), Mocks
+
+### 7.3 Test Code (Framework‑Native)
+- Write tests starting from **Level 0**, then Level 1..N.
+- Use AAA.
+- No real I/O.
+- Explicit expected outcomes.
+- Use per-framework best practices (fixtures, parametrization, setup/teardown) *without* creating cross-test coupling.
+
+### 7.4 Execution Plan
+Provide:
+- **CI plan**: staged gating (atomic → composed → module)
+- **Dev plan**: how to run signal‑rich (collect multiple failures)
+
+### 7.5 Quality Checklist
+At minimum:
+- Deterministic
+- Isolated
+- Explicit expected outcomes
+- Correct levels (atomic first)
+- Happy + boundary + error coverage
+- Non‑brittle asserts
+- Clear naming
+
+---
+
+## 8) Refactorer Mode: Required Workflow and Output Contract
+When in **Refactorer** mode, you MUST deliver the following artifacts **in this exact order**.
+
+### 8.1 Audit Artifact (what’s wrong & why)
+Identify:
+1) **Flakiness sources** (time, random, I/O, shared state, order dependence)
+2) **Brittleness sources** (over-mocking, impl-detail asserts, fragile snapshots)
+3) **Dependency structure gaps** (missing leaf tests, misleveled tests)
+4) **Coverage gaps** (missing happy/boundary/error)
+
+### 8.2 Static Analysis Artifact
+Same requirements as Generator:
+- UUT list
+- Call graph
+- Levels table
+- External deps to isolate
+
+### 8.3 Refactor Plan (stepwise)
+Provide a numbered plan that:
+- Stabilizes determinism (freeze time, seed random, inject deps, fakes)
+- Removes real I/O
+- Re-levels tests and reorganizes files
+- Replaces brittle asserts with behavioral asserts
+- Adds missing cases minimally
+
+### 8.4 Updated Test Matrix Artifact
+Refresh the matrix to ensure:
+- Each UUT has happy + boundary + error (if applicable)
+- Correct level assignment
+- Mocking strategy is explicit and minimal
+
+### 8.5 Refactored Test Code
+- Provide updated files (or patches) in separate fenced blocks per file.
+- Preserve original behavioral intent unless it is clearly incorrect; if you change behavior, document why.
+
+### 8.6 Execution Plan
+- CI (gated fail-fast by stage)
+- Dev (signal‑rich, optionally include framework-native triage commands)
+
+### 8.7 Quality Checklist (Refactor‑specific additions)
+Also confirm:
+- No sleeps/retries to hide flakes
+- No hidden cross-test dependencies
+- Brittle mocks removed where a fake is simpler
+
+---
+
+## 9) CI Gating vs Test Logic (Critical Rule)
+**Gating belongs to CI**, not to test bodies.
+
+### 9.1 CI (Strict Gated Fail‑Fast)
+Run stages and block next stage if previous fails. Example:
+- Stage 1: `tests/unit/atomic` (fail-fast)
+- Stage 2: `tests/unit/composed` (fail-fast; only if Stage 1 green)
+- Stage 3: `tests/unit/module` (optional; only if Stage 2 green)
+
+### 9.2 Dev (Signal‑Rich)
+- Run full suite without fail-fast to gather multiple failures.
+- Use fail-fast only for focused debugging.
+
+---
+
+## 10) Assumptions You MUST Actively Challenge (Pre‑Flight)
+Before writing or changing tests, challenge these common failure modes:
+
+1) **Leaf identification:** Did you misread the call graph or miss a dependency?
+2) **Expected errors:** Is the exception type correct? Is message stable enough to assert?
+3) **Boundaries:** Null/empty, max size, negative, overflow, encoding, and type errors.
+4) **Determinism risks:** timestamps, UUIDs, randomness, unordered structures.
+5) **Coupling:** Are you asserting behavior, or implementation details?
+
+If uncertain:
+- State the uncertainty explicitly in your artifacts.
+- Choose robust techniques (freeze time, seed random, normalize outputs).
+- Avoid overly specific assertions until justified.
+
+---
+
+## 11) Fine‑Grained Test Dependencies (Rare Exception)
+Avoid “Test B depends on Test A”.
+
+Only if truly necessary:
+- Make dependency explicit and documented.
+- Prefer framework support (markers/plugins) or CI staging.
+- Justify why level-based staging is insufficient.
+- Avoid long chains; improve leaf tests instead.
+
+---
+
+## 12) Operational Templates (Copy/Paste Prompts)
+
+### 12.1 Generator Mode Prompt Template
+**Task:** Create HDT unit tests (Generator mode)  
+**Lang/Framework:** `{{LANG}} / {{TEST_FRAMEWORK}}`  
+**Scope:** `{{TARGET_SCOPE}}`  
+**Constraints:** `{{CONSTRAINTS}}`  
+**Source Code:**  
+```text
+{{SOURCE_CODE}}
+```  
+**Required output:** Follow the Generator workflow and artifact order in Sections 7 and 5.
+
+### 12.2 Refactorer Mode Prompt Template
+**Task:** Refactor HDT unit tests (Refactorer mode)  
+**Lang/Framework:** `{{LANG}} / {{TEST_FRAMEWORK}}`  
+**Scope:** `{{TARGET_SCOPE}}`  
+**Constraints:** `{{CONSTRAINTS}}`  
+**Source Code:**  
+```text
+{{SOURCE_CODE}}
+```  
+**Existing Tests:**  
+```text
+{{EXISTING_TESTS}}
+```  
+**Required output:** Follow the Refactorer workflow and artifact order in Sections 8 and 5.
+
+---
+
+## 13) Final Self‑Check (Mandatory)
+Before outputting test code, verify:
+
+- [ ] Mode correctly chosen (Generator vs Refactorer)
+- [ ] Static analysis completed (UUTs, call graph, levels, external deps)
+- [ ] Tests are deterministic (no time/random/env nondeterminism)
+- [ ] Tests are isolated (no real I/O)
+- [ ] Level 0 exists and runs first
+- [ ] Each UUT has happy + boundary + error (if applicable)
+- [ ] Assertions are behavioral and explicit
+- [ ] CI gating is described outside of test bodies
+- [ ] Repo layout and naming are consistent

usereq/resources/docs/Requirements_Template.md

@@ -0,0 +1,78 @@
+---
+title: "{{project name}} Requirements"
+description: Software requirements specification
+version: "{{version}}"
+date: "{{date_modified}}"
+author: "{{author}}"
+scope:
+  paths:
+    - "**/*.py"
+    - "**/*.ipynb"
+    - "**/*.c"
+    - "**/*.h"
+    - "**/*.cpp"
+  excludes:
+    - ".*/**"
+visibility: "draft"
+tags: ["markdown", "requirements", "example"]
+---
+
+# {{project name}} Requirements
+<!-- Metadata is in the YAML front matter; do not duplicate it in the body. -->
+
+<!-- Optional: omit a Table of Contents to reduce token footprint for LLM agents. If a TOC is included, it MUST be auto-generated and kept minimal. -->
+
+## 1. Introduction
+<!-- Overview of the SRS: purpose, scope, audience, and document organization. Avoid detailed requirements here. -->
+
+### 1.1 Document Rules
+This document MUST follow these authoring rules (LLM-first, normative SRS):
+- This document MUST be written and maintained in English.
+- Use RFC 2119 keywords exclusively (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY). Do not use "shall".
+- In requirements sections, every bullet MUST be a requirement and MUST start with a unique, stable Requirement ID (e.g., **REQ-001**).
+- Requirement IDs MUST be stable: never renumber, reuse, or repurpose an ID. Only the dedicated reorganization workflow may renumber and it MUST emit an old→new ID mapping.
+- Requirement ID prefixes MUST be consistent; if additional prefixes are needed beyond PRJ/CTN/DES/REQ/TST, they MUST be defined once in this section before first use.
+- Each requirement MUST be atomic, single-sentence, and testable; target <= 35 words per requirement; split any compound behavior into separate IDs.
+- Write for other LLM Agents and automated parsers (high semantic density; no filler).
+- On every change to this document:
+  - Update `date` and `version` in the YAML front matter only (avoid duplicating metadata in the body).
+  - Do NOT maintain an in-document revision history; use git history / CHANGELOG.md for change tracking.
+
+### 1.2 Project Scope
+<!-- The project (name/version), primary purpose, key capabilities, and boundaries. Keep brief and focus on the "what" and "why", not the "how". Avoid detailed requirements here. -->
+
+## 2. Project Requirements
+<!-- Background and context that shape the project's requirements. Avoid detailed requirements here. -->
+
+### 2.1 Project Functions
+<!-- Major functional areas or features of the project -->
+- **PRJ-001**: MUST <single-sentence project function (<= 35 words)>.
+- **PRJ-002**: Requirement description of project function 2
+<!-- add here other project function requirements -->
+
+### 2.2 Project Constraints
+<!-- Design and implementation constraints that affect the solution of the project -->
+- **CTN-001**: MUST <single-sentence constraint (<= 35 words)>.
+- **CTN-002**: Requirement description of project constraint 2
+<!-- add here other project constraint requirements -->
+
+## 3. Requirements
+<!-- Identifiable, verifiable, and testable requirements. Avoid implementation details. -->
+
+### 3.1 Design and Implementation
+<!-- Constraints and mandates on design, deployment, and maintenance -->
+- **DES-001**: Requirement description of design constraint 1
+- **DES-002**: MUST <single-sentence design constraint (<= 35 words)>.
+<!-- add here other design constraint requirements -->
+### 3.2 Functions
+<!-- Externally observable behaviors organized by feature or use case -->
+- **REQ-001**: MUST <single observable behavior with explicit trigger and expected outcome>.
+- **REQ-002**: Requirement description of function 2
+<!-- add here other function requirements -->
+
+## 4. Test Requirements
+<!-- Define the test requirements linked to functional/non-functional requirements (or to a verification context) and specify a clear, reproducible test procedure with explicit pass/fail criteria.  -->
+
+- **TST-001**: MUST verify <requirement-id> using <reproducible procedure> with explicit pass/fail criteria.
+
+<!-- Do not add a revision history section here; use git history / CHANGELOG.md instead. -->