Skip to content

code-yeongyu/oh-my-openagent / packages/shared-skills/skills/ulw-research

ulw-research

Unverified

Runs maximum-saturation research with a cooperating team, claim-graph gating, and a cited, QA'd deliverable. Use when the user explicitly asks for research or a deep investigation, including any 'ulw' research wording.

FileKindSize
AGENTS.mdmarkdown9.2 KB
ATTRIBUTION.mdmarkdown2.4 KB
SKILL.mdskill md42.2 KB
references/deliverable-phase.mdmarkdown49.1 KB
references/fact-ledger-grammar.mdmarkdown6.8 KB
references/fact-ledger.mdmarkdown24.4 KB
references/fidelity-claim-kinds.mdmarkdown5.2 KB
references/markdown-blocks.mdmarkdown721 B
references/report-gates.mdmarkdown32.0 KB
references/report-visualization.mdmarkdown15.4 KB
references/research-collection.mdmarkdown26.8 KB
references/research-delivery.mdmarkdown14.3 KB
references/unit-rules.mdmarkdown16.3 KB
scripts/claim-kinds.mjsscript11.2 KB
scripts/claim-kinds.test.tsscript13.5 KB
scripts/claim-prefix.test.tsscript4.9 KB
scripts/claims-index.mjsscript5.3 KB
scripts/claims-index.test.tsscript5.7 KB
scripts/cli-support.mjsscript4.1 KB
scripts/cli-support.test.tsscript4.3 KB
scripts/contracts-validation.test.tsscript3.3 KB
scripts/contracts.mjsscript26.1 KB
scripts/contracts.test.tsscript7.9 KB
scripts/conversion-altered.test.tsscript11.0 KB
scripts/conversion-originals.test.tsscript22.7 KB
scripts/conversion-probe-classes.test.tsscript45.2 KB
scripts/conversion-probe.mjsscript13.5 KB
scripts/conversion-probe.test.tsscript11.6 KB
scripts/copy-returns-fidelity-policy.test.tsscript10.4 KB
scripts/copy-returns-polish.test.tsscript12.1 KB
scripts/copy-returns.test.tsscript10.6 KB
scripts/css-hiding.mjsscript9.1 KB
scripts/css-lite.mjsscript7.6 KB
scripts/css-lite.test.tsscript6.4 KB
scripts/delivery-barrier-meaning.test.tsscript12.3 KB
scripts/delivery-barrier.test.tsscript11.4 KB
scripts/design-spec.mjsscript7.2 KB
scripts/design-spec.test.tsscript6.7 KB
scripts/entities.mjsscript2.5 KB
scripts/entry-guard.mjsscript794 B
scripts/fact-commands-fill.mjsscript6.6 KB
scripts/fact-commands-meaning.mjsscript12.6 KB
scripts/fact-commands-polish.mjsscript10.3 KB
scripts/fact-commands-verify.mjsscript12.6 KB
scripts/fact-commands.mjsscript13.8 KB
scripts/fact-derive-2.test.tsscript7.2 KB
scripts/fact-derive.mjsscript4.9 KB
scripts/fact-derive.test.tsscript10.8 KB
scripts/fact-expr.mjsscript4.5 KB
scripts/fact-fill.mjsscript11.7 KB
scripts/fact-fill.test.tsscript10.7 KB
scripts/fact-ledger-grammar.test.tsscript11.8 KB
scripts/fact-ledger-kinds.mjsscript16.5 KB
scripts/fact-ledger-kinds.test.tsscript9.3 KB
scripts/fact-ledger-legacy.test.tsscript8.9 KB
scripts/fact-ledger-schema.mjsscript11.9 KB
scripts/fact-ledger-schema.test.tsscript1.5 KB
scripts/fact-ledger.mjsscript5.5 KB
scripts/fact-ledger.test.tsscript9.7 KB
scripts/fact-locate.mjsscript12.1 KB
scripts/fact-locate.test.tsscript7.2 KB
scripts/fact-pairs.mjsscript8.3 KB
scripts/fact-pairs.test.tsscript6.6 KB
scripts/fact-recompute.mjsscript4.8 KB
scripts/fact-unit-dimensions-2.test.tsscript8.4 KB
scripts/fact-unit-dimensions.test.tsscript11.9 KB
scripts/fact-unit-rules.test.tsscript8.9 KB
scripts/fidelity-binding.mjsscript6.7 KB
scripts/fidelity-binding.test.tsscript4.0 KB
scripts/fidelity-brief.mjsscript6.4 KB
scripts/fidelity-brief.test.tsscript7.8 KB
scripts/fidelity-claims.mjsscript5.1 KB
scripts/fidelity-csv.mjsscript1.1 KB
scripts/fidelity-lexicon.mjsscript8.1 KB
scripts/fidelity-lexicon.test.tsscript6.0 KB
scripts/fidelity-originals.mjsscript9.9 KB
scripts/fidelity-policy.mjsscript10.1 KB
scripts/fidelity-records.mjsscript13.4 KB
scripts/fidelity-snapshot-readability.mjsscript2.2 KB
scripts/fidelity-sources.mjsscript4.3 KB
scripts/fidelity-state.mjsscript2.1 KB
scripts/fidelity-state.test.tsscript1.7 KB
scripts/fidelity-trace.mjsscript6.1 KB
scripts/fidelity-trace.test.tsscript3.3 KB
scripts/fidelity-value-unit.mjsscript13.3 KB
scripts/fidelity-values.mjsscript16.1 KB
scripts/fidelity-values.test.tsscript15.8 KB
scripts/format-extract-css.mjsscript5.1 KB
scripts/format-extract.mjsscript10.3 KB
scripts/format-extract.test.tsscript11.2 KB
scripts/gates-context.test.tsscript2.6 KB
scripts/gates-fidelity.mjsscript6.3 KB
scripts/gates-fidelity.test.tsscript3.3 KB
scripts/gates-figures.mjsscript9.9 KB
scripts/gates-layout.mjsscript6.6 KB
scripts/gates-layout.test.tsscript12.4 KB
scripts/gates-static-headings.test.tsscript961 B
scripts/gates-static.mjsscript8.1 KB
scripts/gates-static.test.tsscript14.9 KB
scripts/gates-structure.mjsscript4.7 KB
scripts/gates-text.mjsscript7.2 KB
scripts/glossary-vocabulary.test.tsscript1.7 KB
scripts/html-foreign-object.mjsscript2.8 KB
scripts/html-lite.mjsscript9.7 KB
scripts/html-lite.test.tsscript7.9 KB
scripts/html-markup.mjsscript7.0 KB
scripts/html-text-map.mjsscript4.8 KB
scripts/html-text-map.test.tsscript15.2 KB
scripts/layout-probe.mjsscript4.6 KB
scripts/layout-probe.test.tsscript4.2 KB
scripts/lexicon.mjsscript2.6 KB
scripts/lexicon.test.tsscript3.2 KB
scripts/markdown-closers.mjsscript4.9 KB
scripts/md-lite-boundaries.test.tsscript2.2 KB
scripts/md-lite.mjsscript7.8 KB
scripts/md-lite.test.tsscript10.3 KB
scripts/meaning-check.mjsscript9.7 KB
scripts/meaning-check.test.tsscript12.0 KB
scripts/number-grammar.mjsscript2.1 KB
scripts/number-grammar.test.tsscript1.8 KB
scripts/numerals.mjsscript12.0 KB
scripts/numerals.test.tsscript6.1 KB
scripts/outcome-start.mjsscript3.8 KB
scripts/outcome-start.test.tsscript5.0 KB
scripts/outcome.mjsscript10.5 KB
scripts/outcome.test.tsscript12.8 KB
scripts/page-source-locator.test.tsscript11.7 KB
scripts/particles-ko.mjsscript4.8 KB
scripts/particles-ko.test.tsscript4.3 KB
scripts/placeholder.mjsscript9.3 KB
scripts/placeholder.test.tsscript3.8 KB
scripts/polish-apply.mjsscript6.8 KB
scripts/polish-apply.test.tsscript19.7 KB
scripts/polish-diff.mjsscript1.7 KB
scripts/polish-diff.test.tsscript10.1 KB
scripts/polish-markup.test.tsscript14.0 KB
scripts/polish-partial.test.tsscript2.5 KB
scripts/polish-project.mjsscript5.8 KB
scripts/polish-rules.mjsscript9.8 KB
scripts/rational.mjsscript5.2 KB
scripts/rational.test.tsscript1.9 KB
scripts/raw-decode.mjsscript4.5 KB
scripts/raw-locator.mjsscript2.4 KB
scripts/raw-snapshot.test.tsscript7.3 KB
scripts/references-fences.test.tsscript1.2 KB
scripts/repair-tracker.mjsscript7.5 KB
scripts/repair-tracker.test.tsscript10.8 KB
scripts/report-tools-2.test.tsscript16.1 KB
scripts/report-tools-3.test.tsscript9.3 KB
scripts/report-tools-4.test.tsscript10.1 KB
scripts/report-tools-5.test.tsscript14.6 KB
scripts/report-tools-commands.mjsscript12.9 KB
scripts/report-tools.mjsscript2.6 KB
scripts/report-tools.test.tsscript12.1 KB
scripts/sentence-split.mjsscript3.0 KB
scripts/sentence-split.test.tsscript4.5 KB
scripts/snapshot-readability.test.tsscript7.0 KB
scripts/source-commands.mjsscript12.4 KB
scripts/source-integrity.test.tsscript18.1 KB
scripts/source-refresh.mjsscript5.2 KB
scripts/source-snapshot.mjsscript9.9 KB
scripts/source-snapshot.test.tsscript6.3 KB
scripts/source-view.mjsscript5.0 KB
scripts/sources-citation.mjsscript12.1 KB
scripts/sources-citation.test.tsscript14.8 KB
scripts/tests/contracts-support.tsscript3.5 KB
scripts/tests/delivery-barrier-session.tsscript3.3 KB
scripts/tests/derive-clock.tsscript341 B
scripts/tests/fact-derive-support.tsscript1.9 KB
scripts/tests/fact-unit-dimensions-support.tsscript1.5 KB
scripts/tests/fact-unit-rules-support.tsscript16.8 KB
scripts/tests/fidelity-values-support.tsscript1.6 KB
scripts/tests/fixtures/assets/figure-1.svgother141 B
scripts/tests/fixtures/bad-report.htmlother2.1 KB
scripts/tests/fixtures/boxes.jsonconfig3.2 KB
scripts/tests/fixtures/conversion-probe.htmlother485 B
scripts/tests/fixtures/design-spec.mdmarkdown458 B
scripts/tests/fixtures/fidelity-brief-locked.mdmarkdown571 B
scripts/tests/fixtures/fidelity-brief-pending.mdmarkdown574 B
scripts/tests/fixtures/fidelity/assets/share.csvother40 B
scripts/tests/fixtures/fidelity/claim-graph.mdmarkdown449 B
scripts/tests/fixtures/fidelity/gen-legacy-dev.mjsscript5.0 KB
scripts/tests/fixtures/fidelity/ledger-basic.jsonconfig5.1 KB
scripts/tests/fixtures/fidelity/ledger-legacy-dev.jsonconfig18.3 KB
scripts/tests/fixtures/fidelity/ledger-verify.jsonconfig9.1 KB
scripts/tests/fixtures/fidelity/polish-edits.jsonconfig303 B
scripts/tests/fixtures/fidelity/report-bad.htmlother821 B
scripts/tests/fixtures/fidelity/report-good.htmlother2.4 KB
scripts/tests/fixtures/fidelity/sources/S4.htmlother680 B
scripts/tests/fixtures/fidelity/sources/S4/acronyms.jsonconfig36 B
scripts/tests/fixtures/fidelity/sources/S4/meta.jsonconfig256 B
scripts/tests/fixtures/fidelity/sources/S4/sentences.jsonlother623 B
scripts/tests/fixtures/fidelity/sources/S4/text.txtmarkdown300 B
scripts/tests/fixtures/fidelity/sources/S5/acronyms.jsonconfig3 B
scripts/tests/fixtures/fidelity/sources/S5/meta.jsonconfig235 B
scripts/tests/fixtures/fidelity/sources/S5/sentences.jsonlother53 B
scripts/tests/fixtures/fidelity/sources/S5/text.txtmarkdown10 B
scripts/tests/fixtures/fidelity/sources/S9.txtmarkdown128 B
scripts/tests/fixtures/good-report.htmlother2.7 KB
scripts/tests/fixtures/reference-report.htmlother2.5 KB

