Lineage Skill

Lineage Skill

Compile source material into a learning Skill that can cite the source, demonstrate the teacher's method, guide practice, correct mistakes, and gradually reduce the learner's dependence on help.

Use this method:

Capture → Cite → Compress → Connect → Codify → Coach → Practice → Consolidate → Transfer → Graduate

Preserve evidence before synthesis. Require observable learner work before mastery. Keep immutable teacher assets separate from private learner state.

Read when needed

• Pipeline, providers, schemas, recovery, and output layouts: references/runtime.md
• Session routing, attempt-first assessment, feedback, and fading: references/apprenticeship-protocol.md
• Progressive concept teaching, SVG/ASCII explanation, and the two-question check: references/micro-lesson-protocol.md
• Claim and feedback provenance: references/provenance-policy.md
• Mastery transitions and review scheduling: references/mastery-policy.md
• Graduation evidence: references/graduation-policy.md
• External learner-state boundary: references/external-learner-store-contract.md

Product invariants

• Trace teacher claims to source, lesson, timestamp, chunk, card, keyframe, or page.
• Distinguish direct_source, source_grounded_synthesis, cross_source_synthesis, mentor_inference, learner evidence, external knowledge, and unsupported content.
• Preserve conflicting sources and their conditions; never flatten disagreement into false consensus.
• Treat TeacherModel as source-supported domain behavior, not a personality or consciousness clone.
• Treat recognition, fluency, lesson completion, and one success as insufficient mastery evidence.
• Require an observable attempt before updating capability state.
• Teach one unseen capability with a plain-language model, precise explanation, useful ASCII/SVG visual, example, counterexample, and exactly two end-of-lesson questions presented together by default.
• Advance at most one mastery state per successful episode.
• Require changed-context H0 performance for transfer and delayed parallel-form success for retention.
• Keep PracticeEpisodes append-only and rebuild MasteryState from events.
• Store real learner data only in a host-provided external private directory.
• Require explicit learner approval before promoting or installing a Personal Skill.
• Keep high-risk learning educational, source-bounded, and distinct from professional qualification.

Detect source state

Choose the smallest workflow that preserves the requested evidence:

1. Raw video/audio: run capture, visual analysis for video, model-selected keyframes, distillation, audit, compilation, generation, and validation.
2. Video plus PDFs: include document parsing or reuse existing OCR.
3. Markdown/TXT/books/notes/OCR: skip media capture; build text chunks and evidence cards before compilation.
4. Existing transcripts, analyses, documents, or distillation: resume from the narrowest missing stage.
5. Existing CoursePackage 0.x: migrate to 1.0 before building teacher/runtime assets.
6. Existing CoursePackage 1.0: compile missing TeacherModel, graph, banks, MentorPackage, and Skill.
7. Multiple CoursePackages: migrate each, merge with namespaced IDs, preserve conflicts, then compile.

Do not rerun expensive capture when stable artifacts already exist and inputs have not changed.

Configure providers

Separate capability from configuration. Report missing configuration and the smallest viable fallback.

• Audio transcription: AUDIO_TRANSCRIBE_API_KEY, AUDIO_TRANSCRIBE_BASE_URL, AUDIO_TRANSCRIBE_MODEL.
• Video/vision: LINEAGE_VISION_API_KEY, LINEAGE_VISION_BASE_URL, LINEAGE_VISION_MODEL.
• Text distillation: LINEAGE_TEXT_API_KEY, LINEAGE_TEXT_BASE_URL, LINEAGE_TEXT_MODEL when LLM distillation is enabled.
• PDF/OCR submission: MINERU_API_TOKEN, unless existing OCR is reused.
• Local media: ffmpeg and ffprobe.

If raw media needs an unavailable provider, stop before that capture stage. If transcripts, OCR, notes, or packages already exist, continue from them and report excluded modalities. Never store secrets in the repository or commit .env.

Run the full compiler

For media and documents:

python scripts/run_course_pipeline.py \
  --input-dir <course-media> \
  --documents-input <pdf-or-directory> \
  --notes-input <notes> \
  --course-name <course-name> \
  --skill-name <skill-name> \
  --mode mentor \
  --apprenticeship full \
  --practice-depth deep \
  --learner-state external \
  --output-dir ./dist

For text or books:

python scripts/run_course_pipeline.py \
  --text-input <markdown-txt-or-directory> \
  --course-name <course-name> \
  --mode mentor \
  --apprenticeship full \
  --output-dir ./dist

Use --text-no-llm for deterministic explicit-label extraction. Treat implicit teacher cognition from ordinary exposition as medium/low confidence and require review.

Compile existing materials

Build or migrate CoursePackage:

python scripts/build_course_package.py \
  --course-name <course-name> \
  --source-dir <course-workspace>

python scripts/migrate_course_package.py \
  <legacy-course-package.json>

Compile the apprenticeship assets in dependency order:

python scripts/build_teacher_model.py --source-dir <course-workspace>
python scripts/build_capability_graph.py --source-dir <course-workspace>
python scripts/build_practice_bank.py --source-dir <course-workspace> --practice-depth deep
python scripts/build_assessment_bank.py --source-dir <course-workspace>
python scripts/build_mentor_package.py --source-dir <course-workspace> --apprenticeship full
python scripts/build_mentor_readiness_audit.py --source-dir <course-workspace>

Then generate and validate:

python scripts/build_course_skill.py \
  --course-name <course-name> \
  --skill-name <skill-name> \
  --mode mentor \
  --apprenticeship full \
  --learner-state external \
  --source-dir <course-workspace> \
  --output-dir ./dist

The builder uses a temporary directory and installs the target only after validation.

Merge courses

python scripts/build_multi_course_package.py \
  --course <course-a-package-or-dir> \
  --course <course-b-package-or-dir> \
  --combined-name <combined-name> \
  --output-dir <combined-workspace>

Migrate each package to an in-memory 1.0 form, namespace colliding IDs, keep source-course identity, record semantic conflicts, and route those conflicts into comparison rather than consensus.

Choose role and apprenticeship

• Default to mentor when the user wants capability formation.
• Use expert for source lookup, course Q&A, explanation, and citations.
• Use consultant for course-grounded diagnosis, option comparison, and advice.
• Use practitioner for playbooks, checklists, templates, workflows, and artifacts.
• Use custom for a user-defined source-bounded role.

Treat role, scope, evidence strategy, apprenticeship mode, and learner-state strategy as separate dimensions. Mentor requests default to full apprenticeship; downgrade to guided or none when readiness is insufficient and report every blocker.

Validate readiness

Require the following for full apprenticeship:

• valid TeacherModel with source-supported cues, decisions, demonstrations, feedback, and graduation signals;
• acyclic CapabilityGraph with complete references and prerequisites;
• at least one practice task and one assessment for each target capability;
• behaviorally anchored rubrics and ordered H0–H4 hints;
• retrieval, transfer, boundary, production, and graduation assessment coverage;
• a complete Mentor protocol and graduation policy;
• source audit that does not block core capabilities;
• no duplicate IDs, dangling references, private learner data, or empty runtime files.

Use guided mode when useful training assets exist but full teacher evidence does not. Do not hide gaps.