From 9ffbd7fe691072e0d4fd0dc648777c1a30466c24 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 25 Sep 2026 11:15:09 +0000
Subject: [PATCH 1/2] Apply the prompt-audit fixes to CLAUDE.md, the
 constitution and speckit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 2026-09 prompt audit found factual rot rather than dated prompting in
CLAUDE.md, three constitution rules that the codebase had outgrown, and
model-dated text in the vendored spec-kit 0.4.2 commands. This applies
the High and Medium findings; the flagged items are left as they were.

CLAUDE.md
- The file list said every path exists and was missing pointerScope.js
  and SymbolSizeTrial.js; both are added from their own headers
- "Recent Changes" still called the 167/166 work "Planned" while the
  file above it described that work as done; the section now holds the
  three most recent entries the template asks for
- Fifteen near-duplicate "Active Technologies" lines become the two facts
  they carried, spelled exactly as the plan template now states them
- Four lines that described a previous version of the code ("is gone",
  "at first", "since spec 167") keep their reason and drop the history

Constitution (1.0.0 → 1.0.1, corrections of fact)
- Principle III named three of the five modes; Pan and Sidebands were
  missing, and /speckit.analyze grades any conflict as CRITICAL
- Principle IV forbade the <audio> first row that spec 168 introduced
- Quality Gates listed three of the eleven checks CI runs

Speckit commands and templates
- The plan template states the repository's constants in Technical
  Context and its real tree in Source Code, instead of generic
  placeholders and a three-option menu every plan had to prune
- The bold-caps opener, a CRITICAL table-formatting block, a forty-line
  ignore-file lookup table, a rule stated five times in the checklist
  command, an implementation choreography that contradicted the tasks
  template, and a research fan-out per technology are rewritten as plain
  statements of the goal
- The extension-hook blocks (~280 lines, gated on a .specify/extensions.yml
  this repository does not have) are removed from the four commands that
  carried them

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HVGXdCBws4z1ut7BSfD4eE
---
 .claude/commands/speckit.analyze.md       |   3 +-
 .claude/commands/speckit.checklist.md     |  41 +------
 .claude/commands/speckit.clarify.md       |   2 +-
 .claude/commands/speckit.constitution.md  |   2 +-
 .claude/commands/speckit.implement.md     | 135 ++--------------------
 .claude/commands/speckit.plan.md          |  77 +-----------
 .claude/commands/speckit.specify.md       |  80 +------------
 .claude/commands/speckit.tasks.md         |  67 +----------
 .claude/commands/speckit.taskstoissues.md |   2 +-
 .specify/memory/constitution.md           |  37 ++++--
 .specify/templates/plan-template.md       |  76 +++++-------
 .specify/templates/tasks-template.md      |   4 +-
 CLAUDE.md                                 |  55 ++++-----
 13 files changed, 110 insertions(+), 471 deletions(-)

diff --git a/.claude/commands/speckit.analyze.md b/.claude/commands/speckit.analyze.md
index 0c71cf32..1f8c12c4 100644
--- a/.claude/commands/speckit.analyze.md
+++ b/.claude/commands/speckit.analyze.md
@@ -8,7 +8,7 @@ description: Perform a non-destructive cross-artifact consistency and quality an
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
+The user's input above, when present, shapes everything that follows.
 
 ## Goal
 
@@ -173,7 +173,6 @@ Ask the user: "Would you like me to suggest concrete remediation edits for the t
 
 ### Analysis Guidelines
 
-- **NEVER modify files** (this is read-only analysis)
 - **NEVER hallucinate missing sections** (if absent, report them accurately)
 - **Prioritize constitution violations** (these are always CRITICAL)
 - **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
diff --git a/.claude/commands/speckit.checklist.md b/.claude/commands/speckit.checklist.md
index b7624e22..a3e6723a 100644
--- a/.claude/commands/speckit.checklist.md
+++ b/.claude/commands/speckit.checklist.md
@@ -29,7 +29,7 @@ description: Generate a custom checklist for the current feature based on user r
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
+The user's input above, when present, shapes everything that follows.
 
 ## Execution Steps
 
@@ -188,14 +188,6 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Merge near-duplicates checking the same requirement aspect
    - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
 
-   **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
-   - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
-   - ❌ References to code execution, user actions, system behavior
-   - ❌ "Displays correctly", "works properly", "functions as expected"
-   - ❌ "Click", "navigate", "render", "load", "execute"
-   - ❌ Test cases, test plans, QA procedures
-   - ❌ Implementation details (frameworks, APIs, algorithms)
-
    **✅ REQUIRED PATTERNS** - These test requirements quality:
    - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
    - ✅ "Is [vague term] quantified/clarified with specific criteria?"
@@ -262,34 +254,3 @@ Sample items:
 - "Is the threat model documented and requirements aligned to it? [Traceability]"
 - "Are security requirements consistent with compliance obligations? [Consistency]"
 - "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
-
-## Anti-Examples: What NOT To Do
-
-**❌ WRONG - These test implementation, not requirements:**
-
-```markdown
-- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
-- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
-- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
-- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
-```
-
-**✅ CORRECT - These test requirements quality:**
-
-```markdown
-- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
-- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
-- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
-- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
-- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
-- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
-```
-
-**Key Differences:**
-
-- Wrong: Tests if the system works correctly
-- Correct: Tests if the requirements are written correctly
-- Wrong: Verification of behavior
-- Correct: Validation of requirement quality
-- Wrong: "Does it do X?"
-- Correct: "Is X clearly specified?"
diff --git a/.claude/commands/speckit.clarify.md b/.claude/commands/speckit.clarify.md
index 3f4376a4..8cf6c71c 100644
--- a/.claude/commands/speckit.clarify.md
+++ b/.claude/commands/speckit.clarify.md
@@ -12,7 +12,7 @@ handoffs:
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
+The user's input above, when present, shapes everything that follows.
 
 ## Outline
 
diff --git a/.claude/commands/speckit.constitution.md b/.claude/commands/speckit.constitution.md
index 63d4f662..b56e83e7 100644
--- a/.claude/commands/speckit.constitution.md
+++ b/.claude/commands/speckit.constitution.md
@@ -12,7 +12,7 @@ handoffs:
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
+The user's input above, when present, shapes everything that follows.
 
 ## Outline
 
