pi-usereq 0.4.0

package/src/resources/prompts/cover.md

@@ -0,0 +1,219 @@
+---
+description: "Implement minimal changes to cover uncovered existing requirements"
+argument-hint: "Optional, context to focus coverage work (can be empty)"
+usage: >
+  Select this prompt when specific uncovered requirement IDs already exist (typically identified by /req-check) and the goal is to implement the minimal deltas needed to satisfy those IDs WITHOUT changing %%DOC_PATH%%/REQUIREMENTS.md. Use for targeted gap-closure in an otherwise existing codebase (small/known missing surface), including adding/adjusting tests under %%TEST_PATH%%, verifying, updating %%DOC_PATH%%/WORKFLOW.md and %%DOC_PATH%%/REFERENCES.md, and committing. Do NOT select if you must change or add requirements (use /req-change or /req-new), if the request is primarily a defect fix relative to already-covered requirements (use /req-fix), or if the implementation is largely absent and needs end-to-end build-out from the SRS (use /req-implement).
+---
+
+# Implement minimal changes to cover uncovered existing requirements
+
+## Purpose
+Close coverage gaps by implementing the missing behaviors for uncovered requirement IDs in the existing codebase, so the implementation becomes fully compliant with the current SRS (`%%DOC_PATH%%/REQUIREMENTS.md`) without changing that SRS.
+
+## Scope
+In scope: identify uncovered requirement IDs, implement minimal code changes under %%SRC_PATHS%%, add/adjust tests under %%TEST_PATH%% as needed, run verification with static analysis and conditional execution of existing unit tests using language-specific test-suite priority policy, update `%%DOC_PATH%%/WORKFLOW.md` and `%%DOC_PATH%%/REFERENCES.md`, and commit. Out of scope: editing `%%DOC_PATH%%/REQUIREMENTS.md`, introducing new requirements/features, or performing large-scale rewrites (use `/req-implement` for “from scratch” rebuilds).
+
+
+## Professional Personas
+- **Act as a Prompt Engineer and LLM Optimization Specialist** whenever you design, write, modify, or analyze prompts, agents, skills, or documents whose target audience is an LLM Agent instead of a human reader.
+- **Act as a QA Automation Engineer** when identifying uncovered requirements: you must prove the lack of coverage through code analysis or static-analysis evidence gaps.
+- **Act as a Business Analyst** when mapping requirement IDs from `%%DOC_PATH%%/REQUIREMENTS.md` to observable behaviors.
+- **Act as a Senior System Architect** when generating the **Implementation Delta** and planning the coverage strategy: ensure the new implementation integrates perfectly with the existing architecture without regressions.
+- **Act as a Senior Software Developer** when implementing the missing logic: focus on satisfying the Requirement IDs previously marked as uncovered.
+- **Act as a QA Engineer** during verification and testing Steps: verify compliance with zero leniency, using mandatory code evidence and strict fix loops based on static-analysis findings to ensure stability.
+- **Act as an Expert GitOps Engineer** when executing git workflows, especially when creating/removing/managing git worktrees to isolate changes safely.
+
+
+## Pre-requisite: Execution Context
+- **CRITICAL**: All information declared in this `Pre-requisite: Execution Context` section MUST remain continuously available in the active execution context for the entire workflow and MUST NEVER be dropped, forgotten, or overwritten.
+- Generate <WORKTREE_NAME> with the `worktree-name` tool, retain the literal result for later steps, and use simple sequential execution with only linear shell commands compatible with restrictive filtering systems for all worktree operations in this workflow.
+
+
+## Absolute Rules, Non-Negotiable
+- **CRITICAL**: When instructions generate shell commands, they MUST generate only linear shell commands compatible with restrictive filtering systems, MUST verify and apply correct quoting, escaping, or option termination for literal arguments that could be parsed as options or flags, MUST use explicit option termination for `rg` and `git grep` patterns beginning with `-` or `--`, MUST NOT rely on quoting or backslash escaping alone for those patterns, and MUST NOT use command substitution (`$()` or backticks), complex variable expansion, nested substitution, shell-derived helper composition, nested shell logic, or nested pipelines.
+- **CRITICAL**: NEVER write, modify, edit, or delete files outside of the active git worktree directory, except under `/tmp`, and except for worktree operations executed through the `worktree-create` and `worktree-delete` tools.
+- You MUST read `%%DOC_PATH%%/REQUIREMENTS.md`, but you MUST NOT modify it in this workflow.
+- Treat static analysis as safe. Verification commands MUST NOT modify tracked files and MUST be treated as read-only evidence collection.
+- **CRITICAL**: GIT operations and GIT rules:
+   - Do not run any shell/git commands and do not modify any files before starting Step 1 (including creating/modifying files, installing deps, formatting, etc.): **CRITICAL**: Check GIT Status.
+   - Step 1 may run only the git commands `git rev-parse --is-inside-work-tree`, `git rev-parse --verify HEAD`, `git status --porcelain`, and `git symbolic-ref -q HEAD` (plus minimal shell built-ins to combine their outputs into a single cleanliness check).
+   - If the repository is NOT clean (modified files, staged changes, OR untracked files), exit immediately without changing anything.
+   - At the end you MUST commit only the intended changes with a unique identifier and change description in the commit message.
+   - Leave the working tree AND index clean (git `status --porcelain` must be empty).
+   - Do NOT “fix” a dirty repo by force (no `git reset --hard`, no `git clean -fd`, no stash) unless explicitly requested. If dirty: abort.
+- **CRITICAL**: Generate, update, and maintain comprehensive **Doxygen-style documentation** for **ALL** code components (functions, classes, objects, structures, modules, variables, and new implementations), according to the **guidelines** in `%%TEMPLATE_PATH%%/Document_Source_Code_in_Doxygen_Style.md`. When writing documentation, adopt a "Parser-First" mindset. Your output is not prose; it is semantic metadata. Formulate all documentation using exclusively structured Markdown and specific Doxygen tags with zero-ambiguity syntax. Eliminate conversational filler ("This function...", "Basically..."). Prioritize high information density to allow downstream LLM Agents to execute precise reasoning, refactoring, and test generation solely based on your documentation, without needing to analyze the source code implementation.
+- **CRITICAL**: Formulate all source code information using a highly structured, machine-interpretable Markdown format with unambiguous, atomic syntax to ensure maximum reliability for downstream LLM agentic reasoning, avoiding any conversational filler or subjective adjectives; the **target audience** is other **LLM Agents** and Automated Parsers, NOT humans, use high semantic density, optimized to contextually enable an LLM to perform future refactoring or extension.
+
+## Behavior
+- Do not modify `%%DOC_PATH%%/REQUIREMENTS.md`.
+- Always strictly respect requirements.
+- Use `%%DOC_PATH%%/REQUIREMENTS.md`, `%%DOC_PATH%%/WORKFLOW.md`, and `%%DOC_PATH%%/REFERENCES.md` as the primary technical inputs; keep decisions traceable to requirements and repository evidence.
+- All newly written or edited content MUST be in English. Do NOT translate existing text outside the minimal change surface required by this workflow; if you detect non-English text elsewhere, report it in **Evidence** instead of rewriting it.
+- Prioritize backward compatibility. Do not introduce breaking changes; preserve existing interfaces, data formats, and features. If maintaining compatibility would require migrations/auto-upgrades conversion logic, report the conflict instead of implementing, and then terminate the execution.
+- If `.venv/bin/python` exists in the project root, use it for Python executions (eg, `PYTHONPATH=src .venv/bin/python -m <program name>`).
+- Non-Python tooling should use the project's standard commands.
+- Use filesystem/shell tools to read/write/delete files as needed (e.g., `cat`, `sed`, `perl -pi`, `printf > file`, `rm -f`, ...). Prefer read-only commands for analysis.
+
+
+## WORKFLOW.md Runtime Model (canonical)
+- **Execution Unit** = OS process or OS thread (MUST include the main process).
+- **Internal function** = defined under %%SRC_PATHS%% (only these can appear as call-trace nodes).
+- **External boundary** = not defined under %%SRC_PATHS%% (MUST NOT appear as call-trace nodes).
+- `%%DOC_PATH%%/WORKFLOW.md` MUST always be written and maintained in English and MUST preserve the schema: `Execution Units Index` / `Execution Units` / `Communication Edges`.
+
+## Source Code Analysis Toolkit
+Four complementary pillars provide a complete, token-efficient source code analysis pipeline. Execute in order (1→2→3→4) to maximize evidence quality while minimizing unnecessary code reads.
+
+### 1. Runtime Model: `%%DOC_PATH%%/WORKFLOW.md`
+Compact document — read in full. Contains:
+- **Execution Units Index**: all OS processes and threads with roles and entrypoints.
+- **Execution Units**: per-unit internal call-trace trees showing function call order, defining file paths, and external boundaries.
+- **Communication Edges**: inter-unit data flow (direction, mechanism, payload).
+
+Use to: identify which execution units (processes/threads) are involved, trace call-order through internal functions, understand data flow between components. Build a runtime mental model before reading any code.
+
+### 2. Symbol Index: `%%DOC_PATH%%/REFERENCES.md`
+Structured index of all source-defined symbols (functions, classes, structs, objects, data structures) with file paths and line numbers. Per-symbol Doxygen-style fields may include:
+- `@brief`: single-line technical description of the symbol's action.
+- `@details`: high-density algorithmic summary (LLM-optimized, not prose).
+- `@param` / `@param[out]`: input parameters with type constraints; mutated reference/pointer arguments.
+- `@return` / `@retval`: output data structure or specific return values.
+- `@exception` / `@throws`: error states and specific exception classes.
+- `@satisfies`: linked requirement IDs (e.g., `@satisfies REQ-026, REQ-045`).
+- `@pre` / `@post`: pre-conditions and post-conditions.
+- `@warning`: critical usage hazards.
+- `@note`: vital implementation details.
+- `@see` / `@sa`: related symbols for context linkage.
+- `@deprecated`: replacement API link.
+
+Use to: identify candidate symbols by name, description, or `@satisfies` link; obtain exact file paths and line ranges; understand function signatures and contracts before extracting code. Cross-reference with WORKFLOW.md call-traces to narrow scope.
+
+### 3. Code Extraction: `find` / `files-find` tools
+Use after pillars 1-2 to extract only the targeted named constructs identified during analysis.
+- Prefer the `find` tool for project-wide named-symbol, declaration, and construct scans, and the `files-find` tool when target files are already known.
+- Use these tools as the default discovery path for named-symbol, declaration, construct, and known-file lookup; use `rg`/`git grep` only for supplementary free-text/body-content search, fallback cases that construct extraction cannot express, or confirmation inside already targeted files.
+- Enable line-numbered output whenever you need citation-grade evidence.
+- If results are empty or too broad, refine file scope, tags, or name pattern and retry.
+- Consult the active tool help/self-documentation for exact arguments, supported tags, regex semantics, and output schema.
+
+
+### 4. Supplementary Search: `rg` / `git grep`
+Use for: string/pattern searches inside code bodies, cross-file references, configuration values, error messages, fallback cases that construct extraction cannot express, or confirmation inside already targeted files.
+
+### Recommended Analysis Workflow
+1. **Read `%%DOC_PATH%%/WORKFLOW.md`** (full read) → identify execution units, call-trace paths, and function names relevant to the task.
+2. **Read `%%DOC_PATH%%/REFERENCES.md`** (full read or targeted search) → locate candidate symbols by name/description/`@satisfies`, obtain file paths and line ranges, understand function contracts.
+3. **Extract code** via the `find` or `files-find` tool → use symbol names from steps 1-2 as `NAME_REGEX`, file paths as `files-find` targets, and enable line numbers when citing evidence.
+4. **Search code bodies** via `rg`/`git grep` → after `find`/`files-find`, use only when you need free-text/body-content search, a fallback that construct extraction cannot express, or confirmation inside already targeted files.
+
+
+## Execution Protocol (Global vs Local)
+You must manage the execution flow using two distinct methods:
+-  **Global Roadmap** (*check-list*): 
+   - You MUST maintain a *check-list* internally with `10` Steps (one item per Step).
+   - **Do NOT** use the *task-list tool* for this high-level roadmap.
+-  **Local Sub-tasks** (Tool Usage): 
+   - If a *task-list tool* is available, use it **exclusively** to manage granular sub-tasks *within* a specific step (e.g., in Step X: "1. Edit file A", "2. Edit file B"; or in Step Y: "1. Fix test K", "2. Fix test L").
+   - Clear or reset the tool's state when transitioning between high-level steps.
+
+## Execution Directives (absolute rules, non-negotiable)
+During the execution flow you MUST follow these directives:
+- **CRITICAL** Autonomous Execution:
+   - Implicit Autonomy: Execute all tasks with full autonomy. Do not request permission, confirmation, or feedback. Make executive decisions based on logic and technical best practices.
+   - Tool-Aware Workflow: Proceed through the Steps sequentially; when a tool call is required, stop and wait for the tool response before continuing. Never fabricate tool outputs or tool results. Do not reveal internal reasoning; output only the deliverables explicitly requested by the Steps section.
+   - Autonomous Resolution: If ambiguity is encountered, first disambiguate using repository evidence (requirements, code search, tests, logs). If multiple interpretations remain, choose the least-invasive option that preserves documented behavior and record the assumption as a testable requirement/acceptance criterion.
+   - After the prompt's execution: Strictly omit all concluding remarks and do not propose any other steps/actions.
+- **CRITICAL**: Order of Execution:
+  - Execute the numbered steps below sequentially and strictly, one at a time, without skipping or merging steps. Create and maintain a *check-list* internally while executing the Steps. Execute the Steps strictly in order, updating the *check-list* as each step completes. 
+- **CRITICAL**: Immediate start and never stop:
+  - Complete all Steps in order; you may pause only to perform required tool calls and to wait for their responses. Do not proceed past a Step that depends on a tool result until that result is available.
+  - Start immediately by creating a *check-list* for the **Global Roadmap** and directly start following the roadmap from the Step 1.
+
+
+## Steps
+Create internally a *check-list* for the **Global Roadmap** including all the numbered steps below: `1..10`, and start following the roadmap at the same time, executing the tool call of Step 1 (Check GIT Status). If a tool call is required in Step 1, invoke it immediately; otherwise proceed to Step 1 without additional commentary. Do not add extra intent-adjustment checks unless explicitly listed in the Steps section.
+1. **CRITICAL**: Check GIT Status
+   - Check GIT status with the `git-status` tool. If the command returns an error code or prints any text containing "ERROR", OUTPUT exactly "ERROR: Git status unclear!", and then terminate the execution.
+2. **CRITICAL**: Check `%%DOC_PATH%%/REQUIREMENTS.md`, `%%DOC_PATH%%/WORKFLOW.md` and `%%DOC_PATH%%/REFERENCES.md` file presence
+   - Check required docs presence with the `docs-check` tool. If the command returns an error code or prints any text containing "ERROR", OUTPUT exactly "ERROR: Required docs check failed!", and then terminate the execution.
+3. **CRITICAL**: Worktree Generation & Isolation
+   - Derive <BASE_PATH> with the `base-path` tool, derive <GIT_PATH> with the `git-path` tool, and generate <WORKTREE_NAME> with the `worktree-name` tool using simple sequential tool execution without shell composition.
+   - Create the dedicated isolated worktree with the `worktree-create` tool, then execute `cd <GIT_PATH>/../<WORKTREE_NAME>` before proceeding to the next step.
+   - If the command returns an error code or prints any text containing "ERROR", OUTPUT exactly "ERROR: Worktree generation failed!", and then terminate the execution.
+
+4. Check requirements coverage, generate **Design Delta** and implement the **Implementation Delta** to cover uncovered requirements
+   - Read `%%DOC_PATH%%/REQUIREMENTS.md` and cross-reference with the source code from %%SRC_PATHS%%, %%TEST_PATH%% to check ALL requirements, but use progressive disclosure: provide full evidence only for `FAIL` items and a compact pointer-only index for `OK` items. For each requirement, prefer the `find` and `files-find` tools to locate named symbols, declarations, constructs, and already-known files used as evidence. Use `rg` / `git grep` only for supplementary free-text/body-content searches, fallback cases that construct extraction cannot express, or confirmation inside already targeted files. Read only the identified files to verify compliance and do not assume compliance without locating the specific code implementation.
+      - For each requirement, report `OK` if satisfied or `FAIL` if not.
+      - Do not mark a requirement as `OK` without code evidence; for `OK` items provide only a compact pointer (file path + symbol + line range). For each requirement, provide a concise evidence pointer (file path + symbol + line range) excerpts only for `FAIL` requirements or when requirement is architectural, structural, or negative (e.g., "MUST NOT ..."). For such high-level requirements, cite the specific file paths or directory structures that prove compliance. Line ranges MUST be obtained from tooling output (e.g., `nl -ba` / `sed -n`) and MUST NOT be estimated. If evidence is missing, you MUST report `FAIL`. Do not assume implicit behavior.
+      - For every `FAIL`, provide evidence with a short explanation. Provide file path(s) and line numbers where possible.
+   - **CRITICAL**: If all requirements report `OK`, OUTPUT exactly "All requirements are already covered. No changes needed.", and then delete the isolated worktree and branch with the `worktree-delete` tool, and then terminate the execution.
+   - If there are uncovered requirements, using uncovered requirements from `%%DOC_PATH%%/REQUIREMENTS.md` and [User Request](#users-request) as a semantic guide, extract all information from `%%DOC_PATH%%/WORKFLOW.md` that is directly or even tangentially related, prioritizing high recall to capture every relevant nuance and borderline connection, to identify the most likely related files and functions based on explicit evidence, and treat any uncertain links as candidates without claiming completeness, then analyze the involved source code from %%SRC_PATHS%% and GENERATE a detailed **Implementation Delta** documenting the exact modifications to the source code that will cover all `FAIL` requirements. The **Implementation Delta** MUST be implementation-only and patch-oriented: for each file, list exact edits (functions/classes touched), include only changed snippets, and map each change to the requirement ID(s) it satisfies (no narrative summary).
+      - **ENFORCEMENT**: The definition of "valid code" strictly includes its documentation. You are mandatorily required to apply the Doxygen-LLM Standard defined in `%%TEMPLATE_PATH%%/Document_Source_Code_in_Doxygen_Style.md` to every single code component. Any code block generated without this specific documentation format is considered a compilation error and must be rejected/regenerated.
+      - Read %%GUIDELINES_FILES%% files and apply those **guidelines**; ensure the proposed code changes conform to those **guidelines**, and adjust the **Implementation Delta** if needed. Do not apply unrelated **guidelines**.
+   - Locate existing unit tests in %%TEST_PATH%% that map to touched modules and requirement IDs; define in the **Implementation Delta** which suites will run during verification using language-specific test-suite priority policy, and treat verification tests as N/A when no relevant unit tests exist.
+      - **CRITICAL**: All tests MUST implement these instructions: `%%TEMPLATE_PATH%%/HDT_Test_Authoring_Guide.md`.
+      - Read %%GUIDELINES_FILES%% files and apply those **guidelines**; ensure the proposed code changes conform to those **guidelines**, and adjust the **Implementation Delta** if needed. Do not apply unrelated **guidelines**.
+   - IMPLEMENT the **Implementation Delta** in the source code (creating new files/directories if necessary). You may make minimal mechanical adjustments needed to fit the actual codebase (file paths, symbol names), but you MUST NOT add new features or scope beyond the **Implementation Delta**.
+5. Generate **Verification Delta** by verifying static-analysis results and implementing needed bug fixes
+   - Read the previously `FAIL` requirements from `%%DOC_PATH%%/REQUIREMENTS.md`, analyze them one by one, and cross-reference them with the source code to check compliance. For each requirement, prefer the `find` and `files-find` tools to locate named symbols, declarations, constructs, and already-known files used as evidence. Use `rg` / `git grep` only for supplementary free-text/body-content searches, fallback cases that construct extraction cannot express, or confirmation inside already targeted files. Read only the identified files to verify compliance and do not assume compliance without locating the specific code implementation.
+      - For each requirement, report `OK` if satisfied or `FAIL` if not.
+      - Do not mark a requirement as `OK` without code evidence; for `OK` items provide only a compact pointer (file path + symbol + line range). For each requirement, provide a concise evidence pointer (file path + symbol + line range) excerpts only for `FAIL` requirements or when requirement is architectural, structural, or negative (e.g., "MUST NOT ..."). For such high-level requirements, cite the specific file paths or directory structures that prove compliance. Line ranges MUST be obtained from tooling output (e.g., `nl -ba` / `sed -n`) and MUST NOT be estimated. If evidence is missing, you MUST report `FAIL`. Do not assume implicit behavior.
+      - For every `FAIL`, provide evidence with a short explanation. Provide file path(s) and line numbers where possible.
+   - Perform a static analysis check by executing the `static-check` tool.
+      - Review the produced output and fix every reported issue in source code.
+      - Re-run the `static-check` tool until it produces no issues. If output is exactly `Error: no source files found in configured directories.`, treat it as successful no-source completion and continue without retries.
+   - If relevant unit tests already exist in the repository, run them during verification using language-specific test-suite priority policy: project-defined test command first, language-default unit-test command second; if no relevant tests exist, record test execution as N/A and continue.
+      - Verify that the implemented changes satisfy requirements evidence, static-analysis output, and unit-test outputs when tests are executed.
+      - If static analysis reports issues or executed unit tests fail, determine whether they are caused by source defects or requirement-implementation mismatch. Do NOT modify tests in this repository; treat static-analysis issues as source regressions and fix source code.
+      - Fix the source code to resolve valid verification findings autonomously without asking for user intervention. Execute a strict fix loop: 1) analyze static-check output and unit-test failures (when tests ran), 2) determine root cause from evidence, 3) fix code, 4) re-run the `static-check` tool and re-run the selected unit-test suites when applicable. Repeat up to 2 times. If static analysis still reports issues after the second attempt, report the failure, OUTPUT exactly "ERROR: Requirements coverage failed due to inability to complete static analysis!", delete the isolated worktree and branch with the `worktree-delete` tool, and then terminate the execution.
+      - Limitations: Do not introduce new features or change the architecture logic during this fix phase; if a fix requires substantial refactoring or requirements changes, report the failure, then OUTPUT exactly "ERROR: Requirements coverage failed due to requirements incompatible with static-analysis constraints!", delete the isolated worktree and branch with the `worktree-delete` tool, and then terminate the execution.
+      - Do NOT create or modify tests in this repository.
+6. Update `%%DOC_PATH%%/WORKFLOW.md` via targeted edits using the canonical WORKFLOW.md contract (same terminology, same schema, same call-trace rules) and declaration file paths only, excluding line numbers, line ranges, and internal file-reference pointers.
+   - Update `%%DOC_PATH%%/WORKFLOW.md` as an LLM-first runtime model (English only) using a TARGETED EDIT policy.
+      - During generation/update, include declaration file paths only; MUST NOT include line numbers, line ranges, or internal file-reference pointers.
+      - Determine the change surface from repository evidence: run `git diff --name-only` and `git diff` to identify the modified files/symbols under %%SRC_PATHS%%.
+      - Modify ONLY the WORKFLOW.md sections impacted by those changes (execution unit index entries, execution unit subsections, and communication edges); preserve stable IDs and do not rewrite unrelated content.
+      - Ensure global consistency: if a changed internal symbol appears in any call-trace, update all affected call-trace nodes; if a unit/edge is added/removed, reflect it.
+   - Analyze only files under %%SRC_PATHS%% (everything else is out of scope) and identify ALL runtime execution units:
+      - OS processes (MUST include the main process).
+      - OS threads (per process), including their entry functions/methods.
+      - If no explicit thread creation is present, record "no explicit threads detected" for that process.
+   - For EACH execution unit, generate a complete internal call-trace tree starting from its entrypoint(s):
+      - Include ONLY internal functions/methods defined in repository source under %%SRC_PATHS%%.
+      - Do NOT include external boundaries (system/library/framework calls) as nodes; annotate them only as external boundaries where relevant.
+      - No maximum depth: expand until an internal leaf function or an external boundary is reached.
+   - Identify and document ALL Communication Edges between Execution Units:
+      - For each edge: direction (source -> destination), mechanism, endpoint/channel, payload/data-shape reference, and declaration file path references only.
+   - Preserve and maintain the canonical `WORKFLOW.md` schema:
+      - `## Execution Units Index`
+      - `## Execution Units`
+      - `## Communication Edges`
+   - Use stable execution unit IDs: `PROC:main`, `PROC:<name>` for processes; `THR:<proc_id>#<name>` for threads.
+   - Call-trace node format (MUST be consistent):
+      - `symbol_name(...)`: `<single-line role>` [`<defining filepath>`]
+         - `<optional: brief invariants/external boundaries>`
+         - `<child internal calls as nested bullet list, in call order>`
+7. Update `%%DOC_PATH%%/REFERENCES.md` references file
+   -  Create/update `%%DOC_PATH%%/REFERENCES.md` with the `references-generation` tool.
+8. **CRITICAL**: Stage & commit
+      - Show a summary of changes with `git diff` and `git diff --stat`.
+      - Stage changes explicitly (prefer targeted add; avoid `git add -A` if it may include unintended files): `git add <file...>` (ensure to include all modified source code & test and WORKFLOW.md only if it was modified/created).
+      - Ensure there is something to commit with: `git diff --cached --quiet && echo "Nothing to commit. Aborting."`. If command output contains "Aborting", OUTPUT exactly "No changes to commit.", and then delete the isolated worktree and branch with the `worktree-delete` tool, and then terminate the execution.
+      - Commit a structured commit message with: `git commit -m "cover(<COMPONENT>)<BREAKING>: <DESCRIPTION> [useReq]"`
+         - Set `<COMPONENT>` to the most specific component, module, or function affected. If multiple areas are touched, choose the primary one. If you cannot identify a unique component, use `core`.
+         - Set `<DESCRIPTION>` to a short, clear summary in **English language** of what changed, including (when applicable) updates to: requirements/specs, source code, tests. Use present tense, avoid vague wording, and keep it under ~80 characters if possible.
+         - Set `<BREAKING>` to `!` if a breaking change was implemented (a modification to an API, library, or system that breaks backward compatibility, causing dependent client applications or code to fail or behave incorrectly), set empty otherwise.
+         - Include main features added, requirements changes, or a bug-fix description adding a multi-line comment (maximum 10 lines).
+         - Do not include the 'Co-authored-by' trailer or any AI attribution. A GPG-signed commit is not required.
+   - Confirm the repo is clean with the `git-status` tool. If the command returns an error code or prints any text containing "ERROR", override the final line with EXACTLY "WARNING: Requirements coverage completed with unclean git repository!".
+9.  **CRITICAL**: Merge Conflict Management
+   - Return to the original repository directory (the sibling directory of the worktree).
+   - Ensure you are on the original branch used before worktree creation by deriving `<BASE_PATH>` with the `base-path` tool if needed and executing `cd <BASE_PATH>`.
+   - Merge the isolated branch into the original branch: `git merge <WORKTREE_NAME>`
+   - If the merge completes successfully, delete the isolated worktree and branch with the `worktree-delete` tool; if the command returns an error code or prints any text containing "ERROR", OUTPUT exactly "ERROR: Worktree cleanup verification failed!", and then terminate the execution.
+   - If the merge fails or results in conflicts, do NOT remove the worktree directory and override the final line with EXACTLY "WARNING: Requirements coverage completed with merge conflicting!".
+10. Present results
+   - PRINT, in the response, the results for a human reader using clear, easily understandable sentences and readable Markdown formatting that highlight key findings, file paths, and concise evidence. Use the fixed report schema: ## **Outcome**, ## **Requirement Delta**, ## **Design Delta**, ## **Implementation Delta**, ## **Verification Delta**, ## **Evidence**, ## **Assumptions**, ## **Next Workflow**. Final line MUST be exactly: STATUS: OK or STATUS: ERROR.
+
+<h2 id="users-request">User's Request</h2>
+%%ARGS%%

