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/fidelity-policy.mjs

View on GitHub
// fidelity-policy.mjs - what the locked `## Fidelity` block of brief.md means to the CLI stages.
//
// lockedBrief is the gate the six reader-facing stages (fact fill, verify, pairs, meaning-check,
// polish-apply, polish-diff) run before reading or writing anything: an unlocked brief returns
// one fidelity_interview_incomplete defect (exit 1), a malformed block is a usage error (exit 2).
// fillPolicy reads the fields fact fill consumes (a value off its table is a usage error, exit 2),
// and policyErrors refuses a placeholder whose row the brief forbids: derived_not_allowed
// (`derived numbers: none` against a derived, converted, or assumed row) and source_outside_floor
// (the source floor is evaluated live against each source's meta.json at every fill and verify;
// under any floor but `standard` a row resting on no source is refused too; a row's outside_floor
// is only the cached result). briefHashOf binds the locked block into the fill map, and
// briefBindingErrors refuses an edition whose map was filled under another brief (brief_changed).
// Collection stages never call this module. node: builtins and sibling imports only.

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

import { CliError, sha256Of } from "./cli-support.mjs"
import { DEFECT_CODES } from "./contracts.mjs"
import { KIND_RULES } from "./fact-ledger-kinds.mjs"
import { FIDELITY_FIELDS, meaningCheckEnabled, requireLockedBrief } from "./fidelity-brief.mjs"

export { meaningCheckEnabled }

/**
 * Ledger kinds a brief with `derived numbers: none` refuses. A policy list, not the ledger's
 * derivation set: it also names assumed. Every name must be a KIND_RULES kind (checked at load).
 */
const DERIVED_KINDS = Object.freeze(["derived", "converted", "assumed"])
for (const kind of DERIVED_KINDS) {
  if (!Object.hasOwn(KIND_RULES, kind)) throw new Error(`fidelity-policy: ${kind} is not a KIND_RULES kind`)
}

/** Fields whose only legal values are a closed table: value (any case) -> its reading. */
const VALUE_TABLES = Object.freeze({
  "derived numbers": Object.freeze({ allowed: false, none: true }),
  fallback: Object.freeze({ "block-quote": "quote", omit: "omit" }),
})

/** The reading of a table value; any other text is a usage error naming the field and the value. */
function tableValue(field, value) {
  const table = VALUE_TABLES[field]
  const key = value.trim().toLowerCase()
  if (Object.hasOwn(table, key)) return table[key]
  throw new CliError(`${field} "${value}" is not ${Object.keys(table).join(", ")}`)
}

/** How each field value the fill stages consume is read; the single owner of those readings. */
export const FIDELITY_VALUE_RULES = Object.freeze({
  tables: VALUE_TABLES,
  derivedKinds: DERIVED_KINDS,
  derivedRefused: (kind) => DERIVED_KINDS.includes(kind),
  derivedNone: (value) => tableValue("derived numbers", value),
  fallback: (value) => tableValue("fallback", value),
  translations: (value) => /with translation beside/iu.test(value),
  meaningCheck: (value) => meaningCheckEnabled({ fields: { "meaning check": value } }),
})

/** The `source floor` forms: `pattern` reads one, `listed` forms carry a comma list. */
export const SOURCE_FLOOR_RULES = Object.freeze([
  Object.freeze({ kind: "standard", form: "standard", pattern: /^standard$/iu, listed: false }),
  Object.freeze({ kind: "primary", form: "primary only", pattern: /^primary only$/iu, listed: false }),
  Object.freeze({ kind: "pointed", form: "pointed only: <list>", pattern: /^pointed only:\s*(.+)$/iu, listed: true }),
  Object.freeze({ kind: "classes", form: "classes: <list>", pattern: /^classes:\s*(.+)$/iu, listed: true }),
])
const lineOf = (text, at) => text.slice(0, at).split("\n").length
const listOf = (text) =>
  text
    .split(",")
    .map((entry) => entry.trim())
    .filter(Boolean)

/** brief.md from --brief, else the session's; a usage error when neither is known. */
export function briefPathOf(flags) {
  if (flags.brief !== undefined && flags.brief !== true) return resolve(flags.brief)
  const dir = flags["session-dir"] ?? process.env.SESSION_DIR
  if (!dir || dir === true) throw new CliError("--brief is required without --session-dir (or SESSION_DIR)")
  return join(resolve(dir), "brief.md")
}

/**
 * @returns {{ parsed: object, refusal: null } | { parsed: null, refusal: { json: object, summary: string, exitCode: 1 } }}
 */
export function lockedBrief(command, flags) {
  const path = briefPathOf(flags)
  const lock = requireLockedBrief(path)
  if (lock.exitCode === 2) throw new CliError(`${path}: ${lock.errors.join("; ")}`)
  if (lock.locked) return { parsed: lock.parsed, refusal: null }
  const json = { command, status: "fail", exitCode: 1, defects: lock.defects }
  return { parsed: null, refusal: { json, summary: `${command}: ${lock.defects[0].message}`, exitCode: 1 } }
}

/**
 * The source floor as a rule, or null for `standard`; a usage error for any other text.
 * @returns {null | { kind: "primary" } | { kind: "pointed" | "classes", list: string[] }}
 */
