Almirah 0.4.3 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46e67646a16db801d9dbe0cd2c2873a38e6e35068c5cde855179b9f5beb00089
-  data.tar.gz: c4953874698c949e6711ebdfa0c84dc0b56d6291674a7127d6ccfbb31802cea4
+  metadata.gz: 7b53b0b8a1c024c618e1fff5aac5288312b51b2a06f228527f06183b31f114ac
+  data.tar.gz: 41959a8eaba117737d913afd63bda6947301e3a5a84aac96b94030f43f6a4564
 SHA512:
-  metadata.gz: 1401a30fbde34dd6c21b77685e3e2506753e7b302d528189e5d3d129eff6f9a15dd169f756be53ea1467dc5805fe36d0ce0678d2a446a866b18e95c66e70de64
-  data.tar.gz: 1db3dd4230d6b77154758bdbad3802fb121ba23c41a3ee33aeb8ba70ac0be4a7ac0d8e14ea05667869d2625fcc638ca2d900a47270f22ff9bac1077c932173ba
+  metadata.gz: 66edfea3c57bb86b6cc5e63de0b63579ec756a12b2704db2c86d2956124e7a9a89fd6e1db86f5481c18840bb4378acbb11d1a5db250d14ccfc7a699c7e0f614e
+  data.tar.gz: ddbd78d3135822cf967a6fac7c2ae87986dbf79aa537b403dfc15c41ffbc36c7594c9460cb086b067d70b7492aee4f0bc81c48b40b07caf02ea70b22fffd915b

data/lib/almirah/doc_fabric.rb

@@ -6,6 +6,9 @@ require_relative 'doc_types/coverage'
 require_relative 'doc_types/implementation'
 require_relative 'doc_types/traceability'
 require_relative 'doc_types/decision'
+require_relative 'doc_types/risk_record'
+require_relative 'doc_types/risk_registry_page'
+require_relative 'doc_types/risks_overview'
 require_relative 'doc_types/decisions_overview'
 require_relative 'doc_types/critical_chain_page'
 require_relative 'doc_parser'
@@ -73,6 +76,21 @@ class DocFabric
     doc
   end
 
+  def self.create_risk_record(path)
+    doc = RiskRecord.new path
+    DocFabric.parse_document doc
+    doc.extract_current_status
+    doc
+  end
+
+  def self.create_risk_registry_page(registry, records, preface, columns, rpn_groups = [])
+    RiskRegistryPage.new registry, records, preface, columns, rpn_groups
+  end
+
+  def self.create_risks_overview(registries, configuration, prefaces = {})
+    RisksOverview.new registries, configuration, prefaces
+  end
+
   def self.create_decisions_overview(project)
     DecisionsOverview.new project
   end

data/lib/almirah/doc_items/controlled_paragraph.rb

@@ -114,7 +114,7 @@ class ControlledParagraph < Paragraph
       if @decision_record_links.length == 1
         dr_doc = @decision_record_links[0].parent_doc
         s += "\t\t<td class=\"item_id\">\
-            <a href=\"./../../decisions/#{dr_doc.html_rel_path}\" \
+            <a href=\"./../../#{dr_doc.output_rel_path}\" \
             class=\"external\" title=\"Decision Record\">#{dr_doc.id.upcase}</a></td>\n"
       else
         s += "\t\t<td class=\"item_id\">"
@@ -125,7 +125,7 @@ class ControlledParagraph < Paragraph
         s += "<div id=\"DRS_#{@id}\" style=\"display: none;\">"
         @decision_record_links.each do |lnk|
           dr_doc = lnk.parent_doc
-          s += "\t\t\t<a href=\"./../../decisions/#{dr_doc.html_rel_path}\" \
+          s += "\t\t\t<a href=\"./../../#{dr_doc.output_rel_path}\" \
             class=\"external\" title=\"Referenced in\">#{dr_doc.id.upcase}</a>\n<br>"
         end
         s += '</div>'

data/lib/almirah/doc_parser.rb

@@ -250,13 +250,14 @@ class DocParser
             if temp_md_table
               if temp_md_table.is_separator_detected # if there is a separator
                 # A Decision Record's Scope table is parsed into a purpose-built
-                # ScopeTable (ADR-194); a Protocol, or a Decision inside an
-                # "Affected Documents" section, into a ControlledTable.
+                # ScopeTable (ADR-194); a Protocol, or a Decision or RiskRecord
+                # inside an "Affected Documents" section, into a ControlledTable
+                # (ADR-218 extends the Decision path to risk records).
                 if doc.instance_of?(Decision) && in_section?(doc, 'Scope') &&
                    temp_md_table.instance_of?(MarkdownTable)
                   temp_md_table = ScopeTable.new(doc, temp_md_table)
                 elsif doc.instance_of?(Protocol) ||
-                      (doc.instance_of?(Decision) && in_section?(doc, 'Affected Documents'))
+                      (doc.is_a?(Decision) && in_section?(doc, 'Affected Documents'))
                   # check if it is a controlled table
                   tmp = /(.*)\s+>\[(\S*)\]/.match(row)
                   if tmp && (temp_md_table.instance_of? MarkdownTable)

data/lib/almirah/doc_types/base_document.rb

@@ -6,7 +6,7 @@ class BaseDocument
   attr_accessor :title, :id, :dom, :headings, :output_rel_path
 
   class << self
-    attr_accessor :show_decisions_link
+    attr_accessor :show_decisions_link, :show_risks_link
   end
 
   def initialize
@@ -37,7 +37,9 @@ class BaseDocument
                           'overview.html'
                         elsif instance_of? CriticalChainPage
                           'critical-chain.html'
-                        elsif instance_of? Decision
+                        elsif instance_of?(RiskRegistryPage) || instance_of?(RisksOverview)
+                          'overview.html'
+                        elsif is_a? Decision # RiskRecord included
                           "#{@id}.html"
                         else
                           "#{@id}/#{@id}.html"
@@ -72,6 +74,7 @@ class BaseDocument
           file.puts decisions_link(rel_to('decisions/overview.html'))
           file.puts critical_chain_link(rel_to('decisions/critical-chain.html'))
         end
+        file.puts risks_link(rel_to('risks/overview.html')) if BaseDocument.show_risks_link
       elsif s.include?('{{GEM_VERSION}}')
         file.puts "(#{Gem.loaded_specs['Almirah'].version.version})"
       else
