Files
repoctl/kdb/kdb.yaml
T
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

212 lines
6.8 KiB
YAML

apiVersion: stewardship.corsus.ru/v1alpha1
kind: KnowledgeBase
metadata:
name: repository-stewardship-kdb
title: Repository Stewardship knowledge index
spec:
repository: repo:repository-stewardship
defaultLanguage: ru
topics:
- id: repository-bootstrap
title: Bootstrap a new repository
summary: Choose a repository type and create the minimal Stewardship layer without inventing domain content
intents:
- repository.initialize
- repository.bootstrap
keywords:
- init
- template
- ssh
- contract
priority: 90
documents:
- stewardship-specification
- stewardship-guide
data:
loadPolicy: headings-only
readHints:
- document: stewardship-specification
headings:
- 1. Цели и границы
- 3. Каноническое обнаружение
- 5. RepositoryContract
- 6. ContentRoot
- 17. Agent entrypoints и adapters
- 18. Bootstrap, adoption и template update
- document: stewardship-guide
headings:
- 4. Минимальная структура репозитория
- 5. Четыре типа репозиториев
- 17. Bootstrap нового и adoption существующего репозитория
- id: repository-adoption
title: Adopt an existing repository
summary: Assess, plan and apply a metadata overlay while preserving existing authoritative content
intents:
- repository.adopt
- repository.standardize
- repository.normalize
keywords:
- assess
- overlay
- legacy
- migration
priority: 100
documents:
- adoption-runbook
- stewardship-specification
- legacy-kdb-treatment
data:
loadPolicy: runbook-first
phases:
- assess
- plan
- review
- apply
- verify
readHints:
- document: adoption-runbook
headings:
- 3. Safety invariants
- 6. Phase 1 — preflight
- 7. Phase 2 — assessment
- 9. Phase 3 — confirmation boundary
- 10. Phase 4 — adoption plan
- 11. Compatibility rules
- 11.5. Normalization recipe documents-to-content-root
- 12. Phase 5 — apply
- 13. Phase 6 — verify
- 14. Finding codes
- id: stewardship-model
title: Understand or evolve the model
summary: Definitions, invariants, schemas and the reasoning behind Repository Stewardship
intents:
- repository.model.explain
- repository.model.change
- repository.standard.design
keywords:
- contract
- intent
- capability
- requirement
- binding
- kdb
priority: 80
documents:
- stewardship-specification
- stewardship-guide
- architecture-options
data:
loadPolicy: specification-first
authorityOrder:
- stewardship-specification
- stewardship-guide
- architecture-options
- id: tooling-implementation
title: Implement repoctl or an adapter
summary: Implementation boundary, commands, validation rules and harness-neutral adapter design
intents:
- repository.tooling.implement
- repository.tooling.test
- repository.tooling.use
- repository.adapter.create
- repository.handoff
keywords:
- repoctl
- parser
- schema
- validator
- skill
- mcp
priority: 85
documents:
- stewardship-specification
- adoption-runbook
- stewardship-guide
- repoctl-human-guide
data:
loadPolicy: selected-sections
readHints:
- document: stewardship-specification
headings:
- 19. Команды MVP
- 20. Validation rules MVP
- 21. Security invariants
- 22. Versioning и расширения
- 23. Порядок реализации
- 24. Acceptance criteria MVP
- document: stewardship-guide
headings:
- 14. Интерфейсы для агентов и людей
- 15. Простая первая версия
- 16. Предлагаемая внутренняя структура repoctl
- document: repoctl-human-guide
headings:
- Команды по порядку знакомства
- Коды возврата
- Устранение неполадок
- id: architecture-research
title: Revisit architecture choices
summary: Earlier alternatives, trade-offs and external design lineage
intents:
- repository.architecture.research
- repository.architecture.compare
keywords:
- architecture
- alternatives
- backstage
- gitops
- mcp
priority: 50
documents:
- architecture-options
- stewardship-specification
data:
loadPolicy: research-on-demand
readHints:
- document: stewardship-specification
headings:
- 28. Design lineage
documents:
- id: stewardship-specification
title: Repository Stewardship Protocol
role: reference
path: docs/specification.md
mediaType: text/markdown
authority: local-canonical
status: draft
- id: stewardship-guide
title: Repository Stewardship human guide
role: explanation
path: docs/guide.md
mediaType: text/markdown
authority: local-canonical
status: draft
- id: adoption-runbook
title: Repository Adoption Runbook
role: runbook
path: docs/adoption-runbook.md
mediaType: text/markdown
authority: local-canonical
status: draft
- id: architecture-options
title: Infrastructure operations architecture options
role: explanation
path: docs/research/infrastructure-operations-architecture-options.md
mediaType: text/markdown
authority: manual
status: draft
- id: legacy-kdb-treatment
title: Legacy knowledge base treatment options
role: explanation
path: docs/research/legacy-knowledge-base-treatment.md
mediaType: text/markdown
authority: manual
status: draft
- id: repoctl-human-guide
title: repoctl CLI reference for humans
role: explanation
path: docs/repoctl.md
mediaType: text/markdown
authority: local-canonical
status: draft