pi-usereq 0.62.0 → 0.64.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.62.0)
+# PI-useReq/pi-usereq (0.64.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.62.0",
+  "version": "0.64.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/scripts/pi-prompts-update.sh

@@ -0,0 +1,240 @@
+#!/usr/bin/env bash
+# @file scripts/pi-prompts-update.sh
+# @brief Updates bundled PI-useReq prompt resources from the latest PI-Prompts release.
+# @details Clones the PI-Prompts repository (master branch), resolves the newest
+#     release ref, and performs a full one-way synchronization of the upstream
+#     `src/instructions`, `src/prompts`, and `src/templates` directories into the
+#     local `src/resources/instructions`, `src/resources/prompts`, and
+#     `src/resources/templates` targets. Full synchronization overwrites every
+#     present file and removes every file that no longer exists upstream by
+#     replacing each target directory with a freshly staged copy. Upstream file
+#     access and modification timestamps are preserved through `cp -p`.
+#     Runtime is dominated by one git clone plus one ref checkout and per-file
+#     copies. Side effects include temporary-directory creation, git
+#     subprocesses, one optional GitHub Releases API request, and replacement of
+#     the three target resource directories. No other repository content is
+#     modified.
+# @satisfies DES-022, REQ-379, REQ-380, REQ-381, REQ-382, REQ-383, REQ-384
+
+set -euo pipefail
+
+PROMPTS_REPO_URL_PRIMARY="https://github.com/Ogekuri/PI-Prompts.git"
+PROMPTS_REPO_URL_FALLBACK="https://github.com/Ogekuri/PI-Prompts"
+PROMPTS_RELEASE_API_URL="https://api.github.com/repos/Ogekuri/PI-Prompts/releases/latest"
+PROMPTS_BRANCH="master"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+TARGET_ROOT="${REPO_ROOT}/src/resources"
+
+## @brief Stores the ordered `upstream-relative:target-relative` synchronization pairs.
+## @details Each entry maps one upstream repository directory to one bundled
+##     `src/resources` target directory synchronized in declaration order. The
+##     constant is immutable at runtime and costs O(1) per element access.
+SYNC_SPECS=(
+  "src/instructions:src/resources/instructions"
+  "src/prompts:src/resources/prompts"
+  "src/templates:src/resources/templates"
+)
+
+WORK_DIR=""
+STAGING_DIR=""
+
+## @brief Writes one progress message to stdout.
+## @details Emits the supplied message fragments joined by single spaces followed
+##     by one newline. Runtime is O(n) in message length. Side effect: writes to
+##     `stdout`.
+## @param[in] ... {string} Progress message fragments.
+## @return {void} No return value.
+log() {
+  printf '%s\n' "$*"
+}
+
+## @brief Aborts the updater with one deterministic diagnostic.
+## @details Writes the supplied diagnostic prefixed with `ERROR: ` to `stderr`
+##     and terminates the process with exit code `1`. Runtime is O(n) in message
+##     length. Side effects include `stderr` output and process exit; the `EXIT`
+##     trap still removes updater temporary directories.
+## @param[in] message {string} Failure diagnostic.
+## @return {never} Never returns.
+fail() {
+  printf 'ERROR: %s\n' "$*" >&2
+  exit 1
+}
+
+## @brief Removes updater temporary directories.
+## @details Deletes the cloned upstream working tree and any pending staging
+##     directory registered in `WORK_DIR` plus `STAGING_DIR`. Invoked through the
+##     `EXIT` trap on every exit path. Runtime is O(1) plus filesystem removal
+##     cost. Side effects include directory removal.
+## @return {void} No return value.
+cleanup() {
+  if [ -n "${STAGING_DIR}" ]; then
+    rm -rf "${STAGING_DIR}"
+  fi
+  if [ -n "${WORK_DIR}" ]; then
+    rm -rf "${WORK_DIR}"
+  fi
+}
+
+## @brief Verifies that one required external tool is available.
+## @details Probes the executable search path for the requested tool name and
+##     aborts through `fail(...)` when the probe fails. Runtime is O(1) plus one
+##     `PATH` lookup. No external state is mutated.
+## @param[in] tool {string} Executable name to probe.
+## @return {void} No return value.
+require_tool() {
+  command -v "$1" >/dev/null 2>&1 || fail "Required tool not found: $1"
+}
+
+## @brief Clones the upstream PI-Prompts master branch into one target directory.
+## @details Attempts a quiet, no-checkout clone of `${PROMPTS_BRANCH}` from
+##     `${PROMPTS_REPO_URL_PRIMARY}`, removes the partial destination on failure,
+##     and retries once with `${PROMPTS_REPO_URL_FALLBACK}`. Prints the resolved
+##     upstream URL on `stdout` so callers can capture provenance. Runtime is
+##     dominated by git subprocess execution. Side effects include
+##     destination-directory creation and removal.
+## @param[in] destination {string} Target directory path for the clone.
+## @return {string} Resolved upstream repository URL on stdout.
+## @throws Exits through `fail(...)` when both upstream URLs are unreachable.
+clone_upstream() {
+  local destination="$1"
+  rm -rf "${destination}"
+  if git clone --quiet --no-checkout --branch "${PROMPTS_BRANCH}" "${PROMPTS_REPO_URL_PRIMARY}" "${destination}" 2>/dev/null; then
+    printf '%s\n' "${PROMPTS_REPO_URL_PRIMARY}"
+    return 0
+  fi
+  log "Primary clone failed, retrying with the fallback repository URL ..."
+  rm -rf "${destination}"
+  if git clone --quiet --no-checkout --branch "${PROMPTS_BRANCH}" "${PROMPTS_REPO_URL_FALLBACK}" "${destination}" 2>/dev/null; then
+    printf '%s\n' "${PROMPTS_REPO_URL_FALLBACK}"
+    return 0
+  fi
+  fail "Unable to clone PI-Prompts from ${PROMPTS_REPO_URL_PRIMARY} or ${PROMPTS_REPO_URL_FALLBACK}."
+}
+
+## @brief Resolves the upstream synchronization ref for the cloned repository.
+## @details Prefers the newest tag reported by the GitHub Releases API when
+##     `curl` is available and that tag exists in the local clone; otherwise
+##     selects the newest version-sorted tag reachable from `${PROMPTS_BRANCH}`;
+##     otherwise falls back to the `${PROMPTS_BRANCH}` head. Prints the resolved
+##     ref name on `stdout`. Runtime is dominated by one optional HTTPS request
+##     plus git ref enumeration. No external state is mutated.
+## @param[in] repository {string} Cloned upstream repository path.
+## @return {string} Resolved `refs/tags/<tag>` or `refs/heads/master` ref on stdout.
+resolve_release_ref() {
+  local repository="$1"
+  local release_tag=""
+
+  if command -v curl >/dev/null 2>&1; then
+    release_tag="$(curl -fsSL --max-time 20 "${PROMPTS_RELEASE_API_URL}" 2>/dev/null \
+      | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
+      | head -n 1 || true)"
+  fi
+
+  if [ -n "${release_tag}" ] \
+    && git -C "${repository}" rev-parse --verify --quiet "refs/tags/${release_tag}" >/dev/null 2>&1; then
+    printf 'refs/tags/%s\n' "${release_tag}"
+    return 0
+  fi
+
+  release_tag="$(git -C "${repository}" tag --sort=-v:refname --merged "${PROMPTS_BRANCH}" 2>/dev/null | head -n 1 || true)"
+  if [ -n "${release_tag}" ]; then
+    printf 'refs/tags/%s\n' "${release_tag}"
+    return 0
+  fi
+
+  log "No PI-Prompts release resolvable, falling back to the ${PROMPTS_BRANCH} head."
+  printf 'refs/heads/%s\n' "${PROMPTS_BRANCH}"
+}
+
+## @brief Fully synchronizes one upstream directory into one target directory.
+## @details Stages every upstream file below `source_dir` into a fresh sibling
+##     staging directory using timestamp-preserving copies, then replaces
+##     `target_dir` with the staged tree through a backup-and-swap sequence so
+##     files removed upstream disappear and existing files are overwritten.
+##     Runtime is dominated by per-file copy cost. Side effects include staging
+##     plus backup directory creation and removal, target-directory replacement,
+##     and one progress line on `stdout`.
+## @param[in] source_dir {string} Absolute upstream source directory path.
+## @param[in] target_dir {string} Absolute bundled target directory path.
+## @return {void} No return value.
+## @throws Exits through `fail(...)` when `source_dir` is not a directory.
+sync_directory() {
+  local source_dir="$1"
+  local target_dir="$2"
+
+  [ -d "${source_dir}" ] || fail "Upstream directory not found: ${source_dir}"
+
+  STAGING_DIR="${target_dir}.staging.$$"
+  rm -rf "${STAGING_DIR}"
+  mkdir -p "${STAGING_DIR}"
+
+  local relative_path destination parent_dir copied=0
+  while IFS= read -r -d '' relative_path; do
+    relative_path="${relative_path#./}"
+    [ -n "${relative_path}" ] || continue
+    destination="${STAGING_DIR}/${relative_path}"
+    parent_dir="$(dirname "${destination}")"
+    mkdir -p "${parent_dir}"
+    cp -p "${source_dir}/${relative_path}" "${destination}"
+    copied=$((copied + 1))
+  done < <(cd "${source_dir}" && find . -type f -print0)
+
+  local backup_dir="${target_dir}.backup.$$"
+  rm -rf "${backup_dir}"
+  if [ -d "${target_dir}" ]; then
+    mv "${target_dir}" "${backup_dir}"
+  fi
+  mv "${STAGING_DIR}" "${target_dir}"
+  STAGING_DIR=""
+  rm -rf "${backup_dir}"
+
+  log "Synchronized ${copied} file(s) into ${target_dir#"${REPO_ROOT}"/}"
+}
+
+## @brief Executes one full bundled-resource update run.
+## @details Validates required tools, allocates the temporary upstream working
+##     tree, clones the PI-Prompts master branch, resolves and checks out the
+##     newest release ref, then synchronizes every ordered pair declared in
+##     `SYNC_SPECS`. Runtime is dominated by the upstream clone plus the three
+##     directory synchronizations. Side effects include temporary-directory
+##     creation and removal, git subprocesses, one optional GitHub Releases API
+##     request, and replacement of the three bundled target directories.
+## @return {void} No return value.
+## @throws Exits through `fail(...)` when any required tool, clone, checkout, or
+##     synchronization step fails.
+main() {
+  require_tool git
+  require_tool find
+  require_tool mkdir
+  require_tool cp
+
+  mkdir -p "${TARGET_ROOT}"
+
+  WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/pi-prompts-update.XXXXXX")" \
+    || fail "Unable to create the temporary working directory."
+  local repository="${WORK_DIR}/PI-Prompts"
+
+  local upstream_url
+  upstream_url="$(clone_upstream "${repository}")"
+  log "Upstream repository: ${upstream_url}"
+
+  local release_ref
+  release_ref="$(resolve_release_ref "${repository}")"
+  git -C "${repository}" checkout --quiet --detach "${release_ref}" \
+    || fail "Unable to check out ${release_ref}."
+  log "Synchronizing from ref: ${release_ref}"
+
+  local spec source_rel target_rel
+  for spec in "${SYNC_SPECS[@]}"; do
+    source_rel="${spec%%:*}"
+    target_rel="${spec#*:}"
+    sync_directory "${repository}/${source_rel}" "${REPO_ROOT}/${target_rel}"
+  done
+
+  log "Bundled prompt resources updated."
+}
+
+trap cleanup EXIT
+main "$@"

