fix(init): stop the entry point from disabling the command it reaches

A field report from bootstrapping Services/Vault: ~20 CLI calls produced
three productive writes, and four of those calls were deliberate failures
sent only to discover a vocabulary.

The worst of it was self-inflicted and new. `repoctl skills install` is the
documented way to make the bootstrap skill reachable, and it writes the
three skill files -- which `init` then reported as INIT_PATH_COLLISION and
redirected to `adopt`. Every skill-driven bootstrap of an empty repository
was pushed onto the adoption path. The collision check exists to protect
content the tool did not author, and identical bytes are nothing to
protect: a path already holding exactly what the plan would write is no
longer a collision, at plan time or at write time, while a file whose
content differs still is. `init` reports only the files it actually wrote.

`--lifecycle` advertised no choices, so its vocabulary was reachable only
by sending a wrong value and reading the refusal; it now carries `choices`
like `--type` does.

`--answers-template` prints a commented answers file naming every key, its
allowed values and its default. The answers keys are not the flag names
(`--type` sets `repositoryType`) and nothing printed the mapping. It lists
`summary` and `namespace` too, which are cheap to answer once and otherwise
survive as generated placeholders in the contract.

`--repo .` proposed the name `adopted-repository`: `Path(".").name` is the
empty string, so the ordinary way to name the current repository fell
through to the generic fallback. Resolve before deriving.

Both skills gained what the report had to discover by hand: that `--plan`
already unwraps a saved result envelope, and that sibling repositories are
where a naming convention comes from.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Alexander Baranov
2026-08-26 14:56:49 +03:00
co-authored by Claude Opus 5
parent c80d39cc73
commit 5b9c97fdcd
8 changed files with 180 additions and 21 deletions
@@ -23,6 +23,8 @@ with machine output, and explains findings. It must not duplicate the runbook lo
forbidden changes) before asking for approval.
5. Only after explicit approval, run
`repoctl adopt --repo <path> --mode apply --plan <plan-file> --approve <planHash>`.
`--plan` accepts the file exactly as `--output json > plan.json` wrote it: the
result envelope is unwrapped for you, so do not strip it down to `data` by hand.
6. Run `repoctl adopt --repo <path> --mode verify --output json` and report the
`AdoptionReport`, including any `unresolvedFindings`.
+12 -8
View File
@@ -10,14 +10,18 @@ rendering or validation here - call the CLI and explain its output.
## Procedure
1. Collect the missing decisions from the user: repository type
(`infrastructure-config` | `service-config` | `software` | `project`), `metadata.name`,
`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
1. Run `repoctl init --answers-template > answers.yaml`. It names every key, its
allowed values and its default; the answers keys are not the flag names
(`--type` sets `repositoryType`). Fill it in with the user.
Answer `summary` and `namespace` too: they are cheap now and otherwise stay
as placeholders in the contract.
All values are refused rather than guessed -- `name` must match
`^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`, `owners` must be non-empty -- and before
choosing a name, look at the sibling repositories and follow their convention.
If the target already holds `ops/contract.yaml`, this is an existing
repository: use `repository-adoption`, not `init`. Skill files left by
`repoctl skills install` are not a collision.
2. Run `repoctl init --repo <path> --answers answers.yaml --output json` to obtain a
`BootstrapPlan` (this performs no writes).
3. Show the user the planned files and the `planHash`.
4. Only after explicit approval, run