LEARN

Without a canonical skills ledger, every promotion conversation devolves into anecdote: "Mai is good at React, right?" — followed by selective memory. With a skills ledger that's evidence-backed (every mastery-level claim ties to a project artifact, a KB post, a cert, or a peer endorsement), the conversation is "Mai's React mastery is at level 4, evidenced by these 3 projects and these 2 KB posts — does the council agree?" The Hội đồng Chuyên môn institutionalises that question and writes the answer down. The VP roll-up turns "contribution" from a feeling into a number that REW can use to weight profit-share fairly. None of this is automatic — humans always decide promotions — but the data substrate makes the decisions explainable, defensible, and (per EU AI Act Art. 13) transparent.

LEARN is also a sabbatical-eligibility partner: the "every 5 continuous years" tick from HR is the time component; LEARN supplies the qualitative side (knowledge-share post, sabbatical readiness review). Together they decide whether a Member is ready to take their accrued sabbatical now or refine the plan.

Every cell traces back to PRD §9.15 and SRS §4.15.

LEARN is one Rust service with four surfaces (GraphQL subgraph for skill/profile/VP reads, REST admin for council + parameter publishes, MCP narrator surface for the CUO/CHRO-skill, NATS event publisher for VP recompute triggers). The Council Vault is a separate Postgres schema with stricter row-level security — only the LEARN admin role can read per-judge rows; HR's role cannot.

Internal components

The schema splits into two zones: the public zone (skill, mastery, VP, promotion case header) readable by HR with appropriate scopes; and the Council Vault (per-judge votes, individual feedback) which only LEARN admin can read. The boundary is enforced at the Postgres role level — HR's read role lacks SELECT on vault tables.

VP roll-up formula (versioned · deterministic)

// Pure function. Versioned via parameter_version_id.
// Same inputs → same vp_total. Forever.

fn compute_vp(
    masteries: &[MasteryClaim],   // accepted only
    projects:  &[ProjectContribution],
    kb_posts:  &[KbAuthorship],
    params:    &VpWeights,         // versioned
) -> VpSnapshot {
    let mastery_score = masteries.iter()
        .map(|m| m.level as f64 * params.discipline_weight(m.discipline) * params.skill_weight(m.skill))
        .sum::<f64>();
    let project_score = projects.iter()
        .map(|p| p.contribution_score * params.project_weight(p.project_kind))
        .sum::<f64>();
    let kb_score = kb_posts.iter()
        .map(|k| params.kb_weight(k.post_kind))
        .sum::<f64>();
    let vp_total = mastery_score + project_score + kb_score;
    VpSnapshot {
        vp_total,
        vp_by_engineering: subscore(masteries, "engineering"),
        vp_by_design:      subscore(masteries, "design"),
        // …
        parameter_version_id: params.id,
        computed_at: input_clock(),  // input, not wall clock
    }
}

Three surfaces — GraphQL for skill / mastery / VP reads, REST admin for council + parameter writes, MCP narrator surface for the CUO/CHRO-skill. Per-judge data is never resolvable from any surface.

GraphQL subgraph

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@requiresScopes"])

type MasteryClaim @key(fields: "id") {
  id: ID!
  memberId: ID!
  skill: Skill!
  level: Int!
  status: MasteryStatus!
  evidence: [Evidence!]!
  endorsements: [Endorsement!]!
  claimedAt: DateTime!
}

type Skill @key(fields: "code") {
  code: String!
  disciplineCode: String!
  displayName: String!
  weight: Float!
}

type VpSnapshot {
  memberId: ID!
  vpTotal: Float!
  vpByEngineering: Float!
  vpByDesign: Float!
  vpByOps: Float!
  vpByBiz: Float!
  parameterVersionId: ID!
  computedAt: DateTime!
}

type PromotionCase @key(fields: "id") {
  id: ID!
  memberId: ID!
  currentLevel: String!
  targetLevel: String!
  status: PromotionStatus!
  outcome: PromotionOutcome  # summary-only
  openedAt: DateTime!
  closedAt: DateTime
}

type PromotionOutcome {
  aggregateScore: Int!  # median
  recommendation: PromotionRecommendation!
  summary: String!
  # NOTE: no per-judge data exposed here
}

enum MasteryStatus { CLAIMED ENDORSED COUNCIL_REVIEWED REJECTED }
enum PromotionStatus { DRAFT SUBMITTED COUNCIL_ASSIGNED IN_REVIEW RECOMMENDED APPROVED PROMOTED REJECTED }
enum PromotionRecommendation { ADVANCE HOLD REFINE }

type Query {
  myMasteries: [MasteryClaim!]!
  memberMasteries(memberId: ID!): [MasteryClaim!]! @requiresScopes(scopes: [["learn.read"]])
  myVp: VpSnapshot!
  memberVp(memberId: ID!): VpSnapshot! @requiresScopes(scopes: [["learn.vp_read"]])
  myPromotionCases: [PromotionCase!]!
  promotionCase(id: ID!): PromotionCase  # outcome only; per-judge inaccessible
  careerPath(memberId: ID!, targetLevel: String!): [CareerStep!]!
  skills(discipline: String): [Skill!]!
}

