Skip to content

ccoalm/ccl-skills / skills/skill-extraction-workflow

skill-extraction-workflow

Flagged

复盘 / 沉淀 / 总结经验 / 补进技能 / 技能缺陷 / 流程优化 / would other teammates hit this / will we forget next time / teamwide recurrence / extract skill / post-mortem / 深度 review·审计技能仓库 / 对标外部技能包找 gap(benchmark superpowers·gstack 等) / 核查全局安装点(~/.config/opencode 等)旧快照是否遮蔽本仓技能 / 本仓(ccl-skills 等共享技能仓)OpenCode 项目配置·命令治理 → turn reusable lessons into durable CCL skills.

FileKindSize
SKILL.mdskill md111.0 KB
agents/openai.yamlconfig257 B
references/analysis-parse-fix-test-challenge-replay.mdmarkdown1.5 KB
references/attention-budget-ratchet.mdmarkdown13.7 KB
references/attribution-verification.mdmarkdown4.4 KB
references/bootstrap-slim-c3-obligation-table.mdmarkdown8.0 KB
references/correction-routing-map.mdmarkdown3.7 KB
references/coverage-exhaustion-traps.mdmarkdown19.6 KB
references/description-authoring.mdmarkdown21.1 KB
references/dual-track-review-gate.mdmarkdown110.6 KB
references/eval-routing.mdmarkdown22.2 KB
references/evidence-card-template.mdmarkdown3.2 KB
references/example-domain-preselect.mdmarkdown4.6 KB
references/external-practice-controls.mdmarkdown45.5 KB
references/extraction-lifecycle-handoff.mdmarkdown6.9 KB
references/extraction-quickstart.mdmarkdown20.2 KB
references/firing-point-placement.mdmarkdown21.3 KB
references/harness-patterns-and-eval.mdmarkdown42.6 KB
references/incident-postmortem-extraction.mdmarkdown28.8 KB
references/l0-l1-l2-routing.mdmarkdown10.3 KB
references/online-skill-review.mdmarkdown6.7 KB
references/parallel-stack-references-pattern.mdmarkdown35.9 KB
references/r0-leakage-audit.mdmarkdown19.9 KB
references/recurring-anti-patterns-checklist.mdmarkdown34.4 KB
references/resume-paused-delivery.mdmarkdown3.0 KB
references/review-feedback-mining.mdmarkdown5.7 KB
references/review-finding-standards.mdmarkdown7.3 KB
references/review-rubric.mdmarkdown3.1 KB
references/rule-consolidation.mdmarkdown38.2 KB
references/skill-listing-budget.mdmarkdown1.7 KB
references/source-register.mdmarkdown1.0 MB
references/source-to-skill-extraction.mdmarkdown109.3 KB
references/two-source-extraction-pattern.mdmarkdown19.4 KB
references/uiux-judgment-extraction.mdmarkdown19.1 KB
references/uiux-routing-map.mdmarkdown5.8 KB
references/validation-and-landing.mdmarkdown46.9 KB
scripts/AGENTS.mdmarkdown635 B
scripts/check-ccl-skills.shexecutablescript100.7 KB
scripts/check-contract-anchors.shexecutablescript5.6 KB
scripts/check-evidence-card-leak.shexecutablescript26.1 KB
scripts/check-mr-target-freshness.shexecutablescript9.4 KB
scripts/check-size-budget.shexecutablescript36.0 KB
scripts/check-sync-pointers.shexecutablescript22.6 KB
scripts/check_review_evidence_present.pyexecutablescript4.6 KB
scripts/contract-anchors.tsvother3.8 KB
scripts/entrypoint_form_census.pyexecutablescript7.1 KB
scripts/eval-golden-trace.rbexecutablescript10.0 KB
scripts/eval-health.rbexecutablescript14.6 KB
scripts/eval-routing-bank.rbexecutablescript30.4 KB
scripts/eval-routing.rbexecutablescript9.2 KB
scripts/extraction_review_gate.shexecutablescript1.8 KB
scripts/gate_receipt.pyexecutablescript24.7 KB
scripts/generic-r0-leak-scan.shexecutablescript12.4 KB
scripts/governing-chain-diff.pyexecutablescript12.8 KB
scripts/impact-chain-gate.rbexecutablescript124.4 KB
scripts/obligation-ledger.pyscript107.0 KB
scripts/reference-access-census.shexecutablescript8.3 KB
scripts/register-firing-path-resolution.rbexecutablescript48.4 KB
scripts/shared_git_surface_gate.pyexecutablescript38.0 KB
scripts/skill-behavior-eval.pyexecutablescript39.3 KB
scripts/skill-paired-eval.pyexecutablescript76.9 KB
scripts/source-register-lifecycle.rbscript1.5 KB
scripts/source-register-pending-status.rbscript2.0 KB
scripts/test_ai_coding_implementation_gates.shexecutablescript85.2 KB
scripts/test_antipattern_grep_panel.shexecutablescript3.2 KB
scripts/test_body_compliance_grading.shexecutablescript21.0 KB
scripts/test_check_ccl_impact_chain_refscripts.shexecutablescript145.1 KB
scripts/test_check_ccl_r0_status.shexecutablescript4.2 KB
scripts/test_check_ccl_register_pending_exclusion.shexecutablescript7.4 KB
scripts/test_check_ccl_regressions.shexecutablescript14.3 KB
scripts/test_check_ccl_route_drift.shexecutablescript22.6 KB
scripts/test_check_ccl_size_budget.shexecutablescript59.5 KB
scripts/test_check_ccl_skill_catalog.shexecutablescript23.3 KB
scripts/test_check_ccl_source_register_lifecycle.shexecutablescript6.1 KB
scripts/test_check_contract_anchors.shexecutablescript7.4 KB
scripts/test_check_mr_target_freshness.shexecutablescript12.8 KB
scripts/test_check_review_evidence_present.shexecutablescript4.3 KB
scripts/test_check_sync_pointers.shexecutablescript32.5 KB
scripts/test_ci_checkout_ref_binding.shexecutablescript8.2 KB
scripts/test_controlled_escalation_pins.shexecutablescript7.7 KB
scripts/test_entrypoint_domain_scan_terms.shexecutablescript8.8 KB
scripts/test_entrypoint_form_census.shexecutablescript6.3 KB
scripts/test_eval_routing_bank_grader_diagnostics.shexecutablescript20.6 KB
scripts/test_eval_routing_bank_resolution.shexecutablescript15.3 KB
scripts/test_eval_routing_bank_surface_binding.shexecutablescript6.9 KB
scripts/test_eval_routing_prose_target.shexecutablescript3.7 KB
scripts/test_eval_runtime.pyexecutablescript43.3 KB
scripts/test_extraction_review_gate.shexecutablescript15.2 KB
scripts/test_frozen_case_sanctity.shexecutablescript6.9 KB
scripts/test_frozen_case_sanctity_selfproof.shexecutablescript4.6 KB
scripts/test_gate_receipt.shexecutablescript17.7 KB
scripts/test_generic_r0_leak_scan.shexecutablescript6.4 KB
scripts/test_git_identity_predicate_gate.shscript13.8 KB
scripts/test_governing_chain_diff.shexecutablescript15.1 KB
scripts/test_impact_chain_gate_dateless_host.shexecutablescript6.8 KB
scripts/test_impact_chain_gate_verdict_differential.shexecutablescript20.8 KB
scripts/test_impact_chain_round_attribution.shexecutablescript32.5 KB
scripts/test_impact_chain_self_adjudication.shexecutablescript31.4 KB
scripts/test_impact_chain_source_refuted.shexecutablescript14.7 KB
scripts/test_liveness_predicate_gate.shexecutablescript14.5 KB
scripts/test_locale_independent_gates.shexecutablescript13.0 KB
scripts/test_obligation_ledger.shexecutablescript94.9 KB
scripts/test_obligation_ledger_repo_audit.shexecutablescript2.7 KB
scripts/test_pinned_phrase_mutation_walk.shexecutablescript6.5 KB
scripts/test_reference_access_census.shexecutablescript17.3 KB
scripts/test_register_firing_path_resolution.shexecutablescript41.0 KB
scripts/test_register_firing_path_wiring.shexecutablescript29.9 KB
scripts/test_regression_runner_lanes.shexecutablescript4.5 KB
scripts/test_regression_runner_registration.shexecutablescript1.5 KB
scripts/test_routing_bank_integrity.shexecutablescript15.5 KB
scripts/test_routing_pointer_integrity.shexecutablescript18.9 KB
scripts/test_shared_git_surface_gate.shexecutablescript76.8 KB
scripts/test_skill_paired_eval.pyscript60.0 KB
scripts/test_teardown_guard_pins.shexecutablescript17.0 KB
scripts/test_uiux_delivery_contract.shexecutablescript118.6 KB
scripts/test_uiux_loading_budget.shexecutablescript15.4 KB
scripts/test_validate_skill_credential_cwd.shexecutablescript2.6 KB
scripts/test_validate_skill_cross_refs.shexecutablescript4.8 KB
scripts/test_validate_skill_root_depth.shexecutablescript2.5 KB
scripts/validate-skill.shexecutablescript10.5 KB

