Files

Santhosh Janardhanan b7bbfb45c0 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.

2026-03-08 18:22:27 -04:00

2.4 KiB

Raw Blame History

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.

2.4 KiB Raw Blame History