docs(openspec): add reporting API contract documentation
Add comprehensive API documentation for the reporting endpoint: - Request/response structure - View type inference (did/is/will) - Blank vs explicit zero semantics - Status values and error responses Related to enhanced-allocation change.
This commit is contained in:
@@ -0,0 +1,74 @@
|
||||
# Allocation Indicators Specification
|
||||
|
||||
## Overview
|
||||
|
||||
This capability defines low-noise variance indicators for planning and execution surfaces.
|
||||
Indicators are decision aids, not decorative status coloring.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Use minimal status palette
|
||||
|
||||
The system SHALL use a minimal indicator palette:
|
||||
- `OVER` -> red
|
||||
- `UNDER` -> amber
|
||||
- `MATCH/SETTLED` -> neutral
|
||||
|
||||
#### Scenario: Match is neutral
|
||||
- **GIVEN** row variance equals 0
|
||||
- **WHEN** rendering status
|
||||
- **THEN** status uses neutral styling
|
||||
- **AND** no additional success color emphasis is required
|
||||
|
||||
### Requirement: Place indicators at summary edges
|
||||
|
||||
The system SHALL prioritize indicator display on row/column summary edges.
|
||||
|
||||
#### Scenario: Row-level over-allocation indicator
|
||||
- **GIVEN** project row total exceeds selected month plan
|
||||
- **WHEN** allocation grid renders
|
||||
- **THEN** project row summary status shows `OVER` in red
|
||||
|
||||
#### Scenario: Column-level over-capacity indicator
|
||||
- **GIVEN** member column total exceeds member month capacity
|
||||
- **WHEN** allocation grid renders
|
||||
- **THEN** member column summary status shows `OVER` in red
|
||||
|
||||
#### Scenario: Under-allocation indicator
|
||||
- **GIVEN** row or column total is below comparison target
|
||||
- **WHEN** grid renders
|
||||
- **THEN** summary status shows `UNDER` in amber
|
||||
|
||||
### Requirement: Keep indicators explainable
|
||||
|
||||
The system SHALL provide text status labels with numeric deltas for accessibility and clarity.
|
||||
|
||||
#### Scenario: Color is not sole signal
|
||||
- **WHEN** status is rendered
|
||||
- **THEN** UI includes text label (`OVER`/`UNDER`) and delta value
|
||||
|
||||
### Requirement: Distinguish project and resource variance semantics
|
||||
|
||||
Project variance and resource variance SHALL remain separate.
|
||||
|
||||
#### Scenario: Project over, resource under
|
||||
- **GIVEN** a project row is `OVER`
|
||||
- **AND** a member column is `UNDER`
|
||||
- **WHEN** indicators render
|
||||
- **THEN** each axis displays its own status independently
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Allocation indicator source
|
||||
|
||||
**Original behavior:** project indicator compared monthly allocation directly to lifecycle estimate assumptions.
|
||||
|
||||
**Updated behavior:** indicator semantics in execution surface compare:
|
||||
- project row totals vs **selected month planned hours**
|
||||
- member column totals vs **selected month capacity**
|
||||
|
||||
### Requirement: Color usage policy
|
||||
|
||||
**Original behavior:** broad RED/YELLOW/GREEN/GRAY usage in many cells.
|
||||
|
||||
**Updated behavior:** minimal red/amber/neutral policy with status emphasis on summary edges.
|
||||
@@ -0,0 +1,88 @@
|
||||
# Project-Month Plan Specification
|
||||
|
||||
## Overview
|
||||
|
||||
This capability defines explicit manager-entered monthly planning per project.
|
||||
It replaces derived monthly budget assumptions and becomes the planning source of truth for allocation variance.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Manager enters explicit monthly plan per project
|
||||
|
||||
The system SHALL allow managers to set planned hours for each project-month cell.
|
||||
|
||||
#### Scenario: Set monthly plan across multiple months
|
||||
- **GIVEN** project `PROJ-001` has `approved_estimate = 3000`
|
||||
- **WHEN** manager sets Jan=1200, Feb=1400, Mar=400
|
||||
- **THEN** the system stores those exact values
|
||||
- **AND** no derived monthly average is applied
|
||||
|
||||
#### Scenario: Edit monthly plan cell inline
|
||||
- **GIVEN** a month-plan grid cell contains 1200
|
||||
- **WHEN** manager edits the cell to 1100 and commits
|
||||
- **THEN** the system persists 1100
|
||||
- **AND** reconciliation status recalculates immediately
|
||||
|
||||
### Requirement: Reconcile month-plan sum against lifecycle approved estimate
|
||||
|
||||
The system SHALL compute reconciliation status per project based on:
|
||||
`sum(non-null monthly planned hours)` vs `approved_estimate`.
|
||||
|
||||
#### Scenario: OVER reconciliation
|
||||
- **GIVEN** `approved_estimate = 3000`
|
||||
- **AND** month-plan sum is 3200
|
||||
- **THEN** status is `OVER`
|
||||
|
||||
#### Scenario: UNDER reconciliation
|
||||
- **GIVEN** `approved_estimate = 3000`
|
||||
- **AND** month-plan sum is 2800
|
||||
- **THEN** status is `UNDER`
|
||||
|
||||
#### Scenario: MATCH reconciliation
|
||||
- **GIVEN** `approved_estimate = 3000`
|
||||
- **AND** month-plan sum is 3000
|
||||
- **THEN** status is `MATCH`
|
||||
|
||||
### Requirement: Preserve blank month semantics
|
||||
|
||||
The planning grid SHALL keep unset months visually blank and semantically distinct from explicit zero.
|
||||
|
||||
#### Scenario: Blank remains blank
|
||||
- **GIVEN** no plan exists for April
|
||||
- **WHEN** manager views planning grid
|
||||
- **THEN** April cell is blank (no `0` shown)
|
||||
|
||||
#### Scenario: Clear cell sets blank semantics
|
||||
- **GIVEN** a month cell has planned value
|
||||
- **WHEN** manager clears the cell and commits
|
||||
- **THEN** the month is stored as blank/unset semantics
|
||||
- **AND** planning UI displays blank
|
||||
|
||||
### Requirement: Allocation variance uses blank plan as zero
|
||||
|
||||
For allocation variance computation only, missing month plan SHALL be treated as planned `0`.
|
||||
|
||||
#### Scenario: Allocate against blank plan month
|
||||
- **GIVEN** no plan is set for selected month
|
||||
- **AND** project allocations total 40h
|
||||
- **WHEN** variance is computed
|
||||
- **THEN** planned value used is 0
|
||||
- **AND** row variance is +40
|
||||
- **AND** allocation operation remains allowed
|
||||
|
||||
### Requirement: Grid-first planning interaction
|
||||
|
||||
Project-month planning SHALL be managed in a grid-first interface.
|
||||
|
||||
#### Scenario: Keyboard-first editing
|
||||
- **WHEN** manager navigates month-plan grid with keyboard
|
||||
- **THEN** inline cell editing and commit are supported
|
||||
- **AND** modal interaction is not required for normal edits
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Monthly budget derivation
|
||||
|
||||
**Original behavior (rejected):** monthly budget derived from `approved_estimate / 12`.
|
||||
|
||||
**Updated behavior:** monthly plan values are explicit manager-entered project-month values; no derivation formula is used for planning behavior.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Resource Allocation - Delta Specification
|
||||
|
||||
This delta documents required updates to existing resource allocation behavior for fidelity with explicit month planning.
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Month execution comparison target
|
||||
|
||||
**Original behavior:** month execution was compared against derived or lifecycle assumptions.
|
||||
|
||||
**Updated behavior:** selected month project allocation is compared against explicit project-month planned hours.
|
||||
|
||||
#### Scenario: Compare row total to month plan
|
||||
- **GIVEN** selected month plan for project is 1200h
|
||||
- **AND** project allocations total 1300h
|
||||
- **THEN** project row variance is +100h
|
||||
- **AND** row status is `OVER`
|
||||
|
||||
#### Scenario: Blank month plan comparison
|
||||
- **GIVEN** selected month has no plan value set
|
||||
- **AND** project allocations total 50h
|
||||
- **THEN** comparison target is 0h
|
||||
- **AND** row status is `OVER`
|
||||
- **AND** allocation remains allowed
|
||||
|
||||
### Requirement: Bulk allocation behavior
|
||||
|
||||
**Original behavior:** all-or-nothing transaction semantics.
|
||||
|
||||
**Updated behavior:** valid items SHALL be saved even if some items fail.
|
||||
|
||||
#### Scenario: Partial bulk success
|
||||
- **WHEN** 10 allocation items are submitted and 2 fail validation
|
||||
- **THEN** 8 valid items are persisted
|
||||
- **AND** failed items return per-index validation errors
|
||||
- **AND** response includes summary created/failed counts
|
||||
|
||||
### Requirement: Untracked execution semantics
|
||||
|
||||
**Original behavior:** untracked support was ambiguous/incomplete.
|
||||
|
||||
**Updated behavior:** `team_member_id = null` is valid and treated as untracked effort.
|
||||
|
||||
#### Scenario: Untracked counted in project, excluded from capacity
|
||||
- **WHEN** untracked allocation exists for selected month
|
||||
- **THEN** project totals include it
|
||||
- **AND** member capacity/utilization computations exclude it
|
||||
@@ -0,0 +1,55 @@
|
||||
# Untracked Allocation Specification
|
||||
|
||||
## Overview
|
||||
|
||||
This capability supports external/unassigned effort by allowing allocations without a team member association.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Support null team member in allocation APIs
|
||||
|
||||
The system SHALL allow allocation records with `team_member_id = null`.
|
||||
|
||||
#### Scenario: Create untracked allocation
|
||||
- **GIVEN** user has allocation create permission
|
||||
- **WHEN** POST /api/allocations with `team_member_id = null`
|
||||
- **THEN** allocation is created successfully
|
||||
|
||||
#### Scenario: Bulk create with mixed tracked/untracked
|
||||
- **GIVEN** a bulk payload contains tracked and untracked entries
|
||||
- **WHEN** POST /api/allocations/bulk is executed
|
||||
- **THEN** untracked entries with valid data are processed successfully
|
||||
|
||||
### Requirement: Include untracked in project totals
|
||||
|
||||
Untracked hours SHALL contribute to project-level and grand totals.
|
||||
|
||||
#### Scenario: Project total includes untracked
|
||||
- **GIVEN** project has tracked 80h and untracked 20h in selected month
|
||||
- **WHEN** project row total is computed
|
||||
- **THEN** row total is 100h
|
||||
|
||||
### Requirement: Exclude untracked from member capacity metrics
|
||||
|
||||
Untracked allocations SHALL NOT contribute to any team member utilization/capacity variance.
|
||||
|
||||
#### Scenario: Member utilization ignores untracked
|
||||
- **GIVEN** selected month has untracked allocations
|
||||
- **WHEN** member column totals and capacity variance are computed
|
||||
- **THEN** untracked rows are excluded from member computations
|
||||
|
||||
### Requirement: Present untracked in execution grid
|
||||
|
||||
The allocation grid SHALL expose untracked as a first-class execution bucket.
|
||||
|
||||
#### Scenario: Untracked column visible
|
||||
- **WHEN** manager opens allocation execution grid
|
||||
- **THEN** untracked column/bucket is visible and editable
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Capacity validation
|
||||
|
||||
**Original behavior:** all allocations were assumed team-member-bound for capacity checks.
|
||||
|
||||
**Updated behavior:** capacity validation is skipped for untracked allocations (`team_member_id = null`).
|
||||
Reference in New Issue
Block a user