Commit Graph
9 Commits
Author SHA1 Message Date
Alexander BaranovandClaude Opus 5 5bb8914d72 fix(adopt): decide KDB treatment by content, and implement runbook 11.1
assess declared kdb/kdb.yaml conformant on the strength of its path alone and
never parsed it, so a legacy custom knowledge base was reported as
stewardship-yaml and the contract was pointed straight at a file that fails the
KnowledgeBase schema. The row of runbook 11.1 covering exactly that case -- a
legacy KDB already occupying the canonical path -- had no branch in the code at
all, and _knowledge_entrypoint could not have helped: both of its branches
returned the same literal, so the loop was dead and the answer was always
kdb/kdb.yaml.

Learned that this is what made the pilot adoption of Services/Antivirus produce
an invalid contract that only surfaced at verify, and had to be repaired by
hand outside the approved plan hash.

- classify a knowledge file by validating it against the KnowledgeBase schema
- when a legacy KDB occupies kdb/kdb.yaml, index it from a new ops/knowledge.yaml,
  preserve the original and forbid writes to it
- generate empty topics deliberately: which sections matter is not inferable
- delete _knowledge_entrypoint and derive the entrypoint from the same decision

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 18:29:07 +03:00
Alexander BaranovandClaude Opus 5 c918bd8373 fix(adopt): confine, gate and splice writes instead of overwriting blindly
apply_plan was the only path in the package that writes to disk and the only one
that skipped confined_path, so an absolute path in a hand-edited plan file
replaced the repository root outright (pathlib join semantics) and wrote
anywhere. It also treated patch-managed-block as a full-file write, meaning the
first plan to emit that action would have destroyed the target CLAUDE.md rather
than patching it -- two bugs that only stayed harmless because build_plan never
emitted the action. Learned that forbiddenChanges and the plan's own
"path-confinement" validation entry were decorative: nothing ever checked them.

- confine every change path via the existing confined_path helper
- implement real managed-block splicing between markers; refuse malformed or
  duplicated markers rather than guessing
- enforce forbiddenChanges at apply time
- re-check the worktree at apply time and refuse only when a dirty path is one
  the plan writes, leaving unrelated user edits alone
- restore rollback by what was on disk, not by what we think we finished
- add gitutil.dirty_paths/ignored; is_dirty threw the path list away
- replace the CLI's guess-the-code-from-the-message mapping with AdoptionError

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 18:25:45 +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 86dd79c8ae test: add spec-driven universal CLI suite; fix context strict + path confinement bugs
- tests-universal/ drives repoctl only as a subprocess CLI, asserting
  directly against docs/specification.md (envelope, exit codes 0-5,
  validation rules MVP, security invariants) so the same suite can judge
  any conforming implementation, including the sibling codex/repoctl-l1
  branch built independently from the same baseline.
- Running it surfaced two real bugs, both fixed:
  - `context --strict` only checked budget truncation, never stale or
    missing referenced documents, despite specification.md 19.2 defining
    exit 4 as "stale or incomplete context" (not just truncation).
  - `paths.confined_path` crashed with an unhandled WinError2 when a
    referenced path's parent directory also didn't exist, because it
    resolved a single non-existent parent with strict=True instead of
    walking up to the nearest existing ancestor.
2026-08-24 15:38:49 +03:00
Alexander BaranovandClaude Sonnet 5 64e6c2f5f5 fix: force UTF-8 stdout/stderr in repoctl and drop non-ASCII em dashes
End-to-end smoke testing of `init` and `adopt` (plan -> approve -> apply -> verify)
via subprocess surfaced a real portability bug: on Windows, sys.stdout defaults to
the console codepage rather than UTF-8 when not attached to a UTF-8 terminal, so
machine YAML/JSON output containing non-ASCII characters (an em dash in generated
skill/docstring text) could fail to decode for downstream consumers. repoctl now
reconfigures stdout/stderr to UTF-8 unconditionally in main(), and the offending
em dashes are replaced with ASCII hyphens so generated file content is unaffected
either way.

Verified via manual CLI smoke tests: full init and adopt flows (including baseline
re-check, plan-hash approval, collision rejection on re-apply, and preservation of
profiles-source/, profiles/ and legacy kdb.yaml) work end to end.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-24 15:04:11 +03:00
Alexander BaranovandClaude Sonnet 5 7286322c83 docs: self-host at L1 and ship the three Claude skill adapters
- Move ops/contract.yaml annotation from specification-only to l1-implemented and
  declare real content roots for repoctl source, schemas, tests and Claude adapters.
- Add repoctl-cli capability to provides[].
- Route repository.tooling.use and repository.handoff intents to the existing
  tooling-implementation KDB topic.
- Update README, AGENTS.md and CLAUDE.md to describe the implemented repoctl surface
  instead of a planned one, without claiming L2/L3/MCP capabilities that don't exist.
- Add .claude/skills/{repository-bootstrap,repository-adoption,repo-handoff}/SKILL.md,
  generated from the same stewardship.skills_content strings that ship inside every
  repoctl init bootstrap (no duplicated logic).

`repoctl validate --repo .` passes with zero findings after this change.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-24 15:00:34 +03:00
Alexander BaranovandClaude Sonnet 5 96d4d08230 feat: implement repoctl L1 core (models, schemas, validate, discover, context, init, adopt)
Adds the repository-stewardship Python package (src/stewardship) with:
- JSON Schemas (Draft 2020-12) for RepositoryContract, KnowledgeBase, CatalogIndex,
  ContextBundle, BootstrapPlan, AdoptionAssessment/Plan/Report, user config and the
  repoctl-result envelope.
- Safe YAML I/O, path confinement, deterministic clock and canonical-JSON hashing.
- validate: schema, ID uniqueness, path safety, KDB references, freshness, secret-shaped
  fields, shell-string detection, and Markdown frontmatter/fence/link checks.
- discover/CatalogIndex with deterministic sorting and duplicate-name detection.
- describe (contract-only) and context (intent-scoped ContextBundle with budgeted
  materialization and --strict truncation).
- init: plan-then-apply bootstrap with SHA-256 plan-hash approval, no fake domain
  artifacts, bundled Claude skills.
- adopt: assess/plan/apply/verify overlay workflow per docs/adoption-runbook.md,
  preserving legacy content roots and KDB, with baseline-hash re-check and rollback.
- argparse-based `repoctl` CLI with human/yaml/json output and spec exit codes.
- pytest suite (39 tests) covering positive/negative fixtures, discovery, context,
  bootstrap and adoption (including LXD- and Antivirus-shaped legacy layouts).

Managed with uv (.venv), ruff clean, mypy --strict clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-24 14:57:34 +03:00
Alexander Baranov 9a39b8a941 docs: baseline specification-only repository stewardship 2026-08-24 14:39:09 +03:00