Skip to content

armelhbobdad/bmad-module-ultracode-goal / skills/ultracode-goal

ultracode-goal

Flagged

Runs a BMAD Epic autonomously to a machine-checked Definition-of-Done. Use when the user requests to 'run an epic autonomously', 'execute this epic', 'ultracode goal', or 'autonomously deliver the epic'.

FileKindSize
SKILL.mdskill md15.9 KB
assets/module-help.csvother2.1 KB
assets/module-setup.mdmarkdown5.9 KB
assets/module.yamlconfig1.9 KB
assets/ucg-awareness/bmad-architecture.tomlconfig2.5 KB
assets/ucg-awareness/bmad-create-epics-and-stories.tomlconfig3.3 KB
assets/ucg-awareness/bmad-prd.tomlconfig2.1 KB
assets/ucg-awareness/bmad-testarch-nfr.tomlconfig1.8 KB
assets/ucg-awareness/bmad-testarch-test-design.tomlconfig3.1 KB
assets/ucg-awareness/shaping-decision.mdmarkdown6.8 KB
assets/ucg-awareness/ucg-create-story.tomlconfig3.3 KB
customize.tomlconfig9.8 KB
references/define-done.mdmarkdown15.4 KB
references/execute.mdmarkdown116.7 KB
references/finalize.mdmarkdown39.2 KB
references/gate.mdmarkdown134.5 KB
references/health-check.mdmarkdown27.0 KB
references/ingest-and-scope.mdmarkdown28.2 KB
references/preflight.mdmarkdown83.6 KB
scripts/carry_build_cache.pyscript18.6 KB
scripts/claim_check.pyscript36.3 KB
scripts/drive_epic.pyexecutablescript64.1 KB
scripts/formalize_check.pyscript83.7 KB
scripts/gate_eval.pyexecutablescript67.8 KB
scripts/gate_trail.pyexecutablescript52.6 KB
scripts/headless_envelope.pyscript12.6 KB
scripts/health_check_fp.pyscript66.5 KB
scripts/hooks/budget_stop.pyexecutablescript18.7 KB
scripts/hooks/guard_pretooluse.pyexecutablescript180.1 KB
scripts/lib/mem_common.pyscript64.6 KB
scripts/link_worktree_deps.pyscript7.1 KB
scripts/mem_observation.pyscript35.5 KB
scripts/mem_recall.pyscript19.9 KB
scripts/merge_config.pyexecutablescript13.8 KB
scripts/merge_customization.pyscript18.7 KB
scripts/merge_help_csv.pyscript9.5 KB
scripts/moved_ac_check.pyscript10.0 KB
scripts/mutate_check.pyscript64.4 KB
scripts/operator_owed.pyscript17.0 KB
scripts/preflight_check.pyscript115.2 KB
scripts/probe_servers.pyscript38.7 KB
scripts/red_ids.pyscript14.0 KB
scripts/status_render.pyscript26.0 KB
scripts/story_sizing.pyexecutablescript11.7 KB
scripts/tests/bench_ucg_formalize.mdmarkdown7.3 KB
scripts/tests/fixtures/claude_mem_real_payload.jsonconfig3.4 KB
scripts/tests/fixtures/engine-6.12/README.mdmarkdown957 B
scripts/tests/fixtures/engine-6.12/config_utils.pyscript4.1 KB
scripts/tests/fixtures/engine-6.12/resolve_customization.pyexecutablescript5.1 KB
scripts/tests/fixtures/engine/README.mdmarkdown1.0 KB
scripts/tests/fixtures/engine/resolve_customization.pyexecutablescript8.0 KB
scripts/tests/fixtures/execute_pre_verification_axes.mdmarkdown29.1 KB
scripts/tests/fixtures/execute_resume_clause_no_baseline.mdmarkdown215 B
scripts/tests/fixtures/execute_run_status_preedit.mdmarkdown1.2 KB
scripts/tests/fixtures/execute_spine_end_no_escalation_fire.mdmarkdown194 B
scripts/tests/fixtures/execute_step0_baseline_no_sha.mdmarkdown1.0 KB
scripts/tests/fixtures/execute_ticker_line.mdmarkdown332 B
scripts/tests/fixtures/finalize_epic_complete_hook_no_escalation.mdmarkdown579 B
scripts/tests/fixtures/finalize_headless_output_hand_composed.mdmarkdown1.2 KB
scripts/tests/fixtures/finalize_no_graphify_section.mdmarkdown19.4 KB
scripts/tests/fixtures/floor/all_clean/impl-artifacts/7-1-clean.mdmarkdown477 B
scripts/tests/fixtures/floor/all_clean/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/floor/all_clean/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/all_clean/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/all_clean/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/all_clean/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/invented_threshold/impl-artifacts/61-1-threshold.mdmarkdown564 B
scripts/tests/fixtures/floor/invented_threshold/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/invented_threshold/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/invented_threshold/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/invented_threshold/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/invented_threshold/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/invented_threshold_unknown/impl-artifacts/61-1-threshold.mdmarkdown644 B
scripts/tests/fixtures/floor/invented_threshold_unknown/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/invented_threshold_unknown/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/invented_threshold_unknown/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/invented_threshold_unknown/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/invented_threshold_unknown/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/9-1-leak.mdmarkdown475 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/test-design-9-1.mdmarkdown291 B
scripts/tests/fixtures/floor/leaked_tea/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/leaked_tea/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/leaked_tea/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/leaked_tea/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea_clean/impl-artifacts/9-1-leak.mdmarkdown475 B
scripts/tests/fixtures/floor/leaked_tea_clean/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/floor/leaked_tea_clean/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/leaked_tea_clean/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/traceability/test-design-9-1.mdmarkdown296 B
scripts/tests/fixtures/floor/orphaned_index/impl-artifacts/10-1-orphan.mdmarkdown513 B
scripts/tests/fixtures/floor/orphaned_index/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/orphaned_index/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/orphaned_index/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/orphaned_index/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/orphaned_index/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/10-1-orphan.mdmarkdown508 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/10-2-helper.mdmarkdown479 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/sprint-status.yamlconfig120 B
scripts/tests/fixtures/floor/orphaned_index_resolved/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/orphaned_index_resolved/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/orphaned_index_resolved/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/orphaned_index_resolved/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/sourced_threshold/impl-artifacts/61-1-threshold.mdmarkdown609 B
scripts/tests/fixtures/floor/sourced_threshold/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/sourced_threshold/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/sourced_threshold/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/sourced_threshold/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/sourced_threshold/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/unclassified_signal/impl-artifacts/12-1-signal.mdmarkdown552 B
scripts/tests/fixtures/floor/unclassified_signal/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/unclassified_signal/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/unclassified_signal/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/unclassified_signal/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/unclassified_signal/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/unclassified_signal_removed/impl-artifacts/12-1-signal.mdmarkdown483 B
scripts/tests/fixtures/floor/unclassified_signal_removed/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/unclassified_signal_removed/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/unclassified_signal_removed/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/unclassified_signal_removed/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/unclassified_signal_removed/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/vacuous_ac/impl-artifacts/8-1-vacuous.mdmarkdown435 B
scripts/tests/fixtures/floor/vacuous_ac/impl-artifacts/sprint-status.yamlconfig90 B
scripts/tests/fixtures/floor/vacuous_ac/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/vacuous_ac/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/vacuous_ac/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/vacuous_ac/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/vacuous_ac_sound/impl-artifacts/8-1-vacuous.mdmarkdown482 B
scripts/tests/fixtures/floor/vacuous_ac_sound/impl-artifacts/sprint-status.yamlconfig90 B
scripts/tests/fixtures/floor/vacuous_ac_sound/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/vacuous_ac_sound/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/vacuous_ac_sound/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/vacuous_ac_sound/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/epic-clean-control/LABEL.mdmarkdown751 B
scripts/tests/fixtures/formalize/epic-clean-control/impl-artifacts/7-1-clean.mdmarkdown477 B
scripts/tests/fixtures/formalize/epic-clean-control/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/formalize/epic-clean-control/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/formalize/epic-clean-control/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/formalize/epic-clean-control/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/epic-clean-control/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/epic-judgment-seed/LABEL.mdmarkdown1.1 KB
scripts/tests/fixtures/formalize/epic-judgment-seed/impl-artifacts/61-1-threshold.mdmarkdown564 B
scripts/tests/fixtures/formalize/epic-judgment-seed/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/formalize/epic-judgment-seed/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/formalize/epic-judgment-seed/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/formalize/epic-judgment-seed/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/epic-judgment-seed/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/impl-artifacts/6-1-experience.mdmarkdown1.3 KB
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/impl-artifacts/sprint-status.yamlconfig93 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/planning-artifacts/architecture-fixture.mdmarkdown93 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/planning-artifacts/prd-fixture.mdmarkdown84 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/1-1-kernel.mdmarkdown848 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/1-2-floor.mdmarkdown538 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/sprint-status.yamlconfig110 B
scripts/tests/fixtures/formalize/ready_epic/planning-artifacts/architecture-fixture.mdmarkdown218 B
scripts/tests/fixtures/formalize/ready_epic/planning-artifacts/prd-fixture.mdmarkdown207 B
scripts/tests/fixtures/formalize/ready_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/ready_epic/tea/traceability/e2e-trace-summary.jsonconfig49 B
scripts/tests/fixtures/formalize/remediable_epic/impl-artifacts/2-1-thin.mdmarkdown202 B
scripts/tests/fixtures/formalize/remediable_epic/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/formalize/remediable_epic/planning-artifacts/architecture-fixture.mdmarkdown94 B
scripts/tests/fixtures/formalize/remediable_epic/planning-artifacts/prd-fixture.mdmarkdown85 B
scripts/tests/fixtures/formalize/remediable_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/remediable_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/impl-artifacts/4-1-signal.mdmarkdown546 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/impl-artifacts/sprint-status.yamlconfig89 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/planning-artifacts/architecture-fixture.mdmarkdown103 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/planning-artifacts/prd-fixture.mdmarkdown94 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/unreadable_epic/impl-artifacts/3-1-broken.mdbinary28 B
scripts/tests/fixtures/formalize/unreadable_epic/impl-artifacts/sprint-status.yamlconfig89 B
scripts/tests/fixtures/formalize/unreadable_epic/tea/config.yamlconfig85 B
scripts/tests/fixtures/formalize/unreadable_epic/tea/traceability/.keepother14 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/5-1-place.mdmarkdown420 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/prd-fixture.mdmarkdown226 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/formalize/wrong_root_epic/planning-artifacts/architecture-fixture.mdmarkdown187 B
scripts/tests/fixtures/formalize/wrong_root_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/wrong_root_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/gate_run_the_gate_no_ticker.mdmarkdown5.7 KB
scripts/tests/fixtures/gate_trail/light/decision-log.mdmarkdown341 B
scripts/tests/fixtures/gate_trail/light/impl-artifacts/.baseline-2-4other41 B
scripts/tests/fixtures/gate_trail/light/impl-artifacts/.baseline-2-6other41 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/gate-decision-2-4.jsonconfig751 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/gate-decision-2-6.jsonconfig755 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/trace-2-4.mdmarkdown1.4 KB
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/trace-2-6.mdmarkdown1.3 KB
scripts/tests/fixtures/gate_trail/production/decision-log.mdmarkdown783 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-1other41 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-2other41 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-3other41 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/atdd-checklist-7-1.mdmarkdown509 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/atdd-checklist-7-2.mdmarkdown300 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/traceability/gate-decision-7-1.jsonconfig648 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/traceability/gate-decision-7-2.jsonconfig679 B

