Almirah 0.4.2 → 0.4.4

data/lib/almirah/project/fever_chart.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# The buffer-consumption fever chart for one decision group (ADR-196): given the
+# group's CriticalChain plan, the effort logged on its records, and the working-
+# hours-per-day conversion, it produces the (completion%, consumption%) point and
+# the historical trail the Critical Chain page plots.
+#
+# It tracks only chain rows with a positive focused estimate (a zero-estimate row
+# carries no schedule weight). Per-row actual effort is read from the owning
+# Decision's append-only # Effort log via row_actual_hours_on, converted to days;
+# the chart never consults the record lifecycle status.
+#
+# It reads the plan's *baseline* chain and buffer (completed rows included,
+# issue-207), not the remaining-work chain: a chain row that overran and then was
+# marked Done has consumed real buffer that must stay accounted, and the
+# consumption denominator must not shrink as rows finish. The live point still
+# credits a Done row in full via its per-row Status (ADR-196); historical trail
+# points reconstruct even a completed row's progress and overrun from its dated
+# # Effort log, which a per-row Status (no dated history) could not.
+class FeverChart
+  # record_lookup maps an upcased record id (e.g. "ADR-196") to its Decision.
+  def initialize(plan, record_lookup, hours_per_day: 8)
+    @rows = plan.baseline_chain.select { |wi| wi.focused_estimate.positive? }
+    @buffer = plan.baseline_buffer
+    @record_lookup = record_lookup
+    @hours_per_day = hours_per_day.to_f
+  end
+
+  # True when there is anything to plot (at least one positive-estimate chain row).
+  def plottable?
+    @rows.any?
+  end
+
+  # The live fever point [completion%, consumption%] as of `date`: a Done row
+  # credits full completion regardless of logged effort, matching the bounded
+  # per-row Status (ADR-193); other rows credit logged effort only.
+  def live_point(date)
+    [completion(date, live: true), consumption(date)]
+  end
+
+  # A historical point [completion%, consumption%] as of `date`, from logged
+  # effort only (the per-row Status has no dated history to replay).
+  def point_on(date)
+    [completion(date, live: false), consumption(date)]
+  end
+
+  # One historical point per date (recent Fridays), in the given order.
+  def trail(dates)
+    dates.map { |d| point_on(d) }
+  end
+
+  # The baseline buffer days these overruns have consumed as of `date` -- the
+  # numerator behind the consumption percentage (its denominator is the baseline
+  # buffer). Lets the Critical Chain page report "X of Y baseline days".
+  def consumed_days(date)
+    @rows.sum { |wi| [actual_days(wi, date) - wi.focused_estimate, 0].max }
+  end
+
+  private
+
+  def completion(date, live:)
+    total = @rows.sum(&:focused_estimate)
+    return 0.0 if total.zero?
+
+    credited = @rows.sum { |wi| credit(wi, date, live: live) * wi.focused_estimate }
+    100.0 * credited / total
+  end
+
+  def credit(work_item, date, live:)
+    return 1.0 if live && work_item.done?
+
+    clamp01(actual_days(work_item, date) / work_item.focused_estimate)
+  end
+
+  # Percentage of the project buffer consumed: the aggregate amount by which chain
+  # rows overran their focused estimate, over the buffer. May exceed 100. A group
+  # whose chain carries no safety (buffer 0) has nothing to consume, so 0.
+  def consumption(date)
+    return 0.0 if @buffer.zero?
+
+    100.0 * consumed_days(date) / @buffer
+  end
+
+  def actual_days(work_item, date)
+    record = @record_lookup[work_item.record_id.to_s.upcase]
+    return 0.0 if record.nil? || @hours_per_day.zero?
+
+    record.row_actual_hours_on(work_item.activity, date) / @hours_per_day
+  end
+
+  def clamp01(value)
+    value.clamp(0.0, 1.0)
+  end
+end

data/lib/almirah/project/project_data.rb

