Commit Graph
5 Commits
Author SHA1 Message Date
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