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/merge_customization.py

View on GitHub
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = ["tomli-w"]
# ///
"""Install-time merge of a UCG-awareness fragment into a BMad customize target.

Lands a fragment's flat ``persistent_facts`` string facts into a target
customization TOML (e.g. ``_bmad/custom/bmad-prd.toml``) using a stamp-scoped
anti-zombie strip-then-reappend, mirroring ``merge_help_csv.py``:

  - the strip (``_strip_ucg_rows``) is the anti-zombie filter — every existing
    ``persistent_facts`` string carrying a ``[ucg:<id>]`` marker is removed
    before the fragment's items are re-appended, so re-install converges
    byte-stable and stale UCG rows never persist;
  - one ``[ucg]`` stamp table (``managed``/``version``/``block``/
    ``installed_at``) plus an ``item_hashes`` manifest of UCG-owned content
    hashes is (re)written under it.

The landing channel is the NESTED ``workflow.persistent_facts`` path, because
every real BMad customize target nests ``persistent_facts`` under a
``[workflow]`` table (verified: ``.claude/skills/{bmad-prd,bmad-architecture,
bmad-create-epics-and-stories,ucg-create-story}/customize.toml``). The runtime
merge only lands an overlay's items in
``resolved['workflow']['persistent_facts']`` when the overlay nests them under
``[workflow]`` too; writing a TOP-LEVEL ``persistent_facts`` key would be a
dark write the live resolve silently ignores. The ``[ucg]`` stamp + manifest
stay TOP-LEVEL of the overlay — that is UCG bookkeeping the live resolve never
reads, and the tool finds its own stamp top-level.

The runtime merge engine is IMPORTED from the project's ``_bmad/scripts/``
(never reimplemented): ``deep_merge`` from ``resolve_customization.py`` on
BMAD releases before 6.11, which define it there, and ``structural_merge``
from ``config_utils.py`` on 6.11 and later, which moved it there and apply
it through ``load_customization``. Because ``persistent_facts`` is a flat
STRING array, that engine can only APPEND (``_merge_arrays`` keys-merges only
dict items with ``code``/``id``); therefore idempotency, anti-zombie,
uninstall and conflict are owned ENTIRELY by this tool's strip-then-reappend:
the engine is the appender the strip compensates for, never the enforcer.

Pre-merge shape probe (three branches):
  - target absent or empty ``{}`` → FRESH install: seed ``[workflow]`` with
    ``persistent_facts`` and merge (NOT a schema-mismatch);
  - target non-empty but does not expose ``workflow.persistent_facts`` (no
    ``[workflow]`` table, or ``[workflow]`` present but no ``persistent_facts``
    key under it) → fail-loud ``schema-mismatch`` SKIP, write nothing — never a
    dark write;
  - target exposes ``workflow.persistent_facts`` → merge.

Conflict detection: a UCG-stamped row whose content-hash no longer
matches the manifest is LEFT in place and reported in ``conflicts``, never
clobbered. Non-``[ucg:``-marked human rows are always preserved.

Exit codes (the merge-family lane, NOT the gate_eval lane):
  0 = success / skip / conflict
  1 = validation error (unparseable --target or --fragment TOML)
  2 = missing engine dependency (resolve_customization.py absent, or neither
      merge function importable from _bmad/scripts/)
"""

from __future__ import annotations

import argparse
import hashlib
import json
import re
import sys
import tomllib
from pathlib import Path

import tomli_w

# The single universal sanctioned landing channel the live customize schema
# exposes, nested under the [workflow] table in every real target. The
# fragment declares persistent_facts top-level; the tool lands it at
# workflow.persistent_facts so the live merge actually resolves it.
WORKFLOW_KEY = "workflow"
CHANNEL = "persistent_facts"

# The per-directive identity marker embedded in each UCG-owned fact string,
# e.g. "...steer the author. [ucg:bmad-prd-01]". A stable prefix the naive
# strip can find without parsing the whole sentence.
UCG_MARKER = re.compile(r"\[ucg:([a-z0-9-]+-\d+)\]")

STAMP_KEY = "ucg"
MANIFEST_KEY = "item_hashes"


def parse_args():
    parser = argparse.ArgumentParser(
        description=(
            "Stamp-scoped strip-then-reappend of a UCG-awareness fragment's "
            "persistent_facts into a BMad customize target, with a pre-merge "
            "shape probe and conflict detection."
        )
    )
    parser.add_argument(
        "--target",
        required=True,
        help="Path to the target customize TOML (e.g. _bmad/custom/bmad-prd.toml).",
    )
    parser.add_argument(
        "--fragment",
        help="Path to the UCG-awareness fragment TOML to merge (omit with --remove).",
    )
    parser.add_argument(
        "--remove",
        action="store_true",
        help="Uninstall: strip only [ucg:<id>]-marked rows and the [ucg] table.",
    )
    parser.add_argument(
        "--verbose",
        action="store_true",
        help="Print detailed progress to stderr.",
    )
    return parser.parse_args()


