pal-e-docs

Glossary: Platform Definitions

glossary Doc

active reference
Project

Glossary: Platform Definitions

Canonical definitions for the DORA Elite AI Enterprise operating model. If a term is used in plans, SOPs, conventions, or templates, it is defined here. A stranger should be able to read this note and understand the vocabulary without asking anyone.

Enterprise

The superuser can manage the entire platform and all its projects from a single Claude Code interface, with the right context loading at the right time.
Enterprise means the system is legible (a stranger can read the docs and understand the product), auditable (every decision traces back to a reason), and operational (work continues without the founder narrating). The documentation answers questions without Lucas in the room.
Three properties make this concrete:
  • Platform-wide context loads automatically — personality, SOP index, plan index, superuser stories across all projects
  • Project-specific context loads on demand — when the superuser points at a project (via working directory or explicit signal), that project's board, roles, active phases, and skills come into focus
  • The superuser has a story in every project — not "Lucas is the founder" but specific needs per project that drive observability, prioritization, and acceptance criteria

Role Hierarchy

Role Scope Maps To Example
<strong>Superuser</strong> Platform-wide Keycloak realm admin, k8s access, all projects Lucas
<strong>Admin</strong> Per-project Keycloak client role: admin, /admin routes, CRUD ops Marcus (Westside)
<strong>Domain Role</strong> Per-project, specific Keycloak client-specific roles, scoped routes Coach, Parent, Player (Westside)
Superuser and Admin are platform-level concepts — they appear on every project page. Domain Roles are project-specific and defined only on the projects that have them.

User Story

Who uses the system, what they need, how we measure success. Section #2 on every project page (per template-project-page). User stories are organized by role from the Role Hierarchy. Each story should be specific enough to derive acceptance criteria and observability metrics.
Format: "As a [role], I can [action], measured by [metric]."
The superuser has stories in every project. Domain roles have stories only in their project.

Traceability Triangle

Every board ticket answers three questions:
  • Why are we doing this? → User story from the project page (story:X label)
  • What part of the system does it touch? → Architecture diagram (arch:Y label)
  • How is it scoped? → Plan phase (note_slug) or Forgejo issue (forgejo_issue_url)
When any leg changes, the other two must be checked for alignment. Defined in template-ticket.

Scoping Pipeline

The chain that turns an idea into deployed code. Management (Betty Sue) owns everything left of the agent spawn. Agents own everything right. The Forgejo Issue is the handoff point — by the time an agent sees it, all context, scope, and acceptance criteria are baked in.
Single entry point — all work enters as a typed Forgejo issue on a project board:
  • Feature — new capability or enhancement
  • Bug — something broke that used to work
  • Spike — investigation before scoping
  • Task — housekeeping, docs, config (no code file targets)

Three Pillars

Pillar Owns DORA Metric Project
<strong>Platform</strong> Infrastructure, DevOps, SRE, observability Deployment Frequency / MTTR pal-e-platform
<strong>Docs</strong> Knowledge system, boards, note taxonomy, product Change Lead Time pal-e-docs
<strong>Agency</strong> Process, enforcement, SOPs, agents, scoping pipeline, hooks Change Failure Rate pal-e-agency
Together, the three pillars form the DORA Elite AI Enterprise. Each pillar maps to a DORA metric and eliminates a dependency on the founder: Platform (infra runs without you), Agency (process runs without you), Docs (product intent is legible without you).

Continuous Kanban

Continuous flow, not time-boxed sprints. One board per project. Columns are statuses (backlog → todo → next_up → in_progress → qa → needs_approval → done), not time periods. Left side (backlog → next_up) is the scoping pipeline owned by Betty Sue. Right side (in_progress → done) is hook-automated. See sop-board-workflow.

Nit

A QA finding on an approved PR that isn't a blocker. Nits are bundled per PR into a single typed Forgejo issue (### Type\nNit-Bundle) on the relevant repo. The issue auto-syncs to the project board's backlog. During triage, Betty Sue can segment individual nits into separate issues if warranted. The plan Epilogue references the nit-bundle issue for provenance but is not the tracking mechanism. See template-issue-nit-bundle.

Issue Types

Type When Template
<strong>Feature</strong> New functionality, enhancements, planned work <code>template-issue-feature</code>
<strong>Bug</strong> Broken behavior, regressions, alert-driven fixes <code>template-issue-bug</code>
<strong>Spike</strong> Unclear scope, needs investigation, time-boxed <code>template-issue-spike</code>
<strong>Nit-Bundle</strong> QA nits from an approved PR, bundled for triage <code>template-issue-nit-bundle</code>
  • template-project-page — project page structure (User Stories at position #2)
  • template-ticket — board ticket structure (traceability triangle labels)
  • template-issue — canonical issue design principle
  • sop-board-workflow — continuous kanban column semantics
  • agent-workflow — management/execution layer boundary
  • dora-framework — DORA metric mapping