fix(skills): sync the distributed adoption skill and pin it to the repo copy

`init` writes .claude/skills/*/SKILL.md into every new repository from the
constants in skills_content, so each skill exists twice: once as the copy
this repository uses, once as the copy it ships. Editing one and not the
other went unnoticed by validate and by every test.

It had already happened. The shipped repository-adoption skill still told
its reader to use `--strategy normalize --recipe documents-to-content-root`
-- an operation the CLI does not offer and CLAUDE.md forbids claiming --
and said nothing about the owner requirement or acknowledged findings.
Every repository bootstrapped since would have received that copy.

Sync both, and add a test that compares each shipped skill against the
checked-in one so the next divergence fails instead of shipping.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Alexander Baranov
2026-08-25 18:11:13 +03:00
co-authored by Claude Opus 5
parent 1ab02a257c
commit 79ea43d5bf
4 changed files with 70 additions and 10 deletions
+8 -4
View File
@@ -14,8 +14,11 @@ with machine output, and explains findings. It must not duplicate the runbook lo
1. Run `repoctl adopt --repo <path> --mode assess --output json` (read-only). 1. Run `repoctl adopt --repo <path> --mode assess --output json` (read-only).
2. Present the classification, detected content roots, and any `questions` that need 2. Present the classification, detected content roots, and any `questions` that need
owner confirmation. owner confirmation.
3. Run `repoctl adopt --repo <path> --mode plan --output json` once open questions are 3. Run `repoctl adopt --repo <path> --mode plan --owner <owner> --output json` once open
resolved. This is still read-only and returns an `AdoptionPlan` with a `planHash`. questions are resolved. This is still read-only and returns an `AdoptionPlan` with a
`planHash`. `plan` refuses without a confirmed owner, and refuses while `assess` left
an error-severity finding; an owner who accepts one lists it under
`acknowledgedFindings` (with a `reason`) in the `--answers` file.
4. Show the full plan (files created, patched managed blocks, preserved paths, 4. Show the full plan (files created, patched managed blocks, preserved paths,
forbidden changes) before asking for approval. forbidden changes) before asking for approval.
5. Only after explicit approval, run 5. Only after explicit approval, run
@@ -23,5 +26,6 @@ with machine output, and explains findings. It must not duplicate the runbook lo
6. Run `repoctl adopt --repo <path> --mode verify --output json` and report the 6. Run `repoctl adopt --repo <path> --mode verify --output json` and report the
`AdoptionReport`, including any `unresolvedFindings`. `AdoptionReport`, including any `unresolvedFindings`.
Default strategy is `overlay`. Only use `--strategy normalize --recipe The only implemented strategy is `overlay`. Normalization recipes are specified in the
documents-to-content-root` when the owner explicitly asks to reorganize root documents. runbook but not implemented, and the CLI does not offer them: do not describe
`--strategy normalize` or `--recipe` as available.
+5 -1
View File
@@ -12,7 +12,11 @@ rendering or validation here - call the CLI and explain its output.
1. Collect the missing decisions from the user: repository type 1. Collect the missing decisions from the user: repository type
(`infrastructure-config` | `service-config` | `software` | `project`), `metadata.name`, (`infrastructure-config` | `service-config` | `software` | `project`), `metadata.name`,
`title`, `owners`, `lifecycle`. `title`, `owners`, `lifecycle`. All of these are refused rather than guessed:
`name` must match `^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`, `owners` must be non-empty,
and `lifecycle` must be one of the schema's values.
If the target directory already holds `ops/contract.yaml` or the other generated
paths, this is an existing repository: use `repository-adoption`, not `init`.
2. Run `repoctl init --repo <path> --answers <answers-file> --output json` to obtain a 2. Run `repoctl init --repo <path> --answers <answers-file> --output json` to obtain a
`BootstrapPlan` (this performs no writes). `BootstrapPlan` (this performs no writes).
3. Show the user the planned files and the `planHash`. 3. Show the user the planned files and the `planHash`.
+13 -5
View File
@@ -20,7 +20,11 @@ rendering or validation here - call the CLI and explain its output.
1. Collect the missing decisions from the user: repository type 1. Collect the missing decisions from the user: repository type
(`infrastructure-config` | `service-config` | `software` | `project`), `metadata.name`, (`infrastructure-config` | `service-config` | `software` | `project`), `metadata.name`,
`title`, `owners`, `lifecycle`. `title`, `owners`, `lifecycle`. All of these are refused rather than guessed:
`name` must match `^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`, `owners` must be non-empty,
and `lifecycle` must be one of the schema's values.
If the target directory already holds `ops/contract.yaml` or the other generated
paths, this is an existing repository: use `repository-adoption`, not `init`.
2. Run `repoctl init --repo <path> --answers <answers-file> --output json` to obtain a 2. Run `repoctl init --repo <path> --answers <answers-file> --output json` to obtain a
`BootstrapPlan` (this performs no writes). `BootstrapPlan` (this performs no writes).
3. Show the user the planned files and the `planHash`. 3. Show the user the planned files and the `planHash`.
@@ -47,8 +51,11 @@ with machine output, and explains findings. It must not duplicate the runbook lo
1. Run `repoctl adopt --repo <path> --mode assess --output json` (read-only). 1. Run `repoctl adopt --repo <path> --mode assess --output json` (read-only).
2. Present the classification, detected content roots, and any `questions` that need 2. Present the classification, detected content roots, and any `questions` that need
owner confirmation. owner confirmation.
3. Run `repoctl adopt --repo <path> --mode plan --output json` once open questions are 3. Run `repoctl adopt --repo <path> --mode plan --owner <owner> --output json` once open
resolved. This is still read-only and returns an `AdoptionPlan` with a `planHash`. questions are resolved. This is still read-only and returns an `AdoptionPlan` with a
`planHash`. `plan` refuses without a confirmed owner, and refuses while `assess` left
an error-severity finding; an owner who accepts one lists it under
`acknowledgedFindings` (with a `reason`) in the `--answers` file.
4. Show the full plan (files created, patched managed blocks, preserved paths, 4. Show the full plan (files created, patched managed blocks, preserved paths,
forbidden changes) before asking for approval. forbidden changes) before asking for approval.
5. Only after explicit approval, run 5. Only after explicit approval, run
@@ -56,8 +63,9 @@ with machine output, and explains findings. It must not duplicate the runbook lo
6. Run `repoctl adopt --repo <path> --mode verify --output json` and report the 6. Run `repoctl adopt --repo <path> --mode verify --output json` and report the
`AdoptionReport`, including any `unresolvedFindings`. `AdoptionReport`, including any `unresolvedFindings`.
Default strategy is `overlay`. Only use `--strategy normalize --recipe The only implemented strategy is `overlay`. Normalization recipes are specified in the
documents-to-content-root` when the owner explicitly asks to reorganize root documents. runbook but not implemented, and the CLI does not offer them: do not describe
`--strategy normalize` or `--recipe` as available.
""" """
REPO_HANDOFF_SKILL = """--- REPO_HANDOFF_SKILL = """---
+44
View File
@@ -0,0 +1,44 @@
"""The skills this repository ships must match the skills it uses.
`init` writes `.claude/skills/*/SKILL.md` into every new repository from the
constants in `skills_content`, so those constants are a distributed artifact
with a second copy checked in here. Editing one and not the other shipped a
stale skill into every repository created afterwards -- silently, because
neither `validate` nor any other test compared them.
"""
from __future__ import annotations
from pathlib import Path
import pytest
from stewardship import skills_content
REPO_ROOT = Path(__file__).resolve().parents[1]
DISTRIBUTED = {
"repository-bootstrap": skills_content.REPOSITORY_BOOTSTRAP_SKILL,
"repository-adoption": skills_content.REPOSITORY_ADOPTION_SKILL,
"repo-handoff": skills_content.REPO_HANDOFF_SKILL,
}
@pytest.mark.parametrize("name", sorted(DISTRIBUTED))
def test_shipped_skill_matches_the_one_in_this_repository(name: str) -> None:
on_disk = (REPO_ROOT / ".claude" / "skills" / name / "SKILL.md").read_text(encoding="utf-8")
assert on_disk.strip() == DISTRIBUTED[name].strip(), (
f"{name}: .claude/skills/{name}/SKILL.md and skills_content.py have diverged. "
"Update both, or the next `repoctl init` ships the stale one."
)
def test_adoption_skill_does_not_offer_normalization() -> None:
"""CLAUDE.md: do not describe an operation the CLI does not offer.
The skill may name `--strategy normalize` in order to say it is unavailable;
what it must never do is instruct someone to use it.
"""
text = skills_content.REPOSITORY_ADOPTION_SKILL
assert "Only use `--strategy normalize" not in text
assert "not implemented" in text