scripts/fact-commands-polish.mjs

View on GitHub
// fact-commands-polish.mjs - `fact polish-apply` and `fact polish-diff`, the script half of the
// proofread gate, plus the --changed-since filter of `fact pairs`.
//
// The writing lane returns polish-edits.json ([{before, after, reason}]) and never edits the
// report. polish-apply applies each edit through polish-apply.mjs and writes the result; a
// rejected (major) or unlocated (minor) edit leaves its region unchanged and is listed with its
// index and reason so the orchestrator can re-send it; every rejection reason is printed verbatim, one
// line per rejected edit (index and the first 60 characters of its before), in the summary and in
// data.rejected_reasons. It exits 0 whenever it wrote the output; json.applied is false when
// any edit was rejected or unlocated, independently of data.applied's accepted-edit count.
// polish-apply never rewrites a fill map: it checks that the edition's map (fillMapOf) records the
// input's bytes, refusing otherwise, and writes `<out>.polished.fill-map.json` beside the output
// (artifact = the polished file, its hash, and polishedFrom = the fill map's path and sha256).
// polish-diff is the whole-document backstop (polish-diff.mjs) between the pre-polish artifact
// and any later copy; it exits 1 on a blocker. pairsChangedSince always reads the pre-polish fill
// map (following a polished map's polishedFrom) and keeps only the pairs whose sentence text
// (normalized) is not in the artifact it names, so the meaning readers re-check exactly what
// changed; when that artifact no longer hashes to the map (polished in place, or edited) nothing
// can be ruled out and every pair is kept. No model, no network.

