@majordigital/create-acorn 1.6.8 → 1.7.0

package/README.md

@@ -65,6 +65,31 @@ npx @majordigital/create-acorn@latest --add-pre-deploy
 
 The `--add-pre-deploy` flag copies the scripts, installs the dependencies (`lighthouse`, `chrome-launcher`, `playwright`, `linkinator`), and adds the npm scripts to your `package.json`. It skips silently if the tooling is already present.
 
+## AI Audit Commands
+
+Every Acorn project ships with 10 specialised audit slash commands for Claude Code, sourced from the [`ai-claude-boilerplate`](https://github.com/MajorDigital/ai-claude-boilerplate):
+
+| Command | Focus |
+|---------|-------|
+| `/audit-accessibility-motion` | A11y compliance and motion/animation safety |
+| `/audit-analytics-conversion` | Analytics setup and conversion tracking |
+| `/audit-code-maintainability` | Code quality and maintainability |
+| `/audit-documentation-onboarding` | Docs completeness and developer onboarding |
+| `/audit-edge-api-resilience` | Edge/API error handling and resilience |
+| `/audit-headless-cms` | CMS integration patterns and content modelling |
+| `/audit-i18n-localization` | Internationalisation and localisation readiness |
+| `/audit-performance-metrics` | Performance and Core Web Vitals |
+| `/audit-security-compliance` | Security posture and compliance |
+| `/audit-seo-semantic` | SEO and semantic markup |
+
+### Adding audit commands to an existing project
+
+```bash
+npx @majordigital/create-acorn@latest --add-audit
+```
+
+The `--add-audit` flag copies all 10 audit commands into the project's `.claude/commands/`. It skips if they are already installed.
+
 ## Acorn Component Architecture
 
 The Acorn library follows a layered component hierarchy designed for consistency and reuse across projects:
@@ -121,6 +146,7 @@ Beyond the component library, every project includes:
 | `scripts/check-links.mjs` | Broken internal link crawler using linkinator |
 | `scripts/cleanup-screenshots.mjs` | Removes pre-deploy artifacts older than 1 month |
 | `.claude/commands/pre-deploy.md` | `/pre-deploy` slash command for Claude Code |
+| `.claude/commands/audit-*.md` | 10 `/audit-*` slash commands for Claude Code |
 
 ## npm
 

package/bin/create-acorn.mjs

@@ -4,7 +4,7 @@ import readline from 'node:readline';
 import { argv, exit } from 'node:process';
 import { spawn } from 'node:child_process';
 import { basename, join, dirname } from 'node:path';
-import { readFileSync, writeFileSync, cpSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, cpSync, rmSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 const CMS_CHOICES = [
@@ -147,6 +147,35 @@ async function setupPreDeploy() {
   console.log('');
 }
 
+function setupAuditCommands() {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const commandsSrc = join(__dirname, '..', 'template', '.claude', 'commands');
+  const commandsDest = join(process.cwd(), '.claude', 'commands');
+
+  const auditFiles = readdirSync(commandsSrc).filter((f) => f.startsWith('audit-') && f.endsWith('.md'));
+  if (auditFiles.length === 0) {
+    console.log('Warning: No audit commands found in the package — skipping.');
+    return;
+  }
+
+  const alreadyInstalled = auditFiles.every((f) => existsSync(join(commandsDest, f)));
+  if (alreadyInstalled) {
+    console.log('Audit commands already installed — skipping.');
+    console.log('');
+    return;
+  }
+
+  mkdirSync(commandsDest, { recursive: true });
+  for (const file of auditFiles) {
+    cpSync(join(commandsSrc, file), join(commandsDest, file), { force: true });
+  }
+  console.log(`Copied ${auditFiles.length} audit commands to .claude/commands/:`);
+  for (const file of auditFiles) {
+    console.log(`  /${file.replace(/\.md$/, '')}`);
+  }
+  console.log('');
+}
+
 async function setupNextApp() {
   console.log('Setting up Next.js 15 project...');
   console.log('');
@@ -1119,6 +1148,15 @@ async function main() {
     return;
   }
 
+  // Standalone audit commands install — run in the current directory, no full setup needed
+  if (argv.includes('--add-audit')) {
+    console.log('Adding audit commands to the current project...');
+    console.log('');
+    setupAuditCommands();
+    console.log('Done. Run any /audit-* command in Claude Code to start an audit.');
+    return;
+  }
+
   // Prompt for project name first
   const nameFromFlag = parseFlag('name');
   let projectDir = nameFromFlag;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@majordigital/create-acorn",
-  "version": "1.6.8",
+  "version": "1.7.0",
   "description": "Interactive starter CLI for Acorn with Storyblok/Prismic/DatoCMS, TypeScript, and Tailwind.",
   "bin": {
     "create-acorn": "bin/create-acorn.mjs",

package/template/.claude/commands/audit-accessibility-motion.md

@@ -0,0 +1,161 @@
+---
+description: "Run an Accessibility & Motion audit on the current project (Module 3)"
+---
+
+# Audit: Accessibility & Motion
+
+**Role:** WCAG 2.1 Compliance Auditor & Interaction Designer
+
+**Objective:** Perform an exhaustive, multi-layered accessibility audit. Do not limit yourself to the items listed — explore the file structure dynamically and execute terminal commands to uncover deep-seated issues.
+
+---
+
+## Pre-Flight
+
+Before starting, confirm:
+- The local dev server is running at http://localhost:3000 (required for axe runtime scan)
+- Install tooling if absent: `npm install -D @axe-core/cli`
+
+---
+
+## Audit Workflow
+
+You MUST follow all phases in order. **Do NOT implement any fixes before the Stop & Review stage.**
+
+---
+
+### Phase 1: Static Analysis
+
+Inspect the codebase using Grep, Glob, and Read tools. Discover files dynamically — do not assume locations.
+
+**1. Runtime Accessibility Scan**
+- Run: `npx axe http://localhost:3000 --reporter=json`
+- If the server isn't running, note this and skip to static analysis. Record the error log.
+- Report all WCAG 2.1 Level AA violations with element selectors and impact levels.
+- Also test key inner pages if accessible (e.g., a product page, a form page).
+
+**2. Semantic HTML & Heading Hierarchy**
+- Scan component files for:
+  - More than one `<h1>` per page (should be exactly one per route)
+  - Skipped heading levels (e.g., `<h1>` → `<h3>` with no `<h2>` in between)
+  - Use of `<div>` or `<span>` for structural content that should be `<section>`, `<article>`, `<aside>`, `<nav>`, or `<main>`
+  - Missing `<main>` landmark in root layout
+
+**3. Interactive Elements**
+- Search for `onClick` handlers on non-interactive elements (`div`, `span`, `p`).
+- For each: verify a keyboard-accessible alternative exists (`role="button"` + `tabIndex={0}` + `onKeyDown`).
+- Check modals and dialogs for focus-trapping: when a modal opens, keyboard focus must stay inside it.
+- Verify all interactive elements have visible focus styles (not `outline: none` without a replacement).
+
+**4. Motion & Animation (Framer Motion)**
+- Search the codebase for `framer-motion`, `motion.`, and `AnimatePresence`.
+- For every animated component, verify:
+  - Content is visible without JavaScript (CSS-based initial visibility or `initial` state set to visible)
+  - No critical content is hidden by `opacity: 0` or `y: 40` with no CSS fallback
+  - Animations respect `prefers-reduced-motion` — check for `useReducedMotion()` hook or a media query check
+- Flag any animation where the initial state hides content that may not animate in (e.g., if JS fails).
+
+**5. Images & Alt Text**
+- Scan for `<img>` tags and `<Image>` / `<PrismicNextImage>` components.
+- Flag any image without an `alt` attribute.
+- Flag images with `alt=""` that appear to be meaningful (not decorative).
+- Check icon buttons: verify they have `aria-label` if the icon carries meaning.
+
+**6. Form Accessibility**
+- Inspect all form components. Verify:
+  - Every `<input>`, `<select>`, `<textarea>` has an associated `<label>` (via `htmlFor` or `aria-label`)
+  - Error messages are associated with their input via `aria-describedby`
+  - Required fields use `aria-required="true"` or the `required` attribute
+  - Success/error state changes are announced to screen readers (via `role="alert"` or `aria-live`)
+
+**7. Skip Navigation**
+- Verify a "Skip to main content" link exists and is the first focusable element on the page.
+
+---
+
+### Phase 2: Research (Run in Parallel)
+
+**First**, read `.agents/patterns/accessibility-motion.md` if it exists. Use it as a baseline — skip re-researching topics already covered unless the file is older than 3 months.
+
+Launch a research subagent to fetch current best practices. The subagent should search for:
+- WCAG 2.1 Level AA compliance checklist (2025–2026)
+- Framer Motion `prefers-reduced-motion` implementation patterns
+- Next.js 15 accessibility best practices
+- Focus management in React modals and dialogs
+
+Compile findings as a reference list with URLs.
+
+**Then**, create or update `.agents/patterns/accessibility-motion.md` with any new research findings, best practices, code examples, and reference URLs. Pattern files should be refreshed every 3 months to stay current with evolving standards.
+
+---
+
+### Phase 3: Findings & Checklist
+
+Combine Phase 1 and Phase 2 results. For every issue found:
+- Assign a severity: **CRITICAL** / **HIGH** / **MEDIUM** / **LOW**
+- Include the exact file path and line number where possible
+- State the recommended fix
+
+Save the full audit report to `.agents/audits/accessibility-motion-{YYYY-MM-DD}.md`.
+
+Also create a condensed implementation checklist at `.agents/checklist/accessibility-motion-{YYYY-MM-DD}.md` — group items by severity tier with commit-and-review gates between each tier. After implementing each tier: stage all changes (`git add`) but do **NOT** commit. Tell the user the changes are staged for review, and **wait for explicit approval** before proceeding to the next tier. The user will review the diff, commit themselves, and tell the agent when to continue. Reference existing files in `.agents/checklist/` for the pattern.
+
+Save the full audit report to `.agents/audits/accessibility-motion-{YYYY-MM-DD}.md`:
+
+```markdown
+# Accessibility & Motion Audit — {date}
+
+## Summary
+Brief overview of audit scope and key findings.
+
+## Research References
+- [Source](url) — why it's relevant
+
+## Findings Checklist
+
+- [ ] **[CRITICAL]** Missing alt text on hero image — `src/slices/Hero/HeroDefault.tsx:18`
+  - Fix: Add `alt` field to PrismicNextImage from Prismic metadata
+- [ ] **[HIGH]** onClick on `<div>` without keyboard handler — `src/ui/components/Card/CardDefault.tsx:34`
+  - Fix: ...
+
+## Command Outputs
+- `npx axe http://localhost:3000`: {result summary or error log}
+```
+
+---
+
+### 🛑 STOP & REVIEW
+
+**Do not proceed past this point until the user explicitly approves.**
+
+Present to the user:
+1. The full findings checklist
+2. Each proposed fix with file and line reference
+3. Research references used
+
+Then ask:
+> "I've completed the Accessibility & Motion audit. The checklist has been saved to `.agents/audits/accessibility-motion-{date}.md`. Shall I proceed with implementing the fixes above?"
+
+**Wait for explicit confirmation before continuing.**
+
+---
+
+### Phase 4: Implementation
+
+After user approval, implement each approved fix in priority order. For each fix:
+- Make the change using Edit tools
+- Run `npm run check` after every meaningful change
+- **Update the checklist immediately** — mark completed items with `[x]` in `.agents/checklist/accessibility-motion-{YYYY-MM-DD}.md` as each item is implemented, not at the end
+- If the user skips or rejects an item, add it to the **Skipped / Rejected Changes** section at the bottom of the checklist using a heading + bullet format per item (e.g., `### #N — Item name` with `- **Status:**` and `- **Reason:**`)
+
+---
+
+### Phase 5: Update Checklist
+
+After all tiers are complete:
+- Verify every item is accounted for: completed `[x]`, deferred `[ ]` with reason, or logged in the Skipped / Rejected Changes section
+- Update the status line:
+```
+## Status: {Complete / Partially Complete — N items deferred, M items skipped}
+```
+- If any items were skipped or rejected, save the Skipped / Rejected Changes section to `.agents/checklist/skipped/accessibility-motion-{YYYY-MM-DD}.md` so future audits don't re-suggest rejected changes

package/template/.claude/commands/audit-analytics-conversion.md

@@ -0,0 +1,149 @@
+---
+description: "Run an Analytics & Conversion Tracking audit on the current project (Module 7)"
+---
+
+# Audit: Analytics & Conversion
+
+**Role:** Marketing Technologist & Data Architect
+
+**Objective:** Perform an exhaustive audit of data layer integrity, tracking accuracy, and consent compliance. Do not limit yourself to the items listed — explore the file structure dynamically and run terminal commands to find deep-seated issues.
+
+---
+
+## Audit Workflow
+
+You MUST follow all phases in order. **Do NOT implement any fixes before the Stop & Review stage.**
+
+---
+
+### Phase 1: Static Analysis
+
+Inspect the codebase using Grep, Glob, and Read tools. Discover files dynamically — do not assume locations.
+
+**1. Data Layer Audit**
+- Search for `dataLayer.push(` across all files. If found:
+  - List every push call with its event name and payload shape
+  - Check event naming consistency: are they `camelCase`, `snake_case`, or mixed? Flag inconsistencies
+  - Verify no PII (email addresses, phone numbers, names) is passed in dataLayer objects or as URL parameters
+- If `dataLayer` is not used, identify the analytics platform in use (Plausible, Google Analytics, Segment, etc.) and audit its equivalent tracking calls
+
+**2. Plausible / Custom Analytics Audit**
+- Search for `plausible(` or equivalent analytics event calls
+- For each event call, verify:
+  - The event fires after a successful action (API response, not just on click)
+  - Event names are consistent (e.g., all camelCase: `formSubmissionContact`, not mixed with `form_submission_contact`)
+  - No PII is passed in the event payload or goal properties
+- Check if all 8 form types have analytics events on successful submission
+- Verify file downloads are tracked (e.g., application images, product manuals)
+
+**3. Conversion Event Attribution**
+- Search for form submission handlers. For each form:
+  - Confirm the analytics event fires only after a successful API response (not on click, not on form submit before validation)
+  - Verify error states do NOT trigger conversion events
+  - Check that the success message is shown before/alongside the event fire (not delayed by tracking)
+
+**4. Consent Integration**
+- Verify tracking scripts respect user consent state.
+- Check if analytics providers are only initialized after consent is granted.
+- Search for any tracking call that fires unconditionally on page load (before consent resolution).
+
+**5. Custom Tracking Hooks**
+- Search for custom analytics hooks (e.g., `useAnalytics`, `useTracking`, `usePlausible`).
+- If found, verify:
+  - They check consent state before firing events
+  - They are used consistently across all form types and key interactions
+  - There are no redundant event fires (same event triggered twice)
+
+**6. URL Parameter PII Check**
+- Search for `router.push`, `redirect()`, and `window.location` usage.
+- Flag any case where email, phone, or name values are appended to URL query strings.
+
+---
+
+### Phase 2: Research (Run in Parallel)
+
+**First**, read `.agents/patterns/analytics-conversion.md` if it exists. Use it as a baseline — skip re-researching topics already covered unless the file is older than 3 months.
+
+Launch a research subagent to fetch current best practices. The subagent should search for:
+- Plausible Analytics event tracking best practices (2025–2026)
+- GDPR-compliant analytics implementation patterns
+- Google Consent Mode V2 and analytics firing order
+- Attribution best practices: tracking on API success vs click
+
+Compile findings as a reference list with URLs.
+
+**Then**, create or update `.agents/patterns/analytics-conversion.md` with any new research findings, best practices, code examples, and reference URLs. Pattern files should be refreshed every 3 months to stay current with evolving standards.
+
+---
+
+### Phase 3: Findings & Checklist
+
+Combine Phase 1 and Phase 2 results. For every issue found:
+- Assign a severity: **CRITICAL** / **HIGH** / **MEDIUM** / **LOW**
+- Include the exact file path and line number
+- State the recommended fix
+
+Save the full audit report to `.agents/audits/analytics-conversion-{YYYY-MM-DD}.md`.
+
+Also create a condensed implementation checklist at `.agents/checklist/analytics-conversion-{YYYY-MM-DD}.md` — group items by severity tier with commit-and-review gates between each tier. After implementing each tier: stage all changes (`git add`) but do **NOT** commit. Tell the user the changes are staged for review, and **wait for explicit approval** before proceeding to the next tier. The user will review the diff, commit themselves, and tell the agent when to continue. Reference existing files in `.agents/checklist/` for the pattern.
+
+Save the full audit report to `.agents/audits/analytics-conversion-{YYYY-MM-DD}.md`:
+
+```markdown
+# Analytics & Conversion Audit — {date}
+
+## Summary
+Brief overview of analytics platform(s) in use, forms tracked, and key findings.
+
+## Research References
+- [Source](url) — why it's relevant
+
+## Findings Checklist
+
+- [ ] **[CRITICAL]** Email address passed in analytics event payload — `src/ui/components/Form/ContactForm.tsx:87`
+  - Fix: Remove `email` field from Plausible event properties
+- [ ] **[HIGH]** Analytics event fires on form submit, not on API success — `src/ui/components/Form/DemoForm.tsx:102`
+  - Fix: Move `plausible()` call inside the `.then()` block of the API response
+
+## Command Outputs
+- Analytics event search: {files found / not found}
+- PII URL parameter check: {result}
+```
+
+---
+
+### 🛑 STOP & REVIEW
+
+**Do not proceed past this point until the user explicitly approves.**
+
+Present to the user:
+1. The full findings checklist
+2. Each proposed fix with file and line reference
+3. Research references used
+
+Then ask:
+> "I've completed the Analytics & Conversion audit. The checklist has been saved to `.agents/audits/analytics-conversion-{date}.md`. Shall I proceed with implementing the fixes above?"
+
+**Wait for explicit confirmation before continuing.**
+
+---
+
+### Phase 4: Implementation
+
+After user approval, implement each approved fix in priority order. For each fix:
+- Make the change using Edit tools
+- Run `npm run check` after every meaningful change
+- **Update the checklist immediately** — mark completed items with `[x]` in `.agents/checklist/analytics-conversion-{YYYY-MM-DD}.md` as each item is implemented, not at the end
+- If the user skips or rejects an item, add it to the **Skipped / Rejected Changes** section at the bottom of the checklist using a heading + bullet format per item (e.g., `### #N — Item name` with `- **Status:**` and `- **Reason:**`)
+
+---
+
+### Phase 5: Update Checklist
+
+After all tiers are complete:
+- Verify every item is accounted for: completed `[x]`, deferred `[ ]` with reason, or logged in the Skipped / Rejected Changes section
+- Update the status line:
+```
+## Status: {Complete / Partially Complete — N items deferred, M items skipped}
+```
+- If any items were skipped or rejected, save the Skipped / Rejected Changes section to `.agents/checklist/skipped/analytics-conversion-{YYYY-MM-DD}.md` so future audits don't re-suggest rejected changes

package/template/.claude/commands/audit-code-maintainability.md

@@ -0,0 +1,149 @@
+---
+description: "Run a Code Maintainability audit on the current project (Module 6)"
+---
+
+# Audit: Code Maintainability
+
+**Role:** Lead Developer Experience (DX) Engineer & Software Quality Auditor
+
+**Objective:** Perform an exhaustive audit of code quality, maintainability, and architectural consistency. Do not limit yourself to the items listed — explore the file structure dynamically and run terminal commands to uncover deep-seated issues.
+
+---
+
+## Audit Workflow
+
+You MUST follow all phases in order. **Do NOT implement any fixes before the Stop & Review stage.**
+
+---
+
+### Phase 1: Static Analysis & Tooling
+
+**1. Linting & Formatting**
+- Run: `npx biome check .`
+- Record the full output. Identify the top 3–5 recurring architectural or style violations.
+- Note any rules that are disabled project-wide — evaluate if they should be re-enabled.
+- Run: `npm run check` (project-specific lint command if configured). Record results.
+
+**2. Cyclomatic Complexity — Large Files**
+- Search for files exceeding 250 lines of code. List all flagged files with their line counts.
+- For each large file, review:
+  - Can it be split into smaller, focused modules?
+  - Does it have a single clear responsibility?
+  - Are there nested conditionals or deeply branched logic that could be simplified?
+
+**3. DRY Violations — Duplicate Patterns**
+- Scan CMS slice/blok components for repeated data-transformation patterns:
+  - Repeated theme resolution logic (should use a shared utility)
+  - Repeated URL/link building logic
+  - Repeated date formatting or data-shaping code
+  - Near-identical component structures that differ by only one prop
+- Flag any utility function or hook that is copy-pasted across 3+ files instead of being shared.
+
+**4. Type Safety**
+- Search for TypeScript `any` usage across the codebase. Flag files with multiple `any` annotations.
+- Check for missing return types on exported functions.
+- Verify that `strict: true` is active in `tsconfig.json`.
+- Flag use of `// @ts-ignore` or `// @ts-expect-error` — each should have a documented reason.
+
+**5. Dead Code**
+- Search for exported functions, components, or types that appear unused across the codebase.
+- Identify commented-out code blocks that should be removed.
+- Check for `console.log`, `console.warn`, or `console.error` statements left in production code.
+
+**6. Dependency Health**
+- Review `package.json`. Flag:
+  - Packages listed in both `dependencies` and `devDependencies`
+  - Packages with `*` or overly loose version ranges
+  - Packages that appear unused (not imported anywhere in `src/`)
+
+---
+
+### Phase 2: Research (Run in Parallel)
+
+**First**, read `.agents/patterns/code-maintainability.md` if it exists. Use it as a baseline — skip re-researching topics already covered unless the file is older than 3 months.
+
+Launch a research subagent to fetch current best practices. The subagent should search for:
+- Biome 2.x configuration best practices (2025–2026)
+- Next.js 15 code organization and maintainability patterns
+- TypeScript strict mode best practices
+- DRY principles for CMS-driven React component architectures
+
+Compile findings as a reference list with URLs.
+
+**Then**, create or update `.agents/patterns/code-maintainability.md` with any new research findings, best practices, code examples, and reference URLs. Pattern files should be refreshed every 3 months to stay current with evolving standards.
+
+---
+
+### Phase 3: Findings & Checklist
+
+Combine Phase 1 and Phase 2 results. For every issue found:
+- Assign a severity: **CRITICAL** / **HIGH** / **MEDIUM** / **LOW**
+- Include the exact file path and line numbers
+- State the recommended fix
+
+Save the full audit report to `.agents/audits/code-maintainability-{YYYY-MM-DD}.md`.
+
+Also create a condensed implementation checklist at `.agents/checklist/code-maintainability-{YYYY-MM-DD}.md` — group items by severity tier with commit-and-review gates between each tier. After implementing each tier: stage all changes (`git add`) but do **NOT** commit. Tell the user the changes are staged for review, and **wait for explicit approval** before proceeding to the next tier. The user will review the diff, commit themselves, and tell the agent when to continue. Reference existing files in `.agents/checklist/` for the pattern.
+
+Save the full audit report to `.agents/audits/code-maintainability-{YYYY-MM-DD}.md`:
+
+```markdown
+# Code Maintainability Audit — {date}
+
+## Summary
+Brief overview of audit scope and key findings.
+
+## Research References
+- [Source](url) — why it's relevant
+
+## Findings Checklist
+
+- [ ] **[HIGH]** Theme resolution duplicated in 6 slice files — should use shared `getThemeClass()` — `src/slices/`
+  - Fix: Ensure all slices import from `src/lib/utils.ts` — remove inline logic
+- [ ] **[MEDIUM]** File exceeds 250 lines — `src/ui/components/Form/ContactForm.tsx` (312 lines)
+  - Fix: Extract form field components into separate files
+
+## Command Outputs
+- `npx biome check .`: {top violations summary or error log}
+- `npm run check`: {result}
+```
+
+---
+
+### 🛑 STOP & REVIEW
+
+**Do not proceed past this point until the user explicitly approves.**
+
+Present to the user:
+1. The full findings checklist
+2. Each proposed fix with file and line reference
+3. The top recurring Biome violations
+4. Research references used
+
+Then ask:
+> "I've completed the Code Maintainability audit. The checklist has been saved to `.agents/audits/code-maintainability-{date}.md`. Shall I proceed with implementing the fixes above?"
+
+**Wait for explicit confirmation before continuing.**
+
+---
+
+### Phase 4: Implementation
+
+After user approval, implement each approved fix in priority order. For each fix:
+- Make the change using Edit tools
+- Run `npm run check` after every meaningful change
+- For refactors that touch multiple files, verify imports are correct after changes
+- **Update the checklist immediately** — mark completed items with `[x]` in `.agents/checklist/code-maintainability-{YYYY-MM-DD}.md` as each item is implemented, not at the end
+- If the user skips or rejects an item, add it to the **Skipped / Rejected Changes** section at the bottom of the checklist using a heading + bullet format per item (e.g., `### #N — Item name` with `- **Status:**` and `- **Reason:**`)
+
+---
+
+### Phase 5: Update Checklist
+
+After all tiers are complete:
+- Verify every item is accounted for: completed `[x]`, deferred `[ ]` with reason, or logged in the Skipped / Rejected Changes section
+- Update the status line:
+```
+## Status: {Complete / Partially Complete — N items deferred, M items skipped}
+```
+- If any items were skipped or rejected, save the Skipped / Rejected Changes section to `.agents/checklist/skipped/code-maintainability-{YYYY-MM-DD}.md` so future audits don't re-suggest rejected changes