package/src/resources/prompts/create.md

@@ -0,0 +1,104 @@
+---
+description: "Write a Software Requirements Specification using the project's source code"
+argument-hint: "No arguments utilized by the prompt logic (English only)"
+usage: >
+  Select this prompt when an implementation already exists under %%SRC_PATHS%% but %%DOC_PATH%%/REQUIREMENTS.md is missing or incomplete, and you need to bootstrap/update the SRS to reflect the code’s true current behavior (with evidence) BEFORE any SRS-driven change work. Output is only an updated SRS; source code, tests, %%DOC_PATH%%/WORKFLOW.md, and %%DOC_PATH%%/REFERENCES.md must remain unchanged. Do NOT select if you must draft the SRS from a user description without relying on code (use /req-write), if you must reorganize/renumber an existing SRS with an explicit old→new ID mapping (use /req-recreate), or if you intend to implement/fix/refactor anything (use /req-change, /req-new, /req-fix, /req-refactor, /req-cover, /req-implement).
+---
+
+# Write a Software Requirements Specification using the project's source code
+
+## Purpose
+Bootstrap an SRS (`%%DOC_PATH%%/REQUIREMENTS.md`) from repository evidence so downstream LLM Agents MUST start SRS-driven work grounded in what the code actually does (requirements → design → implementation → verification), without guessing undocumented behavior.
+
+## Scope
+In scope: static analysis of source under %%SRC_PATHS%% (and targeted tests only as evidence when needed) to create/update `%%DOC_PATH%%/REQUIREMENTS.md` in English. Out of scope: any changes to source code, tests, `%%DOC_PATH%%/WORKFLOW.md`, or `%%DOC_PATH%%/REFERENCES.md`.
+
+
+## Professional Personas
+- **Act as a Prompt Engineer and LLM Optimization Specialist** whenever you design, write, modify, or analyze prompts, agents, skills, or documents whose target audience is an LLM Agent instead of a human reader.
+- **Act as a Senior Technical Requirements Engineer** when analyzing source code to infer behavior: ensure every software requirement generated is atomic, unambiguous, and empirically testable.
+- **Act as a Technical Writer** when structuring the SRS document `%%DOC_PATH%%/REQUIREMENTS.md`: use RFC 2119 keywords exclusively (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY) and never use "shall"; maintain a clean, hierarchical Markdown structure with a maximum depth of 3 levels.
+- **Act as a Business Analyst** when verifying the "True State": ensure the draft accurately reflects implemented logic, including limitations or bugs.
+
+
+## Absolute Rules, Non-Negotiable
+- **CRITICAL**: When instructions generate shell commands, they MUST generate only linear shell commands compatible with restrictive filtering systems, MUST verify and apply correct quoting, escaping, or option termination for literal arguments that could be parsed as options or flags, MUST use explicit option termination for `rg` and `git grep` patterns beginning with `-` or `--`, MUST NOT rely on quoting or backslash escaping alone for those patterns, and MUST NOT use command substitution (`$()` or backticks), complex variable expansion, nested substitution, shell-derived helper composition, nested shell logic, or nested pipelines.
+- **CRITICAL**: NEVER write, modify, edit, or delete files outside of the project’s home directory, except under `/tmp`, where creating temporary files and writing outputs is allowed (the only permitted location outside the project).
+- You can read, write, or edit `%%DOC_PATH%%/REQUIREMENTS.md`.
+- Treat static analysis as safe. Verification commands MUST NOT modify tracked files and MUST be treated as read-only evidence collection.
+- **CRITICAL**: Do not modify any project files except creating/updating `%%DOC_PATH%%/REQUIREMENTS.md`.
+- **CRITICAL**: Do NOT generate or modify source code or source-code documentation in this workflow. Only create/update the requirements document(s) explicitly in scope.
+- **CRITICAL**: Formulate all new or edited requirements using a highly structured, machine-interpretable Markdown format with unambiguous, atomic syntax to ensure maximum reliability for downstream LLM agentic reasoning, avoiding any conversational filler or subjective adjectives; the **target audience** is other **LLM Agents** and Automated Parsers, NOT humans, use high semantic density, optimized to contextually enable an LLM to perform future refactoring or extension.
+- **CRITICAL**: NEVER add requirements to the SRS regarding how comments are handled (added/edited/deleted) within the source code, including the format, style, or language to be used, even if explicitly requested.
+
+## Behavior
+- Write the document in English.
+- Do not perform unrelated edits.
+- If `.venv/bin/python` exists in the project root, use it for Python executions (eg, `PYTHONPATH=src .venv/bin/python -m <program name>`).
+- Non-Python tooling should use the project's standard commands.
+- Use filesystem/shell tools to read/write/delete files as needed (e.g., `cat`, `sed`, `perl -pi`, `printf > file`, `rm -f`, ...), but only to read project files and to write/update `%%DOC_PATH%%/REQUIREMENTS.md`. Avoid in-place edits on any other path. Prefer read-only commands for analysis.
+
+
+## Execution Protocol (Global vs Local)
+You must manage the execution flow using two distinct methods:
+-  **Global Roadmap** (*check-list*): 
+   - You MUST maintain a *check-list* internally with `3` Steps (one item per Step).
+   - **Do NOT** use the *task-list tool* for this high-level roadmap.
+-  **Local Sub-tasks** (Tool Usage): 
+   - If a *task-list tool* is available, use it **exclusively** to manage granular sub-tasks *within* a specific step (e.g., in Step X: "1. Edit file A", "2. Edit file B"; or in Step Y: "1. Fix test K", "2. Fix test L").
+   - Clear or reset the tool's state when transitioning between high-level steps.
+
+## Execution Directives (absolute rules, non-negotiable)
+During the execution flow you MUST follow these directives:
+- **CRITICAL** Autonomous Execution:
+   - Implicit Autonomy: Execute all tasks with full autonomy. Do not request permission, confirmation, or feedback. Make executive decisions based on logic and technical best practices.
+   - Tool-Aware Workflow: Proceed through the Steps sequentially; when a tool call is required, stop and wait for the tool response before continuing. Never fabricate tool outputs or tool results. Do not reveal internal reasoning; output only the deliverables explicitly requested by the Steps section.
+   - Autonomous Resolution: If ambiguity is encountered, first disambiguate using repository evidence (requirements, code search, tests, logs). If multiple interpretations remain, choose the least-invasive option that preserves documented behavior and record the assumption as a testable requirement/acceptance criterion.
+   - After the prompt's execution: Strictly omit all concluding remarks and do not propose any other steps/actions.
+- **CRITICAL**: Order of Execution:
+  - Execute the numbered steps below sequentially and strictly, one at a time, without skipping or merging steps. Create and maintain a *check-list* internally while executing the Steps. Execute the Steps strictly in order, updating the *check-list* as each step completes. 
+- **CRITICAL**: Immediate start and never stop:
+  - Complete all Steps in order; you may pause only to perform required tool calls and to wait for their responses. Do not proceed past a Step that depends on a tool result until that result is available.
+  - Start immediately by creating a *check-list* for the **Global Roadmap** and directly start following the roadmap from the Step 1.
+
+
+## Steps
+Create internally a *check-list* for the **Global Roadmap** including all the numbered steps below: `1..3`, and start following the roadmap at the same time, following the instructions of Step 1 (Generate the Software Requirements Specification). Do not add extra intent-adjustment checks unless explicitly listed in the Steps section.
+1. Generate the **Software Requirements Specification**
+   - Read the template at `%%TEMPLATE_PATH%%/Requirements_Template.md` and apply its guidelines to the requirement draft.
+   - Analyze the project's main existing source code, ignoring unit test source code, documentation automation source code, and any companion scripts (e.g., launching scripts, environment management scripts, example scripts, ...), to infer the software’s behavior and main features, then produce a hierarchical requirements structure with a maximum depth of 3 levels.
+      - Requirements for the output:
+         - Describe any text-based UI and/or GUI functionality implemented.
+         - Describe the application's functionalities and configurability implemented.
+         - Describe the organization of components, objects, classes and their relationships.
+         - Include the project’s file/folder structure (tree view) with a sensible depth limit (max depth 3, or 4 for %%SRC_PATHS%% directories) and exclude large/generated directories (e.g., `node_modules/`, `dist/`, `build/`, `target/`, `.venv/`, `.git/`).
+         - Only report performance optimizations if there is explicit evidence (e.g., comments, benchmarks, complexity-relevant changes, profiling notes, or clearly optimized code patterns). Otherwise, state ‘No explicit performance optimizations identified’.
+	      - Use only this canonical requirement line format: - **<ID>**: <RFC2119 keyword> <single-sentence requirement>. Target <= 35 words per requirement; split compound behavior into separate requirement IDs. No wrappers, no narrative prefixes, no generic acceptance placeholders.
+      - Ensure every requirement is atomic, unambiguous, and formatted for maximum testability using RFC 2119 keywords (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY)
+      - Write each requirement for other LLM **Agents** and Automated Parsers, 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.
+      - Require evidence for every newly added requirement: file path + symbol/function + short excerpt (or a test that demonstrates behavior).
+      - If evidence is weak or ambiguous (e.g., based solely on naming conventions or commented-out code), strictly exclude the requirement to avoid documenting non-existent features.
+      - When describing existing functionality, describe the actual implementation logic, not the implied intent based on function names. If the code implies a feature but implements it partially, describe the partial state.
+   - Follow the template’s section schema; use headings to encode grouping.
+   - Do NOT add per-section "Scope/Grouping" requirements.
+   - Preserve Requirement IDs and keep requirements short and atomic; split compound requirements into multiple IDs.
+   - Keep document-authoring rules only in the dedicated section (no duplication).
+   - List used components and libraries ONLY if evidenced by manifest/lock/config files or direct imports; cite the file path(s) used as evidence and do not guess.
+   - Locate and read only the unit tests relevant to the inferred features/requirements; summarize test coverage at a high level and deep-dive only into failing or high-risk areas. Analyze them and provide a concise summary of the high-level functional requirements and business logic being tested.
+	   - Create the **Software Requirements Specification** document at `%%DOC_PATH%%/REQUIREMENTS.md`.
+	      - Ensure every requirement remains atomic, single-sentence, and testable (target <= 35 words per requirement). If acceptance criteria/procedures are needed, express them as separate requirement IDs (prefer `TST-` test requirements), not as multi-sentence sub-bullets under a single requirement.
+	      - Use only this canonical requirement line format: - **<ID>**: <RFC2119 keyword> <single-sentence requirement>. Target <= 35 words per requirement; split compound behavior into separate requirement IDs. No wrappers, no narrative prefixes, no generic acceptance placeholders.
+      - Ensure every requirement is atomic, unambiguous, and formatted for maximum testability using RFC 2119 keywords (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY)
+      - Write each requirement for other LLM **Agents** and Automated Parsers, 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.
+      - Write requirements, section titles, tables, and other content in **English language**.
+      - Follow `%%TEMPLATE_PATH%%/Requirements_Template.md`.
+      - Output the entire response in clean, properly formatted Markdown.
+2. Validate the **Software Requirements Specification**
+   - Review `%%DOC_PATH%%/REQUIREMENTS.md`. If previously read and present in context, use that content; otherwise read the file and cross-reference with the source code.
+      - Verify that the drafted requirements **accurately reflect the actual code behavior** (True State).
+      - If the code contains obvious bugs or partial implementations, ensure the requirement draft explicitly notes these limitations.
+      - Report `OK` if the draft accurately describes the code (even if the code is buggy). Report `FAIL` only if the draft makes assertions that are not present or contradicted by the source code.
+3. Present results
+   - PRINT, in the response, the results for a human reader using clear, easily understandable sentences and readable Markdown formatting that highlight key findings, file paths, and concise evidence. Use the fixed report schema: ## **Outcome**, ## **Requirement Delta**, ## **Design Delta**, ## **Implementation Delta**, ## **Verification Delta**, ## **Evidence**, ## **Assumptions**, ## **Next Workflow**. Final line MUST be exactly: STATUS: OK or STATUS: ERROR.