def _content_hash(text: str) -> str:
    """Stable content hash of a fact string (full string incl. its marker)."""
    return hashlib.sha256(text.encode("utf-8")).hexdigest()


def _marker_id(text: str) -> str | None:
    """The single [ucg:<id>] id embedded in a fact string, or None."""
    found = UCG_MARKER.findall(text)
    return found[0] if found else None


def _is_ucg_row(text: str) -> bool:
    return _marker_id(text) is not None


def _strip_ucg_rows(facts: list, keep_ids: set[str] | None = None) -> list:
    """Anti-zombie filter mirroring merge_help_csv.py:filter_rows.

    Remove every persistent_facts string carrying a [ucg:<id>] marker, except
    those whose id is in ``keep_ids`` (conflicted hand-edits, left in place).
    Non-string items and non-UCG human rows are always preserved.
    """
    keep_ids = keep_ids or set()
    kept = []
    for item in facts:
        if isinstance(item, str):
            marker = _marker_id(item)
            if marker is not None and marker not in keep_ids:
                continue
        kept.append(item)
    return kept


def _channel_exposed(data: dict) -> bool:
    """True iff the target exposes the nested workflow.persistent_facts channel
    (a [workflow] table carrying a persistent_facts key).
    """
    workflow = data.get(WORKFLOW_KEY)
    return isinstance(workflow, dict) and CHANNEL in workflow


def _get_channel(data: dict) -> list:
    """Return workflow.persistent_facts as a list (empty when absent)."""
    workflow = data.get(WORKFLOW_KEY)
    if not isinstance(workflow, dict):
        return []
    facts = workflow.get(CHANNEL)
    return list(facts) if isinstance(facts, list) else []


def _set_channel(data: dict, facts: list) -> None:
    """Write workflow.persistent_facts, creating the [workflow] table if needed
    (fresh-seed path). Mutates ``data`` in place.
    """
    workflow = data.get(WORKFLOW_KEY)
    if not isinstance(workflow, dict):
        workflow = {}
        data[WORKFLOW_KEY] = workflow
    workflow[CHANNEL] = facts


def _load_toml(path: Path) -> dict:
    """Parse a TOML file; raises tomllib.TOMLDecodeError on malformed input."""
    with path.open("rb") as fh:
        return tomllib.load(fh)


def _resolve_merge_engine(target_path: Path, verbose: bool):
    """Guarded import of the structural merge BMAD's resolver uses, from
    ``<project>/_bmad/scripts/`` relative to --target (which lives under
    ``_bmad/custom/``). Never define it locally.

    BMAD before 6.11 defines it in ``resolve_customization.py`` as
    ``deep_merge``. BMAD 6.11 moved it to ``config_utils.py`` as
    ``structural_merge``, which the resolver applies through
    ``load_customization``, so ``deep_merge`` no longer exists there. The
    resolver itself must be present either way: without it no BMAD skill
    reads the overlay this tool writes.

    Returns the imported callable, or None when the resolver is absent or
    neither function imports; the caller then takes the documented exit-2
    missing-dep path.
    """
    # --target == .../_bmad/custom/<name>.toml ; engine == .../_bmad/scripts/.
    custom_dir = target_path.resolve().parent  # _bmad/custom
    engine_dir = custom_dir.parent / "scripts"  # _bmad/scripts
    if not (engine_dir / "resolve_customization.py").is_file():
        if verbose:
            print(f"resolve_customization.py not found in {engine_dir}", file=sys.stderr)
        return None
    if str(engine_dir) not in sys.path:
        sys.path.insert(0, str(engine_dir))
    try:
        from resolve_customization import deep_merge  # noqa: WPS433 (guarded; BMAD before 6.11)

        return deep_merge
    except ImportError:
        pass
    try:
        from config_utils import structural_merge  # noqa: WPS433 (guarded; BMAD 6.11+)

        return structural_merge
    except ImportError:
        if verbose:
            print(
                f"neither resolve_customization.deep_merge nor "
                f"config_utils.structural_merge importable from {engine_dir}",
                file=sys.stderr,
            )
        return None


def _emit(result: dict) -> None:
    print(json.dumps(result, indent=2))


