Updates rules to match code

Author: aridlehoover

INIT.md

@@ -0,0 +1,18 @@
+Constructor/initializer testing locations
+- spec/domain/projects/project_spec.rb:35 (defaults description to empty string)
+- spec/domain/projects/project_spec.rb:45 (defaults point_of_contact to empty string)
+- spec/domain/projects/project_spec.rb:74 (defaults archived to false)
+- spec/domain/projects/project_spec.rb:98 (defaults current_state to :new)
+- spec/domain/projects/project_spec.rb:104 (invalid when initialized with invalid state)
+- spec/domain/teams/team_spec.rb:34 (defaults description to empty string)
+- spec/domain/teams/team_spec.rb:44 (defaults point_of_contact to empty string)
+- spec/domain/teams/team_spec.rb:59 (defaults archived to false)
+- spec/domain/initiatives/initiative_spec.rb:34 (defaults description to empty string)
+- spec/domain/initiatives/initiative_spec.rb:44 (defaults point_of_contact to empty string)
+- spec/domain/initiatives/initiative_spec.rb:59 (defaults archived to false)
+- spec/domain/initiatives/initiative_spec.rb:69 (defaults current_state to :new)
+- spec/domain/initiatives/initiative_spec.rb:79 (converts string state to symbol)
+- spec/domain/initiatives/initiative_spec.rb:86 (invalid when state is not allowed)
+- spec/presenters/health_presenter_spec.rb:6 (describe #initialize)
+- spec/presenters/confidence_presenter_spec.rb:6 (describe #initialize)
+- spec/presenters/trend_presenter_spec.rb:6 (describe #initialize)

NIL.md

@@ -0,0 +1,31 @@
+Explicit return nil
+- lib/domain/teams/team.rb:43
+- lib/domain/teams/team.rb:98
+- lib/domain/support/health_rollup.rb:43
+- lib/domain/projects/project_health.rb:38
+- lib/domain/projects/project_health.rb:44
+- app/controllers/projects_controller.rb:301
+- app/persistence/health_update_repository.rb:74
+- app/persistence/health_update_repository.rb:77
+- app/persistence/initiative_repository.rb:10
+- app/persistence/team_repository.rb:10
+- app/persistence/project_repository.rb:15
+- app/persistence/project_repository.rb:186
+- app/presenters/initiative_header_presenter.rb:42
+- app/presenters/team_edit_modal_presenter.rb:29
+- app/presenters/initiative_edit_modal_presenter.rb:29
+
+Conditional or ternary returning nil
+- lib/domain/teams/team.rb:112
+- app/controllers/dashboard_controller.rb:200
+- app/controllers/initiatives_controller.rb:197
+- app/controllers/teams_controller.rb:192
+- app/persistence/health_update_repository.rb:37
+- app/persistence/project_repository.rb:180
+- app/persistence/project_repository.rb:189
+- app/persistence/team_repository.rb:178
+- app/presenters/team_header_presenter.rb:31
+- app/presenters/team_header_presenter.rb:32
+- app/presenters/team_header_presenter.rb:33
+- app/presenters/team_header_presenter.rb:35
+- app/presenters/team_section_item_presenter.rb:22

TODO.md

@@ -2,6 +2,7 @@
 
 ## SMALL THINGS
 * [x] Use zen logo on home page
+* [x] Are Archived projects being inluded in health? NO
 * [ ] Sticky header not working
 * [ ] Health update hit text highly recommended
 * [ ] Spacing beneath search dropdown is too much
@@ -14,9 +15,16 @@
 * [ ] Projects section should match all other pages
 * [ ] Improve tab stops everwhere.
 * [ ] State should not include New
-* [ ] Are Archived projects being inluded in health?
+* [ ] Should archived be a state rather than a boolean?
+* [ ] Review opportunities for null objects in NIL.md
+* [ ] Review opportunities to remove specs that test constructors in INIT.md
 
 ## FEATURE IDEAS
+* [ ] Project filters
+    * [ ] All
+    * [ ] What's going well
+    * [ ] What needs leadership attention (at risk / off track / blocked / unowned)
+    * [ ] What needs management attention (stale)
 * [ ] Executive summary
 * [ ] People with contact fields
 * [ ] Personal dashboard / check in
@@ -32,11 +40,6 @@
 * [ ] Critical projects
     * [ ] 2x weight
     * [ ] Requires comment to enable
-* [ ] Project filters
-    * [ ] All
-    * [ ] What's going well
-    * [ ] What needs leadership attention (at risk / off track / blocked / unowned)
-    * [ ] What needs management attention (stale)
 
 ## DUMB IDEAS
 * [ ] Add randomly rotating taglines
@@ -125,4 +128,20 @@ Executive Summary View (one screen)
 
 ## Teams
 * Array to score = direct child teams + average of direct owned projects
-* Score = average of health scores
+* Score = average of health scores
+
+
+# Health & Health Scores
+
+Currently, HealthUpdates store a string. They should record a number. It would save a bunch of conversions.
+
+* HEALTH_SCORES = { on_track: 1, at_risk: 0, off_track: -1 }
+* HEALTH_THRESHOLDS = { on_track: 0.5, off_track: -0.5 }
+
+ProjectHealth
+InitiativeHealth
+TeamHealth
+ - All three use HealthScore
+
+HealthScore
+ - Calculates scores and returns the appropriate characterizations of the scores

rules/domain/initiatives/initiative.md

@@ -1,7 +1,7 @@
 An Initiative represents a strategic effort composed of projects.
 
 Identifiers and attributes
-- `name` is required and globally unique.
+- `name` is required and unique among initiatives.
 - `description` and `point_of_contact` are optional strings defaulting to `''`.
 - `archived` defaults to false and is exposed via `archived?`.
 
@@ -10,9 +10,10 @@ Structure and ordering
 - Initiatives may only relate to top-level (parentless) projects; child projects cannot be related to initiatives.
 
 Health model
-- Uses health rollup scoring (`:on_track => 1`, `:at_risk => 0`, `:off_track => -1`; thresholds >0 `:on_track`, <0 `:off_track`, else `:at_risk`); `:not_available` related project health is ignored.
+- Uses health rollup scoring (`:on_track => 1`, `:at_risk => 0`, `:off_track => -1`; thresholds >0.5 `:on_track`, <=-0.5 `:off_track`, else `:at_risk`); `:not_available` related project health is ignored.
 - Current health is the rollup average of related projects whose `current_state` is `:in_progress` or `:blocked`.
 - Related projects in other states are ignored.
+- Archived related projects are ignored.
 - If no related projects are in a working state, health is `:not_available`.
 
 Validation

rules/domain/initiatives/update_initiative.md

@@ -1,5 +1,5 @@
 Action: UpdateInitiative
 - Purpose: replace an existing Initiative in the InitiativeRepository with a new instance.
-- Inputs: initiative id; initiative attributes (`name`, optional `description`, optional `point_of_contact`, archived flag, loaders as needed).
+- Inputs: initiative id; initiative attributes (`name`, optional `description`, optional `point_of_contact`, archived flag).
 - Failures: initiative not found; new initiative invalid; new initiative name conflicts with an existing Initiative.
 - Success: returns Result.success with the updated Initiative persisted.

rules/domain/projects/create_subordinate_project.md

@@ -2,5 +2,5 @@ Action: CreateSubordinateProject
 - Purpose: create a new Project and append it to a parent Project’s children sorted set (as last).
 - Inputs: parent project id; project attributes (`name`, optional `description`, optional `point_of_contact`).
 - Constraints: the created child is attached to exactly one parent project; ordering is maintained within the parent’s set.
-- Failures: project invalid; project name conflicts with any existing Project (error text: `"team name must be unique"`).
+- Failures: project invalid; project name conflicts with any existing Project (error text: `"project name must be unique"`).
 - Success: returns Result.success with the created Project; persists the Project and parent-child relationship with order at the end of the parent’s set.

rules/domain/projects/project.md

@@ -1,7 +1,7 @@
 A Project is the central unit of work.
 
 Identifiers and attributes
-- `name` is required and globally unique.
+- `name` is required and unique among projects.
 - `description` and `point_of_contact` are optional strings defaulting to `''`.
 - `archived` defaults to false and is exposed via `archived?`.
 
@@ -14,8 +14,8 @@ Structure and ordering
 
 State model
 - Allowed states: `:new, :todo, :in_progress, :blocked, :on_hold, :done`.
-- Only `SetProjectState` mutates state values.
-- Leaf projects store `current_state` directly; any state can transition to any other state.
+- `SetProjectState` mutates state values; `SetInitiativeState` can also cascade state to related projects.
+- Leaf projects store `current_state` directly; leaf projects can be set to any state except `:new`.
 - Parent projects derive `current_state` from their leaf descendants via rollup; stored state is ignored.
 - State rollup priority (highest to lowest): `:blocked, :in_progress, :on_hold, :todo, :new, :done`.
   - If any leaf is `:blocked`, parent state is `:blocked`.
@@ -30,11 +30,11 @@ Health model
 - Health enum: `:not_available, :on_track, :at_risk, :off_track`.
 - Health updates (value objects) hold `project_id, date, health, description?`; loaded lazily.
 - Weekly health updates are a lazily loaded subset for trends.
-- Health scoring for rollups: `:on_track => 1`, `:at_risk => 0`, `:off_track => -1`; averages map back via thresholds (>0 `:on_track`, <0 `:off_track`, else `:at_risk`). Subordinate health of `:not_available` is ignored.
+- Health scoring for rollups: `:on_track => 1`, `:at_risk => 0`, `:off_track => -1`; averages map back via thresholds (>0.5 `:on_track`, <=-0.5 `:off_track`, else `:at_risk`). Subordinate health of `:not_available` is ignored; archived and non-working-state children are excluded.
 - Current health calculation:
   - If subordinate projects exist, health is the rollup average of subordinate current health. Subordinates with `:not_available` health are ignored. If all subordinates have `:not_available` health, health is `:not_available`.
   - If no subordinate projects (leaf), use health updates: `:not_available` when none exist; otherwise the health of the latest update by date.
-- Health trend: the last 6 weekly updates plus current health; empty when no updates exist.
+  - Health trend: the last 6 weekly updates plus current health; when no updates exist, returns a single current entry with `:not_available`.
 
 Validation
 - `valid?` requires present `name` and allowed state; exposes `errors` explaining failures.

rules/domain/projects/update_project.md

@@ -1,5 +1,5 @@
 Action: UpdateProject
 - Purpose: replace an existing Project in the ProjectRepository with a new instance.
-- Inputs: project id; project attributes (`name`, optional `description`, optional `point_of_contact`, optional `current_state`, optional archived flag, loaders as needed).
+- Inputs: project id; project attributes (`name`, optional `description`, optional `point_of_contact`, optional archived flag).
 - Failures: project not found; new project invalid; new project name conflicts with an existing Project.
 - Success: returns Result.success with the updated Project persisted.

rules/domain/teams/team.md

@@ -1,7 +1,7 @@
 A Team represents a group of people working together.
 
 Identifiers and attributes
-- `name` is required and globally unique.
+- `name` is required and unique among teams.
 - `description` and `point_of_contact` are optional strings defaulting to `''`.
 - `archived` defaults to false and is exposed via `archived?`.