package/src/core/prompts.ts

@@ -81,16 +81,28 @@ const PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH = `${PI_DEV_DOCS_PROMPT_PATH}/coding-
  * @details Prompt guidance cites this directory when requiring read-only validation against the pi client implementation. Lookup complexity is O(1).
  */
 const PI_DEV_SOURCE_PROMPT_PATH = "pi.dev-src/pi-mono";
+/**
+ * @brief Stores the repository-relative root directory of the pi CLI client sources.
+ * @details Prompt guidance cites this directory when declaring the permanently read-only pi CLI client reference and source-of-truth mandates for new implementations, source-code modifications, and bug fixes. Lookup complexity is O(1).
+ */
+const PI_DEV_SOURCE_ROOT_PROMPT_PATH = "pi.dev-src";
 /**
  * @brief Defines the injected pi.dev governance guidance block.
- * @details The block requires read-only handling for documentation and pi client sources, coding-agent-document review, coding-agent-document compliance, optional manifest-referenced document handling, and pi client source validation for ambiguous or bug-fix interface work. Construction happens once at module load. Access complexity is O(1).
- * @satisfies REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
+ * @details The block requires read-only handling for documentation and pi client sources, mandatory read-only pi CLI client reference usage plus source-of-truth handling for new implementations, source-code modifications, and bug fixes, coding-agent-document review, coding-agent-document compliance, optional manifest-referenced document handling, and pi client source validation for ambiguous or bug-fix interface work. Construction happens once at module load. Access complexity is O(1).
+ * @satisfies CTN-017, CTN-023, CTN-024, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275, REQ-378
  */
 const PI_DEV_CONFORMANCE_BLOCK = [
   "- Treat every path under `docs/` as read-only; do NOT modify "
     + "any documentation file, including those under `docs/pi.dev/`.",
   "- Treat every path under `pi.dev-src/` as read-only; do NOT modify "
     + `\`${PI_DEV_SOURCE_PROMPT_PATH}\` or any other pi client source.`,
