pi-usereq 0.4.0

package/src/resources/prompts/flowchart.md

@@ -0,0 +1,220 @@
+---
+description: "Write a FLOWCHART.md using the project's source code"
+argument-hint: "No arguments utilized by the prompt logic"
+usage: >
+  Select this prompt ONLY for docs-maintenance of %%DOC_PATH%%/FLOWCHART.md, when it is missing/outdated and you need to regenerate the primary runtime flowchart from evidence in %%SRC_PATHS%% and commit that doc change. Do NOT select if you will change requirements, workflow, references, source code, or tests; choose /req-change, /req-new, /req-fix, /req-refactor, /req-cover, /req-implement, /req-create, /req-recreate, /req-workflow, or /req-references as appropriate. Do NOT select for read-only analysis/audits (use /req-analyze or /req-check).
+---
+
+# Write a FLOWCHART.md using the project's source code
+
+## Purpose
+Maintain an LLM-oriented runtime flowchart (`%%DOC_PATH%%/FLOWCHART.md`) derived from repository evidence so downstream LLM Agents can reason about primary execution flow, decision branches, and grouped internal operations during SRS-driven design/implementation.
+
+## Scope
+In scope: static analysis of source under %%SRC_PATHS%% to generate/overwrite only `%%DOC_PATH%%/FLOWCHART.md` in English only, following the mandated Mermaid output contract, then commit that doc change. Out of scope: changes to requirements, workflow, references, source code, or tests.
+
+## 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 System Architect and Senior System Engineer** when analyzing source code; your primary goal is to trace the execution flow, decision points, and grouping boundaries across files and modules.
+- **Act as a Business Analyst** when cross-referencing code findings with `%%DOC_PATH%%/REQUIREMENTS.md` to ensure functional alignment.
+- **Act as a Technical Writer and Expert Mermaid.js Developer** when producing the final flowchart, ensuring structurally valid Mermaid syntax and zero-hallucination mapping.
+- **Act as a QA Auditor** when reporting facts, requiring concrete evidence as declaration file paths only (excluding line numbers and line ranges) for every finding.
+- **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 can read, write, or edit `%%DOC_PATH%%/FLOWCHART.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%%/FLOWCHART.md`.
+- **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**: 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
+- Write the `%%DOC_PATH%%/FLOWCHART.md` document in English.
+- Do not perform unrelated edits.
+- Use the repository's existing language-specific environment/toolchain to execute code and tests; do NOT create new environments unless explicitly requested by the user. For Python, prefer Astral `uv` (`uv run`, `uvx`) when available, then fall back to the repository's existing `.venv` (if present). For other ecosystems (e.g., Node.js, Rust, C/C++), 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%%/FLOWCHART.md`. Avoid in-place edits on any other path. Prefer read-only commands for analysis.
+
+## Canonical Terminology (MUST use these exact terms)
+- **Process**: an OS process execution unit (MUST include the main process).
+- **Thread**: an OS thread execution unit within a process.
+- **Execution Unit**: a Process or a Thread.
+- **Internal function**: a function/method defined in repository source under %%SRC_PATHS%%.
+- **External boundary**: any call/interaction whose target implementation is not defined under %%SRC_PATHS%% (libraries/frameworks/OS/network/DB/etc.).
+- **Communication Edge**: an explicit runtime interaction between two execution units.
+
+## FLOWCHART.md Output Contract
+- The generated `%%DOC_PATH%%/FLOWCHART.md` MUST be parser-stable and token-efficient: a single fenced Mermaid block, deterministic node labels, and zero narrative filler outside the fence.
+- The generated `%%DOC_PATH%%/FLOWCHART.md` MUST contain only a fenced `mermaid` block that starts with `graph TD`.
+- The flowchart MUST represent the primary execution flow and MUST exclude tangential or secondary flows.
+- The flowchart MUST group non-atomic internal functions into sequential alphabetical phases.
+- Each phase node MUST list atomic operations as sequentially numbered parameterless function prototypes.
+- Decision nodes MUST encode branching criteria in strict pseudo-code syntax.
+- Visible graph text MUST NOT expose internal working tags such as temporary decision or join identifiers.
+
+## 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 `7` 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..7`, 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**: 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.
+
+3. Static analysis: build the runtime model from %%SRC_PATHS%%
+   - Analyze only files under %%SRC_PATHS%%; treat all files outside %%SRC_PATHS%% as out of scope and never document them.
+   - Identify ALL execution units used at runtime:
+      - 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, derive entrypoint(s) and build a complete internal call-trace tree:
+      - Include ONLY internal functions as call-trace nodes (defined 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 ALL explicit communication edges between execution units and record for each edge:
+      - Direction (source -> destination), mechanism (IPC/thread communication), endpoint/channel (queue/topic/path/socket/etc.), and payload/data-shape references.
+
+4. Generate and overwrite `%%DOC_PATH%%/FLOWCHART.md` document with a Mermaid flowchart representing the primary execution flow
+   - Isolate the core program functionality and disregard secondary or tangential flows.
+   - Group non-atomic functions into logical phases with sequential alphabetical labels.
+   - Inside each phase, extract atomic operations, label them with sequential integers, and document them using strictly parameterless function prototypes.
+   - Deduce actual control flow, branching, and joins from the code analyzed in Step 3.
+   - **Granularity consistency rule (CRITICAL):** maintain the same abstraction level across sibling branches that originate from the same decision node. If one branch exposes internal sub-operations of a composite internal function, then every sibling branch at that same decision depth MUST expose the equivalent internal sub-operations needed for semantic comparison; conversely, if one branch remains collapsed as a composite phase, sibling branches MUST NOT mix in a lower-level expansion unless that lower-level expansion is required in all sibling branches.
+   - **Comparability rule (CRITICAL):** the flowchart MUST make branch-to-branch equivalence explicit. Do not represent one branch as a wrapper function and another branch as the wrapper’s internal steps when both branches implement the same logical stage. Expand or collapse branches so that a downstream LLM Agent can compare them without inferring hidden steps.
+   - **Mandatory-entry vs optional-effect rule (CRITICAL):** explicitly distinguish between:
+      - mandatory stage entry: the caller always invokes the helper or stage wrapper;
+      - optional stage effect: the invoked helper may internally return the input unchanged, bypass its principal work, or otherwise behave as pass-through.
+     A helper that is always called MUST NOT be rendered as an unconditional application phase when its internal logic can disable the actual effect.
+   - **Decision-hoisting rule (CRITICAL):** when the first semantically relevant branch is internal to a composite helper, the flowchart MUST extract that branch outside the helper and render it as an explicit decision diamond using the real code condition expressed in strict pseudo-code.
+   - **Optional-wrapper detection heuristic (CRITICAL):** the agent MUST actively inspect composite helpers and wrappers for internal optional-work branches, including patterns such as:
+      - `if <mode> is None`
+      - `if not <enabled_flag>`
+      - enum or selector values such as `disable`
+      - early returns such as `return stage_input`, `return input_rgb`, or `return image_rgb_float`
+      - diagnostic messages indicating `disabled` or `pass-through`
+   - **Enable-state wrapper rule (CRITICAL):** if a composite helper contains enable-state validation and can bypass its principal work, the flowchart MUST render that condition as an explicit decision node even when the helper call itself is always executed. Wrappers with enable-state validation plus pass-through MUST NOT remain collapsed into a single phase node when the hidden decision changes the semantic meaning of the flow.
+   - **No hidden-step ambiguity rule (CRITICAL):** do not allow a phase node to visually imply that an internal operation is skipped when that operation is actually executed inside a composite helper, or to imply unconditional work when that helper can internally bypass the work. If a composite helper contains operations that are shown explicitly in an alternative branch, or contains the first relevant bypass condition for that logical stage, either:
+      - expand the composite helper to expose those operations and the bypass decision in the same decision region, or
+      - collapse the alternative branch to the same semantic level,
+        choosing the representation that maximizes branch readability and preserves the primary execution flow without hiding branch semantics.
+   - **Optional-stage representation rule (CRITICAL):** for a helper with mandatory stage entry and optional stage effect, the flowchart MUST show both semantic outcomes:
+      - disabled or bypass branch: render an explicit pass-through path to the next step;
+      - enabled branch: render either the phase node that actually applies the effect or a coherent expansion of its internal sub-steps.
+   - **Wrapper-function rule (CRITICAL):** a composite internal function MAY appear as a single visible phase only if its internal operations are not separately exposed elsewhere in parallel or sibling branches of the same logical decision region and it does not hide a decision that changes whether the stage effect is applied. If those operations are exposed elsewhere, or if such a decision exists, the composite function MUST be expanded enough to remove ambiguity.
+   - **Join readability rule (CRITICAL):** place joins only after branches have been normalized to a comparable semantic granularity and after enabled and disabled branches have actually reconverged. A join MUST NOT merge branches where one path still hides decision-relevant internal operations that are shown in another path.
+   - **Skipped-work rule (CRITICAL):** represent intentionally skipped work explicitly only when the source code emits or enforces a real skip condition. Do not create an apparent skip merely by collapsing one branch more aggressively than another. Real pass-through branches MUST be rendered as explicit bypasses.
+   - **Lexical signal check (CRITICAL):** before finalizing the flowchart, cross-check `%%DOC_PATH%%/REQUIREMENTS.md` and `%%DOC_PATH%%/WORKFLOW.md` for signal terms such as `optional`, `disabled`, `pass-through`, `enable-state validation`, `when omitted`, and `disable`; when those terms correspond to an analyzed stage or helper, ensure the flowchart reflects the same optionality semantics with visible decision and bypass structure.
+   - **Normative category example (CRITICAL):** "A helper always invoked by the caller but internally bypassed by an enable/disable selector MUST be rendered as a decision region, not as an unconditional application phase."
+   - Before writing the file, perform a strict internal audit cross-referencing the generated flowchart, the runtime model from Step 3, the original source code, and the lexical signals found in `%%DOC_PATH%%/REQUIREMENTS.md` and `%%DOC_PATH%%/WORKFLOW.md`.
+   - The internal audit MUST explicitly verify:
+      - every decision node has sibling branches rendered at comparable semantic granularity;
+      - every optional stage with mandatory stage entry has a visible decision node;
+      - every real pass-through is represented as an explicit bypass;
+      - no branch appears to omit an operation that is actually executed inside a composite helper;
+      - no composite helper hides a decision that changes the stage effect;
+      - every visible skip corresponds to a real code-level skip or bypass condition;
+      - no join occurs before enabled and disabled branches reconverge;
+      - every join occurs only after branch normalization.
+   - Mermaid generation rules:
+      - Write the final output strictly enclosed within ` ```mermaid ` and ` ``` ` fences.
+      - Use a vertical layout (`graph TD`).
+      - Flowchart nodes MUST represent phases and MUST contain the phase letter followed by the numbered list of atomic operations.
+      - Decision blocks MUST contain the decision criteria written in strict pseudo-code syntax.
+      - Use arrows and diamond nodes for branching, and do not output internal working tags in the final visible graph.
+5. **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 only `%%DOC_PATH%%/FLOWCHART.md`).
+   - 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 "docs(<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: Flowchart request completed with unclean git repository!".
+6. **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: Flowchart request completed with merge conflicting!".
+7. 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/implement.md