scripts/headless_envelope.py

View on GitHub
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# ///
"""The single headless-envelope adapter.

`build_headless_envelope` adapts a blocker source — either an ordered blocker list
or `formalize_check.py`'s formalize verdict object — into the ONE canonical five-key
headless envelope (status, skill, decision_log, report, deferred_work) plus the
conditional `reason`, exactly the shape the preflight step-4 block and the
ucg-formalize SKILL.md block document. The formalize verdict stays a SEPARATE
script-layer object — it is never nested into the envelope (two-layer
separation). A formalize RED therefore routes through the IDENTICAL channel as a
semantic-scan RED; no formalize-specific key, no formalize-specific status.

`reason` is POSITIONAL: the one-line rendering of `blockers[0]` (the caller-supplied
order; reds carry no severity field), flattened to a single physical line. Every
formalize RED is also written to the run's `.decision-log.md`, so a headless
block is never silent and the one-line reason reconstructs to its full finding. An
empty blocker list cannot make a block silent either: it is a fail-closed signal in
its own right, so the adapter substitutes an explicit no-recorded-blocker blocker
rather than emitting a blocked envelope whose `reason` is the empty string.

Both terminal shapes also land on disk at `<impl-artifacts>/run-result.json`, so an
automator reads a file instead of scraping the transcript. `render_envelope` is the
ONE serialization: the string it returns is what the file holds and what the run
emits on stdout, so the two are byte-identical by construction rather than by
convention. The write is best-effort: it never raises, because a terminal emit that
died on an unwritable directory would convert a clean exit into a crash.

Stdlib-only. Fail-closed (mirroring gate_eval.py `nfr_status is None -> failing`):
a missing / unparseable formalize verdict is treated as a blocking signal, never neutral.
"""

