Ucg Formalize

UCG Formalize

Overview

/ucg-formalize <epic> is the opt-in, operator-on-demand readiness verdict for a single BMAD Epic — the thin LLM layer over the readiness kernel (scripts/formalize_check.py). It adapts the kernel's graduated verdict (ready / remediable / blocked) into the canonical five-key headless envelope; it never recomputes the readiness verdict. Each verdict and remediation lands in .decision-log.md.

Conventions

• This skill ships no scripts/ or customize.toml of its own: the kernel (formalize_check.py, headless_envelope.py), customize.toml, and references/ all live in the parent ultracode-goal module. {ucg-root} names that module directory — {project-root}/_bmad/ucg/ultracode-goal in an installed project, or {project-root}/skills/ultracode-goal in a source checkout of the module itself. Resolve it once (first of those two that exists) and qualify every script path with it, so {ucg-root}/scripts/… and {ucg-root}/customize.toml resolve from any cwd. It is deliberately not {skill-root}: this is a top-level skill, so {skill-root} would resolve to this skill's own directory, which holds none of those files.
• {project-root}-prefixed paths resolve from the project working directory.
• {workflow.implementation_artifacts}, {workflow.tea_config_path}, {workflow.trace_output_dir} (step 2's leaked-TEA destination) and {workflow.deferred_work_path} resolve from the parent module's customize.toml workflow block (the same path scalars the autonomous run reads). {planning_artifacts} is not a workflow scalar — it resolves from BMad core config.yaml (root + bmm section), mirroring the parent SKILL.md, and is not part of the customize override surface.
• Of the three universal [workflow] defaults, this entry point loads one and runs neither. persistent_facts is loaded: it is read-only context, and a cold standalone verdict is exactly the session that has none. activation_steps_prepend and activation_steps_append are not executed here — they are operator-configured actions belonging to the autonomous run, and the standalone surfaces stay thin and side-effect-free. ucg-resolve and ucg-status state this same split, so the three agree; ucg-status in particular could not honor it otherwise, having promised to write nothing at all.
• The decision log (.decision-log.md) is canonical memory: record the verdict and every auto-remediation as you go. It lives in the Epic's run folder under {project-root}/_bmad-output/ultracode-goal/: reuse the newest epic-<id>-* folder for this Epic when one exists (appending a session entry), otherwise create epic-<id>-<UTC yyyymmddThhmmssZ> for this standalone check. That resolved path is what the Headless decision_log key carries, so two invocations over the same Epic cannot scatter their verdicts across two files.

On Activation

/ucg-formalize can run cold (outside an active ultracode goal run), so resolve the scalars this skill consumes — the step-1 kernel's and step 2's {workflow.trace_output_dir} — before calling the kernel, against the parent module, so they are the same path scalars the autonomous run reads. Run python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {ucg-root} --key workflow (on failure, merge {ucg-root}/customize.toml → {project-root}/_bmad/custom/ultracode-goal.toml → {project-root}/_bmad/custom/ultracode-goal.user.toml, scalars override / arrays append), and load {planning_artifacts} from {project-root}/_bmad/config.yaml (root + bmm section). If they cannot be resolved, do not pass unresolved {…} tokens to the kernel or to a step-2 file move (a move into a literal {workflow.trace_output_dir} directory would log as a successful remediation the kernel re-run can never see): record a blocked verdict and push a non-remediable blocker — source the unresolved config path, note "customization/config scalars unresolved" — into step 4's ordered blocker list, so the Headless reason renders.

1. Run the readiness kernel

Resolve the Epic id <id> the operator named, then run the readiness kernel — qualified by {ucg-root} so it resolves from any cwd:

uv run {ucg-root}/scripts/formalize_check.py --epic <id> --project-root {project-root} --planning-artifacts {planning_artifacts} --impl-artifacts {workflow.implementation_artifacts} --tea-config {workflow.tea_config_path}

Read the kernel's readiness verdict JSON from stdout. Its shape is {ready, verdict, mechanical_budget, judgment_required, mechanical_gaps[], judgment_candidates[], checks{}}. Do not recompute it: read mechanical_budget and the verdict off the JSON, never re-derive them here. There is one kernel — a second readiness evaluator would let the two callers drift.

The kernel is fail-closed: a missing / unreadable / ambiguous artifact is recorded as a failing gap, never a neutral pass.

2. Mechanical auto-remediation pass

Iterate the kernel's mechanical_gaps[] and apply the machine-derivable fix for each entry where remediable: true. The remediation per kind:

• leaked_tea_artifact — move the TEA artifact from the source/impl tree to the {workflow.trace_output_dir} root and re-point any reference to it. A path move is meaning-preserving. Verify identity before moving: a non-TEA false positive is archived out of the impl-artifacts scan tree — never into the trace dir (that misfiles it) and never left in place (an uncleared remediable gap keeps the verdict off ready).
• orphaned_index (regenerable story/AC) — regenerate the missing story or AC stub via bmad-create-story so the cited id resolves.
• missing_planning_artifact / missing_impl_artifact — backfill the regenerable scaffold (a PRD/ADR stub, the sprint-status.yaml rollup via bmad-sprint-planning).
• ac_missing_named_verification / ac_missing_anti_vacuous_twin — backfill the canonical named-verification / anti-vacuous-twin / gate-ability scaffold derivable from the AC shape.
• story_keys_uncovered / story_without_ac — run the bmad-create-story scaffold for the story keys the gap's detail names: story_keys_uncovered lists the unresolved subset, and story_without_ac names the one story whose AC section is missing.
• no_in_scope_stories — same scaffold, but this gap's detail names only the Epic and the artifacts directory, never a key list, so take the keys from the sprint rollup's rows for this Epic instead of trying to read them out of detail. First discriminate on the input: when the Epic id matches no row at all in the rollup, that is a mistyped or unseeded Epic, not a gap to scaffold over — record it as a non-remediable blocker and route to status=blocked rather than authoring stories for an Epic nobody planned.
• blank_pxi_score — write the gap's own recomputed value into the blank Score cell at its source line. Use the value the kernel supplies; never re-derive the product here, which would be a second multiplier free to disagree with the first.

The kernel emits ten remediable: true kinds and the list above covers all ten. A remediable: true kind that is nonetheless not listed here is never improvised from its detail: record it as a non-remediable blocker naming the kind and route to status=blocked. That clause is what keeps this list honest as the kernel grows — a new kind blocks loudly instead of being guessed at, and the halt catch-all below then covers the never-remediated case as well as the remediated-but-unfixed one.

Log each remediation to .decision-log.md as you apply it. Never auto-remediate a judgment_candidate, and never auto-remediate a remediable: false mechanical gap (an unreadable artifact cannot be fixed from its own unreadable content).

Re-run the kernel (step 1) after the remediation pass so mechanical_budget reflects the fixes — the remediate-then-re-run loop. The verdict mapping in step 4 reads the post-remediation kernel verdict.

Remediation halt catch-all. If a remediation sub-skill itself fails or blocks on interactive input, do not re-invoke it blind: record a non-remediable gap naming the sub-skill and the exact input it needed, and let the verdict mapping route the run to status=blocked. Likewise cap the loop at one pass per gap: if a kernel re-run still reports a gap whose kind+source a prior pass already remediated, the fix did not take — record it as a non-remediable blocker and route to status=blocked rather than re-entering step 2, so the remediate-then-re-run loop always converges instead of spinning silently.

3. Judgment subagent (exactly one)

Spawn exactly one throwaway subagent to read the judgment candidates; a second pass would double-judge the same candidates, so never two. Seed the subagent with the kernel's judgment_candidates[].source list as targeted hypotheses to confirm (it confirms the flagged sources, it does not scan blind), plus the artifact paths. The corpus stays in the subagent's discarded context (zero-net-context) — this layer holds only the returned findings.

The kernel only flags; the subagent decides. It must confirm-or-clear each seeded judgment_candidate into reds or concerns, never recording one as a RED unprompted. Fail-closed: a judgment_candidate the subagent can neither confirm nor clear defaults to RED (JUDGMENT), mirroring gate_eval.py's nfr_status is None → failing and the identical rule the spine's scan carries ({ucg-root}/references/preflight.md, second hypothesis stream). Without it a candidate the subagent simply does not return on is neither red nor concern, and silently vanishes into an accept — which would make this standalone pass fail-open exactly where the spine's is fail-closed, and contradict the kernel's own fail-closed contract stated in step 1. This rule binds the degraded inline read below too: losing the subagent costs the zero-net-context property, never the fail-closed one.

The subagent must return only this object — the live three-key contract the parent {ucg-root}/references/preflight.md semantic scan uses — no prose, no document quotes beyond the one-line evidence fields:

{"reds": [{"source": "<artifact path:line>",
           "kind": "undecided-product|undecided-architecture|contradiction|undefinable-done",
           "decision_needed": "<the exact decision a human must make>",
           "evidence": "<one quoted line>"}],
 "concerns": [{"source": "<artifact path:line>", "note": "<cosmetic / non-blocking gap, one line>"}],
 "advisories_checked": [{"sig": "<advisory id>", "status": "recurred|not-observed|unknown"}]}

Mint ids before mapping, and apply the operator's closes. Hand the returned scan object — the degraded inline read below yields the same object — to the same id layer the spine runs ({ucg-root}/references/preflight.md, step 3), in report-only mode:

uv run {ucg-root}/scripts/red_ids.py --scan - --impl-artifacts {workflow.implementation_artifacts} --dry-run

It mints each red's stable id and drops every red whose id an operator already closed in {workflow.implementation_artifacts}/.decisions.json, so a decision answered through /ucg-resolve does not re-block this surface at every invocation. Never mint, compare, or edit an id by hand, and a non-zero exit clears nothing: every scanned red stands. --dry-run is deliberate — .preflight-reds.json is the autonomous run's durable registry and a standalone readiness check must not overwrite it, which also means a red found only here is not answerable through /ucg-resolve until an autonomous preflight records it.

Any surviving reds entry maps to status=blocked. Record each red with its minted id, its source, and the exact decision needed in .decision-log.md. A purely cosmetic gap belongs in concerns, never red.

If subagent spawning is unavailable — wrong runtime, quota exhausted, or the spawn errors — do not dead-end the verdict: read the kernel's flagged judgment_candidates[].source inline in the current context (accepting the context cost; only the zero-net-context property is lost) and proceed to verdict mapping.

4. Verdict mapping

Map the post-remediation kernel verdict plus the subagent reds to the headless status by this deterministic decision-list; remediable is an internal loop state, never a headless emit value.

The last row is why this list is total. Without it the common case falls through every row: the kernel flags a judgment candidate on most Epics, the subagent clears it, and the result satisfies neither the accept row (the kernel never said ready) nor the first reject row (there is no red and no non-remediable gap). Its blocker list is the cleared candidates themselves, each by source, with decision_needed naming that the kernel flagged it and the judgment pass cleared it.

Row 1 is keyed on the kernel's own verdict word, never on the budget alone. The two are not equivalent: formalize_check.py sets verdict = "blocked" whenever judgment_required is true, independent of mechanical_budget, and step 2 never removes a judgment candidate (it is forbidden to remediate one). So budget 0 with zero reds is reachable while the kernel still reads blocked — whenever the subagent classified every flagged candidate into concerns. Keying the accept row on the budget would route that state to complete and hand back a ready verdict the kernel never gave. The budget and reds clause is the explanation of a ready verdict, not the test for one.

An artifact the kernel could not read is fail-closed to status=blocked (mirroring gate_eval.py's nfr_status is None -> failing read), never treated as neutral — formalize's blocked is a deliberate strengthening over gate_eval's reloop.

For a blocked envelope, assemble the ordered blocker list — confirmed reds before non-remediable mechanical gaps, each in source (path:line) order — and hand it to the blocked adapter (see Headless), which renders reason positionally from it.

Headless

With -H, run non-interactively and emit exactly one object at the single exit point. This is the canonical five-always-present-key envelope — byte-identical to the autonomous parent SKILL.md shape: skill is the constant ultracode-goal (never ucg-formalize), and the script-layer keys (verdict, mechanical_budget) never leak into the envelope.

Serialize through the one shared module {ucg-root}/scripts/headless_envelope.py — the same definition {ucg-root}/references/preflight.md and {ucg-root}/references/finalize.md use — so this entry point and the autonomous run cannot serialize the same verdict differently. The module exposes two entry points, and they are picked by shape, never by name:

build_headless_envelope reads like the general adapter and is not: it is the blocked one, which is why it is also exported as build_blocked_envelope — the name to read for. Handing it a complete-shaped mapping now raises ValueError; before it raised, it read no blockers, synthesised one, appended that fabrication to .decision-log.md, and wrote a blocked run-result.json over a successful run. That was observed in the field, which is why the shape rule is stated here rather than left to inference.

This entry point passes no impl_artifacts. The parent passes it so the adapter also pins the envelope to {workflow.implementation_artifacts}/run-result.json; a readiness check is not a run, and writing that file here would overwrite an autonomous run's terminal verdict with the result of a standalone question. Stdout is the sole output of /ucg-formalize.

On the accept path (status=complete, post-remediation verdict ready) emit all five keys:

{"status": "complete",
 "skill": "ultracode-goal",
 "decision_log": "<path to this run's .decision-log.md>",
 "report": "<path to the readiness report, or null>",
 "deferred_work": "<path to {workflow.deferred_work_path}, or null>"}

On the reject path (status=blocked) emit the same five keys plus the conditional sixth reason; report and deferred_work are null because the run blocked before producing them:

{"status": "blocked",
 "skill": "ultracode-goal",
 "decision_log": "<path to this run's .decision-log.md>",
 "report": null,
 "deferred_work": null,
 "reason": "<positional blockers[0], one line>"}

An automator parses the five canonical keys at any verdict; reason appears only on a blocked emit. Record the final verdict to .decision-log.md before emitting; the log carries the full blocker and remediation list.

Measurement protocol

The kernel emits a self-measured timing block on every verdict carrying wall_clock_ms, mechanical_ms, epic, and artifact_count. Append those four values verbatim as one line to .decision-log.md on every verdict, reusing the existing decision-log channel. They are the only durations recorded: measured by the kernel in Python, copied here, never authored. This layer times nothing itself — a duration the model derives by subtracting two clock reads it carried across the remediation loop is authored arithmetic wearing a measurement's name.

The wall-clock ceiling is declared-unknown: set only from a first real preflight-invoked run, never authored here. An over-budget formalize never blocks, escalates, or downgrades a verdict — the measurement is provenance, not a gate.