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

package/packages/shared-skills/skills/ulw-research/references/deliverable-phase.md

@@ -0,0 +1,187 @@
+# ulw-research - deliverable phase contract
+
+Read this before the brief is written and again before Phase 6. It replaces the old blocking format question with a contract that never stalls collection: the deliverable is derived from the request and its destination, the requester is asked only what is genuinely missing, and every promise made about the output is tracked in a manifest until it is delivered, skipped, or blocked with a reason.
+
+Every helper named here is one command of the dispatcher:
+
+```bash
+node "$SKILL_DIR/scripts/report-tools.mjs" <command> ...
+```
+
+`$SKILL_DIR` is the directory of the skill's `SKILL.md`. The helpers are plain `.mjs` files with no dependencies and run under `node` or `bun` on macOS, Linux, and Windows. They never launch a browser. Exit codes: `0` pass, `1` semantic failure (blockers found, a failed verify, a blocked repair), `2` usage or IO error. JSON goes to stdout and a one-line summary to stderr. Always pass `--session-dir "$SESSION_DIR"` explicitly; `SESSION_DIR` in the environment is only a fallback.
+
+## 1. Lanes
+
+The brief names exactly one lane. The lane decides how much the requester is asked, what the design spec starts from, and how strict the gates are.
+
+| Lane | Definition | How to say it to the requester |
+| --- | --- | --- |
+| `template-strict` | The requester pointed at a document (a prior report, a page, a house template). Its structure, tokens, citation style, and figure standard are copied mechanically and not reinterpreted. | "I will match the document you pointed at: same structure, colors, fonts, and citation style." |
+| `template-vibe` | The requester named a register or feeling ("like a consulting deck", "a clean blog post") without a document to copy. The design spec is written from the defaults in section 6 and the register. | "I will write it in that style using the default report design; point me at an example if you want an exact match." |
+| `no-format` | Nothing about the shape was said and the destination implies it (a chat answer, a thread post, a quick note). No interview about format. | "I will answer in the shape this destination expects." |
+| `edit-existing` | A complete deliverable for this question already exists (section 2). The run edits it in place. It never regenerates it. | "I will update the existing report rather than write a new one." |
+
+## 2. Deliverable state
+
+Before the brief is written, decide the state of any deliverable the request refers to:
+
+```bash
+node "$SKILL_DIR/scripts/report-tools.mjs" outcome state --deliverable <path> --session-dir "$SESSION_DIR"
+```
+
+| State | Meaning | What it opens |
+| --- | --- | --- |
+| `none` | No file, or an empty one. | A fresh run in the lane the request implies. |
+| `partial` | The file carries a `STATUS: draft` line in its first 5 lines, or its manifest still has a `pending` row. | Resume the on-disk skeleton: keep the sections that exist, fill the missing ones, and never start over. |
+| `complete` | The manifest says every promised row is resolved and the file is present and non-empty. | `edit-existing` only. A complete report is never regenerated from scratch. |
+
+## 3. Destination-derived defaults
+
+The request and its destination usually answer the format question already. Derive the defaults first; the interview (section 4) only covers what this table leaves open.
+
+| Request or destination signal | Default format set | Lane | QA tier |
+| --- | --- | --- | --- |
+| A question answered in chat, with no document asked for | `post` (the answer itself, Markdown) | `no-format` | light |
+| A thread, channel, or messenger post | `post` | `no-format` | light |
+| A web page URL as the destination, or "blog", "page" | `html` | `template-vibe` | full |
+| The words "PDF", "DOCX", "slides", or "LaTeX" in the request | exactly the named formats (`pdf`, `docx`, `slides`, `latex`) | `template-vibe` | full |
+| "Report", "document", "write-up" with no format word and no destination | `pdf` + `docx` | `template-vibe` | full |
+| A pointed-at document (a file, a URL, a prior report) | the reference's own format | `template-strict` | full |
+| A prior report of the same kind in this workspace, not pointed at | that report's format, offered as the Q1 default | `template-vibe` | full |
+| A complete existing deliverable for this question (section 2) | its existing format | `edit-existing` | the original's tier |
+
+QA tiers: **light** runs the static gates and one render check of the answer. **Full** runs the static gates, the layout gates, visual QA of every page, and the proofread gate (section 7).
+
+## 4. The empty-info interview
+
+The interview has exactly three questions, asked together through the harness question tool without waiting for the answer. A question is **skipped** when the request, the destination, a pointed-at document, or a declared memory episode already answers it; when all three are answered, nothing is asked.
+
+- **Q1 - destination and format.** Options in this order: the memory hit (the choice recorded for the most similar prior context, section 5) when there is one; the derived default from section 3; "describe the format in your own words" (free text, which becomes the brief for the design spec); "don't care, you decide" (resolves to the derived default).
+- **Q2 - audience and length.** Who reads it, and a length band: `short` (a page or a post), `standard` (a report of about 5 to 12 pages), or `deep` (a full dossier). The derived default is first.
+- **Q3 - template lineage.** The pointed-at document, the last report of the same kind, or the clean analyst register (section 6). The derived default is first.
+
+Non-blocking rule: ask, do not wait, and start collection. Write `brief.md` at once with every field and who answered it; the unanswered fields carry their defaults. A late answer is folded in until the assembly lane starts; after that it becomes a re-render request, handled like any other repair.
+
+Recorded fields, under `## Deliverable` in `brief.md`:
+
+```text
+lane: template-vibe
+state: none
+formats: pdf, docx (answered_by: request)
+destination: internal review document (answered_by: default)
+audience: engineering leads, standard (answered_by: user)
+template: clean analyst register (answered_by: default)
+format description: none
+```
+
+`answered_by` is one of `user`, `default`, `request`. Run `outcome init` (section 9) in the same step, with the formats as the promised list.
+
+## 5. Report-format memory episodes
+
+When the memory tool is present, the requester's report-format choices are kept as an append-only episode log, so a repeat requester is not asked the same question twice. When no memory tool is present, skip this section silently.
+
+- Pointer: `system/human/report-style.md`, projected every session. One line naming the log, plus the generalizations currently in force.
+- Episode log: `reference/human-report-style.md`, one line per episode, newest last:
+
+```text
+- [YYYY-MM-DD] <destination kind> · <audience> - <format and template chosen, one line> <!-- src: <session-id>; pattern: observed|declared; confidence: low|medium|high -->
+```
+
+Qualification (write after delivery, only when one of these holds): `declared` - the requester stated the preference outright ("always PDF only"); `observed` - the requester made the same unsolicited choice on 2 or more runs (read the log first). Record format and template choices only, never report content, subjects, names, or findings. Append; never rewrite an existing line.
+
+Read-time generalization (before the interview): a similar context is one with the same destination kind and audience. Consistent similar episodes supply Q1's first option; a `declared` similar episode skips the question it answers. One session never flips a default: a single `observed` episode that disagrees with the rest changes nothing.
+
+Pruning: keep the log near 15 lines. When it grows past that, prune the oldest episodes that agree with the majority for their context first. Never prune a `declared` episode or a minority episode (the only one recording a different choice for its context). Update the pointer in the same memory commit when a generalization changes.
+
+## 6. design-spec.md
+
+Write `$SESSION_DIR/design-spec.md` the moment the deliverable fields are known, before any asset lane starts. Every asset and assembly lane receives it.
+
+1. When a document was pointed at, extract it first. Do not retype its stylesheet:
+   ```bash
+   node "$SKILL_DIR/scripts/report-tools.mjs" format-extract <reference.html|reference.md> --out "$SESSION_DIR/design-spec.md"
+   node "$SKILL_DIR/scripts/report-tools.mjs" format-extract <https://...> --from-url --out "$SESSION_DIR/design-spec.md"
+   ```
+   The extractor copies the CSS custom properties (light and dark), font stacks by role, the most-used colors, px breakpoints, the section skeleton, the heading numbering, the citation marker style, the lineage mode, and the figure containers, under the fixed sections `Extracted from`, `Tokens`, `Typography`, `Layout`, `Structure`, `Figures`, `Citations`, `Open questions`. A field it cannot determine reads `TODO: ask`. A PDF reference is unsupported: ask for its HTML or Markdown source.
+2. Fill every `TODO: ask` from the interview answers, then from the clean analyst register below. Never guess a value.
+3. Apply the binding figure standard and the defaults:
+   - Every figure sits in a fixed-size container with a caption; the image scales inside it with contain-fit, its aspect ratio preserved, never stretched, cropped, or spilling out. Every chart carries a title, axis labels, units, and value labels as real text, with deterministic ticks (round values computed from the data range, never left to a renderer's auto-scaling).
+   - One accent color over neutral background, text, and rule tones. Every color in prose, charts, and diagrams is a spec token.
+   - For web deliverables, HTML/CSS bars and inline SVG are preferred over image charts, and the page has responsive breakpoints so it reads on a phone, a tablet, and a desktop.
+   - Gothic (sans) type only, as a real embedded webfont for the report language; Korean text uses `word-break: keep-all; overflow-wrap: anywhere`.
+   - A closing section on how the report was made (method, sources, members and waves, the gates it passed, what verification overturned) and a numbered sources section with access dates.
+4. Declare the lineage mode on its own line in the spec:
+   - `Lineage: inline` (the analyst default): every unit-bearing number carries `MEASURED`, `ASSUMED`, or `DERIVED` inline or in a `data-lineage` attribute, or a `[S<n>]` citation in the same element. The gate reports an untagged number as a major defect.
+   - `Lineage: section` (web and blog register): sources are bracketed source-label links at sentence end (the report language's word for "source"), lineage distinctions live in the figure captions, and every section is cited. The gate reports an untagged number as an advisory minor defect; the section-citation gate carries the weight.
+
+## 7. Delivery gates, in order
+
+Nothing reaches the requester until the gates for its QA tier pass, in this order. Each gate writes its status into the manifest with `outcome gate <gate> <pass|fail|not_run> --session-dir "$SESSION_DIR"`.
+
+1. **Static gates.** `check` on the rendered HTML:
+   ```bash
+   node "$SKILL_DIR/scripts/report-tools.mjs" check "$SESSION_DIR/report.html" --design-spec "$SESSION_DIR/design-spec.md" > "$SESSION_DIR/defects.json"
+   ```
+   It checks keep-all, palette tokens, emoji, em dashes in prose (en dashes outside numeric ranges are advisory), heading length and generic headings, unsourced numbers (section 6), figure containers and captions, chart SVG text, Korean serif fonts, sections without citations, the closing section, the sources section, broken local assets, and any `--require-section <regex>` the brief requires. Every code, severity, and fix is in [report-gates.md](report-gates.md).
+2. **Layout gates.** Print the probe, evaluate it in the rendered page through the browser skill's owned headless engine, save the returned object as `$SESSION_DIR/boxes.json`, and re-run `check` with `--layout "$SESSION_DIR/boxes.json"`. It adds overflow past the container, clipped text, scroll containers, distorted images, and overlapping siblings.
+   ```bash
+   node "$SKILL_DIR/scripts/report-tools.mjs" layout-probe --json   # .source is one async expression
+   ```
+3. **Visual QA.** Render the artifact to images (PDF pages to PNG, the HTML in the browser skill's engine at desktop and phone widths) and look at the pixels for what a machine cannot see: composition, hierarchy, page breaks, figure legibility.
+4. **Proofread.** A dedicated writing lane proofreads the final text only (grammar, spelling, punctuation, terminology, native register); it never composes or rewrites content.
+
+The light tier runs gate 1 and one render (recorded as `visual`) and records `layout` and `proofread` as `not_run`. The full tier runs all four.
+
+## 8. Bounded repair loop
+
+After every gate run that produced defects, ask the tracker what to do next:
+
+```bash
+node "$SKILL_DIR/scripts/report-tools.mjs" repair decide --state "$SESSION_DIR/repair-state.json" --defects "$SESSION_DIR/defects.json" --artifact-bytes <report bytes> --renders <rendered page count> --session-dir "$SESSION_DIR"
+```
+
+- `action: repair`: fix the listed defects, re-render, re-run the gate, and ask again.
+- `action: deliver`: stop repairing and deliver. `reason` is `clean` or the stop condition that fired; the residual defects are written into the manifest and listed in the closing briefing.
+- `action: block` (exit `1`): do not deliver. Either a content-integrity defect remains (`missing_closing_section`, `missing_citation_section`, `broken_asset_reference`, `missing_required_section`, `missing_promised_deliverable`), or a stop fired without proof of a usable artifact (`--artifact-bytes` and `--renders`). Tell the requester what blocks delivery and record the affected rows as `failed` with the reason.
+
+Defaults: 3 repair attempts, a plateau of 2 consecutive attempts that do not improve the (blocker, major, minor) counts compared in that order, and 15 minutes of wall clock from the first decision. A defect set that repeats an earlier attempt exactly stops the loop as an oscillation. When several conditions hold at once the reported reason follows `clean`, `blocking`, `oscillation`, `plateau`, `max_attempts`, `wall_clock`.
+
+## 9. Outcome manifest and closing briefing
+
+`$SESSION_DIR/outcome.json` tracks every promise made about the output, so a promised format is never silently dropped.
+
+```bash
+node "$SKILL_DIR/scripts/report-tools.mjs" outcome init --promised pdf,docx --lane template-vibe --session-dir "$SESSION_DIR"
+node "$SKILL_DIR/scripts/report-tools.mjs" outcome set pdf delivered --path "$SESSION_DIR/report.pdf" --pages 12 --session-dir "$SESSION_DIR"
+node "$SKILL_DIR/scripts/report-tools.mjs" outcome set docx blocked_capability --reason "no document converter in this session" --session-dir "$SESSION_DIR"
+node "$SKILL_DIR/scripts/report-tools.mjs" outcome render "$SESSION_DIR/renders/page-01.png" --page 1 --session-dir "$SESSION_DIR"
+node "$SKILL_DIR/scripts/report-tools.mjs" outcome verify --session-dir "$SESSION_DIR"
+node "$SKILL_DIR/scripts/report-tools.mjs" outcome finish --session-dir "$SESSION_DIR"
+node "$SKILL_DIR/scripts/report-tools.mjs" outcome briefing --session-dir "$SESSION_DIR"
+```
+
+- `init` runs when the brief is written (section 4): one `pending` row per promised format (`pdf`, `docx`, `html`, `md`, `latex`, `slides`, `post`).
+- `set` resolves a row: `delivered` (absolute path; bytes are read from disk; pages when paginated), `blocked_capability` (this session cannot produce it), `skipped` (the requester or the lane dropped it), or `failed`. Every status except `delivered` needs `--reason`.
+- `verify` runs before delivery and exits `1` while a row is `pending`, a status lacks its reason, or a delivered file is missing or empty.
+- `finish` stamps the finish time, the elapsed minutes from the session directory's start stamp, and the source and domain counts from `sources-ledger.md`.
+- `briefing` prints the closing block from the manifest and the ledger: sources and distinct domains, elapsed minutes, every deliverable with its status, the gate results, the residual defects, and the repair summary. That text is the closing briefing, pasted as printed, never filled in from memory.
+
+## 10. Command reference
+
+Invoke every command as `node "$SKILL_DIR/scripts/report-tools.mjs" <command>`. Exit codes for all of them: `0` pass, `1` semantic failure, `2` usage or IO error.
+
+| Command | Flags | Exit `1` when |
+| --- | --- | --- |
+| `check <report.html>` | `--design-spec <spec>` (required), `--layout <boxes.json>`, `--require-section <regex>` (repeatable), `--max-defects N` | any blocker defect |
+| `layout-probe` | `--cap N` (default 400), `--root <selector>` (default `main, article`), `--json` | never |
+| `repair decide` | `--state <file>` and `--defects <json>` (required), `--artifact-bytes N`, `--renders N`, `--session-dir <dir>`, `--max-attempts N`, `--plateau-limit N`, `--wall-clock-ms N`, `--now <ISO>` | the decision is `block` |
+| `outcome init` | `--promised <list>` (required), `--lane <lane>`, `--session-dir <dir>`, `--now <ISO>` | never |
+| `outcome set <format> <status>` | `--path <file>`, `--pages N`, `--reason <text>`, `--session-dir <dir>`, `--now <ISO>` | never |
+| `outcome gate <gate> <status>` | `--session-dir <dir>` | never |
+| `outcome render <png>` | `--page N` (required), `--session-dir <dir>` | never |
+| `outcome state` | `--deliverable <path>` (required), `--session-dir <dir>` | never |
+| `outcome verify` | `--session-dir <dir>` | a promise is unresolved or a delivered file is missing or empty |
+| `outcome finish` | `--ledger <file>`, `--session-dir <dir>`, `--now <ISO>` | never |
+| `outcome briefing` | `--json`, `--ledger <file>`, `--session-dir <dir>`, `--now <ISO>` | never |
+| `format-extract <reference>` | `--out <design-spec.md>` (required), `--from-url` | never (an unsupported reference exits `2`) |
+| `--help` | `--json` | never |

package/packages/shared-skills/skills/ulw-research/references/report-gates.md

@@ -0,0 +1,66 @@
+# Report-Gates Defect Glossary
+
+This reference catalogs every defect code the report gates (`static`, `layout`, `visual`, `proofread`) can raise, their severity and impact, and how to repair them.
+
+## Defect Codes by Category
+
+### Static Gate (Content & Structure)
+
+| Code | Severity | Integrity | What It Detects | How to Fix |
+|------|----------|-----------|-----------------|-----------|
+| `korean_no_keep_all` | major | false | Text containing Hangul uses default word breaking, causing character-level wrapping and orphaned characters on mobile or narrow containers. | Add "word-break: keep-all; overflow-wrap: anywhere" to the body or the slide text container. |
+| `palette_off_token` | minor | false | Color values are hardcoded literals (hex, rgb) instead of design-system tokens or are missing from the design spec palette. | Replace the literal color with a design-spec token (var(--...)) or add the color to the spec palette. |
+| `emoji_in_prose` | major | false | Emoji characters appear in body text, headings, or figure captions. Emoji render at inconsistent sizes and lack semantic meaning. | Remove the emoji; use an inline SVG icon or plain text. |
+| `em_dash_in_prose` | major | false | Em dashes (—) are used in body text for sentence breaks or parenthetical asides. Readability and accessibility suffer without a rewrite. | Rewrite the sentence with a comma, colon, or period instead of an em dash. |
+| `en_dash_in_prose` | minor | false | En dashes (–) are used incorrectly outside of numeric ranges. Only numeric ranges (e.g., "pages 5–10") should use en dashes. | Use a hyphen for compounds; keep the en dash only between numbers. |
+| `heading_too_long` | minor | false | A heading exceeds one visual line: 26 Korean characters (52 display width units) or 12 English words. | Shorten the heading to one line (26 Korean characters or 12 English words). |
+| `heading_generic` | minor | false | A heading uses generic labels (e.g., "Introduction", "Background") without conveying the section's specific claim or finding. | Make the heading carry the section's claim instead of a generic label. |
+| `unsourced_number` | major | false | A numeric value (percentage, count, duration, ratio) appears without a source attribution, measurement tag, or derivation chain. | Tag the number MEASURED / ASSUMED / DERIVED or cite its source in the same paragraph. |
+| `chart_without_figure` | major | false | An image or chart lacks a figure wrapper with a caption. Uncaptioned charts isolate visuals from narrative flow. | Wrap the image or chart in a figure container with a caption. |
+| `chart_svg_no_text` | major | false | An SVG chart or diagram lacks a title, axis labels, units, or value labels. Visuals cannot stand alone without text guidance. | Give the chart a title, axis labels, units, and value labels as SVG text. |
+| `chart_svg_missing_labels` | minor | false | An SVG chart has some labels (e.g., title) but is missing others (e.g., axis ticks or unit). | Add the missing title, axis ticks, or unit label to the chart. |
+| `korean_serif_font` | major | false | A serif or brush Korean font family is applied to Korean text. The design spec mandates gothic (sans) Korean typefaces. | Use a gothic (sans) Korean family; serif and brush families are banned by the design spec. |
+| `section_without_citation` | major | false | A major section or subsection contains no in-text citations or reference marks. Source attribution is missing. | Cite at least one source inside this section or merge it into a cited one. |
+| `missing_closing_section` | blocker | true | The report lacks a closing section explaining the methodology, sources, and gate outcomes. Delivery is incomplete without narrative closure. | Add the closing section that explains how the report was made (method, sources, gates). |
+| `missing_citation_section` | blocker | true | The report has no sources, references, or citation definitions (e.g., [S1], [S2]). Attribution is impossible. | Add a sources or references section, or [S<n>] definition lines. |
+| `broken_asset_reference` | blocker | true | An asset file (image, diagram, spreadsheet) is missing or unreadable. The deliverable cannot be rendered or is incomplete. | Re-render or restore the missing asset file before delivery. |
+| `missing_required_section` | blocker | true | A section explicitly required by the brief (e.g., via `--require-section`) is absent. | Add the section the brief requires (matched by --require-section). |
+| `missing_promised_deliverable` | blocker | true | A deliverable (e.g., a slide deck, a chart, a data file) is promised in the brief but not delivered, not marked blocked_capability, and not skipped with a reason. | Produce the promised deliverable or record it as blocked_capability or skipped with a reason. |
+
+### Layout Gate (Rendering & Presentation)
+
+| Code | Severity | Integrity | What It Detects | How to Fix |
+|------|----------|-----------|-----------------|-----------|
+| `layout_overflow` | major | false | An element exceeds its container width or height, causing horizontal scroll or content spillage in PDF, DOCX, or slide renders. | Constrain the element to its container (max-width: 100%, overflow-wrap: anywhere, or a narrower measure). |
+| `layout_text_clipped` | major | false | Text is clipped or hidden by `overflow: hidden` or a fixed container height. Content is lost or unreadable. | Remove the overflow: hidden clip or give the text room to wrap. |
+| `layout_scroll_container` | minor | false | A table or list is wrapped in a scrollable container for HTML deliverables. Scrolling content prints clipped in PDF or DOCX. | Scrolling content prints clipped; make the content fit or wrap the table in a scroll wrapper only for HTML deliverables. |
+| `layout_image_distorted` | major | false | An image is distorted, stretched, or squeezed (aspect ratio is not preserved). The visual information is misrepresented. | Preserve the image aspect ratio (object-fit: contain inside a fixed container). |
+| `layout_sibling_overlap` | major | false | Two adjacent block elements overlap (via negative margins, absolute positioning, or grid collision). Layout is broken. | Separate the overlapping elements (margins, grid, or a slide split). |
+
+## Exit Codes
+
+Gates emit a manifest-level outcome with one of three statuses:
+
+| Status | Meaning |
+|--------|---------|
+| `pass` | All checks passed; no defects raised. |
+| `fail` | One or more defects raised (blocker, major, or minor severity). Repair is required before delivery. |
+| `not_run` | The gate was not invoked (e.g., no probe file provided for layout, no visual inspection conducted). |
+
+### Layout Gate Probe File Requirement
+
+The `layout` gate only runs when a probe file (a rendering artifact: PDF, PNG, or HTML snapshot) is provided alongside the manifest. If no probe file is available, the manifest records `layout: not_run` and the gate does not emit defects.
+
+## Lineage and Citation Markers
+
+Defect codes and their hints are delivered via the outcome manifest under `residualDefects` (if repair did not exhaust). Each defect entry includes:
+
+- **code**: A string key from the table above (e.g., `"em_dash_in_prose"`)
+- **message**: A human-readable narrative or location hint describing where the defect was found (e.g., "Line 42: em dash found in paragraph 2")
+
+Citations within reports follow one of two lineage modes:
+
+- **inline**: Source marks appear as `[Sn]` or `[Rn]` hyperlinks inline with the cited text.
+- **section**: Sources are listed in a dedicated section with numbered entries ([S1], [S2], etc.).
+
+Both modes are valid; choose based on the report's narrative flow.

package/packages/shared-skills/skills/ulw-research/scripts/cli-support.mjs

@@ -0,0 +1,102 @@
+// cli-support.mjs - argument parsing, typed usage errors, exit-code mapping, and JSON file IO
+// shared by every report-tools subcommand. node: builtins only.
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+
+/** A usage or input error: always exit code 2. */
+export class CliError extends Error {
+	constructor(message) {
+		super(message)
+		this.name = "CliError"
+	}
+}
+
+const IO_CODES = new Set(["ENOENT", "EACCES", "EISDIR", "ENOTDIR", "EPERM"])
+
+/** 0 pass, 1 semantic failure (result.exitCode), 2 usage or IO error. */
+export function exitCodeFor(resultOrError) {
+	if (resultOrError instanceof CliError) return 2
+	if (resultOrError instanceof Error) return IO_CODES.has(resultOrError.code) ? 2 : 1
+	return resultOrError?.exitCode === 1 ? 1 : 0
+}
+
+/**
+ * Parse `--name value`, `--name=value`, boolean flags, and repeatable flags.
+ * @param {readonly string[]} argv
+ * @param {{ repeatable?: string[], booleans?: string[] }} spec
+ */
+export function parseArgs(argv, { repeatable = [], booleans = [] } = {}) {
+	const repeat = new Set(repeatable)
+	const bools = new Set(booleans)
+	const positionals = []
+	const flags = {}
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index]
+		if (!arg.startsWith("--")) {
+			positionals.push(arg)
+			continue
+		}
+		const eq = arg.indexOf("=")
+		const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq)
+		let value
+		if (bools.has(name) && eq === -1) value = true
+		else if (eq !== -1) value = arg.slice(eq + 1)
+		else {
+			value = argv[index + 1]
+			if (value === undefined || value.startsWith("--")) throw new CliError(`--${name} requires a value`)
+			index += 1
+		}
+		if (repeat.has(name)) flags[name] = [...(flags[name] ?? []), value]
+		else flags[name] = value
+	}
+	return {
+		positionals,
+		flags,
+		/** @param {string} name @param {number} [fallback] */
+		int(name, fallback) {
+			if (flags[name] === undefined) {
+				if (fallback === undefined) throw new CliError(`--${name} is required`)
+				return fallback
+			}
+			const parsed = Number(flags[name])
+			if (!Number.isInteger(parsed) || parsed <= 0) throw new CliError(`--${name} requires a positive integer`)
+			return parsed
+		},
+		/** @param {string} name */
+		required(name) {
+			const value = flags[name]
+			if (value === undefined || value === true) throw new CliError(`--${name} is required`)
+			return value
+		},
+	}
+}
+
+/** Read and parse a JSON file; a missing or malformed file is a CliError naming the path. */
+export function readJsonFile(path) {
+	let text
+	try {
+		text = readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+	try {
+		return JSON.parse(text)
+	} catch (error) {
+		throw new CliError(`${path} is not valid JSON: ${error.message}`)
+	}
+}
+
+/** Write JSON through a sibling temp file + rename, so a crash never leaves a half-written file. */
+export function writeJsonAtomic(path, value) {
+	const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.tmp`)
+	writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`)
+	renameSync(temp, path)
+}
+
+/** Print a result: JSON on stdout, one summary line on stderr. */
+export function emit(result, { stdout = process.stdout, stderr = process.stderr } = {}) {
+	if (typeof result.text === "string") stdout.write(result.text.endsWith("\n") ? result.text : `${result.text}\n`)
+	else stdout.write(`${JSON.stringify(result.json ?? result, null, 2)}\n`)
+	if (result.summary) stderr.write(`${result.summary}\n`)
+}

