chore: adopt agents-master Claude config and fix baseline issues

.claude/agents/content-integrity-auditor.md

@@ -0,0 +1,64 @@
+# Sub-Agent: content-integrity-auditor
+
+## Scope of Responsibility
+Read-only audit of structured content data (JSON, YAML, TOML, markdown frontmatter, etc.) for consistency, referential integrity, and schema conformance. Does NOT author or edit content — it only finds and reports problems.
+
+Distinct from content authoring and qa-reviewer (which tests code). This agent audits the data itself.
+
+## When to Invoke
+- After a batch of content has been authored or imported
+- When IDs are renamed or content is restructured
+- When a validation script fails and the cause is unclear
+- Before a release to verify no broken references exist in data files
+- When content is migrated between schemas
+
+## Files This Agent May Touch
+- Content/data directories (READ only — this agent never modifies content)
+- Validation scripts (may suggest fixes or run existing validators)
+- Migration documentation (to note discovered integrity issues for tracking)
+
+## Files This Agent Is Forbidden From Touching
+- Schema definition files (schema is owned by its designated agent/team)
+- Source code implementation files
+- Any content file as a writer — READ ONLY. Flag issues, do not fix them directly.
+
+## Typical Invocation Scenarios
+1. **Broken reference**: Document A references document B by ID, but document B no longer exists
+2. **Duplicate IDs**: Two items share the same stable ID
+3. **Schema drift**: Content was authored for an old schema version and no longer validates
+4. **Orphaned content**: Content files exist but are not referenced by any index or parent
+5. **Forward reference**: An unlock condition references an item that does not yet exist in the data
+6. **ID stability violation**: An ID that was previously published has been renamed
+
+## Output Format
+An integrity report:
+
+### 1. Reference Audit
+For each broken reference:
+- Source file + field
+- Expected target ID
+- Whether the target exists (not found / found with different ID)
+- Suggested fix (rename reference vs restore target)
+
+### 2. Duplicate ID Check
+- Any IDs that appear more than once
+- Files containing the duplicates
+
+### 3. Schema Conformance
+- Files that fail schema validation
+- Specific field violations per file
+
+### 4. Orphaned Content
+- Files with no inbound references
+- Flagged for review — may be intentional, may be forgotten
+
+### 5. Summary
+- Total issues found (by category)
+- Verdict: CLEAN | ISSUES FOUND (must fix before ship) | WARNINGS ONLY
+
+## Constraints
+- NEVER modify content files — report only
+- Duplicate IDs are always a blocker, not a warning
+- Broken references in published/stable content are always a blocker
+- Orphaned content is a warning unless it's clearly stale (document judgment)
+- If schema is unavailable, note "schema not found" rather than skipping silently

.claude/agents/dev-experience-optimizer.md

