npm - @lifeaitools/rdc-skills - Versions diffs - 0.24.38 → 0.24.39 - Mend

@lifeaitools/rdc-skills 0.24.38 → 0.24.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (191) hide show

package/.claude/settings.json +15 -15
package/.claude-plugin/marketplace.json +21 -21
package/.claude-plugin/plugin.json +1371 -1371
package/.github/workflows/publish.yml +34 -34
package/.github/workflows/self-test.yml +58 -58
package/CHANGELOG.md +310 -310
package/LICENSE +21 -21
package/MANIFEST.md +221 -221
package/README.md +377 -377
package/README.sandbox.md +3 -3
package/assets/watcher/viewer.html +164 -164
package/bin/rdc-skills-mcp.mjs +316 -316
package/commands/build.md +183 -183
package/commands/collab.md +180 -180
package/commands/deploy.md +152 -152
package/commands/design.md +31 -31
package/commands/edit.md +28 -28
package/commands/fixit.md +124 -124
package/commands/handoff.md +173 -173
package/commands/help.md +95 -95
package/commands/overnight.md +220 -220
package/commands/plan.md +158 -158
package/commands/preplan.md +131 -131
package/commands/prototype.md +145 -145
package/commands/release.md +49 -49
package/commands/report.md +99 -99
package/commands/review.md +120 -120
package/commands/self-test.md +113 -113
package/commands/status.md +86 -86
package/commands/watch.md +98 -98
package/commands/workitems.md +137 -137
package/git-sha.json +1 -1
package/guides/agent-bootstrap.md +295 -295
package/guides/agents/backend.md +104 -104
package/guides/agents/content.md +94 -94
package/guides/agents/cs2.md +56 -56
package/guides/agents/data.md +87 -87
package/guides/agents/design.md +77 -77
package/guides/agents/frontend.md +92 -92
package/guides/agents/infrastructure.md +81 -81
package/guides/agents/setup.md +281 -281
package/guides/agents/verify.md +151 -151
package/guides/agents/viz.md +106 -106
package/guides/backend.md +146 -146
package/guides/content.md +147 -147
package/guides/cs2.md +190 -190
package/guides/data.md +123 -123
package/guides/design.md +116 -116
package/guides/engineering-behavior.md +43 -43
package/guides/escalation-protocol.md +125 -125
package/guides/frontend.md +151 -151
package/guides/history-md-spec.md +297 -297
package/guides/infrastructure.md +179 -179
package/guides/lessons-learned-spec.md +153 -153
package/guides/output-contract.md +108 -108
package/guides/publish-md-spec.md +289 -289
package/guides/rdc-skills-startup.md +30 -30
package/guides/verify.md +11 -11
package/hooks/check-cwd.js +31 -31
package/hooks/check-rdc-environment.js +164 -164
package/hooks/check-services.js +6 -6
package/hooks/check-stale-work-items.js +19 -19
package/hooks/foreground-process-gate.js +128 -128
package/hooks/gate-watchdog-selfcheck.js +257 -257
package/hooks/hook-logger.js +25 -25
package/hooks/lib/run-evidence-gate.mjs +241 -241
package/hooks/no-stop-open-epics.js +127 -127
package/hooks/post-tool-batch-gate.js +203 -203
package/hooks/post-work-check.js +21 -21
package/hooks/postcompact-log.js +13 -13
package/hooks/precompact-log.js +13 -13
package/hooks/rate-limit-retry.js +46 -46
package/hooks/rdc-invocation-marker.js +157 -157
package/hooks/rdc-output-contract-gate.js +94 -94
package/hooks/require-work-item-on-commit.js +294 -294
package/hooks/restart-brief.js +19 -19
package/hooks/run-hidden-hook.ps1 +47 -47
package/hooks/task-completed-gate.js +274 -274
package/hooks/work-item-exit-gate.js +944 -944
package/lib/catalog.mjs +236 -236
package/lib/cloud-rewrite.mjs +155 -155
package/package.json +56 -56
package/rules/work-items-rpc.md +520 -520
package/scaffold/templates/HISTORY.md.template +39 -39
package/scaffold/templates/PUBLISH.md.template +21 -21
package/scaffold/templates/brochure-studio-default.html +70 -70
package/scripts/acceptance.mjs +502 -502
package/scripts/fixtures/guides/bad-guide.md +15 -15
package/scripts/fixtures/guides-clean/good-guide.md +16 -16
package/scripts/install-rdc-skills.js +1289 -1289
package/scripts/install.ps1 +202 -202
package/scripts/install.sh +132 -132
package/scripts/lib/assertions.mjs +287 -287
package/scripts/lib/manifest-schema.mjs +754 -754
package/scripts/lib/runner.mjs +465 -465
package/scripts/lib/sandbox.mjs +435 -435
package/scripts/prepack.mjs +32 -32
package/scripts/rdc-brochure.mjs +464 -464
package/scripts/rdc-design-cli.mjs +134 -134
package/scripts/rebuild-mcp.mjs +107 -107
package/scripts/self-test.mjs +1460 -1460
package/scripts/stamp-git-sha.mjs +29 -29
package/scripts/test-guide-validator.mjs +196 -196
package/scripts/test-rdc-hooks.mjs +145 -145
package/scripts/uninstall.ps1 +77 -77
package/scripts/uninstall.sh +69 -69
package/scripts/update.ps1 +43 -43
package/scripts/update.sh +43 -43
package/scripts/validate-place-histories.js +461 -461
package/scripts/validate-publish-manifests.js +424 -424
package/scripts/watch-init.mjs +100 -100
package/skills/brochure/SKILL.md +107 -107
package/skills/build/SKILL.md +563 -563
package/skills/channel-formatter/SKILL.md +533 -533
package/skills/co-develop/SKILL.md +196 -196
package/skills/collab/SKILL.md +239 -239
package/skills/convert/SKILL.md +140 -140
package/skills/deploy/SKILL.md +541 -541
package/skills/design/SKILL.md +211 -211
package/skills/design/reference/ownership.md +16 -16
package/skills/design/reference/rampa.md +92 -92
package/skills/design/reference/studio-model.md +153 -153
package/skills/edit/SKILL.md +98 -98
package/skills/fixit/SKILL.md +165 -165
package/skills/fs-mcp/SKILL.md +148 -148
package/skills/handoff/SKILL.md +236 -200
package/skills/help/SKILL.md +143 -143
package/skills/housekeeping/SKILL.md +189 -189
package/skills/lifeai-brochure-author/SKILL.md +340 -340
package/skills/overnight/SKILL.md +251 -251
package/skills/plan/SKILL.md +345 -345
package/skills/preplan/SKILL.md +90 -90
package/skills/prototype/SKILL.md +150 -150
package/skills/rdc-brochurify/SKILL.md +245 -245
package/skills/rdc-extract-verifier-rules/SKILL.md +191 -191
package/skills/release/SKILL.md +140 -140
package/skills/report/SKILL.md +100 -100
package/skills/review/SKILL.md +152 -152
package/skills/rpms-filemap/SKILL.cloud.md +111 -111
package/skills/rpms-filemap/SKILL.md +111 -111
package/skills/self-test/SKILL.md +132 -132
package/skills/status/SKILL.md +99 -99
package/skills/terminal-config/SKILL.md +62 -62
package/skills/tests/MATRIX.md +54 -54
package/skills/tests/README.md +47 -47
package/skills/tests/rdc-brochure.test.json +34 -34
package/skills/tests/rdc-build.test.json +36 -36
package/skills/tests/rdc-channel-formatter.test.json +45 -45
package/skills/tests/rdc-co-develop.test.json +29 -29
package/skills/tests/rdc-collab.test.json +29 -29
package/skills/tests/rdc-convert.test.json +35 -35
package/skills/tests/rdc-deploy.test.json +30 -30
package/skills/tests/rdc-design.test.json +27 -27
package/skills/tests/rdc-edit.test.json +29 -29
package/skills/tests/rdc-fixit.test.json +36 -36
package/skills/tests/rdc-fs-mcp.test.json +36 -36
package/skills/tests/rdc-handoff.test.json +28 -28
package/skills/tests/rdc-help.test.json +29 -29
package/skills/tests/rdc-housekeeping.test.json +31 -31
package/skills/tests/rdc-lifeai-brochure-author.test.json +35 -35
package/skills/tests/rdc-overnight.test.json +37 -37
package/skills/tests/rdc-plan.test.json +27 -27
package/skills/tests/rdc-preplan.test.json +31 -31
package/skills/tests/rdc-prototype.test.json +28 -28
package/skills/tests/rdc-rdc-brochurify.test.json +23 -23
package/skills/tests/rdc-rdc-extract-verifier-rules.test.json +34 -34
package/skills/tests/rdc-release.test.json +29 -29
package/skills/tests/rdc-report.test.json +28 -28
package/skills/tests/rdc-review.test.json +29 -29
package/skills/tests/rdc-rpms-filemap.test.json +28 -28
package/skills/tests/rdc-self-test.test.json +24 -24
package/skills/tests/rdc-status.test.json +29 -29
package/skills/tests/rdc-terminal-config.test.json +29 -29
package/skills/tests/rdc-watch.test.json +24 -24
package/skills/tests/rdc-workitems.test.json +27 -27
package/skills/watch/SKILL.md +97 -97
package/skills/workitems/SKILL.md +151 -151
package/tests/acceptance.test.mjs +59 -59
package/tests/channel-formatter.contract.test.mjs +251 -251
package/tests/curl-surface.test.mjs +289 -289
package/tests/harness-gates.test.mjs +325 -325
package/tests/help-surface.test.mjs +61 -61
package/tests/install-rdc-skills.test.mjs +49 -49
package/tests/manifest-contract-fields.test.mjs +78 -78
package/tests/mcp.test.mjs +271 -271
package/tests/require-work-item-on-commit.test.mjs +162 -162
package/tests/run-evidence-gate.test.mjs +82 -82
package/tests/skill-test-matrix.test.mjs +66 -66
package/tests/validate-skills.js +27 -27
package/tests/work-item-exit-gate-l2.test.mjs +368 -368
package/tests/work-item-exit-gate-l3.test.mjs +197 -197

