Skip to content

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

ultracode-goal

Unverified

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.mdmarkdown120.0 KB
references/finalize.mdmarkdown39.3 KB
references/gate.mdmarkdown143.7 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.2 KB
scripts/formalize_check.pyscript87.5 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.pyscript28.6 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.pyscript18.6 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/health_check_fp.py

View on GitHub
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""Deterministic fingerprint, seen-cache and queue plumbing for the ultracode-goal health check.

Plumbing ONLY. This script computes the dedup fingerprints of a health-check
finding (turning a section heading into its slug and a defect name into its
key) with the issue title and the machine-read top of the issue body, reads
the machine-local seen-cache into a verdict (asking GitHub for a recorded
issue's state through `gh`, bounded) with the line a regression's body opens
with, merge-writes a record under a lock, splits the configured repository
into the host it names, as gh reads it (github.com for OWNER/REPO), and its
OWNER/REPO, and writes a drafted body into the local queue under a free name
with the commands that submit it. It
makes NO submit/queue/route decision: that judgment lives in
references/health-check.md (the LLM), as do the severity, the section and the
defect name it is given.

The fingerprint is install-mode-invariant: the `step_file` component is ALWAYS
the source-repo form `skills/ultracode-goal/references/{stage}.md` regardless of
where the skill is installed, so the same defect dedups to the same key across a
dev checkout and an installed `_bmad/` tree.

    fp        = "fp-" + sha1("{severity}|ultracode-goal/{stage}|"
                             "skills/ultracode-goal/references/{stage}.md|"
                             "{section-slug}|{defect-key}")[:7]
    legacy_fp = the same hash without "|{defect-key}": the section fingerprint,
                which every defect of one severity in one section shares, and
                the fingerprint versions without the defect key filed under

Subcommands:
  fingerprint --severity S --stage T
              (--section-slug SLUG | --stdin) (--defect-key KEY | --stdin)
      Validate S against the 3 severities and T against the 7 stages (the six
      run stages and `health-check`, the health check's own). The
      section comes from --section-slug or from `section_heading` in the JSON
      object --stdin reads, never both; the defect from --defect-key or from
      that object's `defect_name`, never both. Without --stdin both flags are
      required (an argparse usage error, exit 2); with it, a pair given twice
      or not at all, a key other than those two and `short_description`, or
      a value that is not a non-empty string exits 1. The two flags stay for
      tests and old calls: --section-slug skips the check that the heading is
      one of the stage file's own, and without --stdin the flags print a null
      title, regression_title and body_header.
        section_heading: must equal, after its leading `#`s, the text of an
          ATX heading line of references/{T}.md beside this script (outside
          fenced code and the frontmatter). Its slug: drop the leading `#`s,
          fold it (NFKD, the compatibility decomposition, then drop the
          combining marks: an accented letter gives its base letter, and a
          ligature, a superscript or a full-width form its plain characters;
          a letter NFKD cannot split, such as `ß`, `ø`, `ł`, `æ`, `œ` or `ı`,
          stays, so it becomes a hyphen below), drop a leading numbering token (`1b.`,
          `5a-ii.`, `4-headless.`), lower-case, turn each run of characters
          that are not ASCII letters or digits into `-`, and trim hyphens.
        defect_name: fold it as a heading is; drop whitespace and the edge
          characters (_NAME_EDGES: backticks, straight and curly quotes, `*`,
          `()[]{}<>`, `.`, `,`, `;`, `!` and `?`) from both ends, in any
          layering; keep its last path component (after `/` or `\\`); drop a
          trailing location (_NAME_LOCATION_RE): a `:N`, then up to two more
          `-N` or `:N`, then an optional `:` or `-` (`:42`, `:42-50`,
          `:42:7:`, `:42:7-12`, `:42-`); a lone `:`; or a GitHub anchor, an
          optional `?plain=1`, then `#L42`, an optional column `C7` and an
          optional range `-L50`, `-L50C3` or `-50` (`#L42`, `#L42-L50`,
          `#L42C7-L50C3`, `?plain=1#L42`); drop whitespace and the edge
          characters from both ends again, and repeat the location and the
          edges until the name stops changing (`` `gate_eval.py:42`: `` gives
          `gate-eval`); drop a known file extension (KNOWN_EXTENSIONS) and
          then leading dashes and underscores; split at whitespace, `_`, `-`,
          `.` and each lower-case letter followed by an upper-case one; drop
          each character that is not an ASCII letter or digit; lower-case;
          keep the last four words, joined by `-`. A name that yields no word
          (one written in another alphabet included) exits 1.
        short_description: optional; the issue title's description. It
          exits 1 when it holds a backtick, `$`, a double quote, a backslash,
          `!` or a character that is not printable (a tab, a line break, NUL,
          U+2028 and the like), since the title goes on a command line inside
          double quotes, or when it makes regression_title longer than 256
          characters (TITLE_MAX, GitHub's limit); surrounding whitespace is
          dropped.
      A given SLUG must be kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$) and a given
      KEY one to four kebab-case words (^[a-z0-9]+(-[a-z0-9]+){0,3}$). Emit
      {"fp", "legacy_fp", "tuple", "section_slug", "defect_key", "title",
      "regression_title", "body_header"}, where `tuple` is the exact sha1
      input of `fp` and, with a short_description D (all three null
      without one):
        title:            [health-check][S][fp] ultracode-goal/T: D
        regression_title: [health-check][S][fp] ultracode-goal/T: REGRESSION: D
        body_header:      the machine-read top of the issue body, the
          `## Workflow`, `## Step File`, `## Section`, `## Severity`,
          `## Fingerprint` (`fp` alone on its line, then the line
          "Section fingerprint: `legacy_fp`") and `## Defect Key` sections,
          each value in backticks, ending in a newline.
      The JSON is printed in UTF-8, a non-ASCII character as itself.
  seen --fp FP --legacy-fp FP --cache PATH [--repo REPO]
      Validate both fingerprints, and REPO as [HOST/]OWNER/REPO (exit 1).
      Emit {"seen": B, "status": S, "record": R, "matched_on": M,
      "opening_line": L}. With --repo, a record with an empty or no
      issue_url, or that is not an object, names no repository and counts as
      without --repo; any other record whose issue_url is not a string under
      https://github.com/OWNER/REPO/ (https://HOST/OWNER/REPO/ for a REPO that
      names a host, HOST normalised as `repo` prints it, so
      www.github.com/OWNER/REPO reads github.com's URLs), compared in any
      letter case, counts as no record, under
      either fingerprint: another repository's issue, a URL that is not
      https:// or one that is not a string alike. The record under --fp
      decides; only when the cache has no --fp key does the record under
      --legacy-fp decide (M is "fp", "legacy_fp", or null when neither is
      there). On the record found, the first branch that matches gives the
      status:
        1. no record under either fingerprint: unseen
        2. action `resolved`: regression
        3. action created, reacted or commented with an issue_url: the
           issue's own state decides, read with
           `gh issue view <issue_url> --json state,stateReason`, stopped after
           10 seconds (GH_TIMEOUT_SEC) with every process it started. CLOSED
           with stateReason COMPLETED, or MERGED (a resolving pull request), is
           regression; every other answer (OPEN, a NOT_PLANNED close) and every
           failure (no gh, the time limit, a non-zero exit, output that is not
           that JSON) is handled. gh runs only for an issue_url that starts
           with https:// and holds no whitespace (any other value is handled
           without a call), is never one found in the current folder, and
           never runs through a shell.
        4. one of those three actions with no issue_url: handled
        5. no action, any other action (an old `queued` included), or a
           record that is not an object: unrecognized
      A record found only under --legacy-fp may be another defect's, so
      handled becomes unseen (a legacy record never suppresses) and
      regression becomes possible-regression; unrecognized stays.
      `seen` is the SUPPRESSION verdict, true for handled alone: every
      uncertain verdict reports. Missing/empty/corrupt cache -> unseen.
      L is the line that opens the issue body, null for unseen, handled and
      unrecognized; U is the record's issue_url when it starts with https://
      and holds no whitespace, D its date when that has the YYYY-MM-DD shape
      (else "on an unrecorded date"), and P, after a possible-regression,
      ": that report's fingerprint has no defect key, so it may be another
      defect in this section". From a `resolved` record, whose date is the
      fix's:
        regression, with U:           Regression of U (resolved D).
        regression, without:          Regression of a previously resolved
                                      local finding (resolved D).
        possible-regression, with U:  Possibly a regression of U (resolved D)P.
        possible-regression, without: Possibly a regression of a previously
                                      resolved local finding in this section
                                      (resolved D).
      From branch 3, whose record dates the report, not the fix:
        a completed close:            Regression of U, closed as completed
                                      since its report on D. (Possibly a
                                      regression ... D P. after a legacy record)
        a merge:                      the same with "merged" for "closed as
                                      completed".
  repo --repo REPO
      Validate REPO as [HOST/]OWNER/REPO (exit 1) and split it into the
      host it names, as gh reads it (github.com for OWNER/REPO), and its
      OWNER/REPO. Emit {"repo", "host", "owner_repo", "host_flag",
      "is_default"}:
        repo        REPO as written
        host        the HOST REPO names, normalised as gh normalises a
                    hostname (one leading lower-case `www.` dropped, so
                    www.WWW.example.com is www.example.com while
                    WWW.example.com keeps its `www.`; then lower case, any
                    *.github.com is github.com, any *.github.localhost is
                    github.localhost, a *.ghe.com name is its tenant's:
                    api.octo.ghe.com is octo.ghe.com), else github.com
                    (DEFAULT_HOST). A HOST the trim leaves empty
                    (www./OWNER/REPO) names no host, as gh reads it. The step
                    links the issue form on it, and `seen --repo` reads issue
                    URLs under it
        owner_repo  REPO without its host, the OWNER/REPO of a `gh api` path
        host_flag   `--hostname HOST` when REPO names a host (not for
                    www./OWNER/REPO), else "". `gh api` takes no --repo:
                    with it, it reaches the host every --repo call reaches,
                    the named one, or gh's default (GH_HOST, or the host gh
                    is logged in to) for OWNER/REPO. `gh auth status` checks
                    the named host alone with it, and every host gh knows
                    without it
        is_default  host is DEFAULT_HOST and owner_repo is DEFAULT_REPO in any
                    letter case
  record --fp FP --cache PATH --issue-url URL --action A --date YYYY-MM-DD
         [--regression]
      Validate FP; A is created, reacted or commented with an https:// URL
      holding no whitespace, or resolved with such a URL or an empty one; the
      date is a real YYYY-MM-DD date. Set the --fp key alone to
      {"issue_url", "action", "date"} and keep every other key. A
      `defect_slug` the replaced record carries is carried over. A `resolved`
      record is never downgraded: without --regression, any other action
      leaves it as it is and emits "written": false (exit 0). The read, merge
      and write hold an OS lock on <cache>.lock (fcntl.flock, or
      msvcrt.locking on Windows), waited on for up to 10 seconds
      (LOCK_WAIT_SEC); the lock file is never deleted. The new file is
      written beside the cache, synced to disk and renamed over it. A cache
      that exists and is not a JSON object is first renamed to
      <cache>.corrupt-<UTC YYYYMMDDTHHMMSSZ> (then -2, -3 in the same second),
      so its records can be repaired by hand; when that rename fails, nothing
      is written. Emit {"written": B, "fp": FP, "record": <what the cache now
      holds under FP>, "set_aside": <the renamed corrupt cache> | null}.
  version --project-root PATH
      The version of the UltraCode Goal this script belongs to, never the
      user's project's: emit {"version": V, "source": S}, or {"version": null,
      "source": "N/A"} when no rung gives one (exit 0). UCG's own root is the
      folder three levels above this script's (UCG_ROOT: a checkout's or a
      plugin's root), and there is none when the script sits fewer than four
      folders deep. The first rung that gives a non-empty version wins; a file
      that is missing, unreadable or malformed, or that names another package,
      falls through to the next:
        1. UCG_ROOT/.claude-plugin/marketplace.json: the version of its
           `plugins` entry named bmad-module-ultracode-goal (PACKAGE_NAME)
                                       -> ".claude-plugin/marketplace.json"
        2. UCG_ROOT/package.json, when its name is PACKAGE_NAME: its version
                                       -> "package.json"
        3. <project-root>/_bmad/ucg/VERSION, which only UCG's CLI installer
           writes, for the copy it installs under .claude/skills/, which has
           no root of its own (plain text)
                                       -> "_bmad/ucg/VERSION"
      UCG's root comes first, so a stale _bmad/ucg/VERSION never masks it.
  queue --queue-dir DIR --body-file F --title TITLE --repo REPO
      Read F (a missing or unreadable F exits 1 and creates nothing). F
      opens with the body_header `fingerprint` prints (after a UTF-8 BOM and
      at most one opening line and a blank line, its line endings LF or
      CRLF), from which the stage T, the severity S and the fingerprint FP
      are read. Each of these exits 1 and creates nothing: F opening with no
      such header; a TITLE that does not start with
      `[health-check][S][FP] ultracode-goal/T: `
      (the title `fingerprint` printed for another finding), is longer than
      TITLE_MAX or holds a character `fingerprint` refuses in a description;
      a REPO that is not [HOST/]OWNER/REPO. Create DIR when absent and write
      F's bytes, unchanged and with no frontmatter, to
      DIR/hc-ultracode-goal-{T}-{UTC YYYYMMDD-HHmmss}.md, opened with
      O_CREAT|O_EXCL so no file is ever overwritten: a taken name gets -2, -3
      and so on before `.md`. Emit {"path": P, "commands": [L, C, B]}, P
      being the absolute path written and L, C and B the commands that submit
      it: the label create and the create, run in that order (a failed L, the
      label there already or no push access, is no error), and B, the create
      without labels, for a reporter without push access to run alone:
        L: gh label create --repo REPO FP --color ededed
             --description 'Health-check fingerprint dedup key'
        C: gh issue create --repo REPO --title TITLE
             --label health-check,workflow-improvement,S,FP --body-file P
        B: gh issue create --repo REPO --title TITLE --body-file P
      each on one line, every argument quoted for a POSIX shell
      (shlex.quote), so a space or a quote in TITLE or P reaches gh as
      written, and `--repo` right after the subcommand, so an allow rule
      scoped to the repository matches. The JSON is printed in UTF-8, a
      non-ASCII character as itself.