type Mutation {
  claimMastery(skillCode: String!, level: Int!, evidenceRef: String!): MasteryClaim!
  endorseMastery(claimId: ID!, supportLevel: Int!, note: String): Endorsement!
  submitPromotionCase(targetLevel: String!): PromotionCase!
  uploadCertificate(input: CertificateInput!): Certification!
}

REST admin surface

MCP tool catalogue (narrator + recommender · read-only)

Flow 1 — Skill registration + mastery claim

Flow 2 — Mastery-level upgrade with peer endorsement

Flow 3 — Promotion request (full Hội đồng Chuyên môn workflow)

Flow 4 — VP recompute (deterministic · monthly)

Flow 5 — Certification expiry surface

A promotion case traverses seven states. Once the parameter_version is snapshotted at submission, the gate criteria for THIS case are immutable — even if the parameters are updated mid-review, this case is judged by the original criteria.

Promotion gate criteria — example (L2 → L3 engineering)

PRD §11.2.5 (usability / explainability) and §11.2.3 (security) bind on LEARN. Cross-referenced at nfr-catalog.html#learn.

LEARN reads contribution data from PROJ + TIME + KB, identity from HR, and gates by AUTH. Its VP outputs feed REW; its promotion outcomes feed HR (and indirectly REW for the compensation_change).

LEARN is in EU AI Act high-risk scope because promotion is employment-decision automation. Same Annex III §4 classification as REW.

Per-judge data leakage and council bias are the principal risks tracked in the risk register.

LEARN health rolls up into 9 KPIs across throughput, integrity, and fairness.

LEARN is operationally owned by HR/Ops; accountable to CHRO (P3 seat); CEO is the final promotion approver.

Admin CLI cyberos-learn for HR/Ops + members.

1. Claim a mastery level

$ cyberos-learn mastery claim --skill react --level 4 \
    --evidence "proj://e-commerce-app"

[claim created]
  id:        01HZJ8…
  skill:     react (engineering)
  level:     4 (current 3)
  status:    claimed (awaiting endorsements ≥ 2)
[audit]    brain seq=15201

2. Endorse a peer

$ cyberos-learn endorse \
    --member mai@cyberskill.com \
    --skill react \
    --support-level 4 \
    --note "led the e-commerce redesign; mentored 2 juniors"

[endorsement recorded]
  endorser:  hoa@cyberskill.com
  endorsee:  mai@cyberskill.com
  skill:     react @ level 4
[claim]   status moved: claimed → endorsed (2 endorsements at target level)
[audit]   brain seq=15211

3. Read your career path

$ cyberos-learn career-path --target L3

[career path: L2 → L3 · engineering]

✓ VP total ≥ 140         (current: 152)
✓ 3 skills at mastery ≥ 4 (react ★4, postgres ★4, k8s ★4)
✓ Lead role on ≥ 1 project (e-commerce-app)
✓ 5 endorsements (current: 7)
✗ Council median ≥ 4     (not yet started)
✓ Time in level ≥ 18 mo  (current: 21 mo)

[ready to submit promotion case]

4. Submit a promotion case

$ cyberos-learn promotion submit --target L3

[case created]
  id:                  01HZJ9…
  target_level:        L3
  parameter_version:   2026.04 (snapshotted)
  status:              submitted
  HR notified for panel assignment.
[audit]   brain seq=15221

5. Assign a council panel (HR/Ops)

$ cyberos-learn council assign \
    --case 01HZJ9… \
    --judges hoa@…,linh@…,thanh@…,nam@…,minh@… \
    --chair hoa@…

[panel assigned] 5 judges + chair
[diversity check] 3 teams, 2 genders, 2 levels — heuristic ✓
[audit]   brain seq=15231

6. Read promotion outcome (outcome-only · no per-judge)

$ cyberos-learn promotion outcome --case 01HZJ9…

[case 01HZJ9… · mai@cyberskill.com · L2 → L3]
  status:           recommended
  aggregate_score:  4 / 5 (median)
  recommendation:   ADVANCE
  summary:          "Strong evidence on React mastery, postgres, k8s.
                    Two judges noted leadership growth across 2 quarters.
                    All criteria met. Recommended for advance."

[per-judge data not exposed — vault-isolated]

7. VP recompute (admin)

$ cyberos-learn vp recompute --member mai@cyberskill.com

[recomputing VP for mai@cyberskill.com]
[inputs] mastery=12 claims · proj=4 contributions · kb=3 posts · time=180d
[kernel] pure fn · 0 I/O · 0 randomness
[result]
  vp_total:           152.4
  vp_by_engineering:  118.0
  vp_by_ops:           24.4
  vp_by_biz:           10.0
[params] version 2026.04
[snapshot] vp_snapshot row written
[audit]   brain seq=15241