@@ -91,6 +94,11 @@ class BaseDocument
     %(<a id="critical_chain_menu_item" href="#{href}">#{icon}&nbsp;Critical Chain</a>)
   end
 
+  def risks_link(href)
+    icon = '<span><i class="fa fa-exclamation-triangle" aria-hidden="true"></i></span>'
+    %(<a id="risks_menu_item" href="#{href}">#{icon}&nbsp;Risks</a>)
+  end
+
   def index_link(href)
     icon = '<span><i class="fa fa-info" aria-hidden="true"></i></span>'
     %(<a id="index_menu_item" href="#{href}">#{icon}&nbsp;Index</a>)

data/lib/almirah/doc_types/risk_record.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'decision'
+require_relative '../doc_items/controlled_table'
+
+# A risk record (ADR-215): one Markdown file per risk, collected from the
+# first-level subfolders of the project's risks/ folder, each subfolder being
+# a risk registry. The record format is the decision-record format — filename
+# letters-digits id, frontmatter title, Status table with a "*" current-state
+# marker — so the type reuses Decision wholesale.
+class RiskRecord < Decision
+  # The first-level risks/ subfolder the record was collected from.
+  attr_accessor :registry
+
+  def to_console
+    puts "\e[36mRisk Record: #{@id}\e[0m"
+  end
+
+  # The rendered HTML of the record section whose heading text equals
+  # `section_name` (ADR-216). Empty when there is no such section — the
+  # register renders it as an empty cell.
+  def section_html(section_name)
+    section_items(section_name).map(&:to_html).join
+  end
+
+  # The numeric value of the named section (ADR-217): its items' plain text
+  # parsed as a Float. nil when the section is missing, empty, or not numeric —
+  # the RPN cell renders blank rather than computing a broken record as safe.
+  def section_numeric(section_name)
+    texts = section_items(section_name).filter_map { |i| i.text if i.respond_to?(:text) }
+    Float(texts.join(' ').strip, exception: false)
+  end
+
+  # The record's value for an RPN group (ADR-217): the product of its numeric
+  # input sections. nil when any input is missing or not numeric — such a
+  # record renders a blank cell and is ignored by the summary aggregates.
+  def rpn_value(group)
+    factors = group[:inputs].map { |input| section_numeric(input) }
+    return nil if factors.any?(&:nil?)
+
+    factors.reduce(:*)
+  end
+
+  # The distinct controlled-paragraph IDs the record's Affected Documents
+  # Req-ID column links to (ADR-218), in the section's row order — the
+  # IDs-only content of the register cell. Empty when the record carries no
+  # Affected Documents section or its rows link nothing.
+  def affected_document_ids
+    table = section_items('Affected Documents').find { |i| i.is_a?(ControlledTable) }
+    return [] if table.nil?
+
+    table.rows.flat_map { |row| row.up_link_ids || [] }.uniq
+  end
+
+  private
+
+  # The items between the heading whose text equals `section_name` and the
+  # next heading of the same or a higher level; empty when no heading matches.
+  def section_items(section_name)
+    in_section = false
+    section_level = nil
+    collected = []
+    @items.each do |item|
+      if item.is_a?(Heading) && !in_section
+        next unless item.text.strip == section_name
+
+        in_section = true
+        section_level = item.level
+      elsif in_section
+        break if item.is_a?(Heading) && item.level <= section_level
+
+        collected.append item
+      end
+    end
+    collected
+  end
+end

data/lib/almirah/doc_types/risk_registry_page.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative 'base_document'
+require_relative 'rpn_rendering'
+require_relative '../doc_items/heading'
+
+# The registry page (ADR-216): build/risks/<registry>/overview.html holding
+# the rendered registry preface (overview.md), when present, followed by the
+# register table — one row per risk record with the implicit linked-ID and
+# Title columns first, then the configured columns filled from each record's
+# section matched by heading text. The Status column is reserved: it is filled
+# from the record's current lifecycle status, never from a section.
+class RiskRegistryPage < BaseDocument
+  include RpnRendering
+
+  STATUS_COLUMN = 'Status'
+  # The column rendered as bare linked IDs from the record's Affected
+  # Documents section (ADR-218), never as the section's prose.
+  AFFECTED_DOCUMENTS_COLUMN = 'Affected Documents'
+
+  attr_accessor :registry, :records, :preface, :columns, :rpn_groups
+
+  # `columns` is the configured per-registry list (ADR-216); nil means the
+  # registry is not configured and gets the implicit columns plus Status only.
+  # `rpn_groups` (ADR-217) appends one computed "<Name> RPN" column per group
+  # after the configured columns; empty appends nothing.
+  def initialize(registry, records, preface, columns, rpn_groups = [])
+    super()
+    @registry = registry
+    @records = records
+    @preface = preface
+    @columns = columns.nil? ? [STATUS_COLUMN] : columns
+    @rpn_groups = rpn_groups
+    @id = 'overview'
+    @title = preface_title || "Risk Registry: #{registry}"
+  end
+
+  def to_console
+    puts "\e[36mRisk Registry: #{@registry}\e[0m"
+  end
+
+  def to_html(output_file_path)
+    html_rows = ['']
+    html_rows.concat preface_html
+    html_rows.append render_register_table
+    save_html_to_file(html_rows, nil, output_file_path)
+  end
+
+  private
+
+  # The preface frontmatter title names the page; without it the registry does.
+  def preface_title
+    params = @preface&.frontmatter&.parameters
+    params && params['title']
+  end
+
+  # The rendered overview.md items. The parser-injected level-0 title heading
+  # is not authored preface content and is skipped.
+  def preface_html
+    return [] if @preface.nil?
+
+    @preface.items.reject { |i| i.is_a?(Heading) && i.level.zero? }.map(&:to_html)
+  end
+
+  def render_register_table
+    s = "<table class=\"controlled risk_register\">\n"
+    s += "\t<thead>\n"
+    s += "\t\t<th>#</th>\n"
+    s += "\t\t<th>Title</th>\n"
+    @columns.each { |c| s += "\t\t<th>#{c}</th>\n" }
+    @rpn_groups.each { |g| s += "\t\t<th>#{g[:name]} RPN</th>\n" }
+    s += "</thead>\n"
+    @records.each { |doc| s += render_record_row(doc) }
+    s + "</table>\n"
+  end
+
+  def render_record_row(doc)
+    href = "./#{record_href(doc)}"
+    s = "\t<tr>\n"
+    s += "\t\t<td class=\"item_id\">\n"
+    s += "\t\t\t<a name=\"#{doc.id}\" id=\"#{doc.id}\" href=\"#{href}\" title=\"Risk Record ID\">#{doc.id.upcase}</a>"
+    s += "\t\t</td>\n"
+    s += "\t\t<td class=\"item_text\" style='padding: 5px;'>\
+<a href=\"#{href}\" class=\"external\">#{record_title(doc)}</a></td>\n"
+    @columns.each { |c| s += render_column_cell(doc, c) }
+    @rpn_groups.each { |g| s += render_rpn_cell(doc, g) }
+    s + "\t</tr>\n"
+  end
+
+  # The Title cell (ENH-221): the frontmatter title with the record's own
+  # leading "ID:" prefix removed, case-insensitively — the ID column already
+  # carries it. A title not starting with the record's ID stays unchanged, and
+  # the record page keeps the full title. Display-only, like the uppercased ID:
+  # anchors and hrefs keep the canonical lowercase id.
+  def record_title(doc)
+    doc.title.to_s.sub(/\A#{Regexp.escape(doc.id)}\s*:\s*/i, '')
+  end
+
+  # The record page path relative to the registry page, which sits at the
+  # registry root: the record's html_rel_path minus its registry segment.
+  def record_href(doc)
+    doc.html_rel_path.split('/', 2).last
+  end
+
+  def render_column_cell(doc, column)
+    return "\t\t<td class=\"item_status\">#{doc.current_status}</td>\n" if column == STATUS_COLUMN
+    return render_affected_documents_cell(doc) if column == AFFECTED_DOCUMENTS_COLUMN
+
+    "\t\t<td class=\"item_text\">#{doc.section_html(column)}</td>\n"
+  end
+
+  # IDs only (ADR-218): each distinct linked controlled-paragraph ID as a
+  # clickable link in row order; a dangling ID renders in the existing
+  # broken-link style rather than being dropped. The Proposed Text stays on
+  # the record page.
+  def render_affected_documents_cell(doc)
+    links = doc.affected_document_ids.map { |id| affected_document_link(doc, id) }
+    "\t\t<td class=\"item_id\">#{links.join(', ')}</td>\n"
+  end
+
+  def affected_document_link(doc, item_id)
+    if doc.wrong_links_hash.key?(item_id)
+      %(<span class="broken_link" title="Unresolved reference">#{item_id}</span>)
+    else
+      spec = /^([a-zA-Z]+)-\d+/.match(item_id)&.[](1)&.downcase
+      href = "./../../specifications/#{spec}/#{spec}.html##{item_id}"
+      %(<a href="#{href}" class="external" title="Affected document">#{item_id}</a>)
+    end
+  end
+
+  # The computed group cell (ADR-217): the record's group value, blank when
+  # any input is missing or not numeric, coloured by the group's thresholds
+  # when configured.
+  def render_rpn_cell(doc, group)
+    value = doc.rpn_value(group)
+    return "\t\t<td class=\"item_rpn\"></td>\n" if value.nil?
+
+    classes = ['item_rpn', rpn_threshold_class(value, group)].compact.join(' ')
+    "\t\t<td class=\"#{classes}\">#{format_rpn(value)}</td>\n"
+  end
+end

data/lib/almirah/doc_types/risks_overview.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'base_document'
+require_relative 'rpn_rendering'
+
+# The all-registries summary page (ADR-219): build/risks/overview.html, the
+# target of the top-menu Risks button. One table row per registry, in
+# file-system order, with the columns Risk Registry (linked to the registry
+# page), Total Risks, Open Risks, Highest RPN and Average RPN — the RPN
+# aggregates computed over the registry's leading RPN group, ignoring records
+# whose group value is blank. The Risk Registry cell shows the registry
+# preface's frontmatter title, falling back to the folder name (ENH-221).
+class RisksOverview < BaseDocument
+  include RpnRendering
+
+  OPEN_EXCLUDED_STATUS = 'Closed'
+
+  attr_accessor :registries, :configuration, :prefaces
+
+  # `registries` is the ordered list of [name, records] pairs; `prefaces`
+  # maps a registry name to its parsed overview.md, when it has one.
+  def initialize(registries, configuration, prefaces = {})
+    super()
+    @registries = registries
+    @configuration = configuration
+    @prefaces = prefaces
+    @id = 'overview'
+    @title = 'Risk Registries'
+  end
+
+  def to_console
+    puts "\e[36mRisks Overview: #{@id}\e[0m"
+  end
+
+  def to_html(output_file_path)
+    html_rows = ['']
+    html_rows.append "<h1>#{@title}</h1>\n"
+    html_rows.append render_registries_table
+    save_html_to_file(html_rows, nil, output_file_path)
+  end
+
+  private
+
+  def render_registries_table
+    s = "<table class=\"controlled risks_overview\">\n"
+    s += "\t<thead>\n"
+    s += "\t\t<th>Risk Registry</th>\n"
+    s += "\t\t<th>Total Risks</th>\n"
+    s += "\t\t<th>Open Risks</th>\n"
+    s += "\t\t<th>Highest RPN</th>\n"
+    s += "\t\t<th>Average RPN</th>\n"
+    s += "</thead>\n"
+    @registries.each { |name, records| s += render_registry_row(name, records) }
+    s + "</table>\n"
+  end
+
+  def render_registry_row(name, records)
+    group = @configuration.get_risk_rpn_groups(name).first
+    values = group ? records.filter_map { |r| r.rpn_value(group) } : []
+    s = "\t<tr>\n"
+    s += "\t\t<td class=\"item_text\" style='padding: 5px;'>\
+<a name=\"#{name}\" id=\"#{name}\" href=\"./#{name}/overview.html\" class=\"external\" \
+title=\"Risk Registry\">#{registry_title(name)}</a></td>\n"
+    s += "\t\t<td class=\"item_rpn\">#{records.length}</td>\n"
+    s += "\t\t<td class=\"item_rpn\">#{open_count(records)}</td>\n"
+    s += render_highest_cell(values, group)
+    s += render_average_cell(values)
+    s + "\t</tr>\n"
+  end
+
+  # The registry preface's frontmatter title (ENH-221) — the same source the
+  # registry page heading uses — or the folder name when the registry has no
+  # preface or the preface carries no title.
+  def registry_title(name)
+    params = @prefaces[name]&.frontmatter&.parameters
+    (params && params['title']) || name
+  end
+
+  # Every record whose marked status is not Closed counts as open — including
+  # records with no current-status marker (ADR-219 keeps the count honest to
+  # the marker; another terminal status is the registry preface's to document).
+  def open_count(records)
+    records.count { |r| r.current_status.to_s.strip != OPEN_EXCLUDED_STATUS }
+  end
+
+  # The worst risk's verdict carries up: the cell keeps the leading group's
+  # threshold colouring. Blank without a group or computable values.
+  def render_highest_cell(values, group)
+    return "\t\t<td class=\"item_rpn\"></td>\n" if values.empty?
+
+    highest = values.max
+    classes = ['item_rpn', rpn_threshold_class(highest, group)].compact.join(' ')
+    "\t\t<td class=\"#{classes}\">#{format_rpn(highest)}</td>\n"
+  end
+
+  def render_average_cell(values)
+    return "\t\t<td class=\"item_rpn\"></td>\n" if values.empty?
+
+    average = (values.sum.to_f / values.length).round(1)
+    "\t\t<td class=\"item_rpn\">#{format_rpn(average)}</td>\n"
+  end
+end

data/lib/almirah/doc_types/rpn_rendering.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Shared RPN cell presentation (ADR-217, reused by the registries summary of
+# ADR-219): the threshold band class and the integer-when-whole formatting.
+module RpnRendering
+  # Acceptable at or below the acceptable bound, unacceptable at or above the
+  # unacceptable bound, caution between them (the ALARP band); a lone bound
+  # leaves the rest of the range as caution. nil when no thresholds configured.
+  def rpn_threshold_class(value, group)
+    if group[:acceptable] && value <= group[:acceptable]
+      'rpn_acceptable'
+    elsif group[:unacceptable] && value >= group[:unacceptable]
+      'rpn_unacceptable'
+    elsif group[:acceptable] || group[:unacceptable]
+      'rpn_caution'
+    end
+  end
+
+  # Whole values print as integers (8 * 3 -> 24, not 24.0).
+  def format_rpn(value)
+    value == value.to_i ? value.to_i.to_s : value.to_s
+  end
+end

data/lib/almirah/project/project_data.rb

@@ -3,7 +3,8 @@ 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, :decision_groups, :work_items, :link_registry
+              :implementation_matrices, :decisions, :decision_groups, :risk_records, :risk_registries,
+              :risk_registry_prefaces, :work_items, :link_registry
 
   def initialize
     @specifications = []
@@ -16,6 +17,14 @@ class ProjectData
     # 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 = {}

data/lib/almirah/project/work_item_scheduler.rb

@@ -5,7 +5,9 @@ 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.
+# 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
@@ -68,57 +70,56 @@ class WorkItemScheduler
 
   # 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).
+  # 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_last = {}
+    @owner_rows = Hash.new { |hash, owner| hash[owner] = [] }
     return if @items.empty?
 
-    owner_free = Hash.new(1)
-    priority_order.each { |wi| place(wi, owner_free) }
+    priority_order.each { |wi| place(wi) }
   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
+  # 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)
-    start = start_day(preds, owner_free[owner])
+    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(work_item, preds, start, owner)
-    advance_owner(owner, work_item, owner_free)
+    @binding[work_item] = binding_predecessor(preds, start, lane_pred)
+    @owner_rows[work_item.owner] << work_item unless work_item.owner.empty?
   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
+  # 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?
 
-  # 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?
+    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
 
-    owner_free[owner] = @ends[work_item]
-    @owner_last[owner] = work_item
+      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(_work_item, preds, start, owner)
+  def binding_predecessor(preds, start, lane_pred)
     candidates = preds.select { |p| @ends[p] == start }
-    resource_pred = @owner_last[owner]
-    candidates << resource_pred if resource_pred && @ends[resource_pred] == start
+    candidates << lane_pred if lane_pred
     candidates.min_by { |c| [c.record_id, c.step] }
   end
 

data/lib/almirah/project.rb

@@ -45,10 +45,12 @@ class Project
     parse_all_protocols
     parse_all_source_files
     parse_decisions
+    parse_risks
     link_all_specifications
     link_all_protocols
     link_all_source_files
     link_all_decisions
+    link_all_risks
     check_wrong_specification_referenced
     build_link_registry
     link_work_items
@@ -62,6 +64,9 @@ class Project
     render_decisions_overview
     render_critical_chain_page
     render_all_decisions
+    render_all_risk_records
+    render_risk_registry_pages
+    render_risks_overview
     render_index
     create_search_data
     report_broken_links
@@ -74,10 +79,12 @@ class Project
     parse_test_run test_run
     parse_all_source_files
     parse_decisions
+    parse_risks
     link_all_specifications
     link_all_protocols
     link_all_source_files
     link_all_decisions
+    link_all_risks
     check_wrong_specification_referenced
     build_link_registry
     link_work_items
@@ -91,6 +98,9 @@ class Project
     render_decisions_overview
     render_critical_chain_page
     render_all_decisions
+    render_all_risk_records
+    render_risk_registry_pages
+    render_risks_overview
     render_index
     create_search_data
     report_broken_links
@@ -238,6 +248,10 @@ class Project
       d.output_rel_path = "decisions/#{d.html_rel_path}"
       reg.register(d)
     end
+    @project_data.risk_records.each do |d|
+      d.output_rel_path = "risks/#{d.html_rel_path}"
+      reg.register(d)
+    end
     @project_data.source_files.each do |d|
       rel = d.path.sub("#{d.root_path}/", '')
       d.output_rel_path = "source_files/#{d.repository}/#{rel}.html"
@@ -309,6 +323,77 @@ class Project
     end
   end
 
+  # Collect risk records (ADR-215): each first-level subfolder of risks/ is a
+  # risk registry; a registry's overview.md is its preface, not a record. Files
+  # directly under risks/ belong to no registry and are not collected.
+  def parse_risks
+    path = @configuration.project_root_directory
+    risks_root = "#{path}/risks"
+    Dir.glob("#{risks_root}/*/**/*.md").each do |f|
+      if File.basename(f).downcase == 'overview.md'
+        register_risk_preface(f, risks_root)
+        next
+      end
+
+      doc = DocFabric.create_risk_record(f)
+      rel_dir = File.dirname(f.sub("#{risks_root}/", ''))
+      doc.registry = rel_dir.split('/').first
+      doc.html_rel_path = "#{rel_dir}/#{doc.id}.html"
+      @project_data.risk_records.append(doc)
+      add_to_risk_registry(doc)
+    end
+    BaseDocument.show_risks_link = risk_registry_names.any?
+    ConsoleReporter.count('parsing risk records', @project_data.risk_records.length)
+    report_duplicate_risk_ids
+  end
+
+  # The registry names in file-system (parse) order: every first-level risks/
+  # folder holding records or a preface. The set that earns the top-menu Risks
+  # button (ADR-219) and a registry page (ADR-216).
+  def risk_registry_names
+    (@project_data.risk_registries.map { |g| g.keys.first } +
+     @project_data.risk_registry_prefaces.keys).uniq
+  end
+
+  # A registry's own overview.md is its preface (ADR-216), parsed like a record
+  # for rendering but never collected. An overview.md nested deeper inside a
+  # registry is neither a record nor a preface and is skipped entirely.
+  def register_risk_preface(file, risks_root)
+    rel_dir = File.dirname(file.sub("#{risks_root}/", ''))
+    return unless rel_dir.index('/').nil?
+
+    doc = DocFabric.create_risk_record(file)
+    doc.registry = rel_dir
+    doc.output_rel_path = "risks/#{rel_dir}/overview.html"
+    @project_data.risk_registry_prefaces[rel_dir] = doc
+  end
+
+  # Add a risk record to its registry, keyed on the first-level folder under
+  # risks/. Registries are single-key hashes appended in folder-encounter order,
+  # mirroring add_to_decision_group.
+  def add_to_risk_registry(doc)
+    registry = @project_data.risk_registries.find { |g| g.key?(doc.registry) }
+    if registry.nil?
+      @project_data.risk_registries.append({ doc.registry => [doc] })
+    else
+      registry[doc.registry].append(doc)
+    end
+  end
+
+  # Two risk records sharing one id would collide in the project-wide link
+  # space; each registry is expected to use its own letter prefix (ADR-215).
+  # Reported as a non-failing warning, like broken links.
+  def report_duplicate_risk_ids
+    duplicates = @project_data.risk_records.group_by(&:id).select { |_id, records| records.length > 1 }
+    return if duplicates.empty?
+
+    ConsoleReporter.warn('duplicated risk ids', duplicates.length)
+    duplicates.each do |id, records|
+      files = records.map { |r| r.path.sub("#{@configuration.project_root_directory}/", '') }.join(', ')
+      puts ConsoleReporter.warn_detail("  #{id}: #{files}")
+    end
+  end
+
   def parse_test_run(test_run)
     path = @configuration.project_root_directory
     Dir.glob("#{path}/tests/runs/#{test_run}/**/*.md").each do |f|
@@ -366,6 +451,22 @@ class Project
     ConsoleReporter.count('decision links', number_of_links)
   end
 
+  # A risk record's Affected Documents uplinks resolve exactly as a decision
+  # record's (ADR-218): the specification paragraph gains the record among its
+  # downlinks and a dangling Req-ID lands in the record's wrong_links_hash.
+  def link_all_risks
+    number_of_links = 0
+    @project_data.risk_records.each do |r|
+      @project_data.specifications.each do |s|
+        next unless r.up_link_docs.key?(s.id.to_s)
+
+        DocLinker.link_decision_to_spec(r, s)
+        number_of_links += 1
+      end
+    end
+    ConsoleReporter.count('risk links', number_of_links)
+  end
+
   def link_all_source_files
     return unless DocLinker.link_all_source_files(@project_data)
 
@@ -535,6 +636,66 @@ class Project
     end
   end
 
+  # Each registry renders to build/risks/<registry>/overview.html (ADR-216):
+  # the rendered preface first, then the register table of the registry's
+  # records, with the columns configured under the risks: root of project.yml
+  # (implicit columns plus Status when unconfigured). A registry holding only
+  # an overview.md still renders, with an empty table. Runs after
+  # render_all_risk_records so every record carries its rendering paths.
+  def render_risk_registry_pages
+    registry_names = risk_registry_names
+    return if registry_names.empty?
+
+    path = @configuration.project_root_directory
+    registry_names.each do |name|
+      records = @project_data.risk_registries.find { |g| g.key?(name) }&.fetch(name) || []
+      preface = @project_data.risk_registry_prefaces[name]
+      if preface
+        preface.root_prefix = '../../'
+        preface.specifications_path = "./#{preface.root_prefix}specifications/"
+      end
+      doc = DocFabric.create_risk_registry_page(name, records, preface, @configuration.get_risk_columns(name),
+                                                @configuration.get_risk_rpn_groups(name))
+      out_dir = "#{path}/build/risks/#{name}"
+      FileUtils.mkdir_p(out_dir)
+      doc.to_html("#{out_dir}/")
+    end
+  end
+
+  # The all-registries summary page (ADR-219): build/risks/overview.html, one
+  # row per registry with the total, open, and leading-group RPN aggregates.
+  # Rendered whenever the project has at least one registry — the same
+  # condition that emits the top-menu Risks button.
+  def render_risks_overview
+    registry_names = risk_registry_names
+    return if registry_names.empty?
+
+    registries = registry_names.map do |name|
+      [name, @project_data.risk_registries.find { |g| g.key?(name) }&.fetch(name) || []]
+    end
+    path = @configuration.project_root_directory
+    FileUtils.mkdir_p("#{path}/build/risks")
+    doc = DocFabric.create_risks_overview(registries, @configuration, @project_data.risk_registry_prefaces)
+    doc.to_html("#{path}/build/risks/")
+  end
+
+  # Each risk record renders to its own page under build/risks/<registry>/,
+  # with the navigation pane, exactly as decision records do (ADR-215).
+  def render_all_risk_records
+    return if @project_data.risk_records.empty?
+
+    build_risks_root = "#{@configuration.project_root_directory}/build/risks"
+    @project_data.risk_records.each do |doc|
+      out_dir_rel = File.dirname(doc.html_rel_path)
+      out_dir = "#{build_risks_root}/#{out_dir_rel}"
+      FileUtils.mkdir_p(out_dir)
+      depth = 1 + out_dir_rel.split('/').size
+      doc.root_prefix = '../' * depth
+      doc.specifications_path = "./#{doc.root_prefix}specifications/"
+      doc.to_html(NavigationPane.new(doc), "#{out_dir}/")
+    end
+  end
+
   def create_search_data
     db = SpecificationsDb.new @project_data.specifications
     data_path = "#{@configuration.project_root_directory}/build/data"

data/lib/almirah/project_configuration.rb

@@ -106,6 +106,29 @@ class ProjectConfiguration
     value
   end
 
+  # The ordered register-column list for a risk registry folder (ADR-216),
+  # read from the risks: root — a list of { folder:, columns: } entries.
+  # nil when the registry carries no configuration; such a registry renders
+  # the implicit columns plus Status only.
+  def get_risk_columns(folder)
+    entry = risk_entry(folder)
+    return nil unless entry.is_a?(Hash) && entry['columns'].is_a?(Array)
+
+    entry['columns'].map(&:to_s)
+  end
+
+  # The named RPN groups of a risk registry folder (ADR-217), from the rpn:
+  # list of its risks: entry, in configured order:
+  # [{ name:, inputs: [..], acceptable:, unacceptable: }, ...]. Groups without
+  # a name or a non-empty inputs list are dropped; a threshold bound that is
+  # absent or not numeric is nil. Empty when the registry declares no groups.
+  def get_risk_rpn_groups(folder)
+    entry = risk_entry(folder)
+    return [] unless entry.is_a?(Hash) && entry['rpn'].is_a?(Array)
+
+    entry['rpn'].filter_map { |raw| risk_rpn_group(raw) }
+  end
+
   def is_spec_db_shall_be_created
     if @parameters.key? 'output'
       @parameters['output'].each do |p|
@@ -115,6 +138,33 @@ class ProjectConfiguration
     false
   end
 
+  # The risks: entry configuring a registry folder, or nil when absent.
+  def risk_entry(folder)
+    return nil unless @parameters.is_a?(Hash)
+
+    entries = @parameters['risks']
+    return nil unless entries.is_a?(Array)
+
+    entries.find { |e| e.is_a?(Hash) && e['folder'].to_s == folder }
+  end
+
+  def risk_rpn_group(raw)
+    return nil unless raw.is_a?(Hash)
+
+    name = raw['name'].to_s
+    inputs = raw['inputs']
+    return nil if name.empty? || !inputs.is_a?(Array) || inputs.empty?
+
+    thresholds = raw['thresholds'].is_a?(Hash) ? raw['thresholds'] : {}
+    { name: name, inputs: inputs.map(&:to_s),
+      acceptable: numeric_threshold(thresholds['acceptable']),
+      unacceptable: numeric_threshold(thresholds['unacceptable']) }
+  end
+
+  def numeric_threshold(value)
+    value.is_a?(Numeric) ? value : nil
+  end
+
   # A value under the planning: key, or nil when planning is absent.
   def planning_value(key)
     return nil unless @parameters.is_a?(Hash)

data/lib/almirah/templates/css/main.css

@@ -505,4 +505,16 @@ img{
     padding: 5px;
     text-align:center;
     background:#fff;
-}
+}/* Risk register RPN threshold bands (ADR-217): acceptable / ALARP caution / unacceptable */
+td.item_rpn {
+    text-align: center;
+}
+td.rpn_acceptable {
+    background-color: #d5f5e3;
+}
+td.rpn_caution {
+    background-color: #fdebd0;
+}
+td.rpn_unacceptable {
+    background-color: #fadbd8;
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: Almirah
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.4
 platform: ruby
 authors:
 - Oleksandr Ivanov
@@ -90,6 +90,10 @@ files:
 - lib/almirah/doc_types/persistent_document.rb
 - lib/almirah/doc_types/planning_dates.rb
 - lib/almirah/doc_types/protocol.rb
+- lib/almirah/doc_types/risk_record.rb
+- lib/almirah/doc_types/risk_registry_page.rb
+- lib/almirah/doc_types/risks_overview.rb
+- lib/almirah/doc_types/rpn_rendering.rb
 - lib/almirah/doc_types/source_file.rb
 - lib/almirah/doc_types/specification.rb
 - lib/almirah/doc_types/traceability.rb
@@ -134,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.1
 specification_version: 4
 summary: Almirah
 test_files: []