Auto-Fix Engine & Remediation DAG (pkg/systemcheck/autofix)

pkg/systemcheck/autofix provides the decoupled auto-fix rule loading, template placeholder substitution, and hierarchical remediation dependency ordering for ZQK system checks and validation pipelines.

Responsibilities

1. AutoFixRuleLoader: - Lazily loads and caches auto_fix_rule objects per project root from the storage provider. - Evaluates rule applicability based on target object kind, category, condition tier, specific rule identifier, and error message substrings. - Performs template placeholder substitution (e.g. {object_id}, {field}, {kind}, {message}, {rule}, {tier}, {category}). - Deterministically selects the highest priority rule (lowest numerical value) when multiple matching rules are found. - Supports thread-safe cache invalidation per project root.

2. Hierarchical Remediation DAG (FixDependencyOrder): - Defines the ontological dependency hierarchy for reference repairs:

   • goal_refs (Priority 4): Goals are root objects with fewest dependencies.
   • priority_plan_ref (Priority 3): Priority plans structure program delivery.
   • milestone_refs / workstream_refs (Priority 2): Milestones and workstreams depend on plans/goals.
   • backlog_item_refs (Priority 1): Backlog items depend on milestones, plans, and goals.
   • Sorts validation issues so that upstream root entities are remediated before downstream dependent entities, avoiding thrashing and cascade failures.
   • Secondary sorting orders by severity tier (Tier 1 blocking issues before Tier 2 warnings).

Usage

import "github.com/zqk-os/zqk/pkg/systemcheck/autofix"

// Lookup singleton rule loader
loader := autofix.GetAutoFixRuleLoader()

// Match fix command for an issue
cmd, ok := loader.GetFixCommand(
    projectRoot,
    storageProvider,
    kind,
    category,
    tier,
    rule,
    message,
    objID,
    field,
    objMap,
)

// Sort issues by dependency hierarchy
sorted := autofix.SortIssuesByDependency(issues)