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:
co-authored by
Claude Opus 5
parent
1ab02a257c
commit
79ea43d5bf
@@ -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).
|
||||
2. Present the classification, detected content roots, and any `questions` that need
|
||||
owner confirmation.
|
||||
3. Run `repoctl adopt --repo <path> --mode plan --output json` once open questions are
|
||||
resolved. This is still read-only and returns an `AdoptionPlan` with a `planHash`.
|
||||
3. Run `repoctl adopt --repo <path> --mode plan --owner <owner> --output json` once open
|
||||
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,
|
||||
forbidden changes) before asking for approval.
|
||||
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
|
||||
`AdoptionReport`, including any `unresolvedFindings`.
|
||||
|
||||
Default strategy is `overlay`. Only use `--strategy normalize --recipe
|
||||
documents-to-content-root` when the owner explicitly asks to reorganize root documents.
|
||||
The only implemented strategy is `overlay`. Normalization recipes are specified in the
|
||||
runbook but not implemented, and the CLI does not offer them: do not describe
|
||||
`--strategy normalize` or `--recipe` as available.
|
||||
|
||||
@@ -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
|
||||
(`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
|
||||
`BootstrapPlan` (this performs no writes).
|
||||
3. Show the user the planned files and the `planHash`.
|
||||
|
||||
@@ -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
|
||||
(`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
|
||||
`BootstrapPlan` (this performs no writes).
|
||||
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).
|
||||
2. Present the classification, detected content roots, and any `questions` that need
|
||||
owner confirmation.
|
||||
3. Run `repoctl adopt --repo <path> --mode plan --output json` once open questions are
|
||||
resolved. This is still read-only and returns an `AdoptionPlan` with a `planHash`.
|
||||
3. Run `repoctl adopt --repo <path> --mode plan --owner <owner> --output json` once open
|
||||
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,
|
||||
forbidden changes) before asking for approval.
|
||||
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
|
||||
`AdoptionReport`, including any `unresolvedFindings`.
|
||||
|
||||
Default strategy is `overlay`. Only use `--strategy normalize --recipe
|
||||
documents-to-content-root` when the owner explicitly asks to reorganize root documents.
|
||||
The only implemented strategy is `overlay`. Normalization recipes are specified in the
|
||||
runbook but not implemented, and the CLI does not offer them: do not describe
|
||||
`--strategy normalize` or `--recipe` as available.
|
||||
"""
|
||||
|
||||
REPO_HANDOFF_SKILL = """---
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user