Обзор базы знаний жил как `python -m stewardship.kdb_table` - работало, но не
как остальной инструмент. Теперь это обычная подкоманда:
repoctl kdb --repo .
Вписана в контракт, а не рядом с ним: `--output json|yaml` возвращает штатный
конверт с `stewardship/knowledge-overview@0.1` внутри, находки уходят в stderr,
коды возврата прежние (0, и 3 при отсутствии базы знаний).
Одно осознанное отличие от прочих команд: `--output human` печатает саму
таблицу, а не строку статуса. Для `emit` это не исключение - параметр
`human_renderer` был предусмотрен и до сих пор не использовался. Вопрос «что в
базе знаний» отвечается содержимым; строка «kdb: success» на него не отвечает.
Таблица идёт в stdout, поэтому `repoctl kdb > kdb.md` даёт чистый markdown.
Точка входа берётся из `spec.knowledge.entrypoint` контракта с откатом на
`kdb/kdb.yaml` - репозиторий, держащий базу в другом месте, не будет объявлен
не имеющим её.
Скилл kdb-table переписан на команду вместо вызова модуля. docs/repoctl.md
получил раздел. Спецификацию править не пришлось: закрытого перечня команд она
не содержит.
Тесты: три на CLI (таблица в stdout и находки в stderr, конверт в json, отказ с
кодом 3), плюс прежние два на разбор entrypoint. 159 passed, mypy strict чист.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
48 lines
2.0 KiB
Markdown
48 lines
2.0 KiB
Markdown
---
|
|
name: kdb-table
|
|
description: Show a repository's knowledge base (its KnowledgeBase entrypoint) to a human as a compact Markdown table of topics, intents and documents. Use when asked what is in the kdb, which topics or intents exist, where a topic routes, what can be passed to `repoctl context`, or for an overview of the knowledge base. Read-only.
|
|
---
|
|
|
|
# kdb-table
|
|
|
|
Thin wrapper. The knowledge base is machine-readable and long: reading the whole
|
|
file to answer "what is in there" is the thing this skill exists to avoid.
|
|
|
|
```bash
|
|
repoctl kdb --repo <path>
|
|
```
|
|
|
|
Like every other command it emits a result envelope; `--output human` renders
|
|
the table instead of the usual one-line outcome, and findings still go to stderr,
|
|
so piping stdout gives clean Markdown. The entrypoint is read from the
|
|
repository's own `ops/contract.yaml`
|
|
(`spec.knowledge.entrypoint`), falling back to `kdb/kdb.yaml`, so no path needs
|
|
to be guessed and the same command works on any adopted repository. A
|
|
repository with no knowledge base gets a `KNOWLEDGE_ENTRYPOINT_MISSING` warning
|
|
and exit code 3, not a traceback.
|
|
|
|
Print the Markdown it emits as-is; do not paraphrase it. Two tables:
|
|
|
|
- **topics**, by descending `priority`: id, declared intents, the documents the
|
|
topic routes to, and the top-level keys of its `data` (what facts sit inside);
|
|
- **documents**: id, path, role, status. `stale` is marked `(!)` - such a
|
|
document is out of date, and `repoctl context` warns about it when it hands
|
|
it over.
|
|
|
|
## When an overview is not what is wanted
|
|
|
|
This answers "what exists". To get only what a specific task needs, take an
|
|
intent from the Intents column and ask the tool instead:
|
|
|
|
```bash
|
|
repoctl context --repo <path> --intent <intent>
|
|
```
|
|
|
|
An unknown intent is answered with the closest known ones, so the table is
|
|
mainly for the human - an agent can afford to guess once.
|
|
|
|
## Out of scope
|
|
|
|
It neither edits nor validates the knowledge base. Schema conformance is
|
|
`repoctl validate --repo <path>`; run that after editing the entrypoint.
|