Commit Graph
5 Commits
Author SHA1 Message Date
Alexander BaranovandClaude Opus 5 523ef61fe3 feat(adopt): let the owner answer the type question assess asks
assess sets confirmationRequired and asks "Confirm repository type" whenever
confidence is below high, but there was no way to answer it: --answers read only
name, title, owners and lifecycle, and build_plan took the type solely from the
classifier's guess. The confirmation boundary in runbook section 9 could not be
closed through the tool, and nothing in the resulting contract distinguished a
deliberate decision from an unreviewed low-confidence default.

- accept the type via --type or a repositoryType answer, validated against the
  known set rather than written through unchecked
- record classification, confidence and evidence in metadata.annotations, which
  the schema already allows as a free-form object
- omit any timestamp so re-planning stays deterministic and planHash stable

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 18:33:42 +03:00
Alexander BaranovandClaude Opus 5 90bf25c49d feat(adopt): point an existing CLAUDE.md at the contract, and derive managedPaths
Runbook 11.2 says an existing shared entrypoint should gain a narrow managed
block rather than be replaced, but build_plan only ever chose between "create"
and "preserve", so a repository that already had CLAUDE.md was adopted without
any pointer to its own contract -- an agent kept reading the large legacy
document first, which is the cost adoption was supposed to remove. The
patch-managed-block action existed in the schema and in apply_plan with nothing
producing it.

managedPaths was hardcoded to ops/contract.yaml even though the plan already
knows every file it authors, so the contract understated what adoption owns and
the missing entries had to be added by hand afterwards.

- emit patch-managed-block for an existing CLAUDE.md, and preserve when the
  block is already current, which makes re-planning idempotent
- assemble the contract last so managedPaths is derived from the actual changes
- keep the pointer block ASCII, matching the earlier em-dash cleanup

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 18:31:53 +03:00
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 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