@invisibleloop/pulse 0.16.0 → 0.17.1

package/src/agent/identity.md

@@ -14,7 +14,7 @@ Every page you ship must meet all of the following. These are not aspirational
 
 **Lighthouse 100 on Accessibility, Best Practices, and SEO.** The \`lighthouse_audit\` tool returns these three scores — all must be 100. If any cannot hit 100, something is wrong with the spec. (Performance is not part of the audit tool and is not required.) The audit is slow — ~30–60 s per run. Always tell the user before calling it.
 
-**Polished and considered.** Use the component library — `button`, `card`, `input`, `alert`, `stat`, `empty`, `table`, and the rest. Use the spacing scale (`u-mt-*`, `u-gap-*`, `u-py-*`). Use the type scale (`u-text-xl`, `u-font-semibold`). Use the colour tokens (`var(--ui-accent)`, `var(--ui-muted)`). Do not leave raw unstyled HTML. Do not invent a layout from scratch when the grid, stack, cluster, container, and section components already solve it.
+**Polished and considered.** Use the component library — `button`, `card`, `input`, `alert`, `stat`, `empty`, `table`, and the rest. Use the spacing scale (`u-mt-*`, `u-gap-*`, `u-py-*`). Use the type scale (`u-text-xl`, `u-font-semibold`). Use the colour tokens (`var(--ui-accent)`, `var(--ui-muted)`). Do not leave raw unstyled HTML. Do not invent a layout from scratch when the grid, stack, cluster, container, and section components already solve it — *unless you have declared a creative override (see "Design Freedom" below), in which case a custom layout is the deliberate, correct choice.*
 
 **Works correctly on first load.** SSR is always on. The page must be readable and navigable before any JavaScript executes. Do not build pages that require client JS to render content.
 
@@ -22,15 +22,30 @@ Every page you ship must meet all of the following. These are not aspirational
 
 **Accessible form labels.** Every `input`, `select`, and `textarea` has a label. Every form has a submit button. Required fields are marked required. Error messages are associated with the field that caused them.
 
+# Design Freedom — The Rule
+
+There are two valid build modes. Knowing which one you are in tells you exactly which rules apply.
+
+**Mode A — components first (the default).** All standard UI patterns come from the component library. The component rules in "What You Will Not Do" below apply in full. This is the right mode for most pages.
+
+**Mode B — creative override.** When the design intent genuinely calls for it — a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe that components would constrain, or a layout a component simply cannot reproduce — you may build with raw HTML throughout. This is a deliberate design decision available to you, not a rule violation and not a shortcut. To use it:
+
+1. **Declare it in a comment at the top of the spec:** `// component-free — creative override: <reason>`. The review tool reads this comment from the source file — announcing the mode in chat is not enough.
+2. Functional atoms (`button`, `input`, `badge`, `modal`) still come from components unless there is a specific design reason not to.
+3. `/pulse-ui.css` stays in `meta.styles` — your custom CSS builds on its token system.
+4. The pass bar changes: instead of the component checklist, **Lighthouse 100 on Accessibility, Best Practices, and SEO, desktop and mobile**, plus CLS 0.00. A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+
+The component rules marked *(Mode A)* below are suspended under a declared creative override. Everything else — accessibility, security, testing, escaping, error handling — applies in both modes, always.
+
 # What You Will Not Do
 
 - Install client-side JS dependencies. No React, Vue, Alpine, htmx, Tailwind, Lodash, Axios, or any other package that runs in the browser. Pulse handles rendering, state, actions, navigation, and SSR. If you need a utility, write it.
 - Use emoji characters in UI output. Use icons from the icon library instead — `iconCheck`, `iconStar`, `iconZap`, etc. If the right icon does not exist, create it in `src/ui/icons.js` following the existing pattern (see the guide for how). Emoji are not accessible, are not theme-aware, and render inconsistently across platforms.
-- Hardcode hex colours in CSS. Use `var(--ui-*)` tokens. They cascade through every component automatically and make theming possible.
-- Use inline `style=""` attributes. Use utility classes or `var(--ui-*)` tokens in a stylesheet.
-- Write raw `<button>`, `<input>`, `<select>`, or `<textarea>` HTML when the component library already provides accessible, styled versions.
-- Write raw `<h1>`–`<h6>` without styling. Use `heading({ level, text })` instead.
-- Write raw `<ul>` or `<ol>` without styling. Use `list({ items })` instead.
+- Hardcode hex colours in CSS. Use `var(--ui-*)` tokens — they cascade through every component automatically and make theming possible. The one place hex values belong is `public/theme.css`, as token *definitions*; every other stylesheet references them via `var()`. A lint hook enforces this.
+- Use inline `style=""` attributes. Use utility classes or `var(--ui-*)` tokens in a stylesheet. *Exception:* structural image styles with no utility-class equivalent (`aspect-ratio`, `object-fit`) are permitted inline — these are layout facts, not theming, and the design gallery uses them this way.
+- Write raw `<button>`, `<input>`, `<select>`, or `<textarea>` HTML when the component library already provides accessible, styled versions. *(Mode A — under a creative override, functional atoms should still come from components unless there is a specific design reason.)*
+- Write raw `<h1>`–`<h6>` without styling. Use `heading({ level, text })` instead. *(Mode A)*
+- Write raw `<ul>` or `<ol>` without styling. Use `list({ items })` instead. *(Mode A)*
 - Output CMS or database HTML without a `prose()` wrapper. Raw HTML from external sources has no styling — always wrap it in `prose({ content: html })`.
 - Use `data-event` on text inputs. Re-rendering on every keystroke destroys focus. Use uncontrolled inputs and read values from `FormData` in `action.onStart` or `action.run`.
 - Skip `onError` in an action. It is required. Always handle failure.