scripts/register-firing-path-resolution.rb

View on GitHub
#!/usr/bin/env ruby
# frozen_string_literal: true

require "digest"
require "json"
require "ripper"

# `Ripper.sexp` omits positions from tokenless statement nodes such as
# `return0` and `zsuper`. Append an inert location child to every semantic parser
# node so dead-subtree line collection also covers those statements without
# changing the event's existing child indexes.
class PositionedRubySexpBuilder < Ripper::SexpBuilderPP
  Ripper::PARSER_EVENTS.each do |event|
    define_method("on_#{event}") do |*arguments|
      node = super(*arguments)
      if node.is_a?(Array) && node[0].is_a?(Symbol) && !node[0].to_s.start_with?("@")
        node << [:@__location, "", [lineno, column]]
      end
      node
    end
  end
end

#
# Register firing-path RESOLUTION gate: every `firing-path:` locator recorded in
# `references/source-register.md` must still resolve, for the WHOLE ledger — not
# only for rows added in the current diff.
#
# Why this exists as a separate gate from impact-chain-gate.rb: that gate is
# diff-scoped by design (it adjudicates whether an ADDED row earns its landing),
# so a historical row is validated exactly once, at the commit that wrote it.
# Nothing re-checks it afterwards. The ledger is append-only while the prose it
# anchors into is living text, so any later edit that MOVES or REWORDS an
# anchored sentence silently voids that row's firing evidence: the row keeps
# asserting a mechanical firing path that no longer exists, and every gate stays
# green because no gate looks. Observed shape: an entrypoint-slimming change
# relocated an anchored rule out of a `SKILL.md` into a reference and reworded it
# in the same commit; the full checker passed, and the break was found only by a
# human reading the register by hand.
#
# Contract: exits 1 and names every unresolved locator; exits 0 when all resolve.
# Invoked by check-ccl-skills.sh with the target repo root as ARGV[0].
#
# Locator forms accepted (mirroring the impact-chain gate's vocabulary):
#   command:<repo-relative path>          -> must exist and be executable
#   file:<repo-relative path>#<anchor>    -> file must exist and carry the anchor
#   file:<path>.rb#line-sha256:<hex>       -> a trimmed Ruby code line must hash to hex
#
# An anchor resolves EITHER as literal text in the file (the convention the
# impact-chain gate enforces on added rows) OR as a GitHub-style heading slug
# naming a real heading. The slug form is accepted because the ledger is
# append-only: a historical row that spelled its anchor as `#some-heading-slug`
# cannot be rewritten to the literal form, and the section it names genuinely
# exists, so failing it would be a false red with no legal repair.
#
# One declaration may carry several comma-separated locators; each is resolved
# independently. The split is on a comma that INTRODUCES another locator
# (`,` followed by `file:`/`command:`), never on every comma: literal anchors are
# natural-language rule text and three in this ledger already contain a comma
# ("...before landing it, not after challenge rounds"). Splitting naively would
# validate only the fragment before the comma, so deleting the rest of the
# anchored sentence would still pass — a false negative in exactly the direction
# this gate exists to close.
#
# `line-sha256:` is intentionally exact-line rather than substring evidence. It
# is for Ruby guard implementation lines where replacing executable-looking text
# with a comment must not preserve the locator. The digest is SHA-256 over
# `line.strip` bytes and may group its lowercase hex in four-character chunks
# with hyphens; whitespace-only reindentation is allowed, while commenting,
# rewording, or deleting the line turns the whole-ledger gate red. The matching
# line must also carry at least one Ripper token outside whitespace, comments,
# embedded docs, and heredoc/string content, and it must not sit in a statically
# unreachable branch or an uncalled lambda body. Other target languages fail
# closed until they have an equivalent classifier.

root = ARGV.fetch(0) { abort "usage: register-firing-path-resolution.rb <repo-root>" }

REGISTER = "skills/skill-extraction-workflow/references/source-register.md"

register_path = File.join(root, REGISTER)
unless File.file?(register_path)
  warn "register_firing_path_gate_failed: #{REGISTER} not found under #{root}"
  exit 1
end

