04 Distributed Role Criteria Architecture

Context

Calab.ai’s Promotion & Performance Evaluation process uses Evaluation Workbooks — one per role type and seniority level — that contain competency criteria grouped by Guild (area) and Management Practice (subarea). Currently, all criteria are monolithically embedded in 5 workbook template files under the HR Management practice (GL05 Administration Guild/Practices/HR Management/05 Templates/).

This creates several governance and scalability problems:

1. No ownership boundary: Criteria authored by the Technology Guild (e.g., Software Eng competencies) are editable by anyone with write access to the HR Management practice. There is no way for CODEOWNERS or PR review to enforce that only the relevant practice owners can modify their criteria.

2. No scalability: The career pathway defines three tracks (Engineer, Architect, Delivery Lead) with 5 seniority levels each. The current approach requires maintaining 15 monolithic workbook files with hundreds of duplicated structural elements.

3. SSOT violation: Each criterion definition is embedded in a workbook template rather than being authored at the source — the Guild that owns the competency expectation.

4. Cross-functional authority: Guilds (e.g., Sales Guild) need to define what they expect from roles owned by other guilds (e.g., Engineers in the Technology Guild), but only within their domain of authority.

Decision

We will adopt a distributed role criteria architecture where:

1. Roles belong to Guilds as primary, not to individual Management Practices. A Roles/ directory under each Guild holds role-level definitions.

2. Criteria are authored in the owning Guild’s Roles directory, grouped by role type and level. Each criteria file contains all criteria that a guild defines for a specific role and level, with criteria items stored as a YAML array in frontmatter.

3. Primary criteria (criteria defined by the guild that owns the role) are stored at 02 Guilds/[GUILD]/Roles/[ROLE TYPE]/[LEVEL].md.

4. Cross-guild criteria (criteria defined by a guild for roles it does not own) are stored at 02 Guilds/[SOURCE GUILD]/Roles/Cross-Guild/[TARGET ROLE TYPE]/[LEVEL].md.

5. Evaluation Workbooks aggregate criteria from all guilds at build/render time using a custom criteria-list code block plugin (see Decision 05), replacing the current monolithic inline fields and non-functional dataviewjs blocks.

Directory Structure

02 Guilds/
├── GL04 Technology Guild/
│   └── Roles/
│       ├── README.md
│       └── Engineer/                    ← Primary role for this guild
│           ├── L1 Engineer.md           ← Criteria from SE, Sol Arch, Plat Arch
│           ├── L2 Senior Engineer.md
│           ├── L3 Lead Engineer.md
│           ├── L4 Senior Lead Engineer.md
│           └── L5 Principal Engineer.md
├── GL02 Sales Guild/
│   └── Roles/
│       ├── README.md
│       └── Cross-Guild/                 ← Secondary criteria from this guild
│           ├── README.md
│           └── Engineer/                ← For a role owned by GL04
│               ├── L1 Engineer.md       ← Criteria from Stakeholder Mgmt
│               ├── L2 Senior Engineer.md
│               ├── L3 Lead Engineer.md
│               ├── L4 Senior Lead Engineer.md
│               └── L5 Principal Engineer.md
└── GL03 Delivery Guild/
    └── Roles/
        ├── README.md
        └── Cross-Guild/
            ├── README.md
            └── Engineer/
                ├── L1 Engineer.md       ← Criteria from Consulting, PM, BA
                ├── L2 Senior Engineer.md
                ├── L3 Lead Engineer.md
                ├── L4 Senior Lead Engineer.md
                └── L5 Principal Engineer.md

Criteria File Schema

All criteria metadata is stored in YAML frontmatter for consistency with repository conventions and programmatic queryability:

---
publish: true
page-status: draft
created: 2026-02-16
owner: guild-technology
type: role-criteria
guild: GL04 Technology Guild
role: Engineer
level: L3
level-title: Lead Engineer
criteria-type: primary
criteria:
  - id: L3-DEV01
    subarea: Software Eng Management
    criterion: >-
      Codes complex functionality across distributed applications.
  - id: L3-ARC01
    subarea: Platform Architecture Management
    criterion: >-
      Creates architectural diagrams for complex solutions.
---

CODEOWNERS Enforcement

When CODEOWNERS is activated, each guild controls its own Roles directory:

/content/02 Guilds/GL04 Technology Guild/Roles/**   @calab-ai/guild-technology
/content/02 Guilds/GL02 Sales Guild/Roles/**        @calab-ai/guild-sales
/content/02 Guilds/GL03 Delivery Guild/Roles/**     @calab-ai/guild-delivery

This ensures that the Sales Guild can only define cross-guild criteria in their own directory. They cannot modify the Technology Guild’s primary criteria for Engineers.

Consequences

Benefits

• Governance-enforced ownership: Each guild controls its own criteria definitions via file path-based permissions
• SSOT compliance: Criteria are authored at the source (the guild that owns the expectation) and aggregated into workbooks
• Scalable: Adding new role types (Architect, Delivery Lead) requires only new criteria files in the relevant guilds’ Roles directories
• Cross-functional authority: A guild can express expectations for any role type, scoped to roles that interact with their domain
• Consistent schema: YAML frontmatter aligns with all other content in the repository

Trade-offs

• More files: 15 criteria files (for the Engineer role alone) instead of 5 monolithic workbooks. Grows to 45+ files across all three career tracks.
• Indirect editing: Guild owners edit criteria in their guild’s Roles directory, not directly in the workbook they see during evaluation.
• Plugin dependency: Workbooks become dependent on the criteria-list plugin for rendering. Without the plugin, the workbook shows a raw code block (identical to the current page-list pattern).

Considered Alternatives

A. Keep Criteria in Workbooks, Add CODEOWNERS Per Section

Use CODEOWNERS at the file level but add review requirements per-section via PR review checklists.

Why not chosen: CODEOWNERS operates at the file/directory level, not per-section within a file. There is no way to enforce that only the Technology Guild can modify the “Software Eng” section within a workbook file. This would require social enforcement only.

B. Criteria Files Under Management Practice Directories

Store criteria at [Practice]/01 Policies/[Role]-[Level] Criteria.md within each Management Practice folder.

Why not chosen: This scatters criteria across 7+ practice directories for a single role/level. The aggregation plugin would need to scan the entire Practices tree. It also conflates practice-level policies with role-level criteria, violating MECE. Roles logically belong to Guilds, not to individual practices.

C. Centralised Criteria Database (Obsidian Database / .base files)

Use Obsidian’s .base database files or a single CSV/JSON criteria database.

Why not chosen: .base files have no Quartz rendering support. A central database would need a custom renderer regardless, and removes the benefit of file path-based governance. The distributed file approach with YAML frontmatter provides both queryability and governance.

Next Actions

• Implement per Plan 07 (Role Criteria and Evaluation Workbooks)
• Monitor file count growth as additional role types are added
• Revisit schema if criteria ID namespacing becomes needed

Related

• 03 Obsidian to Quartz Rendering — Established the dual-rendering plugin pattern
• 05 Criteria Aggregation Rendering — Plugin architecture for workbook aggregation
• Plan 01: Governance Model & Content Structure — Original governance model
• Plan 07: Role Criteria and Evaluation Workbooks — Implementation plan