def main() -> None:
    args = parse_args()
    verbose = args.verbose
    target_path = Path(args.target)

    # --- Guarded engine import. Even --remove honors the
    # contract: the merge family always proves the engine is present, so an
    # absent engine is the exit-2 missing-dep signal regardless of operation.
    merge = _resolve_merge_engine(target_path, verbose)
    if merge is None:
        print(
            "warning: BMAD's customization merge engine not found in _bmad/scripts/ "
            "(resolve_customization.py, plus config_utils.py on BMAD 6.11 and later); "
            "writing nothing. Install BMAD's customization layer first.",
            file=sys.stderr,
        )
        sys.exit(2)

    # --- Single read of the target (no TOCTOU between probe and write).
    target_existed = target_path.exists()
    original_bytes = target_path.read_bytes() if target_existed else b""
    try:
        target_data = tomllib.loads(original_bytes.decode("utf-8")) if target_existed else {}
    except tomllib.TOMLDecodeError as error:
        print(f"Error: unparseable target TOML {target_path}: {error}", file=sys.stderr)
        sys.exit(1)

    # ----------------------------------------------------------------- remove
    if args.remove:
        _do_remove(target_path, target_data, target_existed, verbose)
        return

    # ------------------------------------------------------------------ merge
    if not args.fragment:
        print("Error: --fragment is required unless --remove is given", file=sys.stderr)
        sys.exit(1)

    fragment_path = Path(args.fragment)
    if not fragment_path.exists():
        print(f"Error: fragment not found at {fragment_path}", file=sys.stderr)
        sys.exit(1)
    try:
        fragment_data = _load_toml(fragment_path)
    except tomllib.TOMLDecodeError as error:
        print(f"Error: unparseable fragment TOML {fragment_path}: {error}", file=sys.stderr)
        sys.exit(1)

    # The fragment authors persistent_facts at TOP LEVEL; the
    # tool re-homes those items into the target's nested workflow channel.
    fragment_facts = fragment_data.get(CHANNEL, [])
    fragment_stamp = fragment_data.get(STAMP_KEY, {})

    # --- Pre-merge shape probe, three branches:
    #   1. absent/empty target  -> FRESH install: seed [workflow] and merge;
    #   2. non-empty but no workflow.persistent_facts -> schema-mismatch SKIP;
    #   3. exposes workflow.persistent_facts -> merge.
    is_fresh = not target_existed or not target_data
    if not is_fresh and not _channel_exposed(target_data):
        result = {
            "status": "skipped",
            "skipped": "schema-mismatch",
            "channel": f"{WORKFLOW_KEY}.{CHANNEL}",
            "target_path": str(target_path.resolve()),
            "rows_removed": 0,
            "rows_added": 0,
            "conflicts": [],
        }
        _emit(result)
        sys.exit(0)

    existing_facts = _get_channel(target_data)
    prior_stamp = target_data.get(STAMP_KEY, {})
    prior_manifest = {}
    if isinstance(prior_stamp, dict):
        prior_manifest = dict(prior_stamp.get(MANIFEST_KEY, {}) or {})

    # --- Conflict detection: a stamped row whose content-hash no longer
    # matches the manifest was hand-edited. Leave it in place (keep its id),
    # report the id, and do NOT re-append the fragment's version over it.
    conflicts: list[str] = []
    for item in existing_facts:
        if not isinstance(item, str):
            continue
        marker = _marker_id(item)
        if marker is None:
            continue  # human row, never a conflict
        recorded = prior_manifest.get(marker)
        if recorded is not None and recorded != _content_hash(item):
            conflicts.append(marker)
    conflicts = sorted(set(conflicts))
    conflict_set = set(conflicts)

    # --- Anti-zombie strip: remove every UCG-marked row EXCEPT the conflicted
    # ones we are leaving verbatim. Human rows pass through untouched.
    rows_before = sum(1 for item in existing_facts if isinstance(item, str) and _is_ucg_row(item))
    stripped_facts = _strip_ucg_rows(existing_facts, keep_ids=conflict_set)
    rows_removed = rows_before - len(conflict_set)

    # --- Re-append the fragment's items (each carrying its embedded marker),
    # skipping any id we are leaving as a conflicted hand-edit. The flat
    # string array is what the imported merge engine would itself APPEND
    # (its _merge_arrays); we drive it explicitly so the
    # idempotency comes from the strip above, not from the appender.
    appended: list[str] = []
    manifest: dict[str, str] = {}
    for fact in fragment_facts:
        if not isinstance(fact, str):
            continue
        marker = _marker_id(fact)
        if marker is None:
            continue
        if marker in conflict_set:
            # Preserve the human's hand-edit; record its (edited) hash so a
            # subsequent unchanged run sees no further conflict drift.
            for item in stripped_facts:
                if isinstance(item, str) and _marker_id(item) == marker:
                    manifest[marker] = _content_hash(item)
                    break
            continue
        appended.append(fact)
        manifest[marker] = _content_hash(fact)

    # Carry forward manifest hashes for conflicted rows already present but not
    # in the fragment (defensive; normally all conflicts are fragment ids).
    for marker in conflict_set:
        if marker not in manifest:
            for item in stripped_facts:
                if isinstance(item, str) and _marker_id(item) == marker:
                    manifest[marker] = _content_hash(item)
                    break

    merged_facts = stripped_facts + appended
    rows_added = len(appended)

    # --- Reconstruct the output dict deterministically: drive the engine for
    # the channel array (proving the engine is wired), then write exactly one
    # refreshed [ucg] stamp + manifest. Rebuilding from human content + a
    # fixed-order UCG block is what makes re-serialization byte-stable.
    # The channel lands NESTED at workflow.persistent_facts (seeding [workflow]
    # on a fresh target); the stamp + manifest stay top-level.
    merged = dict(target_data)
    if isinstance(merged.get(WORKFLOW_KEY), dict):
        merged[WORKFLOW_KEY] = dict(merged[WORKFLOW_KEY])  # don't mutate the read
    # engine append over empty base == identity (proves the engine is wired):
    _set_channel(merged, merge([], merged_facts))

    stamp = {
        "managed": True,
        "version": str(fragment_stamp.get("version", "")),
        "block": str(fragment_stamp.get("block", "ucg-awareness")),
        "installed_at": str(fragment_stamp.get("installed_at", "")),
        MANIFEST_KEY: {mid: manifest[mid] for mid in sorted(manifest)},
    }
    merged[STAMP_KEY] = stamp

    new_bytes = tomli_w.dumps(merged).encode("utf-8")
    target_path.parent.mkdir(parents=True, exist_ok=True)
    target_path.write_bytes(new_bytes)

    result = {
        "status": "conflict" if conflicts else "success",
        "target_path": str(target_path.resolve()),
        "target_existed": target_existed,
        "rows_removed": rows_removed,
        "rows_added": rows_added,
        "skipped": None,
        "conflicts": conflicts,
    }
    if verbose:
        print(
            f"stripped {rows_removed} UCG rows, appended {rows_added}, "
            f"conflicts={conflicts}",
            file=sys.stderr,
        )
    _emit(result)
    sys.exit(0)