diff --git a/.claude/commands/speckit.implement.md b/.claude/commands/speckit.implement.md
index 5847f611..78a62945 100644
--- a/.claude/commands/speckit.implement.md
+++ b/.claude/commands/speckit.implement.md
@@ -8,41 +8,7 @@ description: Execute the implementation plan by processing and executing all tas
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Pre-Execution Checks
-
-**Check for extension hooks (before implementation)**:
-- Check if `.specify/extensions.yml` exists in the project root.
-- If it exists, read it and look for entries under the `hooks.before_implement` key
-- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
-- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
-  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
-  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
-- For each executable hook, output the following based on its `optional` flag:
-  - **Optional hook** (`optional: true`):
-    ```
-    ## Extension Hooks
-
-    **Optional Pre-Hook**: {extension}
-    Command: `/{command}`
-    Description: {description}
-
-    Prompt: {prompt}
-    To execute: `/{command}`
-    ```
-  - **Mandatory hook** (`optional: false`):
-    ```
-    ## Extension Hooks
-
-    **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
-    EXECUTE_COMMAND: {command}
-    
-    Wait for the result of the hook command before proceeding to the Outline.
-    ```
-- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+The user's input above, when present, shapes everything that follows.
 
 ## Outline
 
@@ -87,49 +53,10 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **IF EXISTS**: Read research.md for technical decisions and constraints
    - **IF EXISTS**: Read quickstart.md for integration scenarios
 
-4. **Project Setup Verification**:
-   - **REQUIRED**: Create/verify ignore files based on actual project setup:
-
-   **Detection & Creation Logic**:
-   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
-
-     ```sh
-     git rev-parse --git-dir 2>/dev/null
-     ```
-
-   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
-   - Check if .eslintrc* exists → create/verify .eslintignore
-   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
-   - Check if .prettierrc* exists → create/verify .prettierignore
-   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
-   - Check if terraform files (*.tf) exist → create/verify .terraformignore
-   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
-
-   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
-   **If ignore file missing**: Create with full pattern set for detected technology
-
-   **Common Patterns by Technology** (from plan.md tech stack):
-   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
-   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
-   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
-   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
-   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
-   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
-   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
-   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
-   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
-   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
-   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `*.dll`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*`
-   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
-   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
-   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
-
-   **Tool-Specific Patterns**:
-   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
-   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
-   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
-   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
-   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+4. **Ignore files**: Check that the repository's ignore files (`.gitignore`, and any
+   tool-specific ones the plan's tooling uses) cover its build outputs, caches and
+   secrets; add only the patterns that are missing. Do not create ignore files for
+   tools the project does not use.
 
 5. Parse tasks.md structure and extract:
    - **Task phases**: Setup, Tests, Core, Integration, Polish
@@ -137,21 +64,12 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **Task details**: ID, description, file paths, parallel markers [P]
    - **Execution flow**: Order and dependency requirements
 
-6. Execute implementation following the task plan:
-   - **Phase-by-phase execution**: Complete each phase before moving to the next
-   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
-   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
-   - **File-based coordination**: Tasks affecting the same files must run sequentially
-   - **Validation checkpoints**: Verify each phase completion before proceeding
-
-7. Implementation execution rules:
-   - **Setup first**: Initialize project structure, dependencies, configuration
-   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
-   - **Core development**: Implement models, services, CLI commands, endpoints
-   - **Integration work**: Database connections, middleware, logging, external services
-   - **Polish and validation**: Unit tests, performance optimization, documentation
-
-8. Progress tracking and error handling:
+6. Execute the tasks in tasks.md order. Tasks marked [P] may run together; tasks
+   that touch the same file run one after another. Where the task list includes
+   test tasks, write those tests before the code they cover. Verify each phase's
+   checkpoint before starting the next.
+
+7. Progress tracking and error handling:
    - Report progress after each completed task
    - Halt execution if any non-parallel task fails
    - For parallel tasks [P], continue with successful tasks, report failed ones
@@ -159,7 +77,7 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Suggest next steps if implementation cannot proceed
    - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
 
-9. Completion validation:
+8. Completion validation:
    - Verify all required tasks are completed
    - Check that implemented features match the original specification
    - Validate that tests pass and coverage meets requirements
@@ -167,32 +85,3 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Report final status with summary of completed work
 
 Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.
-
-10. **Check for extension hooks**: After completion validation, check if `.specify/extensions.yml` exists in the project root.
-    - If it exists, read it and look for entries under the `hooks.after_implement` key
-    - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-    - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
-    - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
-      - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
-      - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
-    - For each executable hook, output the following based on its `optional` flag:
-      - **Optional hook** (`optional: true`):
-        ```
-        ## Extension Hooks
-
-        **Optional Hook**: {extension}
-        Command: `/{command}`
-        Description: {description}
-
-        Prompt: {prompt}
-        To execute: `/{command}`
-        ```
-      - **Mandatory hook** (`optional: false`):
-        ```
-        ## Extension Hooks
-
-        **Automatic Hook**: {extension}
-        Executing: `/{command}`
-        EXECUTE_COMMAND: {command}
-        ```
-    - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
diff --git a/.claude/commands/speckit.plan.md b/.claude/commands/speckit.plan.md
index e3c0764b..9a6f142e 100644
--- a/.claude/commands/speckit.plan.md
+++ b/.claude/commands/speckit.plan.md
@@ -16,41 +16,7 @@ handoffs:
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Pre-Execution Checks
-
-**Check for extension hooks (before planning)**:
-- Check if `.specify/extensions.yml` exists in the project root.
-- If it exists, read it and look for entries under the `hooks.before_plan` key
-- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
-- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
-  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
-  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
-- For each executable hook, output the following based on its `optional` flag:
-  - **Optional hook** (`optional: true`):
-    ```
-    ## Extension Hooks
-
-    **Optional Pre-Hook**: {extension}
-    Command: `/{command}`
-    Description: {description}
-
-    Prompt: {prompt}
-    To execute: `/{command}`
-    ```
-  - **Mandatory hook** (`optional: false`):
-    ```
-    ## Extension Hooks
-
-    **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
-    EXECUTE_COMMAND: {command}
-
-    Wait for the result of the hook command before proceeding to the Outline.
-    ```
-- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+The user's input above, when present, shapes everything that follows.
 
 ## Outline
 
@@ -69,35 +35,6 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
 
-5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root.
-   - If it exists, read it and look for entries under the `hooks.after_plan` key
-   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
-   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
-     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
-     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
-   - For each executable hook, output the following based on its `optional` flag:
-     - **Optional hook** (`optional: true`):
-       ```
-       ## Extension Hooks
-
-       **Optional Hook**: {extension}
-       Command: `/{command}`
-       Description: {description}
-
-       Prompt: {prompt}
-       To execute: `/{command}`
-       ```
-     - **Mandatory hook** (`optional: false`):
-       ```
-       ## Extension Hooks
-
-       **Automatic Hook**: {extension}
-       Executing: `/{command}`
-       EXECUTE_COMMAND: {command}
-       ```
-   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
-
 ## Phases
 
 ### Phase 0: Outline & Research
@@ -107,14 +44,10 @@ You **MUST** consider the user input before proceeding (if not empty).
    - For each dependency → best practices task
    - For each integration → patterns task
 
-2. **Generate and dispatch research agents**:
-
-   ```text
-   For each unknown in Technical Context:
-     Task: "Research {unknown} for {feature context}"
-   For each technology choice:
-     Task: "Find best practices for {tech} in {domain}"
-   ```
+2. **Resolve each unknown**: research it yourself, or hand it to a sub-agent when
+   the question is independent of the others and large enough to be worth its own
+   context. The stack is fixed (see Technical Context), so a technology the plan
+   merely restates needs no research task.
 
 3. **Consolidate findings** in `research.md` using format:
    - Decision: [what was chosen]
diff --git a/.claude/commands/speckit.specify.md b/.claude/commands/speckit.specify.md
index fbb630ba..04b8763e 100644
--- a/.claude/commands/speckit.specify.md
+++ b/.claude/commands/speckit.specify.md
@@ -16,41 +16,7 @@ handoffs:
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Pre-Execution Checks
-
-**Check for extension hooks (before specification)**:
-- Check if `.specify/extensions.yml` exists in the project root.
-- If it exists, read it and look for entries under the `hooks.before_specify` key
-- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
-- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
-  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
-  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
-- For each executable hook, output the following based on its `optional` flag:
-  - **Optional hook** (`optional: true`):
-    ```
-    ## Extension Hooks
-
-    **Optional Pre-Hook**: {extension}
-    Command: `/{command}`
-    Description: {description}
-
-    Prompt: {prompt}
-    To execute: `/{command}`
-    ```
-  - **Mandatory hook** (`optional: false`):
-    ```
-    ## Extension Hooks
-
-    **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
-    EXECUTE_COMMAND: {command}
-
-    Wait for the result of the hook command before proceeding to the Outline.
-    ```
-- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+The user's input above, when present, shapes everything that follows.
 
 ## Outline
 
@@ -198,50 +164,16 @@ Given that feature description, do this:
            **Your choice**: _[Wait for user response]_
            ```
 
