agentic-ads-engine 0.1.0 → 0.2.0

package/README.md

@@ -2,25 +2,26 @@
 
 Offline tools for ad drafts. Node 20 or later. Plain JavaScript ESM with JSDoc, no build step, and zero runtime dependencies.
 
-## Quick start
-
-Run from this checkout:
+## Install
 
 ```sh
-node bin/agentic-ads list-templates
-node bin/agentic-ads list-hooks
-node bin/agentic-ads lint --copy 'Browse available listings'
-node bin/agentic-ads plan --site demo --goal discovery --dry-run
-node test/e2e.mjs
+npm install agentic-ads-engine        # library and CLI in a project
+npm install -g agentic-ads-engine     # the agentic-ads and agentic-ads-mcp commands
 ```
 
-The package is not published by this task. To install the local package:
+## Quick start
 
 ```sh
-npm install /path/to/agentic-ads-engine
-npx agentic-ads plan
+npx agentic-ads list-templates
+npx agentic-ads hooks
+npx agentic-ads lint --copy 'Browse available listings'
+npx agentic-ads plan --site demo --goal discovery --dry-run
+npx agentic-ads serve --port 8787     # HTTP API, loopback only unless AGENTIC_ADS_TOKEN is set
+npx agentic-ads-mcp                   # MCP server over stdio
 ```
 
+From a git checkout, use `node bin/agentic-ads ...` and run `node test/e2e.mjs` for the tests.
+
 CLI output is JSON. Exit codes: `0` for a result, `1` for invalid input, and `2` for blocked copy.
 `lint` requires `--copy`. It accepts `--category housing|none`; the default is `housing`.
 `plan` accepts `--site`, `--goal`, `--template`, `--ratio`, `--copy`, and `--category`.
@@ -99,10 +100,10 @@ News framing, staging, and urgency also require review. Conservative checks can
 The package does not inspect actual audience settings or implement current platform policy in full.
 
 Keep private data out of inputs. Contact-pattern checks are incomplete; they cannot reliably detect names, addresses, or secrets.
-The CLI prints supplied copy in plans. No telemetry, account integration, credentials, or network calls are included.
+The CLI prints supplied copy in plans. No telemetry, account integration, or outbound network calls are included.
 No source assets or competitor copy are bundled. Research informs the formats and disclosure needs only.
 
-The E2E script spawns both executables and a library integration process.
+The E2E script spawns the CLI, MCP server, HTTP server, and a library integration process.
 It records assertions in `test/artifacts/e2e.json`, which Git ignores and npm excludes.
 Run `npm run ci:local` before any future push. Publishing and pushing are separate operator actions.
 
@@ -134,3 +135,91 @@ No paid calls, current price checks, media QA, or platform approval occur here.
 
 Run `node test/mutate-formats.mjs` to repeat the three deliberate faults and restore the files.
 It records failures and the restored pass in `test/artifacts/formats-mutations.json`.
+
+### Owner feedback checks
+
+`agentic-ads qa-rules` lists R1 through R26. Use `agentic-ads qa-rules show R5`
+to read one rule. MCP provides `list_qa_rules` and `get_qa_rule` with an `id` argument.
+
+Each format declares `kinds` and `feedbackRules`. A format plan includes
+`reviewChecklist` entries and the six instructions in `costRatchet`.
+Every entry starts as `NOT CHECKED`. This status blocks shipping.
+A reviewer must record PASS or FAIL with a measured value. Voice and sound fit need the owner's ear.
+
+The JavaScript API exports `listRules()`, `getRule(id)`, and `checklistFor(format)`.
+Pass a format descriptor from `getFormat(id)` to `checklistFor`.
+Rules use `blocking` severity. `applies` names format kinds; `all` covers every format.
+Story formats include stickman, POV, before-after, lo-fi, sitcom, and storytime.
+Sitcom has dialogue. Talking-object has visible speech. All current formats have captions.
+
+Run `node test/mutate-qa.mjs` to verify three deliberate faults and restore the files.
+Results go to `test/artifacts/qa-mutations.json` and `test/artifacts/e2e.json`.
+
+## Hook catalog
+
+```sh
+node bin/agentic-ads hooks
+node bin/agentic-ads hooks show shocked-face
+node bin/agentic-ads hooks pick --format pov --emotion curiosity --housing
+```
+
+The catalog contains 42 hooks. Each includes format IDs, emotion, kind, risk, a housing flag, and a short rationale.
+The patterns paraphrase the supplied playbook and style catalog. They include the six requested owner feedback openings.
+No research records, personal data, or account IDs are included.
+
+MCP exposes `list_hooks({format?, emotion?, housing?})`, `get_hook({id})`, and `pick_hooks({format, emotion?, housing?})`.
+CLI and MCP picks return all matching hooks in catalog order, with cold-start scores.
+The original `list-hooks` command and MCP tool still return the whole catalog.
+Format, emotion, and housing filters combine with AND. Invalid filters fail; no matches return an empty list.
+
+The library exports `listHooks`, `getHook`, and `pickHooks(filter, scores = {})`.
+Picks rank matching hooks by descending score. Catalog order resolves ties.
+`selectFor(site, goal, filter = {})` retains its low-risk rule and returns one hook or `null`.
+The original two-argument call still works. Filters apply before score ranking.
+`housing: true` keeps only hooks with `housingSafe: true`. It does not filter by risk level, so medium-risk hooks can still appear.
+
+`housingSafe` means the pattern passes housing lint with generic slot values and contains no eligibility claim, invented number, or testimonial.
+It does not approve arbitrary slot values or rendered media. Fill every slot and lint the final copy before use.
+Every result still requires human review. Personal savings, occupancy, interviews, and broken-trust claims remain outside the housing-safe set.
+
+Run `node test/mutate-hooks.mjs` to verify three single-line faults and restore the catalog.
+Evidence goes to `test/artifacts/hooks-mutations.json`. E2E results go to `test/artifacts/e2e.json`.
+`test/hook-expectations.json` pins every ID and housing flag; review changes to this file explicitly.
+
+## HTTP API for admin sites
+
+Start `node bin/agentic-ads serve`. The defaults are `127.0.0.1:8787`.
+Use `--host H` and `--port N` to change them. Port `0` selects an available port.
+The startup JSON reports the bound port. SIGTERM closes the server and its connections.
+
+```sh
+node bin/agentic-ads serve --port 8787
+curl http://127.0.0.1:8787/health
+curl http://127.0.0.1:8787/v1/formats/sitcom
+curl http://127.0.0.1:8787/v1/qa-rules/R5
+curl -H 'Content-Type: application/json' -d '{"copy":"Browse listings","category":"housing"}' http://127.0.0.1:8787/v1/lint
+curl -H 'Content-Type: application/json' -d '{"format":"sitcom","site":"demo"}' http://127.0.0.1:8787/v1/plan
+```
+
+GET routes: `/health`, `/v1/formats`, `/v1/formats/:id`, `/v1/hooks`, `/v1/templates`,
+`/v1/qa-rules`, and `/v1/qa-rules/:id`. Health returns `{"status":"ok"}`.
+POST routes: `/v1/lint` and `/v1/plan`. Their results match the CLI and MCP tools.
+Blocked lint findings return HTTP 200 with `status: "blocked"`.
+Plans only produce dry-run results. Any `apply` field is refused, including nested fields and query parameters.
+JSON bodies have a 64 KiB limit. Requests have a ten-second timeout.
+Errors return JSON without stacks: 400 invalid input, 401 unauthorized, 403 forbidden host, 404 missing route or item,
+405 wrong method, 408 timeout, 413 oversized body, and 415 unsupported media type.
+
+Set `AGENTIC_ADS_TOKEN` to require `Authorization: Bearer <token>` on every route, including health.
+The token needs 32 or more characters and must not start or end with spaces. Without a token, the server accepts only loopback `Host` values with its own port. This blocks DNS rebinding from a web page.
+A non-loopback host requires this setting. The server never logs bodies or tokens.
+Responses containing the configured token are refused. Use TLS through your admin site's server for remote access.
+
+An admin site's backend can call these routes and keep the token in server-side settings.
+Proxy calls through that backend for browser clients. CORS headers are absent by default.
+`AGENTIC_ADS_CORS_ORIGIN=https://admin.example` allows that exact origin in response headers.
+Unauthenticated browser preflight requests still return 401 when a token is set.
+Direct cross-origin browser calls with bearer headers therefore require the backend proxy.
+
+Run `node test/mutate-api.mjs` to prove authentication, the Host check, the token length rule, body limits, and apply checks detect deliberate faults.
+The script restores the source and writes `test/artifacts/api-mutations.json`.

