Commit Graph
16 Commits
Author SHA1 Message Date
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 BaranovandClaude Opus 5 e5a42fa446 test(adopt): bind the compatibility tables to code, and check apply's safety
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>
2026-08-24 18:48:54 +03:00
Alexander BaranovandClaude Opus 5 005419a0ba fix: quiet the secret scan, narrow the CLI to what exists, name unknown intents
The secret-shaped scan walked the entire tree with rglob and filtered
afterwards, so a repository with gigabytes of gitignored vendor material paid
for statting all of it, and reported findings Git had already been told to
ignore. It also reported every hit under ADOPT_SECRET_TRACKED regardless of
whether the path was tracked, so a blocker code appeared on files that were
merely present -- including an `icon-show-password.png` inside an unpacked
vendor manual. A code named TRACKED firing on untracked files teaches people to
ignore it.

--strategy normalize and --recipe were advertised by the CLI while normalize
raised unconditionally and --recipe was never read anywhere, which is the thing
AGENTS.md asks us not to do.

An unknown intent returned an empty bundle in silence, indistinguishable from a
topic that genuinely has no content -- easy to hit by passing a topic id where
an intent belongs.

- prune ignored directories during the walk; drop ignored matches; skip formats
  that cannot carry a credential
- split ADOPT_SECRET_SHAPED_UNTRACKED from the ADOPT_SECRET_TRACKED blocker
- remove the normalize choice and the dead --recipe argument
- warn CONTEXT_INTENT_UNKNOWN with the closest declared intents

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 18:44:44 +03:00
Alexander BaranovandClaude Opus 5 a4b0fa5a8b fix(adopt): weigh classification evidence, and stop calling mirrors sources
Classification counted directories that merely exist, so `docs/` -- present in
nearly every repository -- carried the same weight as `policies/` and tied the
two types against each other. That tie is why the Antivirus pilot came out as
low confidence and demanded a confirmation it did not actually need; with
weights it is high confidence on the same evidence. Ties are now explicit rather
than settled by declaration order, and reported as ADOPT_TYPE_AMBIGUOUS.

Content roots were emitted with authority "source" and writePolicy "managed"
unconditionally, which meant a repository holding both profiles-source/ and
profiles/ had its generated mirror declared a source -- precisely the error
runbook section 7.2 names as the one not to make. Learned the tool has been
producing the contract its own documentation warns against.

- weighted evidence, deterministic tie-breaking, explicit ambiguity finding
- declare a known mirror as authority mirror / writePolicy generated, with
  generatedFrom, and fall back to source only when nothing generates it here
- give roots meaningful roles instead of reusing the directory name

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 18:40:11 +03:00
Alexander BaranovandClaude Opus 5 56a42389ab fix(adopt): make verify check something
verify re-derived baselineRevision from current HEAD instead of reading the
plan's, so drift between the planned and the actual baseline was undetectable by
construction. Called without --plan -- the obvious way to call it -- it returned
empty changedPaths and preservedPaths, which reads as "adoption touched nothing"
when it means "this verified nothing"; the pilot run reported a green pass that
was entirely vacuous. None of the specific checks runbook section 13 promises
were implemented.

Learned that a preserve promise was never actually enforced: overwriting a
preserved file after apply still produced a passing report.

- take the baseline from the plan and flag divergence from HEAD
- fail on a modified preserved path, warn on changes outside the plan
- mark an unscoped report rather than letting empty lists imply success
- express all of this through unresolvedFindings, since the report schema is
  closed and widening it would be a normative change
- expand untracked directories in dirty_paths; git collapses them to "dir/",
  which never matches the file paths a plan names

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