bigpowers 2.87.4 → 2.87.6

package/.cursor/rules/hook-commits.mdc

@@ -0,0 +1,93 @@
+---
+description: "Set up pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing."
+alwaysApply: false
+---
+
+# Hook Commits
+> **HARD GATE** — **HARD GATE** — Pre-commit and commit-msg hooks must run before any commit lands. Skipping hooks (`--no-verify`) is forbidden unless explicitly authorized for a specific commit and documented.
+
+
+## What This Sets Up
+
+- **Husky** pre-commit hook
+- **lint-staged** running Prettier on all staged files
+- **Prettier** config (if missing)
+- **typecheck** and **test** scripts in the pre-commit hook
+
+## Steps
+
+### 1. Detect package manager
+
+Check for `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `bun.lockb` (bun). Use whichever is present. Default to npm if unclear.
+
+### 2. Install dependencies
+
+Install as devDependencies:
+
+```
+husky lint-staged prettier
+```
+
+### 3. Initialize Husky
+
+```bash
+npx husky init
+```
+
+This creates `.husky/` dir and adds `prepare: "husky"` to package.json.
+
+### 4. Create `.husky/pre-commit`
+
+Write this file (no shebang needed for Husky v9+):
+
+```
+npx lint-staged
+npm run typecheck
+npm run test
+```
+
+**Adapt**: Replace `npm` with detected package manager. If repo has no `typecheck` or `test` script in package.json, omit those lines and tell the user.
+
+### 5. Create `.lintstagedrc`
+
+```json
+{
+  "*": "prettier --ignore-unknown --write"
+}
+```
+
+### 6. Create `.prettierrc` (if missing)
+
+Only create if no Prettier config exists. Use these defaults:
+
+```json
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "printWidth": 80,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "semi": true,
+  "arrowParens": "always"
+}
+```
+
+### 7. Verify
+
+- [ ] `.husky/pre-commit` exists and is executable
+- [ ] `.lintstagedrc` exists
+- [ ] `prepare` script in package.json is `"husky"`
+- [ ] `prettier` config exists
+- [ ] Run `npx lint-staged` to verify it works
+
+### 8. Commit
+
+Stage all changed/created files and commit with message: `chore: add pre-commit hooks (husky + lint-staged + prettier)`
+
+This will run through the new pre-commit hooks — a good smoke test that everything works.
+
+## Notes
+
+- Husky v9+ doesn't need shebangs in hook files
+- `prettier --ignore-unknown` skips files Prettier can't parse (images, etc.)
+- The pre-commit runs lint-staged first (fast, staged-only), then full typecheck and tests

package/.cursor/rules/inspect-quality.mdc

@@ -0,0 +1,105 @@
+---
+description: "Interactive QA session where user reports bugs or issues conversationally, and the agent logs them to specs/bugs/registry.yaml with a structured audit schema. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, or mentions \"QA session\"."
+alwaysApply: false
+---
+
+# Inspect Quality
+> **HARD GATE** — **HARD GATE** — Quality metrics (coverage, lint, cyclomatic complexity, security scans) must be monitored. If a metric degrades, surface it as a blocker. Do NOT accept regressions.
+
+
+Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and log each issue to `specs/bugs/registry.yaml` with a structured, durable format.
+
+## For each issue the user raises
+
+### 1. Listen and lightly clarify
+
+Let the user describe the problem in their own words. Ask **at most 2–3 short clarifying questions** focused on:
+
+- What they expected vs what actually happened
+- Steps to reproduce (if not obvious)
+- Whether it's consistent or intermittent
+
+Do NOT over-interview. If the description is clear enough to log, move on.
+
+### 2. Explore the codebase in the background
+
+Kick off an Agent (subagent_type=Explore) to understand the relevant area. The goal is NOT to find a fix — it's to:
+
+- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if present)
+- Understand what the feature is supposed to do
+- Identify the user-facing behavior boundary
+
+### 3. Assess scope: single issue or breakdown?
+
+Break down when:
+
+- The fix spans multiple independent areas
+- There are clearly separable concerns that could be worked on in parallel
+- The user describes something with multiple distinct failure modes
+
+Keep as a single issue when:
+
+- It's one behavior that's wrong in one place
+- The symptoms are all caused by the same root behavior
+
+### 4. Log to specs/bugs/registry.yaml
+
+Append the issue to `specs/bugs/registry.yaml`. Create the `specs/bugs/` directory if it doesn't exist.
+
+#### registry.yaml format
+
+The file maintains a Markdown table with the following columns (derived from structured audit practice):
+
+| Field | Description |
+|-------|-------------|
+| `bug_id` | `BUG-YYYY-MM-DDTHHMMSS` |
+| `date` | `YYYY-MM-DD` |
+| `severity` | `critical` / `high` / `medium` / `low` |
+| `priority` | `p0` / `p1` / `p2` / `p3` |
+| `scope` | kebab-case area (e.g. `auth`, `checkout`) |
+| `what_happened` | actual behavior (user-facing terms) |
+| `what_expected` | expected behavior |
+| `steps_to_reproduce` | numbered steps |
+| `root_cause` | one-line hypothesis |
+| `files_changed` | filled in after fix |
+| `approach` | filled in after fix |
+| `risk_level` | `low` / `medium` / `high` |
+| `new_tests` | count (filled in after fix) |
+| `type_check` | `pass` / `fail` (filled in after fix) |
+| `lint` | `pass` / `fail` (filled in after fix) |
+| `commit_type` | `fix` / `fix!` / `feat` (filled in after fix) |
+| `release_type` | `patch` / `minor` / `major` (filled in after fix) |
+| `commit_message` | Conventional Commits message (filled in after fix) |
+| `follow_ups` | semicolon-separated follow-up items |
+| `file` | path to detailed `specs/bugs/BUG-*.md` (filled in by investigate-bug) |
+| `status` | `open` / `in-progress` / `fixed` / `wont-fix` |
+
+When a bug is fixed (via `validate-fix`), update the relevant row with the resolution fields.
+
+#### Issue body (for context below the table)
+
+For each bug, also append a detail section:
+
+```markdown
+### BUG-YYYY-MM-DDTHHMMSS: [short title]
+
+**What happened:** [actual behavior, plain language]
+**What I expected:** [expected behavior]
+**Steps to reproduce:**
+1. [Step 1]
+2. [Step 2]
+
+**Additional context:** [domain-language observations, no file paths]
+```
+
+#### Rules for all entries
+
+- **bug_id** uses full timestamp: `BUG-YYYY-MM-DDTHHMMSS` — matches the individual bug file name in `specs/bugs/`
+- **No file paths or line numbers** — these go stale
+- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if it exists)
+- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws"
+- **Reproduction steps are mandatory** — if you can't determine them, ask the user
+
+### 5. Continue the session
+
+After logging, ask: "Next issue, or are we done?" Keep going until the user says done. Each issue is independent — don't batch them.

package/.cursor/rules/investigate-bug.mdc

@@ -0,0 +1,126 @@
+---
+description: "Investigate a bug or issue by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, mentions \"triage\", or wants to plan a fix."
+alwaysApply: false
+---
+
+# Investigate Bug
+
+**Boundary**: End-to-end bug entry point — history check → RCA (via `diagnose-root`) → fix approach → TDD plan → bug file. Delegates the 4-phase RCA to `diagnose-root`; does not re-implement it.
+
+Investigate a reported problem, find its root cause, and write a TDD fix plan to `specs/bugs/BUG-*.md`. This is a mostly hands-off workflow — minimize questions to the user.
+
+## Process
+
+### 0. Read previous bug history
+
+Before starting diagnosis:
+
+1. Read `specs/bugs/registry.yaml` (if it exists) — check for prior bugs in the same `scope` or with similar symptoms.
+2. If a relevant prior bug is found, read the corresponding `specs/bugs/BUG-*.md` file to understand previous root cause analysis and fix approach.
+3. Note in your investigation whether this is a recurrence, a related issue, or novel.
+
+### 1. Capture the problem
+
+Get a brief description of the issue from the user. If they haven't provided one, ask ONE question: "What's the problem you're seeing?"
+
+Do NOT ask follow-up questions yet. Start investigating immediately.
+
+> **Security-impact assessment** — After capturing the problem, assess and document: `Security impact: NONE / LOW / MEDIUM / HIGH / CRITICAL`. If HIGH or CRITICAL, assign bug severity HIGH and document the exploit path in findings. If MEDIUM+, include exploit path in the bug file. Document "no security exploit path identified" for NONE/LOW.
+
+### 2. Explore and diagnose (4-phase RCA)
+
+Run the 4-phase root-cause analysis via the `diagnose-root` skill (Reproduce → Isolate → Hypothesize → Verify). That skill is the canonical RCA engine — do not re-implement the phases here.
+
+Also look at:
+- Recent changes to affected files (`git log --oneline <file>`)
+- Existing tests (what's tested, what's missing)
+- Similar patterns elsewhere in the codebase that work correctly
+
+> **HARD GATE** — Do NOT proceed to Step 3 (Fix Approach) until `diagnose-root` Phase 4 produces a verified root cause. "It probably is X" is not verified.
+
+### 3. Identify the fix approach
+
+Based on your investigation, determine:
+
+- The minimal change needed to fix the root cause
+- Which modules/interfaces are affected
+- What behaviors need to be verified via tests
+- Whether this is a regression, missing feature, or design flaw
+- Risk level: Low / Medium / High
+
+### 4. Design TDD fix plan
+
+Create a concrete, ordered list of RED-GREEN cycles. Each cycle is one vertical slice:
+
+- **RED**: Describe a specific test that captures the broken/missing behavior
+- **GREEN**: Describe the minimal code change to make that test pass
+
+Rules:
+- Tests verify behavior through public interfaces, not implementation details
+- One test at a time, vertical slices (NOT all tests first, then all code)
+- Each test should survive internal refactors
+- Include a final refactor step if needed
+- **Durability**: Only suggest fixes that would survive radical codebase changes. Tests assert on observable outcomes (API responses, UI state, user-visible effects), not internal state.
+
+### 5. Write the bug file
+
+Save the investigation and fix plan to `specs/bugs/BUG-NNN-slug.md`. Create the `specs/bugs/` directory if it doesn't exist.
+
+After writing, append a row to `specs/bugs/registry.yaml` with: bug_id (same timestamp), date, severity, priority, scope, summary, and file path. Create `specs/bugs/registry.yaml` if it doesn't exist.
+
+<diagnosis-template>
+
+# BUG-YYYY-MM-DDTHHMMSS: [short title]
+
+## Problem
+
+A clear description of the bug or issue, including:
+- What happens (actual behavior)
+- What should happen (expected behavior)
+- How to reproduce (if applicable)
+
+## Root Cause Analysis
+
+Describe what you found during investigation:
+- The code path involved
+- Why the current code fails
+- Any contributing factors
+- Risk level: Low / Medium / High
+
+Do NOT include specific file paths, line numbers, or implementation details that couple to current code layout. Describe modules, behaviors, and contracts instead.
+
+## TDD Fix Plan
+
+A numbered list of RED-GREEN cycles:
+
+1. **RED**: Write a test that [describes expected behavior]
+   **GREEN**: [Minimal change to make it pass]
+   **verify**: [runnable command]
+
+2. **RED**: Write a test that [describes next behavior]
+   **GREEN**: [Minimal change to make it pass]
+   **verify**: [runnable command]
+
+**REFACTOR**: [Any cleanup needed after all tests pass]
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] All new tests pass
+- [ ] Existing tests still pass
+
+## Resolution
+
+<!-- filled in by validate-fix -->
+
+</diagnosis-template>
+
+After writing the bug file, print a one-line summary of the root cause and suggest running `kickoff-branch` next to create a fix branch.
+
+## References
+
+<!-- story: e35s10 -->
+
+- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm
+- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating

package/.cursor/rules/kickoff-branch.mdc

@@ -0,0 +1,142 @@
+---
+description: "Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions \"start a branch\" or \"new worktree\"."
+alwaysApply: false
+---
+
+# story: e51s03
+# story: e20s03
+
+
+# Kickoff Branch
+
+> **HARD GATE** — Direct work on `main` or `master` is PROHIBITED. Every task MUST start with this skill to create a feature branch or worktree.
+>
+> **HARD GATE** — Do NOT proceed with development until **Preflight** passes on the default branch. Red Preflight blocks branch creation and all forward work — invoke `quick-fix` or `fix-bug` per CONVENTIONS § Discovered Defects.
+
+Create an isolated working environment before touching any code. **Preflight must be green** before you write feature code — solo-default owns the whole tree, not just the current task diff.
+
+## Process
+
+### 1. Confirm task name
+
+Ask if not already known: "What's the name of this feature or task?" Use it as the branch name slug (kebab-case, max 40 chars).
+
+### 2. Anchor on default branch (main or master)
+
+> **HARD GATE** — Kickoff MUST start from an updated, clean default branch in the **primary** repository root (not a linked worktree).
+
+```bash
+# Detect default branch
+DEFAULT=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
+
+git checkout "$DEFAULT"
+git pull --ff-only origin "$DEFAULT"   # skip if no remote
+git status                             # working tree MUST be clean
+git log --oneline -5
+```
+
+**Spec-only pre-kickoff** — before enforcing the clean-tree gate, check whether dirty files are spec artifacts:
+
+```bash
+DIRTY=$(git status --porcelain | awk '{print $2}')
+NON_SPEC=$(echo "$DIRTY" | grep -v '^specs/' || true)
+
+if [ -z "$DIRTY" ]; then
+  : # clean — proceed
+elif [ -z "$NON_SPEC" ]; then
+  # spec-only dirty tree — offer auto-commit
+  echo "Dirty spec artifacts: $(echo $DIRTY | tr '\n' ' ')"
+  read -p "Commit spec artifacts before kickoff? [Y/n]: " CONFIRM
+  CONFIRM=${CONFIRM:-Y}
+  if [[ "$CONFIRM" =~ ^[Yy] ]]; then
+    git add specs/
+    git commit -m "chore(state): checkpoint before kickoff"
+  fi
+else
+  echo "Dirty tree: $NON_SPEC (not a spec artifact). Stash or commit before proceeding."
+  exit 1
+fi
+```
+
+- **Spec artifacts** match `specs/` — state.yaml, epics YAMLs, execution-status.yaml, etc.
+- **Non-spec dirty files** (src/, scripts/, SKILL.md, …) still enforce the full clean-tree gate.
+- If not on `$DEFAULT` after checkout, stop and fix before continuing.
+
+### 3. Pre-flight & Conflict Resolution
+
+Before creating the worktree, verify the target environment is clean:
+
+```bash
+# 1. Check for existing directory
+ls -d ../<task-slug> 2>/dev/null
+
+# 2. Check for existing branch
+git branch --list <task-slug>
+
+# 3. Check for "ghost" worktrees (metadata exists but directory is gone)
+git worktree list | grep "<task-slug>"
+```
+
+**Handling Conflicts:**
+- **Directory exists:** If `../<task-slug>` already exists, ask the user if they want to use it or delete it.
+- **Branch exists:** If the branch exists but no worktree is attached, ask to use the existing branch (`git worktree add ../<task-slug> <task-slug>`) or delete it.
+- **Ghost worktree:** If `git worktree list` shows the path but the directory is missing, run `git worktree prune` to clear the stale metadata. `bash scripts/cleanup-worktrees.sh` does this plus reports any worktree whose branch is already merged or deleted — advisory only, it prints the `git worktree remove`/`git branch -d` commands rather than running them, so review before acting.
+
+### 4. Create worktree + branch
+
+```bash
+# From the main repo root (not another worktree)
+git worktree add ../<task-slug> -b <task-slug>
+cd ../<task-slug>
+```
+
+If the user prefers a branch without a worktree:
+```bash
+git checkout -b <task-slug>
+```
+
+### 4. Verify clean baseline
+
+> **HARD GATE (e39s02):** Acquire story lock in `specs/agent-locks.yaml` before running tests.
+
+```bash
+LOCK="specs/agent-locks.yaml"; STORY="<story-id>"
+if [ -f "$LOCK" ]; then
+  python3 -c "
+import yaml,sys,datetime
+d=yaml.safe_load(open('$LOCK'))or{'locks':[]}
+for l in d['locks']:
+  if l['story_id']=='$STORY':print(f'LOCKED by {l[\"locked_by\"]} at {l[\"locked_at\"]}');sys.exit(1)
+d['locks'].append({'story_id':'$STORY','locked_by':'agent: build-epic','locked_at':datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),'files_touched':[]})
+yaml.dump(d,open('$LOCK','w'),default_flow_style=False)
+print(f'LOCK ACQUIRED: $STORY')
+"
+fi
+```
+
+If locked: abort. If unlocked: entry added, proceed.
+
+Run **Preflight** (from `CLAUDE.md` Commands table, or `BP_PREFLIGHT` from `bash scripts/bp-read-agents.sh`) and confirm green before writing any code:
+
+```bash
+# Preflight — project's full local verification stack
+# bigpowers example:
+npm run compliance && bash scripts/run-verification-gates.sh
+
+# Or project-specific from CLAUDE.md / AGENTS.md
+```
+
+- [ ] Preflight passes (all chained gates green)
+- [ ] No type errors (`npm run typecheck` or equivalent, if not in Preflight)
+- [ ] No lint errors (`npm run lint` or equivalent, if not in Preflight)
+
+If Preflight is red, **stop** — route to `quick-fix` or `fix-bug`. Fix before kickoff continues.
+
+### 5. Confirm readiness
+
+Report: `✓ Preflight green` + branch + worktree. Suggest next: `develop-tdd` or `execute-plan`.
+
+## Handoff
+
+Gate: READY -> next: develop-tdd
+Writes: state.yaml handoff.next_skill = develop-tdd

package/.cursor/rules/maintain-wiki.mdc

@@ -0,0 +1,63 @@
+---
+description: "Agent-maintained OKF wiki — INGEST source docs, LINT for issues, QUERY across concept pages. Run as part of build-epic Step 8 and verify-work Phase 3."
+alwaysApply: false
+---
+
+# Maintain Wiki
+
+Three operations for keeping the OKF wiki bundle consistent with its source docs.
+
+## INGEST
+
+Read source doc (CLAUDE.md, CONVENTIONS.md, or SKILL.md) and write/update OKF concept pages:
+
+```bash
+# Regenerate skills-wiki from SKILL.md files
+bash scripts/sync-skills.sh --okf
+
+# Regenerate conventions-wiki from CONVENTIONS.md
+bash scripts/decompose-conventions.sh
+
+# Regenerate agent-guide from CLAUDE.md
+bash scripts/generate-agent-guide.sh
+```
+
+## LINT
+
+Check for common OKF issues:
+
+1. **Stale concepts** — source file mtime vs concept page mtime. If source is newer, concept is stale.
+2. **Orphan concepts** — concept page exists but source doc section no longer exists.
+3. **Missing cross-references** — skill concept pages with no `enforced_by` or `references` links.
+4. **Contradictions** — two concept pages that make opposite claims about the same topic.
+5. **Broken links** — internal OKF links that point to non-existent concept pages.
+
+```bash
+# Quick stale check: compare source vs concept mtimes
+for page in specs/skills-wiki/skills/*.md; do
+  skill=$(basename "$page" .md)
+  source="skills/$skill/SKILL.md"
+  if [ -f "$source" ] && [ "$page" -ot "$source" ]; then
+    echo "STALE: $skill (SKILL.md newer than concept page)"
+  fi
+done
+```
+
+## QUERY
+
+Search across OKF concept pages to answer questions:
+
+```bash
+# Find all concepts about a topic
+grep -rl "topic" specs/skills-wiki/ specs/conventions-wiki/ specs/agent-guide/
+
+# Trace a convention → enforcing skills
+grep -A1 "enforced_by" specs/conventions-wiki/*.md
+
+# Find skill by description keyword
+grep -ril "keyword" specs/skills-wiki/skills/*.md
+```
+
+## Verify
+
+→ verify: `test -d specs/skills-wiki && test -d specs/conventions-wiki && test -d specs/agent-guide`

package/.cursor/rules/map-codebase.mdc

@@ -0,0 +1,70 @@
+---
+description: "Derives the tech-stack doc from scratch by scanning the codebase — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists findings into specs/tech-architecture/tech-stack.md. Run when the tech doc doesn't exist yet; use survey-context to consume it once it does."
+alwaysApply: false
+---
+
+# Map Codebase
+
+Perform a deep architectural and structural analysis of the codebase. Unlike `survey-context` which identifies "where we are", `map-codebase` identifies "what we are dealing with" and "how things are done".
+
+> **Use this vs survey-context:** `map-codebase` BUILDS the tech-stack doc by scanning the codebase from scratch. `survey-context` READS existing specs/tech-architecture docs without re-deriving them. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
+
+> **HARD GATE** — Cold analysis only. Do NOT assume architectural patterns without reading the code. If the codebase structure surprises you, call out the delta.
+
+## Process
+
+### 1. Identify Core Stack & Dependencies
+- Scan `package.json`, `Cargo.toml`, `requirements.txt`, etc.
+- Identify primary framework, runtime, and critical libraries (ORM, Auth, State, UI).
+- Note version constraints and any deprecated or unusual dependencies.
+
+### 2. Map High-Level Architecture
+- Identify the entry points (CLI, Web, API).
+- Map the primary data flow (e.g., Controller → Service → Repository).
+- Identify where business logic lives vs. where I/O lives.
+- Look for established patterns (e.g., hexagonal, layered, feature-folders).
+
+### 3. Analyze "Gray Areas" (The "How")
+Search for patterns and anti-patterns in these categories:
+- **Error Handling:** Are exceptions caught early or bubbled? Is there a global error handler? Are error messages structured?
+- **API Shapes:** Is it REST, GraphQL, or RPC? What is the casing (camelCase, snake_case)? How are responses structured?
+- **Type Safety:** Is it strictly typed? Are there many `any` or `unsafe` blocks? Are interfaces used for DIP?
+- **Observability:** Is there structured logging? Are there health checks? Where do logs go?
+- **Testing:** What is the test coverage strategy? Are mocks used? Where do tests live?
+
+### 4. Identify Planning "Signals"
+Look for signals that will influence upcoming plans:
+- **Consistency Gaps:** "Half the project uses async/await, the other half uses Promises."
+- **Debt Hotspots:** "The `AuthManager` is 1500 lines and handles both JWT and session logic."
+- **Integration Points:** "We need to talk to the Stripe API, but there's no wrapper yet."
+- **Conventions:** "The team always uses functional components over classes."
+
+### 5. Persist to specs/tech-architecture/tech-stack.md
+Compile all findings into `specs/tech-architecture/tech-stack.md`. This file serves as the project's "Long-Term Memory".
+
+```markdown
+# Project Context
+
+## Stack
+- [Framework/Language]
+- [Key Libraries]
+
+## Architecture
+- [Pattern Description]
+- [Data Flow]
+
+## Conventions (Observed)
+- [Error Handling Pattern]
+- [API Design]
+- [Type System]
+
+## Signals / Active Considerations
+- [Gap 1]
+- [Hotspot 2]
+```
+
+## When to Use
+- When first joining a project.
+- Before a major refactor or architectural change.
+- When `survey-context` reveals a lack of domain knowledge.
+- To refresh `specs/tech-architecture/tech-stack.md` after significant changes.