Output: JSON to stdout. Errors are JSON to stdout with exit code 1 (operational
failure, a value that breaks its rule, or a record that could not take the lock,
set a corrupt cache aside or write); argparse usage errors exit 2. A successful
payload exits 0.
"""

from __future__ import annotations

import argparse
import errno
import hashlib
import json
import os
import re
import shlex
import shutil
import signal
import subprocess
import sys
import tempfile
import time
import unicodedata
from datetime import date, datetime, timezone
from pathlib import Path

if os.name == "nt":
    import msvcrt
else:
    import fcntl

SEVERITIES = ("bug", "friction", "gap")
STAGES = (
    "ingest-and-scope",
    "preflight",
    "define-done",
    "execute",
    "gate",
    "finalize",
    # The health check's own stage reference, for a defect in its own
    # instructions (references/health-check.md routes it to the local queue only).
    "health-check",
)
ACTIONS = ("created", "reacted", "commented", "resolved")

# Which recorded actions SUPPRESS a later sighting of the same fingerprint.
# Deliberately a literal tuple and NOT `ACTIONS` minus `resolved`: a disposition
# added later then defaults to NOT suppressing until it is opted in here, and a
# missing or unrecognized action (a hand-edited cache, an old `queued` record,
# or one written by a newer module) does not suppress either. That is the
# fail-closed direction for a health check: a duplicate report is closed by the
# dedup Action, while a silenced regression is caught by nothing. When in
# doubt, report.
SUPPRESSING_ACTIONS = ("created", "reacted", "commented")
RESOLVED = "resolved"

# Each rule is matched with fullmatch, so a value ending in a newline fails it.
SLUG_RE = re.compile(r"[a-z0-9]+(-[a-z0-9]+)*")
DEFECT_KEY_RE = re.compile(r"[a-z0-9]+(-[a-z0-9]+){0,3}")
FP_RE = re.compile(r"fp-[0-9a-f]{7}")
DATE_RE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")
URL_PREFIX = "https://"
# The host the script reads an OWNER/REPO value as on, for the issue-form link and the seen cache's issue URLs.
DEFAULT_HOST = "github.com"
# The domain of GitHub Enterprise Cloud tenants with data residency (TENANT.ghe.com), which gh normalises to the tenant.
GHE_COM = "ghe.com"
# The host of a GitHub development instance, which gh normalises any *.github.localhost to.
GITHUB_LOCALHOST = "github.localhost"

# The stage references a section_heading is looked up in: the skill's own
# references/ folder, beside scripts/, wherever the skill is installed.
REFERENCES_DIR = Path(__file__).resolve().parent.parent / "references"
# The root of the UltraCode Goal this script belongs to, a checkout's or a plugin's: the folder above skills/, three
# levels above this script's. None when the script sits fewer than four folders deep. `version` reads it at call time,
# so a test can point it elsewhere.
_PARENTS = Path(__file__).resolve().parents
UCG_ROOT = _PARENTS[3] if len(_PARENTS) > 3 else None
# The name UCG's package.json and its marketplace's plugin entry carry: a file at UCG_ROOT that names another package
# (the user's project, when UCG_ROOT is not UCG's) gives no version.
PACKAGE_NAME = "bmad-module-ultracode-goal"
# An ATX heading line: up to three spaces, one to six `#`, then its text.
_HEADING_LINE_RE = re.compile(r" {0,3}(#{1,6})(?:[ \t]+(.*?))?[ \t]*")
# The optional closing sequence of an ATX heading (`## Title ##`).
_HEADING_CLOSE_RE = re.compile(r"(?:^|[ \t]+)#+$")
# A fence line opens or closes a fenced code block, whose `#` lines are no headings.
_FENCE_RE = re.compile(r" {0,3}(`{3,}|~{3,})")
# A leading numbering token: `1.`, `1b.`, `0.5.`, `5a-ii.`, `4-headless.`.
_NUMBERING_RE = re.compile(r"[0-9][0-9A-Za-z]*(?:[.-][0-9A-Za-z]+)*\.\s+")
_NOT_SLUG_RE = re.compile(r"[^a-z0-9]+")

# The file extensions a defect name drops: `gate_eval.py` names the script `gate-eval`.
KNOWN_EXTENSIONS = (
    ".py", ".md", ".json", ".yaml", ".yml", ".toml", ".js", ".cjs", ".mjs", ".ts", ".sh", ".csv", ".txt",
)
_PATH_SEP_RE = re.compile(r"[/\\]")
# What a name copied from Markdown, a log or a compiler may be wrapped in or end with, besides whitespace: backticks,
# straight and curly quotes, emphasis, brackets and sentence punctuation.
_NAME_EDGES = "`'\"\u2018\u2019\u201c\u201d*()[]{}<>.,;!?"
# A location after the name: `:42`, then up to two more `-N` or `:N`, then an optional `:` or `-` (`:42-50`, `:42:7`,
# `:42:7:`, `:42:7-12`, `:42-`); a lone `:`; or a GitHub anchor, an optional `?plain=1` then `#L42`, an optional
# column `C7` and an optional range `-L50`, `-L50C3` or `-50`. Its repetition is bounded, so a try at one position
# reads no more than three numbers.
_NAME_LOCATION_RE = re.compile(
    r"(?::(?:[0-9]+(?:[-:][0-9]+){0,2}[:-]?)?"
    r"|(?:\?plain=1)?#L[0-9]+(?:C[0-9]+)?(?:-(?:L[0-9]+(?:C[0-9]+)?|[0-9]+))?)\Z"
)
# The most characters that are not digits a location holds (`?plain=1#L42C7-L50C3`), so the one a name ends with
# starts no further back than its last this many: the search for it starts there, whatever the name's length.
_NAME_LOCATION_NON_DIGITS = 13
_DIGITS = "0123456789"
_NAME_SPLIT_RE = re.compile(r"[\s_.-]+")
_CASE_BOUNDARY_RE = re.compile(r"(?<=[a-z])(?=[A-Z])")
_NOT_ALNUM_RE = re.compile(r"[^A-Za-z0-9]")
DEFECT_KEY_WORDS = 4
STDIN_KEYS = ("section_heading", "defect_name", "short_description")
# What a title may not hold besides a character that is not printable (a tab, a line break, NUL, U+2028): it goes
# on a command line inside double quotes, where each of these is special (`!` to an interactive shell's history).
TITLE_UNSAFE = "`$\"\\!"
# GitHub refuses an issue title longer than this many characters.
TITLE_MAX = 256
# The record date an opening line names when the record holds no YYYY-MM-DD date.
UNRECORDED_DATE = "on an unrecorded date"

QUEUE_STAMP_FORMAT = "%Y%m%d-%H%M%S"
# What every health-check issue is filed with besides its severity and fingerprint labels, and the fp-* label's
# look as the health check creates it (the dedup Action creates it the same way).
ISSUE_LABELS = ("health-check", "workflow-improvement")
FP_LABEL_COLOR = "ededed"
FP_LABEL_DESCRIPTION = "Health-check fingerprint dedup key"
# The start of a draft: at most one opening line (a regression's) and a blank line, then the body_header
# `fingerprint` prints, its line endings LF or CRLF.
_DRAFT_HEADER_RE = re.compile(
    r"(?:[^\r\n]+\r?\n\r?\n)?"
    r"## Workflow\r?\n`ultracode-goal/(?P<stage>" + "|".join(STAGES) + r")`\r?\n\r?\n"
    r"## Step File\r?\n`skills/ultracode-goal/references/(?P=stage)\.md`\r?\n\r?\n"
    r"## Section\r?\n`[^`\r\n]+`\r?\n\r?\n"
    r"## Severity\r?\n`(?P<severity>" + "|".join(SEVERITIES) + r")`\r?\n\r?\n"
    r"## Fingerprint\r?\n`(?P<fp>fp-[0-9a-f]{7})`\r?\n\r?\n"
    r"Section fingerprint: `fp-[0-9a-f]{7}`\r?\n\r?\n"
    r"## Defect Key\r?\n`[^`\r\n]+`(?:\r?\n|\Z)"
)
# A repository as gh takes it: [HOST/]OWNER/REPO.
REPO_RE = re.compile(r"(?:[A-Za-z0-9][A-Za-z0-9.-]*/)?[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9._-]+")
# The health_check_repo customize.toml ships: its issues are public, which the step's gate says.
DEFAULT_REPO = "armelhbobdad/bmad-module-ultracode-goal"

GH_TIMEOUT_SEC = 10.0
KILL_WAIT_SEC = 2.0  # each wait once the time limit stops gh: SIGTERM or taskkill, then the child
LOCK_WAIT_SEC = 10.0
_LOCK_POLL_MIN_SEC = 0.01
_LOCK_POLL_MAX_SEC = 0.2
CORRUPT_STAMP_FORMAT = "%Y%m%dT%H%M%SZ"
# Windows refuses to rename over a file another process has open (a `seen`
# reading the cache, a virus scanner); the rename is retried for this long.
_IS_WINDOWS = os.name == "nt"
_REPLACE_WAIT_SECONDS = 5.0
_REPLACE_POLL_SECONDS = 0.02


class _WriteError(Exception):
    """record could not read the cache, set a corrupt one aside or write it."""


class _LockBusy(Exception):
    """Another record call held <cache>.lock for the whole wait."""


def _fail(message: str) -> int:
    print(json.dumps({"error": message}))
    return 1


def _repo_error(repo: str) -> str | None:
    """The rule a --repo value breaks, or None: gh takes [HOST/]OWNER/REPO."""
    if REPO_RE.fullmatch(repo):
        return None
    return "invalid repo %r; expected [HOST/]OWNER/REPO" % repo


def _normalize_host(host: str) -> str:
    """host as gh normalises a hostname before it uses one: one leading lower-case `www.` dropped (www.WWW.example.com
    is www.example.com, while WWW.example.com keeps its `www.`), then lower case, any *.github.com is github.com, any
    *.github.localhost is github.localhost, and a *.ghe.com name is its tenant's (api.octo.ghe.com is octo.ghe.com).
    `--repo` normalises its host this way; `--hostname` does not, so the step is given the normalised one. A host the
    trim leaves empty (`www.`) gives "", which names no host."""
    host = host.removeprefix("www.").lower()
    if host.endswith("." + DEFAULT_HOST):
        return DEFAULT_HOST
    if host.endswith("." + GITHUB_LOCALHOST):
        return GITHUB_LOCALHOST
    if host.endswith("." + GHE_COM):
        return ".".join(host.split(".")[-3:])
    return host


def _named_host(repo: str) -> str | None:
    """The host repo names, normalised as gh does, or None when it names none: an OWNER/REPO value, or one whose host
    the `www.` trim leaves empty (`www./OWNER/REPO`), which gh reads as OWNER/REPO on its default host."""
    if repo.count("/") != 2:
        return None
    return _normalize_host(repo.split("/", 1)[0]) or None


def split_repo(repo: str) -> tuple[str, str]:
    """(HOST, OWNER/REPO) of repo, which REPO_RE has accepted: the host it names, normalised as gh does, else
    DEFAULT_HOST."""
    owner_repo = repo.split("/", 1)[1] if repo.count("/") == 2 else repo
    return _named_host(repo) or DEFAULT_HOST, owner_repo


def _sha7(text: str) -> str:
    return hashlib.sha1(text.encode("utf-8")).hexdigest()[:7]


def _compute_fp(severity: str, stage: str, slug: str, defect_key: str) -> tuple[str, str, str]:
    """Return (fp, legacy_fp, tuple_string). The tuple string is fp's exact sha1 input."""
    step_file = f"skills/ultracode-goal/references/{stage}.md"
    legacy = f"{severity}|ultracode-goal/{stage}|{step_file}|{slug}"
    keyed = f"{legacy}|{defect_key}"
    return f"fp-{_sha7(keyed)}", f"fp-{_sha7(legacy)}", keyed


def _heading_text(text: str) -> str:
    """A heading's text: no leading `#`s, no ATX closing sequence, single spaces."""
    text = text.strip().lstrip("#")
    text = _HEADING_CLOSE_RE.sub("", text.strip())
    return " ".join(text.split())


def _stage_headings(stage_file: Path) -> list[str]:
    """The text of every ATX heading line of stage_file, outside its frontmatter and fenced code.

    Raises OSError when the file cannot be read.
    """
    lines = stage_file.read_text(encoding="utf-8-sig").splitlines()
    start = 0
    if lines and lines[0].strip() == "---":
        for i in range(1, len(lines)):
            if lines[i].strip() == "---":
                start = i + 1
                break
    headings = []
    fence = None
    for line in lines[start:]:
        run = _FENCE_RE.match(line)
        if fence is not None:
            # Only a run of the same character, at least as long and alone on its line, closes it.
            closes = run and run.group(1)[0] == fence[0] and len(run.group(1)) >= len(fence)
            if closes and not line.strip().strip(fence[0]):
                fence = None
            continue
        if run:
            fence = run.group(1)
        elif _HEADING_LINE_RE.fullmatch(line):
            headings.append(_heading_text(line))
    return headings


def _fold(text: str) -> str:
    """NFKD, then no combining mark: an accented letter gives its base letter, a ligature or a superscript its plain
    characters. A letter NFKD cannot split (`ß`, `ø`, `ł`, `æ`, `œ`, `ı`) stays as it is."""
    return "".join(ch for ch in unicodedata.normalize("NFKD", text) if not unicodedata.combining(ch))


