@invisibleloop/pulse 0.17.0 → 0.17.1

package/.claude/commands/build-page.md

@@ -50,7 +50,7 @@ Check for:
 - Layout looks correct
 - No console errors via `mcp__chrome-devtools__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?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — run tests and Lighthouse", "I'd like some changes first"]`; otherwise ask in plain prose.
+Then ask the user: "Happy with the design and layout, or would you like any changes before I run tests and Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — run tests and Lighthouse", "I'd like some changes first"]`; 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. 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.
 
 **Do not proceed to step 7 until the user explicitly confirms.** If they want changes, make them and return to step 6.
 

package/.claude/commands/verify.md

@@ -15,8 +15,8 @@ If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify
 If this is a new page build (came through `pulse_intake` or `build-page`):
 
 1. Take a screenshot and describe what you see to the user.
-2. Ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; otherwise ask in plain prose.
-3. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved.
+2. Ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; 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. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved. 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.
 
 ### 3. Validate the spec
 

package/.claude/pulse-checklist.md

@@ -66,8 +66,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```js
   const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
   ```
-- **Create a shared component in `src/ui/` when the same pattern is needed across 2 or more different specs.** Follow the existing pattern: a named export that returns an HTML string.
-- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Wait until the third use before extracting.
+- **Create a shared component in `src/components/` when the same pattern is needed across 2 or more different specs.** A named export that returns an HTML string — same shape as the `layout()` pattern in the routing guide. Never paste a section's HTML into a second spec: extract it at the second use, then import it from both. (`src/ui/` is the framework's own library inside the package — project-level shared code always goes in `src/components/`.)
+- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Within a single spec, wait until the third use before extracting a helper; across specs, extract at the second use.
 
 ### Correctness
 
@@ -106,6 +106,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **`app.css` must contain no hex values or raw colour values.** A lint hook enforces this and will block the build. Hex values belong in `public/theme.css` as token definitions; `app.css` references them via `var()` only.
 - **Load order in `meta.styles`:** `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must be defined before `app.css` references them.
+- **CSS for a shared section lives in the shared `app.css`, once.** Every spec that renders the section lists the same file in `meta.styles`. Never copy a CSS block into a second per-page stylesheet — two copies drift apart. Per-page stylesheets are for styles only one page uses.
 
 ### Security
 

package/CLAUDE.md

@@ -6,7 +6,7 @@ Pulse is a spec-first frontend framework. The spec is the source of truth. No co
 
 ```bash
 npm run dev    # start dev server at http://localhost:3000 (pulse_build serves production on 3001)
-npm test       # run all 92 unit tests
+npm test       # run the full unit test suite
 npm run build  # bundle for production → public/dist/
 ```
 
@@ -37,6 +37,8 @@ public/
 
 A spec is a plain JS object. Every property is optional except `route` and `view`. `state` defaults to `{}` — omit it on purely server-rendered pages.
 