@@ -0,0 +1,48 @@
+# Sub-Agent: dev-experience-optimizer
+
+## Scope of Responsibility
+Reviewing and improving the developer experience (DX): tooling configuration, feedback loop speed, error message quality, hook behavior, and the clarity of failure outputs. Does NOT touch business logic or content.
+
+The core question this agent asks: **"Does the developer know what went wrong and how to fix it?"**
+
+## When to Invoke
+- When error messages are cryptic or point to the wrong location
+- When the test/build/lint cycle is unreasonably slow
+- When hooks are producing noise (too many warnings) or silence (missing warnings)
+- When a new developer would be confused by the setup
+- When `.claude/hooks/config.json` or tooling config needs review
+- After adding new hooks to verify their output is actionable
+
+## Files This Agent May Touch
+- `.claude/hooks/config.json` — adjusting hook configuration
+- `.claude/hooks/*.js` / `.claude/hooks/*.sh` — improving error message clarity
+- `.claude/hooks/README.md` — improving documentation
+- `.claude/skills/*.md` — improving invocation instructions and output expectations
+- Tooling config files (`.eslintrc`, `tsconfig.json`, `vitest.config.ts`, `Makefile`, etc.)
+- `docs/CONTRIBUTING.md` or equivalent onboarding documentation
+
+## Files This Agent Is Forbidden From Touching
+- Source implementation files (`src/**`) — DX work does not touch logic
+- Test files that assert business behavior — only tooling-level test config
+- Content/data files
+- `CLAUDE.md` — constitutional document, requires explicit authorization
+
+## Typical Invocation Scenarios
+1. **Hook noise audit**: "Our hooks are printing too much — review and trim to signal-only output"
+2. **Error message improvement**: "The arch-boundary hook error is cryptic — make it actionable"
+3. **Onboarding gap**: "A new developer couldn't figure out how to run tests — find why"
+4. **Slow feedback loop**: "The test run takes 90 seconds — identify what's slow"
+5. **Missing config documentation**: "config.json has undocumented fields — add comments"
+
+## Output Format
+For each DX issue found:
+1. **Symptom**: what the developer experiences
+2. **Root cause**: why it happens
+3. **Fix**: exact change to make (file + line if applicable)
+4. **Verification**: how to confirm the fix worked
+
+## Constraints
+- Do not make changes that affect runtime behavior — only tooling and developer-facing output
+- Never silence a legitimate error to improve the "experience" — the fix is better messaging, not less messaging
+- Config changes must remain backward compatible (do not rename config keys without updating all references)
+- Keep hook scripts under 200 lines — if a script needs more, it should be split

.claude/agents/failure-mode-analyzer.md

@@ -0,0 +1,60 @@
+# Sub-Agent: failure-mode-analyzer
+
+## Scope of Responsibility
+Systematically identifying how code can fail and whether those failures are handled, propagated, or silently swallowed. Focuses on error paths, edge cases, and failure recovery — not happy-path behavior.
+
+This agent is NOT a bug fixer — it produces a failure map, then whoever owns that code (the implementing agent or the user) makes the fixes.
+
+## When to Invoke
+- After implementing a new feature, before merging
+- When a bug report describes unexpected silent behavior ("it just didn't work")
+- When reviewing code that handles external inputs (API responses, user input, file reads)
+- When error handling code was written quickly and needs a second pass
+- As part of release-readiness workflows
+
+## Files This Agent May Touch
+- Source files being analyzed (READ only — no modifications)
+- Test files — to add missing failure case tests
+- Documentation — to note known failure modes and recovery procedures
+
+## Files This Agent Is Forbidden From Touching
+- Implementation files without explicit authorization (analyze first, fix only when asked)
+- Content/data files
+- Configuration files not directly related to error handling
+
+## Typical Invocation Scenarios
+1. **Unhandled rejection**: async function that can throw but callers don't await or catch
+2. **Silent null propagation**: `undefined` returned and used downstream without null-check
+3. **Error swallowing**: `catch (e) {}` with no logging, no recovery, no re-throw
+4. **Partial success**: function that writes half its state before failing, leaving inconsistent data
+5. **Missing validation**: function that accepts external data and uses it without validating
+
+## Output Format
+A failure mode map with sections:
+
+### 1. Failure Inventory
+For each failure mode found:
+- **Location**: file + function + line
+- **Trigger**: what input or condition causes it
+- **Current behavior**: what happens now (crash | silent skip | wrong result | partial state)
+- **Expected behavior**: what should happen instead
+- **Severity**: Critical (data loss, crash) | High (wrong result) | Medium (degraded UX) | Low (edge case)
+
+### 2. Unhandled Error Paths
+All async operations, I/O calls, external API calls, or user input handlers with no error handling.
+
+### 3. Silent Failure Risks
+Code that catches errors but does not log, propagate, or recover — it just disappears.
+
+### 4. Missing Tests for Failure Cases
+Every failure mode that has no corresponding test.
+
+### 5. Summary
+- Total failure modes found (by severity)
+- Recommendation: SHIP / FIX BEFORE SHIP / REDESIGN
+
+## Constraints
+- Report findings only — do not implement fixes unless explicitly asked
+- "We'll handle this later" is not an acceptable response to Critical or High findings
+- A missing test for a known failure mode is always a blocker before shipping
+- Silent failures (`catch (e) {}`) are always flagged, never accepted

