Course OS (SRC-1293)

Chủ dự án 08.10.2026: việc soạn một course tách thành 12 năng lực tái dùng (skill course-*). Các skill không nói với nhau bằng chữ tự do mà bằng artifact YAML có cấu trúc; workflow nằm ở doc này, tách khỏi skill; mỗi skill có version; reviewer gửi việc quay lại đúng skill cần sửa.

Doc này là canonical cho KIẾN TRÚC (registry, schema artifact, workflow, version). Chuẩn NỘI DUNG vẫn là course-design-standard.md (CD-1..CD-17); skill chỉ là quy trình và trỏ về chuẩn, không chép lại. Cửa vào cho agent: skill course-design (điều phối).

1. Mười hai skill, bốn loại

Loại	Skill	Làm gì
STRATEGY	course-architect	Định vị course: ladder, level, mã, Big Idea cấp course, khuôn lesson
STRATEGY	course-learner	Mô tả learner: tuổi, level vào, tiền kiến thức, hiểu lầm hay gặp, ràng buộc
STRATEGY	course-competency	Course Outcomes "Tôi có thể..." và năng lực đo được (CD-6, CD-10)
DESIGN	course-curriculum	Chia unit, Inquiry Frame, progression (CD-1, CD-9)
DESIGN	course-experience	Learning Cycle mỗi unit: chặng mỗi lesson (CD-8d, CD-12)
DESIGN	course-lesson	Đặc tả một lesson (CD-8)
DESIGN	course-activity	Activity và Bước của lesson, pha vòng trong (CD-8d, CD-8f)
DESIGN	course-assessment	Formative Task, Performance Task, mastery (CD-6, CD-8, CD-9)
DESIGN	course-question	Từng câu hỏi: đáp án, nhiễu bắt hiểu lầm, phản hồi (CD-8, CD-8c)
DESIGN	course-rubric	Rubric 3-5 criteria x 3 bậc (CD-9 thành phần 9)
PRODUCTION	course-content	Viết chữ learner đọc và đưa vào đường lưu thật (D1, file TS, trình sửa Dolphin)
QUALITY	course-review	Rà mọi artifact theo chuẩn, sinh review-report có skill phải chạy lại

Skill đã có, xếp vào cùng nhóm course (không đổi vai): course-design (điều phối), make-meaning-lesson (lesson mở unit, course-lesson gọi nó), content-editor (đường vào D1 của AI Teen, course-content gọi nó), lab-extract, lab-pipeline.

2. Registry

registry:
  - { id: course-architect,   version: 1.0.0, type: strategy,   input: [],                                              output: course-blueprint,    depends_on: [] }
  - { id: course-learner,     version: 1.0.0, type: strategy,   input: [course-blueprint],                              output: learner-model,       depends_on: [course-architect] }
  - { id: course-competency,  version: 1.0.0, type: strategy,   input: [course-blueprint, learner-model],               output: competency-model,    depends_on: [course-architect, course-learner] }
  - { id: course-curriculum,  version: 1.0.0, type: design,     input: [course-blueprint, competency-model, learner-model], output: curriculum-map, depends_on: [course-competency] }
  - { id: course-experience,  version: 1.0.0, type: design,     input: [curriculum-map, course-blueprint],              output: learning-experience, depends_on: [course-curriculum] }
  - { id: course-lesson,      version: 1.0.0, type: design,     input: [learning-experience, curriculum-map, learner-model], output: lesson-spec,   depends_on: [course-experience] }
  - { id: course-activity,    version: 1.0.0, type: design,     input: [lesson-spec, course-blueprint],                 output: activity-spec,       depends_on: [course-lesson] }
  - { id: course-assessment,  version: 1.0.0, type: design,     input: [competency-model, curriculum-map, lesson-spec], output: assessment-spec,     depends_on: [course-lesson] }
  - { id: course-question,    version: 1.0.0, type: design,     input: [assessment-spec, lesson-spec],                  output: question-spec,       depends_on: [course-assessment] }
  - { id: course-rubric,      version: 1.0.0, type: design,     input: [assessment-spec, competency-model],             output: rubric-spec,         depends_on: [course-assessment] }
  - { id: course-content,     version: 1.0.0, type: production, input: [lesson-spec, activity-spec, question-spec],     output: content-spec,        depends_on: [course-activity, course-question] }
  - { id: course-review,      version: 1.0.0, type: quality,    input: [any],                                           output: review-report,       depends_on: [] }

3. Nơi để artifact

Nội dung đọc được của curriculum đã sống ở docs/curriculum/<subject>/... (ví dụ docs/curriculum/genai/prompting/). Artifact của một course đặt cạnh đó:

docs/curriculum/<subject>/<course-code>/os/
  course-blueprint.yaml   learner-model.yaml   competency-model.yaml
  curriculum-map.yaml     learning-experience.yaml
  lessons/<unit-seq>-<lesson-seq>.lesson-spec.yaml
  lessons/<unit-seq>-<lesson-seq>.activity-spec.yaml
  lessons/<unit-seq>-<lesson-seq>.question-spec.yaml
  lessons/<unit-seq>-<lesson-seq>.content-spec.yaml
  assessment-spec.yaml    rubric-spec.yaml
  reviews/<YYYY-MM-DD>-<n>.review-report.yaml

Artifact là bản THIẾT KẾ; dữ liệu learner thấy vẫn ở D1 hay file TS của app. Chưa có cổng CI đọc các file YAML này; tên file và trường dưới đây là hợp đồng giữa các skill.

4. Trường chung và provenance

Mọi artifact mở bằng cùng một khối:

artifact: lesson-spec          # một trong 12 loại ở §5
course: ai-teen-1              # mã course, khớp curriculum_courses.code
produced_by: course-lesson@1.0.0
inputs:                        # artifact đã đọc, kèm version của skill sinh ra chúng
  - { artifact: learning-experience, produced_by: course-experience@1.0.0 }
status: draft                  # draft | reviewed | approved
updated: 2026-10-08

Luật version (semver của SKILL, không phải của nội dung):

• patch (1.0.x): sửa câu chữ trong skill, artifact cũ vẫn hợp lệ.
• minor (1.x.0): thêm trường TUỲ CHỌN vào output; artifact cũ vẫn đọc được.
• major (x.0.0): đổi hay bỏ trường bắt buộc; mọi artifact produced_by bản major cũ phải chạy lại skill ấy, rồi chạy lại các skill phụ thuộc theo depends_on.
• Đổi version là sửa frontmatter version: trong SKILL.md và dòng registry ở §2 trong cùng commit.

5. Schema tối giản của 12 artifact

Chỉ ghi trường BẮT BUỘC; ánh xạ về chuẩn CD và về bảng D1 thật (tra từ migrations/).

Artifact	Trường bắt buộc	Chuẩn	Bảng D1 / nơi lưu
course-blueprint	subject, ladder, level, code, name_vi, big_idea, lesson_template, unit_count	CD-1, CD-10	curriculum_courses (0084), curriculum_course_specs (0086), curriculum_course_sources
learner-model	age_band, entry_level, prerequisites[], misconceptions[], constraints[]	CD-9 (Prerequisites, Misconception Map)	curriculum_course_prereqs, curriculum_course_pains
competency-model	course_outcomes[] ("Tôi có thể..."), competencies[]{id, can_do, evidence}	CD-6, CD-10	curriculum_course_outcomes (0086)
curriculum-map	units[]{seq, name_vi, big_idea, essential_question, outcomes[], concepts[]}	CD-1, CD-9, CD-16	curriculum_units (0084), curriculum_unit_outcomes, curriculum_unit_concepts, curriculum_unit_questions
learning-experience	units[]{seq, lessons[]{seq, stage}}, stage thuộc Make Meaning, Investigate, Create, Share and Reflect	CD-8d, CD-12	AI Teen: apps/learn/src/aiTeen/lessonTemplate.ts
lesson-spec	unit_seq, seq, stage, guiding_question, lesson_outcome ("Tôi hiểu..."), concepts[], misconceptions[], interventions[]	CD-8, CD-8e	curriculum_lessons (0084), curriculum_lesson_outcomes, curriculum_lesson_concepts, curriculum_lesson_misconceptions, curriculum_lesson_interventions
activity-spec	activities[]{n, name_vi, phase, parts[]{n, step, title}}	CD-8d, CD-8f, CD-8c	AI Teen: ai_teen_content_docs (0338), journey ở apps/learn/src/aiTeen/journeys.ts
assessment-spec	formative[]{lesson, concept, targets_misconception}, performance_task{title, prompt, product}, mastery	CD-6, CD-8, CD-9	curriculum_unit_tasks (0085)
question-spec	questions[]{id, kind, stem_vi, choices[], answer, why_vi, concept, review, catches[]}	CD-8, CD-8c, CD-8f	curriculum_lesson_quiz + curriculum_lesson_quiz_choices (0204), curriculum_lesson_gate_quiz, curriculum_lesson_questions
rubric-spec	criteria[]{seq, text_vi, outcome_seq, levels{forming, meets, strong}}	CD-9 thành phần 9	curriculum_task_criteria (0085); kiểm ở workers/foundry/src/rubric.ts
content-spec	target (d1-curriculum, ai-teen-editor, ts-file), items[]{path_or_table, key, status}	CD-4, CD-7	bảng ở các dòng trên; AI Teen qua ai_teen_content_versions
review-report	findings[]{id, artifact, rule, severity, message, rerun}, verdict	mọi CD	chỉ file YAML, không vào D1

Hai trường hay sai: stage (vòng ngoài, gắn LESSON) và phase (vòng trong, gắn ACTIVITY) là hai thứ khác nhau theo CD-8d. Tên ba bậc rubric trong YAML là tiếng Anh (forming, meets, strong), nhãn hiển thị vẫn theo CD-9 (Đang hình thành, Đạt, Vững).

6. Ba workflow

workflows:
  create-course:
    steps: [course-architect, course-learner, course-competency, course-curriculum, course-experience,
            "for each lesson: course-lesson, course-activity",
            course-assessment, course-rubric, "for each lesson: course-question, course-content",
            course-review]
    loop: "review-report.findings[].rerun -> chạy lại skill ấy và mọi skill phụ thuộc, rồi course-review lại"
  create-lesson:
    requires: [curriculum-map, learning-experience]
    steps: [course-lesson, course-activity, course-question, course-content, course-review]
  revise-assessment:
    requires: [competency-model, curriculum-map, lesson-spec]
    steps: [course-assessment, course-question, course-rubric, course-content, course-review]

Workflow dừng khi review-report.verdict: pass. Quá 3 vòng review mà vẫn fail thì dừng, báo chủ dự án.

7. Để dành (giai đoạn sau)

• Evals: bộ ca kiểm tự động cho từng skill. Giai đoạn này mỗi skill chỉ ghi Quality Criteria và Failure Conditions.
• Golden Courses: một vài course mẫu đã duyệt làm chuẩn so sánh.
• Cổng CI cho schema artifact: chưa có; §5 là hợp đồng bằng chữ.
• Khung CBE (competency-based education) đầy đủ: chưa có doc trong repo ngoài trích dẫn reDesign ở SDD-043; skill không được bịa thêm khung.

Trace

Nguồn	Nội dung
SRC-1293	Course OS: 12 skill, artifact YAML, registry, workflow, version (chủ dự án 08.10.2026)