Commit Graph
10 Commits
Author SHA1 Message Date
Alexander BaranovandClaude Opus 5 5b9c97fdcd 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>
2026-08-26 14:56:49 +03:00
Alexander BaranovandClaude Opus 5 c80d39cc73 feat(skills): install the agent skills into any repository
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>
2026-08-26 14:35:38 +03:00
Alexander BaranovandClaude Opus 5 c21ffceef3 fix(discover): a contract inside another repository is not a repository
`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>
2026-08-25 18:17:11 +03:00
Alexander BaranovandClaude Opus 5 1ab02a257c fix(adopt,init): decide by evidence, refuse instead of defaulting
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>
2026-08-25 18:10:59 +03:00
Alexander BaranovandClaude Opus 5 693211cee9 docs: record the open question about non-conformant knowledge bases
The adapter that adoption generates is schema-correct and inert: it is created
with empty topics on purpose, so `context` on such a repository returns an
empty bundle. That is the honest answer at apply time, but it leaves the
repository without routing indefinitely, which is the whole point of a KDB --
so whether the adapter should stay or the legacy file should be rebuilt into
one canonical index is a real open question, not a settled one.

Recorded as research rather than as a runbook change: no decision was taken and
no behaviour changed. The note argues against rebuilding, and identifies why
the adapter cannot yet grow into a replacement -- runbook 11.1 offers
`Topic.data.x-selector` as the way to index sections of a legacy source, and
build_context assembles bundles from document ids and never reads it. Until
that exists a topic can only reference a whole legacy file, so incremental
migration has nowhere to start.

Also names the question that precedes both options: whether the legacy file is
a knowledge base in a foreign format or domain data that was called kdb, which
adoption currently cannot distinguish and does not ask.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 23:26:50 +03:00
Alexander BaranovandClaude Opus 5 6c6dfb6fb6 fix(adopt): decide the adapter path by content too
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>
2026-08-24 22:56:50 +03:00
Alexander BaranovandClaude Opus 5 1974155281 docs: align the runbook with what adoption actually does
The tables in sections 11.1 and 11.2 were right and the code was wrong, so most
of this is recording how a row is decided rather than changing the rule: format
comes from validating content against the KnowledgeBase schema, never from the
path a file happens to occupy.

Section 13 promised thirteen verify checks and ran none of the specific ones.
Rather than let the list keep implying coverage that does not exist, it now
separates what L1 checks from what waits on normalization and L3, and states
plainly that an unscoped report proves nothing.

- document the managed-block markers, insertion point and idempotence
- mark normalization and its recipes as not implemented, matching the CLI
- record that migrate does not exist, which is why post-adoption edits to a
  contract currently fall outside plan/approve
- add the finding codes introduced with the safety and verify work, and explain
  why a tracked secret and an ignored one are no longer the same code
- PLAN.md: Antivirus is a Wave 1 pilot the owner adopts deliberately; LXD stays
  read-only. Normalization test row follows the feature into deferral

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 18:52:43 +03:00
Alexander Baranov 36d5d01d43 fix: accept saved result envelopes as plan files; fix docs CLI examples
apply_plan/apply_bootstrap_plan required the raw plan object, but the
natural capture workflow (repoctl ... --output json > plan.json) saves
the full result envelope, so following the documented workflow verbatim
failed the hash check. repoctl now unwraps a stored envelope's `data`
automatically (an idea worth keeping from codex/repoctl-l1's cli.py,
which had the same fallback).

Found while walking docs/repoctl.md's adopt and cross-repo examples
live end to end: two more invocation bugs in the doc itself
(`config add-root` takes a positional path, not `--path`; `--output`
must follow `config` itself, not the add-root/remove-root subaction) --
fixed and clarified in place.
2026-08-24 16:02:24 +03:00
Alexander Baranov 4fbe56d81f docs: add human-facing repoctl guide in Russian, route it via KDB
docs/repoctl.md walks a human through what repoctl is, the install-once
/ invoke-from-other-repositories model (folding in the framing already
present on the sibling codex/repoctl-l1 branch's docs/repoctl.md), each
command with real sample output, the exit-code table, and troubleshooting.
docs/specification.md stays the normative machine reference.

kdb/kdb.yaml routes the new document into the tooling-implementation
topic; README.md links it and documents running tests-universal.
2026-08-24 15:42:48 +03:00
Alexander Baranov 9a39b8a941 docs: baseline specification-only repository stewardship 2026-08-24 14:39:09 +03:00