Make --emit-yaml output pasteable, and refuse a --refresh that would do nothing (#380)

[realmarcin]

Closes #380.

The divergence

apply_to_community dumped blocks at width=4096, one key per line. --emit-yaml used PyYAML's default, so the two long scalars wrapped:

    mapping_source: kg-microbe NCBI2GTDB.tsv.gz; GTDB release latest (built 2026-07-25) [grounded at g__
      rank; 1 GTDB taxa under the NCBI taxon]

--emit-yaml exists to be pasted into a record, so the two paths disagreeing is how wrapped blocks reached the KB.

This is not cosmetic — it is the root cause of the corruption #378 had to fix. Once both shapes exist, a line-level editor has to handle both, and that PR's first version matched exactly six spaces and orphaned the continuations into duplicate keys.

The fix

One constant, DUMP_WIDTH, used by both call sites. What keeps it fixed is a test that renders the same grounding down each path and compares bytes — otherwise a future change to either dump call (a width, a flow style, a sort) reintroduces #380 silently.

The secondary point, also real

--refresh only modifies how --apply treats existing blocks. On its own, or with --ncbi-id/--name where there is no stored block, it ran the ordinary report and exited 0 — leaving the caller believing a re-ground had happened. Argparse enforced neither:

$ gtdb_ground.py --community X.yaml --refresh          # before: normal report, exit 0
$ gtdb_ground.py --name Bosea --refresh                # before: normal report, exit 0

Both are now refused with a message saying what --refresh actually does. --community X --refresh --apply is unaffected, and a test pins that so the guard can't over-reach.

Scope

scripts/gtdb_ground.py only, +22/−2. No KB record changes. Six new tests. just qc green.

⚠️ CI note: GitHub Actions has produced no run on this repository since 14:50 UTC, so this PR will likely show no checks — the same stall blocking #456. Local just qc (lint + full suite + every offline validator) is green on this tree.

🤖 Generated with Claude Code

[realmarcin]

Review round 1 — the test that mattered was a tautology

The reviewer confirmed the code is sound on every probe, and then found that my headline test proved nothing.

test_both_render_paths_agree rebuilt emit_block's body character-for-character and compared it to emit_block. It passed for any DUMP_WIDTH and never touched apply_to_community — whose dump is a different call: on the inner block, without default_flow_style, with a hand-prefixed indent. Changing the apply side left all six tests green, which is exactly the regression the file's docstring promises to catch.

It now applies a block to a real record and reads back what landed, comparing key-for-key against --emit-yaml and asserting no line wrapped. Verified against main's script: four tests fail, this one among them — before the rewrite, only the orphan check did.

Two smaller ones from the same review:

• the fixture used a genus-rank lineage, which contains no whitespace and therefore cannot wrap — leaving gtdb_lineage, the scalar the module comment names as a wrapping risk, untested. It's a species lineage now, whose final segment carries a space.
• the orphan detector keyed on the absence of a colon, which a wrapped scalar can contain. It keys on indentation instead.

What the review cleared

• No workflow breaks. Repo-wide, the only --refresh invocations already carry --apply (gtdb_coherence.py:247 and a history record); the skill mentions it in prose only; justfile:472 is a generic passthrough; no CI workflow invokes the script.
• The no-op diagnosis holds. args.refresh is read at exactly three places: the two new guards and the single apply_to_community call. withdraw_ambiguous and apply_status_to_community take no refresh, so refusing those combinations is right too.
• width=4096 is safe. emit_block only prints to stdout; the KB already carries a 2014-char line, and no linter enforces YAML line length.

just qc green · 1570 passed, 16 skipped.

⚠️ Actions is still stalled repo-wide (no run since 14:50 UTC), so this will likely show no checks — same as #456.

[realmarcin]

Cause identified: a GitHub Actions platform outage

Not this repo, not this PR. GitHub's own status API:

$ curl -s https://www.githubstatus.com/api/v2/components.json
  Webhooks: operational
  Actions:  major_outage

Repo and org Actions settings are both {"enabled": true, "allowed_actions": "all"}, so it is not a permissions or quota problem either. No workflow has run on this repository since 14:50 UTC (now past 20:00).

Nothing to do here but wait. This PR is ready: just qc green locally — lint, the full suite, and every offline validator, which between them are a superset of the lint and validate-strict jobs. It should merge on a green run once Actions returns.