Skip to content

fix(consumer): make the adoption skill runnable, and execute what .gds declares - #182

Merged
rldyourmnd merged 2 commits into
mainfrom
fix/consumer-contract-and-hygiene
Aug 15, 2026
Merged

fix(consumer): make the adoption skill runnable, and execute what .gds declares#182
rldyourmnd merged 2 commits into
mainfrom
fix/consumer-contract-and-hygiene

Conversation

@rldyourmnd

Copy link
Copy Markdown
Contributor

Three findings that share a shape: a document telling somebody else how to verify
something, which was never itself verified.

1. The consumer skill could not be followed

ci-consumer-adoption says "This is the caller side", then opened with:

.venv/bin/python -I -B scripts/check_python_execution_contract.py --launch resolve_profile.py -- …

Those paths are inside this repository. An agent following the skill in a consumer
repository gets No such file or directory before making its first decision.

Worse, the skill also requires pinning to a released tag, and
scripts/resolve_profile.py does not exist in 0.13.3, the newest release. The two
instructions could not both be obeyed.

Both mirrored copies carried it identically — mirror parity working exactly as
designed, and saying nothing about whether the mirrored thing is true.

Fix: the block checks the library out first and says plainly that the resolver is
newer than the last release. check_consumer_skill_contract.py holds both halves, and
the second is the one that will rot: what the skill says about the newest release must
match what that tag contains, in both directions — so the caveat has to be removed
once a release carries the resolver.

2. .gds/repository.yaml was exempt from working

It is read across the submodule boundary by github-device-sync, which runs what it
finds under verification.commands. Nothing checked those commands worked, and for
weeks after the launcher split they did not.

The exemption shielding it carried four claims, all false by now:

claim reality
"its verification command is stale after the launcher split" it runs, exit 0
"Generated estate projection" bundle.lock.yaml lists exactly one projection output, compiled-policy.json; this file has no generated header
"tracked in github-device-sync#176" that issue closed 2026-08-13
"A hand edit here is reverted by the next gds run" .claude/CLAUDE.md says the opposite — a superproject cannot write into a submodule tree

That entry reproduced the exact misreading the repository brief warns about — the one
that left a broken command declared for weeks because the fix looked like somebody
else's to make.

Fix: the exemption states its one true reason — the commands must be the
portable python3 -I -B form, because the control plane runs them where this
repository's .venv does not exist — and check_gds_verification_commands.py
executes what the file declares. Exempt from the form rule is not exempt from
working.

validate_all.py is checked for form only rather than executed, because running the
aggregate validator from inside itself would recurse. That limit is stated in the file.

3. aqtinstall.log

5.7 KB of local Qt debug output, tracked since 12a5eeb. The review called it
immaterial and I agree on severity — but a build artifact in a supply-chain library's
published tree costs two lines to remove. Gone, and named in .gitignore.

Mutations

Mutation Result
skill reverts to library-local paths with no checkout RED (caught)
skill drops the released-version caveat RED (caught)
.gds reverts to bare python3 scripts/validate_all.py (the original defect) RED (caught)
.gds names a script that does not exist RED (caught)
a declared .gds command exits non-zero RED (caught)
verification.required names an undefined command RED (caught)

Note on the role

The plan flagged the skill's role: repository-launcher in
catalog/python-execution.yml as wrong for a consumer-facing document. It is now
accurate rather than wrong: the block genuinely runs the launcher, inside a library
checkout. Appropriateness — the thing the role could not check — is covered by the new
contract instead.

Verification

  • validate_all — all tiers OK with GH_TOKEN
  • actionlint — clean · skill mirrors regenerated through the launcher, check_skills OK

…s declares

ci-consumer-adoption says "This is the *caller* side" and then opened with
.venv/bin/python and scripts/... -- paths inside this repository. An agent
following it in a consumer repository got No such file or directory before its
first decision. It also requires pinning to a released tag while
scripts/resolve_profile.py does not exist in 0.13.3, so the two instructions
could not both be obeyed. Both mirrored copies carried it identically: parity
working as designed, and saying nothing about whether the mirrored thing is
true.

The block now checks the library out first, and
check_consumer_skill_contract.py holds both halves -- library-local paths must
be established by the block that uses them, and what the skill says about the
newest release must match what that tag contains, in both directions, so the
caveat must be removed once a release carries the resolver.

.gds/repository.yaml is read across the submodule boundary and its
verification.commands are run by the control plane. Nothing checked they
worked, and after the launcher split they did not. The exemption shielding it
carried four claims that had all become false, including that it is a
generated projection -- bundle.lock.yaml lists one projection output and this
is not it -- and that the issue was tracked upstream, when it closed on
2026-08-13. The exemption now states its one true reason, and
check_gds_verification_commands.py executes what the file declares.

aqtinstall.log, 5.7 KB of local Qt debug output, was tracked. Removed and
named in .gitignore.
@github-actions github-actions Bot added ci Continuous integration and removed ci Continuous integration labels Aug 15, 2026
…in the sweep

The release-version half needs SemVer tags, and the blocking job checks out
without them, so core failed on its own environment rather than on the tree.
That is the split check_release_ledger already makes: headings reconcile in
core, tags reconcile in the advisory sweep. catalog/validation-tiers.yml
records the git_tags requirement, and the tier contract now holds it -- which
is how the mismatch was found.
@github-actions github-actions Bot added ci Continuous integration and removed ci Continuous integration labels Aug 15, 2026
@rldyourmnd
rldyourmnd merged commit fd0cc49 into main Aug 15, 2026
29 checks passed
@rldyourmnd
rldyourmnd deleted the fix/consumer-contract-and-hygiene branch August 15, 2026 01:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant