Skip to content

docs(glossary): SkillVersion (14th entity) + Skill Refiner brand-canon terms (0r8m.5) #181

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jeremylongshore merged 2 commits into from
Jun 20, 2026
Merged

docs(glossary): SkillVersion (14th entity) + Skill Refiner brand-canon terms (0r8m.5) #181

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
61f9a30
docs(glossary): add SkillVersion (14th entity) + 5 Skill Refiner term…
jeremylongshore Jun 20, 2026
885e6c1
docs(glossary): address CodeRabbit + Gemini review on #181
jeremylongshore Jun 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions 000-docs/014-DR-GLOS-canonical-glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@

---

## 2. The 13 canonical entities
## 2. The 14 canonical entities
Comment thread
jeremylongshore marked this conversation as resolved.

The canonical domain model is the 13-entity directed-acyclic reference graph defined in Blueprint B § 2. Each entity below carries a one-paragraph definition for glossary purposes; the **complete 10-attribute schema** (Purpose · Required fields · UUID strategy · Mutability rules · Retention policy · Replayability guarantees · Provenance requirements · Lifecycle states · Storage recommendations · Audit requirements) lives in Blueprint B § 2.N for each entity N. Cross-references in any normative doc that need the full schema **MUST** link to Blueprint B § 2.N — not redefine the schema here.
The canonical domain model is the 13-entity directed-acyclic reference graph defined in Blueprint B § 2, plus `SkillVersion` — the **14th** entity, added post-Blueprint-B by DR-028 T1 (the DISCRIMINATOR resolution, ISEDC Session 7). Each entity below carries a one-paragraph definition for glossary purposes; the **complete 10-attribute schema** (Purpose · Required fields · UUID strategy · Mutability rules · Retention policy · Replayability guarantees · Provenance requirements · Lifecycle states · Storage recommendations · Audit requirements) lives in Blueprint B § 2.N for each entity N (SkillVersion's shape is defined by the kernel `schemas/v1/skill-version.schema.json` per DR-028 T1, not Blueprint B). Cross-references in any normative doc that need the full schema **MUST** link to Blueprint B § 2.N — not redefine the schema here.

The order below matches Blueprint B's dependency order. A downstream entity may reference an upstream entity; never the reverse. Reference data (EvalSpec, MatcherMap, SkillSnapshot, FailureTaxonomy) never depends on a runtime entity.

Expand Down Expand Up @@ -145,6 +145,13 @@
- **See Blueprint B § 2.13** for the full attribute schema.
- **Common cross-references:** § 4 of this glossary for the canonical MM-1..MM-6 definitions; `JudgeDecision` (every FAIL verdict references an MM class); `MatcherMap` (also categorized by `mm_class`); `CONTRIBUTING-failure-shape.md` (the MM-7+ extension path).

### 2.14 SkillVersion
Comment thread
jeremylongshore marked this conversation as resolved.

The kernel's refinement-lineage record for a skill — the entity the Skill Refiner appends to each time it accepts an edit. Added as the **14th canonical entity** by DR-028 T1 (the DISCRIMINATOR resolution, ISEDC Session 7), so it sits outside Blueprint B § 2's original 13. **Distinct from `SkillSnapshot`** (§ 2.9): a SkillSnapshot content-addressed-pins a skill's _source state_; a SkillVersion captures the _refinement lineage_ — `version_kind` (`edit` | `revert` | `restore`, the closed signable discriminator), `parent_version_id` (SkillVersion → SkillVersion lineage, nullable for a root version), and `source_snapshot_hash` (a READ-ONLY content-hash **reference** to a SkillSnapshot, **not** a relational foreign key). It carries `refiner_strategy_id` for signed-manifest mechanism-traceability. Ships minimal per the DR-028 T1 binding-minority constraint: no lifecycle state machine and no status/signing fields (deferred to a v0.4.0 follow-up DR). Shipped in `@intentsolutions/core@0.8.0`.

Check failure on line 150 in 000-docs/014-DR-GLOS-canonical-glossary.md

View workflow job for this annotation

GitHub Actions / Vale (prose lint, advisory) 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'nullable'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'nullable'?", "location": {"path": "000-docs/014-DR-GLOS-canonical-glossary.md", "range": {"start": {"line": 150, "column": 575}}}, "severity": "ERROR"}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

- **See** the kernel `schemas/v1/skill-version.schema.json` + `src/entities/SkillVersion.ts` for the full shape (defined by DR-028 T1, not Blueprint B § 2); **Plan 027** (Skill Refiner, v5; supersedes 025) for design context.
- **Common cross-references:** `SkillSnapshot` (§ 2.9, the source state a SkillVersion references by hash); **Skill Refiner** (§ 3, the subsystem that produces SkillVersions); `EditProposal` (§ 3, the candidate change a SkillVersion records once accepted); `skill-refiner-pass/v1` (the predicate whose provenance triple references the SkillVersion id).
Comment thread
jeremylongshore marked this conversation as resolved.

---

## 3. Operational terms
Expand Down Expand Up @@ -173,6 +180,16 @@

**judge.** An LLM-as-judge or deterministic-validator function that emits a `JudgeDecision`. Judges that are deterministic produce verdicts mechanically; LLM-judges produce verdicts probabilistically with a confidence and (usually) a seed. The `verdict_source` field on a JudgeDecision declares which kind — `deterministic`, `llm_with_seed`, `llm_no_seed`, or `hybrid`. The platform discourages `llm_no_seed` because it cannot be replayed beyond statistical reconstruction. Citation: Blueprint B § 2.5.

**Skill Refiner.** The eval-guided SKILL.md improvement loop — the second product in the IS agent-rig stack (_J-Rig Skill Binary Eval_ tests, _Skill Refiner_ improves, _Rollout Gate_ ships). It proposes safe, minimal SKILL.md edits and accepts one only on a strict-improvement-on-Pareto-dominant-behavioral-with-non-regressing-others predicate (DR-028 P0-RATIFY-1), recording each accepted edit as a `SkillVersion` (§ 2.14) and emitting a signed evidence report. Ratified at ISEDC Session 7 (DR-028); delivered as a Claude Code plugin with the 3-layer hook architecture. An IS-native concept — prior art in eval-driven optimization is cited for design context only, not borrowed (DR-010 § 13.6). Citation: Plan 027 (v5); DR-028; Blueprint B § 7.
Comment thread
jeremylongshore marked this conversation as resolved.

**3-layer hooks (sinker / line / hook).** The Skill Refiner plugin's hook architecture — three coordinated Claude Code hooks named, in the fishing metaphor, **sinker** (deepest / setup), **line** (mid), and **hook** (the catch). L3 is a `PreToolUse:Bash` hook (not `PostToolUse:Bash`, per the v4.1 mechanism fix), so the Refiner intercepts before the tool runs. Citation: Plan 027 § 4; DR-028.

**EditProposal.** The Skill Refiner's term for a single candidate SKILL.md edit, generated by a RefinerStrategy before acceptance. An EditProposal is the _input_ to the acceptance gate; it becomes durable only if it clears the acceptance predicate, at which point a `SkillVersion` (§ 2.14) records the accepted change. Citation: Plan 027; DR-028 AC-13 (RefinerStrategy interface).

**ScoreRecord.** The Skill Refiner's per-attempt behavioral-score record — the measured behavioral delta plus per-named-dimension deltas a candidate `EditProposal` produces on the eval set, i.e., the data the acceptance predicate reads to decide ACCEPT / REJECT. The signed determinants of an accepted record surface in the `skill-refiner-pass/v1` predicate body (Blueprint B § 7). Citation: Plan 027; DR-028 P0-RATIFY-1.

**Skill Refiner evidence reports.** The signed, human-readable reports (Markdown + HTML) the Skill Refiner emits for each refinement run — showing the proposed edit, the behavioral deltas, the accept / reject verdict, and the `SkillVersion` lineage. They are the Refiner's analogue to the platform's other signed evidence (the unification thesis — every validator emits Evidence Bundle, DR-010 Q3). Citation: Plan 027; DR-028; Blueprint B § 7.
Comment thread
jeremylongshore marked this conversation as resolved.

---

## 4. Intentional Mapping vocabulary (MM-1..MM-6)
Expand Down
Loading