Almirah 0.4.2 → 0.4.3

data/lib/almirah/dom/doc_section.rb

@@ -7,7 +7,7 @@ class DocSection
     @parent_section = nil
   end
 
-  def to_html # rubocop:disable Metrics/MethodLength
+  def to_html
     s = ''
     s += "\t<li onclick=\"nav_toggle_expand_list(this, event)\">" \
       '<span class="fa-li"><i class="fa fa-minus-square-o"> </i></span>'

data/lib/almirah/navigation_pane.rb

@@ -1,17 +1,13 @@
-
 class NavigationPane
+  attr_accessor :specifications
 
-    attr_accessor :specifications
+  def initialize(specification)
+    @doc = specification
+  end
 
-    def initialize(specification)
-        @doc = specification
-    end
+  def to_html
+    return @doc.dom.section_tree_to_html if @doc.dom
 
-    def to_html
-        if  @doc.dom
-            return @doc.dom.section_tree_to_html()
-        else
-            return ''
-        end
-    end
-end
+    ''
+  end
+end

data/lib/almirah/project/critical_chain.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative 'work_item_scheduler'
+
+# Resource-levelled scheduler variant for the critical chain (ADR-195): each
+# row's duration is its focused estimate, and rows are prioritised by the longest
+# downstream chain of focused durations (ties: record sequence, then step). The
+# forward pass, resource levelling, binding-predecessor tracking, and chain
+# tracing are all inherited from WorkItemScheduler.
+class ChainScheduler < WorkItemScheduler
+  def duration_for(work_item)
+    work_item.focused_estimate
+  end
+
+  private
+
+  def priority_key(work_item, memo)
+    [-downstream_length(work_item, memo, []), work_item.record_sequence, work_item.step]
+  end
+
+  # The longest path of focused durations from this row through its in-scope
+  # successors to a sink. Memoised and cycle-guarded.
+  def downstream_length(work_item, memo, stack)
+    return memo[work_item] if memo.key?(work_item)
+    return duration_for(work_item) if stack.include?(work_item)
+
+    stack.push(work_item)
+    tail = scoped_successors(work_item).map { |s| downstream_length(s, memo, stack) }.max || 0
+    stack.pop
+    memo[work_item] = duration_for(work_item) + tail
+  end
+end
+
+# The Gantt's scheduler (ADR-201/195): real focused-estimate durations like the
+# critical-chain scheduler, but rounded up to whole day columns with a one-day
+# minimum so an unestimated row (focused 0) still shows a visible bar. The chain
+# and buffer keep their exact-duration math in ChainScheduler / CriticalChain.
+class GanttScheduler < ChainScheduler
+  def duration_for(work_item)
+    [work_item.focused_estimate.ceil, 1].max
+  end
+end
+
+# The critical chain and project buffer for one decision group's Scope rows
+# (ADR-195). This object serves two distinct jobs that want opposite treatment of
+# completed work, so it keeps two views of the same Scope rows:
+#
+# - the *scheduling* chain (`chain` / `buffer` / `projected_duration`) excludes
+#   Done rows as finished work — you do not re-schedule what is already done — and
+#   reports the duration of the work still remaining;
+# - the *baseline* chain (`baseline_chain` / `baseline_buffer`) keeps every row,
+#   Done included, as the plan was originally sized. Buffer-consumption accounting
+#   (the fever chart, ADR-196) reads this view so that a chain row which overran
+#   and then completed keeps consuming buffer instead of vanishing the moment it
+#   is marked Done, and so the consumption denominator stays a stable plan-time
+#   baseline rather than shrinking as rows finish (issue-207).
+#
+# A predecessor outside the given set (a row in another group) drops out and is
+# treated as an already-available input. The buffer aggregates the safety
+# (safe - focused, clamped at 0) along a chain and cuts it by buffer_ratio,
+# rounded up.
+class CriticalChain
+  def initialize(work_items, buffer_ratio: 0.5)
+    @all_items = work_items
+    @items = work_items.reject(&:done?)
+    @buffer_ratio = buffer_ratio
+    @scheduler = ChainScheduler.new(@items)
+    @baseline_scheduler = ChainScheduler.new(@all_items)
+  end
+
+  # The remaining chain (Done rows excluded) in start order — drives the chain
+  # table and the projected completion of the work still to do.
+  def chain
+    @scheduler.critical_chain
+  end
+
+  # The chain as originally planned, completed rows included (issue-207). Buffer
+  # consumption is accounted against this set so completed overruns stay visible.
+  def baseline_chain
+    @baseline_scheduler.critical_chain
+  end
+
+  # Chain length in working days (the latest finish).
+  def length
+    @scheduler.makespan
+  end
+
+  # ceil(buffer_ratio * Σ_chain max(safe - focused, 0)) over the remaining chain.
+  def buffer
+    buffer_for(chain)
+  end
+
+  # The plan-time buffer over the full baseline chain — the stable denominator for
+  # buffer-consumption %, unaffected by rows completing (issue-207).
+  def baseline_buffer
+    buffer_for(baseline_chain)
+  end
+
+  def projected_duration
+    length + buffer
+  end
+
+  # False when no row carries a positive focused estimate, so the overview marks
+  # the group "unestimated" rather than reporting a misleadingly short plan.
+  # Reads the baseline so a fully-completed group still reports as estimated and
+  # keeps its (100%-complete) fever chart instead of collapsing to "not sized".
+  def estimated?
+    @all_items.any? { |wi| wi.focused_estimate.positive? }
+  end
+
+  private
+
+  def buffer_for(rows)
+    safety = rows.sum { |wi| [wi.safe_estimate - wi.focused_estimate, 0].max }
+    (@buffer_ratio * safety).ceil
+  end
+end