-        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
-           - Use consistent spacing with pipes aligned
-           - Each cell should have spaces around content: `| Content |` not `|Content|`
-           - Header separator must have at least 3 dashes: `|--------|`
-           - Test that the table renders correctly in markdown preview
-        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
-        6. Present all questions together before waiting for responses
-        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
-        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
-        9. Re-run validation after all clarifications are resolved
+        4. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        5. Present all questions together before waiting for responses
+        6. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        7. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        8. Re-run validation after all clarifications are resolved
 
    d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
 
 7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
 
-8. **Check for extension hooks**: After reporting completion, check if `.specify/extensions.yml` exists in the project root.
-   - If it exists, read it and look for entries under the `hooks.after_specify` key
-   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
-   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
-     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
-     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
-   - For each executable hook, output the following based on its `optional` flag:
-     - **Optional hook** (`optional: true`):
-       ```
-       ## Extension Hooks
-
-       **Optional Hook**: {extension}
-       Command: `/{command}`
-       Description: {description}
-
-       Prompt: {prompt}
-       To execute: `/{command}`
-       ```
-     - **Mandatory hook** (`optional: false`):
-       ```
-       ## Extension Hooks
-
-       **Automatic Hook**: {extension}
-       Executing: `/{command}`
-       EXECUTE_COMMAND: {command}
-       ```
-   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
-
 **NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
 
 ## Quick Guidelines
diff --git a/.claude/commands/speckit.tasks.md b/.claude/commands/speckit.tasks.md
index d021892d..3fa175c2 100644
--- a/.claude/commands/speckit.tasks.md
+++ b/.claude/commands/speckit.tasks.md
@@ -17,41 +17,7 @@ handoffs:
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Pre-Execution Checks
-
-**Check for extension hooks (before tasks generation)**:
-- Check if `.specify/extensions.yml` exists in the project root.
-- If it exists, read it and look for entries under the `hooks.before_tasks` key
-- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
-- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
-  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
-  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
-- For each executable hook, output the following based on its `optional` flag:
-  - **Optional hook** (`optional: true`):
-    ```
-    ## Extension Hooks
-
-    **Optional Pre-Hook**: {extension}
-    Command: `/{command}`
-    Description: {description}
-
-    Prompt: {prompt}
-    To execute: `/{command}`
-    ```
-  - **Mandatory hook** (`optional: false`):
-    ```
-    ## Extension Hooks
-
-    **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
-    EXECUTE_COMMAND: {command}
-    
-    Wait for the result of the hook command before proceeding to the Outline.
-    ```
-- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+The user's input above, when present, shapes everything that follows.
 
 ## Outline
 
@@ -94,42 +60,13 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Suggested MVP scope (typically just User Story 1)
    - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
 
-6. **Check for extension hooks**: After tasks.md is generated, check if `.specify/extensions.yml` exists in the project root.
-   - If it exists, read it and look for entries under the `hooks.after_tasks` key
-   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-   - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
-   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
-     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
-     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
-   - For each executable hook, output the following based on its `optional` flag:
-     - **Optional hook** (`optional: true`):
-       ```
-       ## Extension Hooks
-
-       **Optional Hook**: {extension}
-       Command: `/{command}`
-       Description: {description}
-
-       Prompt: {prompt}
-       To execute: `/{command}`
-       ```
-     - **Mandatory hook** (`optional: false`):
-       ```
-       ## Extension Hooks
-
-       **Automatic Hook**: {extension}
-       Executing: `/{command}`
-       EXECUTE_COMMAND: {command}
-       ```
-   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
-
 Context for task generation: $ARGUMENTS
 
 The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
 
 ## Task Generation Rules
 
-**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+Tasks are organized by user story, so each story can be implemented and tested on its own.
 
 **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
 
