pi-usereq 0.64.0 → 0.65.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.64.0)
+# PI-useReq/pi-usereq (0.65.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.64.0",
+  "version": "0.65.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/scripts/pi-cli-update-src-docs.sh

@@ -0,0 +1,370 @@
+#!/usr/bin/env bash
+# @file scripts/pi-cli-update-src-docs.sh
+# @brief Updates read-only pi CLI reference sources and docs from the latest pi CLI release.
+# @details Clones the official pi CLI repository (https://github.com/earendil-works/pi),
+#     resolves the newest release tag reachable from the upstream default branch, and
+#     performs a full one-way synchronization of the upstream repository root into the
+#     local read-only `pi.dev-src/pi` target. Every dot-prefixed upstream entry
+#     (`.git`, `.github`, `.gitignore`, and any other file or directory whose name
+#     starts with `.`) is excluded at every tree level. 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`.
+#     After the source synchronization completes, three documentation targets are
+#     refreshed from the synchronized sources: `docs/pi.dev/coding-agent-docs`
+#     from `pi.dev-src/pi/packages/coding-agent/docs`,
+#     `docs/pi.dev/coding-agent-examples` from
+#     `pi.dev-src/pi/packages/coding-agent/examples`, and `docs/pi.dev/durable-docs`
+#     from `pi.dev-src/pi/packages/durable/docs`. Existing target files whose
+#     bytes differ from the upstream candidate only in carriage-return
+#     line-ending characters are preserved with their committed bytes and
+#     timestamps, so repeated updates against an unchanged upstream release
+#     leave the git working tree clean. Before any modification, the
+#     updater prints the resolved latest version and the stored versions read from
+#     `docs/pi.dev/pi-cli-version.txt` and `pi.dev-src/pi-cli-version.txt`
+#     (missing or empty files report `unknown`), then requires an explicit `Y`
+#     confirmation; any other input aborts without modifications. On success, the
+#     resolved version is written into both version marker files. Runtime is
+#     dominated by one git clone plus one tag checkout and per-file copies.
+#     Side effects include temporary-directory creation, git subprocesses, and
+#     replacement of the four target directories plus the two version marker
+#     files. No other repository content is modified.
+# @satisfies DES-023, REQ-385, REQ-386, REQ-387, REQ-388, REQ-389, REQ-390, REQ-391, REQ-392, REQ-393, REQ-394, REQ-395
+
+set -euo pipefail
+
+PI_REPO_URL_PRIMARY="https://github.com/earendil-works/pi.git"
+PI_REPO_URL_FALLBACK="https://github.com/earendil-works/pi"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+## @brief Stores the resolved read-only pi CLI source synchronization target.
+## @details The updater replaces the whole content of `${REPO_ROOT}/${SRC_TARGET_REL}`
+##     with the non-dot upstream repository tree. The constant is immutable at
+##     runtime and costs O(1) per access.
+SRC_TARGET_REL="pi.dev-src/pi"
+
+## @brief Stores the ordered `source-relative:target-relative` documentation synchronization pairs.
+## @details Each entry maps one directory inside the synchronized `${SRC_TARGET_REL}`
+##     tree to one `docs/pi.dev` target directory synchronized in declaration order
+##     after the source synchronization completes. The constant is immutable at
+##     runtime and costs O(1) per element access.
+DOC_SYNC_SPECS=(
+  "pi.dev-src/pi/packages/coding-agent/docs:docs/pi.dev/coding-agent-docs"
+  "pi.dev-src/pi/packages/coding-agent/examples:docs/pi.dev/coding-agent-examples"
+  "pi.dev-src/pi/packages/durable/docs:docs/pi.dev/durable-docs"
+)
+
+## @brief Stores the documentation version marker path relative to the repository root.
+## @details Read before the update and overwritten with the resolved version after
+##     successful synchronization. The constant is immutable at runtime.
+DOC_VERSION_REL="docs/pi.dev/pi-cli-version.txt"
+
+## @brief Stores the source version marker path relative to the repository root.
+## @details Read before the update and overwritten with the resolved version after
+##     successful synchronization. The constant is immutable at runtime.
+SRC_VERSION_REL="pi.dev-src/pi-cli-version.txt"
+
+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 Reads one stored pi CLI version marker file.
+## @details Returns the first line of the marker file with all surrounding
+##     whitespace removed when the file exists and is non-empty; otherwise
+##     returns the literal `unknown` so missing or empty version markers are
+##     handled deterministically. Runtime is O(n) in file size. Side effects are
+##     limited to filesystem reads.
+## @param[in] marker_path {string} Absolute version marker file path.
+## @return {string} Trimmed stored version or `unknown` on `stdout`.
+read_version_file() {
+  local marker_path="$1"
+  local version=""
+  if [ -f "${marker_path}" ] && [ -s "${marker_path}" ]; then
+    version="$(head -n 1 "${marker_path}" | tr -d '[:space:]' || true)"
+  fi
+  if [ -z "${version}" ]; then
+    version="unknown"
+  fi
+  printf '%s\n' "${version}"
+}
+
+## @brief Clones the upstream pi CLI repository default branch into one target directory.
+## @details Attempts a quiet, no-checkout clone from `${PI_REPO_URL_PRIMARY}`,
+##     removes the partial destination on failure, and retries once with
+##     `${PI_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 "${PI_REPO_URL_PRIMARY}" "${destination}" 2>/dev/null; then
+    printf '%s\n' "${PI_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 "${PI_REPO_URL_FALLBACK}" "${destination}" 2>/dev/null; then
+    printf '%s\n' "${PI_REPO_URL_FALLBACK}"
+    return 0
+  fi
+  fail "Unable to clone pi CLI from ${PI_REPO_URL_PRIMARY} or ${PI_REPO_URL_FALLBACK}."
+}
+
+## @brief Resolves the latest released pi CLI tag reachable from the default branch.
+## @details Prefers the default branch reported by `refs/remotes/origin/HEAD` and
+##     falls back to `origin/master` then `origin/main` when the symbolic ref is
+##     absent. Selects the newest version-sorted tag matching `v[0-9]*` that is
+##     merged into the resolved default ref, which represents the latest release
+##     reachable from that branch. Prints the resolved tag on `stdout`. Runtime is
+##     dominated by git ref enumeration. No external state is mutated.
+## @param[in] repository {string} Cloned upstream repository path.
+## @return {string} Latest release tag name on stdout.
+## @throws Exits through `fail(...)` when no release tag is resolvable.
+resolve_release_tag() {
+  local repository="$1"
+  local default_ref=""
+  local release_tag=""
+
+  default_ref="$(git -C "${repository}" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+  if [ -z "${default_ref}" ]; then
+    if git -C "${repository}" rev-parse --verify --quiet refs/remotes/origin/master >/dev/null 2>&1; then
+      default_ref="origin/master"
+    else
+      default_ref="origin/main"
+    fi
+  fi
+
+  release_tag="$(git -C "${repository}" tag --list 'v[0-9]*' --sort=-v:refname --merged "${default_ref}" 2>/dev/null | head -n 1 || true)"
+  if [ -z "${release_tag}" ]; then
+    fail "Unable to resolve the latest pi CLI release tag from ${default_ref}."
+  fi
+  printf '%s\n' "${release_tag}"
+}
+
+## @brief Decides whether one staged upstream file must replace the existing target file.
+## @details Returns success (replace) when the target file does not exist or when
+##     its bytes differ from the staged upstream file beyond line-ending
+##     characters. Returns failure (preserve) when both files are byte-equal or
+##     when both files are equal after removing every carriage-return byte, so
+##     committed reference bytes and timestamps stay stable when upstream
+##     releases change only line endings. Runtime is O(n) in compared file size
+##     plus at most three subprocesses. Side effects are limited to subprocess
+##     execution and stdin pipes; no file is mutated.
+## @param[in] source_file {string} Absolute staged upstream candidate file path.
+## @param[in] target_file {string} Absolute existing target file path.
+## @return {integer} `0` when the staged file must replace the target; `1` when
+##     the existing target bytes must be preserved.
+staged_copy_replaces_existing() {
+  local source_file="$1"
+  local target_file="$2"
+  local source_normalized=""
+  local target_normalized=""
+
+  if [ ! -f "${target_file}" ]; then
+    return 0
+  fi
+  if cmp -s -- "${source_file}" "${target_file}"; then
+    return 0
+  fi
+  source_normalized="$(tr -d '\r' < "${source_file}" | git hash-object --stdin)" || return 0
+  target_normalized="$(tr -d '\r' < "${target_file}" | git hash-object --stdin)" || return 0
+  [ "${source_normalized}" != "${target_normalized}" ]
+}
+
+## @brief Fully synchronizes one upstream directory into one target directory.
+## @details Stages every upstream entry below `source_dir` into a fresh sibling
+##     staging directory using timestamp-preserving copies, excluding every
+##     dot-prefixed entry and its whole subtree at every tree level, then
+##     replaces `target_dir` with the staged tree through a backup-and-swap
+##     sequence so files removed upstream disappear and existing files are
+##     overwritten with an exact file-set match. Existing target files
+##     whose bytes differ from the staged upstream file only in carriage-return
+##     line-ending characters are preserved through
+##     `staged_copy_replaces_existing(...)` so unchanged upstream releases do
+##     not dirty the git working tree. 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 read-only 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 entry destination parent_dir copied=0
+  while IFS= read -r -d '' entry; do
+    entry="${entry#./}"
+    [ -n "${entry}" ] || continue
+    destination="${STAGING_DIR}/${entry}"
+    if [ -d "${source_dir}/${entry}" ]; then
+      mkdir -p "${destination}"
+    else
+      parent_dir="$(dirname "${destination}")"
+      mkdir -p "${parent_dir}"
+      if staged_copy_replaces_existing "${source_dir}/${entry}" "${target_dir}/${entry}"; then
+        cp -p "${source_dir}/${entry}" "${destination}"
+      else
+        cp -p "${target_dir}/${entry}" "${destination}"
+      fi
+    fi
+    copied=$((copied + 1))
+  done < <(cd "${source_dir}" && find . -mindepth 1 \( -name '.*' -prune \) -o -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 Requests explicit user confirmation before any modification.
+## @details Prints the versions plus one English confirmation sentence, reads one
+##     line from `stdin`, and returns success only when the confirmation input is
+##     exactly `Y`; any other input, including end-of-stream input, returns
+##     failure so callers abort without modifications. Runtime is O(1) plus one
+##     user interaction. Side effects include `stdout` and `stderr` writes.
+## @param[in] latest_version {string} Resolved upstream release version.
+## @param[in] doc_version {string} Stored version of `${DOC_VERSION_REL}`.
+## @param[in] src_version {string} Stored version of `${SRC_VERSION_REL}`.
+## @return {integer} `0` when the user confirmed with exactly `Y`; `1` otherwise.
+confirm_update() {
+  local latest_version="$1"
+  local doc_version="$2"
+  local src_version="$3"
+  local answer=""
+
+  log "Latest pi CLI release : ${latest_version}"
+  log "Stored version (${DOC_VERSION_REL}): ${doc_version}"
+  log "Stored version (${SRC_VERSION_REL}): ${src_version}"
+  log "This update replaces the read-only reference sources in ${SRC_TARGET_REL} and the documentation in docs/pi.dev with the content of the latest pi CLI release."
+  printf 'Proceed with the update? [Y/n] '
+  read -r answer || answer=""
+  [ "${answer}" = "Y" ]
+}
+
+## @brief Executes one full pi CLI reference update run.
+## @details Validates required tools, allocates the temporary upstream working
+##     tree, clones the pi CLI default branch, resolves and checks out the newest
+##     release tag, prints the resolved plus stored versions, requires an explicit
+##     `Y` confirmation, synchronizes the upstream repository root into the
+##     read-only source target excluding every dot-prefixed entry, synchronizes
+##     every ordered documentation pair declared in `DOC_SYNC_SPECS`, and writes
+##     the resolved version into both version marker files. Runtime is dominated
+##     by the upstream clone plus the four directory synchronizations. Side
+##     effects include temporary-directory creation and removal, git subprocesses,
+##     and replacement of the four target directories plus the two version marker
+##     files.
+## @return {void} No return value.
+## @throws Exits through `fail(...)` when any required tool, clone, tag
+##     resolution, or synchronization step fails.
+main() {
+  require_tool git
+  require_tool find
+  require_tool mkdir
+  require_tool cp
+  require_tool cmp
+
+  local doc_version src_version
+  doc_version="$(read_version_file "${REPO_ROOT}/${DOC_VERSION_REL}")"
+  src_version="$(read_version_file "${REPO_ROOT}/${SRC_VERSION_REL}")"
+
+  WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/pi-cli-update-src-docs.XXXXXX")" \
+    || fail "Unable to create the temporary working directory."
+  local repository="${WORK_DIR}/pi"
+
+  local upstream_url
+  upstream_url="$(clone_upstream "${repository}")"
+  log "Upstream repository: ${upstream_url}"
+
+  local release_tag
+  release_tag="$(resolve_release_tag "${repository}")"
+
+  if ! confirm_update "${release_tag}" "${doc_version}" "${src_version}"; then
+    log "Update aborted; no repository content was modified."
+    return 0
+  fi
+
+  git -C "${repository}" checkout --quiet --detach "${release_tag}" \
+    || fail "Unable to check out ${release_tag}."
+  log "Synchronizing from release: ${release_tag}"
+
+  sync_directory "${repository}" "${REPO_ROOT}/${SRC_TARGET_REL}"
+
+  local spec source_rel target_rel
+  for spec in "${DOC_SYNC_SPECS[@]}"; do
+    source_rel="${spec%%:*}"
+    target_rel="${spec#*:}"
+    sync_directory "${REPO_ROOT}/${source_rel}" "${REPO_ROOT}/${target_rel}"
+  done
+
+  printf '%s\n' "${release_tag}" > "${REPO_ROOT}/${DOC_VERSION_REL}"
+  printf '%s\n' "${release_tag}" > "${REPO_ROOT}/${SRC_VERSION_REL}"
+
+  log "pi CLI reference sources and documentation updated to ${release_tag}."
+}
+
+trap cleanup EXIT
+main "$@"

package/scripts/pi-prompts-update.sh

@@ -8,13 +8,19 @@
 #     `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
+#     access and modification timestamps are preserved through `cp -p`. Before
+#     any modification, the updater prints the resolved latest PI-Prompts
+#     release version and the stored version read from
+#     `src/resources/pi-prompts-version.txt` (missing or empty files report
+#     `unknown`), then requires an explicit `Y` confirmation; any other input
+#     aborts without modifications. On success, the resolved version is written
+#     into `src/resources/pi-prompts-version.txt`. 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, replacement of the three target resource
+#     directories, and overwrite of the one version marker file. No other
+#     repository content is modified.
+# @satisfies DES-022, REQ-379, REQ-380, REQ-381, REQ-382, REQ-383, REQ-384, REQ-396, REQ-397, REQ-398, REQ-399
 
 set -euo pipefail
 
@@ -27,6 +33,12 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 TARGET_ROOT="${REPO_ROOT}/src/resources"
 
+## @brief Stores the PI-Prompts version marker path relative to the repository root.
+## @details Read before the update and overwritten with the resolved version after
+##     successful synchronization. The constant is immutable at runtime.
+## @satisfies REQ-396, REQ-399
+PROMPTS_VERSION_REL="src/resources/pi-prompts-version.txt"
+
 ## @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
@@ -87,6 +99,73 @@ require_tool() {
   command -v "$1" >/dev/null 2>&1 || fail "Required tool not found: $1"
 }
 
+## @brief Reads one stored PI-Prompts version marker file.
+## @details Returns the first line of the marker file with all surrounding
+##     whitespace removed when the file exists and is non-empty; otherwise
+##     returns the literal `unknown` so missing or empty version markers are
+##     handled deterministically. Runtime is O(n) in file size. Side effects are
+##     limited to filesystem reads.
+## @param[in] marker_path {string} Absolute version marker file path.
+## @return {string} Trimmed stored version or `unknown` on `stdout`.
+## @satisfies REQ-396
+read_version_file() {
+  local marker_path="$1"
+  local version=""
+  if [ -f "${marker_path}" ] && [ -s "${marker_path}" ]; then
+    version="$(head -n 1 "${marker_path}" | tr -d '[:space:]' || true)"
+  fi
+  if [ -z "${version}" ]; then
+    version="unknown"
+  fi
+  printf '%s\n' "${version}"
+}
+
+## @brief Derives the release version from one resolved upstream synchronization ref.
+## @details Strips the `refs/tags/` prefix from a release-tag ref and the
+##     `refs/heads/` prefix from a branch-head ref so the printed version and
+##     the stored version marker share one deterministic release identity.
+##     Runtime is O(n) in ref length. No external state is mutated.
+## @param[in] release_ref {string} Resolved `refs/tags/<tag>` or `refs/heads/<branch>` ref.
+## @return {string} Release version on `stdout`.
+resolve_release_version() {
+  local release_ref="$1"
+  case "${release_ref}" in
+    refs/tags/*)
+      printf '%s\n' "${release_ref#refs/tags/}"
+      ;;
+    refs/heads/*)
+      printf '%s\n' "${release_ref#refs/heads/}"
+      ;;
+    *)
+      printf '%s\n' "${release_ref}"
+      ;;
+  esac
+}
+
+## @brief Requests explicit user confirmation before any modification.
+## @details Prints the resolved latest PI-Prompts release version plus the stored
+##     version and one English confirmation sentence, reads one line from
+##     `stdin`, and returns success only when the confirmation input is exactly
+##     `Y`; any other input, including end-of-stream input, returns failure so
+##     callers abort without modifications. Runtime is O(1) plus one user
+##     interaction. Side effects include `stdout` and `stderr` writes.
+## @param[in] latest_version {string} Resolved upstream release version.
+## @param[in] stored_version {string} Stored version of `${PROMPTS_VERSION_REL}`.
+## @return {integer} `0` when the user confirmed with exactly `Y`; `1` otherwise.
+## @satisfies REQ-397, REQ-398
+confirm_update() {
+  local latest_version="$1"
+  local stored_version="$2"
+  local answer=""
+
+  log "Latest PI-Prompts release : ${latest_version}"
+  log "Stored version (${PROMPTS_VERSION_REL}): ${stored_version}"
+  log "This update replaces the bundled prompt resources in src/resources/instructions, src/resources/prompts, and src/resources/templates with the content of the latest PI-Prompts release."
+  printf 'Proceed with the update? [Y/n] '
+  read -r answer || answer=""
+  [ "${answer}" = "Y" ]
+}
+
 ## @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,
@@ -194,22 +273,30 @@ sync_directory() {
 }
 
 ## @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.
+## @details Validates required tools, reads the stored PI-Prompts version marker,
+##     allocates the temporary upstream working tree, clones the PI-Prompts
+##     master branch, resolves the newest release ref plus its release version,
+##     prints the resolved plus stored versions and requires an explicit `Y`
+##     confirmation, checks out the resolved release ref, synchronizes every
+##     ordered pair declared in `SYNC_SPECS`, and writes the resolved version
+##     into the version marker file. 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, replacement of the three bundled target
+##     directories, and overwrite of the version marker file.
 ## @return {void} No return value.
 ## @throws Exits through `fail(...)` when any required tool, clone, checkout, or
 ##     synchronization step fails.
+## @satisfies REQ-396, REQ-397, REQ-398, REQ-399
 main() {
   require_tool git
   require_tool find
   require_tool mkdir
   require_tool cp
 
+  local prompts_version
+  prompts_version="$(read_version_file "${REPO_ROOT}/${PROMPTS_VERSION_REL}")"
+
   mkdir -p "${TARGET_ROOT}"
 
   WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/pi-prompts-update.XXXXXX")" \
@@ -222,6 +309,15 @@ main() {
 
   local release_ref
   release_ref="$(resolve_release_ref "${repository}")"
+
+  local release_version
+  release_version="$(resolve_release_version "${release_ref}")"
+
+  if ! confirm_update "${release_version}" "${prompts_version}"; then
+    log "Update aborted; no repository content was modified."
+    return 0
+  fi
+
   git -C "${repository}" checkout --quiet --detach "${release_ref}" \
     || fail "Unable to check out ${release_ref}."
   log "Synchronizing from ref: ${release_ref}"
@@ -233,7 +329,9 @@ main() {
     sync_directory "${repository}/${source_rel}" "${REPO_ROOT}/${target_rel}"
   done
 
-  log "Bundled prompt resources updated."
+  printf '%s\n' "${release_version}" > "${REPO_ROOT}/${PROMPTS_VERSION_REL}"
+
+  log "Bundled prompt resources updated to ${release_version}."
 }
 
 trap cleanup EXIT

package/src/core/context-file-size.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Measures runtime character and token sizes of the canonical context files.
- * @details Provides reusable helpers that compute character and `cl100k_base` token estimates for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` under `<base-path>/<docs-dir>` so configuration menus and command summaries share one measurement contract. Runtime is O(n) in aggregate context-file size. Side effects are limited to filesystem reads.
+ * @details Provides reusable helpers that compute character and `cl100k_base` token estimates for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` under `<base-path>/<docs-dir>` so configuration menus and command summaries share one measurement contract. Measurements are memoized per resolved path against the file `mtimeMs` plus `size` signature and reuses the process-cached shared tokenizer, so repeated menu renders resolve unchanged files through filesystem stats only. Runtime is O(n) on first measurement per content revision and O(1) per unchanged remeasure. Side effects are limited to filesystem reads and module-local cache mutation.
  */
 
 import fs from "node:fs";
@@ -9,6 +9,7 @@ import path from "node:path";
 import { DEFAULT_DOCS_DIR, type UseReqConfig } from "./config.js";
 import { normalizeRelativeDirContract } from "./path-context.js";
 import { countFileMetrics } from "./token-counter.js";
+import { ReqError } from "./errors.js";
 
 /**
  * @brief Stores the canonical context-file names in their documented injection order.
@@ -41,6 +42,27 @@ export interface ContextFileSizeFacts {
  */
 export const MISSING_CONTEXT_FILE_SIZE: ContextFileSizeFacts = Object.freeze({ exists: false, chars: 0, tokens: 0 });
 
+/**
+ * @brief Stores one memoized context-file measurement with its staleness signature.
+ * @details Pairs the measured facts with the `mtimeMs` plus `size` filesystem signature observed at measurement time so later probes can decide, through one stat call, whether the cached facts still describe the current file content. The interface is compile-time only and introduces no runtime cost.
+ */
+interface CachedContextFileSizeEntry {
+  readonly statSignature: string;
+  readonly facts: ContextFileSizeFacts;
+}
+
+/**
+ * @brief Bounds the module-local context-file measurement cache.
+ * @details Worktree-backed prompt runs measure three context files per execution path, so unbounded caching would accumulate one entry triplet per generated worktree in long-lived pi hosts. Exceeding the bound clears the cache completely, which only costs one re-measurement per live path. Lookup complexity is O(1).
+ */
+const CONTEXT_FILE_SIZE_CACHE_LIMIT = 64;
+
+/**
+ * @brief Stores the module-local context-file measurement cache keyed by resolved path.
+ * @details Maps each measured absolute context-file path to its stat-signed facts so repeated configuration-menu renders and command summaries reuse identical measurements while any content revision invalidates only the affected entry. Cache state is module-local and never serialized into configuration.
+ */
+const contextFileSizeCache = new Map<string, CachedContextFileSizeEntry>();
+
 /**
  * @brief Resolves one canonical context-file absolute path for one project base.
  * @details Joins the project base with the trailing-slash-free configured `docs-dir` (falling back to `DEFAULT_DOCS_DIR`) and the supplied canonical file name so menus, summaries, and the `%%CONTEXT_FILES%%` renderer address identical targets. Runtime is O(p) in path length. No external state is mutated.
@@ -61,18 +83,34 @@ export function resolveContextFilePath(
 
 /**
  * @brief Measures one context file into deterministic size facts.
- * @details Probes filesystem existence and file kind, reads UTF-8 content, and reuses the shared `countFileMetrics` tokenizer for the `cl100k_base` token estimate. Missing, non-file, and unreadable targets return `MISSING_CONTEXT_FILE_SIZE` facts without throwing. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
+ * @details Probes the target with one `stat` call, returns the memoized facts when the observed `mtimeMs` plus `size` signature matches the cached entry, and otherwise reads UTF-8 content and reuses the process-cached shared tokenizer behind `countFileMetrics` for the `cl100k_base` token estimate before storing the fresh facts in the bounded cache. Missing, non-file, and unreadable targets return `MISSING_CONTEXT_FILE_SIZE` facts without throwing and without caching. Runtime is O(1) for unchanged remeasures and O(n) in file size on first measurement per content revision. Side effects are limited to filesystem reads and module-local cache mutation.
  * @param[in] filePath {string} Absolute context-file path to measure.
  * @return {ContextFileSizeFacts} Measured size facts for the target.
  * @satisfies REQ-373, REQ-374
  */
 export function measureContextFileSize(filePath: string): ContextFileSizeFacts {
+  let stat: fs.Stats | undefined;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    stat = undefined;
+  }
+  if (!stat || !stat.isFile()) {
+    return MISSING_CONTEXT_FILE_SIZE;
+  }
+  const statSignature = `${stat.mtimeMs}:${stat.size}`;
+  const cachedEntry = contextFileSizeCache.get(filePath);
+  if (cachedEntry && cachedEntry.statSignature === statSignature) {
+    return cachedEntry.facts;
+  }
   try {
-    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
-      return MISSING_CONTEXT_FILE_SIZE;
-    }
     const metrics = countFileMetrics(fs.readFileSync(filePath, "utf8"));
-    return { exists: true, chars: metrics.chars, tokens: metrics.tokens };
+    const facts: ContextFileSizeFacts = { exists: true, chars: metrics.chars, tokens: metrics.tokens };
+    if (contextFileSizeCache.size >= CONTEXT_FILE_SIZE_CACHE_LIMIT) {
+      contextFileSizeCache.clear();
+    }
+    contextFileSizeCache.set(filePath, { statSignature, facts });
+    return facts;
   } catch {
     return MISSING_CONTEXT_FILE_SIZE;
   }
@@ -80,7 +118,7 @@ export function measureContextFileSize(filePath: string): ContextFileSizeFacts {
 
 /**
  * @brief Measures every canonical context file for one project base.
- * @details Iterates `CONTEXT_FILE_NAMES` in documented order, resolves each configured `<base-path>/<docs-dir>` target through `resolveContextFilePath`, and returns the keyed facts record consumed by configuration menus and command summaries. Runtime is O(n) in aggregate context-file size. Side effects are limited to filesystem reads.
+ * @details Iterates `CONTEXT_FILE_NAMES` in documented order, resolves each configured `<base-path>/<docs-dir>` target through `resolveContextFilePath`, and returns the keyed facts record consumed by configuration menus and command summaries. Repeated invocations with unchanged files resolve through the stat-signed measurement cache. Runtime is O(n) in aggregate context-file size on first measurement per content revision and O(1) per unchanged remeasure. Side effects are limited to filesystem reads and module-local cache mutation.
  * @param[in] projectBase {string} Absolute project root path.
  * @param[in] config {UseReqConfig} Effective project configuration supplying the docs directory.
  * @return {Record<ContextFileName, ContextFileSizeFacts>} Measured size facts keyed by canonical file name.
@@ -107,3 +145,162 @@ export function measureContextFileSizes(
 export function formatContextFileSize(facts: ContextFileSizeFacts): string {
   return `${facts.chars}c/${facts.tokens}t`;
 }
+
+/**
+ * @brief Stores the documented fallback context-window token budget.
+ * @details Used as the occupancy computation basis and as the early-check limit whenever the selected model max input context is unknown, and always renders behind the `*` marker so consumers can detect the assumed basis. Lookup complexity is O(1).
+ * @satisfies REQ-403
+ */
+export const CONTEXT_OCCUPANCY_FALLBACK_CONTEXT_WINDOW_TOKENS = 1_000_000;
+
+/**
+ * @brief Maps every canonical context file to its persisted configuration flag key.
+ * @details Single mapping source shared by the token summation and segment renderers so enabled-file selection stays identical across every occupancy surface. Lookup complexity is O(1). No external state is mutated.
+ */
+const CONTEXT_FILE_FLAG_KEYS: Record<ContextFileName, "context-files-requirements" | "context-files-references" | "context-files-workflow"> = {
+  "REQUIREMENTS.md": "context-files-requirements",
+  "REFERENCES.md": "context-files-references",
+  "WORKFLOW.md": "context-files-workflow",
+};
+
+/**
+ * @brief Describes the computed context-occupancy facts of one enabled context-file set.
+ * @details Stores the aggregate token total, the resolved selected-model max input context (undefined when unknown), the effective basis tokens used for the percentage, the rendered percentage label, the rendered max-context label, and the final bracketed occupancy suffix. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-400
+ */
+export interface ContextOccupancyFacts {
+  readonly totalTokens: number;
+  readonly maxContextTokens: number | undefined;
+  readonly basisTokens: number;
+  readonly percentLabel: string;
+  readonly maxLabel: string;
+  readonly suffix: string;
+}
+
+/**
+ * @brief Sums the `cl100k_base` token estimates of every enabled existing context file.
+ * @details Iterates `CONTEXT_FILE_NAMES` in documented order, skips disabled flags and missing or unreadable files, and accumulates the measured token estimates so occupancy surfaces and the prompt-dispatch early check share one total. Runtime is O(1) in file count. No external state is mutated.
+ * @param[in] config {Pick<UseReqConfig, "context-files-requirements" | "context-files-references" | "context-files-workflow">} Effective configuration supplying the three context-file flags.
+ * @param[in] sizes {Record<string, ContextFileSizeFacts>} Measured context-file size facts keyed by canonical file name.
+ * @return {number} Aggregate token estimate of enabled existing context files.
+ * @satisfies REQ-400
+ */
+export function sumEnabledContextFileTokens(
+  config: Pick<UseReqConfig, "context-files-requirements" | "context-files-references" | "context-files-workflow">,
+  sizes: Record<string, ContextFileSizeFacts>,
+): number {
+  let totalTokens = 0;
+  for (const fileName of CONTEXT_FILE_NAMES) {
+    const facts = sizes[fileName];
+    if (!config[CONTEXT_FILE_FLAG_KEYS[fileName]] || !facts || !facts.exists) {
+      continue;
+    }
+    totalTokens += facts.tokens;
+  }
+  return totalTokens;
+}
+
+/**
+ * @brief Formats one context-window token count as a compact human-readable label.
+ * @details Renders token counts of one million or more as `<x.x>M`, counts of one thousand or more as `<x.x>K`, and smaller counts as rounded integers so the documented `1.0M` fallback shape stays deterministic. Runtime is O(1). No external state is mutated.
+ * @param[in] tokens {number} Context-window token count to label.
+ * @return {string} Compact context-window label such as `1.0M`, `200.0K`, or `512`.
+ * @satisfies REQ-403
+ */
+export function formatContextWindowTokensLabel(tokens: number): string {
+  if (tokens >= 1_000_000) {
+    return `${(tokens / 1_000_000).toFixed(1)}M`;
+  }
+  if (tokens >= 1_000) {
+    return `${(tokens / 1_000).toFixed(1)}K`;
+  }
+  return String(Math.round(tokens));
+}
+
+/**
+ * @brief Formats one occupancy percentage as a compact label with one decimal place.
+ * @details Rounds the percentage to one decimal place and removes a trailing `.0` so whole percentages render as `36%` and fractional values keep their decimal digit. Runtime is O(1). No external state is mutated.
+ * @param[in] percent {number} Occupancy percentage value.
+ * @return {string} Percentage label such as `36%`, `0.4%`, or `0%`.
+ * @satisfies REQ-402
+ */
+export function formatContextOccupancyPercentLabel(percent: number): string {
+  const fixed = percent.toFixed(1);
+  return fixed.endsWith(".0") ? fixed.slice(0, -2) : fixed;
+}
+
+/**
+ * @brief Computes the context-occupancy facts of one enabled context-file token total.
+ * @details Resolves the effective basis from the supplied max input context or the documented 1,000,000-token fallback, derives the percentage label, derives the max label with the `*` marker only for the unknown fallback, and renders `[<percent>% context]` for a known max or `[<percent>%/1.0M* context]` for the fallback basis. Runtime is O(1). No external state is mutated.
+ * @param[in] totalTokens {number} Aggregate enabled existing context-file token estimate.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens; undefined selects the fallback basis.
+ * @return {ContextOccupancyFacts} Computed occupancy facts including the rendered suffix.
+ * @satisfies REQ-400, REQ-402, REQ-403
+ */
+export function computeContextOccupancyFacts(
+  totalTokens: number,
+  maxContextTokens: number | undefined,
+): ContextOccupancyFacts {
+  const knownMax = typeof maxContextTokens === "number" && Number.isFinite(maxContextTokens) && maxContextTokens > 0
+    ? maxContextTokens
+    : undefined;
+  const basisTokens = knownMax ?? CONTEXT_OCCUPANCY_FALLBACK_CONTEXT_WINDOW_TOKENS;
+  const percentLabel = formatContextOccupancyPercentLabel((totalTokens / basisTokens) * 100);
+  const maxLabel = knownMax === undefined
+    ? `${formatContextWindowTokensLabel(basisTokens)}*`
+    : formatContextWindowTokensLabel(knownMax);
+  const suffix = knownMax === undefined
+    ? `[${percentLabel}%/${maxLabel} context]`
+    : `[${percentLabel}% context]`;
+  return { totalTokens, maxContextTokens: knownMax, basisTokens, percentLabel, maxLabel, suffix };
+}
+
+/**
+ * @brief Renders every enabled existing context file as a `name(<chars>c/<tokens>t)` segment list.
+ * @details Iterates `CONTEXT_FILE_NAMES` in documented order, skips disabled flags and missing or unreadable files, and joins the remaining segments with the documented ` • ` separator so early-check diagnostics reuse the same segment shape as the configuration summary. Runtime is O(1) in file count. No external state is mutated.
+ * @param[in] config {Pick<UseReqConfig, "context-files-requirements" | "context-files-references" | "context-files-workflow">} Effective configuration supplying the three context-file flags.
+ * @param[in] sizes {Record<string, ContextFileSizeFacts>} Measured context-file size facts keyed by canonical file name.
+ * @return {string} Joined segment list, or the empty string when no enabled existing context file contributes.
+ * @satisfies REQ-410
+ */
+export function formatEnabledContextFileSegments(
+  config: Pick<UseReqConfig, "context-files-requirements" | "context-files-references" | "context-files-workflow">,
+  sizes: Record<string, ContextFileSizeFacts>,
+): string {
+  const segments: string[] = [];
+  for (const fileName of CONTEXT_FILE_NAMES) {
+    const facts = sizes[fileName];
+    if (!config[CONTEXT_FILE_FLAG_KEYS[fileName]] || !facts || !facts.exists) {
+      continue;
+    }
+    segments.push(`${fileName}(${formatContextFileSize(facts)})`);
+  }
+  return segments.join(" • ");
+}
+
+/**
+ * @brief Enforces the context-occupancy early check for one prepared prompt command.
+ * @details Sums the enabled existing context-file tokens, computes the occupancy facts against the supplied max input context or the documented fallback, and throws one deterministic ReqError diagnostic listing every enabled existing file segment, the aggregate token total, and the occupancy suffix whenever the total strictly exceeds the basis. Runtime is O(1) in file count. No external state is mutated.
+ * @param[in] config {Pick<UseReqConfig, "context-files-requirements" | "context-files-references" | "context-files-workflow">} Effective configuration supplying the three context-file flags.
+ * @param[in] sizes {Record<string, ContextFileSizeFacts>} Measured context-file size facts keyed by canonical file name.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens; undefined selects the fallback basis.
+ * @return {ContextOccupancyFacts} Computed occupancy facts when the check passes.
+ * @throws {ReqError} Throws when the enabled token total strictly exceeds the effective basis.
+ * @satisfies REQ-408, REQ-409, REQ-410
+ */
+export function enforceContextOccupancyLimit(
+  config: Pick<UseReqConfig, "context-files-requirements" | "context-files-references" | "context-files-workflow">,
+  sizes: Record<string, ContextFileSizeFacts>,
+  maxContextTokens: number | undefined,
+): ContextOccupancyFacts {
+  const facts = computeContextOccupancyFacts(sumEnabledContextFileTokens(config, sizes), maxContextTokens);
+  const segments = formatEnabledContextFileSegments(config, sizes);
+  if (segments.length > 0 && facts.totalTokens > facts.basisTokens) {
+    throw new ReqError(
+      `Context occupancy early check failed: enabled context files total ${facts.totalTokens}t exceed ` +
+        `${facts.maxLabel} selected model input context. ${segments} ${facts.suffix}`,
+      1,
+    );
+  }
+  return facts;
+}

package/src/core/extension-status.ts

@@ -364,6 +364,22 @@ function normalizeContextUsage(
   };
 }
 
+/**
+ * @brief Resolves the selected model max input context tokens from one normalized context-usage snapshot.
+ * @details Accepts only finite positive `contextWindow` numbers so missing, non-numeric, and non-positive runtime values degrade to `undefined`, which every context-occupancy consumer treats as the documented unknown basis. Runtime is O(1). No external state is mutated.
+ * @param[in] contextUsage {ContextUsage | undefined} Normalized context-usage snapshot from the status controller state.
+ * @return {number | undefined} Selected model max input context tokens, or undefined when unknown.
+ * @satisfies REQ-401
+ */
+export function resolveModelContextWindowTokens(
+  contextUsage: ContextUsage | undefined,
+): number | undefined {
+  const contextWindow = contextUsage?.contextWindow;
+  return typeof contextWindow === "number" && Number.isFinite(contextWindow) && contextWindow > 0
+    ? contextWindow
+    : undefined;
+}
+
 /**
  * @brief Refreshes the stored context-usage snapshot from the active extension context.
  * @details Calls `ctx.getContextUsage()` on every intercepted event so the

package/src/core/prompt-command-runtime.ts

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { ReqError } from "./errors.js";
+import { enforceContextOccupancyLimit, measureContextFileSizes } from "./context-file-size.js";
 import { classifyPiNotifyOutcome, type PiNotifyOutcome } from "./pi-notify.js";
 import {
   normalizeGitWorktreePrefix,
@@ -1695,7 +1696,7 @@ export function validatePromptRequiredDocs(
 
 /**
  * @brief Prepares prompt-command execution for one bundled prompt.
- * @details Runs slash-command-owned git validation, enforces the prompt-specific required-doc matrix, resolves persisted origin and execution session files, applies the effective worktree policy, generates and verifies a dedicated worktree when enabled, and returns the execution plan consumed by prompt rendering plus lifecycle hooks. Worktree-backed execution reuses the active session directory for the forked session file. Runtime is dominated by git subprocesses, worktree creation, and optional session-file cloning. Side effects include worktree creation, session-file creation, filesystem reads, and optional prompt debug-log writes.
+ * @details Runs slash-command-owned git validation, enforces the context-occupancy early check against the selected model max input context, enforces the prompt-specific required-doc matrix, resolves persisted origin and execution session files, applies the effective worktree policy, generates and verifies a dedicated worktree when enabled, and returns the execution plan consumed by prompt rendering plus lifecycle hooks. Worktree-backed execution reuses the active session directory for the forked session file. Runtime is dominated by git subprocesses, worktree creation, and optional session-file cloning. Side effects include worktree creation, session-file creation, filesystem reads, and optional prompt debug-log writes.
  * @param[in] promptName {PromptCommandName} Bundled prompt identifier.
  * @param[in] promptArgs {string} Raw prompt argument string.
  * @param[in] projectBase {string} Absolute current project base.
@@ -1706,9 +1707,10 @@ export function validatePromptRequiredDocs(
  * @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
  * @param[in] originalModel {PromptCommandModelSelection | undefined} Active model provider plus identifier captured by the command handler for later re-application.
  * @param[in] originalThinkingLevel {string | undefined} Active thinking level captured by the command handler for later re-application.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens consumed by the early occupancy check; undefined selects the documented 1,000,000-token fallback.
  * @return {PromptCommandExecutionPlan} Prepared execution plan.
- * @throws {ReqError} Throws when repository validation, required-doc validation, worktree creation, or session preparation fails.
- * @satisfies REQ-200, REQ-203, REQ-206, REQ-207, REQ-215, REQ-219, REQ-220, REQ-245, REQ-256, REQ-271, REQ-366
+ * @throws {ReqError} Throws when repository validation, the context-occupancy early check, required-doc validation, worktree creation, or session preparation fails.
+ * @satisfies REQ-200, REQ-203, REQ-206, REQ-207, REQ-215, REQ-219, REQ-220, REQ-245, REQ-256, REQ-271, REQ-366, REQ-408, REQ-409, REQ-410, REQ-411
  */
 export function preparePromptCommandExecution(
   promptName: PromptCommandName,
@@ -1721,8 +1723,10 @@ export function preparePromptCommandExecution(
   debugOptions?: PromptCommandDebugOptions,
   originalModel?: PromptCommandModelSelection,
   originalThinkingLevel?: string,
+  maxContextTokens?: number | undefined,
 ): PromptCommandExecutionPlan {
   const gitPath = validatePromptGitState(projectBase, config);
+  enforceContextOccupancyLimit(config, measureContextFileSizes(projectBase, config), maxContextTokens);
   const reuseCurrentSessionFile = isUsablePromptSessionFile(currentSessionFile, projectBase);
   const originalSessionFile = resolvePromptSessionFile(
     reuseCurrentSessionFile ? currentSessionFile : undefined,

package/src/core/prompts.ts

@@ -17,7 +17,7 @@ import {
   comparePiUsereqStartupToolNames,
   type PiUsereqStartupToolName,
 } from "./pi-usereq-tools.js";
-import { formatContextFileSize, type ContextFileSizeFacts } from "./context-file-size.js";
+import { computeContextOccupancyFacts, formatContextFileSize, sumEnabledContextFileTokens, type ContextFileSizeFacts } from "./context-file-size.js";
 import { formatRuntimePathForDisplay, normalizeRelativeDirContract } from "./path-context.js";
 import type {
   PromptCommandExecutionPlan,
@@ -387,28 +387,35 @@ export const PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE = "pi-usereq-prompt-command";
 
 /**
  * @brief Builds the on-screen command invocation summary for one bundled prompt-backed `req-<prompt>` command.
- * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. When measured context-file size facts are supplied, every enabled existing context file in the `context files` field is rendered as `name(<chars>c/<tokens>t)`; without facts, or for enabled missing files, the plain `name` form is rendered. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. The `context files`, `static code checks`, and `enabled tools` fields render the literal `none` placeholder whenever their respective enabled-item list is empty so the summary never shows a blank value. Sections are emitted in the order `Command:`, `Configuration:` with its bullet list, then `User's Request:`, each separated by one blank line. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
+ * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. When measured context-file size facts are supplied, every enabled existing context file in the `context files` field is rendered as `name(<chars>c/<tokens>t)`; when the enabled existing token total contributes tokens, the field additionally appends the `[<percent>% context]` occupancy suffix against the selected model max input context (or `[<percent>%/1.0M* context]` with the documented fallback); without facts, or for enabled missing files, the plain `name` form is rendered. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. The `context files`, `static code checks`, and `enabled tools` fields render the literal `none` placeholder whenever their respective enabled-item list is empty so the summary never shows a blank value. Sections are emitted in the order `Command:`, `Configuration:` with its bullet list, then `User's Request:`, each separated by one blank line. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
  * @param[in] promptName {string} Bundled prompt name without the `req-` prefix.
  * @param[in] args {string} User request arguments passed to the slash command.
  * @param[in] config {UseReqConfig} Effective project configuration supplying directory, git, static-check, and tool fields.
  * @param[in] contextFileSizes {Record<string, ContextFileSizeFacts> | undefined} Optional measured context-file size facts keyed by canonical file name, consumed for `context files` size suffixes.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens consumed by the occupancy suffix; undefined selects the documented 1,000,000-token fallback.
  * @return {string} Multi-line command invocation summary text.
- * @satisfies REQ-335, REQ-336, REQ-337, REQ-338, REQ-353, REQ-377
+ * @satisfies REQ-335, REQ-336, REQ-337, REQ-338, REQ-353, REQ-377, REQ-402, REQ-403, REQ-404, REQ-407
  */
 export function renderPromptCommandSummary(
   promptName: string,
   args: string,
   config: UseReqConfig,
   contextFileSizes?: Record<string, ContextFileSizeFacts>,
+  maxContextTokens?: number | undefined,
 ): string {
-  const contextFiles = CONTEXT_FILE_DESCRIPTORS
+  const contextSegments = CONTEXT_FILE_DESCRIPTORS
     .filter((descriptor) => config[descriptor.flagKey])
     .map((descriptor) => {
       const baseName = descriptor.fileName.replace(/\.md$/, "").toLowerCase();
       const facts = contextFileSizes?.[descriptor.fileName];
       return facts?.exists ? `${baseName}(${formatContextFileSize(facts)})` : baseName;
     })
-    .join(", ") || "none";
+    .join(", ");
+  const totalContextTokens = contextFileSizes ? sumEnabledContextFileTokens(config, contextFileSizes) : 0;
+  const contextFiles = (contextSegments || "none")
+    + (contextSegments && totalContextTokens > 0
+      ? ` ${computeContextOccupancyFacts(totalContextTokens, maxContextTokens).suffix}`
+      : "");
   const enabledLanguages = DEFAULT_STATIC_CHECK_LANGUAGES
     .filter((language) => config["static-check"][language]?.enabled === "enable")
     .join(", ") || "none";

package/src/core/token-counter.ts

@@ -196,14 +196,34 @@ function defaultJsTiktokenModuleLoader(): JsTiktokenModule {
 
 let jsTiktokenModuleLoader: () => JsTiktokenModule = defaultJsTiktokenModuleLoader;
 
+const cachedTokenCounterEncodings = new Map<string, TokenCounterEncoding>();
+
+/**
+ * @brief Resolves one shared tokenizer encoding for a `TokenCounter` construction.
+ * @details Checks the process-scoped per-encoding cache first and constructs the `js-tiktoken` encoding only on the first request per encoding name, so repeated `TokenCounter` construction across the `files-tokens` runner, canonical-doc counting, and context-file measurement reuses one parsed encoder instead of re-parsing the bundled BPE ranks each time. Runtime is O(1) after the first construction for the encoding and dominated by the single deferred `getEncoding` construction otherwise. Side effect: mutates the module-local encoding cache on first resolution per encoding name.
+ * @param[in] encodingName {string} `js-tiktoken` encoding identifier.
+ * @return {TokenCounterEncoding} Cached or newly constructed tokenizer encoding.
+ * @throws {ReqError} Propagates the deterministic unavailable-dependency failure when `js-tiktoken` cannot be loaded.
+ */
+function resolveTokenCounterEncoding(encodingName: string): TokenCounterEncoding {
+  const cachedEncoding = cachedTokenCounterEncodings.get(encodingName);
+  if (cachedEncoding) {
+    return cachedEncoding;
+  }
+  const encoding = loadJsTiktokenModule().getEncoding(encodingName);
+  cachedTokenCounterEncodings.set(encodingName, encoding);
+  return encoding;
+}
+
 /**
  * @brief Overrides the `js-tiktoken` loader for tests.
- * @details Enables deterministic dependency-failure tests without mutating repository dependencies on disk. Runtime is O(1). Side effects are limited to module-local test state.
+ * @details Enables deterministic dependency-failure tests without mutating repository dependencies on disk. Clears the process-scoped encoding cache so every loader swap observes fresh module behavior instead of encoders constructed by the previous loader. Runtime is O(e) in cached encoding count. Side effects are limited to module-local test state and cache reset.
  * @param[in] loader {(() => JsTiktokenModule) | undefined} Replacement loader, or `undefined` to restore the default loader.
  * @return {void} No return value.
  */
 export function setJsTiktokenModuleLoaderForTests(loader?: () => JsTiktokenModule): void {
   jsTiktokenModuleLoader = loader ?? defaultJsTiktokenModuleLoader;
+  cachedTokenCounterEncodings.clear();
 }
 
 /**
@@ -233,23 +253,23 @@ function loadJsTiktokenModule(): JsTiktokenModule {
 
 /**
  * @brief Encapsulates one tokenizer instance for repeated token counting.
- * @details Caches a `js-tiktoken` encoding object so multiple documents can be counted without repeated encoding lookup. Counting cost is O(n) in content length. The class mutates only instance state during construction.
+ * @details Resolves the process-scoped shared encoder for the requested encoding so multiple documents and multiple counter instances are counted without repeated encoding construction; the first construction per encoding name parses the BPE ranks once and every later `TokenCounter` reuses it through the module-local cache. Counting cost is O(n) in content length. The class mutates only instance state during construction.
  */
 export class TokenCounter {
   /**
    * @brief Stores the tokenizer implementation used for subsequent counts.
-   * @details The field holds the encoder returned by `getEncoding`. Access complexity is O(1). The value is initialized once per instance.
+   * @details Holds the cached encoder resolved through the per-encoding process cache. Access complexity is O(1); construction is O(1) after the first resolution for the encoding name.
    */
   private encoding: TokenCounterEncoding;
 
   /**
    * @brief Initializes a token counter for one encoding family.
-   * @details Resolves the named tokenizer once and reuses it across `countTokens` calls. Construction complexity is O(1) relative to caller-controlled input size. Side effects are limited to instance initialization.
+   * @details Resolves the shared cached tokenizer for the encoding name, constructing the underlying `js-tiktoken` encoding at most once per encoding name per process so repeated constructions from token tools and context-file measurement are constant-time cache hits. Side effects are limited to instance initialization plus the optional first-time encoding cache mutation.
    * @param[in] encodingName {string} `js-tiktoken` encoding identifier. Defaults to `cl100k_base`.
    * @return {TokenCounter} New token counter instance.
    */
   constructor(encodingName = TOKEN_COUNTER_ENCODING) {
-    this.encoding = loadJsTiktokenModule().getEncoding(encodingName);
+    this.encoding = resolveTokenCounterEncoding(encodingName);
   }
 
   /**
@@ -427,7 +447,7 @@ function buildCountFileMetricsResult(filePath: string, content: string, counter:
 
 /**
  * @brief Counts tokens, characters, bytes, and lines for one in-memory content string.
- * @details Instantiates a `TokenCounter`, tokenizes the supplied text, and pairs the result with raw character length, UTF-8 byte size, and logical line count. Runtime is O(n). No filesystem I/O occurs.
+ * @details Resolves the process-cached shared `TokenCounter` encoder for the encoding, tokenizes the supplied text once, and pairs the result with raw character length, UTF-8 byte size, and logical line count. Runtime is O(n) after the one-time per-encoding encoder construction. No filesystem I/O occurs.
  * @param[in] content {string} Text payload to measure.
  * @param[in] encodingName {string} Tokenizer identifier. Defaults to `cl100k_base`.
  * @return {{ tokens: number; chars: number; bytes: number; lines: number }} Aggregate metrics for the supplied content.

package/src/index.ts

@@ -84,8 +84,10 @@ import {
   type PiUsereqStartupToolName,
 } from "./core/pi-usereq-tools.js";
 import {
+  computeContextOccupancyFacts,
   formatContextFileSize,
   measureContextFileSizes,
+  sumEnabledContextFileTokens,
   type ContextFileName,
   type ContextFileSizeFacts,
 } from "./core/context-file-size.js";
@@ -160,6 +162,7 @@ import {
   getPiUsereqRuntimeSoundLevel,
   isStaleExtensionContextError,
   renderPiUsereqStatus,
+  resolveModelContextWindowTokens,
   setPiUsereqRuntimeSoundLevel,
   setPiUsereqStatusConfig,
   setPiUsereqWorkflowState,
@@ -3397,6 +3400,7 @@ function registerPromptCommands(
         });
         const projectBase = getProjectBase(commandCwd);
         const config = loadProjectConfig(commandCwd);
+        const maxContextTokens = resolveModelContextWindowTokens(statusController.state.contextUsage);
         transitionPromptWorkflowState(
           statusController,
           ctx,
@@ -3427,6 +3431,7 @@ function registerPromptCommands(
             },
             originalModel,
             originalThinkingLevel,
+            maxContextTokens,
           );
           const content = renderPrompt(
             promptName,
@@ -3470,6 +3475,7 @@ function registerPromptCommands(
             args,
             config,
             measureContextFileSizes(projectBase, config),
+            maxContextTokens,
           );
           const promptDelivery = deliverPromptCommand(pi, content, commandSummary, promptContext);
           transitionPromptWorkflowState(
@@ -4545,44 +4551,56 @@ async function configureStaticCheckMenu(
 }
 
 /**
- * @brief Summarizes the `Context Files` flag state with measured sizes for the top-level menu value column.
- * @details Renders the three context-file flags as compact `name:on|off` segments in the documented order, appending `(<chars>c/<tokens>t)` measured size facts to every enabled segment so the top-level row exposes a runtime estimate of the injected context payload while disabled segments stay plain `name:off`. Runtime is O(1) in segment count. No external state is mutated.
+ * @brief Summarizes the `Context Files` flag state with measured sizes and context occupancy for the top-level menu value column.
+ * @details Renders the three context-file flags as compact `name:on|off` segments in the documented order, appending `(<chars>c/<tokens>t)` measured size facts to every enabled segment, then appends the occupancy suffix computed from the enabled existing token total against the selected model max input context (`[<percent>% context]`, or `[<percent>%/1.0M* context]` with the documented fallback) whenever that total contributes tokens, while disabled segments stay plain `name:off`. Runtime is O(1) in segment count. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] sizes {Record<ContextFileName, ContextFileSizeFacts>} Measured context-file size facts keyed by canonical file name.
- * @return {string} Compact `Context Files` summary string.
- * @satisfies REQ-327, REQ-376
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens; undefined selects the documented 1,000,000-token fallback.
+ * @return {string} Compact `Context Files` summary string with the occupancy suffix.
+ * @satisfies REQ-327, REQ-376, REQ-402, REQ-403, REQ-404, REQ-405
  */
 function formatContextFilesSummary(
   config: UseReqConfig,
   sizes: Record<ContextFileName, ContextFileSizeFacts>,
+  maxContextTokens?: number | undefined,
 ): string {
   const segments = [
     `requirements:${config["context-files-requirements"] ? `on(${formatContextFileSize(sizes["REQUIREMENTS.md"])})` : "off"}`,
     `references:${config["context-files-references"] ? `on(${formatContextFileSize(sizes["REFERENCES.md"])})` : "off"}`,
     `workflow:${config["context-files-workflow"] ? `on(${formatContextFileSize(sizes["WORKFLOW.md"])})` : "off"}`,
   ];
-  return segments.join(" \u2022 ");
+  const summary = segments.join(" \u2022 ");
+  const totalTokens = sumEnabledContextFileTokens(config, sizes);
+  return totalTokens > 0
+    ? `${summary} ${computeContextOccupancyFacts(totalTokens, maxContextTokens).suffix}`
+    : summary;
 }
 
 /**
  * @brief Builds the shared settings-menu choices for the `Context Files` submenu.
- * @details Exposes one inline toggle row per context file in the documented `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md` order whose value renders `on|off • <chars>c/<tokens>t` measured size facts plus a value-less subtree-local `Reset defaults` row. Cycle values embed the same measured facts so inline toggling keeps the size estimate visible while persisting the on|off state. Runtime is O(1) in row count. No external state is mutated.
+ * @details Exposes one inline toggle row per context file in the documented `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md` order whose value renders `on|off • <chars>c/<tokens>t` measured size facts plus the context-occupancy suffix computed from the enabled existing token total against the selected model max input context, followed by a value-less subtree-local `Reset defaults` row. Cycle values embed the same measured facts and occupancy suffix so inline toggling keeps the size estimate visible while persisting the on|off state. Runtime is O(1) in row count. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] sizes {Record<ContextFileName, ContextFileSizeFacts>} Measured context-file size facts keyed by canonical file name.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens; undefined selects the documented 1,000,000-token fallback.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered `Context Files` submenu choices.
- * @satisfies REQ-327, REQ-328, REQ-333, REQ-375
+ * @satisfies REQ-327, REQ-328, REQ-333, REQ-375, REQ-403, REQ-404, REQ-406
  */
 function buildContextFilesMenuChoices(
   config: UseReqConfig,
   sizes: Record<ContextFileName, ContextFileSizeFacts>,
+  maxContextTokens?: number | undefined,
 ): PiUsereqSettingsMenuChoice[] {
+  const totalTokens = sumEnabledContextFileTokens(config, sizes);
+  const occupancySuffix = totalTokens > 0
+    ? ` ${computeContextOccupancyFacts(totalTokens, maxContextTokens).suffix}`
+    : "";
   const buildRow = (
     id: "context-files-requirements" | "context-files-references" | "context-files-workflow",
     fileName: ContextFileName,
     description: string,
   ): PiUsereqSettingsMenuChoice => {
-    const sizedOn = `on \u2022 ${formatContextFileSize(sizes[fileName])}`;
-    const sizedOff = `off \u2022 ${formatContextFileSize(sizes[fileName])}`;
+    const sizedOn = `on \u2022 ${formatContextFileSize(sizes[fileName])}${occupancySuffix}`;
+    const sizedOff = `off \u2022 ${formatContextFileSize(sizes[fileName])}${occupancySuffix}`;
     return {
       id,
       label: fileName,
@@ -4619,13 +4637,15 @@ function buildContextFilesMenuChoices(
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable effective project configuration.
  * @param[in] onConfigChange {() => void} Shared persistence-plus-status callback.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens used by the submenu occupancy suffix; undefined selects the documented 1,000,000-token fallback.
  * @return {Promise<void>} Promise resolved when the submenu closes.
- * @satisfies REQ-327, REQ-328, REQ-333
+ * @satisfies REQ-327, REQ-328, REQ-333, REQ-406
  */
 async function configureContextFilesMenu(
   ctx: ExtensionCommandContext,
   config: UseReqConfig,
   onConfigChange: () => void,
+  maxContextTokens?: number | undefined,
 ): Promise<void> {
   const contextFileSizes = measureContextFileSizes(getProjectBase(ctx.cwd), config);
   const setFlag = (flagKey: "context-files-requirements" | "context-files-references" | "context-files-workflow", enabled: boolean): void => {
@@ -4635,9 +4655,9 @@ async function configureContextFilesMenu(
   };
   let focusedChoiceId: string | undefined;
   while (true) {
-    const choice = await showPiUsereqSettingsMenu(ctx, "Context Files", buildContextFilesMenuChoices(config, contextFileSizes), {
+    const choice = await showPiUsereqSettingsMenu(ctx, "Context Files", buildContextFilesMenuChoices(config, contextFileSizes, maxContextTokens), {
       initialSelectedId: focusedChoiceId,
-      getChoices: () => buildContextFilesMenuChoices(config, contextFileSizes),
+      getChoices: () => buildContextFilesMenuChoices(config, contextFileSizes, maxContextTokens),
       onChange: (choiceId, newValue) => {
         if (choiceId === "context-files-requirements") {
           setFlag("context-files-requirements", newValue.startsWith("on"));
@@ -4688,12 +4708,14 @@ async function configureContextFilesMenu(
  * @details Serializes primary configuration actions into right-valued menu rows consumed by the shared settings-menu renderer, including the `Context Files` injection toggles, automatic git-commit mode, effective prompt-command worktree state, notification summary, debug summary, locked worktree rows when automatic git commit is disabled, and display-only local plus global config paths. Runtime is O(s) in source-directory count. No external state is mutated.
  * @param[in] cwd {string} Current working directory.
  * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens used by the `Context Files` occupancy suffix; undefined selects the documented 1,000,000-token fallback.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered top-level menu choices.
- * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-314, REQ-318, REQ-319, REQ-320, REQ-326, REQ-376
+ * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-314, REQ-318, REQ-319, REQ-320, REQ-326, REQ-376, REQ-405
  */
 function buildPiUsereqMenuChoices(
   cwd: string,
   config: UseReqConfig,
+  maxContextTokens?: number | undefined,
 ): PiUsereqSettingsMenuChoice[] {
   const autoGitCommitDisabled = config.AUTO_GIT_COMMIT === "disable";
   const effectiveGitWorktreeEnabled = resolveEffectiveGitWorktreeEnabled(
@@ -4722,7 +4744,7 @@ function buildPiUsereqMenuChoices(
     {
       id: "context-files",
       label: "Context Files",
-      value: formatContextFilesSummary(config, measureContextFileSizes(cwd, config)),
+      value: formatContextFilesSummary(config, measureContextFileSizes(cwd, config), maxContextTokens),
       description: "Toggle injection of REQUIREMENTS.md, REFERENCES.md, and WORKFLOW.md into prompt context through `%%CONTEXT_FILES%%`.",
     },
     {
@@ -4865,6 +4887,7 @@ async function configurePiUsereq(
   });
   let config = loadProjectConfig(ctx.cwd);
   const projectBase = getProjectBase(ctx.cwd);
+  const maxContextTokens = resolveModelContextWindowTokens(statusController.state.contextUsage);
   const initialShortcut = config["notify-sound-toggle-shortcut"];
   const persistConfigChange = () => {
     Object.assign(config, normalizeConfigPaths(projectBase, config));
@@ -4878,10 +4901,10 @@ async function configurePiUsereq(
     const choice = await showPiUsereqSettingsMenu(
       ctx,
       "pi-usereq",
-      buildPiUsereqMenuChoices(ctx.cwd, config),
+      buildPiUsereqMenuChoices(ctx.cwd, config, maxContextTokens),
       {
         initialSelectedId: focusedChoiceId,
-        getChoices: () => buildPiUsereqMenuChoices(ctx.cwd, config),
+        getChoices: () => buildPiUsereqMenuChoices(ctx.cwd, config, maxContextTokens),
         onChange: (choiceId, newValue) => {
           if (choiceId === "auto-git-commit") {
             config.AUTO_GIT_COMMIT = newValue === "enable" ? "enable" : "disable";
@@ -4934,7 +4957,7 @@ async function configurePiUsereq(
       continue;
     }
     if (choice === "context-files") {
-      await configureContextFilesMenu(ctx, config, persistConfigChange);
+      await configureContextFilesMenu(ctx, config, persistConfigChange, maxContextTokens);
       continue;
     }
     if (choice === "auto-git-commit") {
@@ -5079,7 +5102,7 @@ async function configurePiUsereq(
           { label: "Document directory", previousValue: config["docs-dir"], nextValue: defaultConfig["docs-dir"] },
           { label: "Source-code directories", previousValue: config["src-dir"].join(", "), nextValue: defaultConfig["src-dir"].join(", ") },
           { label: "Unit tests directory", previousValue: config["tests-dir"], nextValue: defaultConfig["tests-dir"] },
-          { label: "Context Files", previousValue: formatContextFilesSummary(config, measureContextFileSizes(ctx.cwd, config)), nextValue: formatContextFilesSummary(defaultConfig, measureContextFileSizes(ctx.cwd, defaultConfig)) },
+          { label: "Context Files", previousValue: formatContextFilesSummary(config, measureContextFileSizes(ctx.cwd, config), maxContextTokens), nextValue: formatContextFilesSummary(defaultConfig, measureContextFileSizes(ctx.cwd, defaultConfig), maxContextTokens) },
           { label: "Auto git commit", previousValue: config.AUTO_GIT_COMMIT, nextValue: defaultConfig.AUTO_GIT_COMMIT },
           { label: "Git worktree", previousValue: config.GIT_WORKTREE_ENABLED, nextValue: defaultConfig.GIT_WORKTREE_ENABLED },
           { label: "Worktree prefix", previousValue: config.GIT_WORKTREE_PREFIX, nextValue: defaultConfig.GIT_WORKTREE_PREFIX },

package/src/resources/pi-prompts-version.txt

@@ -0,0 +1 @@
+v0.8.0