from __future__ import annotations

import json
import re
from pathlib import Path

SKILL = "ultracode-goal"
# The five always-present canonical keys; `reason` is the conditional sixth.
CANONICAL_KEYS = ("status", "skill", "decision_log", "report", "deferred_work")
# Path-pinned and overwrite-in-place, exactly like run-status.json.
RESULT_FILENAME = "run-result.json"


def _blocker_fields(blocker: dict) -> tuple[str, str]:
    """(source, decision) for a blocker of either shape.

    Formalize and semantic-scan reds carry {source, decision_needed};
    preflight_check.py's mechanical blockers carry {id, detail}. Reading only the
    first shape rendered an empty `reason` whenever a mechanical blocker led the
    list (a missing story skill, an unborn HEAD), so a headless operator got
    a blocked envelope with no cause in it.
    """
    source = str(blocker.get("source") or blocker.get("id") or "").strip()
    decision = str(blocker.get("decision_needed") or blocker.get("detail") or "").strip()
    return source, decision


def _one_line(blocker: dict) -> str:
    """Render a blocker as ONE physical line (no newline)."""
    source, decision = _blocker_fields(blocker)
    text = f"{source} - {decision}" if source and decision else (source or decision)
    return re.sub(r"\s+", " ", text.replace("\n", " ")).strip()