package/src/agent/skills/build-page/SKILL.md

@@ -40,11 +40,11 @@ Write the spec file. Follow these rules:
 
 Use `pulse_validate` on the spec. Fix any errors before continuing.
 
-### 5. Register with the server
+### 5. Restart and reload
 
-Check the project's server entry file (e.g. `src/server.js` or `pulse.config.js`) and add the new spec if needed.
+Pages under `src/pages/` are auto-discovered — no server entry file to edit. Call `pulse_restart_server`, then `navigate_page` so the browser is not on a stale tab.
 
-### 6. Screenshot
+### 6. Screenshot + design approval
 
 Use the chrome-devtools navigate_page tool to load the page, then take_screenshot.
 
@@ -53,13 +53,15 @@ Check for:
 - Layout looks correct
 - No console errors via list_console_messages
 
+Then ask the user: *"Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?"* — use your host's question tool if it has one (e.g. AskUserQuestion); it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end. **Do not proceed until the user explicitly approves.** If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
+
 ### 7. Lighthouse
 
-Run lighthouse_audit (desktop, then mobile). All four scores — Accessibility, Best Practices, SEO, Performance — must be 100 before continuing.
+Run lighthouse_audit (desktop, then mobile) against the production server — call `pulse_build` first and navigate to the production URL. **Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Performance is reported but not gated (it varies with machine load).
 
 ### 8. Run the checklist
 
-Go through `.github/instructions/pulse-checklist.instructions.md` and confirm every applicable point passes. Fix anything that fails.
+Go through `.claude/pulse-checklist.md` and confirm every applicable point passes. Fix anything that fails.
 
 ### 9. Write tests
 

package/src/agent/skills/verify/SKILL.md

@@ -34,8 +34,8 @@ Navigate to the page route with `mcp__chrome-devtools__navigate_page`, then take
 **If `pulse_intake` ran earlier in this session** (i.e. this is a new page or site, not an edit or bug fix):
 
 1. Show the screenshot to the user.
-2. Ask: *"Happy with the layout and direction, or any changes before I run Lighthouse?"*
-3. **Stop and wait for their response.** Do not proceed to step 4b or Lighthouse until the user explicitly approves.
+2. Ask: *"Happy with the layout and direction, or any changes before I run Lighthouse?"* — use your host's question tool if it has one (e.g. AskUserQuestion); it waits for the answer without ending the turn. If you must ask in plain prose and end your turn, call `pulse_await_approval` first so the Stop hooks let the turn end.
+3. **Stop and wait for their response.** Do not proceed to step 4b or Lighthouse until the user explicitly approves. If a `VERIFY REQUIRED` stop-hook block fires while your question is unanswered, that is not permission to continue — call `pulse_await_approval`, re-ask, and end your turn.
 
 If the user requests changes: make edits, restart the server, take a new screenshot, describe what changed, ask again. Repeat until approved. No Lighthouse between design rounds.
 

package/src/agent/workflow.md

@@ -59,6 +59,8 @@ If the user's request is already very specific (a one-liner edit, a bug fix, "ad
 
 Call `pulse_list_structure` to see what already exists. Fetch only the guide sections relevant to your intent (the `pulse_intent` response tells you which ones).
 
+**Check `src/components/` for shared sections before building.** If a layout, nav, footer, CTA strip, or section you're about to write already exists there — or already exists inline in another spec — reuse or extract it now rather than writing a second copy. Catching duplication here is cheap; catching it at review (phase 7) means the expensive gates already ran against the duplicated version.
+
 Do not fetch every guide section for every task. Fetch what you need.
 
 ---
@@ -73,7 +75,7 @@ Decide the complexity tier (see below) and confirm with the user if the task is
 
 **Skip confirmation for trivially small tasks** (add a button, fix a label, swap a component). When in doubt, confirm.
 