@@ -3,9 +3,10 @@ require_relative '../link_registry'
 class ProjectData
   attr_reader :specifications, :protocols, :traceability_matrices, :coverage_matrices, :source_files,
               :specifications_dictionary, :covered_specifications_dictionary, :implemented_specifications_dictionary,
-              :implementation_matrices, :decisions, :link_registry
+              :implementation_matrices, :decisions, :decision_groups, :risk_records, :risk_registries,
+              :risk_registry_prefaces, :work_items, :link_registry
 
-  def initialize # rubocop:disable Metrics/MethodLength
+  def initialize
     @specifications = []
     @protocols = []
     @traceability_matrices = []
@@ -13,6 +14,20 @@ class ProjectData
     @source_files = []
     @implementation_matrices = []
     @decisions = []
+    # Insertion-ordered list of single-key hashes { "<first-level folder>" => [Decision, ...] },
+    # grouping decision records by the planning folder they live in (see ADR-197).
+    @decision_groups = []
+    @risk_records = []
+    # Insertion-ordered list of single-key hashes { "<first-level risks/ folder>" => [RiskRecord, ...] },
+    # grouping risk records by the registry they live in (see ADR-215).
+    @risk_registries = []
+    # Registry prefaces (ADR-216): each registry's parsed overview.md, keyed by
+    # the registry (first-level risks/ folder) name. A registry without an
+    # overview.md has no entry; its page simply starts at the register table.
+    @risk_registry_prefaces = {}
+    # Every Scope-row WorkItem across all decision records, keyed by its canonical
+    # "<record>.<step>.<activity>" id (see ADR-194), populated by link_work_items.
+    @work_items = {}
 
     @specifications_dictionary = {}
     @covered_specifications_dictionary = {}

