EDPA Playbook — Od nuly po první PI

Prerekvizity

EDPA V2 je local-first: zdrojem pravdy je .edpa/backlog/**/*.md (YAML frontmatter), git je audit trail. GitHub je volitelný — žádný GitHub Project, žádné org Issue Types, žádný obousměrný sync.

Nástroje

EDPA V2 běží čistě lokálně nad gitem. gh je potřeba pouze pokud chcete volitelný PR-signal sync (workflow edpa-contribution-sync.yml) — viz Fáze 2.

Volitelné: GitHub CLI scopes pro PR-signal sync

Pokud zapnete volitelný PR-signal sync, stačí běžné repo scope:

gh auth login        # běžný repo scope stačí
gh auth status

Tým a backlog

Před začátkem je třeba mít:

• Definovaný tým: jména, role (Arch, Dev, DevSecOps, PM, QA, BO), FTE, kapacity
• Alespoň základní backlog (1 Epic, 2-3 Features, 5-10 Stories)
• Git repozitář (GitHub remote je volitelný)

role: v people.yaml je volný label pro reporty (sloupec v timesheetu, Excel exporty) a vstup do syntetického kalibračního korpusu. Engine signal weights se aplikují bez ohledu na roli osoby — commit_author=4.00, pr_reviewer=2.17, issue_comment=1.46, atd. jdou každému stejně.

Fáze 1: Infrastruktura (Den 1, ~1 hodina)

Cesta A: Claude Code (doporučeno)

V terminálu s Claude Code nainstalovaným:

/edpa:setup --with-ci --with-hooks --with-rules

Claude Code (skill /edpa:setup) provede kroky 1.1-1.4 automaticky — vendoruje engine do .edpa/engine/, naseje konfiguraci a id_counters.yaml a volitelně nainstaluje git hooky, PR-signal CI workflow a .claude/rules/. Idempotentní — opakované spuštění nic nerozbije.

Cesta B: Manuální CLI

Následující kroky popisují manuální postup bez Claude Code.

1.1 Nainstalovat EDPA a vendorovat engine

Varianta A: Shell installer (doporučeno)

cd my-project
curl -fsSL https://edpa.technomaton.com/install.sh | sh

Varianta B: project_setup.py

project_setup.py vendoruje engine + naseje configy + id_counters.yaml. Flagy navíc nainstalují git hooky, contribution-sync CI workflow a .claude/rules/. Bez --org/--repo — žádné GitHub provisioning.

python3 .edpa/engine/scripts/project_setup.py --with-ci --with-hooks --with-rules

Výsledná struktura:

my-project/
  .edpa/
    config/
      edpa.yaml          # Projekt + governance (zdroj verze metodiky)
      people.yaml        # Tym a kapacity (teams, people)
      cw_heuristics.yaml # CW signalove vahy
      id_counters.yaml   # Citace ID (S-1, E-1, F-1, ...)
    backlog/
      initiatives/       # 1 soubor = 1 initiative (.md s YAML frontmatter)
      epics/             # 1 soubor = 1 epic
      features/          # 1 soubor = 1 feature
      stories/           # 1 soubor = 1 story
    iterations/          # PI a iterace (PI-2026-1.yaml, PI-2026-1.1.yaml, ...)
    reports/             # Generovane reporty + edpa_results.json per iterace
    snapshots/           # Zmrazene snapshoty iteraci
    data/                # Ground truth pro kalibraci (po PI)
    engine/              # VENDOROVANY engine (instaluje project_setup.py)
      VERSION
      scripts/
        engine.py            # EDPA vypocetni jadro
        backlog.py           # Sprava backlogu (add, tree, show, wsjf, validate)
        detect_contributors.py  # evidence[] -> contributors[] (cw)
        calibrate_signals.py    # Kalibrace signalovych vah (MAD)
        reports.py           # Vykazy + PI summary + xlsx
        board.py             # Lokalni HTML Kanban board
        capacity_override.py # Kapacitni override per osoba/iterace
        sync_pr_contributions.py  # Materializace PR-thread signalu (volitelne CI)
        ...                  # dalsi pomocne skripty + hooks/
      templates/
        people.yaml.tmpl
        cw_heuristics.yaml.tmpl
        edpa.yaml.tmpl
  .github/workflows/         # JEN s --with-ci
    edpa-contribution-sync.yml  # Po merge PR: PR-thread signaly -> evidence[]
  .claude/rules/             # JEN s --with-rules (architektonicka pravidla)
  docs/                      # Dokumentace

1.2 Nakonfigurovat tým a kapacity (people.yaml)

project_setup.py už .edpa/config/people.yaml naseje ze šablony. Případně ručně:

cp .edpa/engine/templates/people.yaml.tmpl .edpa/config/people.yaml

Upravit .edpa/config/people.yaml. Tady žijí teams + people — žádný separátní registr. Kadenci (iteration_weeks / pi_iterations) nastav per-PI v pi: bloku .edpa/iterations/PI-*.yaml:

teams:
  - id: "Muj Tym"
    planning_factor: 0.8               # Planujeme na 80% kapacity

people:
  - id: alice
    name: "Alice Novakova"
    role: Arch                          # Arch, Dev, DevSecOps, PM, QA, BO
    team: "Muj Tym"
    fte: 0.5
    capacity_per_iteration: 20          # hodiny: FTE x 40 pro 1-tydenni iter.
                                        # (40 pro 2-tydenni)
    email: "alice@example.com"
    availability: confirmed             # confirmed, partial, unavailable

  - id: bob
    name: "Bob Svoboda"
    role: Dev
    team: "Muj Tym"
    fte: 1.0
    capacity_per_iteration: 40          # FTE x 40 pro 1-tydenni iter.
    email: "bob@example.com"
    availability: confirmed

  # Pridat dalsi cleny tymu...

1.3 Nakonfigurovat projekt + governance (edpa.yaml)

project_setup.py naseje .edpa/config/edpa.yaml ze šablony (NE project.yaml — ten v V2 neexistuje). Případně ručně:

cp .edpa/engine/templates/edpa.yaml.tmpl .edpa/config/edpa.yaml

Upravit .edpa/config/edpa.yaml:

project:
  name: "Muj Projekt"                   # ← Display name (jedine povinne pole)
  description: ""
  domain: "mujprojekt.cz"
  # Volitelne: funding (granty/dotace) + organizations (pro audit/fakturaci)

governance:
  # Auto-razitkovano na verzi pluginu instalatorem.
  methodology: "EDPA v2.11.1"
  # Jedina vypocetni cesta od v1.14 (zadny simple/full/gates mode selector,
  # zadny audit_mode -- snapshoty vzdy nesou plny signals[] audit trail).

naming:
  pi_pattern: "PI-{year}-{pi_num}"                    # PI-2026-1
  iteration_pattern: "PI-{year}-{pi_num}.{iter_num}"  # PI-2026-1.3
  branch_pattern: "{type}/{item_id}-{description}"    # feature/S-200-omop-parser
  item_prefixes:
    initiative: "I"
    epic: "E"
    feature: "F"
    story: "S"
    task: "T"
    defect: "D"
    event: "EV"

1.4 Nakonfigurovat CW signálové váhy (cw_heuristics.yaml)

project_setup.py naseje .edpa/config/cw_heuristics.yaml (NE heuristics.yaml). Případně ručně:

cp .edpa/engine/templates/cw_heuristics.yaml.tmpl .edpa/config/cw_heuristics.yaml

Výchozí hodnoty jsou kalibrované Monte Carlo simulací. Pro začátek stačí bez úprav. Kalibrace na vlastní data se provádí po prvním PI (viz Fáze 3).

EDPA V2 je evidence-driven: cw[osoba, item] = contribution_score / Σ contribution_score, kde contribution_score = Σ signal_weight. Klíčové výchozí signálové váhy:

Rolové váhy přispěvatelů (--contributor PERSON:ROLE:CW) — owner 1.0 / key 0.6 / reviewer 0.25 / consulted 0.15; evidence_threshold 1.0. cw_heuristics.yaml navíc obsahuje gate_weights pro Feature/Epic/Initiative — status transition na rodiči rozděluje jeho Job Size napříč lifecyclem (součet = 1.0 per typ).

Kalibrace přes /edpa:calibrate — Monte Carlo random sampling + coordinate descent přes 3D prostor signálových vah proti syntetickému korpusu. Detail viz sekce Architektura.

1.5 Nakonfigurovat iterace (iterations/)

PI a iterace žijí v .edpa/iterations/ jako samostatné soubory:

# .edpa/iterations/PI-2026-1.yaml — PI-level metadata
pi:
  id: PI-2026-1
  status: active
  iteration_weeks: 1                      # AI-native default
  pi_iterations: 5                         # 4 delivery + 1 IP
  start_date: 2026-04-01
  end_date: 2026-05-05

# .edpa/iterations/PI-2026-1.1.yaml — per-iteration data
iteration:
  id: PI-2026-1.1
  pi: PI-2026-1
  start_date: 2026-04-01
  end_date: 2026-04-07
  weeks: 1
  status: planned
# planning / delivery / stories_detail follow as the iteration runs

Vytvoř obdobně PI-2026-1.{2..5}.yaml. Poslední iterace dostane type: IP (Innovation & Planning). Kontinuitu (žádné mezery / překryvy, weeks × 7 ≈ rozdíl dat) hlídá validate_iterations.py i automatický PostToolUse hook.

1.6 Naplnit backlog

EDPA používá file-per-item strukturu — každý work item je samostatný .md soubor s YAML frontmatter (v V2 NE .yaml):

.edpa/
  config/
    edpa.yaml                    # projekt + governance
    people.yaml                  # tym a kapacity
    cw_heuristics.yaml           # CW signalove vahy
    id_counters.yaml             # citace ID
  backlog/
    initiatives/
      I-1.md                     # 1 soubor = 1 initiative
    epics/
      E-1.md                     # 1 soubor = 1 epic
    features/
      F-1.md                     # 1 soubor = 1 feature
    stories/
      S-1.md                     # 1 soubor = 1 story
  iterations/
    PI-2026-1.1.yaml             # plan iterace

Příklad story souboru (.edpa/backlog/stories/S-1.md — YAML frontmatter + volitelné tělo):

---
id: S-1
type: Story
title: "Implementace parseru"
status: Backlog
parent: F-1
js: 5
assignee: bob
iteration: PI-2026-1.1
---
Volitelny popis / akceptacni kriteria v Markdownu.

Přidání nového itemu (LOKÁLNĚ — žádné GitHub volání):

# Claude Code:
/edpa:add    # interaktivne prida jeden item (Initiative/Epic/Feature/Story/Defect/Event/Risk)

# CLI:
python3 .edpa/engine/scripts/backlog.py add --type Story --parent F-1 \
  --title "..." --js 5 --assignee bob --iteration PI-2026-1.1
python3 .edpa/engine/scripts/backlog.py add --type Epic --parent I-1 \
  --title "..." --js 13 --bv 13 --tc 8 --rr-oe 5

backlog.py add je v V2 čistě lokální (žádné gh): ID se přidělí z id_counters.yaml (S-42, E-15, I-3), hierarchie rodiče se zvaliduje, YAML se zapíše pod .edpa/backlog/ a změna se auto-commitne jako feat(<ID>):. PR-odvozené signály přicházejí až později přes volitelný contribution-sync workflow.

Přidělování přispěvatelů lze udělat hned při založení (per-item CW share):

python3 .edpa/engine/scripts/backlog.py add --type Story --parent F-1 --title "..." --js 5 \
  --contributor bob:owner:0.7 --contributor carol:reviewer:0.3
# Format PERSON:ROLE:CW, ROLE ∈ {owner,key,reviewer,consulted}, CW ∈ [0,1]

Ověřit integritu:

python3 .edpa/engine/scripts/backlog.py validate

Zobrazit hierarchii:

python3 .edpa/engine/scripts/backlog.py tree
python3 .edpa/engine/scripts/backlog.py tree --level epic

Zobrazit WSJF prioritizaci:

python3 .edpa/engine/scripts/backlog.py wsjf
python3 .edpa/engine/scripts/backlog.py wsjf --level feature

Zobrazit detail položky:

python3 .edpa/engine/scripts/backlog.py show S-1
python3 .edpa/engine/scripts/backlog.py show E-1

1.7 Ověřit setup

# Demo EDPA engine (bez realnych dat)
python3 .edpa/engine/scripts/engine.py --demo

# Validace backlogu
python3 .edpa/engine/scripts/backlog.py validate

# Status projektu
python3 .edpa/engine/scripts/backlog.py status

# Vizualni HTML board (local-first nahrada za Projects board)
python3 .edpa/engine/scripts/board.py --output .edpa/board.html

1.8 Commitnout základní konfiguraci

backlog.py add commituje itemy automaticky. Počáteční config a vendorovaný engine commitni:

git add .edpa/
git commit -m "feat(edpa): initial EDPA V2 setup for my-project"
git push origin main   # volitelne, pokud mate GitHub remote

Fáze 2: První iterace (Týden 1)

2.1 Iteration Planning

1. Potvrzení kapacity — tým potvrdí dostupnost na iteraci
2. Výběr stories — z backlogu dle WSJF pořadí, na 80% kapacity

# WSJF ranking features
python3 .edpa/engine/scripts/backlog.py wsjf --level feature

# Tree pro konkrétní iteraci
python3 .edpa/engine/scripts/backlog.py tree --iteration PI-2026-1.1

3. Přiřazení assignees — každá story musí mít assignee
4. Aktualizace backlogu — iteration: PI-2026-1.1 na vybraných stories

2.2 Denní práce

Branch naming konvence {type}/{ITEM}-{popis} — v V2 ji vynucují git hooky (--with-hooks), už ne CI:

# Formát: {type}/{ITEM_ID}-{popis}
git checkout -b feature/S-200-omop-parser
git checkout -b feature/F-102-anon-engine
git checkout -b bugfix/S-215-upload-validation
git checkout -b chore/T-050-ci-pipeline

Povolené typy: feature, bugfix, hotfix, chore
Povolené prefixy: S (Story), F (Feature), E (Epic), T (Task), D (Defect), I (Initiative), EV (Event)

Git hooky (--with-hooks) materializují evidenci lokálně, bez GitHubu:

Registrace hooků je idempotentní a self-refreshing (SessionStart auto-update je po update pluginu znovu zaregistruje). Cizí (ne-EDPA) hooky se nikdy nepřepisují — přeskočí se s varováním. Stav hooků (aktivní / chybějící / cizí / lefthook) zkontroluješ kdykoli read-only doctorem:

python3 .edpa/engine/scripts/project_setup.py --check-hooks
python3 .edpa/engine/scripts/project_setup.py --refresh-hooks   # jen znovu zaregistruje

pre-commit:
  commands:
    edpa-id-safety:
      run: sh .edpa/engine/scripts/hooks/pre-commit-id-safety
commit-msg:
  commands:
    edpa-ticket-attached:
      run: sh .edpa/engine/scripts/hooks/commit-msg-ticket-attached {1}
post-commit:
  commands:
    edpa-evidence:
      run: sh .edpa/engine/scripts/hooks/post-commit-evidence
pre-push:
  commands:
    edpa-id-safety:
      run: sh .edpa/engine/scripts/hooks/pre-push-id-safety {1} {2}
      use_stdin: true

Commit konvence:

git commit -m "feat(S-200): implement OMOP CDM parser"
git commit -m "fix(S-215): validate upload file size"
git commit -m "test(S-201): add unit tests for parser"
git commit -m "docs(E-10): update epic hypothesis"

EDPA engine rozpoznává reference S-XXX, F-XXX, E-XXX v commitech (a volitelně v PR) pro detekci evidence.

Pull Request workflow (volitelné, jen s GitHub remote):

git push origin feature/S-200-omop-parser
gh pr create --title "S-200: OMOP CDM parser implementation" \
  --body "Closes #42

## Changes
- Implemented OMOP CDM parser
- Added schema validation

## Testing
- Unit tests: 15 passing
"

PR review = signál pro EDPA. Aby se PR-thread signály (pr_reviewer, issue_comment) dostaly do evidence[], je potřeba volitelný contribution-sync workflow — viz 2.3.

2.3 Volitelný GitHub PR-signal sync

EDPA V2 funguje čistě lokálně — post-commit hook a /edpa:materialize zapisují commit_author, yaml_edit a state_transition do evidence[]; engine je čistý reader. GitHub je volitelný a slouží pouze k materializaci PR-thread signálů.

S --with-ci se nainstaluje jediný V2 workflow .github/workflows/edpa-contribution-sync.yml. Po merge PR spustí sync_pr_contributions.py, který z PR-threadu vytáhne signály (pr_reviewer, issue_comment) a zapíše je do evidence[] příslušných itemů. Vyžaduje secret EDPA_TOKEN (viz docs/edpa-token-setup.md). Flow metriky lze číst přes MCP nástroj edpa_flow_metrics.

2.4 Iteration Close

Na konci každé iterace (1 týden AI-native / 2 týdny classic):

Claude Code (doporučeno):

/edpa:close-iteration PI-2026-1.1

Claude Code (skill close-iteration) připraví kapacitu, spustí EDPA engine a vygeneruje reporty automaticky.

Manuální CLI:

python3 .edpa/engine/scripts/engine.py --edpa-root .edpa --iteration PI-2026-1.1
# volitelne: --output cesta/edpa_results.json

Výstupy:

.edpa/reports/iteration-PI-2026-1.1/
  edpa_results.json        # Kompletni vypocet (JSON)
  timesheet-alice.md       # Vykaz pro kazdou osobu (DerivedHours > 0)
  timesheet-team.md        # Agregovany tymovy rollup
  edpa-results.xlsx        # Team Summary + Item Costs (Excel)
.edpa/snapshots/
  PI-2026-1.1.json         # Zmrazeny snapshot (audit trail)

Výpočet (od v1.14 jediná cesta): score = JS × CW, hours = (score / Σ score) × capacity. Žádný --mode simple|full ani Role Strength.

Score        = JobSize × CW
DerivedHours = (Score / ΣScores) × Capacity

Invarianty (engine automaticky kontroluje):

• Součet DerivedHours osoby == její kapacita (přesně)
• Součet poměrů == 1.0
• Žádné záporné hodiny
• Pokud invariant selže, engine hlásí FAIL

2.5 Aktualizace iteračního plánu

Po uzavření iterace vytvořit/aktualizovat .edpa/iterations/PI-2026-1.1.yaml:

iteration:
  id: PI-2026-1.1
  pi: PI-2026-1
  start_date: 2026-04-01
  end_date: 2026-04-14
  weeks: 2
  status: closed

planning:
  capacity: 380
  planning_factor: 0.80
  planned_sp: 24
  stories:
    - S-200
    - S-201
    - S-202

delivery:
  delivered_sp: 24
  predictability: "100%"
  velocity: 24
  spillover: []
  unplanned: []
  notes: "První iterace -- plný delivery."

Fáze 3: PI Close (Po 4-5 iteracích)

Cesta A: Claude Code (doporučeno)

/edpa:calibrate

Claude Code (skill /edpa:autocalib) spustí kalibraci signálových vah přes Monte Carlo + coordinate-descent optimalizátor, vyhodnotí MAD a navrhne úpravy cw_heuristics.yaml. Pro generování reportů:

/edpa:reports PI-2026-1

Cesta B: Manuální CLI

Následující kroky popisují manuální postup.

3.1 Retrospektiva

Na konci PI (po 4 delivery iteracích + 1 IP iterace):

1. Projít auto-detekci vs. realita na 5-10 stories
2. Pro každou story porovnat: kdo byl auto-detekován, jaké CW engine přiřadil, odpovídá realitě?

3.2 Zaznamenat ground truth

Kalibrátor běží proti Monte Carlo syntetickému korpusu a hledá MAD-optimální signálové váhy v .edpa/config/cw_heuristics.yaml. Žádný ground_truth.yaml není povinný — lze spustit kdykoli, i před prvním PI close.

Pokud chcete kalibrovat proti reálným záznamům z PI retro, zapište team-confirmed CW korekce do .edpa/data/ground_truth.yaml:

records:
  - person: alice          # id z .edpa/config/people.yaml
    item: S-200
    iteration: PI-2026-1.1
    confirmed_cw: 0.35     # PM/retro-confirmed share (0..1)
    notes: "design review + arch. rozhodnutí"

  - person: bob
    item: S-200
    iteration: PI-2026-1.1
    confirmed_cw: 0.65
    notes: "implementation + tests"

  # ... alespoň 20 záznamů pro spolehlivou kalibraci

3.3 Kalibrace CW signálů

Claude Code (doporučeno):

/edpa:calibrate

Manuální CLI:

python3 .edpa/engine/scripts/calibrate_signals.py \
  --ground-truth .edpa/data/ground_truth.yaml \
  --heuristics .edpa/config/cw_heuristics.yaml

calibrate_signals.py (skill /edpa:calibrate) jede dvoufázově: náhodný Monte Carlo sample napříč signálovými váhami → coordinate-descent (Nelder-Mead) zjemnění kolem nejlepších kandidátů. Metrika je MAD na syntetickém korpusu; nižší MAD = lepší kalibrace.

Výstup (orientačně):

MAD=0.041200
RECORDS=20
TOTAL_DEVIATION=0.824000

Interpretace MAD (Mean Absolute Deviation):

Korekce signálových vah: pokud MAD > 0.06, podívat se na záznamy s největším abs(auto_cw - confirmed_cw), identifikovat vzory dle role (typicky BO, PM, Arch — strategické role jsou Gitem podhodnoceny), upravit signals: váhy v .edpa/config/cw_heuristics.yaml a znovu spustit kalibraci.

3.4 Plánování dalšího PI

1. Nové epicy/features — přidat přes backlog.py add (auto-commit) do .edpa/backlog/
2. WSJF prioritizace: python3 .edpa/engine/scripts/backlog.py wsjf
3. Kapacitní plánování — aktualizovat .edpa/config/people.yaml (změny FTE, dostupnost)
4. Vytvořit nové iteration soubory v .edpa/iterations/ pro nový PI

Fáze 4: Kontinuální provoz

S Claude Code (doporučeno)

Každá iterace:

/edpa:close-iteration PI-2026-1.X    # uzavreni iterace
/edpa:reports PI-2026-1.X             # generovani reportu

Každý PI:

/edpa:close-pi PI-2026-1               # uzavreni PI: guard iteraci, status, rollup
/edpa:calibrate                       # kalibrace signalovych vah

Každá iterace (1 týden AI-native / 2 týdny classic)

1. Planning — vybrat stories, přiřadit assignees
2. Denní práce — branch naming, commity s referencemi, (volitelně) PR review
3. Iteration Close — EDPA engine, generování reportů
4. Review — tým zkontroluje výkazy, zahlásí korektury (manuální CW override přes --contributor / /contribute)

Každý PI (5 týdnů AI-native / 10 týdnů classic)

1. Retrospektiva — auto-detected CW vs realita
2. Ground truth — zaznamenat alespoň 20 nových záznamů
3. CW kalibrace — calibrate_signals.py, vyhodnotit MAD
4. Velocity trend — porovnat delivery across iterací
5. Predictability — (delivered_sp / planned_sp) across iterací

# Status za celou iteraci
python3 .edpa/engine/scripts/backlog.py status --iteration PI-2026-1.3

# Celkovy status projektu
python3 .edpa/engine/scripts/backlog.py status

# Kapacitni override (napr. dodatecne hodiny mimo evidenci)
python3 .edpa/engine/scripts/capacity_override.py PI-2026-1.1 --add --person bob --hours 12

# Velocity / flow reporty
python3 .edpa/engine/scripts/reports.py PI-2026-1.1

Volitelná automatizace přes GitHub Actions

V2 má jediný volitelný workflow (jen s --with-ci):

Checklist — Co mít hotové

Den 1

• Engine vendorovaný do .edpa/engine/ (/edpa:setup nebo project_setup.py)
• .edpa/config/people.yaml — tým s rolemi, FTE, kapacitami (teams + people)
• .edpa/config/edpa.yaml — název projektu, governance, naming
• .edpa/config/cw_heuristics.yaml — výchozí signálové váhy (ze šablony)
• .edpa/config/id_counters.yaml — naseto
• .edpa/iterations/ — PI + iterace s datumy
• Backlog naplněný přes backlog.py add (alespoň 1 Epic, 3 Features, 10 Stories)
• backlog.py validate projde bez chyb
• engine.py --demo projde úspěšně
• (volitelné) git hooky nainstalovány (--with-hooks), contribution-sync CI (--with-ci)

Týden 1

• Tým pracuje s branch naming konvencí (feature/S-XXX-popis)
• Commity referují work items (feat(S-XXX): ...)
• post-commit hook zaznamenává commit_author evidenci
• (volitelné) PR reviews probíhají a contribution-sync je materializuje

Konec iterace 1

• EDPA engine spuštěn pro iteraci
• edpa_results.json vygenerován v .edpa/reports/iteration-<ID>/
• Výkazy timesheet-<id>.md vygenerovány (per-person)
• Všechny invarianty prošly (all_invariants_passed: true)
• Snapshot zmrazen v .edpa/snapshots/
• Tým zkontroloval výsledky

Konec iterace 2-4

• Velocity stabilní (odchylka < 20%)
• Prediktabilita > 80% (delivered / planned)

Konec PI 1

• Ground truth zaznamenáno (min. 20 záznamů)
• CW kalibrace provedena (calibrate_signals.py / /edpa:calibrate)
• MAD vyhodnoceno (cíl: < 0.06)
• Signálové váhy upraveny v cw_heuristics.yaml (pokud MAD > 0.06)
• Plánování PI 2 — nové epicy, WSJF, kapacity
• Nové iteration soubory v .edpa/iterations/ pro nový PI

CLI Reference

Claude Code příkazy (doporučeno)

engine.py — EDPA výpočetní jádro

backlog.py — Správa backlogu

reports.py — Výkazy a PI summary

board.py — Lokální HTML board

capacity_override.py — Kapacitní override

detect_contributors.py / calibrate_signals.py

sync_pr_contributions.py (volitelné, CI)

Architektura

V2 je local-first: .edpa/ (backlog v .md + config) je jediný zdroj pravdy, git je audit trail. GitHub je volitelný — jediný tok směrem dovnitř je jednosměrné materializování PR-thread signálů do evidence[].

                  .edpa/  (git) -- JEDINY ZDROJ PRAVDY
        backlog/**/*.md  +  config/  +  iterations/
                                |
              +-----------------+-----------------+
              |                 |                 |
        EDPA engine        backlog.py         board.py
        (vypocet)          (add/tree/wsjf)    (HTML board)
              |                                    |
        +-----+-----+                              v
        |           |                       .edpa/board.html
   reports/     snapshots/                  (lokalni)
   timesheet-*.md  *.json
   xlsx

Tok dat

   (volitelne) GitHub PR thread
   reviews / komentare
              |
              |  edpa-contribution-sync.yml (po merge PR)
              |  sync_pr_contributions.py
              v  -- JEDNOSMERNE: signaly -> evidence[]
   post-commit hook / /edpa:materialize
   local_evidence.py --materialize  (dedup podle ref)
              |  zapisuje commit_author, yaml_edit, state_transition
              v  -- do evidence[]
   +-------------------------------------+
   |  .edpa/  (git) -- ZDROJ PRAVDY      |
   |  backlog *.md  config  iterations   |
   |  evidence[]  -- jediny zdroj signalu|
   +-------------------------------------+
              |
        aggregate_signals (skip weight-0)
        evidence[] -> contributors[] (cw)
              |
        +-----+-----------------------+
        |             |               |
   EDPA engine    reports.py      board.py
   (pure reader)  timesheety      HTML board
        |
   reports/ + snapshots/ + xlsx

Evidence detection

EDPA je evidence-driven. cw[osoba, item] = contribution_score / Σ_osoby contribution_score, kde contribution_score = Σ signal_weight. Výchozí signálové váhy (cw_heuristics.yaml):

Lokální signály (commit_author, yaml_edit, state_transition) materializuje do evidence[] post-commit hook a /edpa:materialize; engine je čte už jen z evidence[] (žádný git scan při výpočtu). PR-thread signály (pr_reviewer, issue_comment) přicházejí jen přes volitelný contribution-sync. Manuální /contribute @person weight:X (nebo --contributor) nese váhu verbatim.

Rolové váhy přispěvatelů: owner 1.0 / key 0.6 / reviewer 0.25 / consulted 0.15; evidence_threshold 1.0.

Výpočet EDPA

Od v1.14 jediná výpočetní cesta (žádný simple/full/gates mode). Pro každou osobu v iteraci:

1. Sebrat evidenci na každé položce → contributors[] s cw
2. Pro každý pár (osoba, položka): score = JS × CW
3. Pro každou osobu: ratio_i = score_i / sum(scores)
4. Odvozené hodiny: hours_i = ratio_i × capacity

Troubleshooting

gh auth (jen volitelný PR-signal sync)

EDPA V2 jádro gh nepotřebuje. Pokud selže volitelný contribution-sync workflow na autentizaci, doplňte secret EDPA_TOKEN (viz docs/edpa-token-setup.md) nebo lokálně:

gh auth login        # bezny repo scope staci
gh auth status

Backlog validate — chyby

ERROR: S-200 references non-existent feature F-999

Řešení:

• Ověřit že všechny feature: reference v stories ukazují na existující features
• Každá story musí mít parent feature
• Každá feature musí mít parent epic

WARNING: S-200 Job Size exceeds maximum (JS=13, max=8)

Řešení:

• Story JS max 8 (classic 2/10) nebo 5 (AI-native 1/5)
• Rozdělit velkou story na menší

EDPA engine — invariant failure

INVARIANT FAILURE -- check results
All invariants passed: NO

Možné příčiny:

• Osoba nemá žádné evidence (není assignee, žádné commity)
• Všechny CW jsou 0 (žádná evidence nad threshold)
• Kapacita je 0

Řešení:

• Ověřit že každá osoba má alespoň 1 přiřazený work item
• Ověřit že commity/PR referují správné item ID (S-XXX, F-XXX)
• Ověřit .edpa/config/people.yaml — kapacity > 0

Branch naming — odmítnutý commit/push (git hook)

Branch name does not follow EDPA convention.
Required format: {type}/{item-id}-{description}

V V2 hlídá konvenci lokální git hook (--with-hooks), už ne CI.

Řešení:

• Formát: feature/S-200-omop-parser, bugfix/S-215-fix-validation
• Typ: feature, bugfix, hotfix, chore
• Prefix: S (Story), F (Feature), E (Epic), T (Task), D (Defect), EV (Event)
• main, develop, release/* jsou výjimky (prochází bez kontroly)

commit-msg hook — chybějící reference itemu

commit-msg: no item reference found

Řešení:

• Přidat referenci itemu do zprávy: feat(S-200): ...
• Nebo pro commity bez ticketu použít prefix no-ticket:

Python — chybějící závislosti

ERROR: pyyaml required. Install with: pip install pyyaml

Řešení:

pip install pyyaml openpyxl ruamel.yaml

Iteration close — "config not found"

ERROR: .edpa/config/people.yaml not found. Run EDPA setup first.

Řešení: spustit setup (vendoruje engine + naseje configy):

/edpa:setup
# nebo
python3 .edpa/engine/scripts/project_setup.py

Případně zkopírovat ze šablon v .edpa/engine/templates/*.tmpl:

cp .edpa/engine/templates/people.yaml.tmpl .edpa/config/people.yaml
cp .edpa/engine/templates/cw_heuristics.yaml.tmpl .edpa/config/cw_heuristics.yaml
cp .edpa/engine/templates/edpa.yaml.tmpl .edpa/config/edpa.yaml

Soubory v .edpa/config/*.yaml (ne *.yaml.tmpl) musí být commitnuté v repu.

MAD příliš vysoké (> 0.10)

Možné příčiny:

• Strategické role (BO, PM, Arch) mají systematicky nižší auto-CW než realitu
• Git měří jen commity/PR, ne rozhodování, specifikaci, mentoring

Řešení:

1. Analyzovat záznamy s největším abs(auto_cw - confirmed_cw)
2. Seskupit dle role
3. Upravit signals: váhy v .edpa/config/cw_heuristics.yaml (zvýšit váhu signálu, který danou roli reprezentuje)
4. Případně přidat manuální /contribute @person weight:X u itemu, kde je strategická práce neviditelná v Gitu
5. Znovu spustit calibrate_signals.py

PR-signal sync — chybějící evidence z PR

PR-thread signály (pr_reviewer, issue_comment) se do evidence[] dostanou jen přes volitelný contribution-sync.

Řešení:

• Ověřit, že je nainstalován .github/workflows/edpa-contribution-sync.yml (/edpa:setup --with-ci)
• Ověřit secret EDPA_TOKEN (viz docs/edpa-token-setup.md)
• Workflow běží až po merge PR; před merge jsou v evidenci jen lokální signály (commit_author, yaml_edit)

Slovníček