import { existsSync, readFileSync } from "node:fs"
import { join, resolve } from "node:path"

import { CliError, parseArgs, readJsonFile, sha256Of, writeJsonAtomic, writeTextAtomic } from "./cli-support.mjs"
import { countDefects, DEFECT_CODES } from "./contracts.mjs"
import { editionFormatOf, fillMapOf, ledgerFrom, markdownAsHtml, sessionOf } from "./fact-commands-verify.mjs"
import { extractPairs } from "./fact-pairs.mjs"
import { lockedBrief } from "./fidelity-policy.mjs"
import { applyEdits, POLISH_EDIT_FIELDS, validatePolishEdits } from "./polish-apply.mjs"
import { diffPolish } from "./polish-diff.mjs"
import { normalizeText } from "./text-normalize.mjs"

export { ledgerFrom, POLISH_EDIT_FIELDS, validatePolishEdits }

export const POLISH_RECORD = "polish-defects.json"

/**
 * The polish-diff exit policy: only a registry blocker fails the command; majors are reported.
 * Fail-closed like the delivery barrier: a code the registry does not know refuses outright,
 * because a caller-claimed severity may not demote it.
 */
export const polishDiffFails = (defects) =>
  defects.some((defect) => {
    if (!Object.hasOwn(DEFECT_CODES, defect?.code)) throw new CliError(`unknown defect code ${defect?.code}`)
    return DEFECT_CODES[defect.code].severity === "blocker"
  })

