work order: submission profile, header parser, honest unknowns, and hfsgtfoomw as fixture zero #101

What this is

A work order from hyperpolymath/hfsgtfoomw — a PiP/overlay userscript product — for the parts of the curation layer we depend on. hfsgtfoomw is being published as a Greasy Fork userscript, and the standing constraint is that every publishing decision stays compatible with checky-monkey as a Greasy Fork complement. This issue is what that sentence turns into as work.

Its design note, with the submission profile and the compatibility argument, is docs/proposals/USCRIPT-PUBLISHING.adoc in that repository. Nothing here asks checky-monkey to change its roadmap; the two asks at the end are questions, not demands.

What we will hand you

Per script, two things:

1. A userscript header with a deliberately narrow surface: @grant GM_getValue, GM_setValue, GM_registerMenuCommand, GM_addStyle; no @connect, no @require, no remote @resource; SPDX @license; @noframes.
2. A TOML submission manifest, userscript-submission/0.1:

[script]
name        = "hfsgtfoomw"
version     = "0.1.0"
homepage    = "https://github.com/hyperpolymath/hfsgtfoomw"
license     = "MPL-2.0"
source      = "https://github.com/hyperpolymath/hfsgtfoomw"
[compat]
managers    = ["tampermonkey", "violentmonkey", "greasemonkey"]
browsers    = ["chrome>=116", "edge>=116", "firefox>=151"]
[permissions]
grants      = ["GM_getValue", "GM_setValue", "GM_registerMenuCommand", "GM_addStyle"]
[network]
egress      = "none"
[build]
reproducible = true
[conformance]
criteria    = "AC-1..AC-11"
report      = "docs/TECHNICAL-CONFORMANCE.adoc"
[accessibility]
keyboard_only = true
announces_state = true
reduced_motion = true
[security]
zero_trust_env = true
telemetry      = "none"

The work order

Ordered by what unblocks the other items; each is independently useful.

1. Header parser. Parse a .user.js header into ScriptMetadata — including the @grant set, @connect, @require, @resource, @noframes, SPDX @license, @match/@include. The model in the README looks right; this is the loader that feeds it.
2. Manifest cross-check. Given a header and a userscript-submission/0.1 manifest for the same script, report every disagreement (declared grant not in the header, egress="none" but an @connect present, licence mismatch, browser floor not implied by the code). Disagreement is a finding, not a failure of the script.
3. Provenance import. Accept a source URL + commit and record it in the CUBS record. "Unverified" must not read as "pass" — that distinction is the whole value of a registry, and a submission with no provenance should show as unknown, never as clean.
4. An honest first analysis pass. Whatever the eight TrustScore dimensions can actually decide from a header and a static scan, and nothing more. A dimension that cannot be decided yet should be absent, not scored at 0 or 100.
5. CUBS record + CLI contract. checky validate <file> and checky record <file> with the estate's three-outcome convention: 0 clean, 1 findings, 2 setup/inert (cannot judge). Exit 2 exists so that a skip is never mistaken for a pass.
6. Planted-positive fixtures. At least one fixture per finding, each with a negative control, so a clean report is evidence. hfsgtfoomw volunteers as fixture zero: we will hand you the script, its manifest, and one deliberately broken variant, and we will keep them in step with the published artifact.
7. Docs, including what you do not check yet. The "not checked yet" list is the part a curator and a user actually needs; a validator that only advertises what it catches trains people to read silence as safety.
8. The language line. The estate denies ReScript (and Python, Go, TypeScript, Nix, AGPL) and names AffineScript as the target for TypeScript- and ReScript-shaped code. The roadmap's "full ReScript rewrites" line is the one thing in this repository that cannot be honoured by anything we publish. Replacing that line — with "AffineScript" or with "Haskell stays in the validator, the scripts move to AffineScript" — is a one-line change with a large effect on what we can claim about compatibility.

Two defects we found while writing the profile

These are reported because they bear on the registry's meaning, not to be difficult:

• No unknown / checks_skipped outcome. The three-outcome convention (0/1/2) exists in the wider estate for exactly this reason. A validator whose report has no "could not judge" state forces every caller to treat absence of a finding as a pass, which is unsafe precisely when the tool is new.
• The ReScript line in the roadmap conflicts with the estate's deny list. It is worth deciding which one is authoritative before the roadmap is used to plan.

What we need from you, to be able to call it compatible

1. Confirm or correct the manifest shape. If userscript-submission/0.1 is wrong for you, say what it should be — we adopt yours rather than mint a second dialect.
2. Say what "curated" will mean at v1. If v1 will only parse headers, we will describe the coverage that way in our docs, rather than implying review.

Until then, our README and publishing notes describe checky-monkey as planned curation, not as a validation we can point at. That is the honest state and we would rather keep it than overstate.

Source of this work order: hyperpolymath/hfsgtfoomw, docs/proposals/USCRIPT-PUBLISHING.adoc §4 (eight-item order), Appendix A (topics), §3 (requirements back on checky-monkey).