| name | kb-sync |
| description | Sync task changes into a convention-driven knowledge pack (catalog.json + repos/*.md) and keep a weekly ledger of synced tasks. Manual, batch cadence — run by PM/team lead. Scans gRPC (.proto), REST (Gin), models (GORM), Makefile from source; human-gated via checkbox proposal. No prose auto-edits. |
| license | MIT |
kb-sync
Keep a source-extracted knowledge pack in sync with code after tasks land — only
numeric/structural facts (RPC / route / table counts, commands), never prose.
Runs as a weekly batch by a PM/team lead, not per task.
Convention
The project declares knowledge/.kb-sync.json:
{ "repos_glob": "1stop-*", "repo_name_prefix": "1stop-",
"repos_root": "..",
"catalog": "knowledge/catalog.json", "fact_sheets": "knowledge/repos",
"ledger": "knowledge/_sync-ledger.json", "changes": "knowledge/changes",
"tickets": "knowledge/tickets",
"task_summary_template": "knowledge/tickets/_TASK_SUMMARY_TEMPLATE.md",
"api_doc": "api.md", "update_api_md": true,
"scanners": ["proto","gin_routes","gorm_models","makefile"] }
Nếu khai tickets, apply ghi task-summary theo template vào tickets/<task>/summary.md
(frontmatter + bảng "KB đã cập nhật" máy điền; phần người để <...>). Bỏ tickets → không ghi.
Any project with this file + a pack (catalog.json + repos/*.md) can use the skill.
repos_root — nơi chứa các repo source, tương đối với workspace (thư mục cha của knowledge/). Hai topology:
- Pack sống CÙNG code (repo source là sibling của
knowledge/): bỏ qua / "." (mặc định).
- Pack là repo RIÊNG (vd
1stop-knowledge sibling với 17 repo source): đặt "repos_root": "..".
REST count: đếm theo pattern .METHOD( trong repo/router/**/*.go — khớp cách catalog được dựng (KHÔNG dùng parser Gin đầy đủ của morkit vì đếm khác → false drift).
Pre-flight
test -d "${HOME}/.claude/plugins/data/docs-hero/.venv" || { echo "ERROR: run /morkit:setup first"; exit 1; }
Flow (two steps, human gate between)
Step 1 — PROPOSE (read-only):
PY="${HOME}/.claude/plugins/data/docs-hero/.venv/bin/python"
S="${MORKIT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/kb-sync/scripts"
$PY "$S/kb_sync_propose.py" --config knowledge/.kb-sync.json --output .tmp/kb-sync-proposal.md
Hai chế độ scope:
Human gate (mặc định): open .tmp/kb-sync-proposal.md, tick [x] the facts to accept.
Step 2 — APPLY (writes only checked items):
$PY "$S/kb_sync_apply.py" --config knowledge/.kb-sync.json --proposal .tmp/kb-sync-proposal.md
Chế độ AUTO — bỏ human-gate (--yes / --accept-all): ghi MỌI mục drift mà không cần tick.
$PY "$S/kb_sync_apply.py" --config knowledge/.kb-sync.json --proposal .tmp/kb-sync-proposal.md --yes
An toàn vì chỉ ghi số tất định (parse_proto/router) + idempotent. Lưới an toàn = git diff trước khi push (thay cho checkbox). Dùng cho sync hands-free định kỳ.
- Updates
catalog.json numbers, refreshes fact-sheet provenance + number tokens,
rolls up api.md totals (if update_api_md).
- Appends a weekly
sync_run to _sync-ledger.json, marks tasks synced,
re-renders SYNC-LOG.md (with a Pending backlog + drift flags).
Guardrails
- Mặc định human-gate: apply chỉ ghi mục
[x]. Chế độ --yes/--accept-all ghi tất cả — chỉ dùng khi user chủ động chọn; lưới an toàn chuyển sang git diff trước push.
- PROPOSE never writes to the KB — only
.tmp/.
- Only numeric/structural facts sync; prose (role, gotchas) stays for fan-out.
- All KB writes go through
safe_io.resolve_within — no path escaping the declared dirs.
- git is called with an arg-list (never a shell string).
- Role: skill does not enforce "lead only" (no CLI RBAC) — convention +
synced_by in the ledger.