function readText(path) {
  try {
    return readFileSync(path, "utf8")
  } catch (error) {
    throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
  }
}

const withSeverity = (entry) => ({
  ...entry,
  severity: DEFECT_CODES[entry.code].severity,
  hint: DEFECT_CODES[entry.code].hint,
})

/** The first 60 characters of an edit's before, on one line. */
const beforePreview = (before) => (typeof before === "string" ? before : "").replace(/\s+/gu, " ").slice(0, 60)

/** One line per rejected edit: its index, the start of its before, and its reason verbatim. */
const rejectionLine = (entry, edit) =>
  `  rejected edit ${entry.index} ("${beforePreview(edit?.before)}"): ${entry.reason}`

function runPolishApply(args) {
  const [report] = args.positionals
  const { flags } = args
  if (!report || flags.edits === undefined || flags.out === undefined)
    throw new CliError(
      "usage: fact polish-apply <report.html> --edits polish-edits.json --out <report.polished.html> [--fill-map F] [--ledger F] [--brief brief.md] [--session-dir D]",
    )
  if (editionFormatOf(report, flags.format) === "md")
    throw new CliError(
      "fact polish-apply takes the filled HTML edition; polish a Markdown edition through its HTML source",
    )
  const { refusal } = lockedBrief("fact polish-apply", flags)
  if (refusal) return refusal
  const html = readText(report)
  const editsText = readText(flags.edits)
  const edits = readJsonFile(flags.edits)
  try {
    validatePolishEdits(edits)
  } catch (error) {
    throw new CliError(
      `${flags.edits} must be an array of {${Object.keys(POLISH_EDIT_FIELDS).join(", ")}} objects: ${error.message}`,
    )
  }
  const result = applyEdits(html, edits, ledgerFrom(flags))
  const mapPath = fillMapOf(report, html, flags["fill-map"])
  const map = mapPath === null ? null : readJsonFile(mapPath)
  if (map !== null && map.artifact_sha256 !== sha256Of(html))
    throw new CliError(
      `${mapPath} does not record the bytes of ${report} (artifact_sha256 differs); refusing to carry its brief binding to the polished edition`,
    )
  const polishedFrom = map?.polishedFrom ?? (map && { map: resolve(mapPath), sha256: sha256Of(readText(mapPath)) })
  writeTextAtomic(flags.out, result.out)
  if (map)
    writeJsonAtomic(`${resolve(flags.out)}.polished.fill-map.json`, {
      ...map,
      artifact: resolve(flags.out),
      artifact_sha256: sha256Of(result.out),
      polishedFrom,
    })
  const defects = [...result.rejected, ...result.unlocated].sort((a, b) => a.index - b.index).map(withSeverity)
  const counts = {
    applied: result.applied.length,
    rejected: result.rejected.length,
    unlocated: result.unlocated.length,
  }
  const data = {
    out: resolve(flags.out),
    ...counts,
    applied_indexes: result.applied,
    input_sha256: sha256Of(html),
    edits_sha256: sha256Of(editsText),
    out_sha256: sha256Of(result.out),
  }
  const rejected_reasons = result.rejected.map((entry) => rejectionLine(entry, edits[entry.index]))
  const summary = [
    `fact polish-apply: ${counts.applied} applied, ${counts.rejected} rejected, ${counts.unlocated} unlocated of ${edits.length} edit(s)`,
    ...rejected_reasons,
  ].join("\n")
  return {
    json: {
      command: "fact polish-apply",
      status: "pass",
      exitCode: 0,
      applied: counts.rejected === 0 && counts.unlocated === 0,
      defects,
      data: { ...data, rejected_reasons },
    },
    summary,
    exitCode: 0,
  }
}