+**One spec = one page = one file.** A site is multiple specs, one per route. A dynamic route (`route: '/blog/:slug'`) is still a single spec serving every matching URL — never one spec per item, and never several pages folded into one spec with `ctx` conditionals. Shared sections live in `src/components/` and are imported by each spec.
+
 ```js
 export const mySpec = {
   route:   '/path',           // URL pattern, supports :params
@@ -360,6 +362,8 @@ There are two CSS files and they have distinct roles — do not mix them:
 
 **`app.css` must never contain hex values.** `rgba()` and `hsla()` are allowed for translucency — but if the same translucent colour is used more than once, extract it as a token in `theme.css` (e.g. `--brand-overlay-12: rgba(0,0,0,0.12)`). If you need to define or override a colour token, put it in `public/theme.css` and reference it via `var()` in `app.css`.
 
+**CSS for a section used by more than one spec lives in the shared `app.css`, once** — every spec that renders the section lists the same file in `meta.styles`. Never copy a CSS block into a second per-page stylesheet; two copies drift. Per-page stylesheets are only for styles a single page uses.
+
 ```css
 /* public/theme.css — hex values live here */
 [data-theme="light"] {

package/README.md

@@ -7,7 +7,6 @@ Write a plain JavaScript object that describes what a page does. Pulse handles r
 ```js
 export default {
   route: '/counter',
-  hydrate: '/src/pages/counter.js',
   meta: {
     title: 'Counter',
     styles: ['/app.css'],
@@ -54,7 +53,7 @@ Full documentation: **[pulseframework.dev](https://pulseframework.dev)**
 
 **The spec is the source of truth.** Every page is a single JS object — data fetching, state, mutations, async actions, and view all in one place. No separate files for routes, controllers, or templates.
 
-**Performance is built in.** Streaming SSR, immutable asset caching, and zero layout shift are automatic. Every scaffolded project targets Lighthouse 100 across all four categories.
+**Performance is built in.** Streaming SSR, immutable asset caching, and zero layout shift are automatic. Every scaffolded project targets Lighthouse 100 for Accessibility, Best Practices, and SEO — and is fast by design (streaming HTML before data resolves, CLS 0.00).
 
 **No client-side dependencies.** Pulse ships no runtime framework to the browser — only a small hydration bundle (~2 kB brotli) that binds your spec's mutations and actions to the DOM.
 
@@ -83,12 +82,13 @@ Full reference at [pulseframework.dev](https://pulseframework.dev):
 - **Guard** — authentication and authorisation before data fetches
 - **Validation & constraints** — declarative form validation and state bounds
 - **Raw responses** — RSS feeds, sitemaps, JSON APIs
+- **Markdown** — built-in parser for blog posts and docs pages, zero browser JS
 - **Performance** — how the framework hits Lighthouse 100
 - **UI components** — 50+ built-in components
 
 ## Status
 
-This is an early-access release. The core architecture is stable and production-quality, but the API may evolve before v1. Feedback and issues welcome on [GitHub](https://github.com/invisibleloop/pulse).
+This is an early-access release. The core architecture is stable and production-quality, but the API may evolve before v1. Feedback and issues welcome on [GitHub](https://github.com/invisibleloop/pulse-framework).
 
 ## License
 

package/docs/.claude/pulse-checklist.md

@@ -66,8 +66,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```js
   const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
   ```
-- **Create a shared component in `src/ui/` when the same pattern is needed across 2 or more different specs.** Follow the existing pattern: a named export that returns an HTML string.
-- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Wait until the third use before extracting.
+- **Create a shared component in `src/components/` when the same pattern is needed across 2 or more different specs.** A named export that returns an HTML string — same shape as the `layout()` pattern in the routing guide. Never paste a section's HTML into a second spec: extract it at the second use, then import it from both. (`src/ui/` is the framework's own library inside the package — project-level shared code always goes in `src/components/`.)
+- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Within a single spec, wait until the third use before extracting a helper; across specs, extract at the second use.
 
 ### Correctness
 
@@ -106,6 +106,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **`app.css` must contain no hex values or raw colour values.** A lint hook enforces this and will block the build. Hex values belong in `public/theme.css` as token definitions; `app.css` references them via `var()` only.
 - **Load order in `meta.styles`:** `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must be defined before `app.css` references them.
+- **CSS for a shared section lives in the shared `app.css`, once.** Every spec that renders the section lists the same file in `meta.styles`. Never copy a CSS block into a second per-page stylesheet — two copies drift apart. Per-page stylesheets are for styles only one page uses.
 
 ### Security
 

package/docs/src/pages/project-structure.js

@@ -82,6 +82,8 @@ export default {
       ${section('one-file-per-page', 'One file per page')}
       <p>Pulse enforces <strong>one spec per file</strong>. Every page is self-contained — state, view, mutations, actions, and validation in one place. This is not a style preference. It is how the framework eliminates the question of where things live.</p>
 
+      <p>This holds for dynamic routes too: <code>route: '/blog/:slug'</code> is <strong>one spec serving every matching URL</strong> — the <code>:param</code> does the multiplying, so a thousand blog posts are still a single file. A site is therefore a small collection of specs, one per route, sharing layouts and sections from <code>src/components/</code> rather than repeating them.</p>
+
       ${callout('tip', 'For large pages, view fragments and helpers can be imported from other modules. The spec file remains the coordination point — the structure is always clear regardless of how the implementation is organised.')}
     `,
   }),

package/examples/.claude/pulse-checklist.md

@@ -66,8 +66,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```js
   const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
   ```
-- **Create a shared component in `src/ui/` when the same pattern is needed across 2 or more different specs.** Follow the existing pattern: a named export that returns an HTML string.
-- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Wait until the third use before extracting.
+- **Create a shared component in `src/components/` when the same pattern is needed across 2 or more different specs.** A named export that returns an HTML string — same shape as the `layout()` pattern in the routing guide. Never paste a section's HTML into a second spec: extract it at the second use, then import it from both. (`src/ui/` is the framework's own library inside the package — project-level shared code always goes in `src/components/`.)
+- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Within a single spec, wait until the third use before extracting a helper; across specs, extract at the second use.
 
 ### Correctness
 
@@ -106,6 +106,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **`app.css` must contain no hex values or raw colour values.** A lint hook enforces this and will block the build. Hex values belong in `public/theme.css` as token definitions; `app.css` references them via `var()` only.
 - **Load order in `meta.styles`:** `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must be defined before `app.css` references them.
+- **CSS for a shared section lives in the shared `app.css`, once.** Every spec that renders the section lists the same file in `meta.styles`. Never copy a CSS block into a second per-page stylesheet — two copies drift apart. Per-page stylesheets are for styles only one page uses.
 
 ### Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.17.0
+0.17.1

package/src/agent/checklist.md

@@ -66,8 +66,8 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```js
   const card = ({ title, body }) => `<div class="card"><h3>${title}</h3><p>${body}</p></div>`
   ```
-- **Create a shared component in `src/ui/` when the same pattern is needed across 2 or more different specs.** Follow the existing pattern: a named export that returns an HTML string.
-- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Wait until the third use before extracting.
+- **Create a shared component in `src/components/` when the same pattern is needed across 2 or more different specs.** A named export that returns an HTML string — same shape as the `layout()` pattern in the routing guide. Never paste a section's HTML into a second spec: extract it at the second use, then import it from both. (`src/ui/` is the framework's own library inside the package — project-level shared code always goes in `src/components/`.)
+- **Do not abstract a pattern that appears only once.** Duplication is cheaper than the wrong abstraction. Within a single spec, wait until the third use before extracting a helper; across specs, extract at the second use.
 
 ### Correctness
 
@@ -106,6 +106,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **`app.css` must contain no hex values or raw colour values.** A lint hook enforces this and will block the build. Hex values belong in `public/theme.css` as token definitions; `app.css` references them via `var()` only.
 - **Load order in `meta.styles`:** `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must be defined before `app.css` references them.
+- **CSS for a shared section lives in the shared `app.css`, once.** Every spec that renders the section lists the same file in `meta.styles`. Never copy a CSS block into a second per-page stylesheet — two copies drift apart. Per-page stylesheets are for styles only one page uses.
 
 ### Security
 

package/src/agent/commands/verify.md

@@ -15,8 +15,8 @@ If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify
 If this is a new page build (came through `pulse_intake` or `build-page`):
 
 1. Take a screenshot and describe what you see to the user.
-2. Ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; otherwise ask in plain prose.
-3. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved.
+2. Ask the user: "Happy with the design and layout, or would you like any changes before I run Lighthouse?" — if your host provides a question tool (e.g. AskUserQuestion), offer the choices `["Yes, looks good — proceed", "I'd like some changes first"]`; 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. **Do not proceed to step 3 until the user explicitly confirms.** If they want changes, stop here, make the changes, then restart from step 2. Lighthouse takes ~90 seconds — do not waste it on a design the user hasn't approved. 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.
 
 ### 3. Validate the spec
 

package/src/agent/coverage-check.js

@@ -13,6 +13,11 @@
 import { execSync } from 'child_process'
 import fs from 'fs'
 
+// Agent is ending its turn to wait for the user's answer (design-approval gate) —
+// let the turn end. The marker is consumed on the user's next prompt, so the
+// gates return in full force afterwards.
+if (fs.existsSync('.pulse-awaiting-approval')) process.exit(0)
+
 // No test files → nothing to check
 const hasTests = fs.existsSync('src/pages') && (function scan(d) {
   for (const f of fs.readdirSync(d)) {

package/src/agent/guide-spec.md

@@ -1,5 +1,11 @@
 Pulse is a spec-first frontend framework. Pages are JS files that export a default spec object.
 
+## Mental model — one spec per page
+
+- **One spec = one route = one file** under `src/pages/`. Every page of a site is its own spec file — a site is a collection of specs, not one big spec.
+- **A dynamic route is still one spec.** `route: '/blog/:slug'` is a single file serving *every* blog post URL — the `:param` does the multiplying. Never create one spec per item (`post-1.js`, `post-2.js`, …), and never merge several distinct pages into one spec with conditionals on `ctx`.
+- **Specs share code, they don't repeat it.** Shared sections, layouts, nav, and footer live in `src/components/` and are imported by each spec that needs them (see `pulse://guide/routing` for the `layout()` pattern).
+
 ## Spec structure
 
 ```js

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.
 
 ---
@@ -157,6 +159,8 @@ 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.
 
@@ -236,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/mcp/mcp.test.js

@@ -152,14 +152,19 @@ const agentDocs = [
   '.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)) &&
-    fs.readFileSync(path.join(ROOT, f), 'utf8').includes('100/100/100/100')
+    fourScore(fs.readFileSync(path.join(ROOT, f), 'utf8'))
   )
-  if (serverSrc.includes('100/100/100/100')) offenders.push('src/mcp/server.js')
+  if (fourScore(serverSrc)) offenders.push('src/mcp/server.js')
   assert(
     offenders.length === 0,
     `Four-score Lighthouse bar found in: ${offenders.join(', ')}. ` +
@@ -204,6 +209,61 @@ test('workflow.md Mode B instructs writing the creative-override spec comment',
   )
 })
 
+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(

package/src/mcp/server.js

@@ -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
 // ---------------------------------------------------------------------------