pi-usereq 0.63.0 → 0.65.0

package/scripts/pi-prompts-update.sh

@@ -0,0 +1,338 @@
+#!/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`. 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
+
+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 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
+##     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 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,
+##     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, 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")" \
+    || 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}")"
+
+  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}"
+
+  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
+
+  printf '%s\n' "${release_version}" > "${REPO_ROOT}/${PROMPTS_VERSION_REL}"
+
+  log "Bundled prompt resources updated to ${release_version}."
+}
+
+trap cleanup EXIT
+main "$@"

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,