def section_slug(heading: str) -> str:
    """The slug rule: no leading `#`s, folded, no numbering token, lower-case, one `-` per run of others."""
    text = _fold(_heading_text(heading))  # folded first, as a name is, so `1.` is the numbering `1.`
    numbering = _NUMBERING_RE.match(text)
    if numbering:
        text = text[numbering.end():]
    return _NOT_SLUG_RE.sub("-", text.lower()).strip("-")


def _edge_bounds(text: str, begin: int, end: int) -> tuple[int, int]:
    """text[begin:end]'s bounds once the whitespace and _NAME_EDGES at either end are gone, in any layering."""
    while begin < end and (text[begin].isspace() or text[begin] in _NAME_EDGES):
        begin += 1
    while end > begin and (text[end - 1].isspace() or text[end - 1] in _NAME_EDGES):
        end -= 1
    return begin, end


def _location_start(text: str, begin: int, end: int) -> int:
    """Where the location text[begin:end] ends with starts (_NAME_LOCATION_RE); end when it ends with none."""
    start, non_digits = end, 0
    while start > begin and (text[start - 1] in _DIGITS or non_digits < _NAME_LOCATION_NON_DIGITS):
        non_digits += text[start - 1] not in _DIGITS
        start -= 1
    location = _NAME_LOCATION_RE.search(text, start, end)
    return location.start() if location else end


def defect_key(name: str) -> str:
    """The defect-key rule; an empty string when the name yields no word."""
    text = _fold(name)
    begin, end = _edge_bounds(text, 0, len(text))  # `gate_eval.py` in backticks, quotes, `**`, brackets or a sentence
    text = _PATH_SEP_RE.split(text[begin:end])[-1]  # `scripts/gate_eval.py` names `gate_eval.py`
    # `gate_eval.py:42:7:` and `gate_eval.py#L42` name it too, and `` `gate_eval.py:42`: `` sheds its `:`, its backtick,
    # then its `:42`: drop a location, then the edges, until neither drops anything. Each round looks back no further
    # than a location reaches and moves bounds instead of copying, so the whole takes time linear in the name's length.
    begin, end = 0, len(text)
    while True:
        bounds = _edge_bounds(text, begin, _location_start(text, begin, end))
        if bounds == (begin, end):
            break
        begin, end = bounds
    text = text[begin:end]
    for ext in KNOWN_EXTENSIONS:
        if text.lower().endswith(ext) and len(text) > len(ext):
            text = text[: -len(ext)]
            break
    text = text.lstrip("-_")
    words = []
    for part in _NAME_SPLIT_RE.split(text):
        for piece in _CASE_BOUNDARY_RE.split(part):
            word = _NOT_ALNUM_RE.sub("", piece).lower()
            if word:
                words.append(word)
    return "-".join(words[-DEFECT_KEY_WORDS:])


def _title_unsafe(text: str) -> bool:
    """True when text holds a character a title on a command line may not: TITLE_UNSAFE, or one not printable."""
    return any(ch in TITLE_UNSAFE or not ch.isprintable() for ch in text)


def _read_stdin_names() -> tuple[dict | None, str | None]:
    """The JSON object --stdin reads, or the rule it breaks.

    Read as UTF-8 bytes, so a heading's non-ASCII character survives whatever
    the locale is.
    """
    raw = getattr(sys.stdin, "buffer", None)
    try:
        text = raw.read().decode("utf-8-sig") if raw is not None else sys.stdin.read()
        data = json.loads(text)
    except (OSError, ValueError, RecursionError):  # UnicodeDecodeError is a ValueError
        return None, "--stdin did not read a JSON object"
    if not isinstance(data, dict):
        return None, "--stdin did not read a JSON object"
    unknown = sorted(set(data) - set(STDIN_KEYS))
    if unknown:
        return None, "unknown --stdin key(s) %s; expected only %s and %s" % (
            ", ".join(map(repr, unknown)),
            ", ".join(STDIN_KEYS[:-1]),
            STDIN_KEYS[-1],
        )
    for key, value in data.items():
        if not isinstance(value, str) or not value.strip():
            return None, "--stdin %s must be a non-empty string" % key
    if _title_unsafe(data.get("short_description", "")):
        return None, (
            "--stdin short_description %r holds a backtick, `$`, double quote, backslash, `!` or a character that is "
            "not printable (a tab or a line break included); the title goes on a command line, so it may hold none"
            % data["short_description"]
        )
    return data, None


def _one_of(flag: str, flag_value: str | None, key: str, names: dict) -> str | None:
    """The rule a section or defect pair breaks: given twice, or not at all."""
    if flag_value is not None and key in names:
        return "give %s or a --stdin %s, not both" % (flag, key)
    if flag_value is None and key not in names:
        return "give %s or a --stdin %s" % (flag, key)
    return None