package/packages/shared-skills/skills/ulw-research/scripts/cli-support.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+
+import { CliError, exitCodeFor, parseArgs, readJsonFile, writeJsonAtomic } from "./cli-support.mjs"
+import { isCliEntry } from "./entry-guard.mjs"
+
+function tempDir() {
+	return mkdtempSync(join(tmpdir(), "report-tools-"))
+}
+
+describe("parseArgs", () => {
+	test("#given spaced, equals, repeated, and boolean flags #when parsed #then positionals and flag values are separated", () => {
+		// given
+		const argv = ["a.html", "--design-spec", "spec.md", "--max-defects=5", "--require-section", "^Methods", "--require-section", "^Sources", "--json", "b"]
+		// when
+		const parsed = parseArgs(argv, { repeatable: ["require-section"], booleans: ["json"] })
+		// then
+		expect(parsed.positionals).toEqual(["a.html", "b"])
+		expect(parsed.flags["design-spec"]).toBe("spec.md")
+		expect(parsed.flags["max-defects"]).toBe("5")
+		expect(parsed.flags["require-section"]).toEqual(["^Methods", "^Sources"])
+		expect(parsed.flags.json).toBe(true)
+	})
+
+	test("#given a value flag with no value #when parsed #then a CliError names the flag", () => {
+		expect(() => parseArgs(["--design-spec"], {})).toThrow(CliError)
+		expect(() => parseArgs(["--design-spec"], {})).toThrow("--design-spec")
+	})
+
+	test("#given an integer flag helper #when the value is not a positive integer #then a CliError is thrown", () => {
+		const parsed = parseArgs(["--cap", "0"], {})
+		expect(() => parsed.int("cap")).toThrow(CliError)
+		expect(parseArgs(["--cap", "7"], {}).int("cap")).toBe(7)
+		expect(parseArgs([], {}).int("cap", 400)).toBe(400)
+	})
+})
+
+describe("exitCodeFor", () => {
+	test("#given results and errors #when mapped #then pass is 0, semantic failure is 1, usage and IO errors are 2", () => {
+		expect(exitCodeFor({ exitCode: 0 })).toBe(0)
+		expect(exitCodeFor({ exitCode: 1 })).toBe(1)
+		expect(exitCodeFor(new CliError("usage"))).toBe(2)
+		const io = Object.assign(new Error("ENOENT"), { code: "ENOENT" })
+		expect(exitCodeFor(io)).toBe(2)
+	})
+})
+
+describe("JSON files", () => {
+	test("#given an existing file #when written atomically #then the new content replaces it and no temp file is left", () => {
+		// given
+		const dir = tempDir()
+		const file = join(dir, "state.json")
+		writeFileSync(file, '{"old":true}')
+		// when
+		writeJsonAtomic(file, { fresh: 1 })
+		// then
+		expect(JSON.parse(readFileSync(file, "utf8"))).toEqual({ fresh: 1 })
+		expect(readJsonFile(file)).toEqual({ fresh: 1 })
+		const leftovers = readdirSync(dir).filter((name) => name !== "state.json")
+		expect(leftovers).toEqual([])
+	})
+
+	test("#given a missing or malformed file #when read #then a CliError names the path", () => {
+		const dir = tempDir()
+		expect(() => readJsonFile(join(dir, "missing.json"))).toThrow(CliError)
+		const bad = join(dir, "bad.json")
+		writeFileSync(bad, "{nope")
+		expect(() => readJsonFile(bad)).toThrow("bad.json")
+	})
+})
+
+describe("isCliEntry", () => {
+	test("#given argv[1] pointing at this module #when checked #then it is an entry, and another path is not", () => {
+		const original = process.argv[1]
+		try {
+			const self = join(import.meta.dir, "entry-guard.mjs")
+			process.argv[1] = self
+			expect(isCliEntry(pathToFileURL(self).href)).toBe(true)
+			process.argv[1] = join(import.meta.dir, "contracts.mjs")
+			expect(isCliEntry(pathToFileURL(self).href)).toBe(false)
+		} finally {
+			process.argv[1] = original
+		}
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/contracts.mjs

@@ -0,0 +1,162 @@
+// contracts.mjs - the fixed vocabulary every report-tools module shares.
+//
+// Severities live here and nowhere else: no module exports a way to change them, so a
+// content-integrity defect can never be demoted by a caller. Plain Node ESM, node: builtins
+// only, runnable by `node` and `bun` alike.
+
+export const SCHEMA_VERSION = 1
+
+function deepFreeze(value) {
+	if (value === null || typeof value !== "object") return value
+	for (const key of Object.keys(value)) deepFreeze(value[key])
+	return Object.freeze(value)
+}
+
+/** code -> { severity, integrity, hint }. integrity = blocks delivery even on repair exhaustion. */
+export const DEFECT_CODES = deepFreeze({
+	korean_no_keep_all: { severity: "major", integrity: false, hint: 'Add "word-break: keep-all; overflow-wrap: anywhere" to the body or the slide text container.' },
+	palette_off_token: { severity: "minor", integrity: false, hint: "Replace the literal color with a design-spec token (var(--...)) or add the color to the spec palette." },
+	emoji_in_prose: { severity: "major", integrity: false, hint: "Remove the emoji; use an inline SVG icon or plain text." },
+	em_dash_in_prose: { severity: "major", integrity: false, hint: "Rewrite the sentence with a comma, colon, or period instead of an em dash." },
+	en_dash_in_prose: { severity: "minor", integrity: false, hint: "Use a hyphen for compounds; keep the en dash only between numbers." },
+	heading_too_long: { severity: "minor", integrity: false, hint: "Shorten the heading to one line (26 Korean characters or 12 English words)." },
+	heading_generic: { severity: "minor", integrity: false, hint: "Make the heading carry the section's claim instead of a generic label." },
+	unsourced_number: { severity: "major", integrity: false, hint: "Tag the number MEASURED / ASSUMED / DERIVED or cite its source in the same paragraph." },
+	chart_without_figure: { severity: "major", integrity: false, hint: "Wrap the image or chart in a figure container with a caption." },
+	chart_svg_no_text: { severity: "major", integrity: false, hint: "Give the chart a title, axis labels, units, and value labels as SVG text." },
+	chart_svg_missing_labels: { severity: "minor", integrity: false, hint: "Add the missing title, axis ticks, or unit label to the chart." },
+	korean_serif_font: { severity: "major", integrity: false, hint: "Use a gothic (sans) Korean family; serif and brush families are banned by the design spec." },
+	section_without_citation: { severity: "major", integrity: false, hint: "Cite at least one source inside this section or merge it into a cited one." },
+	missing_closing_section: { severity: "blocker", integrity: true, hint: "Add the closing section that explains how the report was made (method, sources, gates)." },
+	missing_citation_section: { severity: "blocker", integrity: true, hint: "Add a sources or references section, or [S<n>] definition lines." },
+	broken_asset_reference: { severity: "blocker", integrity: true, hint: "Re-render or restore the missing asset file before delivery." },
+	missing_required_section: { severity: "blocker", integrity: true, hint: "Add the section the brief requires (matched by --require-section)." },
+	missing_promised_deliverable: { severity: "blocker", integrity: true, hint: "Produce the promised deliverable or record it as blocked_capability or skipped with a reason." },
+	layout_overflow: { severity: "major", integrity: false, hint: "Constrain the element to its container (max-width: 100%, overflow-wrap: anywhere, or a narrower measure)." },
+	layout_text_clipped: { severity: "major", integrity: false, hint: "Remove the overflow: hidden clip or give the text room to wrap." },
+	layout_scroll_container: { severity: "minor", integrity: false, hint: "Scrolling content prints clipped; make the content fit or wrap the table in a scroll wrapper only for HTML deliverables." },
+	layout_image_distorted: { severity: "major", integrity: false, hint: "Preserve the image aspect ratio (object-fit: contain inside a fixed container)." },
+	layout_sibling_overlap: { severity: "major", integrity: false, hint: "Separate the overlapping elements (margins, grid, or a slide split)." },
+})
+
+const LAYOUT_PREFIX = "layout_"
+/** Codes checkStatic can raise (G1-G15). */
+export const STATIC_CODES = Object.freeze(
+	Object.keys(DEFECT_CODES).filter((code) => !code.startsWith(LAYOUT_PREFIX) && code !== "missing_promised_deliverable"),
+)
+/** Codes checkLayout can raise (L1-L5). */
+export const LAYOUT_CODES = Object.freeze(Object.keys(DEFECT_CODES).filter((code) => code.startsWith(LAYOUT_PREFIX)))
+/** Codes only the outcome manifest verifier raises. */
+export const MANIFEST_CODES = Object.freeze(["missing_promised_deliverable"])
+
+export const INTEGRITY_CODES = Object.freeze(
+	new Set(Object.entries(DEFECT_CODES).filter(([, entry]) => entry.integrity).map(([code]) => code)),
+)
+
+export const LANES = Object.freeze(["template-strict", "template-vibe", "no-format", "edit-existing"])
+export const STATES = Object.freeze(["none", "partial", "complete"])
+export const DELIVERABLE_FORMATS = Object.freeze(["pdf", "docx", "html", "md", "latex", "slides", "post"])
+export const DELIVERABLE_STATUSES = Object.freeze(["pending", "delivered", "blocked_capability", "skipped", "failed"])
+export const GATE_NAMES = Object.freeze(["static", "layout", "visual", "proofread"])
+export const GATE_STATUSES = Object.freeze(["pass", "fail", "not_run"])
+export const LINEAGE_MODES = Object.freeze(["inline", "section"])
+export const ANSWERED_BY = Object.freeze(["user", "default", "request"])
+export const REPAIR_DEFAULTS = Object.freeze({ maxAttempts: 3, plateauLimit: 2, wallClockMs: 15 * 60 * 1000 })
+export const DESIGN_SPEC_SECTIONS = Object.freeze([
+	"Extracted from",
+	"Tokens",
+	"Typography",
+	"Layout",
+	"Structure",
+	"Figures",
+	"Citations",
+	"Open questions",
+])
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+
+function isObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function check(errors, condition, message) {
+	if (!condition) errors.push(message)
+}
+
+function validateDeliverable(row, index, errors) {
+	const at = `deliverables[${index}]`
+	if (!isObject(row)) return errors.push(`${at} must be an object`)
+	check(errors, DELIVERABLE_FORMATS.includes(row.format), `${at}.format must be one of ${DELIVERABLE_FORMATS.join(", ")}`)
+	check(errors, DELIVERABLE_STATUSES.includes(row.status), `${at}.status must be one of ${DELIVERABLE_STATUSES.join(", ")}`)
+	check(errors, typeof row.promised === "boolean", `${at}.promised must be a boolean`)
+	check(errors, typeof row.updatedAt === "string" && ISO_DATE.test(row.updatedAt), `${at}.updatedAt must be an ISO timestamp`)
+	for (const key of ["path", "reason"]) {
+		if (row[key] !== undefined) check(errors, typeof row[key] === "string", `${at}.${key} must be a string`)
+	}
+	for (const key of ["bytes", "pages"]) {
+		if (row[key] !== undefined) check(errors, Number.isInteger(row[key]) && row[key] >= 0, `${at}.${key} must be a non-negative integer`)
+	}
+}
+
+function validateDefect(defect, at, errors) {
+	if (!isObject(defect)) return errors.push(`${at} must be an object`)
+	check(errors, Object.hasOwn(DEFECT_CODES, defect.code), `${at}.code is not a known defect code`)
+	check(errors, typeof defect.message === "string", `${at}.message must be a string`)
+}
+
+/** @returns {{ ok: boolean, errors: string[] }} */
+export function validateOutcomeManifest(manifest) {
+	const errors = []
+	if (!isObject(manifest)) return { ok: false, errors: ["manifest must be an object (schemaVersion missing)"] }
+	check(errors, manifest.schemaVersion === SCHEMA_VERSION, `schemaVersion must be ${SCHEMA_VERSION}`)
+	check(errors, typeof manifest.sessionDir === "string" && manifest.sessionDir.length > 0, "sessionDir must be a non-empty string")
+	check(errors, typeof manifest.startedAt === "string" && ISO_DATE.test(manifest.startedAt), "startedAt must be an ISO timestamp")
+	check(errors, manifest.finishedAt === null || (typeof manifest.finishedAt === "string" && ISO_DATE.test(manifest.finishedAt)), "finishedAt must be null or an ISO timestamp")
+	check(errors, manifest.elapsedMinutes === null || (Number.isFinite(manifest.elapsedMinutes) && manifest.elapsedMinutes >= 0), "elapsedMinutes must be null or a non-negative number")
+	check(errors, manifest.lane === null || LANES.includes(manifest.lane), `lane must be null or one of ${LANES.join(", ")}`)
+	check(errors, manifest.interview === null || isObject(manifest.interview), "interview must be null or an object")
+	if (Array.isArray(manifest.deliverables)) manifest.deliverables.forEach((row, index) => validateDeliverable(row, index, errors))
+	else errors.push("deliverables must be an array")
+	if (Array.isArray(manifest.renders)) {
+		manifest.renders.forEach((render, index) => {
+			check(errors, isObject(render) && typeof render.path === "string" && Number.isInteger(render.page) && render.page >= 1, `renders[${index}] must be { path: string, page: integer >= 1 }`)
+		})
+	} else errors.push("renders must be an array")
+	if (isObject(manifest.gates)) {
+		for (const gate of GATE_NAMES) check(errors, GATE_STATUSES.includes(manifest.gates[gate]), `gates.${gate} must be one of ${GATE_STATUSES.join(", ")}`)
+	} else errors.push("gates must be an object")
+	if (Array.isArray(manifest.residualDefects)) manifest.residualDefects.forEach((defect, index) => validateDefect(defect, `residualDefects[${index}]`, errors))
+	else errors.push("residualDefects must be an array")
+	check(errors, manifest.repair === null || isObject(manifest.repair), "repair must be null or an object")
+	check(errors, manifest.sources === null || isObject(manifest.sources), "sources must be null or an object")
+	return { ok: errors.length === 0, errors }
+}
+
+function isMeasure(value) {
+	return Array.isArray(value) && value.length === 3 && value.every((n) => Number.isInteger(n) && n >= 0)
+}
+
+/** @returns {{ ok: boolean, errors: string[] }} */
+export function validateRepairState(state) {
+	const errors = []
+	if (!isObject(state)) return { ok: false, errors: ["repair state must be an object (schemaVersion missing)"] }
+	check(errors, state.schemaVersion === SCHEMA_VERSION, `schemaVersion must be ${SCHEMA_VERSION}`)
+	check(errors, typeof state.startedAt === "string" && ISO_DATE.test(state.startedAt), "startedAt must be an ISO timestamp")
+	if (isObject(state.budget)) {
+		for (const key of ["maxAttempts", "plateauLimit", "wallClockMs"]) {
+			check(errors, Number.isInteger(state.budget[key]) && state.budget[key] > 0, `budget.${key} must be a positive integer`)
+		}
+	} else errors.push("budget must be an object")
+	if (Array.isArray(state.attempts)) {
+		state.attempts.forEach((attempt, index) => {
+			const at = `attempts[${index}]`
+			if (!isObject(attempt)) return errors.push(`${at} must be an object`)
+			check(errors, typeof attempt.at === "string" && ISO_DATE.test(attempt.at), `${at}.at must be an ISO timestamp`)
+			check(errors, isMeasure(attempt.measure), `${at}.measure must be [blocker, major, minor] counts`)
+			check(errors, typeof attempt.signature === "string", `${at}.signature must be a string`)
+		})
+	} else errors.push("attempts must be an array")
+	check(errors, Number.isInteger(state.consecutiveNonProgress) && state.consecutiveNonProgress >= 0, "consecutiveNonProgress must be a non-negative integer")
+	check(errors, Array.isArray(state.seenSignatures) && state.seenSignatures.every((s) => typeof s === "string"), "seenSignatures must be an array of strings")
+	return { ok: errors.length === 0, errors }
+}