+  `- Every file under \`${PI_DEV_SOURCE_ROOT_PROMPT_PATH}/\` is a pi CLI client `
+    + "source: it MAY and MUST be used as read-only reference material "
+    + "during analysis, implementation, verification, and bug fixing.",
+  `- Treat \`${PI_DEV_SOURCE_ROOT_PROMPT_PATH}/\` as the source-of-truth (SoT) `
+    + "for new implementations, source-code modifications, and bug fixes; "
+    + "derive pi-client-facing behavior from it without modifying it "
+    + "in any way.",
   "- If the task creates or modifies software that interfaces with the "
     + `pi.dev CLI, review \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` `
     + "before analysis, implementation, verification, or bug fixing.",
@@ -110,11 +122,11 @@ const PI_DEV_CONFORMANCE_BLOCK = [
 
 /**
  * @brief Builds the conditional pi.dev governance block for one rendered prompt.
- * @details Emits the coding-agent-document-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the `docs/pi.dev/coding-agent-docs/` directory; the manifest file is optional and its absence does not suppress the block. Time complexity O(1). No filesystem writes.
+ * @details Emits the coding-agent-document-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the `docs/pi.dev/coding-agent-docs/` directory; the manifest file is optional and its absence does not suppress the block. The emitted rules declare `pi.dev-src/` the permanently read-only pi CLI client reference and source-of-truth for new implementations, source-code modifications, and bug fixes. Time complexity O(1). No filesystem writes.
  * @param[in] promptName {string} Bundled prompt identifier.
  * @param[in] projectBase {string} Absolute project root used for coding-agent-docs directory existence checks.
  * @return {string} Markdown bullet block or the empty string when injection is not applicable.
- * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
+ * @satisfies CTN-023, CTN-024, REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275, REQ-378
  */
 function buildPiDevConformanceBlock(promptName: string, projectBase: string): string {
   if (!PI_DEV_AWARE_PROMPT_NAMES.has(promptName)) {
@@ -134,7 +146,7 @@ function buildPiDevConformanceBlock(promptName: string, projectBase: string): st
  * @param[in] promptName {string} Bundled prompt identifier.
  * @param[in] projectBase {string} Absolute project root used for coding-agent-docs directory existence checks.
  * @return {string} Prompt markdown with zero or one injected conformance block.
- * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
+ * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275, REQ-378
  */
 function injectPiDevConformanceBlock(text: string, promptName: string, projectBase: string): string {
   const block = buildPiDevConformanceBlock(promptName, projectBase);
@@ -326,7 +338,7 @@ function renderBundledCommitInstruction(
  * @param[in] config {UseReqConfig} Effective project configuration used for path substitutions.
  * @param[in] executionPlan {PromptCommandExecutionPlan | undefined} Optional prompt-command execution plan used for injected runtime guidance.
  * @return {string} Fully rendered prompt markdown ready for `pi.sendUserMessage(...)`.
- * @satisfies REQ-002, REQ-003, REQ-032, REQ-033, REQ-034, REQ-108, REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209, REQ-211, REQ-213, REQ-214, REQ-273, REQ-274, REQ-275, REQ-329, REQ-330, REQ-331, REQ-332
+ * @satisfies REQ-002, REQ-003, REQ-032, REQ-033, REQ-034, REQ-108, REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209, REQ-211, REQ-213, REQ-214, REQ-273, REQ-274, REQ-275, REQ-378, REQ-329, REQ-330, REQ-331, REQ-332
  */
 export function renderPrompt(
   promptName: string,

package/src/resources/prompts/analyze.md

@@ -102,7 +102,7 @@ Use for: string/pattern searches inside code bodies, cross-file references, conf
 ## 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 `2` Steps (one item per Step).
+   - 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").
@@ -123,13 +123,22 @@ During the execution flow you MUST follow these directives:
 
 
 ## Steps
-Create internally a *check-list* for the **Global Roadmap** including all the numbered steps below: `1..2`, and start following the roadmap at the same time, executing the instructions of Step 1. 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.
+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, executing the instructions of Step 1. 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. Analyze the [User Request](#users-request)
    - 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%% to answer the [User Request](#users-request), ensuring compliance with %%GUIDELINES_FILES%% documents if present.
    - Do NOT create or modify tests in this workflow. If you cite tests as evidence, treat them as read-only artifacts.
    - Read %%GUIDELINES_FILES%% files and ensure any suggested follow-up changes would conform to those **guidelines**. Do not check unrelated **guidelines**.
-2. Present results
+2. Generate the follow-up prompt text from the analysis outcome
+   - Using the Step 1 analysis outcome, classify the result against `%%DOC_PATH%%/REQUIREMENTS.md` into exactly one branch:
+      - IF the analysis identified an implementation behavior that conflicts with requirements (the source code must change while `%%DOC_PATH%%/REQUIREMENTS.md` stays unchanged), GENERATE the exact prompt text to pass to the LLM Agent with the `/req-fix` command, including the defect summary, the affected requirement IDs, and concrete evidence (file paths with line numbers).
+      - ELSE IF the analysis identified changes needed to BOTH the source code and `%%DOC_PATH%%/REQUIREMENTS.md`, GENERATE the exact prompt text to pass to the LLM Agent with the `/req-change` command, including the requested change description, the affected requirement IDs, and concrete evidence (file paths with line numbers).
+      - ELSE IF the analysis identified source-code modifications with the intent of improving or adjusting the sources (internals, structure, maintainability, or performance) while `%%DOC_PATH%%/REQUIREMENTS.md` stays unchanged and NO implementation behavior conflicting with requirements was identified, GENERATE the exact prompt text to pass to the LLM Agent with the `/req-refactor` command, including the improvement objective, the affected source paths/symbols, the requirement IDs constraining the behavior to preserve, and concrete evidence (file paths with line numbers).
+      - ELSE (no source-code or requirements modifications are required), do NOT generate any follow-up prompt text.
+   - Each generated follow-up prompt text (`/req-fix`, `/req-change`, or `/req-refactor`) MUST be printed ONLY when the analysis identified its corresponding trigger in the classification above, and MUST NOT be printed in any other case; when generated, carry it into Step 3 for printing under the `## **Next Workflow**` report section.
+   - Do NOT execute the generated follow-up prompt and do NOT apply any fix or repository modification in this workflow; this workflow remains read-only.
+3. Present results
    - PRINT, in the response, the final analysis report 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.