def cmd_fingerprint(args: argparse.Namespace) -> int:
    if args.severity not in SEVERITIES:
        return _fail(
            "invalid severity %r; expected one of %s"
            % (args.severity, ", ".join(SEVERITIES))
        )
    if args.stage not in STAGES:
        return _fail(
            "invalid stage %r; expected one of %s" % (args.stage, ", ".join(STAGES))
        )

    names: dict = {}
    if args.stdin:
        names, problem = _read_stdin_names()
        if problem:
            return _fail(problem)
        problem = _one_of("--section-slug", args.section_slug, "section_heading", names) or _one_of(
            "--defect-key", args.defect_key, "defect_name", names
        )
        if problem:
            return _fail(problem)

    slug = args.section_slug
    if "section_heading" in names:
        heading = names["section_heading"]
        stage_file = REFERENCES_DIR / f"{args.stage}.md"
        try:
            headings = _stage_headings(stage_file)
        except (OSError, UnicodeDecodeError) as exc:
            return _fail("could not read %s: %s" % (stage_file, exc))
        if _heading_text(heading) not in headings:
            return _fail(
                "section_heading %r is no heading of references/%s.md; copy a heading line of that file"
                % (heading, args.stage)
            )
        slug = section_slug(heading)
        if not slug:
            return _fail("section_heading %r yields no slug" % heading)
    elif not SLUG_RE.fullmatch(slug):
        return _fail(
            "invalid section-slug %r; expected kebab-case ^[a-z0-9]+(-[a-z0-9]+)*$" % slug
        )

    key = args.defect_key
    if "defect_name" in names:
        key = defect_key(names["defect_name"])
        if not key:
            return _fail("defect_name %r yields no word" % names["defect_name"])
    elif not DEFECT_KEY_RE.fullmatch(key):
        return _fail(
            "invalid defect-key %r; expected one to four kebab-case words "
            "^[a-z0-9]+(-[a-z0-9]+){0,3}$" % key
        )

    fp, legacy_fp, tuple_str = _compute_fp(args.severity, args.stage, slug, key)
    title = regression_title = header = None
    if "short_description" in names:
        description = names["short_description"].strip()
        prefix = f"[health-check][{args.severity}][{fp}] ultracode-goal/{args.stage}: "
        title = prefix + description
        regression_title = prefix + "REGRESSION: " + description
        if len(regression_title) > TITLE_MAX:
            return _fail(
                "short_description makes the regression title %d characters long; GitHub takes at most %d, so "
                "shorten it by %d" % (len(regression_title), TITLE_MAX, len(regression_title) - TITLE_MAX)
            )
        header = body_header(args.severity, args.stage, slug, key, fp, legacy_fp)
    _print_utf8(
        {
            "fp": fp,
            "legacy_fp": legacy_fp,
            "tuple": tuple_str,
            "section_slug": slug,
            "defect_key": key,
            "title": title,
            "regression_title": regression_title,
            "body_header": header,
        }
    )
    return 0


def _print_utf8(payload: dict) -> None:
    """Print payload as JSON in UTF-8 whatever the locale, non-ASCII as itself: the title is used as printed."""
    text = json.dumps(payload, ensure_ascii=False) + "\n"
    out = getattr(sys.stdout, "buffer", None)
    if out is None:
        sys.stdout.write(text)
        return
    sys.stdout.flush()
    out.write(text.encode("utf-8"))
    out.flush()


def body_header(severity: str, stage: str, slug: str, key: str, fp: str, legacy_fp: str) -> str:
    """The machine-read top of an issue body: the sections the dedup Action and a maintainer's triage read."""
    return (
        f"## Workflow\n`ultracode-goal/{stage}`\n\n"
        f"## Step File\n`skills/ultracode-goal/references/{stage}.md`\n\n"
        f"## Section\n`{slug}`\n\n"
        f"## Severity\n`{severity}`\n\n"
        f"## Fingerprint\n`{fp}`\n\n"
        # At the start of a line of its own: the dedup Action's SECTION_RE reads it there.
        f"Section fingerprint: `{legacy_fp}`\n\n"
        f"## Defect Key\n`{key}`\n"
    )


# --- the cache ---------------------------------------------------------------


def _parse(raw: bytes) -> dict | None:
    """The cache object in raw bytes: {} for an empty file, None when it is not a JSON object."""
    try:
        text = raw.decode("utf-8-sig")
    except UnicodeDecodeError:
        return None
    if not text.strip():
        return {}
    try:
        data = json.loads(text)
    except (ValueError, RecursionError):  # RecursionError: nested past the parser's depth
        return None
    return data if isinstance(data, dict) else None


def _load_cache(cache: Path) -> dict:
    """Read the seen-cache as a dict. Missing/empty/unreadable/corrupt -> {} (never raises)."""
    try:
        raw = cache.read_bytes()
    except OSError:
        return {}
    return _parse(raw) or {}


# --- the issue-state check -----------------------------------------------------


def _resolve_outside_cwd(command: str) -> str | None:
    """shutil.which, refusing a resolution into the current folder.

    shutil.which on Windows searches the current folder ahead of PATH, and a
    `.` or empty PATH entry does the same on POSIX. The current folder is the
    user's project, which this module does not control, so a `gh` planted
    there reads as no gh. Returns an absolute path, or None.
    """
    resolved = shutil.which(command)
    if resolved is None:
        return None
    resolved = os.path.abspath(resolved)
    here = os.path.normcase(os.path.realpath(os.getcwd()))
    if os.path.normcase(os.path.realpath(os.path.dirname(resolved))) == here:
        return None
    return resolved


def _child_env() -> dict:
    """os.environ with gh's prompts and update notice turned off."""
    env = dict(os.environ)
    env["GH_PROMPT_DISABLED"] = "1"
    env["GH_NO_UPDATE_NOTIFIER"] = "1"
    return env


def _stop(proc: subprocess.Popen, windows: bool = _IS_WINDOWS) -> None:
    """Stop proc and everything it started once the time limit runs out.

    POSIX sends SIGTERM to its process group, then SIGKILL to whatever is
    left; Windows runs taskkill /F /T on its tree.
    """
    try:
        if windows:
            taskkill = _resolve_outside_cwd("taskkill")
            if taskkill:
                try:
                    subprocess.run(
                        [taskkill, "/F", "/T", "/PID", str(proc.pid)],
                        stdin=subprocess.DEVNULL,
                        capture_output=True,
                        timeout=KILL_WAIT_SEC,
                        check=False,
                    )
                except (OSError, subprocess.TimeoutExpired):
                    pass  # proc itself is still killed below
            proc.kill()
        else:
            os.killpg(proc.pid, signal.SIGTERM)
            try:
                proc.wait(timeout=KILL_WAIT_SEC)
            except subprocess.TimeoutExpired:
                pass
            os.killpg(proc.pid, signal.SIGKILL)
    except (OSError, ValueError, subprocess.TimeoutExpired):
        pass
    try:
        proc.wait(timeout=KILL_WAIT_SEC)
    except subprocess.TimeoutExpired:
        pass


def _run(argv: list[str], timeout: float) -> tuple[int | None, bytes, bytes]:
    """Run argv with no stdin and no shell; (returncode, stdout, stderr).

    returncode is None when the time limit stopped the call. The call gets a
    process group (a POSIX session) of its own, so _stop reaches all it
    started, and its output goes to temporary files, not pipes, so a child it
    left behind cannot hold a read open. Raises OSError or ValueError when
    argv cannot start.
    """
    kwargs: dict = {}
    if _IS_WINDOWS:
        kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
    else:
        kwargs["start_new_session"] = True
    with tempfile.TemporaryFile() as out_f, tempfile.TemporaryFile() as err_f:
        proc = subprocess.Popen(
            argv,
            stdin=subprocess.DEVNULL,
            stdout=out_f,
            stderr=err_f,
            env=_child_env(),
            **kwargs,
        )
        try:
            returncode = proc.wait(timeout=timeout)
        except subprocess.TimeoutExpired:
            _stop(proc)
            returncode = None
        out_f.seek(0)
        err_f.seek(0)
        return returncode, out_f.read(), err_f.read()


