lazycodex-ai 5.0.0-beta.89 → 5.0.0-beta.90

package/packages/shared-skills/skills/ulw-research/scripts/report-tools.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// report-tools.mjs - the ulw-research deliverable CLI. Invoked as
+//   node "$SKILL_DIR/scripts/report-tools.mjs" <command> ...
+// Exit codes: 0 pass, 1 semantic failure (blockers, a failed verify, a blocked repair), 2 usage or IO.
+
+import { CliError, emit, exitCodeFor } from "./cli-support.mjs"
+import { isCliEntry } from "./entry-guard.mjs"
+import { runCheck, runFormatExtract, runLayoutProbe, runOutcome, runRepairDecide } from "./report-tools-commands.mjs"
+
+export const COMMANDS = Object.freeze([
+	"check",
+	"layout-probe",
+	"repair decide",
+	"outcome init",
+	"outcome set",
+	"outcome gate",
+	"outcome render",
+	"outcome state",
+	"outcome verify",
+	"outcome finish",
+	"outcome briefing",
+	"format-extract",
+])
+
+export async function run(argv) {
+	const [command, ...rest] = argv
+	switch (command) {
+		case "check":
+			return runCheck(rest)
+		case "layout-probe":
+			return runLayoutProbe(rest)
+		case "repair":
+			if (rest[0] !== "decide") throw new CliError("usage: repair decide --state <file> --defects <json>")
+			return runRepairDecide(rest.slice(1))
+		case "outcome":
+			return runOutcome(rest)
+		case "format-extract":
+			return runFormatExtract(rest)
+		case "--help":
+		case "help":
+			if (rest.includes("--json")) return { json: { commands: COMMANDS }, exitCode: 0 }
+			return { text: `report-tools <command>\n${COMMANDS.map((name) => `  ${name}`).join("\n")}`, exitCode: 0 }
+		default:
+			throw new CliError(`usage: report-tools <${COMMANDS.join(" | ")}> (run --help)`)
+	}
+}
+
+export async function main(argv = process.argv.slice(2)) {
+	try {
+		const result = await run(argv)
+		emit(result)
+		return exitCodeFor(result)
+	} catch (error) {
+		process.stderr.write(`report-tools: ${error.message}\n`)
+		return exitCodeFor(error)
+	}
+}
+
+if (isCliEntry(import.meta.url)) {
+	process.exitCode = await main()
+}