package/skills/rdc-brochurify/SKILL.md CHANGED Viewed

@@ -1,245 +1,245 @@
----
-name: rdc-brochurify
-version: 0.1.0
-description: |
-  Orchestrate a Brochurify job from source ingest through delivered PDF, using six parallel-dispatched typed sub-agents and the convergence loop. Use this skill EVERY TIME the user invokes Brochurify directly via "brochurify this", "make a brochure from", "convert this to a brochure PDF", or "rdc:brochurify". Also runs automatically when a job arrives from the broker via monkey_dispatch. The skill enforces D-001 through D-016 from the brochurify DECISIONS-LOG.
-triggers:
-  - "rdc:brochurify"
-  - "brochurify this"
-  - "make a brochure from"
-  - "convert to brochure PDF"
-  - "generate brochure from"
-  - monkey_dispatch payload with skill="brochurify"
----
-# rdc:brochurify Orchestrator
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Report brochure job state, artifacts, and blockers directly; do not dump raw tool logs.
-> **Sandbox contract:** When `RDC_TEST=1`, do not install dependencies, open browsers,
-> upload to R2/Supabase, ask follow-up questions, or fabricate a PDF/grade/URL. Inspect
-> the fixture, report Wave 1 feasibility, and state that render/grade/deliver are
-> gated when the Brochurify runtime is absent.
-The orchestrator dispatches six waves of typed sub-agents in sequence. Each wave has a clear input contract, an output contract, and a parallelism profile.
-## Inputs
-The orchestrator accepts a job payload:
-```json
-{
-  "job_id": "uuid",
-  "source": {
-    "kind": "url" | "html" | "docx" | "md" | "jsx" | "corpus",
-    "ref": "https://..." | "file:///path/..." | "<html>..." | { corpus_query }
-  },
-  "mode": "read-only" | "cosmetic" | "editorial" | "creative",
-  "theme": "prt" | "place-fund" | "zoen" | "evergreen" | "editorial-neutral",
-  "page_size": "letter" | "a4" | "legal" | "digest" | "tabloid",
-  "brief": "optional natural-language brief for editorial/creative modes",
-  "org_id": "uuid",
-  "user_id": "uuid"
-}
-```
-## Outputs
-- A PDF in R2 (`brochurify-output` bucket) with a signed URL
-- A completion record in Supabase `brochure_jobs` with:
-  - `pdf_r2_key`, `pdf_url`
-  - `final_grade`, `page_scores` (jsonb array)
-  - `iter` (iteration count reached)
-  - `trace` (jsonb log of all 6 waves × iterations)
-## The Six Waves
-### Wave 1 — Ingest
-**Goal:** Normalize any source into kit-compliant JSX.
-**Sub-agent:** `ingest-author` (typed agent with the `lifeai-brochure-author` skill loaded)
-**Inputs:** raw source from job payload
-**Outputs:** `working/draft.jsx` (kit-compliant JSX) + `working/assets/` (extracted images)
-**Per-source handling:**
-- `url` — fetch via Playwright (whitelist) or structural-summary mode (open web)
-- `html` — direct ingest, strip scripts/iframes/ads
-- `docx` — pandoc to HTML, then ingest
-- `md` — render to HTML, then ingest
-- `jsx` — pre-built input; skip to validate
-- `corpus` — Creative mode only; corpus reader + Author-Mode-* sub-agent
-**Failure mode:** if ingest cannot map content to kit primitives, raise a structured error with the unmappable content range and ask the user to clarify.
-### Wave 2 — Validate
-**Goal:** Confirm the JSX passes static and structural validation before render.
-**Sub-agent:** none — runs `pnpm bk-lint working/draft.jsx` directly
-**Behavior:**
-- If pass → Wave 3
-- If fail → return errors to Wave 1 agent, retry once
-- If fail twice → escalate to orchestrator: try a different ingest strategy, page-size change, or surface to user
-**Every failure here writes to `enhancement-log.jsonl`** with:
-- `src: "ingest-author"`
-- `fail_layer: "static"` or `fail_layer: "structural"`
-- The specific rule violated
-### Wave 3 — Render
-**Goal:** Produce a first-iteration PDF and per-page screenshots.
-**Sub-agent:** none — runs Paged.js via Playwright headless
-**Process:**
-1. Build the kit + theme bundle into `working/bundle.html`
-2. Open with Paged.js polyfill
-3. Wait for `pagedjs:rendered` event
-4. Snapshot DOM after pagination → `working/paged.html`
-5. Per-page screenshot at 150 DPI → `working/pages/page-{N}.png`
-6. Render to PDF → `working/iter-{i}.pdf`
-**Failure mode:** if Paged.js fails to converge (rare; usually a kit bug), fall back to print-to-PDF without paged-media polyfill, flag as low-quality iteration, continue.
-### Wave 4 — Grade (Vision, Parallel)
-**Goal:** Score each page against the 7-dimension rubric.
-**Sub-agent:** `vision-grader` — dispatched **once per page in parallel**.
-**Per-page inputs:**
-- The page screenshot
-- The source JSX for that page (extracted by walking the paginated DOM)
-- The rubric (R1-R7 with weights and target ranges)
-**Per-page outputs (structured):**
-```json
-{
-  "page": 3,
-  "grade": 82,
-  "dimensions": {
-    "R1_margin_integrity": 95,
-    "R2_bottom_slack": 70,
-    "R3_heading_breathing": 85,
-    "R4_widows_orphans": 100,
-    "R5_image_placement": 80,
-    "R6_table_integrity": 100,
-    "R7_text_density": 75
-  },
-  "issues": [
-    {"dim": "R2", "desc": "tail gap 1.1in below last paragraph", "fix_hint": "compress paragraph or push next-page content"}
-  ]
-}
-```
-**Document grade:** `min(page_grades)` per D-013.
-**Convergence:**
-- Grade ≥ 75 → Wave 6 (Deliver)
-- Grade < 75 AND iter < 10 → Wave 5 (Patch)
-- iter = 10 → Wave 6 with `partial=true` flag
-### Wave 5 — Patch (Parallel)
-**Goal:** Produce a corrected JSX that addresses the issues from Wave 4.
-**Sub-agent:** `patch-author` — dispatched **once per low-graded page in parallel**.
-**Mode restrictions:**
-- `read-only` — only break, sizing, spacing patches allowed
-- `cosmetic` — read-only patches + image resize, caption compression, paragraph splits at sentence boundaries
-- `editorial` — cosmetic + paragraph rewrites within 15% character or 25% word reduction
-- `creative` — editorial + free composition (the authoring sub-agent fully active)
-**Patch types:**
-- `force-break-before` — insert page break before an element
-- `adjust-spacing` — change Stack/Cluster gap variant
-- `resize-figure` — change Figure width/height variant
-- `compress-paragraph` — drop or merge a sentence (cosmetic+ only)
-- `rewrite-paragraph` — full rewrite (editorial+ only)
-- `rebalance-cluster` — split a Cluster onto two pages
-- `change-affinity` — adjust an affinity prop
-Each patch is applied to `working/draft.jsx`, the validator re-runs, then Wave 3 renders again.
-**Edit tracking (editorial mode):** every paragraph rewrite is logged with before/after to `working/edits.jsonl`. The completion record includes this log.
-### Wave 6 — Deliver
-**Goal:** Final PDF, signed URL, completion record.
-**Process:**
-1. Upload final PDF to R2 with key `brochurify-output/{org_id}/{job_id}.pdf`
-2. Generate 7-day signed URL
-3. Update `brochure_jobs` row:
-   ```sql
-   UPDATE brochure_jobs SET
-     status = 'completed',
-     iter = $iter,
-     current_grade = $grade,
-     page_scores = $pageScoresJson,
-     pdf_r2_key = $r2Key,
-     pdf_url = $signedUrl,
-     completed_at = now()
-   WHERE id = $jobId;
-   ```
-4. Send SSE event `{type:"complete", url, grade, iter}` to broker
-5. Append enhancement log entries from this run to `enhancement-log.jsonl`
-## Trace Logging
-Every wave appends to `working/trace.jsonl`:
-```jsonl
-{"ts":"...","wave":1,"agent":"ingest-author","iter":1,"status":"start"}
-{"ts":"...","wave":1,"agent":"ingest-author","iter":1,"status":"complete","blocks":127}
-{"ts":"...","wave":2,"iter":1,"status":"complete","errors":0}
-{"ts":"...","wave":3,"iter":1,"status":"complete","pages":8,"render_ms":2340}
-{"ts":"...","wave":4,"iter":1,"page":1,"grade":85,"status":"complete"}
-{"ts":"...","wave":4,"iter":1,"page":2,"grade":68,"status":"complete","issues":2}
-...
-```
-This trace is stored in `brochure_jobs.payload.trace` for forensic review.
-## Cost Profile
-- **Wave 1:** 1 sub-agent call (one model invocation)
-- **Wave 2:** 0 model calls (deterministic validator)
-- **Wave 3:** 0 model calls (deterministic render)
-- **Wave 4:** N parallel model calls (N = page count)
-- **Wave 5:** M parallel model calls (M = pages needing patch; usually 0-3)
-- **Wave 6:** 0 model calls
-Typical 8-page brochure, 2 iterations: ~1 + 16 + 4 = ~21 model calls total. All on Max plan. Zero per-job API cost.
-## Hard Caps
-- **Max iterations:** 10 (per D-006)
-- **Max wall-clock:** 15 minutes per job
-- **Max page count:** 50 (anything larger is split into multiple jobs)
-- **Max source size:** 5MB raw HTML, 25MB docx, 50MB total assets
-Exceeding any cap → job fails with structured error; no partial billing.
-## Failure Recovery
-| Failure | Recovery |
-|---|---|
-| Validator fails repeatedly | Try page-size change (Letter → Legal → Digest) before failing job |
-| Vision agent disagrees with itself | Lock grade after 3 iterations of same page; mark "best-effort" |
-| Convergence not reached at iter=10 | Ship best version, flag low-graded pages, log to enhancement |
-| Paged.js render fails | Fall back to direct PDF; flag low-quality iteration |
-| R2 upload fails | Retry 3x then fall back to Supabase storage URL |
-## When to invoke
-Direct user invocation: `rdc:brochurify <source-url-or-path> [--mode] [--theme] [--page-size]`
-Programmatic invocation: a `monkey_dispatch` job arriving with `skill="brochurify"` and the job payload as `args`.
-Either path executes the same 6-wave loop. Direct user invocation also returns the trace and the PDF URL to the calling session.
+---
+name: rdc-brochurify
+version: 0.1.0
+description: |
+  Orchestrate a Brochurify job from source ingest through delivered PDF, using six parallel-dispatched typed sub-agents and the convergence loop. Use this skill EVERY TIME the user invokes Brochurify directly via "brochurify this", "make a brochure from", "convert this to a brochure PDF", or "rdc:brochurify". Also runs automatically when a job arrives from the broker via monkey_dispatch. The skill enforces D-001 through D-016 from the brochurify DECISIONS-LOG.
+triggers:
+  - "rdc:brochurify"
+  - "brochurify this"
+  - "make a brochure from"
+  - "convert to brochure PDF"
+  - "generate brochure from"
+  - monkey_dispatch payload with skill="brochurify"
+---
+# rdc:brochurify Orchestrator
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Report brochure job state, artifacts, and blockers directly; do not dump raw tool logs.
+> **Sandbox contract:** When `RDC_TEST=1`, do not install dependencies, open browsers,
+> upload to R2/Supabase, ask follow-up questions, or fabricate a PDF/grade/URL. Inspect
+> the fixture, report Wave 1 feasibility, and state that render/grade/deliver are
+> gated when the Brochurify runtime is absent.
+The orchestrator dispatches six waves of typed sub-agents in sequence. Each wave has a clear input contract, an output contract, and a parallelism profile.
+## Inputs
+The orchestrator accepts a job payload:
+```json
+{
+  "job_id": "uuid",
+  "source": {
+    "kind": "url" | "html" | "docx" | "md" | "jsx" | "corpus",
+    "ref": "https://..." | "file:///path/..." | "<html>..." | { corpus_query }
+  },
+  "mode": "read-only" | "cosmetic" | "editorial" | "creative",
+  "theme": "prt" | "place-fund" | "zoen" | "evergreen" | "editorial-neutral",
+  "page_size": "letter" | "a4" | "legal" | "digest" | "tabloid",
+  "brief": "optional natural-language brief for editorial/creative modes",
+  "org_id": "uuid",
+  "user_id": "uuid"
+}
+```
+## Outputs
+- A PDF in R2 (`brochurify-output` bucket) with a signed URL
+- A completion record in Supabase `brochure_jobs` with:
+  - `pdf_r2_key`, `pdf_url`
+  - `final_grade`, `page_scores` (jsonb array)
+  - `iter` (iteration count reached)
+  - `trace` (jsonb log of all 6 waves × iterations)
+## The Six Waves
+### Wave 1 — Ingest
+**Goal:** Normalize any source into kit-compliant JSX.
+**Sub-agent:** `ingest-author` (typed agent with the `lifeai-brochure-author` skill loaded)
+**Inputs:** raw source from job payload
+**Outputs:** `working/draft.jsx` (kit-compliant JSX) + `working/assets/` (extracted images)
+**Per-source handling:**
+- `url` — fetch via Playwright (whitelist) or structural-summary mode (open web)
+- `html` — direct ingest, strip scripts/iframes/ads
+- `docx` — pandoc to HTML, then ingest
+- `md` — render to HTML, then ingest
+- `jsx` — pre-built input; skip to validate
+- `corpus` — Creative mode only; corpus reader + Author-Mode-* sub-agent
+**Failure mode:** if ingest cannot map content to kit primitives, raise a structured error with the unmappable content range and ask the user to clarify.
+### Wave 2 — Validate
+**Goal:** Confirm the JSX passes static and structural validation before render.
+**Sub-agent:** none — runs `pnpm bk-lint working/draft.jsx` directly
+**Behavior:**
+- If pass → Wave 3
+- If fail → return errors to Wave 1 agent, retry once
+- If fail twice → escalate to orchestrator: try a different ingest strategy, page-size change, or surface to user
+**Every failure here writes to `enhancement-log.jsonl`** with:
+- `src: "ingest-author"`
+- `fail_layer: "static"` or `fail_layer: "structural"`
+- The specific rule violated
+### Wave 3 — Render
+**Goal:** Produce a first-iteration PDF and per-page screenshots.
+**Sub-agent:** none — runs Paged.js via Playwright headless
+**Process:**
+1. Build the kit + theme bundle into `working/bundle.html`
+2. Open with Paged.js polyfill
+3. Wait for `pagedjs:rendered` event
+4. Snapshot DOM after pagination → `working/paged.html`
+5. Per-page screenshot at 150 DPI → `working/pages/page-{N}.png`
+6. Render to PDF → `working/iter-{i}.pdf`
+**Failure mode:** if Paged.js fails to converge (rare; usually a kit bug), fall back to print-to-PDF without paged-media polyfill, flag as low-quality iteration, continue.
+### Wave 4 — Grade (Vision, Parallel)
+**Goal:** Score each page against the 7-dimension rubric.
+**Sub-agent:** `vision-grader` — dispatched **once per page in parallel**.
+**Per-page inputs:**
+- The page screenshot
+- The source JSX for that page (extracted by walking the paginated DOM)
+- The rubric (R1-R7 with weights and target ranges)
+**Per-page outputs (structured):**
+```json
+{
+  "page": 3,
+  "grade": 82,
+  "dimensions": {
+    "R1_margin_integrity": 95,
+    "R2_bottom_slack": 70,
+    "R3_heading_breathing": 85,
+    "R4_widows_orphans": 100,
+    "R5_image_placement": 80,
+    "R6_table_integrity": 100,
+    "R7_text_density": 75
+  },
+  "issues": [
+    {"dim": "R2", "desc": "tail gap 1.1in below last paragraph", "fix_hint": "compress paragraph or push next-page content"}
+  ]
+}
+```
+**Document grade:** `min(page_grades)` per D-013.
+**Convergence:**
+- Grade ≥ 75 → Wave 6 (Deliver)
+- Grade < 75 AND iter < 10 → Wave 5 (Patch)
+- iter = 10 → Wave 6 with `partial=true` flag
+### Wave 5 — Patch (Parallel)
+**Goal:** Produce a corrected JSX that addresses the issues from Wave 4.
+**Sub-agent:** `patch-author` — dispatched **once per low-graded page in parallel**.
+**Mode restrictions:**
+- `read-only` — only break, sizing, spacing patches allowed
+- `cosmetic` — read-only patches + image resize, caption compression, paragraph splits at sentence boundaries
+- `editorial` — cosmetic + paragraph rewrites within 15% character or 25% word reduction
+- `creative` — editorial + free composition (the authoring sub-agent fully active)
+**Patch types:**
+- `force-break-before` — insert page break before an element
+- `adjust-spacing` — change Stack/Cluster gap variant
+- `resize-figure` — change Figure width/height variant
+- `compress-paragraph` — drop or merge a sentence (cosmetic+ only)
+- `rewrite-paragraph` — full rewrite (editorial+ only)
+- `rebalance-cluster` — split a Cluster onto two pages
+- `change-affinity` — adjust an affinity prop
+Each patch is applied to `working/draft.jsx`, the validator re-runs, then Wave 3 renders again.
+**Edit tracking (editorial mode):** every paragraph rewrite is logged with before/after to `working/edits.jsonl`. The completion record includes this log.
+### Wave 6 — Deliver
+**Goal:** Final PDF, signed URL, completion record.
+**Process:**
+1. Upload final PDF to R2 with key `brochurify-output/{org_id}/{job_id}.pdf`
+2. Generate 7-day signed URL
+3. Update `brochure_jobs` row:
+   ```sql
+   UPDATE brochure_jobs SET
+     status = 'completed',
+     iter = $iter,
+     current_grade = $grade,
+     page_scores = $pageScoresJson,
+     pdf_r2_key = $r2Key,
+     pdf_url = $signedUrl,
+     completed_at = now()
+   WHERE id = $jobId;
+   ```
+4. Send SSE event `{type:"complete", url, grade, iter}` to broker
+5. Append enhancement log entries from this run to `enhancement-log.jsonl`
+## Trace Logging
+Every wave appends to `working/trace.jsonl`:
+```jsonl
+{"ts":"...","wave":1,"agent":"ingest-author","iter":1,"status":"start"}
+{"ts":"...","wave":1,"agent":"ingest-author","iter":1,"status":"complete","blocks":127}
+{"ts":"...","wave":2,"iter":1,"status":"complete","errors":0}
+{"ts":"...","wave":3,"iter":1,"status":"complete","pages":8,"render_ms":2340}
+{"ts":"...","wave":4,"iter":1,"page":1,"grade":85,"status":"complete"}
+{"ts":"...","wave":4,"iter":1,"page":2,"grade":68,"status":"complete","issues":2}
+...
+```
+This trace is stored in `brochure_jobs.payload.trace` for forensic review.
+## Cost Profile
+- **Wave 1:** 1 sub-agent call (one model invocation)
+- **Wave 2:** 0 model calls (deterministic validator)
+- **Wave 3:** 0 model calls (deterministic render)
+- **Wave 4:** N parallel model calls (N = page count)
+- **Wave 5:** M parallel model calls (M = pages needing patch; usually 0-3)
+- **Wave 6:** 0 model calls
+Typical 8-page brochure, 2 iterations: ~1 + 16 + 4 = ~21 model calls total. All on Max plan. Zero per-job API cost.
+## Hard Caps
+- **Max iterations:** 10 (per D-006)
+- **Max wall-clock:** 15 minutes per job
+- **Max page count:** 50 (anything larger is split into multiple jobs)
+- **Max source size:** 5MB raw HTML, 25MB docx, 50MB total assets
+Exceeding any cap → job fails with structured error; no partial billing.
+## Failure Recovery
+| Failure | Recovery |
+|---|---|
+| Validator fails repeatedly | Try page-size change (Letter → Legal → Digest) before failing job |
+| Vision agent disagrees with itself | Lock grade after 3 iterations of same page; mark "best-effort" |
+| Convergence not reached at iter=10 | Ship best version, flag low-graded pages, log to enhancement |
+| Paged.js render fails | Fall back to direct PDF; flag low-quality iteration |
+| R2 upload fails | Retry 3x then fall back to Supabase storage URL |
+## When to invoke
+Direct user invocation: `rdc:brochurify <source-url-or-path> [--mode] [--theme] [--page-size]`
+Programmatic invocation: a `monkey_dispatch` job arriving with `skill="brochurify"` and the job payload as `args`.
+Either path executes the same 6-wave loop. Direct user invocation also returns the trace and the PDF URL to the calling session.