export function parseSourceFloor(value) {
  const text = value.trim()
  for (const rule of SOURCE_FLOOR_RULES) {
    const match = rule.pattern.exec(text)
    if (!match) continue
    if (rule.kind === "standard") return null
    return rule.listed ? { kind: rule.kind, list: listOf(match[1]) } : { kind: rule.kind }
  }
  throw new CliError(`source floor "${value}" is not ${SOURCE_FLOOR_RULES.map((rule) => rule.form).join(", ")}`)
}

function hostOf(url) {
  return typeof url === "string" && URL.canParse(url) ? new URL(url).hostname.toLowerCase() : null
}

/** Whether one source (id and meta.json) satisfies a parsed floor rule. */
export function sourceInsideFloor(rule, sourceId, meta) {
  if (rule.kind === "primary") return meta.provenance === "primary"
  if (rule.kind === "pointed") return rule.list.includes(sourceId) || rule.list.includes(meta.url)
  const host = hostOf(meta.url)
  return (
    host !== null && rule.list.some((entry) => host === entry.toLowerCase() || host.endsWith(`.${entry.toLowerCase()}`))
  )
}

/** The fields fact fill consumes: the fallback form and whether a translation binds to its quote. */
export function fillPolicy(parsed) {
  const field = (name) => parsed.fields[name]
  return {
    fallback: FIDELITY_VALUE_RULES.fallback(field("fallback")),
    translations: FIDELITY_VALUE_RULES.translations(field("languages")),
    derivedNone: FIDELITY_VALUE_RULES.derivedNone(field("derived numbers")),
    floor: parseSourceFloor(field("source floor")),
  }
}

/** Source ids behind a row: its own, or for a derived row its operands' sources; null marks a leaf with no source. */
function sourcesOf(row, rows, seen = new Set()) {
  if (seen.has(row.fact_id)) return []
  seen.add(row.fact_id)
  if (row.source_id) return [row.source_id]
  const inputs = [...(row.operands ?? []), ...(row.derived_from ?? [])]
  if (inputs.length === 0) return [null]
  return inputs.flatMap((id) => (rows.has(id) ? sourcesOf(rows.get(id), rows, seen) : [null]))
}

/** sha256 of the locked `## Fidelity` block normalized: the seven fields in FIDELITY_FIELDS order, `field: value` per line. */
export const briefHashOf = (parsed) =>
  sha256Of(FIDELITY_FIELDS.map((field) => `${field}: ${parsed.fields[field]}`).join("\n"))

/** brief_changed when there is no fill map (map null) or it was not written under the current brief (or predates the binding). */
export function briefBindingErrors(map, mapPath, parsed) {
  if (map?.brief_sha256 === briefHashOf(parsed)) return []
  const why =
    map === null
      ? `no fill map at ${mapPath}`
      : `${mapPath} ${typeof map.brief_sha256 === "string" ? "was filled under a different ## Fidelity block" : "records no brief_sha256"}`
  return [
    {
      code: "brief_changed",
      token: null,
      line: null,
      message: `${why}; re-run fact fill under the current brief`,
      severity: DEFECT_CODES.brief_changed.severity,
      integrity: DEFECT_CODES.brief_changed.integrity,
      hint: DEFECT_CODES.brief_changed.hint,
    },
  ]
}

function metaOf(sessionDir, sourceId, cache) {
  if (!cache.has(sourceId)) {
    const file = join(sessionDir, "sources", sourceId, "meta.json")
    cache.set(
      sourceId,
      existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : { url: null, provenance: "unknown" },
    )
  }
  return cache.get(sourceId)
}

const defect = (code, pointer, text, message) => ({
  code,
  token: pointer.token,
  line: lineOf(text, pointer.start),
  message,
  severity: DEFECT_CODES[code].severity,
  hint: DEFECT_CODES[code].hint,
})

/**
 * Refusals for the placeholders of one fill source (or the data-fact elements of one edition at
 * verify). Sets each referenced row's outside_floor to this evaluation and reports whether any
 * cached value changed.
 * @param {{ token: string, start: number, parsed: { id?: string } }[]} found findPlaceholders output
 * @returns {{ errors: object[], cacheChanged: boolean }}
 */
export function policyErrors(text, found, ledger, sessionDir, policy) {
  const rows = new Map(ledger.rows.map((row) => [row.fact_id, row]))
  const metas = new Map()
  const errors = []
  let cacheChanged = false
  for (const pointer of found) {
    const row = rows.get(pointer.parsed?.id)
    if (row === undefined || row.status !== "active") continue
    if (policy.derivedNone && FIDELITY_VALUE_RULES.derivedRefused(row.kind)) {
      errors.push(
        defect(
          "derived_not_allowed",
          pointer,
          text,
          `${row.fact_id} is ${row.kind}; the brief records derived numbers: none`,
        ),
      )
    }
    const sources = sourcesOf(row, rows)
    const outside =
      policy.floor === null
        ? []
        : [
            ...new Set(
              sources.filter(
                (id) => id === null || !sourceInsideFloor(policy.floor, id, metaOf(sessionDir, id, metas)),
              ),
            ),
          ]
    if (row.outside_floor !== outside.length > 0) cacheChanged = true
    row.outside_floor = outside.length > 0
    const named = outside.map((id) => id ?? "no source").join(", ")
    if (outside.length > 0)
      errors.push(
        defect("source_outside_floor", pointer, text, `${row.fact_id} rests on ${named}, outside the source floor`),
      )
  }
  return { errors, cacheChanged }
}
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