def fr5_blockers(verdict: object) -> list[dict]:
    """Extract an ordered blocker list from a formalize verdict — fail-closed.

    A missing / non-dict / unparseable verdict, or one whose ``verdict`` is not the
    terminal ``ready``, is a BLOCKING signal: blocked when ``verdict == 'blocked'``
    (its judgment_candidates are the blockers: on a ``--scan`` re-run's verdict, the
    candidates the scan left unanswered, since an answered one moves to
    judged_candidates) or on an unreadable verdict.

    A candidate the scan CONFIRMED (``judged_candidates`` with ``judged_as ==
    'red'``) is a red at any readable verdict, ``ready`` included: the kernel no
    longer owes a judgment on it, but it blocks through the reds stream. It is
    named first, since confirmed reds lead the blocker list. ``ready`` and
    ``remediable`` with no confirmed red yield no blockers. The verdict cannot
    see a red an operator closed (red_ids.py drops those), so a caller that ran
    red_ids.py hands the adapter an ordered list instead.
    """
    if not isinstance(verdict, dict):
        return [{"source": "formalize", "decision_needed": "formalize verdict unreadable or absent", "kind": "unreadable"}]
    v = verdict.get("verdict")
    if v not in ("ready", "remediable", "blocked"):
        return [{"source": "formalize", "decision_needed": "formalize verdict is unreadable or missing", "kind": "unreadable"}]
    judged = verdict.get("judged_candidates")
    confirmed = [
        _candidate_blocker(c)
        for c in (judged if isinstance(judged, list) else [])
        if isinstance(c, dict) and c.get("judged_as") == "red"
    ]
    if v == "blocked":
        cands = verdict.get("judgment_candidates") or []
        blockers = confirmed + [_candidate_blocker(c) for c in cands if isinstance(c, dict)]
        # A blocked verdict with no candidates is still a block (fail-closed).
        return blockers or [{"source": "formalize", "decision_needed": "formalize verdict is blocked", "kind": "blocked"}]
    return confirmed