-**When asking the user questions:** ask one question at a time. If you present choices, use at most 4 options — the `ask_user` tool enforces this limit and will error if exceeded. For open-ended questions (names, copy, features, hex colours), ask as plain prose with no choices at all.
+**When asking the user questions:** ask one question at a time. If you present choices, use at most 4 options — question tools in agent hosts (e.g. Claude Code's AskUserQuestion) cap the number of choices and will error if exceeded. For open-ended questions (names, copy, features, hex colours), ask as plain prose with no choices at all.
 
 ---
 
@@ -157,15 +159,18 @@ Or use the guide-components table. Never write these patterns from scratch in Mo
 
 If you're about to type `class="hero"` or `class="product-card"` in Mode A, stop — use the component instead.
 
+**Reuse across specs (both modes):** one spec = one page; a site is many specs sharing code. Before writing a new section, check `src/components/` — and if a section you're writing already exists in another spec, extract it to `src/components/` *now* and import it from both, rather than pasting a copy. Same for CSS: a shared section's styles go in the shared `app.css` (listed in `meta.styles` by every spec that uses it), never duplicated into per-page stylesheets.
+
 **Mode B — Creative override (raw HTML throughout)**
 When the design intent calls for a more expressive, unconventional, or typographically-driven layout that components would constrain, you may build with raw HTML throughout. This is a deliberate design decision, not a shortcut.
 
 Rules for Mode B:
+- **Declare it in a comment at the top of the spec file:** `// component-free — creative override: <reason>`. The review tool detects creative override by reading this comment from the source — without it, `pulse_review` will flag every component pattern as a violation even though you chose Mode B deliberately. Announcing the mode in chat is not enough; the comment must be in the file.
 - Load `/pulse-ui.css` in `meta.styles` — the token system is still required
 - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason
-- The quality gate is 100/100/100/100 Lighthouse on both desktop and mobile — this replaces the component checklist as the pass bar
+- The quality gate is Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop and mobile) plus CLS 0.00 — this replaces the component checklist as the pass bar. Performance is reported but not gated.
 
-Announce Mode B explicitly in the build brief: *"Mode B — component-free, raw HTML for creative control."*
+Announce Mode B explicitly in the build brief (*"Mode B — component-free, raw HTML for creative control"*) **and** write the override comment into the spec.
 
 ### 3b — Announce before writing
 
@@ -235,6 +240,12 @@ Do this before every screenshot, console check, or visual inspection. Never debu
 3. **Ask the user directly:** *"Happy with the layout and direction, or any changes before I run tests and Lighthouse?"*
 4. **Wait for their response before doing anything else.** Do not run design_review, layout_review, or Lighthouse until you have a clear go-ahead.
 
+**How to wait without tripping the Stop hooks.** The project's Stop hooks (missing tests, coverage, verify stamp) block any turn that ends with unverified spec edits — they cannot tell "abandoning the work" from "pausing for the user's answer". So:
+
+- **Preferred:** ask the question with your host's question tool (e.g. AskUserQuestion in Claude Code). A question tool waits for the answer *without ending the turn*, so the Stop hooks never fire.
+- **Otherwise:** call `pulse_await_approval` immediately before asking in plain prose and ending your turn. It writes a one-turn marker the Stop hooks respect; the marker is consumed when the user replies.
+- **Never** respond to a `VERIFY REQUIRED` block by running `/verify` while your approval question is unanswered. The block does not override the approval gate — an unanswered question means the design is not approved, and Lighthouse on an unapproved design wastes ~90 seconds and pre-empts the user's changes.
+
 **If the user requests changes:**
 - Make the edits
 - Take a new screenshot

package/src/cli/scaffold.js

@@ -188,12 +188,26 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
           ]
         }
       ],
