[IanMayo]

Summary

A prompt audit of the repository's model-facing text (CLAUDE.md, the constitution, the vendored spec-kit commands and templates) found factual rot rather than dated prompting in CLAUDE.md, three constitution rules the codebase had outgrown, and model-dated text in spec-kit 0.4.2. This PR applies the High and Medium findings, and fixes the script that was generating the worst of the rot.

Audit fixes (commit 1)

CLAUDE.md

• The file list promised every path exists and was missing pointerScope.js and SymbolSizeTrial.js; both added
• "Recent Changes" still called the 167/166 work "Planned" while the file above described it as done; trimmed to the three entries the template asks for
• Fifteen near-duplicate "Active Technologies" lines become the two facts they carried
• Four lines describing 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; Sync Impact Report updated)

• Principle III named three of the five modes (Pan and Sidebands missing). /speckit.analyze grades any conflict with the constitution as CRITICAL, so this made every Pan/Sidebands plan look non-compliant
• 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 and real tree instead of generic placeholders and a three-option structure menu
• Bold-caps openers, a CRITICAL table-formatting block, a 40-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 repo does not have) are removed from the four commands that carried them. Decline this if you plan to adopt spec-kit extensions.

Stop the duplication (commit 2)

update-agent-context.sh deduped Active Technologies entries by exact substring, so every rewording of the same stack in a plan appended a line. Three layers now prevent that:

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

Two upstream bugs in the same function surfaced and are fixed: the tech-section branch consumed the ## Recent Changes heading so that section was never trimmed when the two sat together (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.

Verification

• yarn test:unit 362 passed (including the new script test)
• yarn typecheck, yarn lint, yarn hygiene all clean at baseline
• Dry run: two /speckit.plan-style runs restating the template's constants leave CLAUDE.md byte-identical; a run adding a real technology appends one entry and one change line
• Playwright suite not run locally (no src/ changes); CI will run it

Not changed

Low-confidence flags from the audit are left as they were: the personal Codespaces/Edge note, the "I'm Groot" shell-quoting line in the commands, the generic SaaS examples in the spec template, issue-number citations, and docs/archive/prompts/.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HVGXdCBws4z1ut7BSfD4eE

---

Generated by Claude Code

[github-actions]

PR Preview

Preview deployment is ready! View Preview

Last updated: 2026-09-25T11:15:53.258Z