data/lib/almirah/project/doc_linker.rb

@@ -17,7 +17,7 @@ class DocLinker
     result
   end
 
-  def self.link_protocol_to_spec(protocol, specification) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+  def self.link_protocol_to_spec(protocol, specification)
     top_document = specification
     bottom_document = protocol
 
@@ -44,7 +44,7 @@ class DocLinker
     end
   end
 
-  def self.link_decision_to_spec(decision, specification) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+  def self.link_decision_to_spec(decision, specification)
     top_document = specification
     bottom_document = decision
 
@@ -68,7 +68,7 @@ class DocLinker
     end
   end
 
-  def self.link_source_file_to_spec(source_file, specification) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+  def self.link_source_file_to_spec(source_file, specification)
     top_document = specification
     bottom_document = source_file
 
@@ -92,7 +92,7 @@ class DocLinker
     end
   end
 
-  def self.link_two_specifications(doc_a, doc_b) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+  def self.link_two_specifications(doc_a, doc_b)
     if doc_b.up_link_docs.key?(doc_a.id.to_s)
       top_document = doc_a
       bottom_document = doc_b

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,9 @@ 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, :work_items, :link_registry
 
-  def initialize # rubocop:disable Metrics/MethodLength
+  def initialize
     @specifications = []
     @protocols = []
     @traceability_matrices = []
@@ -13,6 +13,12 @@ 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 = []
+    # 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,166 @@
+# 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.
+#
+# 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 later
+  # of its dependency finish and its owner's next free day; the owner's cursor
+  # then advances past it, serialising the lane (resource levelling).
+  def schedule
+    @starts = {}
+    @ends = {}
+    @binding = {}
+    @owner_last = {}
+    return if @items.empty?
+
+    owner_free = Hash.new(1)
+    priority_order.each { |wi| place(wi, owner_free) }
+  end
+
+  # Assigns one work item its start day at the later of its dependency finish and
+  # its owner's next free day, records the predecessor that bound that start, then
+  # advances that owner's free cursor past it.
+  def place(work_item, owner_free)
+    owner = work_item.owner
+    preds = scoped_predecessors(work_item)
+    start = start_day(preds, owner_free[owner])
+    @starts[work_item] = start
+    @ends[work_item] = start + duration_for(work_item)
+    @binding[work_item] = binding_predecessor(work_item, preds, start, owner)
+    advance_owner(owner, work_item, owner_free)
+  end
+
+  # The earliest day a row may start: the later of its in-scope predecessors'
+  # latest finish and its owner's next free day.
+  def start_day(preds, owner_free_day)
+    dep_finish = preds.map { |p| @ends[p] || 1 }.max || 1
+    [dep_finish, owner_free_day].max
+  end
+
+  # Advance an owner's free cursor past the just-placed row, and remember it as
+  # that owner's most recent row (the resource hand-off candidate). A blank owner
+  # holds no resource, so it never serialises.
+  def advance_owner(owner, work_item, owner_free)
+    return if owner.empty?
+
+    owner_free[owner] = @ends[work_item]
+    @owner_last[owner] = work_item
+  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(_work_item, preds, start, owner)
+    candidates = preds.select { |p| @ends[p] == start }
+    resource_pred = @owner_last[owner]
+    candidates << resource_pred if resource_pred && @ends[resource_pred] == start
+    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