[yi-ge]

Why

upstream-health-hold.json could only cover upstream-path-change and outdated. When the upstream head of a held collection adds children that children does not declare, the new-skill finding stays actionable even after maintainers have reviewed those children and decided not to declare them, so the tracking issue (#213) can never close. skills/marketingskills is in this state today: its two new upstream children were reviewed in the 2026-10-27 round (#227), but nothing can hold the finding.

What changes

• new-skill is now a holdable status (HOLDABLE = ("upstream-path-change", "new-skill", "outdated")).
• A hold that lists new-skill also checks the undeclared children:
  • the set of undeclared child paths at branch head must equal the set at the reviewed head; otherwise stale-hold: undeclared children changed since <head> (added …; removed …);
  • the staleness diff adds those undeclared child paths to the installed scope (declared children plus root LICENSE*/NOTICE*/COPYING*), so any change inside them gives stale-hold: upstream changed within the installed scope or undeclared children since <head>;
  • a network error while listing children at the reviewed head is unreachable, not a stale hold.
• Holds without new-skill compare the same scope and keep every existing message. The only wording change for them is the validation error for an unholdable status, which now lists new-skill among the holdable statuses.
• The discovery filter moves into undeclared_children(), which the new-skill finding and the hold check share, so both always agree on what is undeclared.
• The checker docstring, the tracking-issue guidance in .github/workflows/upstream-health.yml, README.md and README.zh-CN.md describe the extended hold.

Tests

New cases in scripts/catalog/test_check_upstream_health.py:

• a valid new-skill hold is reported as held, and stays held after an unrelated upstream change;
• a newly added undeclared child, and later the removal of the reviewed ones, make the hold stale;
• a content change inside a held undeclared child makes the hold stale;
• an outdated-only hold on a collection still ignores changes to undeclared children (existing behaviour);
• a network error while listing children at the reviewed head stays unreachable.

The validation test now accepts new-skill and still rejects broken, unreachable, unpinned, held, stale-hold and ok.

Validation

• scripts/i18n/test_validate_i18n.py: 19 tests pass.
• scripts/catalog/test_validate_catalog_metadata.py: 51 tests pass.
• scripts/catalog/test_collection_generator.py: 10 tests pass.
• scripts/catalog/test_check_upstream_health.py: 47 tests pass (5 new).
• validate_catalog_metadata.py --require-complete and validate-i18n.py: 0 errors, 103 existing warnings. translate.py --check, actionlint and git diff --check are clean.
• Live run on marketingskills (entry and hold as on main, in a scratch copy, not committed):
  • with new-skill added to the 2026-10-27 hold, the result is stale-hold, because upstream has since moved from 17772c7 to 0cd9b3a and changed declared children. The same hold without new-skill is also stale, so this is not caused by the new check. The two undeclared children are unchanged between those heads.
  • with the reviewed head set to a commit whose tree equals the current head, new-skill and outdated are both held and the summary reports actionable: false.

Follow-up

After this lands, the marketingskills hold can add new-skill to its statuses. Its reviewed head needs a fresh review first, because upstream has changed declared children since 17772c7.

The pre-publication sensitive-token scan was run privately by the maintainer and passed.

Refs #213.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.