package/bin/agentic-ads

@@ -2,14 +2,26 @@
 import { execute, tools } from '../src/index.js';
 try {
   let [action, ...argv] = process.argv.slice(2);
+  if (action === 'serve') {
+    await (await import('../src/http.js')).serve(argv);
+  } else {
   const args = {};
+  if (action === 'hooks') {
+    action = argv[0] === 'show' ? 'get_hook' : argv[0] === 'pick' ? 'pick_hooks' : 'list_hooks';
+    if (action === 'get_hook') { argv.shift(); args.id = argv.shift(); }
+    if (action === 'pick_hooks' || argv[0] === 'list') argv.shift();
+  }
+  if (action === 'qa-rules') {
+    action = argv[0] === 'show' ? 'get_qa_rule' : 'list_qa_rules';
+    if (action === 'get_qa_rule') { argv.shift(); args.id = argv.shift(); }
+  }
   if (action === 'formats') {
     action = argv[0] === 'show' ? 'get_format' : 'list_formats';
     if (action === 'get_format') { argv.shift(); args.id = argv.shift(); }
   }
   if (action === 'plan' && argv.some(arg => arg === '--format' || arg.startsWith('--format='))) action = 'plan_format';
   const schema = tools.find(t => t.name === action)?.inputSchema;
-  if (!schema) throw new Error('Use formats, list-templates, list-hooks, lint, or plan');
+  if (!schema) throw new Error('Use hooks, qa-rules, formats, list-templates, list-hooks, lint, plan, or serve');
   while (argv.length) {
     const option = argv.shift(), separator = option.indexOf('=');
     const flag = separator < 0 ? option : option.slice(0, separator);
@@ -31,6 +43,7 @@ try {
   const result = execute(action, args);
   console.log(JSON.stringify(result));
   if (result.status === 'blocked' || result.policy?.status === 'blocked') process.exitCode = 2;
+  }
 } catch (error) {
   console.log(JSON.stringify({ error: error.message })); process.exitCode = 1;
 }

package/bin/agentic-ads-mcp

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { execute, tools } from '../src/index.js';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 // MCP stdio uses one JSON-RPC message per line. stdout is protocol-only.
 const send = message => process.stdout.write(JSON.stringify(message) + '\n');
 const fail = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
@@ -17,7 +19,7 @@ function receive(line) {
   if (method === 'initialize') {
     if (typeof params.protocolVersion !== 'string') { fail(id, -32602, 'Missing protocol version'); return; }
     initialized = true;
-    result = { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'agentic-ads-engine', version: '0.1.0' } };
+    result = { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'agentic-ads-engine', version } };
   } else if (method === 'ping') result = {};
   else if (!initialized) { fail(id, -32002, 'Initialize first'); return; }
   else if (method === 'tools/list') result = { tools };

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "agentic-ads-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Offline ad templates, hook selection, policy lint, and planning tools",
   "type": "module",
   "engines": { "node": ">=20" },
   "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/itsryanarmani/agentic-ads-engine.git" },
+  "homepage": "https://github.com/itsryanarmani/agentic-ads-engine#readme",
+  "bugs": { "url": "https://github.com/itsryanarmani/agentic-ads-engine/issues" },
   "exports": { ".": "./src/index.js", "./formats": "./src/formats/index.js", "./templates": "./src/templates/index.js", "./hooks": "./src/hooks/index.js", "./policy": "./src/policy/index.js", "./providers": "./src/providers/index.js" },
   "bin": { "agentic-ads": "./bin/agentic-ads", "agentic-ads-mcp": "./bin/agentic-ads-mcp" },
   "files": ["src/", "bin/", "README.md", "LICENSE"],

package/src/formats/index.js

@@ -1,3 +1,4 @@
+import { checklistFor, costRatchet } from '../qa/index.js';
 import { readFileSync } from 'node:fs';
 const library = JSON.parse(readFileSync(new URL('./library.json', import.meta.url), 'utf8'));
 const costs = ['free', 'cheap', 'mid', 'expensive'], risks = ['low', 'medium', 'high'];
@@ -28,7 +29,8 @@ export function planFormat(input = {}) {
   const stages = f.stages.map(id => ({ id, provider: f.providers[id], estimatedCostUsd: f.providers[id].estimatedCostUsd }));
   const sum = key => Math.round(stages.reduce((n, s) => n + s.estimatedCostUsd[key], 0) * 1000) / 1000;
   return { format: f.id, site: input.site, goal, dryRun: true, applied: false, spendUsd: 0, stages,
+    reviewChecklist: checklistFor(f), costRatchet,
     qaGates: f.qaGates, policyRisk: f.policyRisk, riskNotes: f.riskNotes,
     total: { low: sum('low'), high: sum('high'), note: f.estimatedCostUsd.note },
-    warnings: ['Plan only; no providers or QA checks run.', 'Historical source review dates are not current price verification.'] };
+    warnings: ['Plan only; no providers or QA checks run.', 'NOT CHECKED blocks shipping. Record PASS or FAIL with a measured value. Voice fit and sound fit need the owner’s ear.', 'Historical source review dates are not current price verification.'] };
 }

package/src/formats/library.json