def _candidate_blocker(c: dict) -> dict:
    return {
        "source": c.get("source", ""),
        "decision_needed": c.get("why_machine_cannot_decide") or c.get("decision_needed", ""),
        "kind": c.get("kind", ""),
    }


def _append_to_log(decision_log: str, lines: list[str]) -> None:
    Path(decision_log).parent.mkdir(parents=True, exist_ok=True)
    with open(decision_log, "a", encoding="utf-8") as fh:
        fh.write("\n".join(lines) + "\n")


def _append_line_to_log(decision_log: str, line: str) -> None:
    _append_to_log(decision_log, ["", line])


def _append_blockers_to_log(decision_log: str, blockers: list[dict]) -> None:
    """Write the full formalize/semantic blockers (source:line + decision_needed) to the log."""
    lines = ["", "## Headless blocked envelope - full blocker list", ""]
    for b in blockers:
        source, decision = _blocker_fields(b)
        lines.append(f"- {source} :: {decision}")
    _append_to_log(decision_log, lines)


def render_envelope(envelope: dict) -> str:
    """The ONE serialization of an envelope.

    Whatever goes to stdout and whatever goes into ``run-result.json`` is THIS string,
    produced once and handed to both sinks. Serializing twice with independently-chosen
    ``json.dumps`` kwargs is the divergence this single function exists to prevent.
    No trailing newline: the file holds exactly the emitted bytes and nothing more.
    """
    return json.dumps(envelope, ensure_ascii=False)


def _resolved_impl_artifacts(impl_artifacts) -> Path | None:
    """The impl-artifacts dir, or None when it has not resolved yet.

    A block that fires before the config resolves (no BMAD project, so no
    ``customize.toml`` scalar to resolve) has nowhere to put the file. None, empty, and
    a still-unsubstituted ``{...}`` placeholder are all that same unresolved case.
    """
    if impl_artifacts is None:
        return None
    text = str(impl_artifacts).strip()
    if not text or ("{" in text and "}" in text):
        return None
    return Path(text)


def write_run_result(text: str, impl_artifacts, decision_log: str | None = None) -> Path | None:
    """Write the serialized envelope to ``<impl-artifacts>/run-result.json``.

    Returns the path written, or None when impl-artifacts has not resolved (the
    pre-resolution block, whose stdout envelope is the sole output) or when the write
    failed. **Never raises**: a failed write is logged and the run still emits, because
    a terminal emit that crashed on an unwritable directory is strictly worse than one
    that only reached stdout.
    """
    target_dir = _resolved_impl_artifacts(impl_artifacts)
    if target_dir is None:
        return None
    path = target_dir / RESULT_FILENAME
    try:
        target_dir.mkdir(parents=True, exist_ok=True)
        path.write_text(text, encoding="utf-8")
    except OSError as exc:
        if decision_log:
            try:
                _append_line_to_log(decision_log, f"WARN run-result-write-failed :: {path} :: {exc}")
            except OSError:
                pass  # the log is unwritable too; the stdout emit still stands
        return None
    return path