def gh_issue_state(issue_url: str, timeout: float | None = None) -> dict | None:
    """`gh issue view <issue_url> --json state,stateReason`: its JSON object, or None on any failure."""
    exe = _resolve_outside_cwd("gh")
    if exe is None:
        return None
    limit = GH_TIMEOUT_SEC if timeout is None else timeout
    try:
        returncode, out, _err = _run(
            [exe, "issue", "view", issue_url, "--json", "state,stateReason"], limit
        )
    except (OSError, ValueError):
        return None
    if returncode != 0:
        return None
    try:
        answer = json.loads(out.decode("utf-8", errors="replace"))
    except ValueError:
        return None
    if not isinstance(answer, dict) or not isinstance(answer.get("state"), str):
        return None
    return answer


def _gh_url(value) -> bool:
    """An issue_url gh may be given: https://, no whitespace (so never a flag)."""
    return (
        isinstance(value, str)
        and value.startswith(URL_PREFIX)
        and not any(ch.isspace() for ch in value)
    )


def _issue_verdict(issue_url) -> tuple[str, str | None]:
    """Branch 3: regression for a completed close ("closed") or a merge ("merged"), handled for anything else."""
    if not _gh_url(issue_url):
        return "handled", None
    answer = gh_issue_state(issue_url)
    if answer is None:
        return "handled", None
    state = answer["state"].upper()
    reason = answer.get("stateReason")
    reason = reason.upper() if isinstance(reason, str) else ""
    if state == "CLOSED" and reason == "COMPLETED":
        return "regression", "closed"
    if state == "MERGED":
        return "regression", "merged"
    return "handled", None


def _verdict(record) -> tuple[str, str | None]:
    """Branches 2 to 5 on a record that exists: the status, and for a regression how the fix is known."""
    if not isinstance(record, dict):
        return "unrecognized", None
    action = record.get("action")
    if action == RESOLVED:
        # Fixed and closed out, so a fresh sighting is a REGRESSION, not a
        # duplicate. The record rides along so the caller can link the original.
        return "regression", RESOLVED
    if action in SUPPRESSING_ACTIONS:
        if record.get("issue_url") in (None, ""):
            return "handled", None
        return _issue_verdict(record.get("issue_url"))
    # Absent or unrecognized: we cannot confirm this was handled, so report.
    return "unrecognized", None


def _issue_prefix(repo: str) -> str:
    """The start of every issue URL of repo: github.com's, or the host's when repo names one, normalised as the
    `repo` subcommand prints it (split_repo), so www.github.com/OWNER/REPO reads github.com's URLs."""
    host, owner_repo = split_repo(repo)
    return f"{URL_PREFIX}{host}/{owner_repo}/"


def _in_repo(record, repo: str | None) -> bool:
    """Whether record may decide a verdict for repo.

    A record that is not an object, or whose issue_url is empty or missing, names no repository, so it decides as it
    always did. Any other issue_url must be a string under repo's issue prefix: another repository's record, or one
    whose URL is not https:// or not a string, neither suppresses this one's finding nor gives its body a line
    linking that issue.
    """
    if repo is None or not isinstance(record, dict):
        return True
    url = record.get("issue_url")
    if url is None or url == "":
        return True
    return isinstance(url, str) and url.lower().startswith(_issue_prefix(repo).lower())


def cmd_seen(args: argparse.Namespace) -> int:
    if not FP_RE.fullmatch(args.fp):
        return _fail("invalid fp %r; expected ^fp-[0-9a-f]{7}$" % args.fp)
    if not FP_RE.fullmatch(args.legacy_fp):
        return _fail("invalid legacy-fp %r; expected ^fp-[0-9a-f]{7}$" % args.legacy_fp)
    if args.repo is not None:
        problem = _repo_error(args.repo)
        if problem:
            return _fail(problem)

    loaded = _load_cache(Path(args.cache).expanduser())
    # A record of another repository's issue counts as no record, before anything reads it (gh included).
    data = {
        key: loaded[key] for key in (args.fp, args.legacy_fp) if key in loaded and _in_repo(loaded[key], args.repo)
    }
    fixed = None
    if args.fp in data:
        record = data[args.fp]
        status, fixed = _verdict(record)
        matched_on = "fp"
    elif args.legacy_fp in data:
        record = data[args.legacy_fp]
        # A section fingerprint may be another defect's: it never suppresses,
        # and a fix it records is only possibly this defect's.
        status, fixed = _verdict(record)
        status = {"handled": "unseen", "regression": "possible-regression"}.get(status, status)
        matched_on = "legacy_fp"
    else:
        record = None
        status = "unseen"
        matched_on = None

    print(
        json.dumps(
            {
                "seen": status == "handled",
                "status": status,
                "record": record,
                "matched_on": matched_on,
                "opening_line": opening_line(status, record, fixed),
            }
        )
    )
    return 0


def opening_line(status: str, record, fixed: str | None) -> str | None:
    """The line a regression's or a possible regression's issue body opens with; None for any other verdict.

    `fixed` is how the fix is known: RESOLVED (the record says so, and its date is the fix's), or "closed" or
    "merged" (the recorded issue's own state, and the record's date is only the day this machine reported it).
    """
    if status not in ("regression", "possible-regression") or not isinstance(record, dict):
        return None
    url = record.get("issue_url")
    day = record.get("date")
    dated = isinstance(day, str) and DATE_RE.fullmatch(day)
    possible = status == "possible-regression"
    lead = "Possibly a regression" if possible else "Regression"
    if fixed in ("closed", "merged"):
        how = "closed as completed" if fixed == "closed" else "merged"
        line = f"{lead} of {url}, {how} since its report " + (f"on {day}" if dated else UNRECORDED_DATE)
    else:
        resolved = f"(resolved {day if dated else UNRECORDED_DATE})"
        if not _gh_url(url):
            where = " in this section" if possible else ""
            return f"{lead} of a previously resolved local finding{where} {resolved}."
        line = f"{lead} of {url} {resolved}"
    if possible:
        return line + ": that report's fingerprint has no defect key, so it may be another defect in this section."
    return line + "."


# --- record --------------------------------------------------------------------


def _record_error(fp: str, action: str, issue_url: str, day: str) -> str | None:
    """The rule the record arguments break, or None."""
    if not FP_RE.fullmatch(fp):
        return "invalid fp %r; expected ^fp-[0-9a-f]{7}$" % fp
    if action not in ACTIONS:
        return "invalid action %r; expected one of %s" % (action, ", ".join(ACTIONS))
    if action == RESOLVED:
        if issue_url != "" and not _gh_url(issue_url):
            return (
                "invalid issue-url %r; a resolved record takes an empty URL or one "
                "that starts with %s and holds no whitespace" % (issue_url, URL_PREFIX)
            )
    elif not _gh_url(issue_url):
        return "invalid issue-url %r; expected one that starts with %s and holds no whitespace" % (
            issue_url,
            URL_PREFIX,
        )
    try:
        if not DATE_RE.fullmatch(day):
            raise ValueError
        date.fromisoformat(day)
    except ValueError:
        return "invalid date %r; expected a real date as YYYY-MM-DD" % day
    return None


def _lock_busy(exc: OSError) -> bool:
    return exc.errno in (errno.EAGAIN, errno.EACCES, errno.EWOULDBLOCK, errno.EDEADLK)


def _try_lock(fd: int) -> None:
    """Take an exclusive lock on fd without waiting; OSError when it is held."""
    if _IS_WINDOWS:
        os.lseek(fd, 0, os.SEEK_SET)
        msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
    else:
        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)


def _unlock(fd: int) -> None:
    try:
        if _IS_WINDOWS:
            os.lseek(fd, 0, os.SEEK_SET)
            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
        else:
            fcntl.flock(fd, fcntl.LOCK_UN)
    except OSError:
        pass  # closing the file releases it too


def _acquire(lock: Path, wait: float) -> int:
    """Open <cache>.lock and lock it, waiting up to `wait` seconds with backoff.

    The OS drops the lock when the holder dies, so a lock left by a killed
    call never needs clearing, and the file is never deleted, which avoids
    races on unlink. Raises _LockBusy at the end of the wait, OSError when the
    file cannot be opened or locked.
    """
    fd = os.open(lock, os.O_RDWR | os.O_CREAT | getattr(os, "O_BINARY", 0), 0o644)
    deadline = time.monotonic() + wait
    delay = _LOCK_POLL_MIN_SEC
    while True:
        try:
            _try_lock(fd)
            return fd
        except OSError as exc:
            left = deadline - time.monotonic()
            if not _lock_busy(exc) or left <= 0:
                os.close(fd)
                if _lock_busy(exc):
                    raise _LockBusy() from None
                raise
        time.sleep(min(delay, left))
        delay = min(delay * 2, _LOCK_POLL_MAX_SEC)