+      UserPromptSubmit: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              // Consume the awaiting-approval marker: it grants exactly one turn-end
+              // (the one that asks the user a blocking question). As soon as the user
+              // replies, the Stop gates are back in force for the next turn.
+              command: `node -e "try{require('fs').unlinkSync('.pulse-awaiting-approval')}catch{}"`,
+              statusMessage: 'Clearing approval pause...',
+            }
+          ]
+        }
+      ],
       Stop: [
         {
           hooks: [
             {
               type: 'command',
-              command: `node -e "const fs=require('fs');const{execSync}=require('child_process');let changed=new Set();let hasGit=false;try{execSync('git rev-parse --is-inside-work-tree',{stdio:'pipe'});hasGit=true;execSync('git status --porcelain',{encoding:'utf8'}).split('\\n').forEach(l=>{const f=l.slice(3).trim().split(' -> ').pop();if(f)changed.add(f);});}catch{}if(!hasGit&&fs.existsSync('src/pages')){for(const f of fs.readdirSync('src/pages')){if(f.endsWith('.js')&&!f.endsWith('.test.js'))changed.add('src/pages/'+f);}}const specs=[...changed].filter(f=>f.match(/^src\\/pages\\/.+\\.js$/)&&!f.endsWith('.test.js'));const missing=specs.filter(f=>{const t=f.replace(/\\.js$/,'.test.js');return!fs.existsSync(t)&&!changed.has(t);});if(missing.length){process.stdout.write(JSON.stringify({decision:'block',reason:'TESTS MISSING: '+missing.join(', ')+' — you must write tests before finishing. Use renderSync/render from @invisibleloop/pulse/testing to test view output, mutations, and any extracted logic functions. Run the tests with node to confirm they pass.'}));}"`,
+              command: `node -e "const fs=require('fs');if(fs.existsSync('.pulse-awaiting-approval'))process.exit(0);const{execSync}=require('child_process');let changed=new Set();let hasGit=false;try{execSync('git rev-parse --is-inside-work-tree',{stdio:'pipe'});hasGit=true;execSync('git status --porcelain',{encoding:'utf8'}).split('\\n').forEach(l=>{const f=l.slice(3).trim().split(' -> ').pop();if(f)changed.add(f);});}catch{}if(!hasGit&&fs.existsSync('src/pages')){for(const f of fs.readdirSync('src/pages')){if(f.endsWith('.js')&&!f.endsWith('.test.js'))changed.add('src/pages/'+f);}}const specs=[...changed].filter(f=>f.match(/^src\\/pages\\/.+\\.js$/)&&!f.endsWith('.test.js'));const missing=specs.filter(f=>{const t=f.replace(/\\.js$/,'.test.js');return!fs.existsSync(t)&&!changed.has(t);});if(missing.length){process.stdout.write(JSON.stringify({decision:'block',reason:'TESTS MISSING: '+missing.join(', ')+' — you must write tests before finishing. Use renderSync/render from @invisibleloop/pulse/testing to test view output, mutations, and any extracted logic functions. Run the tests with node to confirm they pass.\\n\\nEXCEPTION — waiting on the user: if you are ending this turn to wait for the user\\'s answer (e.g. the design-approval gate), call pulse_await_approval first, then ask and end your turn. Do not write tests or run /verify on an unapproved design.'}));}"`,
               statusMessage: 'Checking for missing tests...',
             },
             {
@@ -203,7 +217,7 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
             },
             {
               type: 'command',
-              command: `node -e "const fs=require('fs');const{execSync}=require('child_process');let specs=[];try{const out=execSync('git status --porcelain',{encoding:'utf8'});out.split('\\n').forEach(l=>{const f=l.slice(3).trim().split(' -> ').pop();if(f&&f.match(/^src\\/pages\\/.+\\.js$/)&&!f.endsWith('.test.js'))specs.push(f);});}catch{if(fs.existsSync('src/pages'))for(const f of fs.readdirSync('src/pages')){if(f.endsWith('.js')&&!f.endsWith('.test.js'))specs.push('src/pages/'+f);}}if(!specs.length)process.exit(0);const stamp='.pulse-verified';let stampMtime=0;try{stampMtime=fs.statSync(stamp).mtimeMs;}catch{}const stale=specs.filter(f=>{try{return fs.statSync(f).mtimeMs>stampMtime;}catch{return true;}});if(stale.length){process.stdout.write(JSON.stringify({decision:'block',reason:'VERIFY REQUIRED: These pages have not been verified since last edit:\\n'+stale.map(f=>'  '+f).join('\\n')+'\\n\\nRun /verify for each changed page. /verify runs Lighthouse (desktop + mobile), performance trace, console check, and code review — then writes the stamp that clears this check.'}));}"`,
+              command: `node -e "const fs=require('fs');if(fs.existsSync('.pulse-awaiting-approval'))process.exit(0);const{execSync}=require('child_process');let specs=[];try{const out=execSync('git status --porcelain',{encoding:'utf8'});out.split('\\n').forEach(l=>{const f=l.slice(3).trim().split(' -> ').pop();if(f&&f.match(/^src\\/pages\\/.+\\.js$/)&&!f.endsWith('.test.js'))specs.push(f);});}catch{if(fs.existsSync('src/pages'))for(const f of fs.readdirSync('src/pages')){if(f.endsWith('.js')&&!f.endsWith('.test.js'))specs.push('src/pages/'+f);}}if(!specs.length)process.exit(0);const stamp='.pulse-verified';let stampMtime=0;try{stampMtime=fs.statSync(stamp).mtimeMs;}catch{}const stale=specs.filter(f=>{try{return fs.statSync(f).mtimeMs>stampMtime;}catch{return true;}});if(stale.length){process.stdout.write(JSON.stringify({decision:'block',reason:'VERIFY REQUIRED: These pages have not been verified since last edit:\\n'+stale.map(f=>'  '+f).join('\\n')+'\\n\\nIMPORTANT — check first: are you ending this turn to wait for the user\\'s answer (e.g. the design-approval question)? If so, do NOT run /verify — the user has not approved the design yet. Call pulse_await_approval, re-ask your question, and end your turn; this gate will let you stop.\\n\\nOtherwise run /verify for each changed page. /verify runs Lighthouse (desktop + mobile), performance trace, console check, and code review — then writes the stamp that clears this check.'}));}"`,
               statusMessage: 'Checking verification stamp...',
             }
           ]
@@ -217,6 +231,8 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
     'node_modules',
     'public/dist',
     '.pulse-build',
+    '.pulse-verified',
+    '.pulse-awaiting-approval',
     '.DS_Store',
     '# Intake images — local design references, not committed',
     'public/intake/*.jpg',

package/src/html.js

@@ -21,4 +21,5 @@ export function escHtml(str) {
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
 }

package/src/mcp/mcp.test.js

@@ -102,6 +102,177 @@ test('no orphaned guide.md (monolithic legacy file should not exist)', () => {
   )
 })
 
+// ── Duplicated doc sync ──────────────────────────────────────────────────────
+// Several agent docs exist in two places (a canonical source plus a copy that is
+// scaffolded into consumer projects or kept in this repo's own .claude/). These
+// pairs must stay byte-identical or the two audiences receive drifting rules.
+
+console.log('\nDuplicated doc sync\n')
+
+const SYNC_PAIRS = [
+  ['src/agent/checklist.md',        '.claude/pulse-checklist.md'],
+  ['src/agent/checklist.md',        'docs/.claude/pulse-checklist.md'],
+  ['src/agent/checklist.md',        'examples/.claude/pulse-checklist.md'],
+  ['src/agent/commands/verify.md',  '.claude/commands/verify.md'],
+]
+
+for (const [a, b] of SYNC_PAIRS) {
+  test(`${a} is in sync with ${b}`, () => {
+    const fa = path.join(ROOT, a)
+    const fb = path.join(ROOT, b)
+    assert(fs.existsSync(fa), `${a} does not exist`)
+    assert(fs.existsSync(fb), `${b} does not exist`)
+    assert(
+      fs.readFileSync(fa, 'utf8') === fs.readFileSync(fb, 'utf8'),
+      `${a} and ${b} have drifted apart. Edit the canonical file and copy it over the other ` +
+      `(cp ${a} ${b} or vice versa) so both audiences get the same rules.`
+    )
+  })
+}
+
+// ── Agent doc consistency guards ─────────────────────────────────────────────
+// Contradictions between agent docs leave the agent unable to know what it can
+// and cannot do. These guards pin the resolved decisions:
+//   - The Lighthouse pass bar is THREE gated scores (Accessibility, Best
+//     Practices, SEO) — Performance is reported, never gated. "100/100/100/100"
+//     reintroduces a four-score bar the audit tooling cannot verify.
+//   - "ask_user" is not a real tool in any host — docs must not name it.
+//   - Emoji are banned in UI output — design guides must not suggest them.
+
+console.log('\nAgent doc consistency\n')
+
+const agentDocs = [
+  ...fs.readdirSync(agentDir).filter(f => f.endsWith('.md')).map(f => path.join('src/agent', f)),
+  ...fs.readdirSync(path.join(agentDir, 'commands')).filter(f => f.endsWith('.md')).map(f => path.join('src/agent/commands', f)),
+  ...fs.readdirSync(path.join(agentDir, 'skills')).flatMap(d => {
+    const p = path.join(agentDir, 'skills', d, 'SKILL.md')
+    return fs.existsSync(p) ? [path.join('src/agent/skills', d, 'SKILL.md')] : []
+  }),
+  '.claude/commands/build-page.md',
+  '.claude/commands/verify.md',
+  '.claude/commands/new-doc-page.md',
+  'CLAUDE.md',
+  'README.md',
+]
+
+test('no agent doc states a four-score Lighthouse bar (100/100/100/100)', () => {
+  const fourScore = (src) =>
+    src.includes('100/100/100/100') ||
+    /all four (scores|categories)/i.test(src) ||
+    /Accessibility, Best Practices, SEO,? and Performance[^.\n]*must (all )?be 100/i.test(src)
+  const offenders = agentDocs.filter(f =>
+    fs.existsSync(path.join(ROOT, f)) &&
+    fourScore(fs.readFileSync(path.join(ROOT, f), 'utf8'))
+  )
+  if (fourScore(serverSrc)) offenders.push('src/mcp/server.js')
+  assert(
+    offenders.length === 0,
+    `Four-score Lighthouse bar found in: ${offenders.join(', ')}. ` +
+    `The gated scores are Accessibility, Best Practices, and SEO (three) — Performance is reported, not gated.`
+  )
+})
+
+test('no agent doc references a literal ask_user tool', () => {
+  const offenders = agentDocs.filter(f =>
+    fs.existsSync(path.join(ROOT, f)) &&
+    /\bask_user\b/.test(fs.readFileSync(path.join(ROOT, f), 'utf8'))
+  )
+  assert(
+    offenders.length === 0,
+    `"ask_user" referenced in: ${offenders.join(', ')}. ` +
+    `No host exposes a tool by that name — phrase host-agnostically (e.g. "your host's question tool").`
+  )
+})
+
+test('design guides do not suggest emoji in UI output', () => {
+  const designGuides = ['src/agent/guide-design-references.md', 'src/agent/guide-design-gallery.md']
+  const offenders = designGuides.filter(f => {
+    const src = fs.readFileSync(path.join(ROOT, f), 'utf8')
+    // Allow lines that mention emoji only to ban them; flag lines that suggest using them
+    return src.split('\n').some(line =>
+      /emoji/i.test(line) && !/never|not |banned|instead of emoji/i.test(line)
+    )
+  })
+  assert(
+    offenders.length === 0,
+    `Emoji suggested (without a ban qualifier) in: ${offenders.join(', ')}. ` +
+    `Emoji are banned in UI output (identity.md) — suggest icon-library glyphs instead.`
+  )
+})
+
+test('workflow.md Mode B instructs writing the creative-override spec comment', () => {
+  const workflow = fs.readFileSync(path.join(agentDir, 'workflow.md'), 'utf8')
+  assert(
+    /component.free — creative override/.test(workflow),
+    'workflow.md Mode B must instruct writing the `// component-free — creative override: <reason>` ' +
+    'comment into the spec — pulse_review detects creative override by reading the source file.'
+  )
+})
+
+test('checklist points cross-spec shared components at src/components/, not src/ui/', () => {
+  const checklist = fs.readFileSync(path.join(agentDir, 'checklist.md'), 'utf8')
+  assert(
+    !/shared component in `src\/ui\/`/.test(checklist),
+    'checklist.md tells the agent to create shared components in src/ui/ — that is the ' +
+    'framework\'s own library inside the package. Project-level shared code goes in src/components/.'
+  )
+  assert(
+    /shared component in `src\/components\/`/.test(checklist),
+    'checklist.md must direct cross-spec shared components to src/components/.'
+  )
+})
+
+test('guide-spec.md states the one-spec-per-page mental model', () => {
+  const guideSpec = fs.readFileSync(path.join(agentDir, 'guide-spec.md'), 'utf8')
+  assert(
+    /one spec per page/i.test(guideSpec) && /dynamic route is still one spec/i.test(guideSpec),
+    'guide-spec.md must state the mental model explicitly: one spec = one route = one file, ' +
+    'and a dynamic route is still one spec serving many URLs.'
+  )
+})
+
+test('approval pause mechanism is wired end to end', () => {
+  // The design-approval gate requires the agent to end its turn and wait for the
+  // user — but the scaffolded Stop hooks block any turn ending with unverified
+  // edits. Without an escape hatch the hooks steamroll the approval gate (the
+  // agent gets blocked, reads "Run /verify", and proceeds without an answer).
+  const scaffoldSrc = fs.readFileSync(path.join(ROOT, 'src/cli/scaffold.js'), 'utf8')
+  const coverageSrc = fs.readFileSync(path.join(agentDir, 'coverage-check.js'), 'utf8')
+  const workflow    = fs.readFileSync(path.join(agentDir, 'workflow.md'), 'utf8')
+
+  // 1. The MCP server must expose the tool that writes the marker
+  assert(/registerTool\(\s*'pulse_await_approval'/.test(serverSrc),
+    'server.js must register pulse_await_approval')
+
+  // 2. Every inline Stop hook in the scaffold must early-exit on the marker
+  const stopHookCount   = (scaffoldSrc.match(/decision:'block'/g) || []).length
+  const markerCheckCount = (scaffoldSrc.match(/\.pulse-awaiting-approval'\)\)process\.exit\(0\)/g) || []).length
+  assert(stopHookCount >= 2 && markerCheckCount >= stopHookCount,
+    `scaffold.js has ${stopHookCount} blocking Stop hooks but only ${markerCheckCount} check ` +
+    `.pulse-awaiting-approval — every blocking Stop hook must allow the approval pause.`)
+
+  // 3. coverage-check.js (the third Stop hook) must early-exit on the marker
+  assert(coverageSrc.includes('.pulse-awaiting-approval'),
+    'coverage-check.js must early-exit when .pulse-awaiting-approval exists')
+
+  // 4. The marker must be consumed when the user replies — one turn-end only
+  assert(/UserPromptSubmit/.test(scaffoldSrc) && /unlinkSync\('\.pulse-awaiting-approval'\)/.test(scaffoldSrc),
+    'scaffold.js must register a UserPromptSubmit hook that deletes .pulse-awaiting-approval')
+
+  // 5. The workflow must teach the mechanism at the design-approval gate
+  assert(workflow.includes('pulse_await_approval'),
+    'workflow.md Phase 5a must explain how to pause: host question tool preferred, pulse_await_approval otherwise')
+})
+
+test('identity.md declares the creative override (Design Freedom) carve-out', () => {
+  const identity = fs.readFileSync(path.join(agentDir, 'identity.md'), 'utf8')
+  assert(
+    /creative override/i.test(identity),
+    'identity.md must include the creative-override carve-out — without it the persona ' +
+    'unconditionally bans raw HTML that workflow.md Mode B explicitly permits.'
+  )
+})
+
 // ── Result ───────────────────────────────────────────────────────────────────
 
 console.log(`\n${passed} passed, ${failed} failed\n`)

package/src/mcp/server.js

@@ -1081,7 +1081,7 @@ ${(() => {
   // Creative override detection — check if spec declares component-free mode
   const creativeOverride = /component.free|creative\s+override|raw\s+HTML\s+throughout/i.test(source)
   checks.push(creativeOverride
-    ? '⚡ **Creative override declared** — component pattern checks are advisory only. Lighthouse 100/100/100/100 is the pass bar.'
+    ? '⚡ **Creative override declared** — component pattern checks are advisory only. Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop + mobile) plus CLS 0.00 is the pass bar.'
     : '○ No creative override declared — component checks apply')
 
   return checks.join('\n')
@@ -1122,7 +1122,7 @@ Work through every item. Fix anything that fails. Refer to the spec source at ${
 
   If no creative override is declared and a component *could* reproduce the design, refactor to use it. Custom utility classes on top of components are fine (\`hero({ ... })\` + override CSS) — but do not write the entire structure from scratch when the component supports the layout.
 
-- [ ] **Creative override** (fill in if applicable): *State the override reason here — e.g. "full-viewport gradient hero not achievable with hero() component"*. Confirm Lighthouse 100/100/100/100 desktop and mobile passes before closing the review.
+- [ ] **Creative override** (fill in if applicable): *State the override reason here — e.g. "full-viewport gradient hero not achievable with hero() component"*. Confirm Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop and mobile) plus CLS 0.00 before closing the review.
 - [ ] No \`data-event\` on text inputs — this destroys focus on every keystroke
 - [ ] No \`className\`, \`htmlFor\`, \`onClick=\`, or other React patterns
 - [ ] No hardcoded hex colours in view — only \`var(--ui-*)\` tokens (anchor \`href="#id"\` values are fine — those are not colours)
@@ -1203,6 +1203,33 @@ The stop hook compares each changed spec's mtime against this stamp. Any spec ne
   }
 )
 
+// ---------------------------------------------------------------------------
+// pulse_await_approval
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  'pulse_await_approval',
+  {
+    description: `Pause the workflow to wait for the user's answer — call this immediately BEFORE ending your turn with a blocking question (e.g. the design-approval gate: "Happy with the layout and direction…?").
+
+It writes a .pulse-awaiting-approval marker that tells the Stop hooks (missing tests, coverage, verify stamp) to let this one turn end without demanding /verify first. The marker is deleted automatically when the user sends their next message — the gates return in full force for your following turn.
+
+**Prefer your host's question tool if it has one** (e.g. AskUserQuestion in Claude Code): a question tool waits for the answer *without ending the turn*, so the Stop hooks never fire and this marker is unnecessary. Use pulse_await_approval only when you must ask in plain prose and end the turn.
+
+Do NOT use this to skip verification — it buys exactly one turn-end, paired with a question the user must answer. Calling it without asking anything just delays the gates by one message.`,
+    inputSchema: {},
+  },
+  () => {
+    const markerPath = path.join(ROOT, '.pulse-awaiting-approval')
+    try {
+      fs.writeFileSync(markerPath, String(Math.floor(Date.now() / 1000)), 'utf8')
+      return text('✓ Awaiting-approval marker written. Ask the user your question and end your turn — the Stop hooks will allow it. The marker is cleared when the user replies.')
+    } catch (err) {
+      return text(`Error writing .pulse-awaiting-approval: ${err.message}\nFallback: run \`touch .pulse-awaiting-approval\` in Bash, then ask your question.`)
+    }
+  }
+)
+
 // ---------------------------------------------------------------------------
 // pulse_run_tests
 // ---------------------------------------------------------------------------

package/src/md/index.js

@@ -25,6 +25,33 @@ function esc(s) {
     .replace(/"/g, '"')
 }
 
+/**
+ * Sanitise a markdown link/image URL.
+ *
+ * Allows http(s), mailto, tel, relative paths, fragment/query refs, and
+ * image data: URIs. Any other scheme — notably javascript:, vbscript:, and
+ * non-image data: URIs — is neutralised to '#', preventing XSS when markdown
+ * comes from an untrusted source (database, user submission, external API).
+ *
+ * The value has already passed through esc(), so it is safe to embed in an
+ * attribute; this guard only blocks dangerous URL schemes.
+ *
+ * @param {string} url
+ * @param {boolean} [isImage=false] - permit image data: URIs when true
+ * @returns {string}
+ */
+function safeUrl(url, isImage = false) {
+  // Strip leading control chars/whitespace that browsers ignore when parsing
+  // the scheme (e.g. "java\tscript:"), then test for a scheme prefix.
+  const stripped = url.replace(/[\x00-\x20]+/g, '')
+  const scheme   = stripped.match(/^([a-zA-Z][a-zA-Z0-9+.\-]*):/)
+  if (!scheme) return url  // no scheme → relative / fragment / query, safe
+  const proto = scheme[1].toLowerCase()
+  if (proto === 'http' || proto === 'https' || proto === 'mailto' || proto === 'tel') return url
+  if (isImage && /^data:image\/(png|jpe?g|gif|webp|avif|svg\+xml);/i.test(stripped)) return url
+  return '#'
+}
+
 // ---------------------------------------------------------------------------
 // Frontmatter — --- key: value --- block at top of file
 // ---------------------------------------------------------------------------
@@ -69,12 +96,12 @@ function renderInline(raw) {
   // 3. Images (before links — same syntax with leading !)
   s = s.replace(/!\[([^\]]*)\]\(([^)\s"]+)(?:\s+"([^"]*)")?\)/g,
     (_, alt, src, title) =>
-      `<img src="${src}" alt="${alt}"${title ? ` title="${title}"` : ''}>`)
+      `<img src="${safeUrl(src, true)}" alt="${alt}"${title ? ` title="${title}"` : ''}>`)
 
   // 4. Links
   s = s.replace(/\[([^\]]+)\]\(([^)\s"]+)(?:\s+"([^"]*)")?\)/g,
     (_, label, href, title) =>
-      `<a href="${href}"${title ? ` title="${title}"` : ''}>${label}</a>`)
+      `<a href="${safeUrl(href)}"${title ? ` title="${title}"` : ''}>${label}</a>`)
 
   // 5. Bold + italic (order: *** before ** before *)
   s = s.replace(/\*{3}([^*\n]+)\*{3}/g, (_, t) => `<strong><em>${t}</em></strong>`)

package/src/md/md.test.js

@@ -175,6 +175,42 @@ test('HTML is escaped in inline text', () => {
   assert(html.includes('<script>'), `Got: ${html}`)
 })
 
+// --- URL scheme sanitisation (XSS) -----------------------------------------
+
+test('link with javascript: scheme is neutralised to #', () => {
+  const { html } = parseMd('[x](javascript:alert(1))')
+  assert(!html.toLowerCase().includes('javascript:'), `Got: ${html}`)
+  assert(html.includes('href="#"'), `Got: ${html}`)
+})
+
+test('javascript: scheme neutralised regardless of case', () => {
+  const { html } = parseMd('[x](JaVaScRiPt:alert(1))')
+  assert(!html.toLowerCase().includes('javascript:'), `Got: ${html}`)
+})
+
+test('image with javascript: scheme is neutralised', () => {
+  const { html } = parseMd('![i](javascript:alert(1))')
+  assert(!html.toLowerCase().includes('javascript:'), `Got: ${html}`)
+  assert(html.includes('src="#"'), `Got: ${html}`)
+})
+
+test('non-image data: URI in image is neutralised', () => {
+  const { html } = parseMd('![i](data:text/html,<script>alert(1)</script>)')
+  assert(html.includes('src="#"'), `Got: ${html}`)
+})
+
+test('image data: URI is allowed', () => {
+  const { html } = parseMd('![i](data:image/png;base64,iVBOR)')
+  assert(html.includes('src="data:image/png;base64,iVBOR"'), `Got: ${html}`)
+})
+
+test('safe schemes and relative/fragment URLs are preserved', () => {
+  for (const url of ['https://ok.com', 'http://ok.com', '/relative', '#frag', 'mailto:a@b.com', 'tel:+15551234']) {
+    const { html } = parseMd(`[x](${url})`)
+    assert(html.includes(`href="${url}"`), `Expected ${url} preserved, got: ${html}`)
+  }
+})
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/src/runtime/ssr.js

@@ -621,4 +621,5 @@ function esc(str) {
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
 }

package/src/runtime/tt.js

@@ -4,6 +4,14 @@
  * everywhere else — behaviour is identical, the protection is simply absent.
  *
  * Policy name 'pulse' must match the trusted-types CSP directive on the server.
+ *
+ * SECURITY NOTE: createHTML/createScriptURL are intentional pass-throughs. The
+ * framework owns the HTML it renders, so this policy does NOT sanitise — it
+ * exists to satisfy `require-trusted-types-for 'script'` and to confine HTML
+ * sinks to a single audited policy (preventing *other* code on the page from
+ * creating its own policy). It is NOT a defence against unescaped user data in
+ * a view: view authors remain responsible for escaping untrusted values with
+ * escHtml() before interpolating them into markup.
  */
 
 let _policy = null