+   - Include the Step 2 generated follow-up prompt text under `## **Next Workflow**` ONLY when Step 2 generated it; omit the follow-up prompt text entirely in all other cases.
 
 <h2 id="users-request">User's Request</h2>
 %%ARGS%%

package/src/resources/prompts/readme.md

@@ -39,7 +39,7 @@ In scope: static analysis of user-visible behavior from %%SRC_PATHS%% and relate
 - Write root `README.md` in English.
 - Do not perform unrelated edits.
 - Analyze user-visible implementation changes, including new features, CLI parameters/options, GUI interactions, distributed APIs, and configuration-file schema updates when present.
-- Validate whether the current root `README.md` is aligned with implementation evidence; identify exact sections to update first, then update only missing, outdated, or incorrect user-facing content in those sections.
+- Validate the current root `README.md` exhaustively against implementation evidence: enumerate every section, validate each sentence, and record a per-sentence conformance outcome before editing; then update only missing, outdated, or incorrect user-facing content.
 - Parse [User Request](#users-request) (`%%ARGS%%`) as explicit additional-edit directives, using the same anchor-based reference model used by `write.md`, and execute those directives in the same scoped README update pass.
 - Keep non-analysis documentary sections unchanged, including document headers, versioning metadata, context/scope descriptions, personal motivations, related projects, and high-level conceptual or graphical descriptions that do not alter interface usage.
 - Preserve existing README structure and formatting patterns (section order, heading hierarchy, bullet/list style, table style) whenever possible.
@@ -136,9 +136,12 @@ Create internally a *check-list* for the **Global Roadmap** including all the nu
    - Use repository evidence only; for each finding, collect file paths and line ranges.
    - Derive a compact "README coverage list" of user-visible behavior that MUST appear in root `README.md`.
 2. Validate and update root `README.md`
-   - Read the current root `README.md` and compare it with the README coverage list from Step 1.
-   - Identify and list the exact `README.md` sections impacted by the detected user-visible implementation changes and explicit additional edits from [User Request](#users-request) before editing.
+   - Read the current root `README.md` and enumerate ALL its sections and headings in document order to fix the complete validation surface.
+   - Validate `README.md` sentence by sentence, section by section, in document order: for every sentence, verify its content against repository implementation evidence and record exactly one outcome: `CONFORMING`, `OUTDATED`, or `UNSUPPORTED`.
+   - Classify non-analysis documentary sections (headers, versioning, motivations, related projects, high-level graphics) as `NOT-ANALYZED-BY-DESIGN` instead of sentence-level validation; never skip any other part or section.
+   - Identify and list the exact `README.md` sections impacted by the detected user-visible implementation changes, the recorded validation outcomes, and explicit additional edits from [User Request](#users-request) before editing.
    - Update only the identified sections so `README.md` reflects the current externally visible behavior and usage flows.
+   - Completeness gate: do NOT proceed to Step 3 until every enumerated section and every sentence has a recorded outcome and every `OUTDATED` or `UNSUPPORTED` sentence in analysis sections is corrected or removed.
    - Keep all non-analysis documentary sections unchanged (e.g., headers, versioning, context/scope narratives, motivations, related projects, high-level graphics/descriptions not tied to interface behavior).
    - Keep content focused on user interaction, setup, commands, interfaces, and observable outputs.
    - Do NOT add internal implementation details, internal architecture, private symbol names, or algorithm internals.