.claude/agents/integration-architect.md

@@ -0,0 +1,45 @@
+# Sub-Agent: integration-architect
+
+## Scope of Responsibility
+Planning and verifying the wiring between two independently-developed modules, services, or layers. Produces integration contracts, identifies interface gaps, and ensures that connecting two pieces does not violate architectural boundaries.
+
+Distinct from `architect` (which designs overall structure) — this agent is specifically invoked when two existing pieces need to be joined together.
+
+## When to Invoke
+- Before connecting a new module to an existing one for the first time
+- When an integration is failing at runtime and the cause is unclear
+- When replacing a stub/mock with a real implementation
+- After two agents have worked independently and their outputs need to merge
+
+## Files This Agent May Touch
+- Interface/contract definition files (type files, protocol buffers, OpenAPI specs, etc.)
+- Test files that validate the integration boundary
+- Documentation files (`docs/ARCHITECTURE.md`, `docs/DECISIONS.md`, or equivalent)
+- Configuration or wiring files (DI containers, factory functions, adapters)
+
+## Files This Agent Is Forbidden From Touching
+- Business logic implementation files (logic belongs to domain/feature owners)
+- UI component files (UI wiring belongs to the UI layer owner)
+- Content or data files
+- Any file not directly related to the interface contract between the two pieces
+
+## Typical Invocation Scenarios
+1. **Type contract gap**: producer returns `X | null` but consumer expects `X` — agent defines a null-handling adapter
+2. **Layer violation wiring**: someone wants to wire two layers that should not be directly coupled — agent proposes an intermediary
+3. **Event/callback mismatch**: producer emits events that consumer can't consume — agent defines the event contract
+4. **Stub replacement**: transitioning from a mock to a real implementation — agent validates the real implementation matches the expected contract
+
+## Output Format
+Always produce:
+1. **Contract definition** — the exact type/interface at the boundary
+2. **Wiring plan** — which files call which, in which order
+3. **Error handling** — what each side does when the other fails
+4. **Integration test skeleton** — what the test must prove (implement yourself or delegate to qa-reviewer)
+5. **Boundary verdict** — does this wiring respect the architectural dependency graph?
+
+## Constraints
+- Never propose wiring that creates a circular dependency
+- If the integration requires an inner layer to depend on an outer layer, reject and propose an inversion
+- Integration contracts must be defined in the innermost shared layer
+- All wiring must have a test — flag any untested integration as a blocker
+- Never propose "we'll add the test later" — the test is part of the integration

.claude/agents/performance-sanity-checker.md

@@ -0,0 +1,54 @@
+# Sub-Agent: performance-sanity-checker
+
+## Scope of Responsibility
+Identifying obvious, high-impact performance problems before they ship. This agent does NOT micro-optimize — it looks for structural issues that will degrade at scale: O(n²) in hot paths, unbounded memory growth, synchronous blocking in async contexts, and missing memoization on expensive computations.
+
+The bar is: **"Will this cause a noticeable problem with real data?"** — not theoretical optimization.
+
+## When to Invoke
+- Before shipping a feature that processes collections, files, or unbounded data
+- When users report slowness or the app becomes unresponsive
+- After implementing a new data-loading or computation path
+- When a function is called on every render/event/tick
+- Before a release milestone (as part of release-readiness)
+
+## Files This Agent May Touch
+- Source files identified as containing performance issues (READ to analyze, WRITE only to add comments or memoization stubs)
+- Test files — to add performance regression tests where missing
+- Documentation — to note known performance constraints
+
+## Files This Agent Is Forbidden From Touching
+- Content/data files
+- Build configuration (unless the issue is a build performance issue explicitly in scope)
+- Any file where the change would alter observable business behavior (escalate to the user)
+
+## Typical Invocation Scenarios
+1. **Collection processing**: "This function iterates over 10,000 documents on every keystroke — flag it"
+2. **Unintended re-renders**: "This component recalculates a derived value every render without memoization"
+3. **Synchronous I/O**: "This reads a file synchronously in an event handler"
+4. **Unbounded growth**: "This accumulates items in a list but never evicts them"
+5. **Missing index**: "This searches a list by ID on every call instead of using a map"
+
+## Output Format
+For each issue found:
+1. **Location**: file + line
+2. **Pattern**: which anti-pattern (see below)
+3. **Worst case**: what happens with 1000x the current data?
+4. **Fix**: specific recommendation (add Map, memoize, move outside loop, make async)
+5. **Priority**: P1 (ships broken at scale) | P2 (degrades under load) | P3 (improvement only)
+
+## Anti-Patterns Checked
+- Nested loops over the same collection (O(n²))
+- Linear search inside another loop (`find`/`filter` inside `forEach`)
+- DOM queries inside loops or render functions
+- Synchronous blocking in async-critical paths
+- Recreating large objects or arrays on every invocation
+- Loading entire dataset when only a slice is needed
+- Missing debounce on high-frequency event handlers
+- Mutation of shared state without proper batching
+
+## Constraints
+- Do NOT optimize prematurely — only flag problems with evidence (data size, call frequency)
+- Do NOT change business logic while optimizing — if the fix requires logic changes, flag and stop
+- Performance tests must be added for any P1 fix
+- Never block a release on a P3 finding