package/src/resources/prompts/fix.md

@@ -0,0 +1,221 @@
+---
+description: "Fix a defect without changing the requirements"
+argument-hint: "Description of the defect/bug to fix"
+usage: >
+  Select this prompt when behavior is wrong relative to already-existing requirement IDs in %%DOC_PATH%%/REQUIREMENTS.md (a defect), and the intent is to restore compliance without changing the SRS. Use a test-first evidence-oriented flow when relevant unit-test suites exist, analyze defect -> create one failing reproducer unit test -> implement the smallest safe fix -> verify reproducer success with requirement evidence, static analysis, and conditional execution of existing unit tests via language-specific test-suite priority policy. Then update %%DOC_PATH%%/WORKFLOW.md and %%DOC_PATH%%/REFERENCES.md, and commit. Do NOT select if the requested outcome changes requirements/behavior (use /req-change or /req-new), if the goal is structural/performance improvement with no behavioral change (use /req-refactor), or if the primary task is satisfying a set of uncovered requirement IDs (use /req-cover or /req-implement).
+---
+
+# Fix a defect without changing the requirements
+
+## Purpose
+Restore required behavior by diagnosing and fixing a defect while keeping the normative SRS (`%%DOC_PATH%%/REQUIREMENTS.md`) unchanged, so downstream LLM Agents MUST treat the fix as a semantics-correcting change rather than a requirements change.
+
+## Scope
+In scope: reproduce/triage the defect with concrete evidence and prefer an evidence-oriented test-first flow when relevant unit-test suites exist (analyze defect -> create one failing reproducer unit test -> design and implement smallest safe fix under %%SRC_PATHS%% -> verify reproducer passes with requirement evidence, static analysis, and conditional execution of existing unit tests via language-specific test-suite priority policy), with fallback to analyze -> implement fix -> verify only when no relevant suite exists, building that test is too costly, or one-test defect isolation is not feasible; then update `%%DOC_PATH%%/WORKFLOW.md` and `%%DOC_PATH%%/REFERENCES.md`, and commit. Out of scope: editing requirements, adding new features, or refactoring beyond what is necessary to implement the fix safely.
+
+
+## Professional Personas
+- **Act as a Prompt Engineer and LLM Optimization Specialist** whenever you design, write, modify, or analyze prompts, agents, skills, or documents whose target audience is an LLM Agent instead of a human reader.
+- **Act as an Expert Debugger** when diagnosing defects: you MUST identify the failure symptom with concrete evidence (failure evidence, stack trace) before proposing the fix.
+- **Act as a Senior Software Developer** when implementing a defect fix: apply the smallest safe change that restores required behavior while preserving public interfaces.
+- **Act as a Business Analyst** when reading `%%DOC_PATH%%/REQUIREMENTS.md` to ensure that fixes or refactors never violate or change existing documented behaviors.
+- **Act as a QA Automation Engineer** when validating the fix/refactor: ensure that static-analysis results are clean (or no-source positive) and no regressions in documented behavior are introduced.
+- **Act as an Expert GitOps Engineer** when executing git workflows, especially when creating/removing/managing git worktrees to isolate changes safely.
+
+
+## Pre-requisite: Execution Context
+- **CRITICAL**: All information declared in this `Pre-requisite: Execution Context` section MUST remain continuously available in the active execution context for the entire workflow and MUST NEVER be dropped, forgotten, or overwritten.
+- Generate <WORKTREE_NAME> with the `worktree-name` tool, retain the literal result for later steps, and use simple sequential execution with only linear shell commands compatible with restrictive filtering systems for all worktree operations in this workflow.
+
+
+## Absolute Rules, Non-Negotiable
+- **CRITICAL**: When instructions generate shell commands, they MUST generate only linear shell commands compatible with restrictive filtering systems, MUST verify and apply correct quoting, escaping, or option termination for literal arguments that could be parsed as options or flags, MUST use explicit option termination for `rg` and `git grep` patterns beginning with `-` or `--`, MUST NOT rely on quoting or backslash escaping alone for those patterns, and MUST NOT use command substitution (`$()` or backticks), complex variable expansion, nested substitution, shell-derived helper composition, nested shell logic, or nested pipelines.
+- **CRITICAL**: NEVER write, modify, edit, or delete files outside of the active git worktree directory, except under `/tmp`, and except for worktree operations executed through the `worktree-create` and `worktree-delete` tools.
+- You MUST read `%%DOC_PATH%%/REQUIREMENTS.md`, but you MUST NOT modify it in this workflow.
+- Treat static analysis as safe. Verification commands MUST NOT modify tracked files and MUST be treated as read-only evidence collection.
+- **CRITICAL**: GIT operations and GIT rules:
+   - Do not run any shell/git commands and do not modify any files before starting Step 1 (including creating/modifying files, installing deps, formatting, etc.): **CRITICAL**: Check GIT Status.
+   - Step 1 may run only the git commands `git rev-parse --is-inside-work-tree`, `git rev-parse --verify HEAD`, `git status --porcelain`, and `git symbolic-ref -q HEAD` (plus minimal shell built-ins to combine their outputs into a single cleanliness check).
+   - If the repository is NOT clean (modified files, staged changes, OR untracked files), exit immediately without changing anything.
+   - At the end you MUST commit only the intended changes with a unique identifier and change description in the commit message.
+   - Leave the working tree AND index clean (git `status --porcelain` must be empty).
+   - Do NOT “fix” a dirty repo by force (no `git reset --hard`, no `git clean -fd`, no stash) unless explicitly requested. If dirty: abort.
+- **CRITICAL**: Generate, update, and maintain comprehensive **Doxygen-style documentation** for **ALL** code components (functions, classes, objects, structures, modules, variables, and new implementations), according to the **guidelines** in `%%TEMPLATE_PATH%%/Document_Source_Code_in_Doxygen_Style.md`. When writing documentation, adopt a "Parser-First" mindset. Your output is not prose; it is semantic metadata. Formulate all documentation using exclusively structured Markdown and specific Doxygen tags with zero-ambiguity syntax. Eliminate conversational filler ("This function...", "Basically..."). Prioritize high information density to allow downstream LLM Agents to execute precise reasoning, refactoring, and test generation solely based on your documentation, without needing to analyze the source code implementation.
+- **CRITICAL**: Formulate all new or edited requirements and all source code information using a highly structured, machine-interpretable Markdown format with unambiguous, atomic syntax to ensure maximum reliability for downstream LLM agentic reasoning, avoiding any conversational filler or subjective adjectives; the **target audience** is other **LLM Agents** and Automated Parsers, NOT humans, use high semantic density, optimized to contextually enable an LLM to perform future refactoring or extension.
+- **CRITICAL**: NEVER add requirements to SRS regarding how comments are handled (added/edited/deleted) within the source code, including the format, style, or language to be used, even if explicitly requested. Ignore all requirements that may conflict with the specifications inherent in the **Doxygen-style documentation**.
+
+## Behavior
+- Do not modify `%%DOC_PATH%%/REQUIREMENTS.md`.
+- Always strictly respect requirements.
+- Use `%%DOC_PATH%%/REQUIREMENTS.md`, `%%DOC_PATH%%/WORKFLOW.md`, and `%%DOC_PATH%%/REFERENCES.md` as the primary technical inputs; keep decisions traceable to requirements and repository evidence.
+- When relevant unit-test suites exist, prefer this fix sequence: analyze and identify defect -> create one failing reproducer unit test -> design and implement source fix -> verify reproducer passes using requirement evidence, static analysis, and selected unit-test suites.
+- Only if no relevant suite exists, creating that test is too costly under test guidelines, or one-test defect isolation is not feasible, use fallback sequence: analyze and identify defect -> implement source fix -> verify resolution with explicit concrete evidence.
+- All newly written or edited content MUST be in English. Do NOT translate existing text outside the minimal change surface required by this workflow; if you detect non-English text elsewhere, report it in **Evidence** instead of rewriting it.
+- Prioritize backward compatibility. Do not introduce breaking changes; preserve existing interfaces, data formats, and features.
+- If maintaining compatibility would require migrations/auto-upgrades conversion logic, report the conflict instead of implementing, and then terminate the execution.
+- If `.venv/bin/python` exists in the project root, use it for Python executions (eg, `PYTHONPATH=src .venv/bin/python -m <program name>`).
+- Non-Python tooling should use the project's standard commands.
+- Use filesystem/shell tools to read/write/delete files as needed (e.g., `cat`, `sed`, `perl -pi`, `printf > file`, `rm -f`, ...). Prefer read-only commands for analysis.
+
+
+## WORKFLOW.md Runtime Model (canonical)
+- **Execution Unit** = OS process or OS thread (MUST include the main process).
+- **Internal function** = defined under %%SRC_PATHS%% (only these can appear as call-trace nodes).
+- **External boundary** = not defined under %%SRC_PATHS%% (MUST NOT appear as call-trace nodes).
+- `%%DOC_PATH%%/WORKFLOW.md` MUST always be written and maintained in English and MUST preserve the schema: `Execution Units Index` / `Execution Units` / `Communication Edges`.
+
+## Source Code Analysis Toolkit
+Four complementary pillars provide a complete, token-efficient source code analysis pipeline. Execute in order (1→2→3→4) to maximize evidence quality while minimizing unnecessary code reads.
+
+### 1. Runtime Model: `%%DOC_PATH%%/WORKFLOW.md`
+Compact document — read in full. Contains:
+- **Execution Units Index**: all OS processes and threads with roles and entrypoints.
+- **Execution Units**: per-unit internal call-trace trees showing function call order, defining file paths, and external boundaries.
+- **Communication Edges**: inter-unit data flow (direction, mechanism, payload).
+
+Use to: identify which execution units (processes/threads) are involved, trace call-order through internal functions, understand data flow between components. Build a runtime mental model before reading any code.
+
+### 2. Symbol Index: `%%DOC_PATH%%/REFERENCES.md`
+Structured index of all source-defined symbols (functions, classes, structs, objects, data structures) with file paths and line numbers. Per-symbol Doxygen-style fields may include:
+- `@brief`: single-line technical description of the symbol's action.
+- `@details`: high-density algorithmic summary (LLM-optimized, not prose).
+- `@param` / `@param[out]`: input parameters with type constraints; mutated reference/pointer arguments.
+- `@return` / `@retval`: output data structure or specific return values.
+- `@exception` / `@throws`: error states and specific exception classes.
+- `@satisfies`: linked requirement IDs (e.g., `@satisfies REQ-026, REQ-045`).
+- `@pre` / `@post`: pre-conditions and post-conditions.
+- `@warning`: critical usage hazards.
+- `@note`: vital implementation details.
+- `@see` / `@sa`: related symbols for context linkage.
+- `@deprecated`: replacement API link.
+
+Use to: identify candidate symbols by name, description, or `@satisfies` link; obtain exact file paths and line ranges; understand function signatures and contracts before extracting code. Cross-reference with WORKFLOW.md call-traces to narrow scope.
+
+### 3. Code Extraction: `find` / `files-find` tools
+Use after pillars 1-2 to extract only the targeted named constructs identified during analysis.
+- Prefer the `find` tool for project-wide named-symbol, declaration, and construct scans, and the `files-find` tool when target files are already known.
+- Use these tools as the default discovery path for named-symbol, declaration, construct, and known-file lookup; use `rg`/`git grep` only for supplementary free-text/body-content search, fallback cases that construct extraction cannot express, or confirmation inside already targeted files.
+- Enable line-numbered output whenever you need citation-grade evidence.
+- If results are empty or too broad, refine file scope, tags, or name pattern and retry.
+- Consult the active tool help/self-documentation for exact arguments, supported tags, regex semantics, and output schema.
+
+
+### 4. Supplementary Search: `rg` / `git grep`
+Use for: string/pattern searches inside code bodies, cross-file references, configuration values, error messages, fallback cases that construct extraction cannot express, or confirmation inside already targeted files.
+
+### Recommended Analysis Workflow
+1. **Read `%%DOC_PATH%%/WORKFLOW.md`** (full read) → identify execution units, call-trace paths, and function names relevant to the task.
+2. **Read `%%DOC_PATH%%/REFERENCES.md`** (full read or targeted search) → locate candidate symbols by name/description/`@satisfies`, obtain file paths and line ranges, understand function contracts.
+3. **Extract code** via the `find` or `files-find` tool → use symbol names from steps 1-2 as `NAME_REGEX`, file paths as `files-find` targets, and enable line numbers when citing evidence.
+4. **Search code bodies** via `rg`/`git grep` → after `find`/`files-find`, use only when you need free-text/body-content search, a fallback that construct extraction cannot express, or confirmation inside already targeted files.
+
+
+## Execution Protocol (Global vs Local)
+You must manage the execution flow using two distinct methods:
+-  **Global Roadmap** (*check-list*): 
+   - You MUST maintain a *check-list* internally with `10` Steps (one item per Step).
+   - **Do NOT** use the *task-list tool* for this high-level roadmap.
+-  **Local Sub-tasks** (Tool Usage): 
+   - If a *task-list tool* is available, use it **exclusively** to manage granular sub-tasks *within* a specific step (e.g., in Step X: "1. Edit file A", "2. Edit file B"; or in Step Y: "1. Fix test K", "2. Fix test L").
+   - Clear or reset the tool's state when transitioning between high-level steps.
+
+## Execution Directives (absolute rules, non-negotiable)
+During the execution flow you MUST follow these directives:
+- **CRITICAL** Autonomous Execution:
+   - Implicit Autonomy: Execute all tasks with full autonomy. Do not request permission, confirmation, or feedback. Make executive decisions based on logic and technical best practices.
+   - Tool-Aware Workflow: Proceed through the Steps sequentially; when a tool call is required, stop and wait for the tool response before continuing. Never fabricate tool outputs or tool results. Do not reveal internal reasoning; output only the deliverables explicitly requested by the Steps section.
+   - Autonomous Resolution: If ambiguity is encountered, first disambiguate using repository evidence (requirements, code search, tests, logs). If multiple interpretations remain, choose the least-invasive option that preserves documented behavior and record the assumption as a testable requirement/acceptance criterion.
+   - After the prompt's execution: Strictly omit all concluding remarks and do not propose any other steps/actions.
+- **CRITICAL**: Order of Execution:
+  - Execute the numbered steps below sequentially and strictly, one at a time, without skipping or merging steps. Create and maintain a *check-list* internally while executing the Steps. Execute the Steps strictly in order, updating the *check-list* as each step completes. 
+- **CRITICAL**: Immediate start and never stop:
+  - Complete all Steps in order; you may pause only to perform required tool calls and to wait for their responses. Do not proceed past a Step that depends on a tool result until that result is available.
+  - Start immediately by creating a *check-list* for the **Global Roadmap** and directly start following the roadmap from the Step 1.
+
+
+## Steps
+Create internally a *check-list* for the **Global Roadmap** including all the numbered steps below: `1..10`, and start following the roadmap at the same time, executing the tool call of Step 1 (Check GIT Status). If a tool call is required in Step 1, invoke it immediately; otherwise proceed to Step 1 without additional commentary. Do not add extra intent-adjustment checks unless explicitly listed in the Steps section.
+1. **CRITICAL**: Check GIT Status
+   - Check GIT status with the `git-status` tool. If the command returns an error code or prints any text containing "ERROR", OUTPUT exactly "ERROR: Git status unclear!", and then terminate the execution.
+2. **CRITICAL**: Check `%%DOC_PATH%%/REQUIREMENTS.md`, `%%DOC_PATH%%/WORKFLOW.md` and `%%DOC_PATH%%/REFERENCES.md` file presence
+   - Check required docs presence with the `docs-check` tool. If the command returns an error code or prints any text containing "ERROR", OUTPUT exactly "ERROR: Required docs check failed!", and then terminate the execution.
+3. **CRITICAL**: Worktree Generation & Isolation
+   - Derive <BASE_PATH> with the `base-path` tool, derive <GIT_PATH> with the `git-path` tool, and generate <WORKTREE_NAME> with the `worktree-name` tool using simple sequential tool execution without shell composition.
+   - Create the dedicated isolated worktree with the `worktree-create` tool, then execute `cd <GIT_PATH>/../<WORKTREE_NAME>` before proceeding to the next step.
+   - If the command returns an error code or prints any text containing "ERROR", OUTPUT exactly "ERROR: Worktree generation failed!", and then terminate the execution.
+
+4. Read requirements, generate **Design Delta** and implement the **Implementation Delta** to fix the defect
+   - Using [User Request](#users-request) as a unified semantic framework, extract all directly and tangentially related information from `%%DOC_PATH%%/REQUIREMENTS.md`, `%%DOC_PATH%%/WORKFLOW.md` and `%%DOC_PATH%%/REFERENCES.md`, prioritizing high recall to capture every borderline connection across both sources, to identify the most likely related files and functions based on explicit evidence, and treat any uncertain links as candidates without claiming completeness, then analyze the involved source code from %%SRC_PATHS%% and GENERATE a detailed **Implementation Delta** documenting the exact modifications to the source code that fix the bug/defect described by the [User Request](#users-request). The **Implementation Delta** MUST be implementation-only and patch-oriented: for each file, list exact edits (functions/classes touched), include only changed snippets, and map each change to the requirement ID(s) it satisfies (no narrative summary)
+      - **ENFORCEMENT**: The definition of "valid code" strictly includes its documentation. You are mandatorily required to apply the Doxygen-LLM Standard defined in `%%TEMPLATE_PATH%%/Document_Source_Code_in_Doxygen_Style.md` to every single code component. Any code block generated without this specific documentation format is considered a compilation error and must be rejected/regenerated.
+      - Read %%GUIDELINES_FILES%% files and apply those **guidelines**; ensure the proposed code changes conform to those **guidelines**, and adjust the **Implementation Delta** if needed. Do not apply unrelated **guidelines**.
+   - Locate existing unit tests in %%TEST_PATH%% that map to touched modules and requirement IDs; when relevant suites exist, add one targeted failing reproducer unit test for the defect before implementing source fixes. Define in the **Implementation Delta** which suites will run during verification using language-specific test-suite priority policy, and treat verification tests as N/A when no relevant unit tests exist.
+      - **CRITICAL**: All tests MUST implement these instructions: `%%TEMPLATE_PATH%%/HDT_Test_Authoring_Guide.md`.
+      - Read %%GUIDELINES_FILES%% files and apply those **guidelines**; ensure the proposed code changes conform to those **guidelines**, and adjust the **Implementation Delta** if needed. Do not apply unrelated **guidelines**.
+   - A change is allowed ONLY if it corrects behavior that is: (a) explicitly required by `%%DOC_PATH%%/REQUIREMENTS.md` (cite requirement ID/section) OR (b) a defect with concrete evidence (crash, security flaw, data corruption, failure evidence, or incorrect output that contradicts a specific documented behavior). If the request implies new requirements or changing documented behavior, recommend `/req-new` or `/req-change`; before terminating, OUTPUT a Markdown table with exactly three columns in this order: `Requirement ID`, `Conflicting Excerpt`, `Conflict Reason + Interrupted Implementation Intent`; each row MUST map one conflicting requirement to the implementation-contrast rationale and intended interrupted modification; then OUTPUT exactly "ERROR: Defect fix failed due to incompatible requirements!", and then delete the isolated worktree and branch with the `worktree-delete` tool, and then terminate the execution.
+   - Preferred execution order for Step 4 when relevant suites exist: analyze and identify defect -> create one failing reproducer unit test -> design and implement source fix -> verify reproducer and full selected suites.
+   - IMPLEMENT the **Implementation Delta** in the source code (creating new files/directories if necessary). You may make minimal mechanical adjustments needed to fit the actual codebase (file paths, symbol names), but you MUST NOT add new features or scope beyond the **Implementation Delta**.
+5. Generate **Verification Delta** by verifying static-analysis results and implementing needed bug fixes
+   - Read `%%DOC_PATH%%/REQUIREMENTS.md` and cross-reference with the source code from %%SRC_PATHS%%, %%TEST_PATH%% to check ALL requirements, but use progressive disclosure: provide full evidence only for `FAIL` items and a compact pointer-only index for `OK` items. For each requirement, prefer the `find` and `files-find` tools to locate named symbols, declarations, constructs, and already-known files used as evidence. Use `rg` / `git grep` only for supplementary free-text/body-content searches, fallback cases that construct extraction cannot express, or confirmation inside already targeted files. Read only the identified files to verify compliance and do not assume compliance without locating the specific code implementation.
+      - For each requirement, report `OK` if satisfied or `FAIL` if not.
+      - Do not mark a requirement as `OK` without code evidence; for `OK` items provide only a compact pointer (file path + symbol + line range). For each requirement, provide a concise evidence pointer (file path + symbol + line range) excerpts only for `FAIL` requirements or when requirement is architectural, structural, or negative (e.g., "MUST NOT ..."). For such high-level requirements, cite the specific file paths or directory structures that prove compliance. Line ranges MUST be obtained from tooling output (e.g., `nl -ba` / `sed -n`) and MUST NOT be estimated. If evidence is missing, you MUST report `FAIL`. Do not assume implicit behavior.
+      - For every `FAIL`, provide evidence with a short explanation. Provide file path(s) and line numbers where possible.
+   - Perform a static analysis check by executing the `static-check` tool.
+      - Review the produced output and fix every reported issue in source code.
+      - Re-run the `static-check` tool until it produces no issues. If output is exactly `Error: no source files found in configured directories.`, treat it as successful no-source completion and continue without retries.
+   - If relevant unit tests already exist in the repository, run them during verification using language-specific test-suite priority policy: project-defined test command first, language-default unit-test command second; if a reproducer unit test was created in Step 4, require explicit evidence that it now passes; if no relevant tests exist, record test execution as N/A and continue.
+      - Verify that the implemented changes satisfy requirements evidence, static-analysis output, and unit-test outputs when tests are executed.
+      - For Step 4, include before/after evidence that links the observed defect to the applied source fix.
+      - Provide explicit concrete verification evidence that the defect is resolved, using requirement evidence and static-analysis output.
+      - If static analysis reports issues or executed unit tests fail, analyze whether they are caused by source defects or requirement-implementation mismatch. Assume requirement evidence is authoritative; when static analysis reports issues, fix source code unless requirements explicitly justify alternative handling.
+      - Fix the source code to resolve valid verification findings autonomously without asking for user intervention. Execute a strict fix loop: 1) analyze static-check output and unit-test failures (when tests ran), 2) determine root cause from evidence, 3) fix code, 4) re-run the `static-check` tool and re-run the selected unit-test suites when applicable. Repeat up to 2 times. If static analysis still reports issues after the second attempt, report the failure, OUTPUT exactly "ERROR: Defect fix failed due to inability to complete static analysis!", delete the isolated worktree and branch with the `worktree-delete` tool, and then terminate the execution.
+      - Limitations: Do not introduce new features or change the architecture logic during this fix phase; if a fix requires substantial refactoring or requirements changes, report the failure, then OUTPUT exactly "ERROR: Defect fix failed due to requirements incompatible with static-analysis constraints!", delete the isolated worktree and branch with the `worktree-delete` tool, and then terminate the execution.
+      - Do NOT create or modify tests outside the defect-focused scope; only the targeted reproducer test and strictly related assertions/fixtures may be changed when required by updated behavior.
+6. Update `%%DOC_PATH%%/WORKFLOW.md` via targeted edits using the canonical WORKFLOW.md contract (same terminology, same schema, same call-trace rules) and declaration file paths only, excluding line numbers, line ranges, and internal file-reference pointers.
+   - Update `%%DOC_PATH%%/WORKFLOW.md` as an LLM-first runtime model (English only) using a TARGETED EDIT policy.
+      - During generation/update, include declaration file paths only; MUST NOT include line numbers, line ranges, or internal file-reference pointers.
+      - Determine the change surface from repository evidence: run `git diff --name-only` and `git diff` to identify the modified files/symbols under %%SRC_PATHS%%.
+      - Modify ONLY the WORKFLOW.md sections impacted by those changes (execution unit index entries, execution unit subsections, and communication edges); preserve stable IDs and do not rewrite unrelated content.
+      - Ensure global consistency: if a changed internal symbol appears in any call-trace, update all affected call-trace nodes; if a unit/edge is added/removed, reflect it.
+   - Analyze only files under %%SRC_PATHS%% (everything else is out of scope) and identify ALL runtime execution units:
+      - OS processes (MUST include the main process).
+      - OS threads (per process), including their entry functions/methods.
+      - If no explicit thread creation is present, record "no explicit threads detected" for that process.
+   - For EACH execution unit, generate a complete internal call-trace tree starting from its entrypoint(s):
+      - Include ONLY internal functions/methods defined in repository source under %%SRC_PATHS%%.
+      - Do NOT include external boundaries (system/library/framework calls) as nodes; annotate them only as external boundaries where relevant.
+      - No maximum depth: expand until an internal leaf function or an external boundary is reached.
+   - Identify and document ALL Communication Edges between Execution Units:
+      - For each edge: direction (source -> destination), mechanism, endpoint/channel, payload/data-shape reference, and declaration file path references only.
+   - Preserve and maintain the canonical `WORKFLOW.md` schema:
+      - `## Execution Units Index`
+      - `## Execution Units`
+      - `## Communication Edges`
+   - Use stable execution unit IDs: `PROC:main`, `PROC:<name>` for processes; `THR:<proc_id>#<name>` for threads.
+   - Call-trace node format (MUST be consistent):
+      - `symbol_name(...)`: `<single-line role>` [`<defining filepath>`]
+         - `<optional: brief invariants/external boundaries>`
+         - `<child internal calls as nested bullet list, in call order>`
+7. Update `%%DOC_PATH%%/REFERENCES.md` references file
+   -  Create/update `%%DOC_PATH%%/REFERENCES.md` with the `references-generation` tool.
+8. **CRITICAL**: Stage & commit
+   - Show a summary of changes with `git diff` and `git diff --stat`.
+   - Stage changes explicitly (prefer targeted add; avoid `git add -A` if it may include unintended files): `git add <file...>` (ensure to include all modified source code & test and WORKFLOW.md only if it was modified/created).
+   - Ensure there is something to commit with: `git diff --cached --quiet && echo "Nothing to commit. Aborting."`. If command output contains "Aborting", OUTPUT exactly "No changes to commit.", and then delete the isolated worktree and branch with the `worktree-delete` tool, and then terminate the execution.
+   - Commit a structured commit message with: `git commit -m "fix(<COMPONENT>)<BREAKING>: <DESCRIPTION> [useReq]"`
+      - Set `<COMPONENT>` to the most specific component, module, or function affected. If multiple areas are touched, choose the primary one. If you cannot identify a unique component, use `core`.
+      - Set `<DESCRIPTION>` to a short, clear summary in **English language** of what changed, including (when applicable) updates to: requirements/specs, source code, tests. Use present tense, avoid vague wording, and keep it under ~80 characters if possible.
+      - Set `<BREAKING>` to `!` if a breaking change was implemented (a modification to an API, library, or system that breaks backward compatibility, causing dependent client applications or code to fail or behave incorrectly), set empty otherwise.
+      - Include main features added, requirements changes, or a bug-fix description adding a multi-line comment (maximum 10 lines).
+         - Do not include the 'Co-authored-by' trailer or any AI attribution. A GPG-signed commit is not required.
+   - Confirm the repo is clean with the `git-status` tool. If the command returns an error code or prints any text containing "ERROR", override the final line with EXACTLY "WARNING: Defect fix completed with unclean git repository!".
+9.  **CRITICAL**: Merge Conflict Management
+   - Return to the original repository directory (the sibling directory of the worktree).
+   - Ensure you are on the original branch used before worktree creation by deriving `<BASE_PATH>` with the `base-path` tool if needed and executing `cd <BASE_PATH>`.
+   - Merge the isolated branch into the original branch: `git merge <WORKTREE_NAME>`
+   - If the merge completes successfully, delete the isolated worktree and branch with the `worktree-delete` tool; if the command returns an error code or prints any text containing "ERROR", OUTPUT exactly "ERROR: Worktree cleanup verification failed!", and then terminate the execution.
+   - If the merge fails or results in conflicts, do NOT remove the worktree directory and override the final line with EXACTLY "WARNING: Defect fix completed with merge conflicting!".
+10. Present results
+   - PRINT, in the response, the results for a human reader using clear, easily understandable sentences and readable Markdown formatting that highlight key findings, file paths, and concise evidence. Use the fixed report schema: ## **Outcome**, ## **Requirement Delta**, ## **Design Delta**, ## **Implementation Delta**, ## **Verification Delta**, ## **Evidence**, ## **Assumptions**, ## **Next Workflow**. Final line MUST be exactly: STATUS: OK or STATUS: ERROR.
+
+<h2 id="users-request">User's Request</h2>
+%%ARGS%%