def _release(fd: int) -> None:
    _unlock(fd)
    try:
        os.close(fd)
    except OSError:
        pass


def _replace(src: Path | str, dst: Path | str) -> None:
    """os.replace, retried on Windows while another process has dst open."""
    deadline = time.monotonic() + _REPLACE_WAIT_SECONDS
    while True:
        try:
            os.replace(src, dst)
            return
        except PermissionError:
            if not _IS_WINDOWS or time.monotonic() >= deadline:
                raise
            time.sleep(_REPLACE_POLL_SECONDS)


def _atomic_write(cache: Path, content: str) -> None:
    """Temp file beside the cache, synced to disk, then renamed over it."""
    fd, tmp_name = tempfile.mkstemp(dir=str(cache.parent), prefix=".hc-seen-", suffix=".tmp")
    try:
        try:
            data = memoryview(content.encode("utf-8"))
            while data:
                data = data[os.write(fd, data):]  # os.write may write fewer bytes than asked
            os.fsync(fd)
        finally:
            os.close(fd)
        _replace(tmp_name, cache)
    except OSError:
        try:
            os.unlink(tmp_name)
        except OSError:
            pass
        raise


def _corrupt_stamp() -> str:
    return datetime.now(timezone.utc).strftime(CORRUPT_STAMP_FORMAT)


def _set_aside(cache: Path) -> Path:
    """Rename a corrupt cache to <cache>.corrupt-<UTC stamp>, never over an earlier one."""
    stamp = _corrupt_stamp()
    aside = cache.with_name(f"{cache.name}.corrupt-{stamp}")
    n = 2
    while os.path.lexists(aside):
        aside = cache.with_name(f"{cache.name}.corrupt-{stamp}-{n}")
        n += 1
    _replace(cache, aside)
    return aside


def _merge(cache: Path, fp: str, new: dict, regression: bool) -> dict:
    """The read, merge and write; runs while the caller holds the lock."""
    set_aside = None
    try:
        raw = cache.read_bytes()
    except FileNotFoundError:
        data = {}
    except OSError as exc:
        raise _WriteError("could not read cache %s: %s" % (cache, exc)) from None
    else:
        data = _parse(raw)
        if data is None:
            try:
                set_aside = _set_aside(cache)
            except OSError as exc:
                raise _WriteError(
                    "could not set aside cache %s, which is not a JSON object: %s; "
                    "nothing was written" % (cache, exc)
                ) from None
            data = {}

    existing = data.get(fp)
    if isinstance(existing, dict):
        if existing.get("action") == RESOLVED and new["action"] != RESOLVED and not regression:
            # Never downgrade a fix: only an issue that tracks the recurrence
            # (--regression) replaces it, so suppression never comes back alone.
            return {"written": False, "fp": fp, "record": existing, "set_aside": None}
        if "defect_slug" in existing:
            # Written by an earlier version of this module; it rides along.
            new = {**new, "defect_slug": existing["defect_slug"]}
    data[fp] = new

    try:
        _atomic_write(cache, json.dumps(data, indent=2, sort_keys=True) + "\n")
    except OSError as exc:
        where = " (the corrupt cache was renamed to %s)" % set_aside if set_aside else ""
        raise _WriteError("could not write cache %s: %s%s" % (cache, exc, where)) from None
    return {
        "written": True,
        "fp": fp,
        "record": new,
        "set_aside": str(set_aside) if set_aside else None,
    }


def cmd_record(args: argparse.Namespace) -> int:
    problem = _record_error(args.fp, args.action, args.issue_url, args.date)
    if problem:
        return _fail(problem)

    cache = Path(args.cache).expanduser()
    new = {"issue_url": args.issue_url, "action": args.action, "date": args.date}
    lock = cache.with_name(cache.name + ".lock")
    try:
        cache.parent.mkdir(parents=True, exist_ok=True)
    except OSError as exc:
        return _fail("could not create %s: %s" % (cache.parent, exc))
    try:
        fd = _acquire(lock, LOCK_WAIT_SEC)
    except _LockBusy:
        return _fail(
            "%s stayed locked by another record call for %s seconds; nothing was written"
            % (lock, LOCK_WAIT_SEC)
        )
    except OSError as exc:
        return _fail("could not take %s: %s" % (lock, exc))
    try:
        result = _merge(cache, args.fp, new, args.regression)
    except _WriteError as exc:
        return _fail(str(exc))
    finally:
        _release(fd)

    print(json.dumps(result))
    return 0


def _read_plain_version(path: Path) -> str | None:
    """Read a plain-text VERSION file, a UTF-8 byte order mark dropped. Missing/unreadable/empty -> None."""
    try:
        text = path.read_text(encoding="utf-8-sig", errors="replace")
    except (FileNotFoundError, OSError):
        return None
    stripped = text.strip()
    return stripped or None


def _read_json(path: Path):
    """The JSON value in path; None when it is missing, unreadable or malformed."""
    try:
        text = path.read_text(encoding="utf-8-sig", errors="replace")
    except (FileNotFoundError, OSError):
        return None
    try:
        return json.loads(text)
    except (ValueError, RecursionError):
        return None


def _json_version(node) -> str | None:
    """The "version" of a JSON object, stripped; None when node is no object or that is no non-empty string."""
    version = node.get("version") if isinstance(node, dict) else None
    if not isinstance(version, str):
        return None
    return version.strip() or None


def _marketplace_version(root: Path) -> str | None:
    """The version of the plugin entry named PACKAGE_NAME in root's .claude-plugin/marketplace.json."""
    data = _read_json(root / ".claude-plugin" / "marketplace.json")
    plugins = data.get("plugins") if isinstance(data, dict) else None
    if not isinstance(plugins, list):
        return None
    return _json_version(next((p for p in plugins if isinstance(p, dict) and p.get("name") == PACKAGE_NAME), None))


def _package_version(root: Path) -> str | None:
    """The version in root's package.json, when its name is PACKAGE_NAME."""
    data = _read_json(root / "package.json")
    if not isinstance(data, dict) or data.get("name") != PACKAGE_NAME:
        return None
    return _json_version(data)


def cmd_version(args: argparse.Namespace) -> int:
    project_root = Path(args.project_root).expanduser()
    root = UCG_ROOT

    # First hit wins: UCG's own root, then the version file only UCG's CLI installer writes. A rung whose file is
    # missing, malformed or another package's gives None and falls through to the next.
    ladder = []
    if root is not None:
        ladder += [
            (_marketplace_version(root), ".claude-plugin/marketplace.json"),
            (_package_version(root), "package.json"),
        ]
    ladder.append((_read_plain_version(project_root / "_bmad" / "ucg" / "VERSION"), "_bmad/ucg/VERSION"))

    for version, source in ladder:
        if version is not None:
            print(json.dumps({"version": version, "source": source}))
            return 0

    print(json.dumps({"version": None, "source": "N/A"}))
    return 0


# --- repo ----------------------------------------------------------------------


def repo_fields(repo: str) -> dict:
    """What `repo` prints for repo, which REPO_RE has accepted: {"repo", "host", "owner_repo", "host_flag",
    "is_default"}. The host and OWNER/REPO are split_repo's, the split `seen --repo` compares issue URLs with."""
    host, owner_repo = split_repo(repo)
    return {
        "repo": repo,
        "host": host,
        "owner_repo": owner_repo,
        # split_repo's host, and only for a value that names one, by the rule split_repo reads it with: for
        # OWNER/REPO, --hostname github.com would pin github.com while every --repo call follows gh's default host
        # (GH_HOST, or the one host gh is logged in to).
        "host_flag": f"--hostname {host}" if _named_host(repo) else "",
        "is_default": host == DEFAULT_HOST and owner_repo.lower() == DEFAULT_REPO.lower(),
    }


def cmd_repo(args: argparse.Namespace) -> int:
    problem = _repo_error(args.repo)
    if problem:
        return _fail(problem)
    print(json.dumps(repo_fields(args.repo)))
    return 0