data/lib/almirah/project/work_item_scheduler.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'set'
+
+# Lays the WorkItem network (ADR-194) on an abstract day axis for the overview
+# swimlane Gantt (ADR-198). It performs a deterministic forward pass over the
+# dependency edges and then levels each owner's lane so two work items of the
+# same owner never overlap. Levelling backfills: a row may be slotted into an
+# idle gap left between rows placed earlier, so a low-priority short row does
+# not queue behind the whole lane when a gap already fits it.
+#
+# Durations are a constant placeholder (3 days) while no per-row estimates
+# exist; `duration_for` is the single hook ADR-195 overrides to feed real
+# estimates without changing the scheduling logic.
+#
+# Days are 1-based. A work item starting on day `s` with duration `d` occupies
+# the inclusive day span `s .. s + d - 1`; its *finish* (the next free day,
+# returned in the ends map) is `s + d`, the earliest a successor or the same
+# owner's next item may start.
+class WorkItemScheduler
+  # Placeholder duration for every work item until ADR-195 supplies estimates.
+  DEFAULT_DURATION = 3
+
+  def initialize(work_items, duration: DEFAULT_DURATION)
+    @items = work_items
+    @duration = duration
+    @item_set = work_items.to_set
+  end
+
+  # { work_item => start_day }, day index 1-based. Empty when there are no items.
+  def start_days
+    schedule unless @starts
+    @starts
+  end
+
+  # The number of day columns the chart needs: the latest finish minus one
+  # (finishes are the exclusive next-free day). Zero when there are no items.
+  def day_count
+    schedule unless @ends
+    @ends.empty? ? 0 : (@ends.values.max - 1)
+  end
+
+  # The schedule length in working days (the latest finish, day 1 being the start).
+  def makespan
+    day_count
+  end
+
+  # The critical chain: the row with the latest finish, traced back through its
+  # binding predecessors (the dependency and resource hand-offs that set each
+  # row's start), returned in start order. Empty when nothing is scheduled.
+  def critical_chain
+    schedule unless @starts
+    return [] if @ends.empty?
+
+    max_end = @ends.values.max
+    node = @items.select { |wi| @ends[wi] == max_end }.min_by { |wi| [wi.record_id, wi.step] }
+    chain = []
+    while node
+      chain.unshift(node)
+      node = @binding[node]
+    end
+    chain
+  end
+
+  def duration_for(_work_item)
+    @duration
+  end
+
+  private
+
+  # Greedy list-scheduler. Items are processed in a deterministic priority order
+  # (resource-free earliest start, then activity rank, record id, step) so that
+  # every item's predecessors are placed before it. Each item starts at the
+  # earliest day at or after its dependency finish where its owner's lane has an
+  # idle gap wide enough for it (resource levelling with backfill).
+  def schedule
+    @starts = {}
+    @ends = {}
+    @binding = {}
+    @owner_rows = Hash.new { |hash, owner| hash[owner] = [] }
+    return if @items.empty?
+
+    priority_order.each { |wi| place(wi) }
+  end
+
+  # Assigns one work item its start day, records the predecessor that bound that
+  # start, then marks the span as occupied in its owner's lane.
+  def place(work_item)
+    preds = scoped_predecessors(work_item)
+    dep_finish = preds.map { |p| @ends[p] || 1 }.max || 1
+    start, lane_pred = earliest_fit(work_item.owner, dep_finish, duration_for(work_item))
+    @starts[work_item] = start
+    @ends[work_item] = start + duration_for(work_item)
+    @binding[work_item] = binding_predecessor(preds, start, lane_pred)
+    @owner_rows[work_item.owner] << work_item unless work_item.owner.empty?
+  end
+
+  # The earliest start at or after `from` where the owner's lane stays clear for
+  # `duration` days, plus the lane row whose finish that start had to wait behind
+  # (nil when the row starts at `from` itself). A blank owner holds no resource,
+  # so it never serialises.
+  def earliest_fit(owner, from, duration)
+    return [from, nil] if owner.empty?
+
+    start = from
+    lane_pred = nil
+    @owner_rows[owner].sort_by { |row| @starts[row] }.each do |row|
+      break if start + duration <= @starts[row]
+      next if @ends[row] <= start
+
+      start = @ends[row]
+      lane_pred = row
+    end
+    [start, lane_pred]
+  end
+
+  # The already-placed predecessor whose finish coincides with this row's start --
+  # the dependency or same-owner hand-off the critical chain is traced back
+  # through. nil when the row starts at the origin with no such predecessor.
+  def binding_predecessor(preds, start, lane_pred)
+    candidates = preds.select { |p| @ends[p] == start }
+    candidates << lane_pred if lane_pred
+    candidates.min_by { |c| [c.record_id, c.step] }
+  end
+
+  def priority_order
+    memo = {}
+    @items.sort_by { |wi| priority_key(wi, memo) }
+  end
+
+  # The deterministic scheduling priority for a row. Overridden by the critical-
+  # chain scheduler (ADR-195) to prioritise the longest downstream duration.
+  def priority_key(work_item, memo)
+    [dependency_start(work_item, memo, []), work_item.activity_rank, work_item.record_id, work_item.step]
+  end
+
+  # The earliest day this item could start ignoring resource contention: 1 when
+  # it has no predecessors, else one past the latest predecessor finish. Memoised
+  # and cycle-guarded — a back-edge (which the DAG-by-construction network should
+  # never have) is treated as start 1 so scheduling still completes.
+  def dependency_start(work_item, memo, stack)
+    return memo[work_item] if memo.key?(work_item)
+    return 1 if stack.include?(work_item)
+
+    preds = scoped_predecessors(work_item)
+    return memo[work_item] = 1 if preds.empty?
+
+    stack.push(work_item)
+    earliest = preds.map { |p| dependency_start(p, memo, stack) + duration_for(p) }.max
+    stack.pop
+    memo[work_item] = earliest
+  end
+
+  # Predecessors inside this scheduler's own item set. A predecessor scheduled in
+  # another scope (e.g. a different decision group, ADR-201) is treated as an
+  # already-available external input: it is dropped here and imposes no finish
+  # constraint, so the dependent simply starts at day 1 with respect to it.
+  def scoped_predecessors(work_item)
+    work_item.predecessor_items.select { |p| @item_set.include?(p) }
+  end
+
+  # Successors inside this scheduler's own item set (the mirror of
+  # scoped_predecessors), used by the critical-chain priority.
+  def scoped_successors(work_item)
+    work_item.successor_items.select { |s| @item_set.include?(s) }
+  end
+end

data/lib/almirah/project/working_calendar.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'set'
+
+# Projects the working-day planning axis (ADR-198 / ADR-195) onto real calendar
+# dates (ADR-205). Working day 1 is the first working date on or after the anchor;
+# Saturdays, Sundays, and any configured holiday are non-working — skipped when
+# counting working days, but still occupying calendar columns. This is a pure
+# projection: it never changes the schedule, the chain, or the buffer.
+class WorkingCalendar
+  SATURDAY = 6
+  SUNDAY = 0
+  FRIDAY = 5
+
+  def initialize(anchor: Date.today, holidays: [])
+    @holidays = holidays.to_set
+    @start = first_working_on_or_after(anchor)
+  end
+
+  # The calendar date of the n-th working day (1-based) counted from the anchor.
+  def date_for(working_day)
+    return @start if working_day <= 1
+
+    date = @start
+    remaining = working_day - 1
+    while remaining.positive?
+      date += 1
+      remaining -= 1 if working?(date)
+    end
+    date
+  end
+
+  # Every calendar date from working day 1 through the working_day_count-th working
+  # day inclusive, including the non-working dates in between. Empty for a count
+  # below 1.
+  def columns(working_day_count)
+    return [] if working_day_count < 1
+
+    (@start..date_for(working_day_count)).to_a
+  end
+
+  # The 0-based calendar column index of the n-th working day within columns.
+  def column_index(working_day)
+    (date_for(working_day) - @start).to_i
+  end
+
+  # The compact business-day axis (ADR-206): weekday dates from working day 1
+  # through the working_day_count-th working day, excluding Saturdays and Sundays
+  # but including weekday holidays. Empty for a count below 1.
+  def business_columns(working_day_count)
+    return [] if working_day_count < 1
+
+    (@start..date_for(working_day_count)).reject { |date| weekend?(date) }
+  end
+
+  # The 0-based business-column index of the n-th working day: the count of
+  # weekdays (holidays included, weekends excluded) from the anchor through it.
+  def business_index(working_day)
+    (@start..date_for(working_day)).count { |date| !weekend?(date) } - 1
+  end
+
+  # The first `count` business-day (weekday) dates from the anchor, holidays
+  # included and weekends excluded — the calendar labels for an axis of `count`
+  # columns, even when it runs past the schedule to cover authored actuals
+  # (ADR-213). Empty for a count below 1.
+  def business_axis(count)
+    return [] if count < 1
+
+    dates = []
+    date = @start
+    while dates.length < count
+      dates << date unless weekend?(date)
+      date += 1
+    end
+    dates
+  end
+
+  # The 0-based business-column index of a real calendar date relative to the
+  # anchor (ADR-213): the count of weekdays from the anchor through the date, minus
+  # one. A weekend date snaps to the preceding weekday's column; a date on or
+  # before the anchor clamps to column 0. Used to place authored committed/logged
+  # dates on the same business-day axis as the schedule.
+  def business_column_for(date)
+    return 0 if date <= @start
+
+    (@start..date).count { |d| !weekend?(d) } - 1
+  end
+
+  def friday?(date)
+    date.wday == FRIDAY
+  end
+
+  def working?(date)
+    !non_working?(date)
+  end
+
+  def non_working?(date)
+    weekend?(date) || @holidays.include?(date)
+  end
+
+  def weekend?(date)
+    [SATURDAY, SUNDAY].include?(date.wday)
+  end
+
+  private
+
+  def first_working_on_or_after(date)
+    date += 1 while non_working?(date)
+    date
+  end
+end