diff --git a/.claude/commands/speckit.taskstoissues.md b/.claude/commands/speckit.taskstoissues.md
index 07991911..dc0ad717 100644
--- a/.claude/commands/speckit.taskstoissues.md
+++ b/.claude/commands/speckit.taskstoissues.md
@@ -9,7 +9,7 @@ tools: ['github/github-mcp-server/issue_write']
 $ARGUMENTS
 ```
 
-You **MUST** consider the user input before proceeding (if not empty).
+The user's input above, when present, shapes everything that follows.
 
 ## Outline
 
diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
index d201562c..a3814887 100644
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -1,14 +1,24 @@
 <!-- Sync Impact Report
-  Version change: 0.0.0 → 1.0.0 (initial ratification)
-  Modified principles: N/A (initial)
-  Added sections: Core Principles (4), Technical Constraints, Quality Gates, Governance
-  Removed sections: PRINCIPLE_5 placeholder (reduced to 4 principles)
+  Version change: 1.0.0 → 1.0.1 (corrections of fact, from the 2026-09 prompt audit)
+  Modified principles:
+    - III. Modular Mode Architecture — names all five modes (Pan and Sidebands
+      were missing) and points at modeRoster.js as the one list
+    - IV. Declarative HTML Configuration — the first row holds the source: an
+      <img>, or the <audio> element of an audio-sourced instance (spec 168)
+  Modified sections: Quality Gates — the list CI actually runs (lint, hygiene,
+    coverage, smoke, standalone build, bundle floor, site checks), not three of it
+  Added sections: none
+  Removed sections: none
   Templates requiring updates:
-    - .specify/templates/plan-template.md ✅ no changes needed (Constitution Check section is generic)
+    - .specify/templates/plan-template.md ✅ updated in the same change (Technical
+      Context and Source Code now state the repository's constants)
     - .specify/templates/spec-template.md ✅ no changes needed
     - .specify/templates/tasks-template.md ✅ no changes needed
     - .specify/templates/checklist-template.md ✅ no changes needed
   Follow-up TODOs: none
+
+  1.0.0 (2026-03-26): initial ratification — Core Principles (4), Technical
+  Constraints, Quality Gates, Governance.
 -->
 
 # GramFrame Constitution
@@ -45,7 +55,8 @@ coordinate, event, or rendering regressions.
 
 ### III. Modular Mode Architecture
 
-Each interaction mode (Analysis, Harmonics, Doppler) MUST extend `BaseMode`.
+Each interaction mode — Pan, Analysis, Harmonics, Sidebands and Doppler, with
+`src/modes/modeRoster.js` as the one list — MUST extend `BaseMode`.
 New modes MUST be registered via `ModeFactory`. Modes MUST NOT directly
 depend on each other.
 
@@ -65,7 +76,8 @@ GramFrame instances MUST be configured via HTML tables with class `gram-config`.
 The component auto-discovers and replaces these tables on `DOMContentLoaded`.
 
 - Configuration MUST be parsed from 2-column table rows (`parameter | value`)
-- The first row MUST contain the spectrogram `<img>` element
+- The first row MUST hold the source: the spectrogram `<img>`, or the `<audio>`
+  element of an audio-sourced instance (spec 168)
 - JavaScript object configuration MUST NOT be required for basic usage
 - Multiple independent instances on a single page MUST be supported
 
@@ -87,8 +99,13 @@ existing deployments rely on this contract.
 All of the following MUST pass before any merge to main:
 
 1. `yarn typecheck` — zero errors
-2. `yarn test` — all Playwright tests green
-3. `yarn build` — clean production build
+2. `yarn lint` and `yarn hygiene` — the lint rules and the debt ratchets
+3. `yarn coverage` — the Vitest unit lane, with coverage
+4. `yarn test` — all Playwright tests green, plus the WebKit smoke config
+5. `yarn build`, `yarn build:standalone` and `yarn check:bundle-floor` — clean
+   builds inside the bundle floor
+6. `yarn build:site` and `yarn check:site` — no dead local link, no page
+   unreachable from `index.html`
 
 ## Governance
 
@@ -101,4 +118,4 @@ Amendments require:
 3. Update to the Sync Impact Report at the top of this file
 4. Propagation check across `.specify/templates/` for consistency
 
-**Version**: 1.0.0 | **Ratified**: 2026-03-26 | **Last Amended**: 2026-03-26
+**Version**: 1.0.1 | **Ratified**: 2026-03-26 | **Last Amended**: 2026-09-25
diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md
index 5a2fafeb..3a30367d 100644
--- a/.specify/templates/plan-template.md
+++ b/.specify/templates/plan-template.md
@@ -17,15 +17,20 @@
   the iteration process.
 -->
 
-**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
-**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
-**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
-**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
-**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
-**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]  
-**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
-**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
-**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+**Language/Version**: JavaScript (ES2020+), JSDoc-typed, no compilation step
+**Primary Dependencies**: None at runtime (zero runtime dependencies); Vite 5 for build
+**Storage**: Browser Web Storage — `localStorage` (trainer) / `sessionStorage` (student)
+**Testing**: Playwright (`yarn test`) and Vitest (`yarn test:unit`)
+**Target Platform**: Evergreen browsers, including pages served over `file://`
+**Project Type**: Library — a single-bundle browser component
+**Performance Goals**: [feature-specific, or N/A]
+**Constraints**: [feature-specific, e.g. no new runtime dependency; module caps in `hygiene-baseline.json`]
+**Scale/Scope**: [feature-specific, or N/A]
+
+The first six lines are the repository's constants. Restate them verbatim unless
+this feature changes one, so the agent context file collects one entry rather
+than a differently worded copy per feature. A feature that stores nothing says
+`N/A` for Storage; the context script records nothing for that.
 
 ## Constitution Check
 