@@ -1,6 +1,8 @@
 [
   {
     "id": "screen-voiceover",
+    "kinds": ["captions"],
+    "feedbackRules": ["R1", "R6", "R7", "R10", "R12", "R14", "R17", "R18", "R19", "R23"],
     "name": "Screen recording + voiceover",
     "description": "Record a real or generic checklist UI with timed narration.",
     "aspectRatios": ["9:16"],
@@ -18,6 +20,8 @@
   },
   {
     "id": "text-broll",
+    "kinds": ["captions"],
+    "feedbackRules": ["R1", "R6", "R7", "R10", "R12", "R14", "R17", "R18", "R19", "R23"],
     "name": "Text over b-roll",
     "description": "Animate exact caption cards over supplied moving footage.",
     "aspectRatios": ["9:16"],
@@ -35,6 +39,8 @@
   },
   {
     "id": "whiteboard",
+    "kinds": ["captions"],
+    "feedbackRules": ["R1", "R6", "R7", "R10", "R12", "R14", "R17", "R18", "R19", "R23"],
     "name": "Whiteboard doodle",
     "description": "Draw SVG ideas to narration word times.",
     "aspectRatios": ["9:16"],
@@ -52,6 +58,8 @@
   },
   {
     "id": "stickman",
+    "kinds": ["captions", "story", "character"],
+    "feedbackRules": ["R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9", "R10", "R12", "R14", "R15", "R17", "R18", "R19", "R20", "R23", "R26"],
     "name": "Stickman explainer",
     "description": "Animate a shared SVG character through a problem and answer.",
     "aspectRatios": ["9:16"],
@@ -69,6 +77,8 @@
   },
   {
     "id": "pov",
+    "kinds": ["captions", "story", "character"],
+    "feedbackRules": ["R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9", "R10", "R12", "R14", "R15", "R17", "R18", "R19", "R20", "R23", "R26"],
     "name": "POV discovery",
     "description": "Use consistent first-person clips with a title and checklist reveal.",
     "aspectRatios": ["9:16"],
@@ -86,6 +96,8 @@
   },
   {
     "id": "telestrator",
+    "kinds": ["captions"],
+    "feedbackRules": ["R1", "R6", "R7", "R10", "R12", "R14", "R17", "R18", "R19", "R23"],
     "name": "Telestrator annotation",
     "description": "Circle relevant UI details with word-timed SVG strokes.",
     "aspectRatios": ["9:16"],
@@ -103,6 +115,8 @@
   },
   {
     "id": "before-after",
+    "kinds": ["captions", "story"],
+    "feedbackRules": ["R1", "R2", "R5", "R6", "R7", "R9", "R10", "R12", "R14", "R17", "R18", "R19", "R20", "R23", "R26"],
     "name": "Before and after",
     "description": "Wipe from confusing paperwork to an actual checklist.",
     "aspectRatios": ["9:16"],
@@ -120,6 +134,8 @@
   },
   {
     "id": "news-parody",
+    "kinds": ["captions"],
+    "feedbackRules": ["R1", "R6", "R7", "R10", "R12", "R14", "R17", "R18", "R19", "R23"],
     "name": "News parody",
     "description": "Use branded news cards with sourced facts and narration.",
     "aspectRatios": ["9:16"],
@@ -137,6 +153,8 @@
   },
   {
     "id": "lo-fi",
+    "kinds": ["captions", "story", "character", "lo-fi"],
+    "feedbackRules": ["R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9", "R10", "R12", "R14", "R15", "R16", "R17", "R18", "R19", "R20", "R23", "R26"],
     "name": "Handheld lo-fi UGC",
     "description": "Use synthetic handheld scenes and narration with fast reaction cuts.",
     "aspectRatios": ["9:16"],
@@ -154,6 +172,8 @@
   },
   {
     "id": "sitcom",
+    "kinds": ["captions", "story", "character", "dialogue"],
+    "feedbackRules": ["R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9", "R10", "R11", "R12", "R13", "R14", "R15", "R17", "R18", "R19", "R20", "R21", "R22", "R23", "R26"],
     "name": "Multi-camera sitcom",
     "description": "Cut fictional dialogue between shared sets, angles, and silent reactions.",
     "aspectRatios": ["9:16"],
@@ -171,6 +191,8 @@
   },
   {
     "id": "storytime",
+    "kinds": ["captions", "story", "character"],
+    "feedbackRules": ["R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9", "R10", "R12", "R14", "R15", "R17", "R18", "R19", "R20", "R23", "R26"],
     "name": "Storytime twist",
     "description": "A fictional narrator moves from confession to checklist payoff.",
     "aspectRatios": ["9:16"],
@@ -188,6 +210,8 @@
   },
   {
     "id": "talking-object",
+    "kinds": ["captions", "character", "speech"],
+    "feedbackRules": ["R1", "R3", "R4", "R6", "R7", "R8", "R10", "R11", "R12", "R14", "R15", "R17", "R18", "R19", "R20", "R23", "R26"],
     "name": "Talking checklist",
     "description": "Animate an illustrated object mouth to narration.",
     "aspectRatios": ["9:16"],

package/src/hooks/index.js

@@ -1,9 +1,32 @@
+import { getFormat } from '../formats/index.js';
 import { readFileSync } from 'node:fs';
 import { mkdir, readFile, open, rename, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 export const hooks = Object.freeze(JSON.parse(readFileSync(new URL('./library.json', import.meta.url), 'utf8'))
-  .map(hook => Object.freeze({ ...hook, tags: Object.freeze(hook.tags) })));
+  .map(hook => Object.freeze({ ...hook, tags: Object.freeze(hook.tags), formats: Object.freeze(hook.formats) })));
+export const emotions = Object.freeze(['shock', 'fear', 'curiosity', 'relief', 'humor', 'pride']);
+/** Filters combine with AND; returned descriptors are independent copies. */
+export function listHooks(filter = {}) {
+  if (!filter || typeof filter !== 'object' || Array.isArray(filter) ||
+      Object.keys(filter).some(k => !['format', 'emotion', 'housing'].includes(k))) throw new Error('Invalid hook filters');
+  if (filter.format !== undefined) getFormat(filter.format);
+  if (filter.emotion !== undefined && !emotions.includes(filter.emotion)) throw new Error('Invalid emotion');
+  if (filter.housing !== undefined && typeof filter.housing !== 'boolean') throw new Error('Invalid housing filter');
+  return structuredClone(hooks.filter(h => (filter.format === undefined || h.formats.includes(filter.format)) &&
+    (filter.emotion === undefined || h.emotion === filter.emotion) && (!filter.housing || h.housingSafe)));
+}
+export function getHook(id) {
+  const hook = hooks.find(h => h.id === id);
+  if (!hook) throw new Error('Unknown hook: ' + String(id));
+  return structuredClone(hook);
+}
+/** Rank only matching hooks. Catalog order resolves equal scores. */
+export function pickHooks(filter, scores = {}) {
+  if (!filter || filter.format === undefined) throw new Error('Missing required argument: format');
+  validate(scores);
+  return listHooks(filter).sort((a, b) => (scores[b.id] ?? 0) - (scores[a.id] ?? 0));
+}
 function validate(scores) {
   if (!scores || typeof scores !== 'object' || Array.isArray(scores)) throw new Error('Invalid scores');
   for (const [id, value] of Object.entries(scores)) {
@@ -48,11 +71,11 @@ export async function writeScores(directory, site, scores) {
  * @param {{id:string, scores?:Record<string,number>}} site
  * @param {string} goal
  */
-export function selectFor(site, goal) {
+export function selectFor(site, goal, filter = {}) {
   if (!site || typeof site !== 'object' || Array.isArray(site)) throw new Error('Invalid site');
   pathFor('.', site.id);
   const scores = validate(site.scores ?? {});
-  const eligible = hooks.filter(h => h.risk === 'low' && h.tags.includes(goal));
+  const eligible = listHooks(filter).filter(h => h.risk === 'low' && h.tags.includes(goal));
   const ranked = eligible.map((hook, order) => ({ hook, order, score: scores[hook.id] ?? 0 }));
   ranked.sort((a, b) => b.score - a.score || a.order - b.order);
   return ranked.length ? structuredClone(ranked[0].hook) : null;

package/src/hooks/library.json

@@ -1,8 +1,44 @@
 [
-  {"id":"door","tags":["discovery"],"pattern":"Take a closer look at {{subject}}","risk":"low"},
-  {"id":"compare","tags":["comparison","discovery"],"pattern":"Compare {{subject}} with the details in view","risk":"low"},
-  {"id":"help","tags":["discovery","help"],"pattern":"Need help exploring {{subject}}? Start here","risk":"low"},
-  {"id":"ugc","tags":["experience"],"pattern":"Here is what I observed about {{subject}}","risk":"medium"},
-  {"id":"before-after","tags":["comparison"],"pattern":"Before and after: {{subject}}. Virtual staging preview.","risk":"medium"},
-  {"id":"update","tags":["news"],"pattern":"Brand update: {{subject}} — {{source}}","risk":"high"}
+  {"id":"door","tags":["discovery"],"pattern":"Take a closer look at {{subject}}","risk":"low","kind":"spoken line","formats":["pov","lo-fi"],"emotion":"curiosity","housingSafe":true,"note":"A direct invitation opens a reveal without making a claim."},
+  {"id":"compare","tags":["comparison","discovery"],"pattern":"Compare {{subject}} with the details in view","risk":"low","kind":"caption","formats":["text-broll","telestrator"],"emotion":"curiosity","housingSafe":true,"note":"Visible details give a comparison something concrete to show."},
+  {"id":"help","tags":["discovery","help"],"pattern":"Need help exploring {{subject}}? Start here","risk":"low","kind":"spoken line","formats":["screen-voiceover","whiteboard"],"emotion":"relief","housingSafe":true,"note":"A clear question leads directly into the useful step."},
+  {"id":"ugc","tags":["experience"],"pattern":"Here is what I observed about {{subject}}","risk":"medium","kind":"spoken line","formats":["lo-fi","storytime"],"emotion":"pride","housingSafe":false,"note":"First-person delivery adds immediacy; observations need verification."},
+  {"id":"before-after","tags":["comparison"],"pattern":"Before and after: {{subject}}. Virtual staging preview.","risk":"medium","kind":"first-frame visual","formats":["before-after"],"emotion":"shock","housingSafe":false,"note":"A split view makes the change legible; staging needs review."},
+  {"id":"update","tags":["news"],"pattern":"Brand update: {{subject}} — {{source}}","risk":"high","kind":"caption","formats":["news-parody"],"emotion":"curiosity","housingSafe":false,"note":"An update creates a reason to listen; verify the source."},
+  {"id":"shocked-face","tags":["discovery"],"pattern":"Open on an illustrated shocked face; cut next to the cause: {{subject}}.","kind":"first-frame visual","formats":["pov","sitcom","storytime"],"emotion":"shock","risk":"medium","housingSafe":true,"note":"Reaction first creates a question that the next shot answers."},
+  {"id":"all-savings","tags":["discovery"],"pattern":"I spent all my savings on this house. {{subject}}","kind":"spoken line","formats":["storytime","lo-fi","sitcom"],"emotion":"fear","risk":"high","housingSafe":false,"note":"Personal stakes start a story quickly; do not present invented experience as testimony."},
+  {"id":"slick-agent","tags":["discovery"],"pattern":"The slick agent called {{subject}} risk-free. That broke my trust.","kind":"spoken line","formats":["sitcom","storytime"],"emotion":"shock","risk":"high","housingSafe":false,"note":"Broken trust supplies conflict; the quoted promise still fails policy lint."},
+  {"id":"someone-lives-there","tags":["discovery"],"pattern":"Wait, someone lives there? Check the occupancy details for {{subject}}.","kind":"spoken line","formats":["pov","storytime","sitcom"],"emotion":"shock","risk":"medium","housingSafe":false,"note":"An unexpected obstacle turns a reveal into a story; verify occupancy first."},
+  {"id":"scare-beat","tags":["discovery"],"pattern":"A brief suspense hit lands as {{subject}} appears; cut straight to the explanation.","kind":"sound","formats":["pov","sitcom","stickman"],"emotion":"fear","risk":"medium","housingSafe":true,"note":"A sound accent marks the obstacle without leaving dead air."},
+  {"id":"street-interview","tags":["discovery"],"pattern":"Street interview: What would you check first about {{subject}}?","kind":"spoken line","formats":["lo-fi","storytime"],"emotion":"curiosity","risk":"medium","housingSafe":false,"note":"A direct question opens a conversation; synthetic interviews can imply false testimony."},
+  {"id":"door-crack","tags":["discovery"],"pattern":"Start with a door already opening onto {{subject}}.","kind":"first-frame visual","formats":["pov","text-broll"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"Movement starts the reveal before an introduction slows it down."},
+  {"id":"key-turn","tags":["discovery"],"pattern":"A key clicks as the view opens onto {{subject}}.","kind":"sound","formats":["pov","text-broll"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"A sound tied to visible action focuses attention on the reveal."},
+  {"id":"caption-cut","tags":["discovery"],"pattern":"Pause here. Look closer at {{subject}}.","kind":"caption","formats":["text-broll"],"emotion":"shock","risk":"low","housingSafe":true,"note":"A short text interruption sets up a concrete visual payoff."},
+  {"id":"detail-circle","tags":["discovery"],"pattern":"Start with a pen circling a detail in {{subject}}.","kind":"first-frame visual","formats":["telestrator","whiteboard"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"An annotation directs attention to the evidence immediately."},
+  {"id":"cursor-open","tags":["discovery"],"pattern":"The cursor opens {{subject}} in the first frame.","kind":"first-frame visual","formats":["screen-voiceover"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"The useful action begins before the viewer has to wait."},
+  {"id":"marker-question","tags":["discovery"],"pattern":"Draw a question mark beside {{subject}} as the narration begins.","kind":"first-frame visual","formats":["whiteboard"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"Drawing and speech share a beat so the opening stays active."},
+  {"id":"paper-chaos","tags":["discovery"],"pattern":"Scattered notes slide into a checklist for {{subject}}.","kind":"first-frame visual","formats":["before-after","stickman"],"emotion":"relief","risk":"low","housingSafe":true,"note":"Visible organization supplies a payoff without promising a financial outcome."},
+  {"id":"tab-overload","tags":["discovery"],"pattern":"More tabs. Still questions about {{subject}}.","kind":"caption","formats":["text-broll","screen-voiceover"],"emotion":"humor","risk":"low","housingSafe":true,"note":"Dry humor makes a familiar research problem easy to recognize."},
+  {"id":"checklist-speaks","tags":["discovery"],"pattern":"I am the checklist. Ask me about {{subject}}.","kind":"spoken line","formats":["talking-object"],"emotion":"humor","risk":"low","housingSafe":true,"note":"A talking prop makes the useful tool part of the scene."},
+  {"id":"paper-eyebrow","tags":["discovery"],"pattern":"An illustrated checklist raises an eyebrow beside {{subject}}.","kind":"first-frame visual","formats":["talking-object","stickman"],"emotion":"humor","risk":"low","housingSafe":true,"note":"A small character reaction delivers a visual joke immediately."},
+  {"id":"mid-question","tags":["discovery"],"pattern":"And the next question is about {{subject}}.","kind":"spoken line","formats":["lo-fi","storytime"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"Starting inside a thought avoids a slow introduction."},
+  {"id":"look-again","tags":["discovery"],"pattern":"Look again at {{subject}}. What detail stands out?","kind":"spoken line","formats":["pov","telestrator"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"A focused question creates a reason to inspect the next shot."},
+  {"id":"prop-entry","tags":["discovery"],"pattern":"Hands bring a checklist for {{subject}} into the opening frame.","kind":"first-frame visual","formats":["lo-fi","pov"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"A useful prop creates movement and gives the narration a subject."},
+  {"id":"deadpan-paper","tags":["discovery"],"pattern":"{{subject}} brought paperwork to the party.","kind":"spoken line","formats":["sitcom","talking-object"],"emotion":"humor","risk":"low","housingSafe":true,"note":"A dry joke adds character without mocking people or communities."},
+  {"id":"question-stack","tags":["discovery"],"pattern":"{{subject}}: what needs a closer look?","kind":"caption","formats":["text-broll","pov"],"emotion":"fear","risk":"low","housingSafe":true,"note":"A question introduces uncertainty without inventing a threat."},
+  {"id":"slow-down","tags":["discovery"],"pattern":"Start with the details of {{subject}}.","kind":"spoken line","formats":["whiteboard","screen-voiceover"],"emotion":"relief","risk":"low","housingSafe":true,"note":"A simple next step turns uncertainty into a useful demonstration."},
+  {"id":"tick-reveal","tags":["discovery"],"pattern":"A soft tick lands as the checklist for {{subject}} opens.","kind":"sound","formats":["screen-voiceover","whiteboard"],"emotion":"relief","risk":"low","housingSafe":true,"note":"An action sound makes the tool reveal clear."},
+  {"id":"wipe-to-guide","tags":["discovery"],"pattern":"Wipe from loose notes to a guide for {{subject}}.","kind":"first-frame visual","formats":["before-after","text-broll"],"emotion":"relief","risk":"low","housingSafe":true,"note":"The contrast shows organization rather than a promised result."},
+  {"id":"side-by-side","tags":["discovery"],"pattern":"{{subject}}: put the details side by side.","kind":"caption","formats":["text-broll","telestrator"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"A comparison creates a clear visual task."},
+  {"id":"quiet-reveal","tags":["discovery"],"pattern":"A soft door creak introduces {{subject}}.","kind":"sound","formats":["pov","text-broll"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"A small physical sound supports the reveal without competing with speech."},
+  {"id":"record-scratch","tags":["discovery"],"pattern":"A short record scratch interrupts the gesture toward {{subject}}.","kind":"sound","formats":["sitcom","talking-object"],"emotion":"humor","risk":"low","housingSafe":true,"note":"A timed interruption gives the visual joke a clear beat."},
+  {"id":"heartbeat-question","tags":["discovery"],"pattern":"A quiet heartbeat underscores the question about {{subject}}; resolve it with the guide.","kind":"sound","formats":["pov","storytime"],"emotion":"fear","risk":"medium","housingSafe":true,"note":"Suspense leads into an answer rather than unsupported danger."},
+  {"id":"ready-notes","tags":["discovery"],"pattern":"Notes ready. Time to explore {{subject}}.","kind":"caption","formats":["text-broll","screen-voiceover"],"emotion":"pride","risk":"low","housingSafe":true,"note":"Preparation offers an achievable action rather than an outcome claim."},
+  {"id":"draw-the-route","tags":["discovery"],"pattern":"A drawn path connects the question about {{subject}} to a checklist.","kind":"first-frame visual","formats":["whiteboard","stickman"],"emotion":"relief","risk":"low","housingSafe":true,"note":"The visual explanation moves from problem to next step."},
+  {"id":"fictional-aside","tags":["discovery"],"pattern":"Fictional scene: the paperwork for {{subject}} gets its own chair.","kind":"spoken line","formats":["sitcom","storytime"],"emotion":"humor","risk":"medium","housingSafe":true,"note":"An obvious fictional joke gives the scene personality without false testimony."},
+  {"id":"envelope-open","tags":["discovery"],"pattern":"Open a generic envelope to reveal a guide to {{subject}}.","kind":"first-frame visual","formats":["pov","text-broll"],"emotion":"curiosity","risk":"medium","housingSafe":true,"note":"The physical reveal adds texture without making an offer claim."},
+  {"id":"empty-box","tags":["discovery"],"pattern":"{{subject}}: which detail fills this box?","kind":"caption","formats":["whiteboard","screen-voiceover"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"An unfinished visual invites attention to the explanation."},
+  {"id":"magnifier","tags":["discovery"],"pattern":"A drawn magnifier moves across the details of {{subject}}.","kind":"first-frame visual","formats":["stickman","telestrator"],"emotion":"curiosity","risk":"low","housingSafe":true,"note":"A moving focus point makes the inspection visible."},
+  {"id":"question-to-action","tags":["discovery"],"pattern":"Questions about {{subject}}? Open the guide alongside the details.","kind":"spoken line","formats":["screen-voiceover","whiteboard"],"emotion":"relief","risk":"low","housingSafe":true,"note":"A direct bridge connects the opening question to a useful action."},
+  {"id":"guide-in-hand","tags":["discovery"],"pattern":"A hand sets a guide beside the notes on {{subject}}.","kind":"first-frame visual","formats":["pov","lo-fi"],"emotion":"pride","risk":"low","housingSafe":true,"note":"An ordinary action shows preparation without claiming a purchase or result."}
 ]

package/src/http.js

@@ -0,0 +1,104 @@
+import { createServer } from 'node:http';
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { execute } from './index.js';
+const digest = value => createHash('sha256').update(value).digest();
+const hasApply = value => value && typeof value === 'object' && Object.entries(value).some(([key, item]) => key === 'apply' || hasApply(item));
+export async function serve(argv) {
+  const options = { host: '127.0.0.1', port: 8787 }, seen = new Set();
+  while (argv.length) {
+    const option = argv.shift(), split = option.indexOf('=');
+    const key = (split < 0 ? option : option.slice(0, split)).slice(2);
+    const value = split < 0 ? argv.shift() : option.slice(split + 1);
+    if (!option.startsWith('--') || !['host', 'port'].includes(key) || seen.has(key) || !value) throw new Error('Invalid serve option');
+    seen.add(key); options[key] = value;
+  }
+  if (!/^\d+$/.test(String(options.port)) || Number(options.port) > 65535) throw new Error('Invalid port');
+  options.port = Number(options.port);
+  const token = process.env.AGENTIC_ADS_TOKEN || '';
+  const loopback = ['localhost', '::1', '127.0.0.1'].includes(options.host);
+  if (!loopback && !token) throw new Error('Non-loopback host requires AGENTIC_ADS_TOKEN');
+  if (token && token !== token.trim()) throw new Error('AGENTIC_ADS_TOKEN must not start or end with spaces');
+  if (token && token.length < 32) throw new Error('AGENTIC_ADS_TOKEN needs 32 or more characters');
+  let boundPort = 0;
+  // Pin localhost to loopback rather than trusting hostname resolution.
+  if (options.host === 'localhost') options.host = '127.0.0.1';
+  const expected = digest('Bearer ' + token);
+  const cors = process.env.AGENTIC_ADS_CORS_ORIGIN;
+  if (cors) {
+    try { if (!/^https?:$/.test(new URL(cors).protocol) || new URL(cors).origin !== cors) throw new Error(); }
+    catch { throw new Error('Invalid CORS origin'); }
+  }
+  const server = createServer({ requestTimeout: 10000, headersTimeout: 10000, connectionsCheckingInterval: 1000 }, (req, res) => {
+    // Without a token, accept only loopback Host values. This blocks DNS rebinding.
+    const hostOk = token || [`127.0.0.1:${boundPort}`, `localhost:${boundPort}`, `[::1]:${boundPort}`].includes(String(req.headers.host).toLowerCase());
+    const timer = setTimeout(() => { send(408, { error: 'Request timeout' }); req.resume(); }, 10000);
+    res.on('close', () => clearTimeout(timer));
+    function send(status, value, headers = {}) {
+      if (res.writableEnded || res.destroyed) return;
+      let body = JSON.stringify(value);
+      if (token && (body.includes(token) || body.includes(JSON.stringify(token).slice(1, -1)))) {
+        status = 400; body = JSON.stringify({ error: 'Invalid request' });
+      }
+      res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', ...(status >= 400 && status !== 413 ? { connection: 'close' } : {}), ...headers });
+      res.end(body);
+    }
+    if (cors && req.headers.origin === cors) {
+      res.setHeader('access-control-allow-origin', cors); res.setHeader('vary', 'Origin');
+    }
+    if (token && !timingSafeEqual(digest(req.headers.authorization ?? ''), expected)) { send(401, { error: 'Unauthorized' }); req.resume(); return; }
+    let url;
+    if (!hostOk) { send(403, { error: 'Forbidden host' }); req.resume(); return; }
+    try { url = new URL(req.url, 'http://localhost'); } catch { send(400, { error: 'Invalid URL' }); return; }
+    const routes = { '/health': null, '/v1/formats': 'list_formats', '/v1/hooks': 'list-hooks',
+      '/v1/templates': 'list-templates', '/v1/qa-rules': 'list_qa_rules', '/v1/lint': 'lint', '/v1/plan': 'plan_format' };
+    const detail = url.pathname.match(/^\/v1\/(formats|qa-rules)\/([^/]+)$/);
+    const action = detail ? (detail[1] === 'formats' ? 'get_format' : 'get_qa_rule') : routes[url.pathname];
+    if (!detail && !Object.hasOwn(routes, url.pathname)) { send(404, { error: 'Not found' }); req.resume(); return; }
+    const method = ['lint', 'plan_format'].includes(action) ? 'POST' : 'GET';
+    if (req.method !== method) { send(405, { error: 'Method not allowed' }, { allow: method }); req.resume(); return; }
+    if (url.searchParams.has('apply')) { send(400, { error: 'Apply is unavailable' }); req.resume(); return; }
+    function run(args) {
+      try { send(200, action === null ? { status: 'ok' } : execute(action, args)); }
+      catch { send(detail ? 404 : 400, { error: detail ? 'Not found' : 'Invalid arguments' }); }
+    }
+    if (method === 'GET') {
+      try { run(detail ? { id: decodeURIComponent(detail[2]) } : {}); }
+      catch { send(400, { error: 'Invalid URL' }); }
+      req.resume(); return;
+    }
+    if (req.headers['content-type']?.split(';')[0].trim().toLowerCase() !== 'application/json') {
+      send(415, { error: 'Use application/json' }); req.resume(); return;
+    }
+    let size = 0, chunks = [], rejected = false;
+    req.on('error', () => { rejected = true; chunks = []; });
+    req.on('data', chunk => {
+      if (rejected) return;
+      size += chunk.length;
+      if (size > 65536) { rejected = true; chunks = []; send(413, { error: 'Body too large' }); return; }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (rejected || res.writableEnded) return;
+      let args;
+      try {
+        args = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (hasApply(args)) { send(400, { error: 'Apply is unavailable' }); return; }
+      } catch { send(400, { error: 'Invalid JSON' }); return; }
+      run(args);
+    });
+  });
+  server.on('clientError', (error, socket) => {
+    if (!socket.writable) return;
+    const status = error.code === 'ERR_HTTP_REQUEST_TIMEOUT' ? '408 Request Timeout' : '400 Bad Request';
+    const body = JSON.stringify({ error: 'Invalid or incomplete request' });
+    socket.end(`HTTP/1.1 ${status}\r\nContent-Type: application/json\r\nConnection: close\r\nContent-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', () => reject(new Error('Unable to start HTTP server')));
+    server.listen(options, resolve);
+  });
+  boundPort = server.address().port;
+  console.log(JSON.stringify({ status: 'listening', port: server.address().port }));
+  const stop = () => { server.close(); server.closeAllConnections(); };
+  process.once('SIGTERM', stop); process.once('SIGINT', stop);
+}

package/src/index.js

@@ -1,13 +1,18 @@
+import { listRules, getRule } from './qa/index.js';
+export { listRules, getRule, checklistFor, costRatchet } from './qa/index.js';
 import { listFormats, getFormat, planFormat } from './formats/index.js';
 export { listFormats, getFormat, planFormat };
 import { templates } from './templates/index.js';
-import { hooks, selectFor } from './hooks/index.js';
+import { hooks, selectFor, listHooks, getHook, pickHooks, emotions } from './hooks/index.js';
 import { lint } from './policy/index.js';
 import { templateProvider, guardCost } from './providers/index.js';
-export { templates, hooks, selectFor, lint, templateProvider, guardCost };
+export { listHooks, getHook, pickHooks, templates, hooks, selectFor, lint, templateProvider, guardCost };
 export { readScores, writeScores } from './hooks/index.js';
 const string = { type: 'string' };
+const hookFilters = { format: string, emotion: { type: 'string', enum: emotions }, housing: { type: 'boolean' } };
 const fields = {
+  list_hooks: hookFilters, pick_hooks: hookFilters, get_hook: { id: string },
+  list_qa_rules: {}, get_qa_rule: { id: string },
   list_formats: { costClass: { type: 'string', enum: ['free', 'cheap', 'mid', 'expensive'] }, risk: { type: 'string', enum: ['low', 'medium', 'high'] } },
   get_format: { id: string },
   plan_format: { format: string, site: string, goal: string, dryRun: { type: 'boolean' } },
@@ -16,8 +21,8 @@ const fields = {
   plan: { site: string, goal: string, template: string, ratio: { enum: ['4:5', '9:16'], type: 'string' }, copy: string, category: { enum: ['housing', 'none'], type: 'string' }, apply: { type: 'boolean' }, dryRun: { type: 'boolean' } },
 };
 export const tools = Object.entries(fields).map(([name, properties]) => ({
-  name, description: ({ list_formats: 'List video formats with optional cost and risk filters.', get_format: 'Get a video format descriptor.', plan_format: 'Plan video stages offline. Apply is unavailable.', 'list-templates': 'List starter template descriptors.', 'list-hooks': 'List hook patterns and risks.', lint: 'Check ad copy; findings always require review.', plan: 'Preview a zero-cost plan. Apply is unavailable.' })[name],
-  inputSchema: { type: 'object', properties, additionalProperties: false, ...({ lint: ['copy'], get_format: ['id'], plan_format: ['format', 'site'] }[name] ? { required: { lint: ['copy'], get_format: ['id'], plan_format: ['format', 'site'] }[name] } : {}) },
+  name, description: ({ list_hooks: 'List hooks with optional filters.', pick_hooks: 'Pick matching hooks in stable score order.', get_hook: 'Get one hook.', list_qa_rules: 'List owner feedback QA rules.', get_qa_rule: 'Get an owner feedback QA rule.', list_formats: 'List video formats with optional cost and risk filters.', get_format: 'Get a video format descriptor.', plan_format: 'Plan video stages offline. Apply is unavailable.', 'list-templates': 'List starter template descriptors.', 'list-hooks': 'List hook patterns and risks.', lint: 'Check ad copy; findings always require review.', plan: 'Preview a zero-cost plan. Apply is unavailable.' })[name],
+  inputSchema: { type: 'object', properties, additionalProperties: false, ...({ pick_hooks: ['format'], get_hook: ['id'], lint: ['copy'], get_qa_rule: ['id'], get_format: ['id'], plan_format: ['format', 'site'] }[name] ? { required: { pick_hooks: ['format'], get_hook: ['id'], lint: ['copy'], get_qa_rule: ['id'], get_format: ['id'], plan_format: ['format', 'site'] }[name] } : {}) },
 }));
 /** Shared CLI/MCP dispatch. Unknown inputs fail before any action. */
 export function execute(action, args = {}) {
@@ -30,6 +35,11 @@ export function execute(action, args = {}) {
     if (!Object.hasOwn(fields[action], key) || typeof value !== field.type || (field.enum && !field.enum.includes(value))) throw new Error('Invalid argument');
     if (typeof value === 'string' && value.length > 20000) throw new Error('Argument too long');
   }
+  if (action === 'list_hooks') return listHooks(args);
+  if (action === 'pick_hooks') return pickHooks(args);
+  if (action === 'get_hook') return getHook(args.id);
+  if (action === 'list_qa_rules') return listRules();
+  if (action === 'get_qa_rule') return getRule(args.id);
   if (action === 'list_formats') return listFormats(args);
   if (action === 'get_format') return getFormat(args.id);
   if (action === 'plan_format') return planFormat(args);

package/src/qa/index.js

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+const rules = JSON.parse(readFileSync(new URL('./rules.json', import.meta.url), 'utf8'));
+export function listRules() { return structuredClone(rules); }
+export function getRule(id) {
+  const rule = rules.find(r => r.id === id);
+  if (!rule) throw new Error('Unknown QA rule: ' + String(id) + '. Use qa-rules to list available IDs.');
+  return structuredClone(rule);
+}
+/** Accept a format descriptor. Review status never implies that checks ran. */
+export function checklistFor(format) {
+  return format.feedbackRules.map(id => {
+    const { title, check } = getRule(id);
+    return { id, title, check, status: 'NOT CHECKED' };
+  });
+}
+export const costRatchet = "Set a hard cap before you spend. One writer per spend log.\nReuse faces, sets, stills, clips and voice ids from earlier videos first.\nPick one lip-sync model for a format and keep it. Do not repeat a bake-off.\nDo not make the same still twice. Do not pay for an unused line.\nWrite `COST_NOTES.md`. Show cost per stage and against the last video of the format.\nA video that costs more than the last one of its format needs a one-line reason.";

package/src/qa/rules.json

@@ -0,0 +1,28 @@
+[
+  {"id": "R1", "title": "Wild emotional hook in the first second.", "check": "Watch 0 to 1 s with sound off. Record what frame 0.0 s shows. It must be a strong emotion or an odd event. In a format with a person, R20 applies.", "origin": "Round 3 hook was \"not intriguing\".", "severity": "blocking", "applies": ["all"]},
+  {"id": "R2", "title": "Cause comes before effect on screen. Show the action, then the result, then who reacts. In a format with a person, the reaction face of R20 comes first. Then the order is action, result, reaction, all by 3 s.", "check": "Step through 0 to 3 s. No character appears without a reason. No object is already broken.", "origin": "Sitcom: door fell, people appeared at 0:02.", "severity": "blocking", "applies": ["story"]},
+  {"id": "R3", "title": "Change the camera angle, not only the zoom.", "check": "Look at the frames: the scene-cut filter cannot see a zoom. About one new angle or pose every 2.5 s. Cuts differ in height, pose or distance. A side change stays on one side of the 180-degree line (R21).", "origin": "\"Different left and right views, not slow zooms.\"", "severity": "blocking", "applies": ["character"]},
+  {"id": "R4", "title": "The same person must show different poses and angles.", "check": "Same face, outfit and hair across all shots. At least 3 poses.", "origin": "Marble lady needed jump cuts.", "severity": "blocking", "applies": ["character"]},
+  {"id": "R5", "title": "Show problem, agitation, then solution. Make the agitation hurt and be funny.", "check": "Mark the three beats on the timeline. Agitation has at least 3 quick cuts, one prop each.", "origin": "\"Highlight problem and solution agitation.\"", "severity": "blocking", "applies": ["story"]},
+  {"id": "R6", "title": "No dead gaps. No silent still over 0.3 s. Tail after the last sound under 0.3 s.", "check": "`freezedetect=n=-60dB:d=0.3` crossed with `silencedetect=n=-35dB:d=0.25`. A range in both is a dead gap.", "origin": "Round 4 had dead gaps.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R7", "title": "Speed up the picture, not the voice. Normal speech pace.", "check": "Words per second from whisper: 2 to 3. Average shot length: 1.5 to 2.2 s for a lo-fi story (the gate in `qa.md`), 1.2 to 1.5 s only for a fast punch edit. No shot over 2.5 s.", "origin": "\"Sound speed too much, pace better.\"", "severity": "blocking", "applies": ["all"]},
+  {"id": "R8", "title": "Voice, face and ethnicity must match.", "check": "A person listens to each voice with the face. Log the voice id per character.", "origin": "\"Ethnicity of source does not match.\"", "severity": "blocking", "applies": ["character"]},
+  {"id": "R9", "title": "A story the viewer can follow. It is personal and coherent, in the first person, as a dramatization. It makes no factual claim.", "check": "Read the captions alone. They tell one story in the first person.", "origin": "Meltdown: \"random words\".", "severity": "blocking", "applies": ["story"]},
+  {"id": "R10", "title": "Captions have spaces. At most 3 words. Time them to the audio.", "check": "Measure the pixel gap: at least 14 px of clear gap between words at 1080 px. Compare caption start with the whisper word start (under 0.15 s).", "origin": "Caption spacing and sync.", "severity": "blocking", "applies": ["captions"]},
+  {"id": "R11", "title": "Mouth movement matches speech. Mouths close in laugh breaks.", "check": "Manual spot check until measured: mouth movement starts within 100 to 200 ms of voice onset (see `ad-video-editing` qa.md section 6). Where a lip-landmark tool ran, give its correlation (0.4 or more) and the tool name. List each failing line.", "origin": "Sitcom v2 and v3.", "severity": "blocking", "applies": ["dialogue", "speech"]},
+  {"id": "R12", "title": "Never cut to a static image that makes no sense.", "check": "Check each cut. Every shot has motion or a reason to hold.", "origin": "Sitcom v2 feedback.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R13", "title": "Back-and-forth dialogue is wanted. Keep it and add more.", "check": "Count speaker changes. At least 4 in a sitcom.", "origin": "\"Love the dialogue.\"", "severity": "blocking", "applies": ["dialogue"]},
+  {"id": "R14", "title": "Sound is required. The ad also works muted.", "check": "Play with sound off. The story and the offer still read. Ship both files.", "origin": "Round 3 had no sound.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R15", "title": "Hold the object identity. A phone stays a phone.", "check": "Compare held objects in frames across the clip.", "origin": "Phone turned into a notepad.", "severity": "blocking", "applies": ["character"]},
+  {"id": "R16", "title": "Lo-fi organic look. No logo. No text except captions, the dramatization tag and one end card with the offer.", "check": "Look at the frames. No logo, no studio polish.", "origin": "Polished images were rejected.", "severity": "blocking", "applies": ["lo-fi"]},
+  {"id": "R17", "title": "Housing safety. \"dramatization\" label. No invented numbers. No real people. No children.", "check": "Run the policy lint on all text and captions.", "origin": "Housing special ad category.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R18", "title": "Cost goes down each time. Report cost per video by stage.", "check": "Compare with the last video of the same format. Explain any rise.", "origin": "Goal: cut cost 50 to 75 percent.", "severity": "blocking", "applies": ["all"]},
+  {"id": "R19", "title": "Do not show an event the video model cannot render. Show damage another way.", "check": "Render one clip first. Look at 3 frames of the event. No duplicate objects (two doors), no melting. If it fails, change the beat (cracking wall, falling plaster).", "origin": "\"No crash, two doors, AI artifact.\"", "severity": "blocking", "applies": ["all"]},
+  {"id": "R20", "title": "In a format with a person, the first frame is that person's reaction face. The cause follows in the next shot or two (see R2). This replaces the 0.0 s check in R1 for those formats.", "check": "Frame 0.0 s: a face, eyes and mouth readable, emotion matches the hook. The cause is on screen by 3 s.", "origin": "\"Shocked face in the first frame.\"", "severity": "blocking", "applies": ["character"]},
+  {"id": "R21", "title": "Keep screen direction. Each person stays on the same side of the frame in every shot. Change the angle on one side of the 180-degree line. Do not cross it.", "check": "List left/right per shot for each person. No swap, including cutaways.", "origin": "Street interview: host moved from right to left.", "severity": "blocking", "applies": ["dialogue"]},
+  {"id": "R22", "title": "A conversation looks like one: eyelines, head turns, small hand gestures, a slow push-in on the punchline. Do the push-in in the edit as a crop. Ask the model for small gestures only.", "check": "Per talking shot: where does the person look? Count eyeline-matched reverse shots (at least 1). Note the crop push-in. OWNER CHECK for how natural it looks.", "origin": "\"Talk as if to someone, more hand movement, zoom in on the guy.\"", "severity": "blocking", "applies": ["dialogue"]},
+  {"id": "R23", "title": "Captions never look jumbled.", "check": "Compile `swiftc -O ocr.swift` (macOS Vision, `VNRecognizeTextRequest`, accurate, language correction off). Run it on one frame per caption from the final render. Retry once on an `e5rt` crash. Character error rate (edit distance divided by expected length, upper case, spaces collapsed) 0.10 or less. Do not run `swift ocr.swift` (it hangs).", "origin": "\"Some letters get jumbled.\"", "severity": "blocking", "applies": ["captions"]},
+  {"id": "R24", "title": "Show the tool of the format. A street interview shows the microphone in the host's hand. Name the mic in the motion prompt and include it in the R15 frame comparison.", "check": "Frame check: mic visible in every host shot, same shape in each.", "origin": "Interview had no visible mic.", "severity": "blocking", "applies": ["interview"]},
+  {"id": "R25", "title": "A horror-comic variant needs a scare beat: something moves behind a door, a sting, a reaction. Then it resolves as a joke.", "check": "Mark the beat on the timeline. A sting starts within 0.2 s of the beat, then a reaction shot. OWNER CHECK for how scary it feels.", "origin": "\"Feel a little bit scared.\"", "severity": "blocking", "applies": ["horror"]},
+  {"id": "R26", "title": "A personal story has a clear hook: the loss, the place, the trust that broke, the surprise. The offer is on the end card. The narrator never says the product worked. See R9 and R17.", "check": "Caption read: one sentence per beat, in that order. No line claims a result.", "origin": "\"I spent all my savings on this house ... a slick agent gave me a lien ... someone lives there.\"", "severity": "blocking", "applies": ["story"]}
+]