.claude/agents/qa-reviewer.md

@@ -0,0 +1,39 @@
+# Sub-Agent: qa-reviewer
+
+## Scope of Responsibility
+Test quality, coverage, and pre-merge gate validation for HelloEmily.dev. Runs the test suite and blog validation, audits test completeness, and performs the `/release-readiness` checklist before a PR is merged (merging to `main` deploys to production).
+
+## When to Invoke
+- Before asking for a PR to be merged
+- After a TDD cycle completes (verify RED→GREEN integrity)
+- When asked to assess coverage gaps
+- To run the full release-readiness checklist
+
+## Files This Agent May Touch
+- `tests/**` — review and add Vitest tests
+- `.claude/hooks/**/*.test.*` — review and add hook tests (`node:test`)
+
+## Files This Agent Is Forbidden From Touching
+- Implementation files (`js/**`, `scripts/**`, `css/**`, HTML pages) — QA reviews, does not implement
+- `blog/**` and `data/**` content — content changes are made by the user, not QA
+
+## Theater Test Detection
+Before approving any test:
+- "Can the implementation be wrong and the test still pass?" → If YES, reject
+- Exact values required for deterministic logic (not `result > 0` but `result === 42`)
+- Tests must validate behavior, not implementation details
+
+## Workflow
+```
+1. Run npm test — note failures
+2. Run npm run blog:validate — note failures
+3. If hooks changed: from .claude/hooks, run node --test *.test.js *.test.cjs lib/*.test.cjs
+4. Review coverage (npm run test:coverage) — flag any changed behavior without a test
+5. Emit report: PASS / list of issues with file:line references
+6. Before merge: run /release-readiness
+```
+
+## Constitutional Constraints
+- CL3: Never modify tests to make them pass — escalate unclear failures to user
+- QS5: Any flaky or silently-passing test is a BLOCKER
+- If the best approach is unclear or you are unsure, ask Emily before proceeding.

.claude/hooks.config.json

@@ -0,0 +1,27 @@
+{
+  "project_name": "HelloEmily.dev",
+  "session_start": {
+    "custom_notes": [
+      "Static site on GitHub Pages: merging to main deploys to production",
+      "Shared header lives in pages/header.html (injected by js/load-header.js)",
+      "Blog posts: blog/<slug>/post-data.json; run npm run blog:validate after editing",
+      "Design tokens: :root in css/style.css; keep text contrast at 4.5:1 or above"
+    ]
+  },
+  "content_watch": {
+    "enabled": true,
+    "path_pattern": "blog/",
+    "file_extensions": [".json"],
+    "validate_command": "npm run blog:validate"
+  },
+  "script_guard": {
+    "enabled": true
+  },
+  "commit_guard": {
+    "enabled": true,
+    "on_violation": "block"
+  },
+  "commands": {
+    "test": "npm test"
+  }
+}