package/packages/shared-skills/skills/ulw-research/scripts/report-tools.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { delimiter, join } from "node:path"
+
+import { COMMANDS, run } from "./report-tools.mjs"
+
+const SCRIPT = join(import.meta.dir, "report-tools.mjs")
+const FIXTURES = join(import.meta.dir, "tests", "fixtures")
+
+function sessionDir() {
+	const root = mkdtempSync(join(tmpdir(), "report-tools-cli-"))
+	const dir = join(root, "20260101-120000")
+	mkdirSync(dir)
+	return dir
+}
+
+function nodeWithoutBun(args: string[]) {
+	const nodePath = Bun.which("node")
+	if (nodePath === null) throw new Error("node not found on PATH")
+	const path = (process.env.PATH ?? "").split(delimiter).filter((entry) => !entry.includes(".bun")).join(delimiter)
+	return Bun.spawnSync({ cmd: [nodePath, SCRIPT, ...args], env: { ...process.env, PATH: path } })
+}
+
+function defectsFile(dir: string, name: string, codes: string[]) {
+	const file = join(dir, name)
+	writeFileSync(file, JSON.stringify(codes.map((code) => ({ code, message: code }))))
+	return file
+}
+
+describe("help and usage", () => {
+	test("#given --help --json #when run #then it lists exactly the command matrix", async () => {
+		const result = await run(["--help", "--json"])
+		expect(result.json.commands).toEqual([...COMMANDS])
+		expect(COMMANDS).toEqual(["check", "layout-probe", "repair decide", "outcome init", "outcome set", "outcome gate", "outcome render", "outcome state", "outcome verify", "outcome finish", "outcome briefing", "format-extract"])
+	})
+
+	test("#given no arguments under node #when spawned #then it exits 2 with a usage line on stderr", () => {
+		const proc = nodeWithoutBun([])
+		expect(proc.exitCode).toBe(2)
+		expect(proc.stderr.toString()).toContain("usage")
+	})
+
+	test("#given a missing report file #when checked #then it exits 2 naming the path", () => {
+		const proc = nodeWithoutBun(["check", "missing-report.html", "--design-spec", "missing-spec.md"])
+		expect(proc.exitCode).toBe(2)
+		expect(proc.stderr.toString()).toContain("missing-spec.md")
+	})
+})
+
+describe("check", () => {
+	test("#given the bad fixture under node #when checked #then it exits 1 with blockers in stdout JSON", () => {
+		const proc = nodeWithoutBun(["check", join(FIXTURES, "bad-report.html"), "--design-spec", join(FIXTURES, "design-spec.md")])
+		expect(proc.exitCode).toBe(1)
+		const parsed = JSON.parse(proc.stdout.toString())
+		expect(parsed.command).toBe("check")
+		expect(parsed.counts.blocker).toBeGreaterThanOrEqual(1)
+		expect(parsed.layout).toBe("not_run")
+	})
+
+	test("#given the good fixture #when checked #then it passes with exit 0", () => {
+		const proc = nodeWithoutBun(["check", join(FIXTURES, "good-report.html"), "--design-spec", join(FIXTURES, "design-spec.md")])
+		expect(proc.exitCode).toBe(0)
+		expect(JSON.parse(proc.stdout.toString()).status).toBe("pass")
+	})
+
+	test("#given a layout probe file #when checked #then layout gates run and the layout field is set", async () => {
+		const result = await run(["check", join(FIXTURES, "good-report.html"), "--design-spec", join(FIXTURES, "design-spec.md"), "--layout", join(FIXTURES, "boxes.json")])
+		expect(result.json.gatesRun).toContain("layout")
+		expect(["pass", "fail"]).toContain(result.json.layout)
+	})
+})
+
+describe("outcome", () => {
+	test("#given a promised pdf and docx #when verified before and after setting them #then verify fails then passes", async () => {
+		// given
+		const dir = sessionDir()
+		const pdf = join(dir, "report.pdf")
+		writeFileSync(pdf, "x")
+		await run(["outcome", "init", "--session-dir", dir, "--promised", "pdf,docx", "--lane", "no-format"])
+		// when
+		const before = await run(["outcome", "verify", "--session-dir", dir])
+		await run(["outcome", "set", "pdf", "delivered", "--path", pdf, "--session-dir", dir])
+		await run(["outcome", "set", "docx", "skipped", "--reason", "no editing audience", "--session-dir", dir])
+		await run(["outcome", "gate", "static", "pass", "--session-dir", dir])
+		const after = await run(["outcome", "verify", "--session-dir", dir])
+		// then
+		expect(before.exitCode).toBe(1)
+		expect(after.exitCode).toBe(0)
+		const manifest = JSON.parse(readFileSync(join(dir, "outcome.json"), "utf8"))
+		expect(manifest.deliverables.find((row: { format: string }) => row.format === "pdf").path).toBe(pdf)
+		expect(manifest.gates.static).toBe("pass")
+	})
+
+	test("#given a ledger and a fixed now #when the briefing is asked as JSON #then counts come from the ledger and the dir stamp", async () => {
+		const dir = sessionDir()
+		await run(["outcome", "init", "--session-dir", dir, "--promised", "html"])
+		writeFileSync(join(dir, "sources-ledger.md"), ["[S1] https://a.example/x", "[S2] https://b.example/y", "[Source 3] https://a.example/z"].join("\n"))
+		const start = new Date(2026, 0, 1, 12, 0, 0)
+		const now = new Date(start.getTime() + 61 * 60_000).toISOString()
+		const result = await run(["outcome", "briefing", "--json", "--session-dir", dir, "--now", now])
+		expect(result.json.sources).toBe(3)
+		expect(result.json.domains).toBe(2)
+		expect(result.json.minutes).toBe(61)
+	})
+})
+
+describe("repair decide", () => {
+	test("#given three minor code sets with the same measure #when decided in turn #then the third call stops on plateau", async () => {
+		const dir = sessionDir()
+		const state = join(dir, "repair-state.json")
+		const reasons = []
+		for (const [index, code] of ["heading_generic", "heading_too_long", "en_dash_in_prose"].entries()) {
+			const result = await run(["repair", "decide", "--state", state, "--defects", defectsFile(dir, `d${index}.json`, [code]), "--artifact-bytes", "4096", "--renders", "1", "--max-attempts", "5"])
+			reasons.push(result.json.decision.reason)
+		}
+		expect(reasons.at(-1)).toBe("plateau")
+	})
+
+	test("#given the same defects twice #when decided #then the second call stops on oscillation", async () => {
+		const dir = sessionDir()
+		const state = join(dir, "repair-state.json")
+		const file = defectsFile(dir, "d.json", ["heading_generic"])
+		await run(["repair", "decide", "--state", state, "--defects", file, "--artifact-bytes", "4096", "--renders", "1"])
+		const second = await run(["repair", "decide", "--state", state, "--defects", file, "--artifact-bytes", "4096", "--renders", "1"])
+		expect(second.json.decision.reason).toBe("oscillation")
+		expect(second.json.decision.action).toBe("deliver")
+	})
+
+	test("#given no artifact proof #when a stop condition holds #then delivery is blocked (fail closed)", async () => {
+		const dir = sessionDir()
+		const state = join(dir, "repair-state.json")
+		const file = defectsFile(dir, "d.json", ["heading_generic"])
+		await run(["repair", "decide", "--state", state, "--defects", file])
+		const second = await run(["repair", "decide", "--state", state, "--defects", file])
+		expect(second.json.decision.action).toBe("block")
+		expect(second.exitCode).toBe(1)
+	})
+})
+
+describe("layout-probe", () => {
+	test("#given --json #when run #then the source is an async IIFE", async () => {
+		const result = await run(["layout-probe", "--json", "--cap", "20"])
+		expect(result.json.source.startsWith("(async () => {")).toBe(true)
+		expect(result.json.source).toContain("const CAP = 20;")
+	})
+})
+
+describe("manifest bookkeeping", () => {
+	test("#given a session manifest #when repair decides deliver-on-exhaustion #then outcome.json carries the repair summary and the residual defects", async () => {
+		// given
+		const dir = sessionDir()
+		await run(["outcome", "init", "--session-dir", dir, "--promised", "html"])
+		const state = join(dir, "repair-state.json")
+		const file = defectsFile(dir, "d.json", ["heading_generic"])
+		const proof = ["--artifact-bytes", "4096", "--renders", "1", "--session-dir", dir]
+		// when
+		await run(["repair", "decide", "--state", state, "--defects", file, ...proof])
+		await run(["repair", "decide", "--state", state, "--defects", file, ...proof])
+		// then
+		const manifest = JSON.parse(readFileSync(join(dir, "outcome.json"), "utf8"))
+		expect(manifest.repair).toEqual({ attempts: 2, action: "deliver", reason: "oscillation" })
+		expect(manifest.residualDefects.map((d: { code: string }) => d.code)).toEqual(["heading_generic"])
+		const briefing = await run(["outcome", "briefing", "--json", "--session-dir", dir])
+		expect(briefing.json.residualDefects).toBe(1)
+		expect(briefing.json.repair).toEqual({ attempts: 2, action: "deliver", reason: "oscillation" })
+	})
+
+	test("#given a clean repair decision #when recorded #then residual defects are emptied", async () => {
+		const dir = sessionDir()
+		await run(["outcome", "init", "--session-dir", dir, "--promised", "html"])
+		const state = join(dir, "repair-state.json")
+		await run(["repair", "decide", "--state", state, "--defects", defectsFile(dir, "a.json", ["heading_generic"]), "--session-dir", dir])
+		await run(["repair", "decide", "--state", state, "--defects", defectsFile(dir, "b.json", []), "--session-dir", dir])
+		const manifest = JSON.parse(readFileSync(join(dir, "outcome.json"), "utf8"))
+		expect(manifest.residualDefects).toEqual([])
+		expect(manifest.repair.reason).toBe("clean")
+	})
+
+	test("#given a ledger and a fixed now #when the run is finished #then finishedAt, elapsedMinutes and source counts are stamped and still validate", async () => {
+		const dir = sessionDir()
+		const pdf = join(dir, "report.pdf")
+		writeFileSync(pdf, "x")
+		await run(["outcome", "init", "--session-dir", dir, "--promised", "pdf"])
+		await run(["outcome", "set", "pdf", "delivered", "--path", pdf, "--session-dir", dir])
+		writeFileSync(join(dir, "sources-ledger.md"), ["[S1] https://a.example/x", "[S2] https://b.example/y"].join("\n"))
+		const now = new Date(new Date(2026, 0, 1, 12, 0, 0).getTime() + 30 * 60_000).toISOString()
+		const result = await run(["outcome", "finish", "--session-dir", dir, "--now", now])
+		const manifest = JSON.parse(readFileSync(join(dir, "outcome.json"), "utf8"))
+		expect(result.exitCode).toBe(0)
+		expect(manifest.finishedAt).toBe(now)
+		expect(manifest.elapsedMinutes).toBe(30)
+		expect(manifest.sources).toEqual({ total: 2, domains: 2 })
+		expect((await run(["outcome", "verify", "--session-dir", dir])).exitCode).toBe(0)
+	})
+})
+
+describe("format-extract exit codes", () => {
+	test("#given a pdf reference under node #when extracted #then it exits 2 with the unsupported message", () => {
+		const dir = sessionDir()
+		const pdf = join(dir, "reference.pdf")
+		writeFileSync(pdf, "%PDF-1.7")
+		const proc = nodeWithoutBun(["format-extract", pdf, "--out", join(dir, "design-spec.md")])
+		expect(proc.exitCode).toBe(2)
+		expect(proc.stderr.toString()).toContain("unsupported")
+	})
+
+	test("#given an unreachable url #when extracted #then it exits 2", () => {
+		const dir = sessionDir()
+		const proc = nodeWithoutBun(["format-extract", "http://127.0.0.1:9/report.html", "--from-url", "--out", join(dir, "design-spec.md")])
+		expect(proc.exitCode).toBe(2)
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/assets/figure-1.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="360" viewBox="0 0 640 360"><rect width="640" height="360" fill="#f7f5f0"/></svg>

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/bad-report.html

@@ -0,0 +1,44 @@
+<!doctype html>
+<html lang="ko">
+<head>
+<meta charset="utf-8">
+<title>Static gate fixture: every static defect once</title>
+<style>
+:root { --bg: #f7f5f0; --fg: #1f1d1a; --accent: #2f6f4f; }
+body { background: var(--bg); color: var(--fg); font-family: "Nanum Myeongjo", serif; }
+.note { color: #123456; }
+</style>
+</head>
+<body>
+<main>
+<h1>분기별 배포 지표 점검 보고서</h1>
+<section>
+<h2>배포 지표가 흔들린 분기</h2>
+<p>이번 분기에는 배포 파이프라인을 두 번 바꿨고, 그 과정을 기록으로 남겼어요 [S1].</p>
+<p>매출이 12.5% 증가했다.</p>
+<p>The rollout finished early — nobody expected that [S1].</p>
+<p>A quick win–loss review followed [S1].</p>
+<p>Launch day went well 🚀 [S1].</p>
+<h3>Summary</h3>
+<h3>This subsection heading keeps going far past any sensible single line of text</h3>
+<img src="data:image/png;base64,iVBORw0KGgo=" alt="unwrapped chart" width="480" height="240">
+<figure>
+<svg width="480" height="240" viewBox="0 0 480 240"><rect x="0" y="0" width="40" height="120" fill="#2f6f4f"/></svg>
+<figcaption>Blank chart [S1]</figcaption>
+</figure>
+<figure>
+<svg width="480" height="240" viewBox="0 0 480 240"><title>Weekly deploys</title><text x="4" y="230">0</text><text x="4" y="20">10</text><text x="200" y="236">Deploys</text></svg>
+<figcaption>Two ticks only [S1]</figcaption>
+</figure>
+<figure>
+<img src="assets/missing-figure.png" alt="lost asset" width="480" height="240">
+<figcaption>Lost asset [S1]</figcaption>
+</figure>
+</section>
+<section>
+<h2>팀 구성은 그대로였다</h2>
+<p>팀 구성은 분기 내내 바뀌지 않았고, 새로 합류한 사람도 떠난 사람도 없었어요. 역할 분담도 그대로여서 배포 담당자는 여전히 한 사람이었고, 리뷰는 돌아가면서 맡았습니다. 회의 방식과 문서 양식도 이전 분기와 같았어요. 그래서 이 절에서는 사람 쪽 변화가 원인이라고 보기 어렵다는 점만 적어 둡니다.</p>
+</section>
+</main>
+</body>
+</html>

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/boxes.json

@@ -0,0 +1,90 @@
+{
+	"probe_version": 1,
+	"viewport": { "w": 1280, "h": 900 },
+	"document": { "w": 1280, "h": 9240 },
+	"count": 7,
+	"truncated": false,
+	"boxes": [
+		{
+			"selector": "body > main > section:nth-of-type(1) > h2",
+			"tag": "h2",
+			"rect": { "x": 353, "y": 420, "w": 574, "h": 38.4 },
+			"parentSelector": "body > main > section:nth-of-type(1)",
+			"parentRect": { "x": 353, "y": 400, "w": 574, "h": 1400 },
+			"scroll": { "sw": 574, "cw": 574, "sh": 38, "ch": 38 },
+			"overflow": { "x": "visible", "y": "visible" },
+			"position": "static",
+			"textLen": 31
+		},
+		{
+			"selector": "body > main > section:nth-of-type(1) > p:nth-of-type(1)",
+			"tag": "p",
+			"rect": { "x": 353, "y": 474.4, "w": 574, "h": 115.6 },
+			"parentSelector": "body > main > section:nth-of-type(1)",
+			"parentRect": { "x": 353, "y": 400, "w": 574, "h": 1400 },
+			"scroll": { "sw": 574, "cw": 574, "sh": 116, "ch": 116 },
+			"overflow": { "x": "visible", "y": "visible" },
+			"position": "static",
+			"textLen": 212
+		},
+		{
+			"selector": "body > main > section:nth-of-type(1) > figure:nth-of-type(1)",
+			"tag": "figure",
+			"rect": { "x": 353, "y": 614, "w": 574, "h": 761 },
+			"parentSelector": "body > main > section:nth-of-type(1)",
+			"parentRect": { "x": 353, "y": 400, "w": 574, "h": 1400 },
+			"scroll": { "sw": 574, "cw": 574, "sh": 761, "ch": 761 },
+			"overflow": { "x": "visible", "y": "visible" },
+			"position": "static",
+			"textLen": 48
+		},
+		{
+			"selector": "body > main > section:nth-of-type(1) > figure:nth-of-type(1) > img",
+			"tag": "img",
+			"rect": { "x": 353, "y": 614, "w": 574, "h": 717 },
+			"parentSelector": "body > main > section:nth-of-type(1) > figure:nth-of-type(1)",
+			"parentRect": { "x": 353, "y": 614, "w": 574, "h": 761 },
+			"scroll": { "sw": 574, "cw": 574, "sh": 717, "ch": 717 },
+			"overflow": { "x": "visible", "y": "visible" },
+			"position": "static",
+			"textLen": 0,
+			"objectFit": "fill",
+			"natural": { "w": 1280, "h": 1600 }
+		},
+		{
+			"selector": "body > main > section:nth-of-type(1) > figure:nth-of-type(2)",
+			"tag": "figure",
+			"rect": { "x": 353, "y": 1399, "w": 574, "h": 368.4 },
+			"parentSelector": "body > main > section:nth-of-type(1)",
+			"parentRect": { "x": 353, "y": 400, "w": 574, "h": 1400 },
+			"scroll": { "sw": 574, "cw": 574, "sh": 368, "ch": 368 },
+			"overflow": { "x": "visible", "y": "visible" },
+			"position": "static",
+			"textLen": 52
+		},
+		{
+			"selector": "body > main > section:nth-of-type(1) > figure:nth-of-type(2) > img",
+			"tag": "img",
+			"rect": { "x": 353, "y": 1399, "w": 574, "h": 324.4 },
+			"parentSelector": "body > main > section:nth-of-type(1) > figure:nth-of-type(2)",
+			"parentRect": { "x": 353, "y": 1399, "w": 574, "h": 368.4 },
+			"scroll": { "sw": 574, "cw": 574, "sh": 324, "ch": 324 },
+			"overflow": { "x": "visible", "y": "visible" },
+			"position": "static",
+			"textLen": 0,
+			"objectFit": "fill",
+			"natural": { "w": 1100, "h": 620 }
+		},
+		{
+			"selector": "#method > pre",
+			"tag": "pre",
+			"rect": { "x": 353, "y": 8120, "w": 574, "h": 180 },
+			"parentSelector": "#method",
+			"parentRect": { "x": 353, "y": 8040, "w": 574, "h": 420 },
+			"scroll": { "sw": 812, "cw": 550, "sh": 156, "ch": 156 },
+			"overflow": { "x": "auto", "y": "auto" },
+			"position": "static",
+			"textLen": 640
+		}
+	]
+}

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/design-spec.md

@@ -0,0 +1,29 @@
+# Design spec
+
+## Extracted from
+- Source: fixture written by hand for the static gate tests
+
+## Tokens
+```css
+:root {
+  --bg: #f7f5f0;
+  --fg: #1f1d1a;
+  --accent: #2f6f4f;
+  --rule: #d9d4c7;
+  --mute: #6b665c;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #121110;
+    --fg: #e8e4dc;
+    --accent: #7fbf9f;
+  }
+}
+```
+
+## Typography
+- Body font: Pretendard, "Apple SD Gothic Neo", sans-serif
+
+## Citations
+- Style: bracket-S
+- Lineage: inline

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/good-report.html

@@ -0,0 +1,57 @@
+<!doctype html>
+<html lang="ko">
+<head>
+<meta charset="utf-8">
+<title>Static gate fixture: passing report</title>
+<style>
+:root { --bg: #f7f5f0; --fg: #1f1d1a; --accent: #2f6f4f; --rule: #d9d4c7; --mute: #6b665c; --ff: Pretendard, "Apple SD Gothic Neo", sans-serif; }
+@media (prefers-color-scheme: dark) { :root { --bg: #121110; --fg: #e8e4dc; --accent: #7fbf9f; } }
+body { background: var(--bg); color: var(--fg); font-family: var(--ff); word-break: keep-all; overflow-wrap: anywhere; }
+th, td { border-bottom: 1px solid var(--rule); }
+figcaption { color: var(--mute); }
+.card { background: #fff; }
+</style>
+</head>
+<body>
+<header><h1>소규모 팀의 배포 속도 비교</h1></header>
+<main>
+<section id="speed">
+<h2>배포 주기가 짧아진 이유 <svg class="mark" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M2 8h12" stroke="#1f1d1a"/></svg></h2>
+<p>매출이 12.5% 증가했다 [S1]. 같은 기간 팀 규모는 그대로였어요.</p>
+<p>2019–2024 구간을 기준으로 비교했습니다.</p>
+<p>배포는 한 달에 48건이었어요 MEASURED.</p>
+<p data-lineage="DERIVED">평균 리드 타임은 3.2일로 계산했어요.</p>
+<p>리뷰 대기 시간은 40% 줄었습니다 <a href="#s3">[3]</a>.</p>
+<figure>
+<img src="assets/figure-1.svg" alt="월별 배포 건수" width="640" height="360">
+<figcaption>그림 1. 월별 배포 건수 [S1]</figcaption>
+</figure>
+<figure class="chart">
+<svg width="640" height="320" viewBox="0 0 640 320" role="img"><title>Monthly deploys</title><rect x="40" y="100" width="60" height="200" fill="#2f6f4f"/><text x="4" y="300" font-size="12">0</text><text x="4" y="200" font-size="12">25</text><text x="4" y="100" font-size="12">50</text><text x="300" y="316" font-size="12">Deploys per month</text></svg>
+<figcaption>월별 배포 추이 [S2]</figcaption>
+</figure>
+<table>
+<thead><tr><th>항목</th><th>상태</th></tr></thead>
+<tbody><tr><td>자동 배포</td><td>✓</td></tr><tr><td>수동 승인</td><td>—</td></tr></tbody>
+</table>
+</section>
+<section id="review">
+<h2>Review load moved to the author</h2>
+<p>Authors now merge their own changes after a green build, which the team describes as the main reason reviews stopped queueing behind one maintainer [S2].</p>
+</section>
+<section id="method">
+<h2>How this report was made</h2>
+<p>We read the public changelog and counted 147 entries by hand, then checked the totals against the team handbook.</p>
+</section>
+<section id="sources">
+<h2>Sources</h2>
+<ol>
+<li id="s1">Quarterly engineering review — internal summary, 2024</li>
+<li id="s2">Team handbook, deploy chapter</li>
+<li id="s3">Review queue dashboard export</li>
+</ol>
+</section>
+</main>
+<footer><p>Fixture for the static gate tests.</p></footer>
+</body>
+</html>

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/reference-report.html

@@ -0,0 +1,86 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Reference report</title>
+<style>
+:root {
+  --bg: #faf6ef;
+  --bg-raise: #ffffff;
+  --fg: #24211b;
+  --fg-mute: #6d6759;
+  --rule: #e4dccb;
+  --accent: #c2410c;
+  --accent-soft: #fbe7d4;
+  --good: #15803d;
+  --measure: 720px;
+  --ff-body: "Inter Display", "Noto Sans KR", sans-serif;
+  --ff-head: "Fraunces", Georgia, serif;
+  --ff-mono: "Iosevka Term", ui-monospace, monospace;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0c0b0a;
+    --bg-raise: #171512;
+    --fg: #fbf0df;
+    --fg-mute: #b3a992;
+    --rule: #2b2721;
+    --accent: #f8b878;
+    --accent-soft: #2a2013;
+    --good: #7cd992;
+  }
+}
+</style>
+<style>
+body {
+  margin: 0;
+  font-family: var(--ff-body);
+  font-size: 17px;
+  line-height: 1.7;
+  color: var(--fg);
+  background: var(--bg);
+}
+h1, h2, h3 { font-family: var(--ff-head); color: #24211b; }
+a { color: #c2410c; }
+code, pre { font-family: var(--ff-mono); }
+.wrap { max-width: var(--measure); margin: 0 auto; padding: 0 16px; }
+.fig { border: 1px solid #e4dccb; background: #ffffff; padding: 16px; }
+.fig img { max-width: 100%; height: auto; object-fit: contain; }
+.fig-cap { color: #6d6759; font-size: 14px; }
+@media (min-width: 560px) { .wrap { padding: 0 24px; } }
+@media (min-width: 640px) { .grid { display: grid; grid-template-columns: 1fr 1fr; } }
+</style>
+</head>
+<body>
+<main class="wrap">
+<h1>How a small team ships every week</h1>
+<p>A reference report used as a format source. Weekly releases held for 19 months [S1].</p>
+<section>
+<h2>01 The release cadence</h2>
+<p>The team shipped 147 announcements in 16 months [S1]. The monthly mean is 8.75 [S2].</p>
+<figure class="fig chart">
+<svg viewBox="0 0 200 100" role="img"><title>Announcements per month</title><text x="4" y="12">count</text></svg>
+<figcaption class="fig-cap">Announcements per month, counted from the changelog [S1].</figcaption>
+</figure>
+</section>
+<section>
+<h2>02 How work is reviewed</h2>
+<p>Work lands on the main branch without a review queue [S3].</p>
+<div class="fig">
+<img src="data:image/gif;base64,R0lGODlhAQABAAAAACw=" alt="Screenshot of the note">
+<p class="fig-cap">The published note, captured on the access date [S3].</p>
+</div>
+<pre><code>git push origin main</code></pre>
+</section>
+<section>
+<h2>03 Sources</h2>
+<ol>
+<li>[S1] Changelog, accessed 2026-09-16.</li>
+<li>[S2] Derived monthly mean.</li>
+<li>[S3] Engineering note, accessed 2026-09-16.</li>
+</ol>
+</section>
+</main>
+</body>
+</html>

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/reference.md

@@ -0,0 +1,23 @@
+# 작은 팀은 어떻게 매주 배포하는가
+
+기준일은 2026년 9월 16일입니다 [S1].
+
+## 01 배포 주기
+
+제품 공지는 147건이었어요 [S1]. 월평균은 8.75건입니다 [S2].
+
+```md
+## 99 not a heading inside a fence
+```
+
+### Details below the section level
+
+## 02 리뷰 없이 일하는 방식
+
+작업은 리뷰 대기열 없이 main 에 들어갑니다 [S3].
+
+## 03 출처
+
+- [S1] Changelog, accessed 2026-09-16.
+- [S2] Derived monthly mean.
+- [S3] Engineering note, accessed 2026-09-16.

package/packages/shared-skills/skills/visual-qa/references/browser-setup.md

@@ -58,7 +58,9 @@ try {
 
 NEVER launch anything against, or clear cookies/cache/site data from, the user's live profile;
 the attached engine is the only sanctioned way to a signed-in page. If no extension is connected,
-run the `browser` skill's `scripts/browser-install.mjs`, relay its one human step, and wait — do
+run the `browser` skill's `scripts/browser-install.mjs` for the browser the user actually uses
+(from memory, or its detection; on `needsChoice` ask them and pass `--browser=<id>`), relay its
+one human step, and wait — do
 not fall back to the owned engine for an authenticated criterion.
 
 ## Capture a screenshot at a fixed viewport