diff --git a/.claude/skills/repository-adoption/SKILL.md b/.claude/skills/repository-adoption/SKILL.md index c1fa76d..ed43ed0 100644 --- a/.claude/skills/repository-adoption/SKILL.md +++ b/.claude/skills/repository-adoption/SKILL.md @@ -14,8 +14,11 @@ with machine output, and explains findings. It must not duplicate the runbook lo 1. Run `repoctl adopt --repo --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 --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 --mode plan --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 --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. diff --git a/.claude/skills/repository-bootstrap/SKILL.md b/.claude/skills/repository-bootstrap/SKILL.md index 5f226ed..f9b8a5a 100644 --- a/.claude/skills/repository-bootstrap/SKILL.md +++ b/.claude/skills/repository-bootstrap/SKILL.md @@ -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 --answers --output json` to obtain a `BootstrapPlan` (this performs no writes). 3. Show the user the planned files and the `planHash`. diff --git a/src/stewardship/skills_content.py b/src/stewardship/skills_content.py index 301acaa..346914d 100644 --- a/src/stewardship/skills_content.py +++ b/src/stewardship/skills_content.py @@ -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 --answers --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 --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 --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 --mode plan --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 --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 = """--- diff --git a/tests/test_distributed_artifacts.py b/tests/test_distributed_artifacts.py new file mode 100644 index 0000000..0e2ca1e --- /dev/null +++ b/tests/test_distributed_artifacts.py @@ -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