Обзор базы знаний жил как `python -m stewardship.kdb_table` - работало, но не
как остальной инструмент. Теперь это обычная подкоманда:
repoctl kdb --repo .
Вписана в контракт, а не рядом с ним: `--output json|yaml` возвращает штатный
конверт с `stewardship/knowledge-overview@0.1` внутри, находки уходят в stderr,
коды возврата прежние (0, и 3 при отсутствии базы знаний).
Одно осознанное отличие от прочих команд: `--output human` печатает саму
таблицу, а не строку статуса. Для `emit` это не исключение - параметр
`human_renderer` был предусмотрен и до сих пор не использовался. Вопрос «что в
базе знаний» отвечается содержимым; строка «kdb: success» на него не отвечает.
Таблица идёт в stdout, поэтому `repoctl kdb > kdb.md` даёт чистый markdown.
Точка входа берётся из `spec.knowledge.entrypoint` контракта с откатом на
`kdb/kdb.yaml` - репозиторий, держащий базу в другом месте, не будет объявлен
не имеющим её.
Скилл kdb-table переписан на команду вместо вызова модуля. docs/repoctl.md
получил раздел. Спецификацию править не пришлось: закрытого перечня команд она
не содержит.
Тесты: три на CLI (таблица в stdout и находки в stderr, конверт в json, отказ с
кодом 3), плюс прежние два на разбор entrypoint. 159 passed, mypy strict чист.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
База знаний машиночитаема и длинна: чтобы ответить «что там вообще есть»,
приходилось читать файл целиком. Теперь есть отдельный вывод для человека.
- `stewardship.kdb_table` - модуль, а не файл рядом со скиллом: `skills install`
переносит только SKILL.md, поэтому скрипт в каталоге скилла не доехал бы до
репозитория, куда скилл поставили. Как модуль он доступен везде, где есть
repoctl: `python -m stewardship.kdb_table --repo <path>`.
- Путь к базе знаний не угадывается: берётся `spec.knowledge.entrypoint` из
`ops/contract.yaml` целевого репозитория, с откатом на `kdb/kdb.yaml`. Значит
работает на любом adopted-репозитории, а не только там, где путь канонический.
- Репозиторий без базы знаний получает одну строку и нулевой код возврата,
а не трейсбек.
- Читает через `stewardship.io`, то есть тем же ruamel, что и остальной код -
новой зависимости нет.
- Вне командной поверхности CLI намеренно: контракт `repoctl` - машинный вывод,
а это пособие для чтения. Спецификацию менять не пришлось.
Скилл `kdb-table` зарегистрирован в SKILLS, поэтому расходится штатным
`repoctl skills install` вместе с остальными тремя. Он тонкий: зовёт модуль,
печатает markdown как есть и отправляет за контекстом под задачу в
`repoctl context --intent`.
Проверено: 156 тестов, mypy strict чист, validate на самом репозитории success.
Два новых теста закрепляют чтение entrypoint из контракта (включая нестандартный
путь) и внятный отказ при отсутствии базы.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Каждый markdown-рендерер процентно кодирует ссылку на файл с пробелами или
не-ASCII в имени. Проверка сравнивала закодированную форму с файловой системой и
объявляла отсутствующим файл, который лежит на месте:
MARKDOWN_LINK_TARGET_MISSING: GitLab%2017.10.0%20%E2%86%92%20Docker%20Migration.md
Ложное срабатывание блокировало `validate` на репозитории Infra/Docker. Ссылка
декодируется перед резолвом; тест закрепляет и пробел, и то, что настоящая
битая ссылка по-прежнему находится.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Правило повторяющейся формы искало каталоги-братья только среди прямых детей
корня. Репозиторий, группирующий стеки по модели деплоя, держит их в
`swarm/<stack>/` — ровно ту раскладку, ради описания которой правило и
существует, оно не видело. На Infra/Docker это давало один content root
(`docs`) и ни одного упоминания 20 стеков.
- `_repeated_shape_root` -> `_repeated_shape_roots`: кандидатами в родители
становятся и корень, и каждый его прямой подкаталог; предлагаются ВСЕ
подошедшие, потому что `swarm/` и `compose/` — два разных content root,
а не конкурс между ними. Идентификатор включает путь, чтобы они не
схлопнулись в один `stacks`.
- `forbiddenChanges`: селектор по spec 6.2 читается относительно `path`, но
подставлялся в запрет как есть. Для корня на глубине это защищало не тот
уровень: `swarm/` публиковал бы `*/docker-compose.y*ml`, под который ни один
из его файлов не попадает. Теперь путь приклеивается обратно.
Тесты: три новых в test_adoption_gates.py — обнаружение под корнем, запрет на
верной глубине, два родителя одновременно. Существующий
test_two_siblings_are_not_a_repeated_shape продолжает держать порог в 3.
153 passed, mypy strict чист, repoctl validate на самом репозитории success.
Пять падений в tests-universal существовали до этого изменения и им не
затронуты — это рассинхрон спецификации с owner-гейтом, отдельная задача.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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>
The stewardship skills were written by exactly one code path: `init`, which
only runs on a new repository. Adopting an existing one starts from the
repository-adoption skill, and nothing could put that skill there -- so the
entry point to the procedure depended on the operator already having it
from somewhere else. Services/Monitoring carries three domain skills of its
own and no stewardship skill; `adopt` lists `.claude/skills` among its
collision paths and installs nothing.
repoctl skills install --repo . # travels with the repository
repoctl skills install --global # follows the operator everywhere
repoctl skills status --repo .
Scope is stated, never guessed: the two answers differ in who ends up with
the skills, and neither is the obvious default.
No plan and no approval hash. That discipline protects a repository's own
content; this writes only tool-owned files, in a fixed subdirectory, whose
content is fully determined by the installed version. The house rule it
does keep is that a write never destroys what it did not author: a skill
whose content differs is reported as SKILLS_MODIFIED and left alone until
`--force` says otherwise, and the check covers every skill before the first
byte is written, so a refusal leaves nothing half-updated.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`tests/fixtures/positive/` holds four valid contracts. Running `discover`
over the machine's Git directory returned six repositories: two real ones
and those four, with nothing in the output to tell them apart. Any
catalog-wide question -- which repositories lack an owner, which are
behind the template version -- was answered over a set that included this
project's own test material.
A repository is the root of a git repository. A directory holding
ops/contract.yaml somewhere inside another repository's working tree is
that repository's content: a fixture, an example, a vendored copy. Skip
it, and say so with CATALOG_NESTED_CONTRACT_SKIPPED rather than silently,
so a genuinely misplaced contract is still visible.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`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>
Running a full assess -> plan -> apply -> verify against Infra/LXD and
Infra/Docker in throwaway worktrees, and a bootstrap into a scratch
directory, surfaced the same two mistakes repeated across both commands:
a shape was read where evidence was available, and a missing answer became
a silent default rather than a refusal.
adopt:
- classify secret-shaped paths by content, not by filename. A live
credential blocks; a file tracked against the repository's own ignore
rules and a name-only match are warnings; findings name keys, never
values. In Infra/Docker this turned 14 false blockers into 2 true ones
and surfaced 14 files committed despite `**/.env`.
- carry assess findings into the plan and refuse while an error-severity
finding is unresolved. An owner may accept one through
`acknowledgedFindings` with a reason; the acknowledgement enters the
plan and therefore planHash, so approval covers it.
- derive metadata.name from the git remote instead of the clone directory,
and refuse to plan without a confirmed owner (runbook section 9).
- propose content roots from the whole content vocabulary rather than the
winning type's markers, and recognise N sibling directories sharing a
marker file as one file-set root with a selector, as runbook 7.2 already
specified. Authority defaulted rather than derived now asks.
init: apply the guards adopt already had. Answers are validated against
the vocabularies that already existed in constants (name, type, lifecycle,
access) so init can no longer create a repository that fails its own
validate; owners are required; a directory that already holds the planned
paths is refused at plan time and pointed at adopt; and every path from a
plan is confined before the first byte is written -- init wrote outside
the repository from an edited plan.
validate: mask fenced blocks and inline code spans before scanning for
Markdown links. A PowerShell snippet in Infra/Docker's CLAUDE.md parsed as
a link and kept validate red for a reason unrelated to the repository.
paths: allow "." as a whole content-root path, never as a segment, so the
file-set root runbook 7.2 describes can be declared.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The rule that a knowledge file's format comes from validating it, never from
the path it occupies, was applied to `kdb/kdb.yaml` and stopped there. The
first branch of _plan_knowledge declared `ops/knowledge.yaml` the entrypoint
without ever looking at its assessed action, so a repository holding a
non-conformant file at the adapter path was adopted with the contract pointing
straight at something that fails the KnowledgeBase schema -- the same defect,
one path over, with the same consequence: it surfaces only at verify and gets
repaired by hand outside the approved plan hash. assess had the answer all
along and build_plan discarded it.
Choosing the free canonical slot makes several legacy sources reachable at
once, so the generated index registers all of them rather than the first;
indexing one and dropping the rest in silence would be a new instance of the
omission runbook 11.1 exists to prevent. That also implements the table's last
row, which had no branch until now.
When both canonical paths hold non-conformant files there is no free slot and
neither occupant may be overwritten, so adoption refuses to plan. The plan
schema is closed and carries no findings field, which leaves nowhere to record
a decision left unresolved -- the same reason malformed markers raise instead
of being guessed at.
- gate the adapter branch on the assessed action, not on the file existing
- give each indexed document an id derived from its own path
- add ADOPT_KNOWLEDGE_UNRESOLVED for the dead end, and document it
- bind the four previously untested rows of 11.1 to the parametrized table
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Runbook 11.1 and 11.2 are decision tables, and nothing tied them to branches:
the two existing antivirus-legacy tests asserted only that kdb/kdb.yaml was
preserved, which stayed true while the surrounding behaviour was wrong. These
cases are parametrized over the table rows so prose and code cannot drift apart
again without a failure.
Writing them found two defects that no existing test could see. splice_managed_block
validated the file it patched but never the block being inserted, so a
hand-edited plan carrying unbalanced markers would have been written in and only
failed on a later run. And the adoption output schemas were validated nowhere,
which had let the richer content roots from the previous commit silently stop
conforming to AdoptionAssessment.
- table-driven coverage of the knowledge and agent-entrypoint rows
- path escape, forbidden path, dirty gate, rollback and preserve-tampering cases
- schema conformance for assessment, plan, report and the generated contract
- widen proposedContentRoots for writePolicy/generatedFrom, and constrain
authority to the enum it always should have used
- add a synthetic_repo fixture instead of a fourth copy of git init
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>