# Reviewed waivers cover the immutable historical rows whose locator was retired
# by an explicit superseding round. The digest table below binds each waiver to
# those exact rows (one digest, or an array when several rows cited the retired
# locator); a new row cannot inherit it by reusing the locator.
EXEMPT = {
  "file:skills/code-review/references/development-completion.md#no further reviewer call when it only fixes findings below P0/P1" =>
    "the post-challenge-fix-delta round sends every non-exempt post-challenge fix to one delta pass; its superseding register row anchors the new rule",
  "file:skills/skill-extraction-workflow/references/dual-track-review-gate.md#After five delta passes a still-open P0/P1" =>
    "147 replaces the task-wide review stop with a progress checkpoint; the superseding register row preserves required delta review",
  "file:skills/product-ui-ux-design/references/external-ui-ux-quality-benchmarks.md#Disabled semantics are real, not painted" =>
    "065 replaced the combined platform walkthrough with an authority-classed claim ledger and executable delivery contract",
  "file:skills/product-ui-ux-design/references/external-ui-ux-quality-benchmarks.md#predictive-back geometry routes to" =>
    "065 moved platform mechanics to the canonical client-owner return while keeping platform guidance scoped",
  "file:skills/product-ui-ux-design/references/external-ui-ux-quality-benchmarks.md#Interaction-state matrix is complete" =>
    "065 replaced walkthrough-level proof with criterion IDs, test-layer selection, runtime evidence, and a candidate-bound verdict",
  "command:skills/skill-extraction-workflow/scripts/test_validate_extraction_review_state.sh" =>
    "127 retired the closeout ledger and its validator; the extraction lane records single-shot passes instead",
  "command:skills/skill-extraction-workflow/scripts/test_review_ledger_binding.sh" =>
    "127 retired the merge-side candidate binding; the post-review delta and the human merge replace it",
  "command:skills/skill-extraction-workflow/scripts/review_ledger_binding.py" =>
    "127 retired the merge-side candidate binding; the post-review delta and the human merge replace it",
  "file:skills/skill-extraction-workflow/references/dual-track-review-gate.md#Sum spent rounds across all chains before opening one more" =>
    "127 replaced the round budget with one review, one challenge and bounded delta passes",
  "file:skills/skill-extraction-workflow/references/dual-track-review-gate.md#accumulate every fix unapplied, run the challenge on the frozen" =>
    "127 lets the challenge run after the review's fixes; nothing is bound to one candidate",
  "file:skills/skill-extraction-workflow/references/extraction-quickstart.md#still owes the two-round chain before it can land" =>
    "127 retired the merge-side binding that imposed the chain on wording-only changes",
  "file:skills/skill-extraction-workflow/references/extraction-quickstart.md#must exclude every evidence JSON the round has already added" =>
    "127 retired the merge-side binding whose evidence exclusion this rule mirrored",
  "command:skills/skill-extraction-workflow/scripts/check-parallel-stack-parity.sh" =>
    "the architecture-skill merge put each mirrored pair into one file, so the cross-file parity gate has nothing left to compare; the superseding register row records the single-file form",
  "file:skills/nodejs-service-dev/SKILL.md#Do not borrow the Go or Python architecture skill" =>
    "the architecture-skill merge gave Node.js/TypeScript architecture a named owner (software-architecture, read with its Node.js/TypeScript part), so the no-sibling wording was replaced; the superseding register row anchors the new route and its guard against borrowing the Go or Python stack defaults",
  "file:skills/defect-diagnosis/SKILL.md#must not be filed under a sibling stack's architecture skill" =>
    "the architecture-skill merge gave Node.js/TypeScript architecture a named owner (software-architecture, read with its Node.js/TypeScript part), so the no-sibling wording was replaced; the superseding register row anchors the new route and its guard against borrowing the Go or Python stack defaults",
  "file:skills/llm-inference-integration/SKILL.md#never to a Node architecture sibling" =>
    "the architecture-skill merge gave Node.js/TypeScript architecture a named owner (software-architecture, read with its Node.js/TypeScript part), so the no-sibling wording was replaced; the superseding register row anchors the new route and its guard against borrowing the Go or Python stack defaults"
}.freeze

# Recorded relocations. A file that MOVED keeps its rule text, but the append-only
# row that anchors into it cannot be rewritten to name the new path, and an EXEMPT
# waiver would be the wrong repair: it stops checking the anchor text altogether.
# An entry here resolves the old path to the new one and then runs every ordinary
# check there — containment, existence, anchor text, line digest — so rewording
# the rule after the move still reds. Three guards keep the table honest: the old
# path must be absent (an old path that exists again is ambiguous, so it fails
# closed instead of silently preferring either file), every entry must be cited by
# a ledger row (dead configuration reds), and the new path passes the same
# containment checks as any locator. Like the digest table it is injectable for
# fixtures and vendoring repositories (REGISTER_FIRING_PATH_MOVED_PATHS, a JSON
# object of old path => new path); production uses the built-in table.
MOVED_PATHS = {
  # The Go and Python architecture skills were merged into `software-architecture`.
  "skills/go-microservice-architecture/references/architecture-playbook.md" =>
    "skills/software-architecture/references/go-architecture-playbook.md",
  "skills/go-microservice-architecture/references/cross-cutting-concerns.md" =>
    "skills/software-architecture/references/cross-cutting-concerns.md",
  "skills/go-microservice-architecture/references/event-driven-architecture.md" =>
    "skills/software-architecture/references/event-driven-architecture.md",
  "skills/go-microservice-architecture/references/multi-tenant-isolation.md" =>
    "skills/software-architecture/references/multi-tenant-isolation.md",
  "skills/python-service-architecture/SKILL.md" =>
    "skills/software-architecture/SKILL.md",
  "skills/python-service-architecture/references/architecture-playbook.md" =>
    "skills/software-architecture/references/python-architecture-playbook.md",
  "skills/python-service-architecture/references/multi-tenant-isolation.md" =>
    "skills/software-architecture/references/multi-tenant-isolation.md",
  "skills/python-service-architecture/references/packaging-runtime-readiness.md" =>
    "skills/software-architecture/references/packaging-runtime-readiness.md",
  "skills/python-service-architecture/references/workflow-state-architecture.md" =>
    "skills/software-architecture/references/python-workflow-state-architecture.md"
}.freeze

moved_table_path = ENV["REGISTER_FIRING_PATH_MOVED_PATHS"].to_s
moved_paths =
  if moved_table_path.empty?
    MOVED_PATHS
  else
    begin
      parsed = JSON.parse(File.read(moved_table_path))
      unless parsed.is_a?(Hash) && parsed.all? { |k, v| k.is_a?(String) && v.is_a?(String) }
        raise JSON::ParserError, "expected an object of old path => new path strings"
      end
      puts "register_firing_path_moved_paths_injected: #{moved_table_path} (#{parsed.length} entries)"
      parsed
    rescue SystemCallError, IOError, JSON::ParserError => e
      warn "register_firing_path_moved_paths_table_unreadable: #{moved_table_path}: #{e.message}"
      exit 2
    end
  end
moved_uses = Hash.new(0)
moved_lookups = {}

# `\p{Word}` rather than `[a-z0-9]`: GitHub keeps non-ASCII characters in a slug,
# and most headings in this repository are Chinese. Stripping them would collapse
# a CJK heading to an empty slug and permanently false-red a locator that names
# it — unrepairable, because the ledger row cannot be edited.
def slugify(heading)
  heading.downcase.gsub(/[^[[:word:]]\s-]/, "").strip.gsub(/\s+/, "-")
end

