Ralph Knowledge Merge And Promotion

This skill contains the deterministic parts of Ralph-v2's knowledge pipeline.

Pipeline Tiers

• Iteration scope: iterations/<N>/knowledge/
• Session scope: knowledge/
• Workspace scope: .docs/

Preflight Gates

If auto-creation or validation fails, return blocked.

Extracted File Frontmatter

---
category: tutorials | how-to | reference | explanation
source_session: <SESSION_ID>
source_iteration: <N>
source_artifacts:
  - iterations/<N>/tasks/task-3.md
extracted_at: <ISO8601>
staged: false
staged_at: null
promoted: false
promoted_at: null
---

Merge Algorithm

EXTRACT Checklist

1. Poll signals.
2. Initialize ## Knowledge Progress if missing.
3. Run Gate 0.
4. Collect evidence from tasks, reports, plan, and review artifacts.
5. Re-poll signals.
6. Filter to reusable knowledge only.
7. Classify into exactly one Diátaxis category.
8. Write iteration knowledge files with traceability frontmatter.
9. Update iterations/<N>/knowledge/index.md.
10. Update knowledge progress.

STAGE Checklist

1. Poll signals.
2. Run Gate 1.
3. Resolve source iterations.
4. Inventory current session knowledge.
5. Merge selected iteration knowledge into session knowledge.
6. Mark source entries as staged.
7. Update knowledge/index.md.
8. Update plan-knowledge-staging.

PROMOTE Checklist

1. Poll signals.
2. Initialize knowledge progress section if needed.
3. Respect INFO + target: Librarian + SKIP_PROMOTION:.
4. Run Gate 2.
5. Read staged, unpromoted knowledge files.
6. Re-poll signals.
7. Merge into .docs/.
8. Strip staging-only frontmatter and normalize content.
9. Apply diataxis-categorizer for sub-category resolution.
10. Mark entries promoted.
11. Update knowledge/index.md and .docs/index.md.