def build_headless_envelope(
    source,
    decision_log,
    *,
    write_log: bool = True,
    impl_artifacts=None,
    report=None,
    deferred_work=None,
) -> dict:
    """Adapt a blocker source into the canonical BLOCKED envelope.

    THIS IS THE BLOCKED ADAPTER. Its complete sibling is
    :func:`build_complete_envelope`, and the name here is historical - see the
    :data:`build_blocked_envelope` alias below, which is what new callers should
    read for.

    ``source`` is either an ordered list of blocker dicts (each {source, decision_needed},
    or a preflight_check.py mechanical blocker {id, detail}) or a formalize verdict dict (adapted via :func:`fr5_blockers`). Returns exactly the five
    canonical keys plus ``reason`` (the one-line rendering of ``blockers[0]``).

    ``report`` / ``deferred_work`` are optional because a blocked exit is not
    always artifact-less. A run that ESCALATED reached Stage 6 and produced a run
    report and a gate trail, so hard-coding them to ``None`` under-reported what
    was on disk for the one run most worth reading. They stay ``None`` when the
    block happened before those artifacts existed, which is the earlier block
    points' case.

    When ``impl_artifacts`` resolves, the same bytes are also written to
    ``run-result.json`` there.
    """
    # Refuse a complete-shaped mapping BEFORE any side effect. Handed one, the
    # fail-closed branch below reads no blockers from it, SYNTHESISES one, and
    # then (a) appends a fabricated "formalize verdict is unreadable or missing"
    # line to the decision log and (b) writes a `blocked` run-result.json over a
    # successful run - corrupting the two artifacts an automator and a resume
    # read, silently and with no exception. Observed in the field. Raising is
    # right even though the emit path is otherwise never-raise: this is a caller
    # error, and the alternative is a wrong answer written to disk.
    if isinstance(source, dict) and str(source.get("status", "")).strip() == "complete":
        raise ValueError(
            "build_headless_envelope is the BLOCKED adapter; a complete-shaped "
            "mapping belongs in build_complete_envelope"
        )
    blockers = source if isinstance(source, list) else fr5_blockers(source)
    decision_log = str(decision_log)
    if not blockers:
        # Fail-closed: a blocked envelope always carries a cause. An empty blocker list
        # is itself the anomaly worth naming, not a licence to emit an empty `reason`
        # and write nothing to the log.
        blockers = [
            {
                "source": "headless",
                "decision_needed": "blocked with no recorded blocker",
                "kind": "unreadable",
            }
        ]
    reason = _one_line(blockers[0])
    if write_log:
        _append_blockers_to_log(decision_log, blockers)
    envelope = {
        "status": "blocked",
        "skill": SKILL,
        "decision_log": decision_log,
        "report": str(report) if report else None,
        "deferred_work": str(deferred_work) if deferred_work else None,
        "reason": reason,
    }
    write_run_result(render_envelope(envelope), impl_artifacts, decision_log)
    return envelope


# The name this adapter should have had. `build_headless_envelope` reads as the
# adapter for headless generally, which is how a complete-shaped mapping came to
# be handed to the blocked one.
build_blocked_envelope = build_headless_envelope


def build_complete_envelope(decision_log, *, report=None, deferred_work=None, impl_artifacts=None) -> dict:
    """Build the canonical COMPLETE envelope: exactly the five canonical keys.

    ``reason`` is not in this dict at all. It is the conditional sixth key of a BLOCKED
    exit, so a complete emit omits it rather than carrying it as ``null`` — a caller must
    read `reason` only when `status` is `blocked`. ``report`` / ``deferred_work`` stay
    ``null`` when that artifact was not produced, so the five are KeyError-safe.
    """
    envelope = {
        "status": "complete",
        "skill": SKILL,
        "decision_log": str(decision_log),
        "report": str(report) if report else None,
        "deferred_work": str(deferred_work) if deferred_work else None,
    }
    write_run_result(render_envelope(envelope), impl_artifacts, envelope["decision_log"])
    return envelope
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall