EDPA — Evidence-Driven Proportional Allocation
Deriving capacity from delivery evidence
1. Summary
A person declares capacity for a period. The system identifies work items they demonstrably contributed to. Capacity is ex post proportionally split among relevant items based on Job Size and contribution level.
The result is a report that is a byproduct of delivery, not a separate administrative activity.
The model provides two complementary views of the same data:
- Per-person view: how a person's capacity is distributed among their items → reports, timesheets
- Per-item view: how work on an item is distributed among people → cost allocation, audit per deliverable
2. Terminology
| Term | Definition | Configuration |
|---|---|---|
| Iteration | Delivery cycle. Stories are planned, delivered, and closed. | 1w (AI-native) / 2w (classic) |
| Planning Interval | Planning cycle. Features are planned, coordinated, and evaluated. | 5w (4+1 IP) / 10w (8+2 IP) |
| IP Iteration | Innovation & Planning iteration at the end of PI. | Last iteration in PI |
| Job Size (JS) | Relative size estimate of a work item. Modified Fibonacci per WSJF (SAFe 6). | 1, 2, 3, 5, 8, 13, 20, 40, 100 |
| WSJF | Prioritization score: (BV + TC + RR&OE) / JS | Independent per level |
| CW | Contribution Weight — per-item normalized share of a person on an item (Σ across persons = 1.0 per item). | 0–1.0 |
| Signal Weight | Weight of a single evidence signal type (commit_author, pr_reviewer, issue_comment) aggregated by detect_contributors.py. In the config under the signals.* key. | cw_heuristics.yaml |
| Contribution Score | Σ fired signal weights per (person, item). Input to per-item normalization. In code as contribution_score. | Automatic |
| Derived Hours | Derived hours, model output. | After Iteration Close |
3. Model architecture
3.1 Three separate layers
| Layer | Purpose | Where it lives |
|---|---|---|
| Operational Metadata | Live delivery data | GitHub Issues + Projects |
| Capacity Registry | People capacity, roles, FTE | YAML / JSON in repo |
| Evidence & Reporting | Frozen snapshots, reports, signatures | /snapshots, /reports, /signed |
3.2 Source of truth
GitHub IS source of truth for: issue hierarchy, ownership, status, Job Size, WSJF inputs, review trail, delivery audit trail.
GitHub IS NOT source of truth for: hourly capacity, FTE, derived hours, signature states. These live in the evidence layer.
4. Work item hierarchy
Each level has its own independent Job Size and WSJF. Feature WSJF is not computed from Stories below it.
| Level | Job Size range | GitHub mapping |
|---|---|---|
| Initiative | 1–100 (mod. Fibonacci) | Issue Type: Initiative |
| Epic | 1–100 (mod. Fibonacci) | Issue Type: Epic |
| Feature | 1–100 (mod. Fibonacci) | Issue Type: Feature |
| Story | 1–100 (mod. Fibonacci) | Issue Type: Story |
| Defect | 1–100 (mod. Fibonacci) | Issue Type: Defect |
| Task | — (sub-Story checklist) | Issue Type: Task |
5. Model: Evidence-Driven Proportional Allocation
5.1 Iteration Planning Protocol
Before EDPA derives hours (ex-post), the team must plan the iteration (ex-ante). Planning requires confirmed capacity as input.
- Confirm Capacity — Each team member confirms availability. This is a commitment, not an estimate. External collaborators negotiate allocation explicitly. Result:
availability: confirmedinpeople.yaml. - Adjust per-iteration capacity (optional) — One-off deviations from baseline (PTO, overtime, ramp) are recorded as a per-iteration override in the iteration YAML
people:block — the/edpa:capacity <iteration> --add --person <id> --hours …command. Thecapacity_per_iterationbaseline stays; the engine applies the override and reportscapacity_baseline+capacity_override. Set before closing the iteration (Stage 1 of/edpa:close-iteration). - Calculate Planning Capacity —
Planning_Capacity = Σ Capacity[P, I] × planning_factor. Theplanning_factoris a team-level property (configured per team inpeople.yamlunderteams:). Default: 0.8. - Select Work — Pull stories from the prioritized backlog (WSJF order) until
Σ JobSizeapproaches historical velocity ×planning_factor. Do not plan to 100%. - Buffer — The remaining ~20% absorbs support, maintenance, incidents, and unplanned work. If buffer items generate evidence, EDPA allocates them normally.
- Edge case — If no unplanned work occurs, all capacity goes to planned items. The guarantee
Σ = Capacityholds regardless.
5.2 Inputs
| Input | Source | Example |
|---|---|---|
Capacity[P, I] | Confirmed at Iteration Planning | 40h |
RelevantItems[P, I] | Automatic from GitHub evidence (Story Done + Feature/Epic/Initiative gates) | 6 items across 4 levels |
JobSize[item] | Custom field on issue | Mod. Fibonacci 1–100 |
cw[P, item] | detect_contributors.py — additive aggregation + per-item normalization | 0–1.0 (Σ on item = 1.0) |
5.3 Evidence detection
| GitHub signal | Signal weight | Detection |
|---|---|---|
| Commit author | 4.00 | Commit with S-/F-/E-/I-XXX in branch/message |
| PR reviewer | 2.17 | Submitted PR review (excluding self) |
| Issue / PR comment | 1.46 | Comment (bots excluded) |
/contribute @person weight:X | explicit | Manual additive signal — weight X from the directive |
- Signals aggregate additively into
contribution_scoreper (person, item) — no "highest wins" - Per-item normalization yields the cw share:
cw = contribution_score / Σ_persons contribution_score /contributeis a peer signal — it does not override auto-detection, it adds weight- Default weights above are calibrated by Monte Carlo simulation (1000 synthetic scenarios)
issue_comment and pr_reviewer weights. See auto-calibration.md.5.4 Calculation — single source, sum-and-normalize
cw.
Worked example: Calculator. Full spec: methodology.md § 5.4.
5.5 Mathematical guarantees (two)
5.6 What the engine credits per item type
EDPA works with 6 issue types (S-, F-, E-, I-, D-, T-). Not all of them participate in the hours calculation the same way:
| Type | Evidence detection | Engine credits | Iteration filter |
|---|---|---|---|
Story (S-) | yes | yes, only status==Done | exact match (PI-2026-1.1) |
Feature (F-) | yes | yes, Done + gate transitions | PI match (PI-2026-1.x) |
Epic (E-) | yes | yes, Done + gate transitions | always (cross-PI) |
Initiative (I-) | yes | yes, Done + gate transitions | always (cross-PI) |
Defect (D-) | yes | yes, only status==Done | always (cross-PI) — intentional |
Task (T-) | yes | no — engine does not walk tasks/ | n/a |
T-XXX reference, the evidence is detected, but the engine assigns it no score — the work should be attached to the parent Story.6. Dual-view CW: two questions, one dataset
CW = 0.25 for a reviewer can mean two things. These are two different questions — the model solves both from the same data:
Question: How is person P's capacity distributed among their items?
Question: How is work on item X distributed among people?
| View | Question | Output | Guarantee |
|---|---|---|---|
| Per-person | How many hours did P spend on what? | Report, audit | Σ = capacity |
| Per-item | How many people and hours did item X cost? | Cost allocation | Σ shares = 100% |
7. Cadence configuration
| Cycle | Duration | 1.0 FTE | 0.5 | 0.25 |
|---|---|---|---|---|
| Iteration | 2 weeks | 80h | 40h | 20h |
| PI | 10 weeks | 400h | 200h | 100h |
| Cycle | Duration | 1.0 FTE | 0.5 | 0.25 |
|---|---|---|---|---|
| Iteration | 1 week | 40h | 20h | 10h |
| PI | 5 weeks | 200h | 100h | 50h |
8. Learning loop
- CW: After 2–3 iterations, evaluate the heuristic. Recalibrate signal weights with the
/edpa:calibrateoptimizer (Monte Carlo + coordinate descent, synthetic corpus). - Job Size: Reference Story “3” ≠ Feature “3”. Independent per level.
- AI: You report time for delivery, not minutes of coding. AI → velocity, not report.
9. GitHub implementation
9.1 Native Issue Types & custom fields
EDPA is local-first: the engine reads local git evidence and backlog YAML, and the GitHub layer is optional. If your team uses GitHub, Issue Types are a native GitHub feature at the organization level (not labels, not custom fields). Managed via issue_types.py setup --org <org>. Filter syntax: type:Epic, type:Story etc.
| Issue Type | Description |
|---|---|
| Initiative | Business case, investment proposal |
| Epic | Strategic goal, 6-9 months |
| Feature | Must fit within a Planning Interval |
| Story | Delivered within an iteration |
| Defect | Defect in existing functionality |
| Task | Technical work |
| Custom field | Type | Values |
|---|---|---|
| Job Size | Number | Mod. Fibonacci 1–100 |
| BV / TC / RR&OE | Number | Mod. Fibonacci 1–100 |
| WSJF Score | Number | Auto (Action) |
| Planning Interval | Iteration | 5 or 10 weeks |
| Iteration | Iteration | 1 or 2 weeks |
| Team | Single select | Team values |
| Primary Owner | Assignee | Accountable owner |
9.2 The engine runs locally; the GitHub layer is optional
V2 has no GitHub Actions pipeline. The engine, WSJF computation, iteration/PI close, and velocity all run locally via /edpa:close-iteration and MCP tools. Attribution is handled by a post-commit hook (local_evidence.py) — it emits commit_author for every commit that references an EDPA item, and works offline and on GitLab/Forgejo too. Hooks register into .git/hooks/, or — if the project uses lefthook — via a single extends: line EDPA writes into lefthook.yml itself.
| Layer | Where it runs | Function |
|---|---|---|
| Engine + calculation | Locally (/edpa:close-iteration) | Score, DerivedHours, snapshot + reports (MD/JSON/XLSX) + per-item |
| Attribution | Local post-commit hook | commit_author from git history for every item-referencing commit |
| Velocity | Locally (MCP edpa_flow_metrics) | Velocity and flow metrics from local data |
| Contribution sync (optional) | GitHub Action — --with-ci | edpa-contribution-sync.yml: after a PR merge, appends pr_reviewer + issue_comment from the PR thread into evidence[] |
--with-ci: only when you have signals that don't live in git history (PR reviews, comments) and want them counted. Single-dev / review-light / off-GitHub teams skip the workflow — local evidence is enough.9.3 Timestamp fields
Every backlog item carries three timestamp fields (written by the engine on status transitions; populated from the issue if the team uses GitHub):
| Field | Source | Usage |
|---|---|---|
created_at | Item creation | Cycle time start, item age |
updated_at | Last item change | Freshness, ordering |
closed_at | Transition to Done | Cycle time end, throughput |
9.4 Flow Metrics MCP tool
The edpa_flow_metrics MCP tool provides work flow analytics based on timestamp fields:
| Metric | Calculation | Usage |
|---|---|---|
| Cycle Time | closed_at - created_at | How long it takes to deliver an item |
| Throughput | Closed items count / iteration | Predictability, capacity planning |
| Item Age | now - created_at (open items) | Detecting stagnating items |
9.5 Branch naming & DoR
CI check blocks PRs without reference to an issue (S-XXX, F-XXX, E-XXX). DoR: Issue Type, Parent, Job Size, BV+TC+RR&OE, Owner.
9b. ID collisions and renumbering (multi-developer setup)
Teams: reserve IDs on the shared git remote (since 2.23.0). A project can hand ID allocation to the git remote the team already pushes to. A reservation is a push of one metadata commit to the ref refs/edpa/ids that the server accepts only if the ref has not moved in the meantime — exactly one pusher wins, the others try the next number. The ID is therefore unique across worktrees, branches and developers the moment it is assigned (~2 s), with no GitHub API and no gh. A ticket no longer has to go through a PR just to "claim" its number; the hooks only let through a ticket that has a reservation.
python3 .edpa/engine/scripts/id_counter.py init-remote --write-config # once per repository
git add .edpa/config/edpa.yaml && git commit -m "chore(no-ticket): reserve ticket IDs in the shared ledger"
python3 .edpa/engine/scripts/id_counter.py status # who allocates IDs here, and why Full guide: dev-collisions.md.
Without a shared ledger (the default, local mode) the worktrees of one clone share a sequence, but two clones do not — if two developers concurrently create a backlog item from the same starting state of main, both get the same ID (e.g. both S-5). The pre-push hook catches the collision; at the latest the merge of the second PR does.
Four defense layers detect the collision as early as possible, plus a semi-automatic recovery tool:
| Layer | When | Tool | What it does |
|---|---|---|---|
| 5 | local git commit | validate_ids.py --staged (pre-commit hook) | Blocks commit if staged backlog has ID inconsistencies (filename ≢ id, missing fields, duplicates) |
| 6 | local git push | validate_ids.py --pre-push (pre-push hook) | Fetch origin, compare local-added IDs against origin/main. Blocks push if ID already exists upstream |
| 7 | PR open/sync (server-side) | .github/workflows/edpa-collision-check.yml | Runs renumber_collisions.py --check. On collision: posts a PR comment with fix instructions + fails the check (PR's merge button stays disabled) |
| Recovery | after conflict | renumber_collisions.py --apply | Renames the local file (S-5.md → S-6.md), rewrites id:, updates parent: refs in dependent items, bumps counter |
Standard recovery flow
Setup for a new project (one-time):
Full guide with decision tree and common collision shapes (single / multi / parent-chain / cascading): docs/dev-collisions.md.
9c. How ID reservation works — the ledger on a git ref
Numbers are unique when one place hands them out. Previously every working tree had its own counter and knew nothing about the others, so two worktrees, two clones or two people got the same S-285. The ledger makes the git remote the team already pushes to that one place — like a ticket dispenser. No forge API, no gh: only git fetch and git push, so it works on any git server.
What it is built on in git
Git has two layers: objects (commits, trees, file contents — named by hash, immutable) and refs (named pointers to a commit; a ref is a name and one hash). A branch is the ref refs/heads/main, a tag refs/tags/v2.23.0, GitHub keeps refs/pull/94/head for a pull request. refs/edpa/ids is a pointer of the same kind, only outside refs/heads/. Consequences:
git cloneandgit pulldo not fetch it on their own (they take branches and tags),- it is not listed among branches in the forge UI,
- branch rules and CI triggers do not apply to it.
Git itself stores data this way (refs/notes/), and so do Gerrit and git-bug.
What the ref holds
The ref points at the newest commit of a chain. Every commit has a parent (the previous reservation), a tree with a single file counters.yaml, and a message that is the audit record of the reservation. It is ordinary git history, without any of your code.
schema: 1
counters: # highest number handed out, per type
Defect: 93
Story: 290
floors: # highest number that may exist WITHOUT a reservation record
Defect: 92
Story: 289 alloc S-290: Website (CZ/EN): describe the remote ID authority
EDPA-Id: S-290
EDPA-Type: Story
EDPA-Parent: F-129
EDPA-Branch: main
EDPA-Created-At: 2026-10-08T07:52:11Z
EDPA-Nonce: 5f0c… git fetch origin refs/edpa/ids
git log FETCH_HEAD --format='%s [%an, %ar]'
git show FETCH_HEAD:counters.yaml One reservation, step by step
- Read. Fetch the tip of
refs/edpa/idsinto a temporary ref and readStory: 290. - Build. Assemble a commit with
Story: 291using plumbing commands — no working tree, no index, your checkout is untouched. - Push with a condition: “accept only if the ref still points at the commit from step 1”.
- The server decides. Accepted →
S-291is yours. Rejected because the ref moved → somebody was faster; back to step 1 and the next number. - Only now the item file is written and committed on your branch.
git hash-object -w --stdin # counters.yaml → blob
git mktree # tree with that one file
git commit-tree <tree> -p <tip> # commit, message = audit record
git push --no-verify --porcelain \
--force-with-lease=refs/edpa/ids:<tip> \
origin <new commit>:refs/edpa/ids Where atomicity comes from
From the git push protocol. For every ref the client sends a triple:
<old hash> <new hash> refs/edpa/ids The server locks the ref, checks that it currently holds the old hash, and only then writes the new one — a compare-and-swap. The same mechanism makes a plain git push to main fail when someone pushed before you. --force-with-lease=<ref>:<hash> states the expected value explicitly; with an empty value it means “only if the ref does not exist yet”, which is how the ledger is created.
- The outcome is never read from error text. After any push that is not a clean success the client re-reads the remote: the ref contains my commit → reserved (even if the acknowledgement was lost in a timeout); the ref moved without it → lost race, retry; the ref did not move → the server refuses this environment.
- Nonce. Two worktrees of one person can build a byte-identical commit; git would answer the second push “up to date” and both would own the number. Every message carries a random
EDPA-Nonce, and “up to date” is never treated as success. --no-verifyon this one push only: projects run tests inpre-push, and this push carries a single metadata commit, never code.
Why a hand-written ticket does not get through
The hooks (validate_ids.py) verify the reservation of every new item. A number at or below the floor needs nothing — the item predates the ledger. Above the floor a record for that ID must exist and its EDPA-Created-At must equal the item's created_at. “Number ≤ highest reserved” would not do: an ID minted by an outdated plugin passes that whenever someone holds an unmerged reservation above it. pre-commit works from the local copy (offline it only warns); pre-push and CI verify online — which also catches --no-verify commits.
Branches, worktrees, clones, agents
- Branches: the number is reserved on the remote, not on a branch. The item file is committed wherever you are; two branches cannot get the same ID.
- Worktrees of one clone: share the ledger copy, the lock and the mode (all of it lives in the shared
.git). They switch together, including ones cut before the opt-in commit. - Other clones and people: coordinated by the server.
- Agent sessions: like a person, provided they may push to the repository. A sandbox restricted to its own branch cannot reserve and says so.
- Unchanged: the content of a ticket is visible to other branches only after merge.
| Where | What |
|---|---|
refs/edpa/cache/ids | newest ledger state this clone knows; only ever moves forward |
git config edpa.idLedgerRemote / edpa.idLedgerRef | where this clone last reached the ledger |
<git common dir>/edpa/ | lock, high-water mark, pool of numbers reserved ahead |
Failure behaviour
| Situation | Behaviour |
|---|---|
| No network | no ID, nothing written. A number is never guessed — that is how two ID series start. For offline work take numbers ahead: id_counter.py reserve --type Story --count 5 |
| Ref deleted or rewound on the server | every clone has the chain cached and the counters are maxima, so the next reservation from a clone that remembers more restores it |
| Ref overwritten with unrelated history | both histories are merged, per-type maximum |
| Process dies between reservation and file write | the number is burned; a gap in the sequence is harmless |
A stray file like S-9999.md | refused (it would lift everyone's sequence); adopt on purpose with id_counter.py doctor --raise |
| Lost race | automatic retry, about 2 s per attempt |
Why one ref, not one per type
A ref per type would save one retry when a Story and a Defect are created in the same second. The gain is small (a retry costs about 2 s; under 16 concurrent processes the average was 1.6 attempts per reservation) and the bottleneck is the network round trip, not the type. The price would be seven reads instead of one, a non-atomic bootstrap, seven audit logs and harder self-healing. The file carries schema: 1, so a later split would not change ticket IDs.
Measured: GitHub accepted the push to refs/edpa/*, about 2.4 s per reservation; 2×128 concurrent reservations from 3 clones and 8 worktrees without a duplicate. Not verified: forges other than GitHub, Windows. Full technical reference: id-ledger.md · operations: dev-collisions.md · decision: ADR-014.
10. Reports and audit
10.1 Pipeline
10.2 Freeze rule
After Iteration Close: snapshot is frozen. Evidence is not overwritten in-place. Every correction is a new revision. Essential for audit defense.
10.3 Audit principle
Provability rests on 5 pillars:
- Local git delivery evidence (commit_author, yaml_edit, gate_events, story_activity)
- Capacity registry (YAML)
- Frozen snapshot (reproducible input)
- Reproducible calculation (Score = JS × CW; CW = additive aggregation + per-item normalization)
- Signed output (BankID, law 21/2020 Sb.)
11. Assumptions and risks
- All items are closed (undelivered items are moved)
- Capacity confirmed at Iteration Planning
- Branch naming enforced (CI check)
- Job Size consistent per level
- CW is calibrated after the first iterations
| Risk | Mitigation |
|---|---|
| Auditor rejects | Methodology + snapshots + BankID |
| CW mismatch | Override + calibration |
| Commit without S-/F-/E-XXX | CI check blocks PR |
| PM/Arch without commits | Comments + /contribute |
| 0 items for a person | Process escalation |
12. Comparison with alternatives
Fixed Split
Pre-defined buckets (e.g., 60% Dev, 20% Arch, 20% QA). Hours are split fixedly by role, regardless of actual contribution. Simple, but inaccurate.
EDPA v2.25.1
Evidence-Driven Proportional Allocation. Hours are derived automatically from local git evidence (commits, yaml edits, status transitions, in-flight Story activity); GitHub Projects + Actions are an optional add-on. Mathematical guarantee: Σ = Capacity.
Manual timesheets
Each team member manually fills in hours. Subjective, administratively demanding, has no per-item view, unauditable without additional evidence.
| Property | Fixed Split | EDPA v2.25.1 | Manual timesheets |
|---|---|---|---|
| Fixed buckets | Yes | No | No |
| Empty levels | Problem | Do not exist | N/A |
| Per-person view | Yes | Yes (primary) | Yes |
| Per-item view | No | Yes (dual-view) | No |
| Cross-functional | Limited | Full | Full |
| Automation | Medium | High | None |
| Math. guarantee | Complex | Native | No |
13. Implementation plan
| Phase | Time | Contents |
|---|---|---|
| Day 1 | 1h | /edpa:setup — vendor the engine into .edpa/engine/, config (edpa.yaml, people.yaml), seed the backlog |
| Day 1 (optional) | 30 min | --with-hooks (git hooks), --with-ci (contribution-sync workflow), --with-rules |
| Iteration 1 | 1–2w | Pilot operation, first reports from /edpa:close-iteration |
| Calibration | 10 min | /edpa:calibrate — recalibrate signal weights after the first iterations |
| Retro PI 1 | 1 day | Cadence, CW accuracy, velocity, dual-view validation |