janpeter/Scrum4Me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: sync data-model, glossary en specs met huidig schema (#164)

Browse source 
Brengt de docs gelijk met de werkelijkheid na PBI-46/47/50/58/59/61/63
en M12. Belangrijkste fixes:

- data-model.md herschreven naar prisma/schema.prisma: nieuwe entiteiten
  (Idea, IdeaLog, IdeaProduct, UserQuestion, ClaudeQuestion, ClaudeJob,
  SprintRun, SprintTaskExecution, ClaudeWorker, LoginPairing,
  PushSubscription, ModelPrice, ProductMember), nieuwe enums
  (FAILED/EXCLUDED, OPEN/CLOSED/ARCHIVED, ADMIN, etc.) en codes
  (PBI/ST/T/SP-N) toegevoegd; verwijderde todos-tabel verwijderd.
- glossary.md: Sprint zonder "max 1 actief" (PBI-63), Story/Task incl.
  FAILED/EXCLUDED, Todo verwijderd, Idea/SprintRun/ClaudeJob/
  verify_result toegevoegd.
- project-structure.md: app/(app)/todos vervangen door
  ideas/insights/jobs/manual/admin/solo; api-tree volledig.
- overview.md: "geen realtime in v1" en Docker-rationale herschreven —
  Postgres LISTEN/NOTIFY + SSE, claude_jobs als queue, opt-in
  Docker-deploy-flow.
- functional.md: F-08 Todo-lijst -> Ideeen-laag, F-09 multi-sprint,
  F-10 Task-status incl. FAILED/EXCLUDED, F-11 endpoint-lijst,
  navigatiestructuur, datamodel-schets en Flow 3 bijgewerkt.
- README.md API-tabel: /api/todos weg, ideas/jobs/users/profile/health
  toegevoegd, kort over realtime/auth-pair/internal/cron.
- patterns + mcp-integration runbook: Todo-/ACTIVE-references vervangen
  door Idea/OPEN; create_todo MCP-tool note over verwijdering.

Linkcheck groen (105 files), INDEX hergegenereerd (98 docs).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser 2026-05-08 08:16:44 +02:00 • committed by GitHub
parent 3842c05ae9
commit f7464db837
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 544 additions and 424 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/glossary.md
View file

@ -3,7 +3,7 @@ title: "Scrum4Me — Glossary"
status: active
audience: [ai-agent, contributor]
language: en
last_updated: 2026-05-03
last_updated: 2026-05-08
when_to_read: "When you encounter a domain term and need its canonical definition and the doc where it is specified."
---
@ -15,6 +15,10 @@ Domain terms used across Scrum4Me docs, code, and MCP tooling.
A Claude Code session that has registered itself as a `ClaudeWorker` record and polls the job queue via `mcp__scrum4me__wait_for_job`. The NavBar counts active workers by `last_seen_at < now() - 15s`. See [MCP integration runbook](./runbooks/mcp-integration.md).
## ClaudeJob
A row in the `claude_jobs` table — the queue from which agents claim work atomically (`FOR UPDATE SKIP LOCKED`). Distinguished by `kind` (`TASK_IMPLEMENTATION`, `IDEA_GRILL`, `IDEA_MAKE_PLAN`, `PLAN_CHAT`, `SPRINT_IMPLEMENTATION`) and tracked through `status` (`QUEUED → CLAIMED → RUNNING → DONE/FAILED/CANCELLED/SKIPPED`). See [data-model](./architecture/data-model.md) and [MCP integration runbook](./runbooks/mcp-integration.md).
## claude-question
A pending question posted by an agent (via `mcp__scrum4me__ask_user_question`) to a human user, stored in the `claude_questions` table. The user answers in the UI; a PostgreSQL `LISTEN/NOTIFY` trigger pushes the answer back to the waiting agent. See [architecture: claude-question-channel](./architecture/claude-question-channel.md) and [ADR-0007](./adr/0007-claude-question-channel-design.md).
@ -27,13 +31,17 @@ An API token whose owning user has `isDemo = true`. All write operations are blo
A preconfigured read-only account used for public showcase. Shares product data with the main account but cannot create, update, or delete anything. See [architecture: auth and sessions](./architecture/auth-and-sessions.md).
## Idea
A user-scoped idea captured before it becomes a PBI. An idea is first _grilled_ via an interactive Q&A loop (`IDEA_GRILL` job → `grill_md`), then materialized through a deterministic plan (`IDEA_MAKE_PLAN` job → `plan_md`) into a PBI with stories and tasks. Replaced the legacy `todos` table in M12. Status enum: `DRAFT | GRILLING | GRILL_FAILED | GRILLED | PLANNING | PLAN_FAILED | PLAN_READY | PLANNED`. See [data-model](./architecture/data-model.md) and the [M12 plan](./plans/M12-ideas.md).
## MCP-job
A `Task` record that has been queued for autonomous agent execution. An agent claims a job atomically via `mcp__scrum4me__wait_for_job` and reports completion via `mcp__scrum4me__update_job_status`. See [MCP integration runbook](./runbooks/mcp-integration.md).
Synonym for **ClaudeJob** — used in agent-facing docs because Claude Code consumes the queue through MCP tools. An agent claims a job atomically via `mcp__scrum4me__wait_for_job` and reports completion via `mcp__scrum4me__update_job_status`. See [MCP integration runbook](./runbooks/mcp-integration.md).
## PBI (Product Backlog Item)
The second level of the work hierarchy: `Product → PBI → Story → Task`. A PBI groups related stories under a single theme or capability. Do not use "Epic", "Feature", or "Issue" as synonyms. See [backlog index](./backlog/index.md).
The second level of the work hierarchy: `Product → PBI → Story → Task`. A PBI groups related stories under a single theme or capability. Status enum: `READY | BLOCKED | FAILED | DONE`. Has a stable `code` (`PBI-N`) per product. Do not use "Epic", "Feature", or "Issue" as synonyms. See [backlog index](./backlog/index.md).
## Solo Panel
@ -41,16 +49,20 @@ The single-user planning screen that shows all PBIs and stories for one product
## Sprint
A time-boxed iteration with a `sprint_goal`. Stories move from `OPEN` to `IN_SPRINT` when added to the active sprint. Only one sprint per product can be `ACTIVE` at a time. See [backlog index](./backlog/index.md).
A time-boxed iteration with a `sprint_goal` and a stable `code` (`SP-N`) per product. A product can hold multiple sprints simultaneously (PBI-63) — `OPEN` is not exclusive; the sprint-switcher in the product header lets the user pick which sprint to plan against. Status enum: `OPEN | CLOSED | ARCHIVED | FAILED`. Stories enter `IN_SPRINT` when added to a sprint via `sprint_id`. See [data-model](./architecture/data-model.md).
## SprintRun
A single execution of the SPRINT_IMPLEMENTATION flow against one Sprint. Tracked in `sprint_runs` with status `QUEUED | RUNNING | PAUSED | DONE | FAILED | CANCELLED`, optional `pause_context` for resume, and a chain via `previous_run_id` for retries. The frozen scope-snapshot per run lives in `sprint_task_executions`. See [sprint execution modes](./architecture/sprint-execution-modes.md).
## Story
The third level of the work hierarchy: `Product → PBI → Story → Task`. A Story has acceptance criteria and a status (`OPEN | IN_SPRINT | DONE`). See [functional spec](./specs/functional.md).
The third level of the work hierarchy: `Product → PBI → Story → Task`. A Story has acceptance criteria, an optional `assignee_id` (Solo-bord claim), a stable `code` (`ST-N`) per product, and a status (`OPEN | IN_SPRINT | DONE | FAILED`). See [functional spec](./specs/functional.md).
## Task
The leaf level of the work hierarchy: `Product → PBI → Story → Task`. A Task has an `implementation_plan`, a `status` (`TO_DO | IN_PROGRESS | REVIEW | DONE`), and an optional `sort_order`. API exposes status as lowercase (`todo | in_progress | review | done`). See [architecture: data model](./architecture/data-model.md) and [ADR-0004](./adr/0004-status-enum-mapping.md).
The leaf level of the work hierarchy: `Product → PBI → Story → Task`. A Task has an `implementation_plan`, a stable `code` (`T-N`) per product, a `status` (`TO_DO | IN_PROGRESS | REVIEW | DONE | FAILED | EXCLUDED`), `verify_only` and `verify_required` flags, and an optional `repo_url` override. API exposes status as lowercase (`todo | in_progress | review | done | failed | excluded`). See [data-model](./architecture/data-model.md) and [ADR-0004](./adr/0004-status-enum-mapping.md).
## Todo
## verify_result
A lightweight freeform note scoped to a product (or unscoped). Not part of the sprint hierarchy — used for quick capture. Created via `mcp__scrum4me__create_todo`. See [MCP integration runbook](./runbooks/mcp-integration.md).
The agent's outcome of a verification pass (`ALIGNED | PARTIAL | EMPTY | DIVERGENT`). Combined with the task's `verify_required` threshold (`ALIGNED | ALIGNED_OR_PARTIAL | ANY`) it determines whether a job's claim of "done" is accepted by the gate. See [agent-flow-pitfalls runbook](./runbooks/agent-flow-pitfalls.md).