function runPolishDiff(args) {
  const { flags } = args
  if (flags.before === undefined || flags.after === undefined)
    throw new CliError(
      "usage: fact polish-diff --before <pre-polish.html> --after <polished.html> [--ledger F] [--out polish-defects.json] [--brief brief.md] [--session-dir D]",
    )
  const { refusal } = lockedBrief("fact polish-diff", flags)
  if (refusal) return refusal
  const after = readText(flags.after)
  const defects = diffPolish(readText(flags.before), after, ledgerFrom(flags)).map((defect) => ({
    ...defect,
    hint: DEFECT_CODES[defect.code]?.hint ?? null,
  }))
  const counts = countDefects(defects)
  const status = polishDiffFails(defects) ? "fail" : "pass"
  const exitCode = status === "fail" ? 1 : 0
  const record = {
    command: "fact polish-diff",
    status,
    exitCode,
    before: resolve(flags.before),
    artifact: resolve(flags.after),
    artifact_sha256: sha256Of(after),
    defects,
    counts,
  }
  const session = sessionOf(flags)
  const out = flags.out ?? (session === null ? null : join(session, POLISH_RECORD))
  if (out !== null) writeJsonAtomic(resolve(out), record)
  const summary = `fact polish-diff: ${status.toUpperCase()} - ${counts.blocker} blocker, ${counts.major} major, ${counts.minor} minor`
  return { json: { ...record, out: out === null ? null : resolve(out) }, summary, exitCode }
}