# --- queue ---------------------------------------------------------------------


def _queue_stamp() -> str:
    return datetime.now(timezone.utc).strftime(QUEUE_STAMP_FORMAT)


def _create_new(queue_dir: Path, stem: str) -> tuple[int, Path]:
    """Open queue_dir/<stem>.md for writing, never over a file: <stem>-2.md, -3 and so on when taken.

    Raises OSError when a free name cannot be opened.
    """
    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
    target = queue_dir / f"{stem}.md"
    n = 2
    while True:
        try:
            return os.open(target, flags, 0o644), target
        except FileExistsError:
            target = queue_dir / f"{stem}-{n}.md"
            n += 1


def _draft_keys(body: bytes) -> tuple[str, str, str] | None:
    """The (stage, severity, fp) of the body_header a draft opens with, or None when it opens with none."""
    match = _DRAFT_HEADER_RE.match(body.decode("utf-8-sig", errors="replace"))
    return (match.group("stage"), match.group("severity"), match.group("fp")) if match else None


def submit_commands(repo: str, title: str, severity: str, fp: str, path: str) -> list[str]:
    """The label create, the create, and the create without labels that file a queued draft.

    Each argument is quoted for a POSIX shell, and `--repo` follows the subcommand, so an allow rule scoped to the
    repository (`gh issue create --repo OWNER/REPO`) matches.
    """

    def line(*argv: str) -> str:
        return " ".join(shlex.quote(arg) for arg in argv)

    label = line("gh", "label", "create", "--repo", repo, fp, "--color", FP_LABEL_COLOR,
                 "--description", FP_LABEL_DESCRIPTION)
    create = line("gh", "issue", "create", "--repo", repo, "--title", title,
                  "--label", ",".join((*ISSUE_LABELS, severity, fp)), "--body-file", path)
    bare = line("gh", "issue", "create", "--repo", repo, "--title", title, "--body-file", path)
    return [label, create, bare]


def cmd_queue(args: argparse.Namespace) -> int:
    body_file = Path(args.body_file).expanduser()
    try:
        body = body_file.read_bytes()
    except OSError as exc:
        return _fail("could not read body file %s: %s" % (body_file, exc))
    keys = _draft_keys(body)
    if keys is None:
        return _fail(
            "body file %s holds no body_header; open the draft with the body_header `fingerprint` printed"
            % body_file
        )
    stage, severity, fp = keys
    prefix = f"[health-check][{severity}][{fp}] ultracode-goal/{stage}: "
    if not args.title.startswith(prefix):
        return _fail(
            "title %r is not this draft's: the draft's body_header gives %s, %s and %s, so its title starts with %r"
            % (args.title, stage, severity, fp, prefix)
        )
    if len(args.title) > TITLE_MAX:
        return _fail("title is %d characters long; GitHub takes at most %d" % (len(args.title), TITLE_MAX))
    if _title_unsafe(args.title):
        return _fail(
            "title %r holds a backtick, `$`, double quote, backslash, `!` or a character that is not printable "
            "(a tab or a line break included)" % args.title
        )
    problem = _repo_error(args.repo)
    if problem:
        return _fail(problem)

    queue_dir = Path(args.queue_dir).expanduser()
    try:
        queue_dir.mkdir(parents=True, exist_ok=True)
    except OSError as exc:
        return _fail("could not create %s: %s" % (queue_dir, exc))
    try:
        fd, target = _create_new(queue_dir, f"hc-ultracode-goal-{stage}-{_queue_stamp()}")
    except OSError as exc:
        return _fail("could not create a queue file in %s: %s" % (queue_dir, exc))
    try:
        try:
            data = memoryview(body)
            while data:
                data = data[os.write(fd, data):]  # os.write may write fewer bytes than asked
        finally:
            os.close(fd)
    except OSError as exc:
        try:
            os.unlink(target)
        except OSError:
            pass
        return _fail("could not write %s: %s" % (target, exc))

    path = os.path.abspath(target)
    _print_utf8({"path": path, "commands": submit_commands(args.repo, args.title, severity, fp, path)})
    return 0


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Fingerprint, seen-cache and queue plumbing for the ultracode-goal health check."
    )
    sub = parser.add_subparsers(dest="command", required=True)

    fp_parser = sub.add_parser("fingerprint", help="Compute the dedup fingerprints.")
    fp_parser.add_argument("--severity", required=True)
    fp_parser.add_argument("--stage", required=True)
    fp_parser.add_argument(
        "--section-slug",
        dest="section_slug",
        help="The section's kebab-case slug, in place of a --stdin section_heading: it skips the check that the "
        "heading is one of the stage file's own. Without --stdin, title, regression_title and body_header print "
        "null.",
    )
    fp_parser.add_argument(
        "--defect-key",
        dest="defect_key",
        help="One to four kebab-case words naming the thing the fix would change, in place of a --stdin "
        "defect_name. Without --stdin, title, regression_title and body_header print null.",
    )
    fp_parser.add_argument(
        "--stdin",
        action="store_true",
        help='Read {"section_heading": ..., "defect_name": ..., "short_description": ...} from stdin: the '
        "first two in place of --section-slug and --defect-key respectively, the optional third for the "
        "issue title and body header.",
    )
    fp_parser.set_defaults(func=cmd_fingerprint)

    seen_parser = sub.add_parser("seen", help="The seen-cache verdict for a finding.")
    seen_parser.add_argument("--fp", required=True)
    seen_parser.add_argument("--legacy-fp", required=True, dest="legacy_fp")
    seen_parser.add_argument("--cache", required=True)
    seen_parser.add_argument(
        "--repo",
        help="The repository findings are filed on, [HOST/]OWNER/REPO: a record of an issue on another one counts "
        "as no record.",
    )
    seen_parser.set_defaults(func=cmd_seen)

    repo_parser = sub.add_parser(
        "repo", help="Split the repository findings are filed on into its host, OWNER/REPO and gh --hostname flag."
    )
    repo_parser.add_argument("--repo", required=True, help="The configured health_check_repo, [HOST/]OWNER/REPO.")
    repo_parser.set_defaults(func=cmd_repo)

    rec_parser = sub.add_parser("record", help="Record a fingerprint outcome to the cache.")
    rec_parser.add_argument("--fp", required=True)
    rec_parser.add_argument("--cache", required=True)
    rec_parser.add_argument("--issue-url", required=True, dest="issue_url")
    rec_parser.add_argument("--action", required=True)
    rec_parser.add_argument("--date", required=True)
    rec_parser.add_argument(
        "--regression",
        action="store_true",
        help="After a regression verdict: the issue tracks the recurrence, so it "
        "replaces a resolved record.",
    )
    rec_parser.set_defaults(func=cmd_record)

    ver_parser = sub.add_parser(
        "version", help="The version of the UltraCode Goal this script belongs to, never the user's project's."
    )
    ver_parser.add_argument(
        "--project-root", required=True, dest="project_root",
        help="The user's project: its _bmad/ucg/VERSION, which UCG's CLI installer writes, is the last rung.",
    )
    ver_parser.set_defaults(func=cmd_version)

    queue_parser = sub.add_parser(
        "queue", help="Write a drafted body into the local queue and print the commands that submit it."
    )
    queue_parser.add_argument("--queue-dir", required=True, dest="queue_dir")
    queue_parser.add_argument(
        "--body-file", required=True, dest="body_file",
        help="The draft, opening with the body_header `fingerprint` printed: the queue file is named after its stage.",
    )
    queue_parser.add_argument("--title", required=True, help="The issue title `fingerprint` printed for the draft.")
    queue_parser.add_argument("--repo", required=True, help="The repository the commands file the issue on.")
    queue_parser.set_defaults(func=cmd_queue)

    args = parser.parse_args(argv)
    if args.command == "fingerprint" and not args.stdin:
        # Without --stdin both flags stay required, as before --stdin existed.
        missing = [
            flag
            for flag, value in (("--section-slug", args.section_slug), ("--defect-key", args.defect_key))
            if value is None
        ]
        if missing:
            fp_parser.error(
                "the following arguments are required without --stdin: %s" % ", ".join(missing)
            )
    return args.func(args)


if __name__ == "__main__":
    sys.exit(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