def _do_remove(target_path: Path, target_data: dict, target_existed: bool, verbose: bool) -> None:
    """--remove: strip only [ucg:<id>]-marked rows from workflow.persistent_facts
    + delete the top-level [ucg] table, leaving every non-UCG item and human
    scalar/table byte-identical.

    TRUE no-op when there is nothing to remove: if the target carries neither a
    [ucg] stamp NOR any [ucg:<id>]-marked row, the file is NOT rewritten (bytes
    stay byte-identical, in==out), and an absent target is left absent (never
    created). 'Nothing to remove' is a clean success (exit 0, removed:0), per
    the merge exit-code lane (1=validation, 2=missing-dep only). A second
    consecutive --remove is therefore also a no-op.
    """
    existing_facts = _get_channel(target_data)
    rows_before = sum(1 for item in existing_facts if isinstance(item, str) and _is_ucg_row(item))
    has_stamp = isinstance(target_data.get(STAMP_KEY), dict)
    nothing_to_remove = rows_before == 0 and not has_stamp

    if nothing_to_remove:
        # Do NOT touch the file: no rewrite, no creation. Byte-identical no-op.
        if verbose:
            state = "absent" if not target_existed else "no UCG artifacts"
            print(f"--remove no-op: target has {state}; wrote nothing", file=sys.stderr)
        result = {
            "status": "success",
            "target_path": str(target_path.resolve()),
            "target_existed": target_existed,
            "rows_removed": 0,
            "rows_added": 0,
            "skipped": None,
            "conflicts": [],
        }
        _emit(result)
        sys.exit(0)

    merged = dict(target_data)
    if _channel_exposed(target_data):
        merged[WORKFLOW_KEY] = dict(merged[WORKFLOW_KEY])  # don't mutate the read
        _set_channel(merged, _strip_ucg_rows(existing_facts))
    merged.pop(STAMP_KEY, None)

    new_bytes = tomli_w.dumps(merged).encode("utf-8")
    target_path.parent.mkdir(parents=True, exist_ok=True)
    target_path.write_bytes(new_bytes)

    result = {
        "status": "success",
        "target_path": str(target_path.resolve()),
        "target_existed": target_existed,
        "rows_removed": rows_before,
        "rows_added": 0,
        "skipped": None,
        "conflicts": [],
    }
    if verbose:
        print(f"removed {rows_before} UCG rows + [ucg] stamp", file=sys.stderr)
    _emit(result)
    sys.exit(0)


if __name__ == "__main__":
    main()
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