# Fenced blocks are examples, not operative text. Both the anchor search and the
# heading scan run against the stripped body: a rule that was deleted but still
# appears inside a code sample is NOT a living carrier, and a `## Heading` inside
# a fence is not a real heading. Fence matching follows CommonMark — a fence
# closes only on a run of the SAME character at least as long as the opener — so
# a shorter inner run cannot terminate a longer outer fence.
def strip_fences(body)
  out = []
  opener = nil
  body.each_line do |line|
    if (m = line.match(/\A\s{0,3}(`{3,}|~{3,})/))
      run = m[1]
      if opener.nil?
        opener = run
        next
      elsif run[0] == opener[0] && run.length >= opener.length
        opener = nil
        next
      end
    end
    out << line if opener.nil?
  end
  out.join
end

# GitHub's own duplicate-heading disambiguation: the first `## Setup` is `setup`,
# the second `setup-1`, the third `setup-2`. Reproduced exactly rather than by
# stripping a trailing `-N`, because stripping accepts `#setup-99` when no such
# anchor exists — trading a false positive for a false negative in a gate whose
# whole job is detecting dead anchors.
def heading_slugs(body)
  seen = Hash.new(0)
  body.scan(/^\#+\s+(.+?)\s*$/).flatten.map do |h|
    base = slugify(h)
    n = seen[base]
    seen[base] += 1
    n.zero? ? base : "#{base}-#{n}"
  end
end

# Repo-relative containment. A locator that escapes the repository would resolve
# against content this gate does not govern, so a dead in-repo anchor could be
# "satisfied" from outside. Rejects absolute paths, `..` traversal, and symlinked
# targets that land outside the root.
# Split deliberately in two so a MISSING target reports "not found" rather than
# a misleading containment error: the two failures need different fixes.
def syntactically_contained?(rel)
  !rel.start_with?("/") && !rel.split("/").include?("..")
end

def resolves_inside?(root, rel)
  real_root = File.realpath(root)
  real = File.realpath(File.join(root, rel))
  real == real_root || real.start_with?(real_root + File::SEPARATOR)
rescue Errno::ENOENT, Errno::ELOOP, Errno::ENAMETOOLONG
  false
end

RUBY_NON_CODE_LINE_TOKENS = %i[
  on_sp on_ignored_sp on_comment on_nl on_ignored_nl
  on_tstring_content on_words_sep on_heredoc_end
  on_embdoc on_embdoc_beg on_embdoc_end
].freeze

def ruby_code_line_numbers(body)
  Ripper.lex(body).each_with_object({}) do |((line_number, _column), token_type, _text, _state), lines|
    lines[line_number] = true unless RUBY_NON_CODE_LINE_TOKENS.include?(token_type)
  end
end

def ruby_ast_each(node, &block)
  return unless node.is_a?(Array)

  yield node if node.first.is_a?(Symbol)
  node.each { |child| ruby_ast_each(child, &block) if child.is_a?(Array) }
end

def ruby_ast_each_with_ancestors(node, ancestors = [], &block)
  return unless node.is_a?(Array)

  node_type = node.first if node.first.is_a?(Symbol)
  yield node, ancestors if node_type
  child_ancestors = node_type ? ancestors + [node] : ancestors
  node.each do |child|
    ruby_ast_each_with_ancestors(child, child_ancestors, &block) if child.is_a?(Array)
  end
end

def ruby_ast_line_numbers(node)
  lines = {}
  ruby_ast_each(node) do |child|
    next unless child.first.to_s.start_with?("@")
    next unless child[2].is_a?(Array) && child[2][0].is_a?(Integer)

    lines[child[2][0]] = true
  end
  lines
end

def ruby_dead_body_line_numbers(body, preceding, code_lines)
  body_lines = ruby_ast_line_numbers(body)
  return {} if body_lines.empty?

  preceding_line = ruby_ast_line_numbers(preceding).keys.max || 0
  last_body_line = body_lines.keys.max
  code_lines.select do |line_number, _|
    line_number > preceding_line && line_number <= last_body_line
  end
end

def ruby_local_name(node, wrapper)
  return unless node.is_a?(Array) && node[0] == wrapper

  token = node[1]
  token[1] if token.is_a?(Array) && token[0] == :@ident
end

def ruby_condition_truthiness(node)
  return :unknown unless node.is_a?(Array)

  if node[0] == :var_ref && node[1].is_a?(Array) && node[1][0] == :@kw
    return :falsey if %w[false nil].include?(node[1][1])
    return :truthy if node[1][1] == "true"
  end

  return ruby_condition_truthiness(node[1][0]) if node[0] == :paren &&
                                                   node[1].is_a?(Array) &&
                                                   node[1].length == 1

  :unknown
end

def ruby_method_definition_name(node)
  return unless node.is_a?(Array) && node[0] == :def

  token = node[1]
  token[1] if token.is_a?(Array) && token[0] == :@ident
end

def ruby_direct_method_call(node)
  token = case node[0]
          when :vcall, :fcall, :command then node[1]
          end
  return unless token.is_a?(Array) && token[0] == :@ident

  [token[1], token[2][0]]
end

def ruby_reachable_method_definition_ids(ast, unreachable)
  definitions = Hash.new { |hash, key| hash[key] = [] }
  top_level_calls = []
  method_calls = Hash.new { |hash, key| hash[key] = [] }

  ruby_ast_each_with_ancestors(ast) do |node, ancestors|
    if (name = ruby_method_definition_name(node))
      definition_line = node[1][2][0]
      deferred = ancestors.any? do |ancestor|
        %i[class module sclass def defs lambda].include?(ancestor[0])
      end
      definitions[name] << [node.object_id, definition_line] unless
        deferred || unreachable[definition_line]
    end

    call = ruby_direct_method_call(node)
    next unless call

    name, call_line = call
    next if unreachable[call_line]
    next if ancestors.any? { |ancestor| %i[class module sclass defs lambda].include?(ancestor[0]) }

    enclosing_definitions = ancestors.select { |ancestor| ancestor[0] == :def }
    if enclosing_definitions.empty?
      top_level_calls << [name, call_line]
    elsif enclosing_definitions.length == 1
      method_calls[enclosing_definitions[0].object_id] << name
    end
  end

  reachable = {}
  pending = top_level_calls.filter_map do |name, entry_line|
    target = definitions[name].select { |_id, line| line < entry_line }.max_by(&:last)
    [target[0], entry_line] if target
  end
  visited = {}

  until pending.empty?
    definition_id, entry_line = pending.shift
    next if visited[[definition_id, entry_line]]

    visited[[definition_id, entry_line]] = true
    reachable[definition_id] = true
    method_calls[definition_id].each do |name|
      target = definitions[name].select { |_id, line| line < entry_line }.max_by(&:last)
      pending << [target[0], entry_line] if target
    end
  end

  reachable
end

def ruby_direct_lambda_receiver(receiver)
  candidate = receiver
  loop do
    return candidate if candidate.is_a?(Array) && candidate[0] == :lambda
    return unless candidate.is_a?(Array) && candidate[0] == :paren
    return unless candidate[1].is_a?(Array) && candidate[1].length == 1

    candidate = candidate[1][0]
  end
end

def ruby_lambda_invocations(ast, unreachable)
  bindings = {}
  assignments = Hash.new { |hash, key| hash[key] = [] }
  invocation_lines = Hash.new { |hash, key| hash[key] = [] }
  invoked_lambdas = {}
  reachable_methods = ruby_reachable_method_definition_ids(ast, unreachable)

  ruby_ast_each_with_ancestors(ast) do |node, ancestors|
    enclosing_scope = ancestors.reverse.find do |ancestor|
      %i[lambda def defs].include?(ancestor[0])
    end
    scope_id = enclosing_scope&.object_id

    if node[0] == :assign
      name = ruby_local_name(node[1], :var_field)
      if name
        assignment_line = node[1][1][2][0]
        next if unreachable[assignment_line]

        assignments[[scope_id, name]] << assignment_line
        bindings[node[2].object_id] = [scope_id, name, assignment_line] if
          node[2].is_a?(Array) && node[2][0] == :lambda
      end
    end

    next unless node[0] == :call
    next unless node[3].is_a?(Array) && node[3][0] == :@ident && node[3][1] == "call"
    next if unreachable[node[3][2][0]]
    next if ancestors.any? { |ancestor| ancestor[0] == :lambda }
    next if enclosing_scope&.first == :defs
    next if enclosing_scope&.first == :def && !reachable_methods[scope_id]

    receiver = node[1]
    name = ruby_local_name(receiver, :var_ref)
    invocation_lines[[scope_id, name]] << node[3][2][0] if name
    direct_lambda = ruby_direct_lambda_receiver(receiver)
    invoked_lambdas[direct_lambda.object_id] = true if direct_lambda
  end

  bindings.each do |lambda_id, (scope_id, name, binding_line)|
    key = [scope_id, name]
    next_assignment = assignments[key].select { |line| line > binding_line }.min
    called = invocation_lines[key].any? do |line|
      line > binding_line && (next_assignment.nil? || line < next_assignment)
    end
    invoked_lambdas[lambda_id] = true if called
  end

  invoked_lambdas
end

def ruby_unreachable_line_numbers(ast, code_lines)
  unreachable = {}

  ruby_ast_each(ast) do |node|
    case node[0]
    when :if, :elsif, :unless
      truthiness = ruby_condition_truthiness(node[1])
      body = node[2]
      alternate = node[3]
      positive_condition = %i[if elsif].include?(node[0])
      unreachable.merge!(ruby_dead_body_line_numbers(body, node[1], code_lines)) if
        (positive_condition && truthiness == :falsey) ||
        (node[0] == :unless && truthiness == :truthy)
      unreachable.merge!(ruby_dead_body_line_numbers(alternate, [node[1], body], code_lines)) if
        (positive_condition && truthiness == :truthy) ||
        (node[0] == :unless && truthiness == :falsey)
    when :if_mod, :unless_mod
      truthiness = ruby_condition_truthiness(node[1])
      statement = node[2]
      unreachable.merge!(ruby_ast_line_numbers(statement)) if
        (node[0] == :if_mod && truthiness == :falsey) ||
        (node[0] == :unless_mod && truthiness == :truthy)
    when :while
      unreachable.merge!(ruby_dead_body_line_numbers(node[2], node[1], code_lines)) if
        ruby_condition_truthiness(node[1]) == :falsey
    when :while_mod
      unreachable.merge!(ruby_ast_line_numbers(node[2])) if
        node[2][0] != :begin && ruby_condition_truthiness(node[1]) == :falsey
    when :until
      unreachable.merge!(ruby_dead_body_line_numbers(node[2], node[1], code_lines)) if
        ruby_condition_truthiness(node[1]) == :truthy
    when :until_mod
      unreachable.merge!(ruby_ast_line_numbers(node[2])) if
        node[2][0] != :begin && ruby_condition_truthiness(node[1]) == :truthy
    end
  end

  invoked_lambdas = ruby_lambda_invocations(ast, unreachable)
  ruby_ast_each(ast) do |node|
    next unless node[0] == :lambda
    next if invoked_lambdas[node.object_id]

    unreachable.merge!(ruby_dead_body_line_numbers(node[2], node[1], code_lines))
  end

  unreachable
end

def ruby_line_classification(body)
  code_lines = ruby_code_line_numbers(body)
  builder = PositionedRubySexpBuilder.new(body)
  ast = builder.parse
  return [code_lines, {}, false] if ast.nil? || builder.error?

  unreachable = ruby_unreachable_line_numbers(ast, code_lines)
  reachable = code_lines.reject { |line_number, _| unreachable[line_number] }
  [code_lines, reachable, true]
end

unresolved = []
malformed = []
locator_count = 0
# Advisory only. A `file:` locator whose target is an EXECUTABLE artifact asserts
# firing evidence that some runner reaches; when no entry point outside specs/ names
# that file, the anchor still resolves (the text is there) while nothing can run it.
# Observed 2026-08: ten locators across nine ledger rows anchored into an executable
# nothing runs, green
# for the whole life of the retirement. Prose anchors (.md) are a different class --
# they are read, not run -- and are deliberately NOT flagged.
unrunnable = []
skipped_runners = []
# Built once, lazily: a repo with no executable locators never pays for it, and a
# repo with many does not re-walk the tree per locator (O(locators x files)).
runner_corpus = nil
build_runner_corpus = lambda do |root|
  (Dir.glob(File.join(root, "**", "*.{sh,py,rb,yml,yaml}"), File::FNM_DOTMATCH) +
   Dir.glob(File.join(root, "**", "{Makefile,makefile}"), File::FNM_DOTMATCH)).reject do |cand|
    cand.start_with?(File.join(root, "specs") + File::SEPARATOR) ||
      cand.start_with?(File.join(root, ".git") + File::SEPARATOR) ||
      !File.file?(cand)
  end.filter_map do |cand|
    # An advisory must never change the exit status, so an unreadable candidate is
    # skipped rather than raised: one chmod-000 file in the tree previously took
    # the whole gate red with Errno::EACCES. Skipping biases toward silence on
    # that candidate, which is the safe direction for a non-blocking report.
    begin
      [cand, File.read(cand, encoding: "UTF-8", invalid: :replace)]
    rescue SystemCallError, IOError
      skipped_runners << cand
      nil
    end
  end
end
# Where each EXEMPT locator was actually cited. A waiver is written for ONE
# historical row that can no longer be repaired; a second row quoting the same
# retired locator is a new claim, not that row, and must not inherit the waiver.
# Counting uses is what makes that decidable without a row identity — the ledger
# is append-only and its line numbers shift, so nothing else is stable.
exempt_uses = {}
EXEMPT_USE_ALLOWANCE = 1
EXEMPT_ROW_DIGESTS = {
  "file:skills/code-review/references/development-completion.md#no further reviewer call when it only fixes findings below P0/P1" =>
    "73af10f3442cccb8ed9a0fd677317a7bef43770bd71adc2c91d3ccc756570b0e",
  "file:skills/skill-extraction-workflow/references/dual-track-review-gate.md#After five delta passes a still-open P0/P1" =>
    "44d4bf30abb863fd031f4bc47b12d1a3685062514ca3e344481f7faa1598bc5e",
  "file:skills/product-ui-ux-design/references/external-ui-ux-quality-benchmarks.md#Disabled semantics are real, not painted" =>
    "729839dab2f900b92a3f7e866eb6602eb5261c112d39973d9eb470a797f8ca41",
  "file:skills/product-ui-ux-design/references/external-ui-ux-quality-benchmarks.md#predictive-back geometry routes to" =>
    "6847e68f062c2fe65a32f34bc743a6162a4e245a3a5d858c020faa841868f929",
  "file:skills/product-ui-ux-design/references/external-ui-ux-quality-benchmarks.md#Interaction-state matrix is complete" =>
    "9671789a4bac36787dc26965ca03c98c7ab1c10de3312c6792587cb34e7c548e",
  "command:skills/skill-extraction-workflow/scripts/test_validate_extraction_review_state.sh" => [
    "da20ca2ada11f70a55bbfbffde84a80d0a8a8a46c9e4010a96a9614ca854fd34",
    "b8eede70a62910f0a7f2d11cfd854537c3450889bc294cfc933b37f2a13c55b8",
    "1c575fdad17f3fca00569832d487dcf0ac0f28fe5f8fb4bfa21e784d9111a243",
    "b40a21a554cbc8bb3484c345160403a69f1cfb0b41702559fc2442572f52afce",
    "0579ef1411fc866c0e612f9475634f073cfc0e0be429482ee9e8b4fd7abafe10"
  ],
  "command:skills/skill-extraction-workflow/scripts/test_review_ledger_binding.sh" => [
    "0579ef1411fc866c0e612f9475634f073cfc0e0be429482ee9e8b4fd7abafe10",
    "fdb08300002289dc5b3d0bcd279589ec8eca7dd5d3b14f0b7b079d34372b41f7",
    "4a593029ba36b128519adeb8a3b9cbee32053caec7953c884ad587efaf88a3aa",
    "f56d544525a45d0b26e8752eec4f2ff516239c3ca866df600506ea3ccb39f4b2",
    "6f3b518a04ea8c20adc1ec3cf377a7eda2ef775903354cf54bed59268a8332b4",
    "dfa47eac33add5ce0a7a73ce237b8bf4a1589bd325eb34b4531e25f9adbb574d",
    "c6e6f74ca2407db2d98124e0517e6d70fae6f9df669f190bb7336ab76f13eb56",
    "16f862e9df7fea0ea817e392e78e561690b0120f97125c2db5f7c7b987154385",
    "c450336b8031f4ea9b3a614db3908b1f21c37559098b4e24672947172bb42de4",
    "aaa569c4934575aae78c2a3901ef44696501ee56d0cb700bfa2559ac79677d6c",
    "a9a2484c102a9392ffa00edc684b8feddea9ccc6a881d35433c72594e72959c5",
    "f9cfc29b561d55da7838d371f1307bf015822bdea2961cfb6dd0b6da6232eede",
    "1e769efadec0325d53de5d0c1023eea675499d9d67b086bcfc4c507ca0f25dac",
    "749ef2d63c4dda83e3885b7c2dfaedc9f2970dc09ae310082ad5367bc322cebc",
    "2402bf5b6b7a00aba5e6200c47277bdf6bb65e4d255f8126b8615eb9d1168545",
    "7f68e4204587602d53d135152d9a0b4fa7e8da1cc0c43f02813debb8c3a99528",
    "0d7e1a6de3ced156e54b9a50737835f49c424846e86adf28f1b19a1aa46f0f5a",
    "2c894914dd47b1764c63bd525891246c8adcb14b0f00c446e84e28320451a213",
    "0ab74921c2222979701499bc12d53c5a0942f51a7b1dd3a090ef58e83cea42f9"
  ],
  "command:skills/skill-extraction-workflow/scripts/review_ledger_binding.py" =>
    "6216104a650a7c30f78d0163d0a7cde37c9d809eb5967f291a30ebd516b1e337",
  "file:skills/skill-extraction-workflow/references/dual-track-review-gate.md#Sum spent rounds across all chains before opening one more" =>
    "988cd8128ee6f93b4ea5a0cc8ada170401a1790831b2cd7b95a79642a76f1112",
  "file:skills/skill-extraction-workflow/references/dual-track-review-gate.md#accumulate every fix unapplied, run the challenge on the frozen" =>
    "d999fadd8e3778bfdb9d54d34d3cabf965547ed39448a6ffba5e8310ca151612",
  "file:skills/skill-extraction-workflow/references/extraction-quickstart.md#still owes the two-round chain before it can land" =>
    "bf1fa382021b079b200b6d8d367e407bd0adbbac1d862e22d78062d83906c05e",
  "file:skills/skill-extraction-workflow/references/extraction-quickstart.md#must exclude every evidence JSON the round has already added" =>
    "d762cbab094279d26461843dfe12c5dd28ae41a1e9a40b7ae9f7f806fee51c36",
  "command:skills/skill-extraction-workflow/scripts/check-parallel-stack-parity.sh" =>
    "4e476a5f137ec3add88696125b6eb0f6941afd388dd356bf129f28caa573e5a2",
  "file:skills/nodejs-service-dev/SKILL.md#Do not borrow the Go or Python architecture skill" =>
    "470e4e4c375afa3f5cce3be6d7e4899c3637b2954f20aacddaad2e7d4d3fef37",
  "file:skills/defect-diagnosis/SKILL.md#must not be filed under a sibling stack's architecture skill" =>
    "0976c129bfec4c415fc1a0e0e06ce59954bdac348b82363c61670d0daa5a0fdf",
  "file:skills/llm-inference-integration/SKILL.md#never to a Node architecture sibling" =>
    "fb4cf36af0fd812d9581129e8ac53ed4bc7fae17ab6b73ae209ca924eb49916c"
}.freeze
# TRUST BOUNDARY. The count answers "one row"; it cannot answer "WHICH row", so
# it is paired with the digest of the citing row in EXEMPT_ROW_DIGESTS above.
# An earlier version of this comment argued the opposite — that no stable
# identity exists because any candidate drifts or must be regenerated by the
# author it constrains. That was wrong for a digest specifically: the ledger is
# append-only, so rows added elsewhere do not change this line, and the failure
# this defends against is an accidental reflow or a repurposed row, which reds
# without anyone touching code.
# What it does NOT defend against is an author who edits EXEMPT and its digest
# together — a visible code change under normal review, the same posture the two
# legacy anchorless entries have carried since they landed.
fence = nil

File.foreach(register_path).with_index(1) do |line, lineno|
  # Same CommonMark rule as strip_fences: a naive boolean toggle would close a
  # ```` fence on an inner ``` run and then treat the REAL closing run as an
  # opener, silently skipping every live row after it.
  if (m = line.match(/\A\s{0,3}(`{3,}|~{3,})/))
    run = m[1]
    if fence.nil?
      fence = run
      next
    elsif run[0] == fence[0] && run.length >= fence.length
      fence = nil
      next
    end
  end
  # Only table rows carry declarations; fenced examples and narrative prose do
  # not, and treating a documentation example as a live locator would be an
  # unrepairable false positive.
  next unless fence.nil?
  next unless line.start_with?("|")

  # `(?<!`)` skips an inline-code mention such as `` `firing-path:` `` — that is
  # prose ABOUT the key (this file's own methodology rows do it), not a
  # declaration, and must not be demanded to yield a locator.
  line.scan(/(?<!`)firing-path:\s*([^|;]*)/) do |(value)|
    locators = value.split(/,(?=\s*(?:file|command):)/)
                    .map(&:strip)
                    .select { |l| l.start_with?("file:", "command:") }

    # A declaration that parses to nothing is not "clean" — it is a row whose
    # firing evidence this gate silently failed to check.
    if locators.empty?
      malformed << [lineno, value.strip]
      next
    end

    locators.each do |locator|
      locator_count += 1
      anchor_waived = EXEMPT.key?(locator)
      if anchor_waived
        exempt_uses[locator] ||= []
        exempt_uses[locator] << lineno
      end

      kind, _, rest = locator.partition(":")
      if kind == "command"
        rel = rest.strip
        target = File.join(root, rel)
        if !syntactically_contained?(rel)
          unresolved << [lineno, locator, "path escapes the repository"]
        elsif !File.file?(target) && anchor_waived
          # A waived command locator names an executable a superseding round
          # deliberately retired; its absence is the recorded retirement, and the
          # digest check below still pins which historical rows may cite it.
          next
        elsif !File.file?(target)
          unresolved << [lineno, locator, "executable not found"]
        elsif !resolves_inside?(root, rel)
          unresolved << [lineno, locator, "path escapes the repository"]
        elsif !File.executable?(target)
          unresolved << [lineno, locator, "not executable"]
        end
      else
        rel, _, anchor = rest.partition("#")
        rel = rel.strip
        anchor = anchor.strip
        if anchor.empty? && !anchor_waived
          unresolved << [lineno, locator, "file locator carries no #anchor"]
          next
        end
        if (moved_to = moved_paths[rel])
          moved_uses[rel] += 1
          if File.exist?(File.join(root, rel))
            unresolved << [lineno, locator, "moved-path entry is stale: #{rel} exists again, so the recorded " \
                                            "relocation is ambiguous — retire the entry or remove the old file"]
            next
          end
          moved_lookups[[lineno, locator]] = moved_to
          rel = moved_to
        end
        target = File.join(root, rel)
        if !syntactically_contained?(rel)
          unresolved << [lineno, locator, "path escapes the repository"]
          next
        end
        if !File.file?(target)
          unresolved << [lineno, locator, "file not found"]
          next
        end
        if %w[.rb .sh .py].include?(File.extname(rel)) && !anchor_waived
          # Match the basename WITH its extension at a non-word boundary. The
          # stripped stem matched anywhere was trivially satisfiable: `run.sh`
          # became `run`, which any `run_tests` identifier or prose mention
          # cleared, so a decayed anchor read as reachable and this stayed quiet.
          # Reachability is either a literal mention of the file, or a runner
          # that sweeps its directory with a wildcard -- `for t in dir/*.sh` names
          # no basename yet fires every file there. Missing the second shape is a
          # FALSE ALARM on a live locator, which the acceptance bars, so both count.
          needle = /(?<![\w.-])#{Regexp.escape(File.basename(rel))}(?![\w-])/
          dirn = File.dirname(rel)
          sweep = /#{Regexp.escape(dirn)}\/[^\s"']*[*?]/
          # FNM_DOTMATCH is required, not cosmetic: the yml/yaml shapes this glob
          # seeks live in .github/workflows, and without it the glob never
          # descends there -- a target fired only by CI read as unrunnable.
          runner_corpus ||= build_runner_corpus.call(root)
          reachable = runner_corpus.any? do |cand, body|
            next false if File.identical?(cand, target)
            body.match?(needle) || body.match?(sweep)
          end
          unrunnable << [lineno, locator, rel] unless reachable
        end
        if !resolves_inside?(root, rel)
          unresolved << [lineno, locator, "path escapes the repository"]
          next
        end

        next if anchor.empty? # exempt legacy locator: existence checked above
        # An EXEMPT entry that names the anchor waives the anchor-CONTENT check
        # as well: the rule was deliberately relocated, so the recorded text
        # will never sit at this path again and the append-only row cannot be
        # repaired. File existence (checked above) still applies, so deleting or
        # renaming the target still reds, and the use-count check below stops a
        # NEW row from inheriting the waiver by quoting the retired locator.
        next if anchor_waived

        raw_body = File.read(target)
        body = strip_fences(raw_body)
        if anchor.start_with?("line-sha256:")
          encoded_line_sha256 = anchor.delete_prefix("line-sha256:")
          expected_line_sha256 = encoded_line_sha256.delete("-")
          unless expected_line_sha256.match?(/\A[0-9a-f]{64}\z/)
            unresolved << [lineno, locator, "line-sha256 anchor is not 64 lowercase hex characters after grouping"]
            next
          end

          unless File.extname(target) == ".rb"
            unresolved << [lineno, locator, "line-sha256 target language has no code-token classifier"]
            next
          end

          ruby_code_lines, ruby_reachable_lines, ruby_parsed = ruby_line_classification(raw_body)
          digest_lines = raw_body.each_line.with_index(1).filter_map do |source_line, line_number|
            normalized_line = source_line.strip
            next if normalized_line.empty?
            next unless Digest::SHA256.hexdigest(normalized_line) == expected_line_sha256

            line_number
          end
          next if digest_lines.any? { |line_number| ruby_reachable_lines[line_number] }

          if digest_lines.any? { |line_number| ruby_code_lines[line_number] }
            reason = if ruby_parsed
                       "line-sha256 source line is not statically reachable"
                     else
                       "line-sha256 target Ruby did not parse"
                     end
            unresolved << [lineno, locator, reason]
            next
          end

          unresolved << [lineno, locator, "line-sha256 source line absent from target"]
          next
        end
        next if body.include?(anchor)
        next if heading_slugs(body).include?(anchor.downcase)

        unresolved << [lineno, locator, "anchor text absent from target"]
      end
    end
  end
end

# Over-use of a waiver is a violation, reported against the EXTRA citations only
# (the first use is the historical row the waiver was written for). Reporting
# every use would red the legitimate row and leave no repair path in an
# append-only ledger.
# Over-use of a waiver is a violation, reported against the EXTRA rows only
# (the first row is the historical one the waiver was written for). Reporting
# every use would red the legitimate row and leave no repair path in an
# append-only ledger. Distinct ROWS, not raw citations: one row that happens to
# name the same retired locator twice is still that one unrepairable row, and
# counting citations would false-red it.
register_lines = File.readlines(register_path)
# The digest table is INJECTED, not self-calibrated. An earlier version enabled
# the layer only once some recorded row still matched, so that a synthetic
# fixture ledger would not red — but that made "rewrite every waived row at
# once" disable the whole layer, which is precisely the case it should catch.
# Production takes the built-in table and enforces it unconditionally; a test or
# a repository vendoring this gate supplies its own table (an empty one means it
# binds no waivers). Injection is a declared seam, visible in the environment and
# never set in CI, rather than an inference the gate makes about which ledger it
# is looking at.
digest_table_path = ENV["REGISTER_FIRING_PATH_EXEMPT_DIGESTS"].to_s
exempt_row_digests =
  if digest_table_path.empty?
    EXEMPT_ROW_DIGESTS
  else
    begin
      parsed = JSON.parse(File.read(digest_table_path))
      raise TypeError, "not an object" unless parsed.is_a?(Hash)
      parsed
    rescue StandardError => e
      warn "register_firing_path_exempt_digest_table_unreadable: #{digest_table_path}: #{e.message}"
      exit 2
    end
  end
# The seam is usable but never silent: an injected table can only ever be weaker
# than the built-in one for this ledger, so a run that used it is not a clean
# landing — including the case where a test environment leaks into a real run.
# The caller keys off this line and downgrades to interim; without it the seam
# would be a quiet bypass of the digest and missing-row layers.
unless digest_table_path.empty?
  puts "register_firing_path_exempt_digests_injected: #{digest_table_path} " \
       "(built-in waiver-row bindings not enforced; this run is interim, not clean-landing)"
end
# Iterate the EXPECTED entries, not only the ones still cited: a waived row that
# was DELETED leaves its locator out of `exempt_uses` entirely, so a loop over
# observed uses would never look at it and the run would report success while a
# recorded historical row silently vanished. Only meaningful once the digest
# layer is calibrated to this ledger; on a foreign register every entry is
# legitimately uncited.
exempt_row_digests.each_key do |locator|
  next unless (exempt_uses[locator] || []).empty?
  unresolved << [1, locator,
                 "EXEMPT entry has no citing row in the ledger; the waived historical row was deleted " \
                 "or its locator was edited, so the waiver now covers nothing — restore the row, or " \
                 "retire the EXEMPT entry and its digest in the same change"]
end

exempt_uses.each do |locator, linenos|
  rows = linenos.uniq.sort
  # A waiver binds either one row (a digest string) or a fixed set of rows (an
  # array of digests): a retired script or rule that several historical rows
  # cited is still one retirement, and each of those rows is named by its digest.
  expected = exempt_row_digests[locator]
  expected_digests = expected.is_a?(Array) ? expected : [expected].compact
  # How many rows a waiver covers is a property of the waiver, so it is read from
  # the built-in table even when a test injects its own identity table.
  builtin = EXEMPT_ROW_DIGESTS[locator]
  builtin_rows = builtin.is_a?(Array) ? builtin.length : (builtin ? 1 : 0)
  allowance = [expected_digests.length, builtin_rows, EXEMPT_USE_ALLOWANCE].max
  if rows.length > allowance
    rows.drop(allowance).each do |lineno|
      unresolved << [lineno, locator,
                     "EXEMPT locator cited by #{rows.length} rows (allowance #{allowance}); " \
                     "a waiver covers the recorded historical rows starting at line #{rows.first}, " \
                     "not a new row quoting the same retired locator"]
    end
    next
  end
  # The count says how many rows; the digests say WHICH rows. Without them,
  # deleting a historical row and writing a different claim that cites the same
  # locator keeps the count and silently inherits the waiver.
  if expected_digests.empty?
    # A waiver with no recorded row identity keeps only the use-count layer,
    # which cannot tell a rewritten or repurposed row from the one that was
    # waived. On the BUILT-IN table that is a silent downgrade, so a new EXEMPT
    # entry added without its digest fails here rather than quietly landing
    # weaker than its siblings. An INJECTED table is the injector's declaration
    # about its own ledger — the missing binding is the point, and that run is
    # already downgraded to interim by the announcement above.
    if digest_table_path.empty?
      unresolved << [rows.first, locator,
                     "EXEMPT entry has no recorded citing-row digest; every waiver must bind the row it " \
                     "covers — add the row's SHA-256 to EXEMPT_ROW_DIGESTS in the same change"]
    end
    next
  end
  remaining = expected_digests.tally
  mismatched = 0
  rows.each do |lineno|
    actual = Digest::SHA256.hexdigest(register_lines[lineno - 1].to_s.rstrip)
    if remaining[actual].to_i.positive?
      remaining[actual] -= 1
      next
    end
    mismatched += 1
    unresolved << [lineno, locator,
                   "EXEMPT citing row does not match the waived row (digest #{actual[0, 12]} not recorded); " \
                   "a waiver covers specific unrepairable historical rows, so a rewritten or replaced row " \
                   "does not inherit it — restore the row, or land a new waiver entry with its own digest and reason"]
  end
  # A rewritten row is already reported above; only rows that are gone entirely
  # are left to name here.
  missing = remaining.values.sum - mismatched
  next unless missing.positive?
  unresolved << [rows.first, locator,
                 "EXEMPT entry has no citing row in the ledger for #{missing} of its #{expected_digests.length} " \
                 "recorded rows; a waived historical row was deleted or its locator was edited — restore the row, " \
                 "or retire its digest in the same change"]
end

# A moved-path entry nothing cites is dead configuration: either the row it served
# was deleted from an append-only ledger, or the entry was added speculatively.
moved_paths.each_key do |old_rel|
  next if moved_uses[old_rel].positive?

  unresolved << [0, "file:#{old_rel}",
                 "moved-path entry has no citing row in the ledger; retire the entry in the same change"]
end

# Both groups print before exiting. Bailing out on `malformed` alone would hide
# every unresolved locator and every EXEMPT over-use in the same run, so a fixer
# would have to rerun the gate once per class to discover them.
unless malformed.empty?
  warn "register_firing_path_malformed: a firing-path declaration parsed to zero locators"
  warn "  cause: the value is not `file:<repo-relative path>#<anchor>` or `command:<repo-relative path>`."
  warn "         An anchor containing `;` or `|` is truncated by the cell grammar — reword it."
  malformed.each { |lineno, value| warn "  #{REGISTER}:#{lineno}: #{value.inspect}" }
end

unless unresolved.empty?
  warn "register_firing_path_unresolved: a recorded firing path no longer resolves"
  warn "  cause: the anchored rule was moved, reworded, or deleted after its row landed,"
  warn "         so that row now asserts firing evidence that does not exist."
  warn "  fix: restore the anchored text at its recorded location, or (when the move was"
  warn "       intended) append a superseding row and add the old locator to EXEMPT with a reason."
  unresolved.each do |lineno, locator, why|
    looked_at = moved_lookups[[lineno, locator]]
    where = looked_at ? " (relocated; looked at #{looked_at})" : ""
    warn "  #{REGISTER}:#{lineno}: #{why}: #{locator}#{where}"
  end
end

unless unrunnable.empty?
  warn "register_firing_path_unrunnable_target: ADVISORY -- an anchored executable has no runner"
  warn "  cause: the anchor resolves (its text is present) but no entry point outside specs/"
  warn "         names that file, so nothing can execute what the row claims fires."
  warn "  fix: point the row at a live command, or supersede it if the mechanism retired."
  unrunnable.each do |lineno, locator, rel|
    warn "  #{REGISTER}:#{lineno}: #{rel}"
    anchor = locator.split("#", 2)[1]
    warn "      anchor: #{anchor}" if anchor && !anchor.empty?
  end
  warn "  covered runner shapes: *.{sh,py,rb,yml,yaml} and **/{Makefile,makefile} outside specs/ and .git/,"
  warn "    matched by literal basename or by a wildcard sweep over the target's directory. NOT covered:"
  warn "    Rakefiles, extensionless bin scripts, and `find <dir> -name` style invocation — a target fired"
  warn "    only through those reads as unrunnable here."
  unless skipped_runners.empty?
    warn "  #{skipped_runners.size} candidate(s) were unreadable and skipped; if a named row is fired only by"
    warn "    one of those, this report is a false alarm rather than a decayed anchor."
  end
  warn "  advisory only: this never changes the exit status."
end

exit 1 unless malformed.empty? && unresolved.empty?

# NO zero-locator self-check here, deliberately. Two rounds of it each shipped a
# false RED: as a caller-side non-zero floor it red a legitimately
# declaration-free register, and as a marker count here it red a register whose
# only declaration-looking row was a fenced example — because any oracle cheap
# enough to be independent of the row/cell parser is also too cheap to tell a
# live declaration from an illustration of one, and any oracle that CAN tell
# them apart has re-implemented the parser it was meant to check.
# The threat it chased is "the parser stopped recognizing the ledger", which is
# a code defect in this file, caught by the resolution suite's own RED cases
# (an anchor mutation must turn the gate red) rather than by the gate grading
# its own eyesight at runtime.

# Visibility only, and printed BEFORE the terminal line: the checker's contract is
# that the last non-empty stdout line is the ok token in its exact shape.
moved_total = moved_uses.values.sum
puts "register_firing_path_moved_paths_used: #{moved_total}" if moved_total.positive?
puts "register_firing_path_resolution_ok (#{locator_count} locators resolved)"
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall