@dzhechkov/keysarium 1.3.0 → 1.5.0

package/templates/.claude/skills/knowledge-extractor/modules/02-classify.md

@@ -0,0 +1,99 @@
+# Classify Module — 7-Category Classification and Deduplication
+
+## Purpose
+
+Assign each raw finding to one of 7 categories, deduplicate across agents, and cross-reference against existing toolkit entries.
+
+## Input
+
+- Findings JSON file (from Module 01, status: `extracting` → set to `classifying`)
+- `TOOLKIT_HARVEST.md` — existing entries to check for duplicates
+- `references/artifact-categories.md` — category definitions and destination mapping
+
+## Protocol
+
+### Step 1: Load and Validate
+
+1. Read findings JSON file
+2. Verify all findings have status `raw`
+3. Set session status to `classifying`
+4. Read `references/artifact-categories.md` for category definitions
+
+### Step 2: Classify Each Finding
+
+For each finding, assign a category based on content analysis:
+
+| Category | Classification Signals |
+|----------|----------------------|
+| skills | Multi-step methodology, complete workflow, orchestrator + modules pattern |
+| commands | Starts with `/` or describes a CLI invocation, has arguments/parameters |
+| hooks | Triggered by an event, pre/post pattern, automation on lifecycle events |
+| rules | Contains "must", "never", "always", constraints, anti-pattern tables |
+| templates | Document skeleton, config file format, placeholder structure `{VAR}` |
+| patterns | Architectural approach, design strategy, topology, reusable structure |
+| snippets | Code block, function, component, < 50 lines, copy-paste ready |
+
+**Tie-breaking rules:**
+- If a finding could be both `patterns` and `skills` → prefer `patterns` unless it has modules/sub-components
+- If a finding could be both `rules` and `patterns` → prefer `rules` if it's primarily a constraint
+- If a finding could be both `templates` and `snippets` → prefer `templates` if it has placeholders, `snippets` if it's code
+
+### Step 3: Deduplicate
+
+**Cross-agent dedup:** Compare all findings pairwise within the session using this algorithm:
+
+1. **Title similarity:** Normalize titles (lowercase, strip punctuation, remove stop words). Compute token overlap ratio: `shared_tokens / max(tokens_A, tokens_B)`.
+2. **Content similarity:** Extract the first 3 non-empty lines of each finding's `content` field. Compute 3-gram set overlap (Jaccard index): `|A ∩ B| / |A ∪ B|`.
+3. **Combined score:** `similarity = title_weight * title_sim + content_weight * content_sim` where `title_weight = 0.4`, `content_weight = 0.6`.
+4. **Threshold:** If `similarity >= 0.80` → duplicate. Keep the finding with higher confidence. Set the other's status to `removed`.
+5. Log: `"Dedup: #N removed (duplicate of #M, similarity: {score})"`
+
+Note: Since an LLM is performing this comparison (not a deterministic function), the algorithm above provides guidance for consistent judgment. The orchestrator should evaluate each pair and apply the threshold consistently.
+
+**Cross-toolkit dedup:** Compare findings against existing `TOOLKIT_HARVEST.md` entries:
+1. For each finding, scan TOOLKIT_HARVEST.md section headings and first paragraphs.
+2. If a finding's title matches an existing entry name (exact or near-match after normalization):
+   - Set finding's `duplicate_of` field to the existing entry name
+   - Flag for gate G6 (will be evaluated in Module 03)
+3. Near-duplicate range (0.70-0.85 similarity): propose a MERGE instead of flagging as duplicate.
+
+### Step 4: Cross-Reference
+
+For each classified finding, check if it references or depends on existing toolkit items:
+- If finding mentions a skill name → add cross-reference link
+- If finding extends an existing pattern → note the relationship
+- Record cross-references in the finding's metadata
+
+### Step 5: Write Results
+
+1. Update each finding in the JSON file with: `category`, `status: "classified"`
+2. Update session status
+3. Return classification summary for display
+
+## Output Format
+
+The orchestrator displays classified findings grouped by category:
+
+```
+## patterns ({N} items)
+#1  [0.85] Agent Swarm Topology — parallel agents with merge pattern
+#4  [0.72] Event-Driven Pipeline — phase-to-phase data flow via files
+
+## rules ({N} items)
+#2  [0.91] Domain Detection Rule — auto-detect domain from keywords
+#7  [0.65] Regulatory Constraint — ФЗ-152 data isolation requirement
+
+## commands ({N} items)
+...
+
+## Removed by dedup: #5 (duplicate of #1), #9 (duplicate of #3)
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Everything classified as "patterns" | > 50% of findings in one category | Re-evaluate with stricter classification signals |
+| Aggressive dedup removes valid findings | High similarity but different use cases | Compare "When to use" sections, not just content |
+| Missing cross-references | Finding extends existing tool but no link | Check TOOLKIT_HARVEST.md entry names explicitly |
+| Category mismatch with source lens | extractor-rules finding classified as pattern | Lens is a hint, not a binding — classify on content |

package/templates/.claude/skills/knowledge-extractor/modules/03-gate.md

@@ -0,0 +1,150 @@
+# Gate Module — 8 Quality Gates with 2-Pass Evaluation
+
+## Purpose
+
+Evaluate each active finding against 8 quality gates using a two-pass approach: deterministic checks first (zero LLM cost), then semantic checks via haiku agent. Set finding status to `approved` or `blocked`.
+
+## Input
+
+- Findings JSON file (from user checkpoint, active findings only)
+- `references/quality-gates.md` — gate definitions, pass criteria, failure messages
+
+## Protocol
+
+### Step 1: Load Gate Definitions
+
+```
+Read: references/quality-gates.md
+```
+
+Load all 8 gate definitions with their type (deterministic/semantic) and pass criteria.
+
+### Step 2: Filter Active Findings
+
+From the findings JSON, select only findings with status `classified` (not `removed` or `merged`).
+These are the findings that survived the user checkpoint.
+
+### Step 3: Pass 1 — Deterministic Gates
+
+For each active finding, evaluate deterministic gates. These are simple checks that require no LLM:
+
+| Gate | Check Logic |
+|------|------------|
+| G1 | `finding.when_to_use` exists AND length > 10 characters |
+| G2 | `finding.when_not_to_use` exists AND length > 10 characters |
+| G5 | `finding.confidence >= 0.5` |
+| G6 | `finding.duplicate_of` is null OR empty (set by Module 02) |
+| G7 | `finding.maturity` is one of: `alpha`, `beta`, `stable` |
+
+For each gate, record the result:
+```json
+{
+  "gate_id": "G1",
+  "passed": true,
+  "evaluation_pass": "deterministic",
+  "reason": null
+}
+```
+
+If any deterministic gate fails, record the failure reason from `quality-gates.md`.
+
+### Step 4: Pass 2 — Semantic Gates
+
+For findings that passed all deterministic gates (or for all findings if you want complete gate data), evaluate semantic gates using a haiku agent:
+
+```
+Agent(
+  subagent_type="general-purpose",
+  model="haiku",
+  description="Harvest Gate Evaluator — semantic gates",
+  prompt="""
+    You are a quality gate evaluator. For each finding below, evaluate 3 semantic gates.
+    Be strict but fair. Err on the side of blocking rather than passing questionable findings.
+
+    ## Gates to Evaluate
+
+    **G3 — Decontextualized:**
+    Check if the finding contains project-specific references: variable names, file paths,
+    company names, dates, slugs, or any hardcoded values tied to the source project.
+    PASS if the finding is generic and reusable as-is.
+    FAIL if any project-specific detail remains.
+
+    **G4 — Concrete Example:**
+    Check if the finding includes at least one concrete, actionable example.
+    The example must show actual usage, not just describe it abstractly.
+    PASS if there is a real example with specifics.
+    FAIL if the example is vague, abstract, or missing.
+
+    **G8 — Brutal Honesty Review:**
+    Ask yourself: "Would a senior engineer actually find this useful in a different project?"
+    PASS only if the answer is genuinely yes — the finding adds real value.
+    FAIL if the finding is obvious, trivial, or too niche to be broadly useful.
+
+    ## Findings to Evaluate
+
+    {FINDINGS_LIST}
+
+    ## Required Output Format
+
+    For each finding, return:
+
+    Finding #N:
+    - G3: PASS/FAIL — [reason]
+    - G4: PASS/FAIL — [reason]
+    - G8: PASS/FAIL — [reason]
+  """
+)
+```
+
+### Step 5: Set Approval Status
+
+For each finding:
+- If ALL 8 gates passed → status = `approved`
+- If ANY gate failed → status = `blocked`, record failing gate IDs
+
+Write results to findings JSON.
+
+### Step 6: Report Blocked Findings
+
+The orchestrator displays blocked findings to the user:
+
+```
+✅ APPROVED: {N} findings passed all gates
+
+⚠️ BLOCKED: {M} findings failed quality gates:
+  #7  — G3 (project-specific references remain: mentions "bank-kc-automation")
+  #12 — G5 (confidence 0.35 < 0.5 threshold)
+  #14 — G4, G8 (no concrete example; fails brutal-honesty review)
+
+Commands:
+• "пропусти GN для #X"  — override specific gate for specific finding
+• "ок"                   — accept blocks, proceed with approved only
+```
+
+### Step 7: Apply Overrides (if any)
+
+If user overrides a gate:
+1. Add gate ID to finding's `gate_overrides` array
+2. Recalculate: if all non-overridden gates pass → status = `approved`
+3. Log override for audit trail
+
+## Override Protocol
+
+User command: `"пропусти G3 для #7"` (override G3 for finding #7)
+
+Validation:
+- Finding #7 must exist and be `blocked`
+- G3 must be one of the failing gates for finding #7
+- **G6 (Not Duplicate) and G8 (Brutal Honesty) CANNOT be overridden** — reject override attempts for these gates
+- Record the override with timestamp
+
+Multiple overrides: `"пропусти G3,G4 для #14"` — override multiple gates at once.
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| All findings pass all gates | 100% pass rate | Haiku semantic evaluator may be too lenient — add calibration examples |
+| Gate G8 blocks everything | > 80% fail on G8 | Review extraction quality — if findings are genuinely weak, that's correct |
+| Overriding all blocked gates | User overrides every block | Advisory: suggest improving extraction rather than overriding all gates |
+| Semantic evaluator contradicts itself | G3 passes but content has project refs | Log discrepancy, flag for human review |

package/templates/.claude/skills/knowledge-extractor/modules/04-integrate.md

@@ -0,0 +1,159 @@
+# Integrate Module — Auto-Placement and Harvest Report
+
+## Purpose
+
+Place approved findings into their target directories as artifact cards, update TOOLKIT_HARVEST.md, generate the harvest report, and trigger post-harvest integrations (memory_store, dream cycles).
+
+## Input
+
+- Findings JSON file (from Module 03, approved findings)
+- `templates/artifact-card.md` — per-finding output template
+- `templates/harvest-report.md` — session report template
+- `TOOLKIT_HARVEST.md` — existing toolkit tracker
+
+## Protocol
+
+### Step 1: Load Approved Findings
+
+1. Read findings JSON file
+2. Filter findings with status `approved`
+3. Set session status to `integrating`
+4. Load artifact card template and harvest report template
+
+### Step 2: Render Artifact Cards
+
+For each approved finding, render the artifact card by filling template placeholders:
+
+| Placeholder | Source |
+|-------------|--------|
+| `{NAME}` | finding.title |
+| `{CATEGORY}` | finding.category |
+| `{MATURITY_BADGE}` | Lookup from maturity-model.md: alpha=🔴, beta=🟡, stable=🟢 |
+| `{MATURITY_LEVEL}` | finding.maturity (capitalized) |
+| `{CONFIDENCE}` | finding.confidence |
+| `{SOURCE_PROJECT}` | session.slug |
+| `{DATE}` | current date (YYYY-MM-DD) |
+| `{DESCRIPTION}` | finding.content |
+| `{WHEN_TO_USE}` | finding.when_to_use |
+| `{WHEN_NOT_TO_USE}` | finding.when_not_to_use |
+| `{EXAMPLE}` | finding.example |
+
+### Step 3: Auto-Place by Category
+
+Place each rendered artifact card according to its category:
+
+| Category | Placement Action |
+|----------|-----------------|
+| **skills** | Create `.claude/skills/{name}/SKILL.md` with the artifact card as initial skeleton. Add frontmatter (trust_tier: 0, trust_tier_label: "Advisory"). |
+| **commands** | Create `.claude/commands/{name}.md` with `$ARGUMENTS` parameter reference and the artifact card content as the command body. |
+| **hooks** | Append artifact card to TOOLKIT_HARVEST.md under `## Хуки` section. Create the section if it doesn't exist. |
+| **rules** | Create `.claude/rules/{name}.md` with the artifact card content formatted as a rule table (anti-pattern detection format). |
+| **templates** | Append artifact card to TOOLKIT_HARVEST.md under `## Шаблоны` section. |
+| **patterns** | Append artifact card to TOOLKIT_HARVEST.md under `## Паттерны` section. |
+| **snippets** | Append artifact card to TOOLKIT_HARVEST.md under `## Сниппеты` section. |
+
+**Naming convention:** Convert finding title to kebab-case for file/directory names. Max 40 characters.
+
+**Collision handling:** If a file already exists at the target path:
+- Do NOT overwrite
+- Log: "Skipped placement for #{N} — target already exists: {path}"
+- Set finding status to `approved` (not `integrated`) and flag for manual review
+
+### Step 4: Update TOOLKIT_HARVEST.md
+
+After placing all artifacts:
+
+1. Update the "Обработанные проекты" table:
+```markdown
+| Проект | Дата harvest | Извлечено артефактов |
+|--------|-------------|---------------------|
+| {slug} | {date} | {approved_count} approved / {total_count} total |
+```
+
+2. Mark checked items in the relevant sections (skills, patterns, commands, etc.)
+
+### Step 5: Generate Harvest Report
+
+Fill the harvest report template with computed metrics:
+
+| Metric | Computation |
+|--------|-------------|
+| TOTAL_EXTRACTED | Count of all findings at creation |
+| AFTER_DEDUP | Count after Module 02 dedup |
+| USER_REMOVALS | Count where status = `removed` AND not from dedup |
+| USER_MERGES | Count where merged_from is not null |
+| APPROVED_COUNT | Count where status = `approved` or `integrated` |
+| BLOCKED_COUNT | Count where status = `blocked` |
+| OVERRIDE_COUNT | Sum of all gate_overrides arrays |
+| PLACED_COUNT | Count where status = `integrated` |
+
+Display the report to the user.
+
+### Step 6: Post-Harvest Integration
+
+1. **memory_store()** — Store harvest results:
+```json
+{
+  "case_slug": "{slug}",
+  "domain": "{domain}",
+  "phase": "harvest",
+  "skill_used": "knowledge-extractor",
+  "reward": "{user_reward}",
+  "reward_label": "{label}",
+  "context": {
+    "patterns_loaded": "{count}",
+    "extractors_spawned": "{lens_list}",
+    "scope_filter": "{filter_or_null}"
+  },
+  "outcome": {
+    "artifacts_created": "{placed_files_list}",
+    "total_extracted": "{N}",
+    "total_approved": "{N}",
+    "total_placed": "{N}",
+    "gate_pass_rate": "{rate}"
+  }
+}
+```
+
+2. **Dream trigger** — Update `.keysarium/insights/trigger-state.json`:
+```json
+{
+  "event_type": "case_completion",
+  "timestamp": "ISO-8601",
+  "details": "Harvest completed for {slug}: {placed_count} artifacts placed"
+}
+```
+
+3. **Clean up** — Delete the findings JSON file ONLY after confirming all placements succeeded and the harvest report was written. If any placement failed or the report could not be generated, keep the findings JSON as a recovery artifact and log: `"Findings JSON retained at {path} — manual review needed."`
+
+### Step 7: Final Display
+
+Show the user a completion summary:
+
+```
+═══════════════════════════════════════════════════════
+✅ HARVEST COMPLETE: {SESSION_ID}
+
+Extracted: {N} → Approved: {M} → Placed: {P}
+
+Placed artifacts:
+  📁 .claude/skills/agent-swarm-topology/SKILL.md
+  📁 .claude/rules/domain-detection.md
+  📄 TOOLKIT_HARVEST.md (3 entries added)
+
+Gate pass rate: {rate}%
+Memory reward stored: {score} ({label})
+
+Run /bto-test on placed skills for promotion to Tier 2.
+═══════════════════════════════════════════════════════
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Overwriting existing files | Target file already exists | NEVER overwrite; skip and flag for manual review |
+| Placing blocked findings | Finding status is `blocked` | Only place findings with status `approved` |
+| Missing TOOLKIT_HARVEST.md sections | Section header doesn't exist yet | Create the section before appending |
+| Forgetting to update "Обработанные проекты" | Table not updated after placement | Always update as the last TOOLKIT_HARVEST.md operation |
+| Leaving findings JSON behind | Temp file not cleaned up | Delete after successful report generation |

package/templates/.claude/skills/knowledge-extractor/references/artifact-categories.md

@@ -0,0 +1,100 @@
+# Artifact Categories Reference
+
+Seven mutually exclusive categories for classifying extracted findings.
+Every finding must be assigned exactly one category before passing through the quality gates.
+If a finding spans multiple categories, split it or assign the primary category.
+
+## Category Taxonomy
+
+| Category | Destination | Description | Examples | Agent Lens |
+|----------|-------------|-------------|----------|------------|
+| skills | .claude/skills/<name>/ | Complete skill bundles (SKILL.md + modules) | New analysis methodology, reusable research approach | All lenses (cross-cutting) |
+| commands | .claude/commands/<name>.md | Slash commands for Claude Code | Pipeline phases, utility commands | extractor-commands |
+| hooks | .claude/hooks/ or TOOLKIT_HARVEST.md | Event-driven automations, pre/post hooks | Pre-commit checks, post-phase triggers | extractor-commands |
+| rules | .claude/rules/<name>.md | Constraints, quality gates, anti-patterns | Domain restrictions, naming conventions | extractor-rules |
+| templates | TOOLKIT_HARVEST.md or lib/ | Document/config structure templates | ADR template, mermaid diagram template | extractor-templates |
+| patterns | TOOLKIT_HARVEST.md or lib/ | Architecture and design patterns | Agent swarm topology, event-driven pipeline | extractor-patterns |
+| snippets | TOOLKIT_HARVEST.md | Reusable code fragments | React components, utility functions, bash one-liners | extractor-snippets |
+
+## Category Descriptions
+
+### skills
+A skill is a self-contained capability bundle that can be loaded by a Claude Code session.
+It requires at minimum a SKILL.md with trigger conditions, usage instructions, and output specification.
+Extract as a skill when the finding represents a repeatable methodology that warrants its own invocation pattern.
+Destination: create a new directory under `.claude/skills/<name>/` with SKILL.md as the entry point.
+
+### commands
+A command is a slash command definition — a markdown file in `.claude/commands/` that Claude Code exposes as `/command-name`.
+Extract as a command when the finding defines a distinct user-facing workflow step or utility.
+Destination: `.claude/commands/<name>.md`
+
+### hooks
+A hook is an event-driven automation that fires on a specific lifecycle event (session start, phase completion, file save).
+Extract as a hook when the finding describes behavior that should trigger automatically, not on user request.
+Destination: `.claude/hooks/` directory if the project uses the hooks directory convention; otherwise document in TOOLKIT_HARVEST.md under the Hooks section.
+
+### rules
+A rule is a constraint, convention, or quality gate that governs agent behavior.
+Extract as a rule when the finding specifies what agents must or must not do, regardless of context.
+Destination: `.claude/rules/<name>.md`
+
+### templates
+A template is a document or configuration scaffold with placeholders that gets filled in for each use.
+Extract as a template when the finding defines a repeatable document structure (not the content itself).
+Destination: `lib/` if it will be referenced by multiple commands; otherwise TOOLKIT_HARVEST.md under Templates section.
+
+### patterns
+A pattern is an architectural or design solution to a recurring structural problem.
+Extract as a pattern when the finding describes how to compose components or agents, not what they contain.
+Patterns are higher-level than snippets and lower-level than skills.
+Destination: `lib/` if it has widespread applicability; otherwise TOOLKIT_HARVEST.md under Patterns section.
+
+### snippets
+A snippet is a concrete, copy-paste-ready code or configuration fragment.
+Extract as a snippet when the finding is language/framework-specific code that solves one small problem.
+Destination: TOOLKIT_HARVEST.md under Snippets section, with language and framework tags.
+
+## Scope Filtering Mapping (category to agent lens for /harvest only X)
+
+When the user invokes `/harvest only <scope>`, only the corresponding extractor agent lens runs.
+All other lenses are suppressed to reduce cost and noise.
+
+| User Scope Argument | Active Agent Lenses | Categories Produced |
+|--------------------|---------------------|---------------------|
+| `skills` | ALL 5 lenses (cross-cutting) | skills |
+| `commands` | extractor-commands | commands, hooks |
+| `rules` | extractor-rules | rules |
+| `templates` | extractor-templates | templates |
+| `patterns` | extractor-patterns | patterns |
+| `snippets` | extractor-snippets | snippets |
+| `code` | extractor-snippets | snippets |
+| `all` (default) | All 5 lenses | All 7 categories |
+
+Note: hooks are produced by extractor-commands because hooks are closely related to command lifecycle automation.
+Note: skills scope spawns ALL 5 lenses because skills are cross-cutting — any lens may discover patterns worthy of promotion to a full skill bundle.
+
+## Deduplication Rules (per-category)
+
+Deduplication is applied during gate G6 (Not Duplicate). The similarity threshold is 0.85.
+Similarity is assessed by the orchestrator using structural comparison (not LLM) unless specified.
+
+| Category | Deduplication Key | Comparison Method |
+|----------|------------------|-------------------|
+| skills | Skill name + trigger conditions | Exact name match OR semantic trigger overlap |
+| commands | Command name (slug) | Exact slash-command name match |
+| hooks | Event type + trigger condition | Exact event type + condition string match |
+| rules | Rule title + first sentence of constraint | Normalized string similarity |
+| templates | Template name + section headings list | Section heading set overlap |
+| patterns | Pattern name + problem statement | Normalized string similarity on problem statement |
+| snippets | Language + first 5 non-whitespace lines | Normalized code similarity |
+
+When a near-duplicate is found (similarity 0.70–0.85), the extractor must decide:
+- If the new finding improves the existing entry (adds a section, fixes an error): propose a MERGE, not a new entry.
+- If the new finding is a different context of the same idea: add as a "variant" note under the existing entry.
+- If similarity >= 0.85: treat as duplicate, reject via G6.
+
+Merge proposals are surfaced in the harvest output as:
+```
+MERGE PROPOSAL: Finding #{X} improves existing entry "{existing_name}" — {reason}
+```

package/templates/.claude/skills/knowledge-extractor/references/maturity-model.md

@@ -0,0 +1,94 @@
+# Maturity Model Reference
+
+Three maturity levels are used to communicate how well-tested and battle-proven an extracted finding is.
+Every finding must be assigned a maturity level at extraction time. The level is surfaced in the artifact card
+and in TOOLKIT_HARVEST.md entries so consumers know how much trust to place in the finding.
+
+## Maturity Levels
+
+| Level | Label | Criteria | Badge |
+|-------|-------|----------|-------|
+| Alpha | Alpha | First extraction, untested. Used in exactly 1 project. No validation. | 🔴 |
+| Beta | Beta | Used in 2+ projects. Basic validation. May have rough edges. | 🟡 |
+| Stable | Stable | Used in 3+ projects. Proven track record. Passed /bto-test or equivalent. | 🟢 |
+
+## Promotion Protocol
+
+Promotion moves a finding from one maturity level to the next. Promotion requires evidence — it is not
+self-declared. The `/harvest` command can suggest promotion but not enforce it; the user confirms.
+
+### Alpha to Beta
+
+Required evidence (any one of the following):
+- The same pattern, rule, template, or snippet was independently observed in a second project's harvest.
+- A team member explicitly applied the finding in a second project and confirmed it worked.
+- The finding was referenced in a command or skill that was used in a second research session.
+
+Promotion action:
+1. Update the `maturity` field in the finding's TOOLKIT_HARVEST.md entry from `alpha` to `beta`.
+2. Add a `used_in` list to the entry noting the two (or more) projects.
+3. Log the promotion: `PROMOTED: "{name}" alpha -> beta — evidence: {source}`.
+
+### Beta to Stable
+
+Required evidence (ALL of the following):
+- Used in 3 or more distinct projects (verified by `used_in` list).
+- At least one of the following validation signals exists:
+  - Passed `/bto-test` Layer 2 evaluation with score >= 7.0.
+  - Has a documented test case in a `references/` or `examples/` directory.
+  - Was reviewed and approved by a second human reviewer in a harvest session.
+
+Promotion action:
+1. Update the `maturity` field from `beta` to `stable`.
+2. Record the validation signal: BTO score, test case path, or reviewer name.
+3. Add the finding to the summary table in TOOLKIT_HARVEST.md under the Stable Findings section.
+4. Log the promotion: `PROMOTED: "{name}" beta -> stable — validation: {signal}`.
+
+### Demotion Protocol
+
+A stable or beta finding may be demoted if evidence of unreliability emerges:
+- A project reports the finding caused errors or required significant modification.
+- A `/bto-test` run scores the finding below 5.0.
+
+Demotion action:
+1. Downgrade maturity by one level (stable -> beta, beta -> alpha).
+2. Add a `demotion_reason` note to the TOOLKIT_HARVEST.md entry.
+3. Log the demotion: `DEMOTED: "{name}" {from} -> {to} — reason: {reason}`.
+
+## Initial Assignment Rules
+
+1. The first extraction of any finding is ALWAYS assigned `alpha` maturity.
+2. Exception: if the finding describes a pattern that was already in use across multiple projects
+   prior to being formally extracted, it may be assigned `beta` at extraction time — but only if
+   the extractor can cite at least 2 distinct prior uses in the finding's `used_in` field.
+3. Exception: if the extracted finding is a verbatim copy of content that already exists in the
+   toolkit at beta or stable maturity (e.g., an updated version of a known pattern), inherit the
+   existing maturity level and propose a MERGE rather than a new entry.
+4. No finding may be assigned `stable` at first extraction, regardless of prior use.
+
+## Maturity in Artifact Card
+
+Every finding written to TOOLKIT_HARVEST.md includes a maturity badge in its header card.
+
+### Format
+
+```
+## [Category] — {finding_name}
+**Maturity:** [ALPHA | BETA | STABLE]
+**Confidence:** {confidence_score}
+**Used in:** {project_slug_1}, {project_slug_2}, ...
+**Validated by:** {bto_score or test_path or reviewer or "not yet validated"}
+```
+
+### Display Rules
+
+- Display maturity label in uppercase.
+- If `used_in` has only one entry, display it as `{slug} (source project)`.
+- If `validated_by` is empty, display `not yet validated`.
+- Include the maturity badge on the same line as the finding name when embedding in summary tables:
+
+```
+| {finding_name} [ALPHA] | {category} | {one-line description} |
+```
+
+- In summary tables, badge order is: STABLE first, then BETA, then ALPHA (most trustworthy at top).