@dzhechkov/skills-book-digitizer 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -30,7 +30,11 @@ reference (`Read` its SKILL.md) — do not restate it; ADD only the book-specifi
30
30
  ## The Knowledge Unit schema (the shared contract for the whole pipeline)
31
31
 
32
32
  ```yaml
33
- id: <book>-<chunk>-<seq> # assigned within ONE atomic chunk run (see idempotency)
33
+ id: <book>-<chunk>-<seq> # GLOBALLY UNIQUE: <chunk> MUST discriminate the chunk (e.g.
34
+ # ch05-p187), not just the chapter — a chapter split across chunks
35
+ # would otherwise collide (ch09-ku01 from two chunks) and the KB
36
+ # upsert-by-id silently drops the duplicates. Include the chunk's
37
+ # start page: `<book>-ch<NN>-p<startpage>-ku<NN>`.
34
38
  type: methodology | decision-framework | formula | heuristic | checklist |
35
39
  tradeoff-table | case-pattern | definition
36
40
  name: "Выбор топологии репликации"
@@ -52,7 +56,10 @@ For each chunk whose `watermark.extracted == false`: read `corpus/<chunk>.md`, e
52
56
  schema. **Idempotency**: `<seq>` is assigned only within one complete chunk run — write to a temp
53
57
  file, then atomically rename + set `watermark.extracted = true` together; on retry, delete partial
54
58
  output first. A changed `source_hash` invalidates that chunk's watermark AND all downstream
55
- phase watermarks.
59
+ phase watermarks. **Id uniqueness (live-run bug):** because `<seq>` restarts per chunk, the
60
+ `<chunk>` segment MUST carry a chunk discriminator (its start page) so ids stay globally unique —
61
+ otherwise a chapter split into N chunks emits N × `ku01` and the KB's upsert-by-id keeps only the
62
+ last (a 116-KU extraction collapsed to 97 rows before this fix).
56
63
 
57
64
  **Fidelity regime (the IP contract — non-negotiable):**
58
65
  - **OUTPUT LANGUAGE (pin it — one language per book):** the book's language by default — detect from
@@ -76,6 +76,16 @@ phrasings for that decision) + **hard negatives** owned by sibling skills AND by
76
76
  arsenal skills. Run them against the FULL installed catalog; require **≥80% correct activation /
77
77
  ≤10% sibling-steal** before pack assembly. A skill that can't route is a skill that never fires.
78
78
 
79
+ **The oracle MUST be an LLM judge, not embedding cosine** (live-run lesson, DDIA pack): give a
80
+ blind judge the catalog of descriptions and ask which ONE skill activates per prompt — that is
81
+ the mechanism the production router actually uses. An embedding-cosine proxy failed 0/10 on a
82
+ family of adjacent decisions, and — worse — the boundary clauses that FIX real routing
83
+ («NOT sharding (→ sibling-id)») made cosine scores *worse*: embeddings are negation-blind, so
84
+ naming the sibling pulls its prompts closer. The same descriptions scored 10/10 under an LLM
85
+ judge. Cosine is a cheap diagnostic at best; never gate on it. Descriptions that pass: lead
86
+ with the decision's UNIQUE nouns/terms, add explicit `NOT … (→ sibling)` boundary clauses, and
87
+ de-duplicate shared boilerplate vocabulary across the family.
88
+
79
89
  ## Anti-patterns
80
90
 
81
91
  | Anti-pattern | Why it fails | Instead |
@@ -84,6 +94,7 @@ arsenal skills. Run them against the FULL installed catalog; require **≥80% co
84
94
  | Bare skill ids (`partitioning-strategy`) | collide at book #2 | `<slug>-`prefix |
85
95
  | Free-typed page citations | can cite the book for invented text | compute from `derived_from` KUs |
86
96
  | Shipping without routing evals | the skill never triggers | evals + CP3.5 gate |
97
+ | Gating routing on embedding cosine | negation-blind: boundary clauses pull siblings closer | LLM-judge oracle (= production router) |
87
98
  | Claiming Validated trust | it's machine-distilled, unreviewed | trust_tier 0/1 + promote path |
88
99
 
89
100
  ## Self-check
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dzhechkov/skills-book-digitizer",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Canonical book-digitizer skill pack — 6 skills that turn an engineering book/textbook/monograph into an installable skill pack whose skills make AI coders work within the book's methodologies: digitize-book (orchestrator), book-ingest, book-knowledge-extract, book-skill-distill, book-pack-assemble, book-kb-index.",
5
5
  "license": "MIT",
6
6
  "author": "dzhechko",