ddd13e6422
Group G — markdown tech-debt cleanup (post-audit 2026-05-02).
- 36 SKILL.md files: added "## When to use" section. Was missing across the
catalog; orchestrator routing by keyword could not auto-dispatch.
- 20 code-implementer agent .md files: added Output Footer block prescribing
RULE 0.16 STATUS-TRUTH MARKER schema in agent's final report. Previously only
code-implementer-rust.md had it; other 27 language/role variants were silent
about the marker, breaking RULE 0.16 §3 status-truth aggregation for non-Rust
batches.
- skills/site-create/: added phase-5-preview.md and phase-6-deploy.md skeleton
files. SKILL.md table-of-contents referenced 7 phases; only 5 existed on disk.
- skills/{ai-animation,rag-pipeline}/skill.md: added migration banner comment
noting they should be SKILL.md (canonical filename). Case-rename via git is a
separate orchestrator task (macOS APFS is case-insensitive; Linux deploy needs
explicit rename).
- 3 deprecated skills (site-builder, competitor-analysis, design-inspiration):
added concrete removed-after dates (was vague "before v2").
- docs/CONVERGENCE-PLAN.md:129: TBD on _blocks/evidence-grading.md duplicate
resolved (file exists, not duplicated).
- docs/DNA-INDEX.md: count edits made then overwritten by auto-encyclopedia-refresh
hook during agent run. The .kei-registry-ignore files in test fixtures (Group F)
are the structural fix; kei-registry walker implementation is the follow-up.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
174 lines
10 KiB
Markdown
174 lines
10 KiB
Markdown
# Convergence Plan — KeiSeiKit Substrate Unification
|
||
|
||
**Date:** 2026-04-23
|
||
**Status:** Synthesis of two parallel convergence audits + user directive "постарайся унифицировать"
|
||
**Hypothesis (user):** "If substrate is right, the primitive count converges, not expands"
|
||
|
||
---
|
||
|
||
## Headline
|
||
|
||
| Layer | Current | After Consolidation | Cut |
|
||
|---|---|---|---|
|
||
| Atom crates | 25 | 15-17 | −36% |
|
||
| Agent capabilities | 11 | 7 | −36% |
|
||
| Skills | 39 | ~28 | −28% |
|
||
| **Total** | **75** | **~52** | **−31%** |
|
||
|
||
Less aggressive than user's gut (~35) because audit shows genuine domain-disjointness in some clusters (setup pipelines, motion/animation). User's hypothesis partially confirmed — substrate does converge, but only where LOC overlap is real. Where it isn't, we get shared blocks + preamble extraction instead.
|
||
|
||
---
|
||
|
||
## Convergence by layer
|
||
|
||
### Atoms (25 → 15-17)
|
||
|
||
Source: `docs/CONVERGENCE-AUDIT-ATOMS.md` (architect, E2).
|
||
|
||
| Consolidation | From | To | When | Effort |
|
||
|---|---|---|---|---|
|
||
| **SQLite-CRUD engine** | 6 crates (kei-chat/content/social/sage/task/crossdomain-store) | 1 `kei-entity-store` engine + 6 thin schema plugins | **parallel with Stream B** (not before) | 2-3 days |
|
||
| **Provisioner unification** | 3 shells (provision-hetzner, provision-vultr, harden-base) | 1 `kei-provision <backend>` Rust (harden-base stays — different lifecycle) | **v0.24 now** | 0.5-1 day |
|
||
| **Frontend meta-dispatcher** | 4 shells (design-scrape, live-preview, figma-tokens, frontend-inspect) | thin `kei-frontend fetch\|analyze` shim, keep 4 impls underneath | post-unlock, optional | 0.5 day |
|
||
| **4 unmapped LBM-port crates** | unknown | audit after mapping | post-unlock (2026-06-03+) | TBD |
|
||
|
||
**Evidence:** `Store::open` is byte-identical across 5 crates (`kei-chat-store/src/store.rs:13-21` et al). FTS re-index literal-same body. Deps 7-liner identical. ~500 LOC duplication removed.
|
||
|
||
**Timing constraint (RULE 0.5):** DO NOT consolidate SQLite-CRUD before Stream B atom refactor of remaining 24 crates lands. Fragment-then-aggregate dual-direction = merge hell.
|
||
|
||
### Capabilities (11 → 7)
|
||
|
||
Source: `docs/CONVERGENCE-AUDIT-CAPS.md` (critic, E2-E4).
|
||
|
||
| Consolidation | From | To | When |
|
||
|---|---|---|---|
|
||
| **scope::path-filter** | scope::files-whitelist + scope::files-denylist | `scope::path-filter { mode: include\|exclude, patterns: [...] }` | post-unlock (schema amendment) |
|
||
| **quality::cargo-green** | quality::cargo-check-green + quality::tests-green | `quality::cargo-green { verbs: [check, test, clippy, fmt] }` — future-proofs clippy + fmt | post-unlock |
|
||
|
||
**Kept separate with rationale:**
|
||
- `output::report-format` + `output::severity-grade` — different validator shapes (section headers vs per-finding enum). Merge into generic `output::validator` pushes complexity down without saving files.
|
||
- `tools::read-only` + `tools::cargo-only-bash` — different gate mechanisms (tool-name allow-list vs argv regex). Rename for clarity only: `tools::read-only` → `tools::deny-tools`, `tools::cargo-only-bash` → `tools::bash-allowlist`.
|
||
- `policy::no-git-ops` — collapse `policy::` + `safety::` namespace ONLY IF no planned `policy::` additions. Check `_manifests/*.toml` before collapsing.
|
||
|
||
**Final 7:** `safety::no-git-ops`, `safety::no-dep-bump`, `scope::path-filter`, `quality::constructor-pattern`, `quality::cargo-green`, `output::report-format`, `output::severity-grade`, `tools::deny-tools`, `tools::bash-allowlist` — actually 9 if we keep policy as safety namespace + don't merge tools. Honest count: **7-9 depending on namespace-merge decision**.
|
||
|
||
### Skills (39 → ~28)
|
||
|
||
Source: same audit.
|
||
|
||
| Consolidation | From | To | When |
|
||
|---|---|---|---|
|
||
| **/audit `<target>`** | /seo-audit + /a11y-audit + /perf-audit + /responsive-audit + /pr-review + /security-review (6) | 1 skill + checklist registry `checklists/<target>.md` | post-unlock — **largest LOC win (~50%)** |
|
||
| **Deprecate /site-builder** | /site-builder (subset of /site-create) | `[DEPRECATED: use /site-create]` header | pre-unlock |
|
||
| **Deprecate research presets** | /competitor-analysis + /design-inspiration (both are /research Phase-5 specializations) | Document as `/research --angle=competitors` / `--angle=design-refs` | pre-unlock |
|
||
| **/animate gateway** | motion-design + scroll-animation + web-effects + ai-animation | Add top-level `/animate` router (40 LOC). Keep 4 existing (domain-disjoint matrices) | pre-unlock |
|
||
|
||
**Kept separate with rationale:**
|
||
- Setup pipelines (ci-scaffold, auth-setup, observability-setup, docs-scaffold, schema-design) — block sets disjoint (`ci-*.md` vs `auth-*.md`). Unified `/scaffold <domain>` would just be a switch. Reject consolidation. Extract `_blocks/pipeline-5phase-template.md` instead.
|
||
- Motion/animation family — each has different decision matrix over different libraries. Mega-skill would be 1000+ LOC.
|
||
|
||
---
|
||
|
||
## Execution plan
|
||
|
||
### 🟢 Pre-unlock quick wins (non-breaking, ship NOW)
|
||
|
||
These land during the current schema-lock window (before 2026-05-14 for agent substrate; before 2026-06-03 for atom substrate). Zero risk of breaking the contract.
|
||
|
||
| # | Task | Effort | Locks affected |
|
||
|---|---|---|---|
|
||
| 1 | Extract `_blocks/pipeline-5phase-template.md` — shared preamble for ci/auth/obs/docs/schema pipeline skills | 0.5 day | none |
|
||
| 2 | Extract `_blocks/rule-pure-click-contract.md` — AskUserQuestion contract referenced by 5+ skills | 0.5 day | none |
|
||
| 3 | Rename capabilities for clarity (`cargo-only-bash` → `bash-allowlist`, `read-only` → `deny-tools`). Keep old names as deprecated aliases | 0.25 day | none (additive) |
|
||
| 4 | Deprecate `/site-builder` with `[DEPRECATED: use /site-create]` header | 0.1 day | none |
|
||
| 5 | Deprecate `/competitor-analysis` + `/design-inspiration` as presets pointing to `/research` | 0.1 day | none |
|
||
| 6 | Add `/animate` gateway skill (40 LOC router) | 0.25 day | none |
|
||
| **7** ✓ | **Cluster 2: Provisioner unification `kei-provision <backend>`** | **1 day** | **atom substrate — but additive, not removing existing scripts** |
|
||
|
||
**Total pre-unlock: ~3 days**. All non-breaking, all safe to parallel-agent.
|
||
|
||
### 🟡 Mid-cycle (parallel with Stream B continued refactor)
|
||
|
||
During the substrate v1 atom-lock window as remaining 24 crates get their atom layout (Stream B extension).
|
||
|
||
| # | Task | Effort |
|
||
|---|---|---|
|
||
| 8 | **Cluster 1: SQLite-CRUD engine extraction** — `kei-entity-store` + 6 plugins. Piggyback on Stream B atom decomposition | 2-3 days |
|
||
| 9 | Enumerate + audit remaining 4 v0.14 LBM-port crates not in the 6 | 0.5 day audit |
|
||
|
||
### 🔴 Post-unlock (after 2026-06-03 for atoms, 2026-05-14 for agents)
|
||
|
||
Requires schema amendment. Non-trivial validation before merging.
|
||
|
||
| # | Task | Effort | Validation required |
|
||
|---|---|---|---|
|
||
| 10 | `scope::path-filter { mode, patterns }` — merge whitelist + denylist | 1 day | Read `_assembler/src/` first to confirm capability-fragment injection supports parameterized mode |
|
||
| 11 | `quality::cargo-green { verbs }` — merge check + test + future clippy/fmt | 1 day | Same |
|
||
| 12 | `/audit <target>` with `checklists/<target>.md` registry | 2-3 days | Refactor 5 existing audit skills to data + data-driven skill shell |
|
||
| 13 | Cluster 3: `kei-frontend fetch\|analyze` meta-dispatcher (OPTIONAL) | 0.5 day | None — optional |
|
||
| 14 | Evaluate policy:: + safety:: namespace merge | 0.25 day | Check planned `policy::` additions first |
|
||
|
||
### Total estimated wall-time with parallel execution
|
||
|
||
- Pre-unlock wave: **~3 days** (7 tasks, fully parallel-safe)
|
||
- Mid-cycle: **~3 days** (piggyback timing)
|
||
- Post-unlock: **~5-6 days** (4 tasks, some parallel)
|
||
|
||
**Grand total: ~12 days over 6-week window = 4 days of my own work / week average.**
|
||
|
||
---
|
||
|
||
## Shared-block extraction (bonus, non-counted)
|
||
|
||
Not a consolidation per se — a DRY refactor. Each saved LOC is LOC that was duplicated across 5+ skills.
|
||
|
||
| Block | Extracted from | LOC saved |
|
||
|---|---|---|
|
||
| `_blocks/pipeline-5phase-template.md` | 5 pipeline skills | ~150 |
|
||
| `_blocks/rule-pure-click-contract.md` | 5+ skills | ~50 |
|
||
| `_blocks/evidence-grading.md` (already exists?) | RESOLVED 2026-05-02: file exists, not duplicated | TBD |
|
||
|
||
---
|
||
|
||
## Validation checklist before consolidation merge
|
||
|
||
Before accepting any task from §Post-unlock:
|
||
|
||
1. Read `_assembler/src/` — confirm capability-fragment injection handles parameterized mode (`mode: include|exclude`)
|
||
2. Grep all shipped manifests for dependencies on the to-be-renamed capability names
|
||
3. Grep all skills for references to deprecated skill names
|
||
4. `tests/substrate_integration.sh` passes post-change (no regression)
|
||
5. `tests/hook_wiring_integration.sh` passes post-change
|
||
6. New test for each consolidation: tempfile fixture → new unified primitive → expected behaviour both modes
|
||
|
||
---
|
||
|
||
## Honest audit gaps disclosed by agents
|
||
|
||
**Atom audit gaps:**
|
||
- Did not enumerate 4 of the 10 v0.14 LBM-port crates → Cluster 4 grade dropped from E2 to E3 for those 4
|
||
- LOC estimates ±20%
|
||
- Did not read `atoms/*.md` — if Stream B already encodes plug-in split, Cluster 1 may be partly in-flight
|
||
|
||
**Capability audit gaps:**
|
||
- Could not read `_capabilities/*.md` directly (Read tool enumeration issue) — verdicts based on manifest references + architecture doc
|
||
- C1-C5 verdicts inherit this — re-validate by reading `_assembler/src/` before schema amend
|
||
|
||
**Both audits graded E2-E4.** Not E1 (which would require running the consolidation and measuring). Take with appropriate humility.
|
||
|
||
---
|
||
|
||
## Convergence wisdom reference
|
||
|
||
**User's hypothesis was right directionally, calibrated wrong in magnitude.**
|
||
- Predicted 75 → ~35 (−53%)
|
||
- Actual 75 → ~52 (−31%)
|
||
|
||
Gap is skills: user assumed 39 → ~18, reality 39 → ~28. Why? Because domain-disjoint content (setup pipelines, motion/animation) doesn't compress via generic wrappers. It compresses via *shared preamble blocks* instead — which is a different technique (block composition vs verb parameterization).
|
||
|
||
**Distinguish:**
|
||
- **Verb parameterization** — when content is homogeneous, extract verb + param (scope::path-filter, quality::cargo-green, /audit <target>). Works when LOC overlap >50%.
|
||
- **Block extraction** — when structure is homogeneous but content heterogeneous, extract shared block and reference it (_blocks/pipeline-5phase-template.md). Works when preamble overlap >50% but body differs.
|
||
- **Subset deprecation** — when one skill is a strict subset of another (/site-builder ⊆ /site-create). Rare but clean.
|
||
|
||
All three techniques apply in this plan. Substrate doesn't always compress via the same primitive.
|