/ UBIQUITOUS_LANGUAGE.md
UBIQUITOUS_LANGUAGE.md
1 # KB-Dashboard — Ubiquitous Language & Vocabulary 2 3 > **Purpose:** This document defines the canonical terms, concepts, and 4 > relationships used throughout KB-Dashboard. It covers two domains: 5 > 6 > - **Project domain** — terms specific to KB-Dashboard's data model, 7 > architecture, and deployment (Project, Snapshot, Scanner, Card, Public 8 > build, Grep guard). 9 > - **Framework heritage** — terms inherited from `@YackShavingSkill` that 10 > govern how KB-Dashboard's work is planned, executed, and reviewed 11 > (Pre-Flight, Tier, Scope Adherence, Adherence Report). KB-Dashboard is the 12 > framework's designated trial consumer per [`CLAUDE.md`](CLAUDE.md) 13 > §Project Definition of Done. 14 > 15 > All code, documentation, plan artifacts, and session journals should use 16 > these terms consistently to eliminate ambiguity and ensure shared 17 > understanding. 18 19 --- 20 21 ## Table of Contents 22 23 ### Project domain 24 25 1. [Domain entities](#1-domain-entities) 26 2. [Lifecycle states](#2-lifecycle-states) 27 3. [Data model terms](#3-data-model-terms) 28 4. [Process layout](#4-process-layout) 29 5. [Public build & privacy](#5-public-build--privacy) 30 6. [Deployment](#6-deployment) 31 32 ### Framework heritage 33 34 7. [Foundational framework concepts](#7-foundational-framework-concepts) 35 8. [Skill modules](#8-skill-modules) 36 9. [Orchestration & complexity](#9-orchestration--complexity) 37 10. [Reflection artifacts](#10-reflection-artifacts) 38 11. [Verification & review](#11-verification--review) 39 40 ### Cross-cutting 41 42 12. [Repository structure](#12-repository-structure) 43 13. [Relationships & glossary](#13-relationships--glossary) 44 45 --- 46 47 ## 1. Domain entities 48 49 | Term | Definition | Usage notes | 50 |------|-----------|-------------| 51 | **Project** | A row in the `projects` PocketBase collection. The unit of work the dashboard surfaces — typically a folder under `$PROJECTS_ROOT` with its own git history. Identified by a unique `slug`. | "Register the project as a row in `projects`." | 52 | **Snapshot** | A row in `project_snapshots`. Append-only, point-in-time record of a Project's derived stats (`commit_count`, `last_commit_*`, `loc`, `language_breakdown`, issue counts). | Scanner-write only; never edited manually. | 53 | **Card** | The dashboard's UI element rendering one Project plus its latest Snapshot. The visual unit a user sees. | "The card shows commit velocity over the last 30 days." | 54 | **Scanner** | The Bun script that reads filesystem state per Project (`git`, `rad`, `tokei`) and writes Snapshots. Triggered by launchd timer or manual refresh button. | One of the three local processes. | 55 | **Source repo** | The git or Radicle repository that a Project's `path` points to. The Scanner reads its history; the dashboard never modifies it. | Read-only by construction. | 56 | **Scan run** | One invocation of the Scanner across all Projects. Produces 0 or more Snapshots and 0 or more `scan_errors` rows. | "Last scan run completed at 14:30." | 57 | **Project registry** | The `projects` collection viewed as a whole — the authoritative list of what KB-Dashboard knows about. | Edited only via the PocketBase admin UI. | 58 59 --- 60 61 ## 2. Lifecycle states 62 63 ### 2.1 Project status 64 65 The `status` enum on a Project. Drives card appearance and inclusion in the public build. 66 67 | Value | Meaning | Public-build visibility | 68 |-------|---------|------------------------| 69 | `active` | Currently being worked on; recent commits expected. | Visible (when `public=true`) | 70 | `idle` | Not actively worked on but not abandoned. May be relevant later. | Visible (when `public=true`) | 71 | `stuck` | Blocked or has unresolved problems. `stuck_reason` is populated. | **Always filtered out** | 72 | `done` | Complete; no further work planned. Stable artifact. | Visible (when `public=true`) | 73 | `archived` | Retired. Kept for historical reasons. | **Always filtered out** | 74 75 ### 2.2 Card freshness 76 77 Derived from Snapshot timestamps and `scan_errors`; not stored on the Project. 78 79 | State | Condition | Visual | 80 |-------|-----------|--------| 81 | **Fresh** | Latest Snapshot < 1h old; no recent `scan_errors` | Default card appearance | 82 | **Stale** | Latest Snapshot > 24h old | Desaturated card + clock glyph | 83 | **Broken** | Most recent scan attempt produced a `scan_errors` row | Red dot + tooltip with error kind | 84 85 --- 86 87 ## 3. Data model terms 88 89 | Term | Definition | 90 |------|-----------| 91 | **Manual field** | A column on `projects` written only via the PocketBase admin UI. Examples: `name`, `path`, `notes`, `public_description`, `status`. | 92 | **Derived field** | A column on `project_snapshots` written only by the Scanner. Examples: `commit_count`, `loc`, `last_commit_at`. | 93 | **Latest snapshot** | The most recent row in `project_snapshots` for a given Project, ordered by `scanned_at desc`. The dashboard joins this with the Project for rendering. | 94 | **`PROJECTS_ROOT`** | Environment variable holding the absolute filesystem prefix that Project `path` values are relative to. | 95 | **Skip-if-identical dedupe** | Scanner optimization: insert a new Snapshot only if any derived value differs from the prior latest Snapshot. Prevents the snapshots table from doubling without new data. | 96 | **Scan error** | A row in `scan_errors`. Local-only; never appears in the public build. Records a per-project failure during a scan run. | 97 | **Append-only collection** | A collection whose rows are only inserted, never updated. `project_snapshots` is the canonical example — preserves history by structure, not policy. | 98 | **Allowlisted column** | A field on `projects` or `project_snapshots` that the Public mapper has been explicitly authorized to expose in the public build. | 99 100 --- 101 102 ## 4. Process layout 103 104 KB-Dashboard runs three local processes (per [`grilling-session.org`](grilling-session.org) §Architecture). Each owns one job; they communicate via PocketBase's REST API. 105 106 | Process | Command | Address | Role | 107 |---------|---------|---------|------| 108 | **PocketBase** | `bun run pb` | `127.0.0.1:8090` | Source of truth + admin UI + REST API | 109 | **Scanner** | `bun run scan` | none (CLI) | Reads `git`/`rad`/`tokei` per Project; upserts Snapshots | 110 | **Dashboard** | `bun run dev` | `127.0.0.1:3000` | TanStack Start SSR; prerenders public build via `bun run build:public` | 111 112 | Term | Definition | 113 |------|-----------| 114 | **Local-only bind** | The convention that PocketBase listens on `127.0.0.1` exclusively. No network exposure of the source of truth. | 115 | **Three-process layout** | The architectural commitment that PocketBase, Scanner, and Dashboard run as independent processes, not a single combined runtime. Restarting any one does not affect the others. | 116 117 --- 118 119 ## 5. Public build & privacy 120 121 | Term | Definition | 122 |------|-----------| 123 | **Public build** | The redacted, prerendered static HTML output at `dist/public/`. The artifact shipped to Dokploy. | 124 | **Public flag** | The boolean column `public` on a Project. False by default. Controls whether the Project appears in the public build. | 125 | **Allowlist-by-field** | The redaction strategy. Every field defaults to private; fields opt in to public visibility via the Public mapper. The opposite of denylist-by-field. | 126 | **Public mapper** | The function in `src/server/public-shape.ts` that converts an internal `(Project, Snapshot)` into a `PublicProject`. Snapshot-tested against a fixture; any new field forces an explicit test update. | 127 | **Public description** | An optional column on a Project, distinct from `notes`. The polished blurb intended for the public build. Empty = no description rendered. | 128 | **Public link** | An entry in `links` with `public=true`. Links default to private; per-link visibility is explicit. | 129 | **Grep guard** | The `bun run guard:public` pre-deploy script. Greps `dist/public/` for known-private strings (paths, SHAs, emails, DB-derived values). Match → exit 1 → no deploy. | 130 | **Build-time leak** | Any private string surviving into `dist/public/`. The Grep guard is the last line of defense against this. | 131 | **Public list filter** | The query `WHERE public = true AND status IN ('active','idle','done') AND archived_at IS NULL`. Stuck/archived projects are filtered at the query layer, not the render layer, so private data is not present in the prerendered HTML. | 132 | **Rounded numeric** | Public-build presentation rule: `loc` is rounded to the nearest 100, `commit_count` to the nearest 10. Precision-as-vanity-metric is treated as a code smell. | 133 134 --- 135 136 ## 6. Deployment 137 138 | Term | Definition | 139 |------|-----------| 140 | **Manual deploy** | The `bun run deploy` command. The only way the public build ships. No auto-deploys, no commit-hook deploys, no scheduled deploys. | 141 | **Deploy slot** | The Docker image tag `registry.brinon.eu/kb-dash:latest`. The image Dokploy pulls on each deploy. | 142 | **Source SHA** | The git short SHA embedded in the deployed image and rendered in the page footer. Lets a viewer always identify exactly which source commit produced what they're seeing. | 143 | **Pre-deploy scan** | The first step of the deploy ritual: run the Scanner so the public build reflects current truth. | 144 | **Deploy ritual** | The full sequence: scan → `build:public` → `guard:public` → `docker build` → `docker push`. Codified in the `bun run deploy` script. | 145 | **Deploy decoupling** | The architectural property that KB-Dashboard's deploy pipeline does not depend on `garden.bastidehub.xyz` (Radicle seed) availability. Source repo lives there; deploy artifacts go via the Dokploy registry on the same VPS as the dashboard. | 146 147 --- 148 149 ## 7. Foundational framework concepts 150 151 These terms come from `@YackShavingSkill` and underpin how KB-Dashboard work is governed. 152 153 | Term | Definition | Usage Notes | 154 |------|-----------|-------------| 155 | **`@YackShavingSkill`** | The overarching skill framework that operationalizes Karpathy-inspired coding principles into an active, agent-aware system. KB-Dashboard is its designated trial consumer. | "KB-Dashboard runs under `@YackShavingSkill`." | 156 | **Induced Complexity** | The tendency of LLM coding agents to over-engineer solutions, add unnecessary abstractions, or expand scope beyond the original request. Also called "feature bloat" or "complexity creep." | The phenomenon the framework is designed to counteract. | 157 | **Agent Counterweight** | The conceptual role of `@YackShavingSkill` — providing architectural guardrails that actively restrain LLM tendencies toward over-engineering. | "The skill acts as an agent counterweight." | 158 | **Artifact** | A concrete, structured output produced by a skill. Artifacts are tangible documents (checklists, reports, matrices, journal entries) rather than abstract guidance. | Skills produce artifacts; the review gate consumes them. | 159 | **Gold Standard** | The ideal code patterns stored in the `examples/patterns/` directory. Concrete code examples that agents must reference and mimic to maintain project style consistency. | "The agent reads the Gold Standard before implementing." | 160 | **Anti-Pattern** | Code examples stored in `examples/anti-patterns/` that demonstrate what to avoid. Used as negative references for the agent's self-review. | Contrasted with Gold Standard patterns. | 161 162 --- 163 164 ## 8. Skill modules 165 166 Four composable skill modules derive from the Karpathy principles. Each is a standalone unit that produces a specific artifact. 167 168 ### 8.1 Skill A — `Think Before Coding` 169 170 | Term | Definition | 171 |------|-----------| 172 | **Pre-Computation Block** | The artifact produced by this skill — a structured document containing assumptions, interpretations, alternatives, and scope declarations. | 173 | **Assumptions List** | A list of all assumptions the agent is making about the request, each rated with a confidence level. | 174 | **Confidence Score** | A qualitative rating (`HIGH`, `MEDIUM`, `LOW`) assigned to each assumption, indicating how certain the agent is of its validity. | 175 | **Scope Declaration** | A statement within the pre-computation block explicitly listing which files/patterns will and will not be changed. | 176 | **Alternatives Considered** | A record of simpler or different approaches that were evaluated and rejected, with rationale for each rejection. | 177 178 ### 8.2 Skill B — `Simplicity First` 179 180 | Term | Definition | 181 |------|-----------| 182 | **Simplicity Review** | The artifact produced by this skill — a self-assessment answering whether the simplest viable solution was chosen. | 183 | **Line-Count Budget** | The estimated and actual number of lines of code for an implementation, compared to expose over-engineering. | 184 | **Simplify Trigger** | A condition detected during the simplicity review that indicates the current approach is more complex than necessary, requiring revision. | 185 | **Abstinence List** | What the agent explicitly chose NOT to implement — features, abstractions, or flexibility that were out of scope. | 186 | **Intentional Exclusions** | Edge cases or error scenarios the agent is deliberately NOT handling in this task. | 187 188 ### 8.3 Skill C — `Surgical Changes` 189 190 | Term | Definition | 191 |------|-----------| 192 | **Change Boundary** | The artifact produced by this skill — a document specifying exactly which files will be modified and why, and which files will not be touched. | 193 | **File Touch List** | The list of files the agent plans to modify, with a per-file rationale. | 194 | **Out-of-Bound List** | The list of files explicitly declared as off-limits for this task. | 195 | **Orthogonal Issues** | Improvements or bugs noticed by the agent that are unrelated to the task scope. These are flagged but deliberately not addressed. | 196 | **Orphan Tracking** | The process of identifying imports, variables, or references that become unused as a direct result of this change. | 197 | **Scope Bleed** | A violation where changes touch files or areas declared out-of-bound in the change boundary. See also: Scope Adherence (the paired metric). | 198 199 ### 8.4 Skill D — `Goal-Driven Execution` 200 201 | Term | Definition | 202 |------|-----------| 203 | **Verification Matrix** | The artifact produced by this skill — a structured table mapping each subtask to explicit pass/fail criteria and test cases. | 204 | **Subtask** | A discrete, testable unit of work within the larger task, each with its own verification criteria. | 205 | **Pass/Fail Criteria** | Specific, testable conditions that determine whether a subtask is successfully completed. | 206 | **Self-Loop** | An iteration where the agent attempts to fix a failed verification criterion without external intervention. | 207 | **Escalation Trigger** | The condition (e.g., max self-loops reached, ambiguous failure) that causes the agent to stop and ask the user for guidance. | 208 209 --- 210 211 ## 9. Orchestration & complexity 212 213 ### 9.1 Complexity Orchestrator 214 215 | Term | Definition | 216 |------|-----------| 217 | **Complexity Orchestrator** | The decision layer that calculates a task's complexity score and activates the appropriate skill subset. Authoritative implementation lives in [`skills/orchestrator.md`](skills/orchestrator.md). | 218 | **Complexity Score** | A numeric value (raw sum, 0–8), calculated by summing four dimension scores. Determines which skills activate. | 219 | **Scope Size** | Complexity dimension: `1 FILE (0)`, `2–3 FILES (1)`, `>3 FILES (2)`. Number of files touched by the task. | 220 | **Ambiguity** | Complexity dimension: `LOW (0)`, `MEDIUM (1)`, `HIGH (2)`. Measures clarity of the request. | 221 | **Risk Surface** | Complexity dimension: `INTERNAL (0)`, `PUBLIC-API (1)`, `CRITICAL-PATH (2)`. Measures impact of potential errors. | 222 | **Knowledge Gap** | Complexity dimension: `NONE (0)`, `PARTIAL (1)`, `UNKNOWN (2)`. Measures how familiar the agent is with the relevant codebase area. | 223 | **Skill Set Activation** | The mapping of complexity score to which skills are enabled (see severity tiers below). | 224 225 ### 9.2 Severity tiers 226 227 | Tier | Score range | Active skills | Additional requirements | 228 |------|-------------|---------------|-------------------------| 229 | **TRIVIAL** | 0–2 | Goal-Driven only | Minimal verification matrix. | 230 | **STANDARD** | 3–5 | Goal-Driven + Simplicity First + Think Before Coding + Surgical Changes | Session Journal required. Gold Standard reference required. | 231 | **COMPLEX** | 6–8 | ALL skills + Expert Reviewer | Session Journal required. Explicit user confirmation required. | 232 233 > **Note:** The canonical score is the raw sum of four 0/1/2 dimensions, range 0–8. The "1–10" label that appears in some early framework drafts is informal; the authoritative scale lives in [`skills/orchestrator.md`](skills/orchestrator.md). 234 235 ### 9.3 Adaptive skill injection 236 237 | Term | Definition | 238 |------|-----------| 239 | **Adaptive Skill Injection** | The process by which the Complexity Orchestrator injects only the required skill templates into the execution plan, based on the calculated complexity score. | 240 | **Skill Wrapper** | A task spec that wraps a skill's prompt template, allowing it to execute as a first-class task. | 241 | **Plan Agent** | The agent responsible for complexity scoring, skill selection, and task generation during the Plan phase. | 242 | **Worker Agent** | The agent responsible for executing the work during the Work phase, guided by skill artifacts. | 243 | **Reviewer Agent** | The agent responsible for validating adherence to principles during the Review phase. Also called the "Expert Reviewer" at COMPLEX complexity. | 244 245 ### 9.4 Agent roles 246 247 | Term | Definition | 248 |------|-----------| 249 | **Executor** | Synonym for Worker Agent. The agent that writes code. | 250 | **Reviewer** | Synonym for Reviewer Agent. The agent that checks code for principle adherence without writing code. | 251 | **Escalation Agent** | A third agent engaged only at COMPLEX complexity when the Reviewer detects violations exceeding a threshold. | 252 253 --- 254 255 ## 10. Reflection artifacts 256 257 The Reflection layer adds a Session Journal as the primary reflection mechanism. 258 259 ### 10.1 Session Journal 260 261 | Term | Definition | 262 |------|-----------| 263 | **Session Journal** | A structured log file (`SESSION_LOG.md`) where the agent records its thinking before and after coding in two entries: Pre-Flight and Post-Flight. | 264 | **Journal Entry** | A single recorded block within the Session Journal. Each task produces at minimum two entries. | 265 | **Pre-Flight Entry** | Journal Entry #1 — written BEFORE coding. Captures the Simplicity Strategy, Scope Boundaries, Contextual References, and Assumptions. | 266 | **Post-Flight Entry** | Journal Entry #2 — written AFTER coding. Captures the Reflex Audit (Pass/Fail), Violation checks, and Verification Results. | 267 268 ### 10.2 Pre-Flight Entry structure 269 270 | Field | Definition | 271 |-------|-----------| 272 | **Reflex Check** | A pair of commitments: (1) a Simplicity Goal stating the technique to use and the approach to avoid, and (2) explicit Scope Boundaries declaring In-Scope and Out-of-Scope items. | 273 | **Simplicity Strategy** | The agent's stated approach for keeping the solution minimal. Values: `MINIMAL`, `STANDARD`, `DEEP`. | 274 | **Contextual Retrieval** | A reference to which `examples/patterns/` file the agent is reading as its Gold Standard before implementation. | 275 | **Trade-off Record** | A documented comparison between two approaches with the rationale for the chosen approach. | 276 277 ### 10.3 Post-Flight Entry structure 278 279 | Field | Definition | 280 |-------|-----------| 281 | **Reflex Audit** | A Pass/Fail judgment on whether the agent's final code met its Pre-Flight Simplicity Goal. Values: `PASSED`, `FAILED`. | 282 | **Violation Checklist** | Specific checks the agent performs on itself: Complexity Creep, Scope Bleed, Style Drift. Each checked as pass/fail. | 283 | **Style Drift** | A violation where the agent's code does not match the structure or patterns from the referenced Gold Standard example. | 284 | **Complexity Creep** | A violation where the agent added unused flags, hidden logic branches, or unnecessary abstractions beyond the Pre-Flight commitment. | 285 286 --- 287 288 ## 11. Verification & review 289 290 ### 11.1 Verification gates 291 292 | Term | Definition | 293 |------|-----------| 294 | **Verification Gate** | The post-hoc check that runs before changes are committed. Reads pre-computation and change-boundary artifacts, diffs actual changes against declared boundaries, and reports violations. | 295 | **Post-Hoc Verification** | Synonym for Verification Gate. Emphasizes that checking happens after execution, not before. | 296 | **Trust But Verify** | The operational philosophy: agents are allowed to proceed, but their output is mechanically checked against their own commitments. | 297 | **Violation** | Any deviation between what the agent declared it would do (in its artifacts) and what it actually did. | 298 | **Violation Count** | The number of detected violations. Used to determine whether to auto-accept, flag, or escalate. | 299 | **Violation Threshold** | The maximum violation count before requiring user intervention or escalation. | 300 301 ### 11.2 Review process 302 303 | Term | Definition | 304 |------|-----------| 305 | **Principle Adherence** | The degree to which the agent's output follows the four core behavioral principles. This is the Reviewer Agent's sole concern. | 306 | **Adherence Report** | A summary emitted at task completion, reporting which skills fired, what artifacts were produced, and how many violations were detected. Path: `.artifacts/{task_id}/adherence_report.md`. | 307 | **Scope Adherence** | The percentage of actually-changed files that were pre-declared in the Change Boundary's File Touch List. Target: 100%. Computed at file granularity. Formula: `100 - (scope_bleed_count × 100 / actual_count)`. See also: Scope Bleed. | 308 | **Orthogonal Change Rate** | The percentage of code changes to files or areas outside the declared scope (target: <5%). | 309 | **Tombstone** | A historical violation recorded in an `adherence_report.md` that has since been corrected in the underlying code. Tombstones persist in `METRICS.md` rollups because adherence reports are frozen at commit time; they represent historical fact, not current drift. Active drift equals rollup count minus tombstone count. KB-Dashboard adopts this pattern from `@YackShavingSkill`; first KB-Dashboard tombstone TBD. | 310 311 ### 11.3 Review phases 312 313 | Term | Definition | 314 |------|-----------| 315 | **Pre-Flight** | The state before coding begins. The agent has produced its Journal Entry #1 and declared its boundaries. | 316 | **Post-Flight** | The state after coding ends, before review begins. The agent has produced its Journal Entry #2. | 317 | **Review Gate** | The entry point to the Review phase. The Reviewer Agent reads the Session Journal first, then inspects the code. | 318 | **Instant Fail** | When a Reviewer detects a direct contradiction between Pre-Flight commitments and Post-Flight output (e.g., committed to 20 lines, produced 200). The review fails immediately without deeper inspection. | 319 320 --- 321 322 ## 12. Repository structure 323 324 ``` 325 KB-Dashboard/ 326 ├── README.md # entry point 327 ├── LICENSE # GPL-3.0-or-later 328 ├── kb-dashboard.org # project governing doc 329 ├── ideas.org # original brainstorm 330 ├── grilling-session.org # architectural decisions 331 ├── plan_phase_*.org # phase plans (this project's; not symlinked) 332 ├── phase*_postmortem.org # phase postmortems (post-execution; future) 333 ├── adr_*.org # Architecture Decision Records (as they accrue) 334 ├── SESSION_LOG.md # task journal entries (introduced in Phase 1 Wave A) 335 ├── METRICS.md # adherence rollup (tool-regenerated; future) 336 ├── UBIQUITOUS_LANGUAGE.md # this file 337 ├── CLAUDE.md ─→ symlink → ../Pi-YackShaving/CLAUDE.md 338 ├── skills/ ─→ symlink → framework skill prompts 339 ├── schemas/ ─→ symlink → framework artifact schemas 340 ├── templates/ ─→ symlink → framework templates 341 ├── examples/ ─→ symlink → framework patterns + anti-patterns 342 ├── tools/ ─→ symlink → framework review tooling 343 ├── src/ # TanStack Start app (from Wave A) 344 ├── scanner/ # Bun scanner script (from Wave C) 345 ├── pb_migrations/ # PocketBase migration files (from Wave B) 346 ├── pb_data/ # gitignored — local SQLite + uploads 347 ├── bin/pocketbase # gitignored — fetched binary 348 ├── dist/ # gitignored — build output 349 └── .artifacts/{task_id}/ # framework artifacts per task 350 ``` 351 352 | Term | Definition | 353 |------|-----------| 354 | **Master Rules** | The `CLAUDE.md` file — a concise, top-level reference of the four principles, providing quick access for agents. Symlinked from Pi-YackShaving. | 355 | **Skill File** | A single `.md` file in `skills/` containing the full prompt template for one skill module. | 356 | **Pattern File** | A file in `examples/patterns/` demonstrating a good code example for the agent to mimic. | 357 | **Anti-Pattern File** | A file in `examples/anti-patterns/` demonstrating a bad code example the agent must avoid. | 358 | **Journal Template** | The file in `templates/` providing the markdown structure for Session Journal entries. | 359 | **Selective-hybrid vendoring** | KB-Dashboard's framework integration: directories (`skills/`, `schemas/`, `templates/`, `examples/`, `tools/`) plus `CLAUDE.md` symlinked from `../Pi-YackShaving/`; `UBIQUITOUS_LANGUAGE.md` copied (this file). Per [`plan_phase_1.org`](plan_phase_1.org) §D3. | 360 361 --- 362 363 ## 13. Relationships & glossary 364 365 ### 13.1 KB-Dashboard data flow 366 367 ``` 368 ┌──────────────────────────── Local dev machine ────────────────────────────┐ 369 │ │ 370 │ ┌────────┐ git log ┌────────────┐ upsert ┌──────────────┐ │ 371 │ │ Source │ ─────────────→│ Scanner │ ────────────→│ PocketBase │ │ 372 │ │ repo │ │ (Bun) │ │ 127.0.0.1 │ │ 373 │ └────────┘ └────────────┘ │ :8090 │ │ 374 │ └──────┬───────┘ │ 375 │ │ │ 376 │ ┌─────────────┐ REST read │ │ 377 │ │ Dashboard │←────────────────────┘ │ 378 │ │ (TanStack) │ │ 379 │ │ :3000 │ │ 380 │ └─────┬───────┘ │ 381 │ │ build:public │ 382 │ ▼ │ 383 │ dist/public/ │ 384 │ │ guard:public + docker push │ 385 └──────────────────────────────────┼─────────────────────────────────────────┘ 386 ▼ 387 ┌──────────────────────┐ 388 │ Dokploy registry │ 389 │ registry.brinon.eu │ 390 │ → nginx → public │ 391 └──────────────────────┘ 392 ``` 393 394 ### 13.2 Framework execution flow (heritage) 395 396 ``` 397 ┌──────────────────────────────────────────────────────────────────┐ 398 │ @YackShavingSkill │ 399 │ │ 400 │ Plan → Work → Review │ 401 │ (Orch.) (Agent) (Gate) │ 402 │ │ 403 │ Plan Agent calculates Complexity Score (0–8) │ 404 │ │ │ 405 │ ├─→ TRIVIAL (0–2): Goal-Driven only │ 406 │ ├─→ STANDARD (3–5): All 4 Skills + Journal │ 407 │ └─→ COMPLEX (6–8): All 4 Skills + Journal + Expert Review │ 408 │ │ 409 │ Worker executes skills, produces Artifacts: │ 410 │ - Think Before Coding → Pre-Computation Block │ 411 │ - Simplicity First → Simplicity Review │ 412 │ - Surgical Changes → Change Boundary │ 413 │ - Goal-Driven → Verification Matrix │ 414 │ │ 415 │ Session Journal recorded by Worker: │ 416 │ - Pre-Flight Entry (before coding) │ 417 │ - Post-Flight Entry (after coding) │ 418 │ │ 419 │ Reviewer inspects: │ 420 │ 1. Session Journal consistency │ 421 │ 2. Artifacts vs. actual code diff │ 422 │ 3. Gold Standard pattern compliance │ 423 │ 4. Generates Adherence Report │ 424 └──────────────────────────────────────────────────────────────────┘ 425 ``` 426 427 ### 13.3 Synonym map 428 429 | Preferred term | Synonyms (use preferred in code/docs) | 430 |----------------|---------------------------------------| 431 | Project | project row, registry entry | 432 | Snapshot | snapshot row, scan record | 433 | Scanner | the scan script, scan job | 434 | Card | project card, dashboard card | 435 | Public build | filtered build, public dist, dist/public | 436 | Grep guard | leak guard, redaction guard | 437 | Source SHA | deploy SHA, build SHA | 438 | Manual deploy | explicit deploy | 439 | Complexity Orchestrator | Orchestrator | 440 | Session Journal | Journal | 441 | Pre-Flight / Post-Flight | Pre-Flight Entry / Post-Flight Entry | 442 | Scope Adherence | Surgical Purity (deprecated), Diff Purity (deprecated) | 443 | Verification Matrix | Verification | 444 | Verification Gate | Gate | 445 | Reflex Audit | Self-Audit | 446 | Gold Standard | Example Pattern | 447 | Anti-Pattern | Negative Example | 448 449 ### 13.4 Abbreviations 450 451 | Abbreviation | Full term | 452 |--------------|-----------| 453 | API | Application Programming Interface | 454 | CI/CD | Continuous Integration / Continuous Deployment | 455 | LOC | Lines of code | 456 | PB | PocketBase | 457 | PRD | Product Requirements Document | 458 | SDK | Software Development Kit | 459 | SHA | Secure Hash Algorithm (git commit identifier) | 460 | SSR | Server-Side Rendering | 461 | UL | Ubiquitous Language (this document's category) | 462 | VPS | Virtual Private Server | 463 464 ### 13.5 Key decisions & conventions 465 466 **Framework heritage:** 467 468 1. **Artifacts are primary.** Every skill MUST produce a concrete artifact. No skills without artifacts. 469 2. **Journal precedes code.** Pre-Flight Journal Entry is a gate — no file modifications until the agent has written it. 470 3. **Reviewer reads Journal first.** The review order is: Journal → Code. Inconsistencies between entries and code are violations. 471 4. **Violations are reported, not blocked.** By default, agents continue after producing a violation report, unless violations exceed the threshold. 472 5. **Complexity drives activation.** Not all skills fire on all tasks. The Complexity Orchestrator determines activation. 473 6. **Examples beat descriptions.** When deciding style, agents reference `examples/patterns/` files over any textual description. 474 475 **KB-Dashboard project domain:** 476 477 7. **Allowlist over denylist.** Public-build redaction defaults to private; fields opt in via the Public mapper. 478 8. **Three-process layout.** PocketBase, Scanner, and Dashboard run as separate local processes; never combined. 479 9. **Append-only snapshots.** History is preserved by structure (`project_snapshots` is insert-only), not policy. 480 10. **Manual deploys only.** No auto-deploy paths from scanner runs, commits, or scheduled jobs. 481 11. **Local-only source of truth.** PocketBase binds to `127.0.0.1` exclusively; the database never has a network-exposed surface. 482 12. **Tracer-bullet phasing.** Phases scope to the smallest vertical slice exercising every architectural seam end-to-end. Width over depth in early phases. 483 13. **Deploy decoupling.** Source repo on Radicle (`garden.bastidehub.xyz`) and deploy artifacts via Docker registry are independently failable; either can be down without blocking the other indefinitely. 484 485 --- 486 487 *This document is the authoritative source for KB-Dashboard terminology — both project-domain and framework-heritage. Update when terminology drift surfaces in code, plans, or session journals. Sections 7–11 mirror `@YackShavingSkill`'s framework conventions; if the framework patches its terminology, propagate the changes here as part of a sweep commit.*