@@ -48,51 +53,24 @@ specs/[###-feature]/
 ```
 
 ### Source Code (repository root)
-<!--
-  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
-  for this feature. Delete unused options and expand the chosen structure with
-  real paths (e.g., apps/admin, packages/something). The delivered plan must
-  not include Option labels.
--->
 
 ```text
-# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
 src/
-├── models/
-├── services/
-├── cli/
-└── lib/
-
-tests/
-├── contract/
-├── integration/
-└── unit/
-
-# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
-backend/
-├── src/
-│   ├── models/
-│   ├── services/
-│   └── api/
-└── tests/
-
-frontend/
-├── src/
-│   ├── components/
-│   ├── pages/
-│   └── services/
-└── tests/
-
-# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
-api/
-└── [same as backend above]
-
-ios/ or android/
-└── [platform-specific structure: feature modules, UI flows, platform tests]
+├── main.js, index.js     # the GramFrame class and the entry point
+├── core/                 # state, events, viewport, configuration, storage, selection
+├── modes/                # one directory per mode; shared/ holds the drag engine and pin sets
+├── components/           # the control row, tables, panels, transport bar
+├── rendering/            # axes, symbols, labels, overlays — draw only, never dispatch
+├── audio/ and player/    # the audio-sourced instance: decode → analyse → paint, and playback
+└── utils/                # coordinates, geometry, formatting — pure functions
+
+tests/            # Playwright specs; helpers/, unit/ (Vitest), smoke/ (WebKit), fixtures/
+sample/, demo/    # sample pages, and the demo pages at their published paths
+docs/ADRs/        # architecture decisions
 ```
 
-**Structure Decision**: [Document the selected structure and reference the real
-directories captured above]
+**Structure Decision**: [Which of these directories this feature touches, and
+any new module — each new module also needs its `CLAUDE.md` file-list entry]
 
 ## Complexity Tracking
 
diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md
index 60f9be45..dc901762 100644
--- a/.specify/templates/tasks-template.md
+++ b/.specify/templates/tasks-template.md
@@ -58,7 +58,7 @@ description: "Task list template for feature implementation"
 
 **Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
 
-**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+No user story work begins until this phase is complete.
 
 Examples of foundational tasks (adjust based on your project):
 
@@ -214,7 +214,7 @@ Task: "Create [Entity2] model in src/models/[entity2].py"
 ### MVP First (User Story 1 Only)
 
 1. Complete Phase 1: Setup
-2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+2. Complete Phase 2: Foundational (blocks all stories)
 3. Complete Phase 3: User Story 1
 4. **STOP and VALIDATE**: Test User Story 1 independently
 5. Deploy/demo if ready
diff --git a/CLAUDE.md b/CLAUDE.md
index 259f4f8a..ab2887c9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -153,6 +153,11 @@ Every path below exists; keep this list in step with `src/` when adding modules.
   - `selectionTarget.js` - What is selected, described: its name, its time, the
     frequency it is about. A leaf, so the readout column and the player can both
     ask without a cycle back through `selection.js`
+  - `pointerScope.js` - Which pointer events reach the active mode: is the
+    pointer over the gram? A marker has to land on the gram, so an off-image
+    press is dropped and a running drag is cancelled — except when panning an
+    audio-sourced gram, where scrolling to the start of a recording *means*
+    bringing blank space into view
   - `wheelPan.js` - The middle-button pan, as a drag on the shared engine. Split
     from `events.js`, which owns *which* gesture happens rather than how each
     one behaves
@@ -222,6 +227,10 @@ Every path below exists; keep this list in step with `src/` when adding modules.
     do to it (arm, rename, delete, describe)
   - `ColorPicker.js` - The colour slider: the one colour control in the panel
   - `SymbolPicker.js` - The symbol button and its popup, plus the size trial
+  - `SymbolSizeTrial.js` - TEMPORARY: the symbol-size trial, in the symbol popup
+    rather than the main panel — a choice between the current symbol size and a
+    larger one, so analysts can compare the two on a real gram. Routes like the
+    colour slider: the targeted feature only, else the next created one
   - `Segmented.js` - The shared two-option segmented control
   - `PinToggle.js` - Tall pins or mini, for the next created pin set or the
     selected one
@@ -407,9 +416,15 @@ There is no visual/screenshot regression testing — see
   without a cap must stay under the default — so a new module cannot grow past
   the line and then be grandfathered in. Shrink one by ten lines or more and
   `yarn hygiene` asks you to lower its cap in the same PR (issue #265)
+- The `## Active Technologies` and `## Recent Changes` sections at the foot of
+  this file are written by `.specify/scripts/bash/update-agent-context.sh` when
+  `/speckit.plan` runs. It dedupes entries by their normalised text and records
+  a change only when a feature adds a technology, and `yarn hygiene` fails an
+  entry that restates another — so a plan states the template's constants
+  verbatim rather than rewording them
 - Build output is unminified for field debugging (`minify: false` in vite.config.js)
 - TypeScript checking with JSDoc annotations (no TypeScript compilation).
-  `strict: true` with **no** per-flag disables since spec 167 — `noImplicitAny`,
+  `strict: true` with **no** per-flag disables — `noImplicitAny`,
   `strictNullChecks` and `strictPropertyInitialization` are all in force, so an
   unguarded `querySelector(...).classList` fails `yarn typecheck` (ADR-007)
 - The version is injected from package.json by a Vite define; no build or test
@@ -482,7 +497,7 @@ There is no visual/screenshot regression testing — see
   `utils/coordinates.js` reads the live element bounds, so nothing else changes
 - The whole gram is drawn from load (spec 171, FR-005): `clampViewTop` is bounded
   by the duration, the image clip is the axes area, and nothing asks whether a
-  time has been played before drawing at it — `isTimeRevealed` is gone
+  time has been played before drawing at it
 - While playing, `core/events.js` and `keyboardControl.js` hold **annotation**
   inert (spec 171, FR-017); a press-and-drag is a drag-seek instead
   (`player/dragSeek.js`: pause under the hand, resume from the released view,
@@ -520,10 +535,10 @@ There is no visual/screenshot regression testing — see
   selection. (`contain`, not `cover`; cropping what was deliberately framed is
   the wrong way for a measurement tool to fail.) The overlay draws that
   resulting view as a second dashed outline, so what you draw is still what you
-  get plus a stated remainder. The dimming stays on the **selection**: it
-  followed the dashed view at first, but a mask that is a different shape from
-  the box under the pointer reads as a second thing moving, and the box being
-  drawn is the one being aimed. It clamps at 10× rather
+  get plus a stated remainder. The dimming stays on the **selection**, not on
+  the dashed view: a mask that is a different shape from the box under the
+  pointer reads as a second thing moving, and the box being drawn is the one
+  being aimed. It clamps at 10× rather
   than refusing — visibly, since the preview is capped by the same limit — and
   a release over the axis margins completes it, deliberately unlike a feature
   drag, which is cancelled off-image, because selecting to the very edge is a
@@ -548,8 +563,7 @@ There is no visual/screenshot regression testing — see
   `getSelectedFeature` in `core/featureStyle.js`, decides what a colour click
   actually does, so the tab and the behaviour cannot disagree
 - **Marker labels** are edited in the style panel, in a field beside the same
-  marker's colour and symbol. The per-row dialog is gone; clearing the field
-  removes the label
+  marker's colour and symbol; clearing the field removes the label
 - **Analysis Mode**: Persistent draggable markers whose grab region follows exactly
   what is drawn — a symbol marker has no crosshair arms to grab (issue #273) — with
   cross-mode visibility and optional
@@ -566,22 +580,8 @@ There is no visual/screenshot regression testing — see
   can neither draw, persist nor block a placement
 
 ## Active Technologies
-- Markdown documentation (no code changes) + N/A (documentation-only feature) (154-enrich-docs)
-- JavaScript (ES2020+, JSDoc-typed, no compilation) + None (zero runtime dependencies, Vite for build) (155-browser-storage)
-- Browser Web Storage API (localStorage / sessionStorage) (155-browser-storage)
-- JavaScript (ES2020+), JSDoc-typed, no compilation + None at runtime (zero runtime deps); Vite for build (156-expand-image-toggle)
-- N/A — expand state is in-memory only (explicitly NOT browser storage) (156-expand-image-toggle)
-- JavaScript (ES2020+), JSDoc-typed, no compilation step + None at runtime (zero runtime dependencies); Vite for build (157-student-tonal-expiry)
-- Browser Web Storage API — `sessionStorage` (student), `localStorage` (trainer) (157-student-tonal-expiry)
-- JavaScript ES2020+, JSDoc-typed (no TS compilation) + None at runtime (zero runtime deps); Vite for build (157-harmonic-pin-symbols)
-- Browser Web Storage (localStorage for trainers / sessionStorage for students) (157-harmonic-pin-symbols)
-- JavaScript ES2020+, JSDoc-typed (no TS compilation) + None at runtime (zero runtime deps); Vite for build (158-harmonic-pin-sampling)
-- N/A — purely presentational; no persisted data or new state (158-harmonic-pin-sampling)
-- JavaScript ES2020+, JSDoc-typed (no TS compilation) + None at runtime (zero runtime deps); Vite for build (161-reformat-markers-harmonics)
-- Browser Web Storage — additive `symbol` field on markers; `cross` (symbol-less) default; no schema bump (161-reformat-markers-harmonics)
-- JavaScript ES2020+, JSDoc-typed, no TypeScript compilation + None at runtime (zero runtime deps); Vite 5 for build (166-consolidation)
-- Unchanged — Web Storage (`localStorage` trainer / `sessionStorage` student) (166-consolidation)
-- Unchanged — Web Storage (`localStorage` trainer / `sessionStorage` student). No persisted-shape change in this phase. (167-structural-refactor)
+- JavaScript (ES2020+), JSDoc-typed, no compilation step + None at runtime (zero runtime dependencies); Vite 5 for build
+- Browser Web Storage — `localStorage` (trainer) / `sessionStorage` (student)
 
 ## Recent Changes
 - 172-control-panel: The upper control panel rebuilt to the design handoff — five hairline-separated columns, a mode rail with the view controls in its foot, a permanent collapsible guidance column, instrument-styled readouts, a twin-tab style panel that states its target, inverted selected rows, and a transport bar with time bookmarks
@@ -594,10 +594,3 @@ There is no visual/screenshot regression testing — see
   frequency, per-bin over time), incoherent frame averaging, and the display
   percentiles — all four exposed as config rows and as toggles on `trial/index.html`,
   so an analyst can judge them against a legacy display on their own recording
-- 171-player-refinements: The whole gram from load (the reveal rule withdrawn), contrast controls, drag-to-seek and zoom while playing, a 0.25–4 rate ladder with explicit pitch, oversize recordings degraded rather than refused, and a polite transport live region
-- 170-region-zoom: Shift-drag a box to zoom into it, in every mode, plus a Fit button and a live aspect-locked selection overlay
-- 167-structural-refactor: Planned Phase 3 — strict type gate burn-down (540 errors), state⇄modes decoupling, table.js split, capability seams, shrunk instance surface
-- 166-consolidation: Planned Phase 2 consolidation — one coordinate pipeline, one drag engine, batched notifications, one diffing table, deterministic tests
-- 165-quick-fixes: Truthful published state and loud failures, dead-code sweep, docs corrected against the code
-- 161-reformat-markers-harmonics: Added a `cross` (symbol-less) default style and in-place restyling of selected markers/harmonic sets (colour + symbol)
-- 154-enrich-docs: Added Markdown documentation (no code changes) + N/A (documentation-only feature)

From 75fcaabfed0b5bbca92ed615de8aa8f596ed608e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 25 Sep 2026 11:15:09 +0000
Subject: [PATCH 2/2] Stop the agent-context script restating Active
 Technologies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

update-agent-context.sh deduped Active Technologies entries by exact
substring, so every rewording of the same stack in a plan's Technical
Context appended a line, and CLAUDE.md collected fifteen copies of one
fact. Three layers now prevent that:

- The script compares entries by their normalised text (case, spacing,
  punctuation and the "(branch)" suffix ignored), treats a Storage line
  that says there is none ("N/A", "None", "Unchanged — …") as no entry,
  and mints a Recent Changes line only when a feature actually adds a
  technology, so the hand-written entries are not evicted by no-ops
- yarn hygiene fails an Active Technologies entry that restates another
  or states nothing, at a baseline of zero
- A Vitest test sources the script and pins the rules on a scratch file

Two upstream bugs in the same function surfaced on the way and are fixed:
the tech-section branch consumed the "## Recent Changes" heading, so that
section was never trimmed when the two sat together (which is how the
file reached ten entries); and `(( count++ ))` from zero returns 1, which
`set -e` read as failure the first time the trimming code ran. Trimming
now keeps three whole entries, continuation lines included.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HVGXdCBws4z1ut7BSfD4eE
---
 .specify/scripts/bash/update-agent-context.sh | 100 +++++++++--
 scripts/hygiene.js                            |  43 +++++
 tests/unit/agent-context-dedupe.test.js       | 156 ++++++++++++++++++
 3 files changed, 283 insertions(+), 16 deletions(-)
 create mode 100644 tests/unit/agent-context-dedupe.test.js

diff --git a/.specify/scripts/bash/update-agent-context.sh b/.specify/scripts/bash/update-agent-context.sh
index ede8d77d..8a410d08 100755
--- a/.specify/scripts/bash/update-agent-context.sh
+++ b/.specify/scripts/bash/update-agent-context.sh
@@ -218,6 +218,51 @@ parse_plan_data() {
     fi
 }
 
+# The fact an Active Technologies entry states, with everything that is not
+# the fact removed: the leading "- ", case, spacing and punctuation. Two
+# entries with the same normalised text are the same entry.
+normalise_tech_entry() {
+    printf '%s' "${1#- }" | tr '[:upper:]' '[:lower:]' | tr -cd '[:alnum:]'
+}
+
+# Does the Active Technologies section of $2 already state $1? Existing
+# entries carry a "(branch)" suffix the candidate does not, so the test is
+# "an existing entry begins with the candidate", both normalised.
+tech_section_has() {
+    local wanted
+    wanted=$(normalise_tech_entry "$1")
+    [[ -z "$wanted" ]] && return 0
+    local in_section=false line
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        if [[ "$line" == "## Active Technologies" ]]; then
+            in_section=true
+            continue
+        fi
+        if [[ $in_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            break
+        fi
+        if [[ $in_section == true ]] && [[ "$line" == "- "* ]]; then
+            [[ "$(normalise_tech_entry "$line")" == "$wanted"* ]] && return 0
+        fi
+    done < "$2"
+    return 1
+}
+
+# A Storage line that says there is none ("N/A", "None", "Unchanged — …") is
+# not a technology, whatever follows the dash.
+is_real_storage() {
+    local value="$1"
+    [[ -n "$value" ]] || return 1
+    case "$value" in
+        "NEEDS CLARIFICATION"*) return 1 ;;
+    esac
+    shopt -s nocasematch
+    local reject=0
+    [[ "$value" =~ ^(n/a|none|unchanged)([^[:alnum:]]|$) ]] && reject=1
+    shopt -u nocasematch
+    [[ $reject -eq 0 ]]
+}
+
 format_technology_stack() {
     local lang="$1"
     local framework="$2"
@@ -400,20 +445,28 @@ update_existing_agent_file() {
     local new_tech_entries=()
     local new_change_entry=""
     
-    # Prepare new technology entries
-    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
+    # Prepare new technology entries. An entry is the fact it states, not its
+    # spelling: "JavaScript (ES2020+)" and "javascript es2020+" are the same
+    # entry, so the comparison is on the normalised text and ignores the
+    # "(branch)" suffix. The old exact-substring grep added a line for every
+    # rewording, and CLAUDE.md collected fifteen copies of one stack.
+    if [[ -n "$tech_stack" ]] && ! tech_section_has "$tech_stack" "$target_file"; then
         new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
     fi
-    
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+
+    if is_real_storage "$NEW_DB" && ! tech_section_has "$NEW_DB" "$target_file"; then
         new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
     fi
-    
-    # Prepare new change entry
-    if [[ -n "$tech_stack" ]]; then
-        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
-    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
-        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+
+    # Prepare new change entry, only when the feature added a technology:
+    # a plan that restates the stack has nothing to record, and recording
+    # it anyway would evict a hand-written entry from the three kept.
+    if [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        if [[ -n "$tech_stack" ]]; then
+            new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+        else
+            new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+        fi
     fi
     
     # Check if sections exist in the file
@@ -434,6 +487,7 @@ update_existing_agent_file() {
     local tech_entries_added=false
     local changes_entries_added=false
     local existing_changes_count=0
+    local current_change_kept=true
     local file_ended=false
     
     while IFS= read -r line || [[ -n "$line" ]]; do
@@ -443,14 +497,15 @@ update_existing_agent_file() {
             in_tech_section=true
             continue
         elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
-            # Add new tech entries before closing the section
+            # Add new tech entries before closing the section. The heading
+            # that closes it is not consumed here: it may be "## Recent
+            # Changes", which the branch below must still see, or that
+            # section is never trimmed when the two sit together.
             if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
                 printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
                 tech_entries_added=true
             fi
-            echo "$line" >> "$temp_file"
             in_tech_section=false
-            continue
         elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
             # Add new tech entries before empty line in tech section
             if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
@@ -476,12 +531,25 @@ update_existing_agent_file() {
             in_changes_section=false
             continue
         elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
-            # Keep only first 2 existing changes
-            if [[ $existing_changes_count -lt 2 ]]; then
+            # The section keeps three entries: the new one plus the first two
+            # existing, or the first three when nothing was added. An entry
+            # may wrap onto indented continuation lines; they follow their
+            # entry's fate, or a dropped entry would leave its tail behind.
+            local keep_existing=3
+            [[ -n "$new_change_entry" ]] && keep_existing=2
+            if [[ $existing_changes_count -lt $keep_existing ]]; then
                 echo "$line" >> "$temp_file"
-                ((existing_changes_count++))
+                # Not `((count++))`: with the count at zero that evaluates to
+                # 0, which `set -e` reads as failure and exits the script.
+                existing_changes_count=$((existing_changes_count + 1))
+                current_change_kept=true
+            else
+                current_change_kept=false
             fi
             continue
+        elif [[ $in_changes_section == true ]] && [[ -n "$line" ]]; then
+            [[ $current_change_kept == true ]] && echo "$line" >> "$temp_file"
+            continue
         fi
         
         # Update timestamp
diff --git a/scripts/hygiene.js b/scripts/hygiene.js
index 95313959..a549d048 100644
--- a/scripts/hygiene.js
+++ b/scripts/hygiene.js
@@ -304,6 +304,49 @@ if (existsSync(coverageSummaryPath)) {
   console.log('\u2022 Uncovered lines: no coverage summary found - run `yarn coverage` to include this check')
 }
 
+// --- 9. Restated entries in CLAUDE.md's Active Technologies -----------------
+
+// `/speckit.plan` appends the plan's Technical Context to this section through
+// `.specify/scripts/bash/update-agent-context.sh`. Until the script compared
+// entries by their normalised text, every rewording of the same stack added a
+// line, and by feature 167 the section said "JavaScript, no runtime deps, Vite"
+// fifteen ways. The script now dedupes and the plan template states the
+// constants verbatim; this check is what fails the build if either regresses.
+//
+// An entry's key is its text lower-cased, letters and digits only. The script
+// tags what it appends with a "(branch)" suffix, so two entries are one fact
+// stated twice when either key begins with the other — the same rule the
+// script applies before appending. An entry that says there is nothing to
+// state ("N/A", "None", "Unchanged") is counted too: it is not a technology.
+const claudeMd = readFileSync(join(repoRoot, 'CLAUDE.md'), 'utf8').split('\n')
+const techStart = claudeMd.indexOf('## Active Technologies')
+const techEntries = []
+for (let i = techStart + 1; techStart >= 0 && i < claudeMd.length; i++) {
+  if (/^##\s/.test(claudeMd[i])) break
+  if (claudeMd[i].startsWith('- ')) techEntries.push(claudeMd[i].slice(2))
+}
+/** @param {string} entry */
+const techKey = entry => entry.toLowerCase().replace(/[^a-z0-9]/g, '')
+const restatedTech = []
+/** @type {{key: string, entry: string}[]} */
+const seenTech = []
+for (const entry of techEntries) {
+  if (/^(n\/a|none|unchanged)(?![a-z0-9])/i.test(entry)) {
+    restatedTech.push(`states nothing: "${entry}"`)
+    continue
+  }
+  const key = techKey(entry)
+  const earlier = seenTech.find(seen => seen.key.startsWith(key) || key.startsWith(seen.key))
+  if (earlier) restatedTech.push(`restates "${earlier.entry}": "${entry}"`)
+  else seenTech.push({ key, entry })
+}
+results.push({
+  name: 'Active Technologies entries in CLAUDE.md that restate another or state nothing',
+  baseline: 0,
+  current: restatedTech.length,
+  detail: restatedTech,
+})
+
 // --- Report -----------------------------------------------------------------
 
 let failed = false
diff --git a/tests/unit/agent-context-dedupe.test.js b/tests/unit/agent-context-dedupe.test.js
new file mode 100644
index 00000000..d99127d7
--- /dev/null
+++ b/tests/unit/agent-context-dedupe.test.js
@@ -0,0 +1,156 @@
+// @vitest-environment node
+/**
+ * Unit lane for `.specify/scripts/bash/update-agent-context.sh`, the script
+ * `/speckit.plan` runs to fold a plan's Technical Context into CLAUDE.md.
+ *
+ * The script once deduped Active Technologies entries by exact substring, so
+ * every rewording of the same stack added a line and CLAUDE.md collected
+ * fifteen copies of one fact. These tests pin the rule that replaced it: an
+ * entry is the fact it states, compared with case, spacing, punctuation and
+ * the "(branch)" suffix ignored; a Storage line that says there is no storage
+ * is not an entry; and trimming Recent Changes keeps a wrapped entry whole.
+ *
+ * The script guards its `main` behind a BASH_SOURCE check, so a test sources
+ * it and calls `update_existing_agent_file` directly on a scratch file.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const script = join(repoRoot, '.specify', 'scripts', 'bash', 'update-agent-context.sh')
+const hasBash = spawnSync('bash', ['-c', 'true']).status === 0
+
+/**
+ * Run `update_existing_agent_file` on `target` as though the plan on branch
+ * `branch` had the given Technical Context, and return the file afterwards.
+ * @param {string} target
+ * @param {{lang?: string, framework?: string, storage?: string, branch?: string}} plan
+ */
+function update(target, { lang = '', framework = '', storage = '', branch = '999-test' }) {
+  const result = spawnSync(
+    'bash',
+    [
+      '-c',
+      [
+        `source "${script}"`,
+        `NEW_LANG=${JSON.stringify(lang)}`,
+        `NEW_FRAMEWORK=${JSON.stringify(framework)}`,
+        `NEW_DB=${JSON.stringify(storage)}`,
+        `CURRENT_BRANCH=${JSON.stringify(branch)}`,
+        `update_existing_agent_file "${target}" 2026-01-01`
+      ].join('\n')
+    ],
+    // The script resolves feature paths when sourced; a named feature keeps
+    // that independent of whichever branch the test runs on.
+    { cwd: repoRoot, env: { ...process.env, SPECIFY_FEATURE: '999-test' }, encoding: 'utf8' }
+  )
+  if (result.status !== 0) throw new Error(`script failed:\n${result.stdout}\n${result.stderr}`)
+  return readFileSync(target, 'utf8')
+}
+
+/**
+ * The lines of the section under `heading`, up to the next heading.
+ * @param {string} text
+ * @param {string} heading
+ */
+function section(text, heading) {
+  const lines = text.split('\n')
+  const start = lines.indexOf(heading)
+  const body = []
+  for (let i = start + 1; i < lines.length && !/^##\s/.test(lines[i]); i++) body.push(lines[i])
+  return body
+}
+
+const STACK = 'JavaScript (ES2020+), JSDoc-typed, no compilation step'
+const DEPS = 'None at runtime (zero runtime dependencies); Vite 5 for build'
+
+const FIXTURE = `# Test Guidelines
+
+## Active Technologies
+- ${STACK} + ${DEPS} (155-first)
+- Browser Web Storage for annotations: \`localStorage\` for trainers (155-first)
+
+## Recent Changes
+- 172-newest: one line
+- 171-wrapped: the head of a wrapped entry
+  and its continuation line
+- 170-oldest: the entry that trimming drops
+  with its own continuation line
+
+## Later
+- untouched
+`
+
+describe.skipIf(!hasBash)('update-agent-context.sh: Active Technologies stays a set of facts', () => {
+  /** @type {string} */
+  let dir = ''
+  /** @type {string} */
+  let target = ''
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'agent-context-'))
+    target = join(dir, 'CLAUDE.md')
+    writeFileSync(target, FIXTURE)
+  })
+  afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+  it('adds nothing when the plan restates the stack verbatim on a new branch', () => {
+    const after = update(target, { lang: STACK, framework: DEPS, branch: '173-next' })
+    const entries = section(after, '## Active Technologies').filter(l => l.startsWith('- '))
+    expect(entries).toHaveLength(2)
+    // and Recent Changes is left alone: the feature added no technology, so
+    // there is nothing to record, and the hand-written entries all survive
+    expect(section(after, '## Recent Changes')).toEqual(section(FIXTURE, '## Recent Changes'))
+  })
+
+  it('adds nothing when only case, spacing or punctuation differ', () => {
+    const after = update(target, {
+      lang: 'javascript  ES2020+ jsdoc typed no-compilation step',
+      framework: 'none at runtime (zero runtime dependencies) vite 5 for build',
+      branch: '173-next'
+    })
+    const entries = section(after, '## Active Technologies').filter(l => l.startsWith('- '))
+    expect(entries).toHaveLength(2)
+  })
+
+  it('adds a genuinely new fact, tagged with its branch', () => {
+    const after = update(target, { lang: 'WebAssembly (Rust 1.80)', branch: '173-next' })
+    const entries = section(after, '## Active Technologies').filter(l => l.startsWith('- '))
+    expect(entries).toHaveLength(3)
+    expect(entries[2]).toBe('- WebAssembly (Rust 1.80) (173-next)')
+  })
+
+  it.each(['N/A', 'N/A — expand state is in-memory only', 'None', 'Unchanged — Web Storage as before'])(
+    'does not record a Storage line that says there is none: %s',
+    storage => {
+      const after = update(target, { storage, branch: '173-next' })
+      const entries = section(after, '## Active Technologies').filter(l => l.startsWith('- '))
+      expect(entries).toHaveLength(2)
+      // and no Recent Changes entry is minted for it either
+      expect(section(after, '## Recent Changes').join('\n')).not.toContain('173-next')
+    }
+  )
+
+  it('records a real Storage line once, however it is spelled later', () => {
+    const first = update(target, { storage: 'IndexedDB for decoded audio', branch: '173-next' })
+    expect(section(first, '## Active Technologies').filter(l => l.startsWith('- '))).toHaveLength(3)
+    const second = update(target, { storage: 'indexeddb, for decoded audio', branch: '174-after' })
+    expect(section(second, '## Active Technologies').filter(l => l.startsWith('- '))).toHaveLength(3)
+  })
+
+  it('trims Recent Changes to three whole entries, continuation lines included', () => {
+    const after = update(target, { lang: 'WebAssembly (Rust 1.80)', branch: '173-next' })
+    const changes = section(after, '## Recent Changes').filter(l => l !== '')
+    expect(changes).toEqual([
+      '- 173-next: Added WebAssembly (Rust 1.80)',
+      '- 172-newest: one line',
+      '- 171-wrapped: the head of a wrapped entry',
+      '  and its continuation line'
+    ])
+    expect(after).not.toContain('with its own continuation line')
+    expect(section(after, '## Later')).toContain('- untouched')
+  })
+})