@@ -0,0 +1,163 @@
+---
+description: "Implement source code from requirements (from scratch)"
+argument-hint: "No arguments utilized by the prompt logic"
+usage: >
+  Select this prompt when %%DOC_PATH%%/REQUIREMENTS.md is already authoritative and stable, but the codebase under %%SRC_PATHS%% is missing large parts of the required functionality (greenfield or major gaps) and you must build an end-to-end implementation (including creating new modules/files and tests under %%TEST_PATH%%) WITHOUT changing requirements. Do NOT select if only a small/known set of requirement IDs is uncovered in an otherwise working codebase (use /req-cover), if you need to modify or add requirements (use /req-change or /req-new), or if the task is a narrow defect fix or refactor (use /req-fix or /req-refactor). Do NOT select for auditing/triage (use /req-check or /req-analyze).
+---
+
+# Implement source code from requirements from scratch
+
+## Purpose
+Produce a working implementation from the normative SRS (`%%DOC_PATH%%/REQUIREMENTS.md`) by building missing functionality end-to-end (including “from scratch” where needed), so the codebase becomes fully compliant with the documented requirement IDs without changing those requirements.
+
+## Scope
+In scope: read `%%DOC_PATH%%/REQUIREMENTS.md`, implement/introduce source under %%SRC_PATHS%% (including new modules/files), add tests under %%TEST_PATH%%, verify via the `static-check` tool 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 requirements or introducing features not present in the SRS (use `/req-change` or `/req-new` to evolve requirements first).
+
+
+## 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.
+
+
+## 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**: 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.
+
+3. Read requirements, generate **Design Delta** and implement the **Implementation Delta** to cover all requirements
+   - Read `%%DOC_PATH%%/REQUIREMENTS.md` and GENERATE a detailed **Implementation Delta** that covers all explicitly specified requirements, and explicitly list any requirement that cannot be implemented due to missing information or repository constraints. The **Implementation Delta** MUST be implementation-only: for each file, list exact developments (functions/classes created), and map each implementation 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 implemented requirement IDs; include in the **Implementation Delta** the language-specific priority order for verification runs, and record test execution 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) from scratch.
+4. Generate **Verification Delta** by verifying static-analysis results and implementing needed bug fixes
+   - Read ALL requirements from `%%DOC_PATH%%/REQUIREMENTS.md`, analyze them one by one, and cross-reference them with the source code to check requirements. 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: Implement request 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: Implement request 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.
+5. Static analysis: build the runtime model from %%SRC_PATHS%%
+   - Analyze only files under %%SRC_PATHS%%; treat all files outside %%SRC_PATHS%% as out of scope and never document them.
+   - Identify ALL execution units used at runtime:
+      - 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, derive entrypoint(s) and build a complete internal call-trace tree:
+      - Include ONLY internal functions as call-trace nodes (defined 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 ALL explicit communication edges between execution units and record for each edge:
+      - Direction (source -> destination), mechanism (IPC/thread communication), endpoint/channel (queue/topic/path/socket/etc.), and payload/data-shape references.
+6. Generate and overwrite `%%DOC_PATH%%/WORKFLOW.md` document using declaration file paths only, excluding line numbers, line ranges, and internal file-reference pointers
+   - Read any existing `%%DOC_PATH%%/WORKFLOW.md` to preserve stable IDs and minimize unnecessary churn, then update it to strictly conform to the Output Contract above.
+   - Generate %%DOC_PATH%%/WORKFLOW.md in English only using deterministic, machine-interpretable Markdown with the required schema and stable field order.
+      - During generation/update, include declaration file paths only; MUST NOT include line numbers, line ranges, or internal file-reference pointers.
+      - `## Execution Units Index` (stable IDs)
+         - Use stable IDs: `PROC:main`, `PROC:<name>` for processes; `THR:<proc_id>#<name>` for threads.
+         - For each execution unit: ID, type (process/thread), parent process (for threads), role, entrypoint symbol(s), and defining file(s).
+      - `## Execution Units`
+         - One subsection per execution unit ID including:
+           - Entrypoint(s)
+           - Lifecycle/trigger (how it starts, stops, and loops/blocks)
+           - Internal Call-Trace Tree (internal functions only; no maximum depth)
+           - External Boundaries (file I/O, network, DB, external APIs, OS interaction)
+      - `## Communication Edges`
+         - List ALL `Communication Edge` items with direction + mechanism + endpoint/channel + payload/data-shape reference + declaration file path references only.
+   - 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 "implement(<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: Implement request 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: Implement request 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.