design: one parsed workflow model for every workflow rule #971

Problem

Hypatia's workflow rules read GitHub Actions YAML as text lines, and each module carries its own job/step parser:

Evidence. Four Codex review rounds on #966 (RE001's risk-scoped rewrite) raised 22 findings. Every one was a YAML shape that the line reader got wrong:

• flow maps spanning lines; on: &anchor; folded run: >-;
• bare - steps; an env: key named run;
• step env overriding job env;
• with: {ref: …}; and more.

Each fix closed one shape and left the class open. #950 and #947 show the same pattern in WH013/RE005.

Proposal

Parse each workflow once into a small typed model, and have every workflow rule query that model:

Workflow  { path, triggers: [event], env, permissions, jobs: [Job] }
Job       { id, runs_on?, uses?, if?, env, permissions, steps: [Step], loc }
Step      { uses?, run?, run_style (:plain | :quoted | :literal | :folded), with, env, if?, loc }

The model keeps source line numbers, so findings still point at the source. Step.run is the scalar's value after folding. The effective step environment is Workflow.env ⊕ Job.env ⊕ Step.env.

Reader: metadatastician/kyq

The estate already has a normative reader for this: metadatastician/kyq, docs/KYAML_SPEC.adoc v0.1.0. It defines a YAML 1.2 subset with block and flow collections, anchors and aliases, folded and literal scalars, the Core Schema, and duplicate keys rejected with located diagnostics. Its executable gate is conformance/ (kyq-conformance, pinned by conformance/VERSION and the tag kyq-conformance-v<version>).

Measured 2026-10-27 at kyq 9a44686:

• kyq-conformance validate accepts 137/137 workflow files across hypatia (34), metadatastician/standards (68) and hyperpolymath/echidna (35).
• parseKyaml returns a positioned AST, with line:column on every node.
• The AST keeps on as a string (Core Schema, so no YAML 1.1 on → true).
• Block scalars come back with their folded/chomped value.

That removes the need for a third-party parser such as yamerl, and the estate gets one definition of "what this YAML means" shared by kyq and hypatia.

How hypatia consumes it. This is the decision to make; the experiment informs it.

flow_to_block (KYAML normalisation) would be retired by any route.

Experiment before building (no rule changes)

1. Prototype the model for research_extensions only, behind a function that returns the same finding maps. Use route B first, since it is cheapest.
2. Differential run on 3 repos (hypatia, metadatastician/standards, hyperpolymath/echidna): today's RE001–RE010 versus the model-backed versions. Report every difference; each one is either a bug the parser fixes or a regression.
3. Replay the edge-case corpus: every fixture added for fix(rules): scope RE001 to credentials exposed to code the job cannot vouch for #966's Codex rounds (in test/research_extensions_test.exs and test/kyaml_workflow_test.exs). It must pass unchanged.
4. Measure cold-start and per-file parse time for route B, and estimate route A's size. The gate builds the escript on every governance run, so runtime dependencies cost every consumer.

The decision point is after step 4: route A, route B, or keep the line reader until route C unblocks.

Out of scope / known limits that survive the model

• Command position inside shell (echo 'run npm ci' vs npm ci) needs a shell tokenizer, not YAML. For now RE001 keeps reporting quoted install words; the maintainer chose that on fix(rules): scope RE001 to credentials exposed to code the job cannot vouch for #966.
• git clone X && ./X/script as fetched code.

Beyond this repo

• kyq: hypatia becomes a consumer of the KYAML spec, so verdict changes in kyq/conformance become hypatia version bumps. Worth recording as a docs/UPSTREAM_HANDOFFS.adoc entry in kyq.
• Estate: every estate repo runs these rules through the governance gate. Precision gained here shows up estate-wide, and so does a regression.