const pairKey = (pair) =>
  [pair.kind, pair.sentence_key, pair.claim_id ?? "", normalizeText(pair.sentence)].join("\u0000")

/** The pre-polish fill map behind --changed-since: a polished map leads to it through polishedFrom, whose sha256 it must still match. */
function prePolishMap(mapPath) {
  const given = readJsonFile(mapPath)
  if (given.polishedFrom === undefined) return { path: resolve(mapPath), map: given }
  const { map: path, sha256 } = given.polishedFrom
  if (typeof path !== "string" || sha256Of(readText(path)) !== sha256)
    throw new CliError(
      `${path} changed after polish wrote ${mapPath}; --changed-since needs the pre-polish fill map it names`,
    )
  return { path, map: readJsonFile(path) }
}

/**
 * The pairs whose sentence text changed since the pre-polish artifact the fill map names: a pair is
 * kept unless the same (kind, sentence key, normalized sentence) occurs in that artifact. Only bytes
 * that still hash to the map's `artifact_sha256` narrow the set; otherwise (the report was polished
 * in place, or edited) every pair is kept, so nothing changed escapes the meaning re-check.
 * @param {object[]} pairs extractPairs output on the polished edition
 * @param {string} mapPath fact fill's `<out>.fill-map.json`, or polish-apply's `<out>.polished.fill-map.json`
 * @returns {{ pairs: object[], fill_map: string, narrowed: boolean }}
 */
export function pairsChangedSince(pairs, mapPath, ledger, claims) {
  const { path, map } = prePolishMap(mapPath)
  if (typeof map.artifact !== "string") throw new CliError(`${path} names no pre-polish artifact`)
  if (typeof map.artifact_sha256 !== "string")
    throw new CliError(`${path} fill map has no artifact_sha256; --changed-since needs the pre-polish hash`)
  const text = existsSync(map.artifact) ? readText(map.artifact) : null
  if (text === null || sha256Of(text) !== map.artifact_sha256) return { pairs, fill_map: path, narrowed: false }
  const html = map.format === "md" ? markdownAsHtml(text, map.entries, ledger).html : text
  const before = new Map()
  for (const pair of extractPairs(html, ledger, claims)) before.set(pairKey(pair), (before.get(pairKey(pair)) ?? 0) + 1)
  const kept = pairs.filter((pair) => {
    const left = before.get(pairKey(pair)) ?? 0
    if (left === 0) return true
    before.set(pairKey(pair), left - 1)
    return false
  })
  return { pairs: kept, fill_map: path, narrowed: true }
}

/** @param {string[]} argv the arguments after `fact polish-apply` or `fact polish-diff` */
export function runFactPolish(sub, argv) {
  const args = parseArgs(argv)
  return sub === "polish-apply" ? runPolishApply(args) : runPolishDiff(args)
}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall