Restructure solution layout by module

src/Policy/__Libraries/StellaOps.Policy/AGENTS.md

@@ -0,0 +1,12 @@
+# StellaOps.Policy — Agent Charter
+
+## Mission
+Deliver the policy engine outlined in `docs/ARCHITECTURE_SCANNER.md` and related prose:
+- Define YAML schema (ignore rules, VEX inclusion/exclusion, vendor precedence, license gates).
+- Provide policy snapshot storage with revision digests and diagnostics.
+- Offer preview APIs to compare policy impacts on existing reports.
+
+## Expectations
+- Coordinate with Scanner.WebService, Feedser, Vexer, UI, Notify.
+- Maintain deterministic serialization and unit tests for precedence rules.
+- Update `TASKS.md` and broadcast contract changes.

src/Policy/__Libraries/StellaOps.Policy/Audit/IPolicyAuditRepository.cs

@@ -0,0 +1,12 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Policy;
+
+public interface IPolicyAuditRepository
+{
+    Task AddAsync(PolicyAuditEntry entry, CancellationToken cancellationToken = default);
+
+    Task<IReadOnlyList<PolicyAuditEntry>> ListAsync(int limit, CancellationToken cancellationToken = default);
+}

src/Policy/__Libraries/StellaOps.Policy/Audit/InMemoryPolicyAuditRepository.cs

@@ -0,0 +1,52 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Policy;
+
+public sealed class InMemoryPolicyAuditRepository : IPolicyAuditRepository
+{
+    private readonly List<PolicyAuditEntry> _entries = new();
+    private readonly SemaphoreSlim _mutex = new(1, 1);
+
+    public async Task AddAsync(PolicyAuditEntry entry, CancellationToken cancellationToken = default)
+    {
+        if (entry is null)
+        {
+            throw new ArgumentNullException(nameof(entry));
+        }
+
+        await _mutex.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            _entries.Add(entry);
+            _entries.Sort(static (left, right) => left.CreatedAt.CompareTo(right.CreatedAt));
+        }
+        finally
+        {
+            _mutex.Release();
+        }
+    }
+
+    public async Task<IReadOnlyList<PolicyAuditEntry>> ListAsync(int limit, CancellationToken cancellationToken = default)
+    {
+        await _mutex.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            IEnumerable<PolicyAuditEntry> query = _entries;
+            if (limit > 0)
+            {
+                query = query.TakeLast(limit);
+            }
+
+            return query.ToImmutableArray();
+        }
+        finally
+        {
+            _mutex.Release();
+        }
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyAuditEntry.cs

@@ -0,0 +1,12 @@
+using System;
+
+namespace StellaOps.Policy;
+
+public sealed record PolicyAuditEntry(
+    Guid Id,
+    DateTimeOffset CreatedAt,
+    string Action,
+    string RevisionId,
+    string Digest,
+    string? Actor,
+    string Message);

src/Policy/__Libraries/StellaOps.Policy/PolicyDiagnostics.cs

@@ -0,0 +1,77 @@
+using System;
+using System.Collections.Immutable;
+using System.Linq;
+
+namespace StellaOps.Policy;
+
+public sealed record PolicyDiagnosticsReport(
+    string Version,
+    int RuleCount,
+    int ErrorCount,
+    int WarningCount,
+    DateTimeOffset GeneratedAt,
+    ImmutableArray<PolicyIssue> Issues,
+    ImmutableArray<string> Recommendations);
+
+public static class PolicyDiagnostics
+{
+    public static PolicyDiagnosticsReport Create(PolicyBindingResult bindingResult, TimeProvider? timeProvider = null)
+    {
+        if (bindingResult is null)
+        {
+            throw new ArgumentNullException(nameof(bindingResult));
+        }
+
+        var time = (timeProvider ?? TimeProvider.System).GetUtcNow();
+        var errorCount = bindingResult.Issues.Count(static issue => issue.Severity == PolicyIssueSeverity.Error);
+        var warningCount = bindingResult.Issues.Count(static issue => issue.Severity == PolicyIssueSeverity.Warning);
+
+        var recommendations = BuildRecommendations(bindingResult.Document, errorCount, warningCount);
+
+        return new PolicyDiagnosticsReport(
+            bindingResult.Document.Version,
+            bindingResult.Document.Rules.Length,
+            errorCount,
+            warningCount,
+            time,
+            bindingResult.Issues,
+            recommendations);
+    }
+
+    private static ImmutableArray<string> BuildRecommendations(PolicyDocument document, int errorCount, int warningCount)
+    {
+        var messages = ImmutableArray.CreateBuilder<string>();
+
+        if (errorCount > 0)
+        {
+            messages.Add("Resolve policy errors before promoting the revision; fallback rules may be applied while errors remain.");
+        }
+
+        if (warningCount > 0)
+        {
+            messages.Add("Review policy warnings and ensure intentional overrides are documented.");
+        }
+
+        if (document.Rules.Length == 0)
+        {
+            messages.Add("Add at least one policy rule to enforce gating logic.");
+        }
+
+        var quietRules = document.Rules
+            .Where(static rule => rule.Action.Quiet)
+            .Select(static rule => rule.Name)
+            .ToArray();
+
+        if (quietRules.Length > 0)
+        {
+            messages.Add($"Quiet rules detected ({string.Join(", ", quietRules)}); verify scoring behaviour aligns with expectations.");
+        }
+
+        if (messages.Count == 0)
+        {
+            messages.Add("Policy validated successfully; no additional action required.");
+        }
+
+        return messages.ToImmutable();
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyDigest.cs

@@ -0,0 +1,304 @@
+using System;
+using System.Buffers;
+using System.Collections.Immutable;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text.Json;
+
+namespace StellaOps.Policy;
+
+public static class PolicyDigest
+{
+    public static string Compute(PolicyDocument document)
+    {
+        if (document is null)
+        {
+            throw new ArgumentNullException(nameof(document));
+        }
+
+        var buffer = new ArrayBufferWriter<byte>();
+        using (var writer = new Utf8JsonWriter(buffer, new JsonWriterOptions
+        {
+            SkipValidation = true,
+        }))
+        {
+            WriteDocument(writer, document);
+        }
+
+        var hash = SHA256.HashData(buffer.WrittenSpan);
+        return Convert.ToHexString(hash).ToLowerInvariant();
+    }
+
+    private static void WriteDocument(Utf8JsonWriter writer, PolicyDocument document)
+    {
+        writer.WriteStartObject();
+        writer.WriteString("version", document.Version);
+
+        if (!document.Metadata.IsEmpty)
+        {
+            writer.WritePropertyName("metadata");
+            writer.WriteStartObject();
+            foreach (var pair in document.Metadata.OrderBy(static kvp => kvp.Key, StringComparer.Ordinal))
+            {
+                writer.WriteString(pair.Key, pair.Value);
+            }
+            writer.WriteEndObject();
+        }
+
+        writer.WritePropertyName("rules");
+        writer.WriteStartArray();
+        foreach (var rule in document.Rules)
+        {
+            WriteRule(writer, rule);
+        }
+        writer.WriteEndArray();
+
+        if (!document.Exceptions.Effects.IsDefaultOrEmpty || !document.Exceptions.RoutingTemplates.IsDefaultOrEmpty)
+        {
+            writer.WritePropertyName("exceptions");
+            writer.WriteStartObject();
+
+            if (!document.Exceptions.Effects.IsDefaultOrEmpty)
+            {
+                writer.WritePropertyName("effects");
+                writer.WriteStartArray();
+                foreach (var effect in document.Exceptions.Effects
+                             .OrderBy(static e => e.Id, StringComparer.Ordinal))
+                {
+                    WriteExceptionEffect(writer, effect);
+                }
+
+                writer.WriteEndArray();
+            }
+
+            if (!document.Exceptions.RoutingTemplates.IsDefaultOrEmpty)
+            {
+                writer.WritePropertyName("routingTemplates");
+                writer.WriteStartArray();
+                foreach (var template in document.Exceptions.RoutingTemplates
+                             .OrderBy(static t => t.Id, StringComparer.Ordinal))
+                {
+                    WriteExceptionRoutingTemplate(writer, template);
+                }
+
+                writer.WriteEndArray();
+            }
+
+            writer.WriteEndObject();
+        }
+
+        writer.WriteEndObject();
+        writer.Flush();
+    }
+
+    private static void WriteRule(Utf8JsonWriter writer, PolicyRule rule)
+    {
+        writer.WriteStartObject();
+        writer.WriteString("name", rule.Name);
+
+        if (!string.IsNullOrWhiteSpace(rule.Identifier))
+        {
+            writer.WriteString("id", rule.Identifier);
+        }
+
+        if (!string.IsNullOrWhiteSpace(rule.Description))
+        {
+            writer.WriteString("description", rule.Description);
+        }
+
+        WriteMetadata(writer, rule.Metadata);
+        WriteSeverities(writer, rule.Severities);
+        WriteStringArray(writer, "environments", rule.Environments);
+        WriteStringArray(writer, "sources", rule.Sources);
+        WriteStringArray(writer, "vendors", rule.Vendors);
+        WriteStringArray(writer, "licenses", rule.Licenses);
+        WriteStringArray(writer, "tags", rule.Tags);
+
+        if (!rule.Match.IsEmpty)
+        {
+            writer.WritePropertyName("match");
+            writer.WriteStartObject();
+            WriteStringArray(writer, "images", rule.Match.Images);
+            WriteStringArray(writer, "repositories", rule.Match.Repositories);
+            WriteStringArray(writer, "packages", rule.Match.Packages);
+            WriteStringArray(writer, "purls", rule.Match.Purls);
+            WriteStringArray(writer, "cves", rule.Match.Cves);
+            WriteStringArray(writer, "paths", rule.Match.Paths);
+            WriteStringArray(writer, "layerDigests", rule.Match.LayerDigests);
+            WriteStringArray(writer, "usedByEntrypoint", rule.Match.UsedByEntrypoint);
+            writer.WriteEndObject();
+        }
+
+        WriteAction(writer, rule.Action);
+
+        if (rule.Expires is DateTimeOffset expires)
+        {
+            writer.WriteString("expires", expires.ToUniversalTime().ToString("O"));
+        }
+
+        if (!string.IsNullOrWhiteSpace(rule.Justification))
+        {
+            writer.WriteString("justification", rule.Justification);
+        }
+
+        writer.WriteEndObject();
+    }
+
+    private static void WriteAction(Utf8JsonWriter writer, PolicyAction action)
+    {
+        writer.WritePropertyName("action");
+        writer.WriteStartObject();
+        writer.WriteString("type", action.Type.ToString().ToLowerInvariant());
+
+        if (action.Quiet)
+        {
+            writer.WriteBoolean("quiet", true);
+        }
+
+        if (action.Ignore is { } ignore)
+        {
+            if (ignore.Until is DateTimeOffset until)
+            {
+                writer.WriteString("until", until.ToUniversalTime().ToString("O"));
+            }
+
+            if (!string.IsNullOrWhiteSpace(ignore.Justification))
+            {
+                writer.WriteString("justification", ignore.Justification);
+            }
+        }
+
+        if (action.Escalate is { } escalate)
+        {
+            if (escalate.MinimumSeverity is { } severity)
+            {
+                writer.WriteString("severity", severity.ToString());
+            }
+
+            if (escalate.RequireKev)
+            {
+                writer.WriteBoolean("kev", true);
+            }
+
+            if (escalate.MinimumEpss is double epss)
+            {
+                writer.WriteNumber("epss", epss);
+            }
+        }
+
+        if (action.RequireVex is { } requireVex)
+        {
+            WriteStringArray(writer, "vendors", requireVex.Vendors);
+            WriteStringArray(writer, "justifications", requireVex.Justifications);
+        }
+
+        writer.WriteEndObject();
+    }
+
+    private static void WriteMetadata(Utf8JsonWriter writer, ImmutableDictionary<string, string> metadata)
+    {
+        if (metadata.IsEmpty)
+        {
+            return;
+        }
+
+        writer.WritePropertyName("metadata");
+        writer.WriteStartObject();
+        foreach (var pair in metadata.OrderBy(static kvp => kvp.Key, StringComparer.Ordinal))
+        {
+            writer.WriteString(pair.Key, pair.Value);
+        }
+        writer.WriteEndObject();
+    }
+
+    private static void WriteSeverities(Utf8JsonWriter writer, ImmutableArray<PolicySeverity> severities)
+    {
+        if (severities.IsDefaultOrEmpty)
+        {
+            return;
+        }
+
+        writer.WritePropertyName("severity");
+        writer.WriteStartArray();
+        foreach (var severity in severities)
+        {
+            writer.WriteStringValue(severity.ToString());
+        }
+        writer.WriteEndArray();
+    }
+
+    private static void WriteStringArray(Utf8JsonWriter writer, string propertyName, ImmutableArray<string> values)
+    {
+        if (values.IsDefaultOrEmpty)
+        {
+            return;
+        }
+
+        writer.WritePropertyName(propertyName);
+        writer.WriteStartArray();
+        foreach (var value in values)
+        {
+            writer.WriteStringValue(value);
+        }
+        writer.WriteEndArray();
+    }
+
+    private static void WriteExceptionEffect(Utf8JsonWriter writer, PolicyExceptionEffect effect)
+    {
+        writer.WriteStartObject();
+        writer.WriteString("id", effect.Id);
+
+        if (!string.IsNullOrWhiteSpace(effect.Name))
+        {
+            writer.WriteString("name", effect.Name);
+        }
+
+        writer.WriteString("effect", effect.Effect.ToString().ToLowerInvariant());
+
+        if (effect.DowngradeSeverity is { } downgradeSeverity)
+        {
+            writer.WriteString("downgradeSeverity", downgradeSeverity.ToString());
+        }
+
+        if (!string.IsNullOrWhiteSpace(effect.RequiredControlId))
+        {
+            writer.WriteString("requiredControlId", effect.RequiredControlId);
+        }
+
+        if (!string.IsNullOrWhiteSpace(effect.RoutingTemplate))
+        {
+            writer.WriteString("routingTemplate", effect.RoutingTemplate);
+        }
+
+        if (effect.MaxDurationDays is int maxDurationDays)
+        {
+            writer.WriteNumber("maxDurationDays", maxDurationDays);
+        }
+
+        if (!string.IsNullOrWhiteSpace(effect.Description))
+        {
+            writer.WriteString("description", effect.Description);
+        }
+
+        writer.WriteEndObject();
+    }
+
+    private static void WriteExceptionRoutingTemplate(Utf8JsonWriter writer, PolicyExceptionRoutingTemplate template)
+    {
+        writer.WriteStartObject();
+        writer.WriteString("id", template.Id);
+        writer.WriteString("authorityRouteId", template.AuthorityRouteId);
+
+        if (template.RequireMfa)
+        {
+            writer.WriteBoolean("requireMfa", true);
+        }
+
+        if (!string.IsNullOrWhiteSpace(template.Description))
+        {
+            writer.WriteString("description", template.Description);
+        }
+
+        writer.WriteEndObject();
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyDocument.cs

@@ -0,0 +1,241 @@
+using System;
+using System.Collections.Immutable;
+using System.Linq;
+
+namespace StellaOps.Policy;
+
+/// <summary>
+/// Canonical representation of a StellaOps policy document.
+/// </summary>
+public sealed record PolicyDocument(
+    string Version,
+    ImmutableArray<PolicyRule> Rules,
+    ImmutableDictionary<string, string> Metadata,
+    PolicyExceptionConfiguration Exceptions)
+{
+    public static PolicyDocument Empty { get; } = new(
+        PolicySchema.CurrentVersion,
+        ImmutableArray<PolicyRule>.Empty,
+        ImmutableDictionary<string, string>.Empty,
+        PolicyExceptionConfiguration.Empty);
+}
+
+public static class PolicySchema
+{
+    public const string SchemaId = "https://schemas.stella-ops.org/policy/policy-schema@1.json";
+    public const string CurrentVersion = "1.0";
+
+    public static PolicyDocumentFormat DetectFormat(string fileName)
+    {
+        if (fileName is null)
+        {
+            throw new ArgumentNullException(nameof(fileName));
+        }
+
+        var lower = fileName.Trim().ToLowerInvariant();
+        if (lower.EndsWith(".yaml", StringComparison.Ordinal)
+            || lower.EndsWith(".yml", StringComparison.Ordinal)
+            || lower.EndsWith(".stella", StringComparison.Ordinal))
+        {
+            return PolicyDocumentFormat.Yaml;
+        }
+
+        return PolicyDocumentFormat.Json;
+    }
+}
+
+public sealed record PolicyRule(
+    string Name,
+    string? Identifier,
+    string? Description,
+    PolicyAction Action,
+    ImmutableArray<PolicySeverity> Severities,
+    ImmutableArray<string> Environments,
+    ImmutableArray<string> Sources,
+    ImmutableArray<string> Vendors,
+    ImmutableArray<string> Licenses,
+    ImmutableArray<string> Tags,
+    PolicyRuleMatchCriteria Match,
+    DateTimeOffset? Expires,
+    string? Justification,
+    ImmutableDictionary<string, string> Metadata)
+{
+    public static PolicyRuleMatchCriteria EmptyMatch { get; } = new(
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty);
+
+    public static PolicyRule Create(
+        string name,
+        PolicyAction action,
+        ImmutableArray<PolicySeverity> severities,
+        ImmutableArray<string> environments,
+        ImmutableArray<string> sources,
+        ImmutableArray<string> vendors,
+        ImmutableArray<string> licenses,
+        ImmutableArray<string> tags,
+        PolicyRuleMatchCriteria match,
+        DateTimeOffset? expires,
+        string? justification,
+        string? identifier = null,
+        string? description = null,
+        ImmutableDictionary<string, string>? metadata = null)
+    {
+        metadata ??= ImmutableDictionary<string, string>.Empty;
+        return new PolicyRule(
+            name,
+            identifier,
+            description,
+            action,
+            severities,
+            environments,
+            sources,
+            vendors,
+            licenses,
+            tags,
+            match,
+            expires,
+            justification,
+            metadata);
+    }
+
+    public bool MatchesAnyEnvironment => Environments.IsDefaultOrEmpty;
+}
+
+public sealed record PolicyRuleMatchCriteria(
+    ImmutableArray<string> Images,
+    ImmutableArray<string> Repositories,
+    ImmutableArray<string> Packages,
+    ImmutableArray<string> Purls,
+    ImmutableArray<string> Cves,
+    ImmutableArray<string> Paths,
+    ImmutableArray<string> LayerDigests,
+    ImmutableArray<string> UsedByEntrypoint)
+{
+    public static PolicyRuleMatchCriteria Create(
+        ImmutableArray<string> images,
+        ImmutableArray<string> repositories,
+        ImmutableArray<string> packages,
+        ImmutableArray<string> purls,
+        ImmutableArray<string> cves,
+        ImmutableArray<string> paths,
+        ImmutableArray<string> layerDigests,
+        ImmutableArray<string> usedByEntrypoint)
+        => new(
+            images,
+            repositories,
+            packages,
+            purls,
+            cves,
+            paths,
+            layerDigests,
+            usedByEntrypoint);
+
+    public static PolicyRuleMatchCriteria Empty { get; } = new(
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty,
+        ImmutableArray<string>.Empty);
+
+    public bool IsEmpty =>
+        Images.IsDefaultOrEmpty &&
+        Repositories.IsDefaultOrEmpty &&
+        Packages.IsDefaultOrEmpty &&
+        Purls.IsDefaultOrEmpty &&
+        Cves.IsDefaultOrEmpty &&
+        Paths.IsDefaultOrEmpty &&
+        LayerDigests.IsDefaultOrEmpty &&
+        UsedByEntrypoint.IsDefaultOrEmpty;
+}
+
+public sealed record PolicyAction(
+    PolicyActionType Type,
+    PolicyIgnoreOptions? Ignore,
+    PolicyEscalateOptions? Escalate,
+    PolicyRequireVexOptions? RequireVex,
+    bool Quiet);
+
+public enum PolicyActionType
+{
+    Block,
+    Ignore,
+    Warn,
+    Defer,
+    Escalate,
+    RequireVex,
+}
+
+public sealed record PolicyIgnoreOptions(DateTimeOffset? Until, string? Justification);
+
+public sealed record PolicyEscalateOptions(
+    PolicySeverity? MinimumSeverity,
+    bool RequireKev,
+    double? MinimumEpss);
+
+public sealed record PolicyRequireVexOptions(
+    ImmutableArray<string> Vendors,
+    ImmutableArray<string> Justifications);
+
+public enum PolicySeverity
+{
+    Critical,
+    High,
+    Medium,
+    Low,
+    Informational,
+    None,
+    Unknown,
+}
+
+public sealed record PolicyExceptionConfiguration(
+    ImmutableArray<PolicyExceptionEffect> Effects,
+    ImmutableArray<PolicyExceptionRoutingTemplate> RoutingTemplates)
+{
+    public static PolicyExceptionConfiguration Empty { get; } = new(
+        ImmutableArray<PolicyExceptionEffect>.Empty,
+        ImmutableArray<PolicyExceptionRoutingTemplate>.Empty);
+
+    public PolicyExceptionEffect? FindEffect(string effectId)
+    {
+        if (string.IsNullOrWhiteSpace(effectId) || Effects.IsDefaultOrEmpty)
+        {
+            return null;
+        }
+
+        return Effects.FirstOrDefault(effect =>
+            string.Equals(effect.Id, effectId, StringComparison.OrdinalIgnoreCase));
+    }
+}
+
+public sealed record PolicyExceptionEffect(
+    string Id,
+    string? Name,
+    PolicyExceptionEffectType Effect,
+    PolicySeverity? DowngradeSeverity,
+    string? RequiredControlId,
+    string? RoutingTemplate,
+    int? MaxDurationDays,
+    string? Description);
+
+public enum PolicyExceptionEffectType
+{
+    Suppress,
+    Defer,
+    Downgrade,
+    RequireControl,
+}
+
+public sealed record PolicyExceptionRoutingTemplate(
+    string Id,
+    string AuthorityRouteId,
+    bool RequireMfa,
+    string? Description);

src/Policy/__Libraries/StellaOps.Policy/PolicyEvaluation.cs

@@ -0,0 +1,552 @@
+using System;
+using System.Collections.Immutable;
+using System.Globalization;
+
+namespace StellaOps.Policy;
+
+public static class PolicyEvaluation
+{
+    public static PolicyVerdict EvaluateFinding(PolicyDocument document, PolicyScoringConfig scoringConfig, PolicyFinding finding)
+    {
+        if (document is null)
+        {
+            throw new ArgumentNullException(nameof(document));
+        }
+
+        if (scoringConfig is null)
+        {
+            throw new ArgumentNullException(nameof(scoringConfig));
+        }
+
+        if (finding is null)
+        {
+            throw new ArgumentNullException(nameof(finding));
+        }
+
+        var severityWeight = scoringConfig.SeverityWeights.TryGetValue(finding.Severity, out var weight)
+            ? weight
+            : scoringConfig.SeverityWeights.GetValueOrDefault(PolicySeverity.Unknown, 0);
+        var trustKey = ResolveTrustKey(finding);
+        var trustWeight = ResolveTrustWeight(scoringConfig, trustKey);
+        var reachabilityKey = ResolveReachabilityKey(finding);
+        var reachabilityWeight = ResolveReachabilityWeight(scoringConfig, reachabilityKey, out var resolvedReachabilityKey);
+        var baseScore = severityWeight * trustWeight * reachabilityWeight;
+        var components = new ScoringComponents(
+            severityWeight,
+            trustWeight,
+            reachabilityWeight,
+            baseScore,
+            trustKey,
+            resolvedReachabilityKey);
+        var unknownConfidence = ComputeUnknownConfidence(scoringConfig.UnknownConfidence, finding);
+
+        foreach (var rule in document.Rules)
+        {
+            if (!RuleMatches(rule, finding))
+            {
+                continue;
+            }
+
+            return BuildVerdict(rule, finding, scoringConfig, components, unknownConfidence);
+        }
+
+        var baseline = PolicyVerdict.CreateBaseline(finding.FindingId, scoringConfig);
+        return ApplyUnknownConfidence(baseline, unknownConfidence);
+    }
+
+    private static PolicyVerdict BuildVerdict(
+        PolicyRule rule,
+        PolicyFinding finding,
+        PolicyScoringConfig config,
+        ScoringComponents components,
+        UnknownConfidenceResult? unknownConfidence)
+    {
+        var action = rule.Action;
+        var status = MapAction(action);
+        var notes = BuildNotes(action);
+        var inputs = ImmutableDictionary.CreateBuilder<string, double>(StringComparer.OrdinalIgnoreCase);
+        inputs["severityWeight"] = components.SeverityWeight;
+        inputs["trustWeight"] = components.TrustWeight;
+        inputs["reachabilityWeight"] = components.ReachabilityWeight;
+        inputs["baseScore"] = components.BaseScore;
+        if (!string.IsNullOrWhiteSpace(components.TrustKey))
+        {
+            inputs[$"trustWeight.{components.TrustKey}"] = components.TrustWeight;
+        }
+        if (!string.IsNullOrWhiteSpace(components.ReachabilityKey))
+        {
+            inputs[$"reachability.{components.ReachabilityKey}"] = components.ReachabilityWeight;
+        }
+        if (unknownConfidence is { Band.Description: { Length: > 0 } description })
+        {
+            notes = AppendNote(notes, description);
+        }
+        if (unknownConfidence is { } unknownDetails)
+        {
+            inputs["unknownConfidence"] = unknownDetails.Confidence;
+            inputs["unknownAgeDays"] = unknownDetails.AgeDays;
+        }
+
+        double score = components.BaseScore;
+        string? quietedBy = null;
+        var quiet = false;
+
+        var quietRequested = action.Quiet;
+        var quietAllowed = quietRequested && (action.RequireVex is not null || action.Type == PolicyActionType.RequireVex);
+
+        if (quietRequested && !quietAllowed)
+        {
+            var warnInputs = ImmutableDictionary.CreateBuilder<string, double>(StringComparer.OrdinalIgnoreCase);
+            foreach (var pair in inputs)
+            {
+                warnInputs[pair.Key] = pair.Value;
+            }
+            if (unknownConfidence is { } unknownInfo)
+            {
+                warnInputs["unknownConfidence"] = unknownInfo.Confidence;
+                warnInputs["unknownAgeDays"] = unknownInfo.AgeDays;
+            }
+
+            var warnPenalty = config.WarnPenalty;
+            warnInputs["warnPenalty"] = warnPenalty;
+            var warnScore = Math.Max(0, components.BaseScore - warnPenalty);
+            var warnNotes = AppendNote(notes, "Quiet flag ignored: rule must specify requireVex justifications.");
+
+            return new PolicyVerdict(
+                finding.FindingId,
+                PolicyVerdictStatus.Warned,
+                rule.Name,
+                action.Type.ToString(),
+                warnNotes,
+                warnScore,
+                config.Version,
+                warnInputs.ToImmutable(),
+                QuietedBy: null,
+                Quiet: false,
+                UnknownConfidence: unknownConfidence?.Confidence,
+                ConfidenceBand: unknownConfidence?.Band.Name,
+                UnknownAgeDays: unknownConfidence?.AgeDays,
+                SourceTrust: components.TrustKey,
+                Reachability: components.ReachabilityKey);
+        }
+
+        switch (status)
+        {
+            case PolicyVerdictStatus.Ignored:
+                score = ApplyPenalty(score, config.IgnorePenalty, inputs, "ignorePenalty");
+                break;
+            case PolicyVerdictStatus.Warned:
+                score = ApplyPenalty(score, config.WarnPenalty, inputs, "warnPenalty");
+                break;
+            case PolicyVerdictStatus.Deferred:
+                var deferPenalty = config.WarnPenalty / 2;
+                score = ApplyPenalty(score, deferPenalty, inputs, "deferPenalty");
+                break;
+        }
+
+        if (quietAllowed)
+        {
+            score = ApplyPenalty(score, config.QuietPenalty, inputs, "quietPenalty");
+            quietedBy = rule.Name;
+            quiet = true;
+        }
+
+        return new PolicyVerdict(
+            finding.FindingId,
+            status,
+            rule.Name,
+            action.Type.ToString(),
+            notes,
+            score,
+            config.Version,
+            inputs.ToImmutable(),
+            quietedBy,
+            quiet,
+            unknownConfidence?.Confidence,
+            unknownConfidence?.Band.Name,
+            unknownConfidence?.AgeDays,
+            components.TrustKey,
+            components.ReachabilityKey);
+    }
+
+    private static double ApplyPenalty(double score, double penalty, ImmutableDictionary<string, double>.Builder inputs, string key)
+    {
+        if (penalty <= 0)
+        {
+            return score;
+        }
+
+        inputs[key] = penalty;
+        return Math.Max(0, score - penalty);
+    }
+
+    private static PolicyVerdict ApplyUnknownConfidence(PolicyVerdict verdict, UnknownConfidenceResult? unknownConfidence)
+    {
+        if (unknownConfidence is null)
+        {
+            return verdict;
+        }
+
+        var inputsBuilder = ImmutableDictionary.CreateBuilder<string, double>(StringComparer.OrdinalIgnoreCase);
+        foreach (var pair in verdict.GetInputs())
+        {
+            inputsBuilder[pair.Key] = pair.Value;
+        }
+
+        inputsBuilder["unknownConfidence"] = unknownConfidence.Value.Confidence;
+        inputsBuilder["unknownAgeDays"] = unknownConfidence.Value.AgeDays;
+
+        return verdict with
+        {
+            Inputs = inputsBuilder.ToImmutable(),
+            UnknownConfidence = unknownConfidence.Value.Confidence,
+            ConfidenceBand = unknownConfidence.Value.Band.Name,
+            UnknownAgeDays = unknownConfidence.Value.AgeDays,
+        };
+    }
+
+    private static UnknownConfidenceResult? ComputeUnknownConfidence(PolicyUnknownConfidenceConfig config, PolicyFinding finding)
+    {
+        if (!IsUnknownFinding(finding))
+        {
+            return null;
+        }
+
+        var ageDays = ResolveUnknownAgeDays(finding);
+        var rawConfidence = config.Initial - (ageDays * config.DecayPerDay);
+        var confidence = config.Clamp(rawConfidence);
+        var band = config.ResolveBand(confidence);
+        return new UnknownConfidenceResult(ageDays, confidence, band);
+    }
+
+    private static bool IsUnknownFinding(PolicyFinding finding)
+    {
+        if (finding.Severity == PolicySeverity.Unknown)
+        {
+            return true;
+        }
+
+        if (!finding.Tags.IsDefaultOrEmpty)
+        {
+            foreach (var tag in finding.Tags)
+            {
+                if (string.Equals(tag, "state:unknown", StringComparison.OrdinalIgnoreCase))
+                {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    private static double ResolveUnknownAgeDays(PolicyFinding finding)
+    {
+        var ageTag = TryGetTagValue(finding.Tags, "unknown-age-days:");
+        if (!string.IsNullOrWhiteSpace(ageTag) &&
+            double.TryParse(ageTag, NumberStyles.Float, CultureInfo.InvariantCulture, out var parsedAge) &&
+            parsedAge >= 0)
+        {
+            return parsedAge;
+        }
+
+        var sinceTag = TryGetTagValue(finding.Tags, "unknown-since:");
+        if (string.IsNullOrWhiteSpace(sinceTag))
+        {
+            return 0;
+        }
+
+        if (!DateTimeOffset.TryParse(sinceTag, CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal, out var since))
+        {
+            return 0;
+        }
+
+        var observedTag = TryGetTagValue(finding.Tags, "observed-at:");
+        if (!string.IsNullOrWhiteSpace(observedTag) &&
+            DateTimeOffset.TryParse(observedTag, CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal, out var observed) &&
+            observed > since)
+        {
+            return Math.Max(0, (observed - since).TotalDays);
+        }
+
+        return 0;
+    }
+
+    private static string? ResolveTrustKey(PolicyFinding finding)
+    {
+        if (!finding.Tags.IsDefaultOrEmpty)
+        {
+            var tagged = TryGetTagValue(finding.Tags, "trust:");
+            if (!string.IsNullOrWhiteSpace(tagged))
+            {
+                return tagged;
+            }
+        }
+
+        if (!string.IsNullOrWhiteSpace(finding.Source))
+        {
+            return finding.Source;
+        }
+
+        if (!string.IsNullOrWhiteSpace(finding.Vendor))
+        {
+            return finding.Vendor;
+        }
+
+        return null;
+    }
+
+    private static double ResolveTrustWeight(PolicyScoringConfig config, string? key)
+    {
+        if (string.IsNullOrWhiteSpace(key) || config.TrustOverrides.IsEmpty)
+        {
+            return 1.0;
+        }
+
+        return config.TrustOverrides.TryGetValue(key, out var weight) ? weight : 1.0;
+    }
+
+    private static string? ResolveReachabilityKey(PolicyFinding finding)
+    {
+        if (finding.Tags.IsDefaultOrEmpty)
+        {
+            return null;
+        }
+
+        var reachability = TryGetTagValue(finding.Tags, "reachability:");
+        if (!string.IsNullOrWhiteSpace(reachability))
+        {
+            return reachability;
+        }
+
+        var usage = TryGetTagValue(finding.Tags, "usage:");
+        if (!string.IsNullOrWhiteSpace(usage))
+        {
+            return usage;
+        }
+
+        return null;
+    }
+
+    private static double ResolveReachabilityWeight(PolicyScoringConfig config, string? key, out string? resolvedKey)
+    {
+        if (!string.IsNullOrWhiteSpace(key) && config.ReachabilityBuckets.TryGetValue(key, out var weight))
+        {
+            resolvedKey = key;
+            return weight;
+        }
+
+        if (config.ReachabilityBuckets.TryGetValue("unknown", out var unknownWeight))
+        {
+            resolvedKey = "unknown";
+            return unknownWeight;
+        }
+
+        resolvedKey = key;
+        return 1.0;
+    }
+
+    private static string? TryGetTagValue(ImmutableArray<string> tags, string prefix)
+    {
+        if (tags.IsDefaultOrEmpty)
+        {
+            return null;
+        }
+
+        foreach (var tag in tags)
+        {
+            if (string.IsNullOrWhiteSpace(tag))
+            {
+                continue;
+            }
+
+            if (tag.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+            {
+                var value = tag[prefix.Length..].Trim();
+                if (!string.IsNullOrEmpty(value))
+                {
+                    return value;
+                }
+            }
+        }
+
+        return null;
+    }
+
+    private readonly record struct ScoringComponents(
+        double SeverityWeight,
+        double TrustWeight,
+        double ReachabilityWeight,
+        double BaseScore,
+        string? TrustKey,
+        string? ReachabilityKey);
+
+    private readonly struct UnknownConfidenceResult
+    {
+        public UnknownConfidenceResult(double ageDays, double confidence, PolicyUnknownConfidenceBand band)
+        {
+            AgeDays = ageDays;
+            Confidence = confidence;
+            Band = band;
+        }
+
+        public double AgeDays { get; }
+
+        public double Confidence { get; }
+
+        public PolicyUnknownConfidenceBand Band { get; }
+    }
+
+    private static bool RuleMatches(PolicyRule rule, PolicyFinding finding)
+    {
+        if (!rule.Severities.IsDefaultOrEmpty && !rule.Severities.Contains(finding.Severity))
+        {
+            return false;
+        }
+
+        if (!Matches(rule.Environments, finding.Environment))
+        {
+            return false;
+        }
+
+        if (!Matches(rule.Sources, finding.Source))
+        {
+            return false;
+        }
+
+        if (!Matches(rule.Vendors, finding.Vendor))
+        {
+            return false;
+        }
+
+        if (!Matches(rule.Licenses, finding.License))
+        {
+            return false;
+        }
+
+        if (!RuleMatchCriteria(rule.Match, finding))
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static bool Matches(ImmutableArray<string> ruleValues, string? candidate)
+    {
+        if (ruleValues.IsDefaultOrEmpty)
+        {
+            return true;
+        }
+
+        if (string.IsNullOrWhiteSpace(candidate))
+        {
+            return false;
+        }
+
+        return ruleValues.Contains(candidate, StringComparer.OrdinalIgnoreCase);
+    }
+
+    private static bool RuleMatchCriteria(PolicyRuleMatchCriteria criteria, PolicyFinding finding)
+    {
+        if (!criteria.Images.IsDefaultOrEmpty && !ContainsValue(criteria.Images, finding.Image, StringComparer.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (!criteria.Repositories.IsDefaultOrEmpty && !ContainsValue(criteria.Repositories, finding.Repository, StringComparer.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (!criteria.Packages.IsDefaultOrEmpty && !ContainsValue(criteria.Packages, finding.Package, StringComparer.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (!criteria.Purls.IsDefaultOrEmpty && !ContainsValue(criteria.Purls, finding.Purl, StringComparer.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (!criteria.Cves.IsDefaultOrEmpty && !ContainsValue(criteria.Cves, finding.Cve, StringComparer.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (!criteria.Paths.IsDefaultOrEmpty && !ContainsValue(criteria.Paths, finding.Path, StringComparer.Ordinal))
+        {
+            return false;
+        }
+
+        if (!criteria.LayerDigests.IsDefaultOrEmpty && !ContainsValue(criteria.LayerDigests, finding.LayerDigest, StringComparer.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (!criteria.UsedByEntrypoint.IsDefaultOrEmpty)
+        {
+            var match = false;
+            foreach (var tag in criteria.UsedByEntrypoint)
+            {
+                if (finding.Tags.Contains(tag, StringComparer.OrdinalIgnoreCase))
+                {
+                    match = true;
+                    break;
+                }
+            }
+
+            if (!match)
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private static bool ContainsValue(ImmutableArray<string> values, string? candidate, StringComparer comparer)
+    {
+        if (values.IsDefaultOrEmpty)
+        {
+            return true;
+        }
+
+        if (string.IsNullOrWhiteSpace(candidate))
+        {
+            return false;
+        }
+
+        return values.Contains(candidate, comparer);
+    }
+
+    private static PolicyVerdictStatus MapAction(PolicyAction action)
+        => action.Type switch
+        {
+            PolicyActionType.Block => PolicyVerdictStatus.Blocked,
+            PolicyActionType.Ignore => PolicyVerdictStatus.Ignored,
+            PolicyActionType.Warn => PolicyVerdictStatus.Warned,
+            PolicyActionType.Defer => PolicyVerdictStatus.Deferred,
+            PolicyActionType.Escalate => PolicyVerdictStatus.Escalated,
+            PolicyActionType.RequireVex => PolicyVerdictStatus.RequiresVex,
+            _ => PolicyVerdictStatus.Pass,
+        };
+
+    private static string? BuildNotes(PolicyAction action)
+    {
+        if (action.Ignore is { } ignore && !string.IsNullOrWhiteSpace(ignore.Justification))
+        {
+            return ignore.Justification;
+        }
+
+        if (action.Escalate is { } escalate && escalate.MinimumSeverity is { } severity)
+        {
+            return $"Escalate >= {severity}";
+        }
+
+        return null;
+    }
+
+    private static string? AppendNote(string? existing, string addition)
+        => string.IsNullOrWhiteSpace(existing) ? addition : string.Concat(existing, " | ", addition);
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyFinding.cs

@@ -0,0 +1,51 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Policy;
+
+public sealed record PolicyFinding(
+    string FindingId,
+    PolicySeverity Severity,
+    string? Environment,
+    string? Source,
+    string? Vendor,
+    string? License,
+    string? Image,
+    string? Repository,
+    string? Package,
+    string? Purl,
+    string? Cve,
+    string? Path,
+    string? LayerDigest,
+    ImmutableArray<string> Tags)
+{
+    public static PolicyFinding Create(
+        string findingId,
+        PolicySeverity severity,
+        string? environment = null,
+        string? source = null,
+        string? vendor = null,
+        string? license = null,
+        string? image = null,
+        string? repository = null,
+        string? package = null,
+        string? purl = null,
+        string? cve = null,
+        string? path = null,
+        string? layerDigest = null,
+        ImmutableArray<string>? tags = null)
+        => new(
+            findingId,
+            severity,
+            environment,
+            source,
+            vendor,
+            license,
+            image,
+            repository,
+            package,
+            purl,
+            cve,
+            path,
+            layerDigest,
+            tags ?? ImmutableArray<string>.Empty);
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyIssue.cs

@@ -0,0 +1,28 @@
+using System;
+
+namespace StellaOps.Policy;
+
+/// <summary>
+/// Represents a validation or normalization issue discovered while processing a policy document.
+/// </summary>
+public sealed record PolicyIssue(string Code, string Message, PolicyIssueSeverity Severity, string Path)
+{
+    public static PolicyIssue Error(string code, string message, string path)
+        => new(code, message, PolicyIssueSeverity.Error, path);
+
+    public static PolicyIssue Warning(string code, string message, string path)
+        => new(code, message, PolicyIssueSeverity.Warning, path);
+
+    public static PolicyIssue Info(string code, string message, string path)
+        => new(code, message, PolicyIssueSeverity.Info, path);
+
+    public PolicyIssue EnsurePath(string fallbackPath)
+        => string.IsNullOrWhiteSpace(Path) ? this with { Path = fallbackPath } : this;
+}
+
+public enum PolicyIssueSeverity
+{
+    Error,
+    Warning,
+    Info,
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyPreviewModels.cs

@@ -0,0 +1,18 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Policy;
+
+public sealed record PolicyPreviewRequest(
+    string ImageDigest,
+    ImmutableArray<PolicyFinding> Findings,
+    ImmutableArray<PolicyVerdict> BaselineVerdicts,
+    PolicySnapshot? SnapshotOverride = null,
+    PolicySnapshotContent? ProposedPolicy = null);
+
+public sealed record PolicyPreviewResponse(
+    bool Success,
+    string PolicyDigest,
+    string? RevisionId,
+    ImmutableArray<PolicyIssue> Issues,
+    ImmutableArray<PolicyVerdictDiff> Diffs,
+    int ChangedCount);

src/Policy/__Libraries/StellaOps.Policy/PolicyPreviewService.cs

@@ -0,0 +1,142 @@
+using System;
+using System.Collections.Generic;
+using System;
+using System.Collections.Immutable;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+
+namespace StellaOps.Policy;
+
+public sealed class PolicyPreviewService
+{
+    private readonly PolicySnapshotStore _snapshotStore;
+    private readonly ILogger<PolicyPreviewService> _logger;
+
+    public PolicyPreviewService(PolicySnapshotStore snapshotStore, ILogger<PolicyPreviewService> logger)
+    {
+        _snapshotStore = snapshotStore ?? throw new ArgumentNullException(nameof(snapshotStore));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public async Task<PolicyPreviewResponse> PreviewAsync(PolicyPreviewRequest request, CancellationToken cancellationToken = default)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        var (snapshot, bindingIssues) = await ResolveSnapshotAsync(request, cancellationToken).ConfigureAwait(false);
+        if (snapshot is null)
+        {
+            _logger.LogWarning("Policy preview failed: snapshot unavailable or validation errors. Issues={Count}", bindingIssues.Length);
+            return new PolicyPreviewResponse(false, string.Empty, null, bindingIssues, ImmutableArray<PolicyVerdictDiff>.Empty, 0);
+        }
+
+        var projected = Evaluate(snapshot.Document, snapshot.ScoringConfig, request.Findings);
+        var baseline = BuildBaseline(request.BaselineVerdicts, projected, snapshot.ScoringConfig);
+        var diffs = BuildDiffs(baseline, projected);
+        var changed = diffs.Count(static diff => diff.Changed);
+
+        _logger.LogDebug("Policy preview computed for {ImageDigest}. Changed={Changed}", request.ImageDigest, changed);
+
+        return new PolicyPreviewResponse(true, snapshot.Digest, snapshot.RevisionId, bindingIssues, diffs, changed);
+    }
+
+    private async Task<(PolicySnapshot? Snapshot, ImmutableArray<PolicyIssue> Issues)> ResolveSnapshotAsync(PolicyPreviewRequest request, CancellationToken cancellationToken)
+    {
+        if (request.ProposedPolicy is not null)
+        {
+            var binding = PolicyBinder.Bind(request.ProposedPolicy.Content, request.ProposedPolicy.Format);
+            if (!binding.Success)
+            {
+                return (null, binding.Issues);
+            }
+
+            var digest = PolicyDigest.Compute(binding.Document);
+            var snapshot = new PolicySnapshot(
+                request.SnapshotOverride?.RevisionNumber + 1 ?? 0,
+                request.SnapshotOverride?.RevisionId ?? "preview",
+                digest,
+                DateTimeOffset.UtcNow,
+                request.ProposedPolicy.Actor,
+                request.ProposedPolicy.Format,
+                binding.Document,
+                binding.Issues,
+                PolicyScoringConfig.Default);
+
+            return (snapshot, binding.Issues);
+        }
+
+        if (request.SnapshotOverride is not null)
+        {
+            return (request.SnapshotOverride, ImmutableArray<PolicyIssue>.Empty);
+        }
+
+        var latest = await _snapshotStore.GetLatestAsync(cancellationToken).ConfigureAwait(false);
+        if (latest is not null)
+        {
+            return (latest, ImmutableArray<PolicyIssue>.Empty);
+        }
+
+        return (null, ImmutableArray.Create(PolicyIssue.Error("policy.preview.snapshot_missing", "No policy snapshot is available for preview.", "$")));
+    }
+
+    private static ImmutableArray<PolicyVerdict> Evaluate(PolicyDocument document, PolicyScoringConfig scoringConfig, ImmutableArray<PolicyFinding> findings)
+    {
+        if (findings.IsDefaultOrEmpty)
+        {
+            return ImmutableArray<PolicyVerdict>.Empty;
+        }
+
+        var results = ImmutableArray.CreateBuilder<PolicyVerdict>(findings.Length);
+        foreach (var finding in findings)
+        {
+            var verdict = PolicyEvaluation.EvaluateFinding(document, scoringConfig, finding);
+            results.Add(verdict);
+        }
+
+        return results.ToImmutable();
+    }
+
+    private static ImmutableDictionary<string, PolicyVerdict> BuildBaseline(ImmutableArray<PolicyVerdict> baseline, ImmutableArray<PolicyVerdict> projected, PolicyScoringConfig scoringConfig)
+    {
+        var builder = ImmutableDictionary.CreateBuilder<string, PolicyVerdict>(StringComparer.Ordinal);
+        if (!baseline.IsDefaultOrEmpty)
+        {
+            foreach (var verdict in baseline)
+            {
+                if (!string.IsNullOrEmpty(verdict.FindingId) && !builder.ContainsKey(verdict.FindingId))
+                {
+                    builder.Add(verdict.FindingId, verdict);
+                }
+            }
+        }
+
+        foreach (var verdict in projected)
+        {
+            if (!builder.ContainsKey(verdict.FindingId))
+            {
+                builder.Add(verdict.FindingId, PolicyVerdict.CreateBaseline(verdict.FindingId, scoringConfig));
+            }
+        }
+
+        return builder.ToImmutable();
+    }
+
+    private static ImmutableArray<PolicyVerdictDiff> BuildDiffs(ImmutableDictionary<string, PolicyVerdict> baseline, ImmutableArray<PolicyVerdict> projected)
+    {
+        var diffs = ImmutableArray.CreateBuilder<PolicyVerdictDiff>(projected.Length);
+        foreach (var verdict in projected.OrderBy(static v => v.FindingId, StringComparer.Ordinal))
+        {
+            var baseVerdict = baseline.TryGetValue(verdict.FindingId, out var existing)
+                ? existing
+                : new PolicyVerdict(verdict.FindingId, PolicyVerdictStatus.Pass);
+
+            diffs.Add(new PolicyVerdictDiff(baseVerdict, verdict));
+        }
+
+        return diffs.ToImmutable();
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/PolicySchemaResource.cs

@@ -0,0 +1,30 @@
+using System;
+using System.IO;
+using System.Reflection;
+using System.Text;
+
+namespace StellaOps.Policy;
+
+public static class PolicySchemaResource
+{
+    private const string SchemaResourceName = "StellaOps.Policy.Schemas.policy-schema@1.json";
+
+    public static Stream OpenSchemaStream()
+    {
+        var assembly = Assembly.GetExecutingAssembly();
+        var stream = assembly.GetManifestResourceStream(SchemaResourceName);
+        if (stream is null)
+        {
+            throw new InvalidOperationException($"Unable to locate embedded schema resource '{SchemaResourceName}'.");
+        }
+
+        return stream;
+    }
+
+    public static string ReadSchemaJson()
+    {
+        using var stream = OpenSchemaStream();
+        using var reader = new StreamReader(stream, Encoding.UTF8, detectEncodingFromByteOrderMarks: true);
+        return reader.ReadToEnd();
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyScoringConfig.cs

@@ -0,0 +1,18 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Policy;
+
+public sealed record PolicyScoringConfig(
+    string Version,
+    ImmutableDictionary<PolicySeverity, double> SeverityWeights,
+    double QuietPenalty,
+    double WarnPenalty,
+    double IgnorePenalty,
+    ImmutableDictionary<string, double> TrustOverrides,
+    ImmutableDictionary<string, double> ReachabilityBuckets,
+    PolicyUnknownConfidenceConfig UnknownConfidence)
+{
+    public static string BaselineVersion => "1.0";
+
+    public static PolicyScoringConfig Default { get; } = PolicyScoringConfigBinder.LoadDefault();
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyScoringConfigBinder.cs

@@ -0,0 +1,603 @@
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Reflection;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Json.Schema;
+using YamlDotNet.Serialization;
+using YamlDotNet.Serialization.NamingConventions;
+
+namespace StellaOps.Policy;
+
+public sealed record PolicyScoringBindingResult(
+    bool Success,
+    PolicyScoringConfig? Config,
+    ImmutableArray<PolicyIssue> Issues);
+
+public static class PolicyScoringConfigBinder
+{
+    private const string DefaultResourceName = "StellaOps.Policy.Schemas.policy-scoring-default.json";
+
+    private static readonly JsonSchema ScoringSchema = PolicyScoringSchema.Schema;
+
+    private static readonly ImmutableDictionary<string, double> DefaultReachabilityBuckets = CreateDefaultReachabilityBuckets();
+
+    private static readonly PolicyUnknownConfidenceConfig DefaultUnknownConfidence = CreateDefaultUnknownConfidence();
+
+    private static readonly IDeserializer YamlDeserializer = new DeserializerBuilder()
+        .WithNamingConvention(CamelCaseNamingConvention.Instance)
+        .IgnoreUnmatchedProperties()
+        .Build();
+
+    public static PolicyScoringConfig LoadDefault()
+    {
+        var assembly = Assembly.GetExecutingAssembly();
+        using var stream = assembly.GetManifestResourceStream(DefaultResourceName)
+            ?? throw new InvalidOperationException($"Embedded resource '{DefaultResourceName}' not found.");
+        using var reader = new StreamReader(stream, Encoding.UTF8, detectEncodingFromByteOrderMarks: true);
+        var json = reader.ReadToEnd();
+        var binding = Bind(json, PolicyDocumentFormat.Json);
+        if (!binding.Success || binding.Config is null)
+        {
+            throw new InvalidOperationException("Failed to load default policy scoring configuration.");
+        }
+
+        return binding.Config;
+    }
+
+    public static PolicyScoringBindingResult Bind(string content, PolicyDocumentFormat format)
+    {
+        if (string.IsNullOrWhiteSpace(content))
+        {
+            var issue = PolicyIssue.Error("scoring.empty", "Scoring configuration content is empty.", "$");
+            return new PolicyScoringBindingResult(false, null, ImmutableArray.Create(issue));
+        }
+
+        try
+        {
+            var root = Parse(content, format);
+            if (root is not JsonObject obj)
+            {
+                var issue = PolicyIssue.Error("scoring.invalid", "Scoring configuration must be a JSON object.", "$");
+                return new PolicyScoringBindingResult(false, null, ImmutableArray.Create(issue));
+            }
+
+            var issues = ImmutableArray.CreateBuilder<PolicyIssue>();
+            var schemaIssues = ValidateAgainstSchema(root);
+            issues.AddRange(schemaIssues);
+            if (schemaIssues.Any(static issue => issue.Severity == PolicyIssueSeverity.Error))
+            {
+                return new PolicyScoringBindingResult(false, null, issues.ToImmutable());
+            }
+
+            var config = BuildConfig(obj, issues);
+            var hasErrors = issues.Any(issue => issue.Severity == PolicyIssueSeverity.Error);
+            return new PolicyScoringBindingResult(!hasErrors, config, issues.ToImmutable());
+        }
+        catch (JsonException ex)
+        {
+            var issue = PolicyIssue.Error("scoring.parse.json", $"Failed to parse scoring JSON: {ex.Message}", "$");
+            return new PolicyScoringBindingResult(false, null, ImmutableArray.Create(issue));
+        }
+        catch (YamlDotNet.Core.YamlException ex)
+        {
+            var issue = PolicyIssue.Error("scoring.parse.yaml", $"Failed to parse scoring YAML: {ex.Message}", "$");
+            return new PolicyScoringBindingResult(false, null, ImmutableArray.Create(issue));
+        }
+    }
+
+    private static JsonNode? Parse(string content, PolicyDocumentFormat format)
+    {
+        return format switch
+        {
+            PolicyDocumentFormat.Json => JsonNode.Parse(content, new JsonNodeOptions { PropertyNameCaseInsensitive = true }),
+            PolicyDocumentFormat.Yaml => ConvertYamlToJsonNode(content),
+            _ => throw new ArgumentOutOfRangeException(nameof(format), format, "Unsupported scoring configuration format."),
+        };
+    }
+
+    private static JsonNode? ConvertYamlToJsonNode(string content)
+    {
+        var yamlObject = YamlDeserializer.Deserialize<object?>(content);
+        return PolicyBinderUtilities.ConvertYamlObject(yamlObject);
+    }
+
+    private static ImmutableArray<PolicyIssue> ValidateAgainstSchema(JsonNode root)
+    {
+        try
+        {
+            using var document = JsonDocument.Parse(root.ToJsonString(new JsonSerializerOptions
+            {
+                WriteIndented = false,
+            }));
+
+            var result = ScoringSchema.Evaluate(document.RootElement, new EvaluationOptions
+            {
+                OutputFormat = OutputFormat.List,
+                RequireFormatValidation = true,
+            });
+
+            if (result.IsValid)
+            {
+                return ImmutableArray<PolicyIssue>.Empty;
+            }
+
+            var issues = ImmutableArray.CreateBuilder<PolicyIssue>();
+            var seen = new HashSet<string>(StringComparer.Ordinal);
+            CollectSchemaIssues(result, issues, seen);
+            return issues.ToImmutable();
+        }
+        catch (JsonException ex)
+        {
+            return ImmutableArray.Create(PolicyIssue.Error("scoring.schema.normalize", $"Failed to normalize scoring configuration for schema validation: {ex.Message}", "$"));
+        }
+    }
+
+    private static void CollectSchemaIssues(EvaluationResults result, ImmutableArray<PolicyIssue>.Builder issues, HashSet<string> seen)
+    {
+        if (result.Errors is { Count: > 0 })
+        {
+            foreach (var pair in result.Errors)
+            {
+                var keyword = SanitizeKeyword(pair.Key);
+                var path = ConvertPointerToPath(result.InstanceLocation?.ToString() ?? "#");
+                var message = pair.Value ?? "Schema violation.";
+                var key = $"{path}|{keyword}|{message}";
+                if (seen.Add(key))
+                {
+                    issues.Add(PolicyIssue.Error($"scoring.schema.{keyword}", message, path));
+                }
+            }
+        }
+
+        if (result.Details is null)
+        {
+            return;
+        }
+
+        foreach (var detail in result.Details)
+        {
+            CollectSchemaIssues(detail, issues, seen);
+        }
+    }
+
+    private static string ConvertPointerToPath(string pointer)
+    {
+        if (string.IsNullOrEmpty(pointer) || pointer == "#")
+        {
+            return "$";
+        }
+
+        if (pointer[0] == '#')
+        {
+            pointer = pointer.Length > 1 ? pointer[1..] : string.Empty;
+        }
+
+        if (string.IsNullOrEmpty(pointer))
+        {
+            return "$";
+        }
+
+        var segments = pointer.Split('/', StringSplitOptions.RemoveEmptyEntries);
+        var builder = new StringBuilder("$");
+        foreach (var segment in segments)
+        {
+            var unescaped = segment.Replace("~1", "/").Replace("~0", "~");
+            if (int.TryParse(unescaped, out var index))
+            {
+                builder.Append('[').Append(index).Append(']');
+            }
+            else
+            {
+                builder.Append('.').Append(unescaped);
+            }
+        }
+
+        return builder.ToString();
+    }
+
+    private static string SanitizeKeyword(string keyword)
+    {
+        if (string.IsNullOrWhiteSpace(keyword))
+        {
+            return "unknown";
+        }
+
+        var builder = new StringBuilder(keyword.Length);
+        foreach (var ch in keyword)
+        {
+            if (char.IsLetterOrDigit(ch))
+            {
+                builder.Append(char.ToLowerInvariant(ch));
+            }
+            else if (ch is '.' or '_' or '-')
+            {
+                builder.Append(ch);
+            }
+            else
+            {
+                builder.Append('_');
+            }
+        }
+
+        return builder.Length == 0 ? "unknown" : builder.ToString();
+    }
+
+    private static PolicyScoringConfig BuildConfig(JsonObject obj, ImmutableArray<PolicyIssue>.Builder issues)
+    {
+        var version = ReadString(obj, "version", issues, required: true) ?? PolicyScoringConfig.BaselineVersion;
+
+        var severityWeights = ReadSeverityWeights(obj, issues);
+        var quietPenalty = ReadDouble(obj, "quietPenalty", issues, defaultValue: 45);
+        var warnPenalty = ReadDouble(obj, "warnPenalty", issues, defaultValue: 15);
+        var ignorePenalty = ReadDouble(obj, "ignorePenalty", issues, defaultValue: 35);
+        var trustOverrides = ReadTrustOverrides(obj, issues);
+        var reachabilityBuckets = ReadReachabilityBuckets(obj, issues);
+        var unknownConfidence = ReadUnknownConfidence(obj, issues);
+
+        return new PolicyScoringConfig(
+            version,
+            severityWeights,
+            quietPenalty,
+            warnPenalty,
+            ignorePenalty,
+            trustOverrides,
+            reachabilityBuckets,
+            unknownConfidence);
+    }
+
+    private static ImmutableDictionary<string, double> CreateDefaultReachabilityBuckets()
+    {
+        var builder = ImmutableDictionary.CreateBuilder<string, double>(StringComparer.OrdinalIgnoreCase);
+        builder["entrypoint"] = 1.0;
+        builder["direct"] = 0.85;
+        builder["indirect"] = 0.6;
+        builder["runtime"] = 0.45;
+        builder["unreachable"] = 0.25;
+        builder["unknown"] = 0.5;
+        return builder.ToImmutable();
+    }
+
+    private static PolicyUnknownConfidenceConfig CreateDefaultUnknownConfidence()
+    {
+        var bands = ImmutableArray.Create(
+            new PolicyUnknownConfidenceBand("high", 0.65, "Fresh unknowns with recent telemetry."),
+            new PolicyUnknownConfidenceBand("medium", 0.35, "Unknowns aging toward action required."),
+            new PolicyUnknownConfidenceBand("low", 0.0, "Stale unknowns that must be triaged."));
+        return new PolicyUnknownConfidenceConfig(0.8, 0.05, 0.2, bands);
+    }
+
+    private static ImmutableDictionary<string, double> ReadReachabilityBuckets(JsonObject obj, ImmutableArray<PolicyIssue>.Builder issues)
+    {
+        if (!obj.TryGetPropertyValue("reachabilityBuckets", out var node))
+        {
+            issues.Add(PolicyIssue.Warning("scoring.reachability.default", "reachabilityBuckets not specified; defaulting to baseline weights.", "$.reachabilityBuckets"));
+            return DefaultReachabilityBuckets;
+        }
+
+        if (node is not JsonObject bucketsObj)
+        {
+            issues.Add(PolicyIssue.Error("scoring.reachability.type", "reachabilityBuckets must be an object.", "$.reachabilityBuckets"));
+            return DefaultReachabilityBuckets;
+        }
+
+        var builder = ImmutableDictionary.CreateBuilder<string, double>(StringComparer.OrdinalIgnoreCase);
+        foreach (var pair in bucketsObj)
+        {
+            if (pair.Value is null)
+            {
+                issues.Add(PolicyIssue.Warning("scoring.reachability.null", $"Bucket '{pair.Key}' is null; defaulting to 0.", $"$.reachabilityBuckets.{pair.Key}"));
+                builder[pair.Key] = 0;
+                continue;
+            }
+
+            var value = ExtractDouble(pair.Value, issues, $"$.reachabilityBuckets.{pair.Key}");
+            builder[pair.Key] = value;
+        }
+
+        if (builder.Count == 0)
+        {
+            issues.Add(PolicyIssue.Warning("scoring.reachability.empty", "No reachability buckets defined; using defaults.", "$.reachabilityBuckets"));
+            return DefaultReachabilityBuckets;
+        }
+
+        return builder.ToImmutable();
+    }
+
+    private static PolicyUnknownConfidenceConfig ReadUnknownConfidence(JsonObject obj, ImmutableArray<PolicyIssue>.Builder issues)
+    {
+        if (!obj.TryGetPropertyValue("unknownConfidence", out var node))
+        {
+            issues.Add(PolicyIssue.Warning("scoring.unknown.default", "unknownConfidence not specified; defaulting to baseline decay settings.", "$.unknownConfidence"));
+            return DefaultUnknownConfidence;
+        }
+
+        if (node is not JsonObject configObj)
+        {
+            issues.Add(PolicyIssue.Error("scoring.unknown.type", "unknownConfidence must be an object.", "$.unknownConfidence"));
+            return DefaultUnknownConfidence;
+        }
+
+        var initial = DefaultUnknownConfidence.Initial;
+        if (configObj.TryGetPropertyValue("initial", out var initialNode))
+        {
+            initial = ExtractDouble(initialNode, issues, "$.unknownConfidence.initial");
+        }
+        else
+        {
+            issues.Add(PolicyIssue.Warning("scoring.unknown.initial.default", "initial not specified; using baseline value.", "$.unknownConfidence.initial"));
+        }
+
+        var decay = DefaultUnknownConfidence.DecayPerDay;
+        if (configObj.TryGetPropertyValue("decayPerDay", out var decayNode))
+        {
+            decay = ExtractDouble(decayNode, issues, "$.unknownConfidence.decayPerDay");
+        }
+        else
+        {
+            issues.Add(PolicyIssue.Warning("scoring.unknown.decay.default", "decayPerDay not specified; using baseline value.", "$.unknownConfidence.decayPerDay"));
+        }
+
+        var floor = DefaultUnknownConfidence.Floor;
+        if (configObj.TryGetPropertyValue("floor", out var floorNode))
+        {
+            floor = ExtractDouble(floorNode, issues, "$.unknownConfidence.floor");
+        }
+        else
+        {
+            issues.Add(PolicyIssue.Warning("scoring.unknown.floor.default", "floor not specified; using baseline value.", "$.unknownConfidence.floor"));
+        }
+
+        var bands = ReadConfidenceBands(configObj, issues);
+        if (bands.IsDefaultOrEmpty)
+        {
+            bands = DefaultUnknownConfidence.Bands;
+        }
+
+        if (initial < 0 || initial > 1)
+        {
+            issues.Add(PolicyIssue.Warning("scoring.unknown.initial.range", "initial confidence should be between 0 and 1. Clamping to valid range.", "$.unknownConfidence.initial"));
+            initial = Math.Clamp(initial, 0, 1);
+        }
+
+        if (decay < 0 || decay > 1)
+        {
+            issues.Add(PolicyIssue.Warning("scoring.unknown.decay.range", "decayPerDay should be between 0 and 1. Clamping to valid range.", "$.unknownConfidence.decayPerDay"));
+            decay = Math.Clamp(decay, 0, 1);
+        }
+
+        if (floor < 0 || floor > 1)
+        {
+            issues.Add(PolicyIssue.Warning("scoring.unknown.floor.range", "floor should be between 0 and 1. Clamping to valid range.", "$.unknownConfidence.floor"));
+            floor = Math.Clamp(floor, 0, 1);
+        }
+
+        return new PolicyUnknownConfidenceConfig(initial, decay, floor, bands);
+    }
+
+    private static ImmutableArray<PolicyUnknownConfidenceBand> ReadConfidenceBands(JsonObject configObj, ImmutableArray<PolicyIssue>.Builder issues)
+    {
+        if (!configObj.TryGetPropertyValue("bands", out var node))
+        {
+            return ImmutableArray<PolicyUnknownConfidenceBand>.Empty;
+        }
+
+        if (node is not JsonArray array)
+        {
+            issues.Add(PolicyIssue.Error("scoring.unknown.bands.type", "unknownConfidence.bands must be an array.", "$.unknownConfidence.bands"));
+            return ImmutableArray<PolicyUnknownConfidenceBand>.Empty;
+        }
+
+        var builder = ImmutableArray.CreateBuilder<PolicyUnknownConfidenceBand>();
+        var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        for (var index = 0; index < array.Count; index++)
+        {
+            var element = array[index];
+            if (element is not JsonObject bandObj)
+            {
+                issues.Add(PolicyIssue.Warning("scoring.unknown.band.type", "Band entry must be an object.", $"$.unknownConfidence.bands[{index}]"));
+                continue;
+            }
+
+            string? name = null;
+            if (bandObj.TryGetPropertyValue("name", out var nameNode) && nameNode is JsonValue nameValue && nameValue.TryGetValue(out string? text))
+            {
+                name = text?.Trim();
+            }
+
+            if (string.IsNullOrWhiteSpace(name))
+            {
+                issues.Add(PolicyIssue.Error("scoring.unknown.band.name", "Band entry requires a non-empty 'name'.", $"$.unknownConfidence.bands[{index}].name"));
+                continue;
+            }
+
+            if (!seen.Add(name))
+            {
+                issues.Add(PolicyIssue.Warning("scoring.unknown.band.duplicate", $"Duplicate band '{name}' encountered.", $"$.unknownConfidence.bands[{index}].name"));
+                continue;
+            }
+
+            if (!bandObj.TryGetPropertyValue("min", out var minNode))
+            {
+                issues.Add(PolicyIssue.Error("scoring.unknown.band.min", $"Band '{name}' is missing 'min'.", $"$.unknownConfidence.bands[{index}].min"));
+                continue;
+            }
+
+            var min = ExtractDouble(minNode, issues, $"$.unknownConfidence.bands[{index}].min");
+            if (min < 0 || min > 1)
+            {
+                issues.Add(PolicyIssue.Warning("scoring.unknown.band.range", $"Band '{name}' min should be between 0 and 1. Clamping to valid range.", $"$.unknownConfidence.bands[{index}].min"));
+                min = Math.Clamp(min, 0, 1);
+            }
+
+            string? description = null;
+            if (bandObj.TryGetPropertyValue("description", out var descriptionNode) && descriptionNode is JsonValue descriptionValue && descriptionValue.TryGetValue(out string? descriptionText))
+            {
+                description = descriptionText?.Trim();
+            }
+
+            builder.Add(new PolicyUnknownConfidenceBand(name, min, description));
+        }
+
+        if (builder.Count == 0)
+        {
+            return ImmutableArray<PolicyUnknownConfidenceBand>.Empty;
+        }
+
+        return builder.ToImmutable()
+            .OrderByDescending(static band => band.Min)
+            .ToImmutableArray();
+    }
+
+    private static ImmutableDictionary<PolicySeverity, double> ReadSeverityWeights(JsonObject obj, ImmutableArray<PolicyIssue>.Builder issues)
+    {
+        if (!obj.TryGetPropertyValue("severityWeights", out var node) || node is not JsonObject severityObj)
+        {
+            issues.Add(PolicyIssue.Error("scoring.severityWeights.missing", "severityWeights section is required.", "$.severityWeights"));
+            return ImmutableDictionary<PolicySeverity, double>.Empty;
+        }
+
+        var builder = ImmutableDictionary.CreateBuilder<PolicySeverity, double>();
+        foreach (var severity in Enum.GetValues<PolicySeverity>())
+        {
+            var key = severity.ToString();
+            if (!severityObj.TryGetPropertyValue(key, out var valueNode))
+            {
+                issues.Add(PolicyIssue.Warning("scoring.severityWeights.default", $"Severity '{key}' not specified; defaulting to 0.", $"$.severityWeights.{key}"));
+                builder[severity] = 0;
+                continue;
+            }
+
+            var value = ExtractDouble(valueNode, issues, $"$.severityWeights.{key}");
+            builder[severity] = value;
+        }
+
+        return builder.ToImmutable();
+    }
+
+    private static double ReadDouble(JsonObject obj, string property, ImmutableArray<PolicyIssue>.Builder issues, double defaultValue)
+    {
+        if (!obj.TryGetPropertyValue(property, out var node))
+        {
+            issues.Add(PolicyIssue.Warning("scoring.numeric.default", $"{property} not specified; defaulting to {defaultValue:0.##}.", $"$.{property}"));
+            return defaultValue;
+        }
+
+        return ExtractDouble(node, issues, $"$.{property}");
+    }
+
+    private static double ExtractDouble(JsonNode? node, ImmutableArray<PolicyIssue>.Builder issues, string path)
+    {
+        if (node is null)
+        {
+            issues.Add(PolicyIssue.Warning("scoring.numeric.null", $"Value at {path} missing; defaulting to 0.", path));
+            return 0;
+        }
+
+        if (node is JsonValue value)
+        {
+            if (value.TryGetValue(out double number))
+            {
+                return number;
+            }
+
+            if (value.TryGetValue(out string? text) && double.TryParse(text, NumberStyles.Float, CultureInfo.InvariantCulture, out number))
+            {
+                return number;
+            }
+        }
+
+        issues.Add(PolicyIssue.Error("scoring.numeric.invalid", $"Value at {path} is not numeric.", path));
+        return 0;
+    }
+
+    private static ImmutableDictionary<string, double> ReadTrustOverrides(JsonObject obj, ImmutableArray<PolicyIssue>.Builder issues)
+    {
+        if (!obj.TryGetPropertyValue("trustOverrides", out var node) || node is not JsonObject trustObj)
+        {
+            return ImmutableDictionary<string, double>.Empty;
+        }
+
+        var builder = ImmutableDictionary.CreateBuilder<string, double>(StringComparer.OrdinalIgnoreCase);
+        foreach (var pair in trustObj)
+        {
+            var value = ExtractDouble(pair.Value, issues, $"$.trustOverrides.{pair.Key}");
+            builder[pair.Key] = value;
+        }
+
+        return builder.ToImmutable();
+    }
+
+    private static string? ReadString(JsonObject obj, string property, ImmutableArray<PolicyIssue>.Builder issues, bool required)
+    {
+        if (!obj.TryGetPropertyValue(property, out var node) || node is null)
+        {
+            if (required)
+            {
+                issues.Add(PolicyIssue.Error("scoring.string.missing", $"{property} is required.", $"$.{property}"));
+            }
+            return null;
+        }
+
+        if (node is JsonValue value && value.TryGetValue(out string? text))
+        {
+            return text?.Trim();
+        }
+
+        issues.Add(PolicyIssue.Error("scoring.string.invalid", $"{property} must be a string.", $"$.{property}"));
+        return null;
+    }
+}
+
+internal static class PolicyBinderUtilities
+{
+    public static JsonNode? ConvertYamlObject(object? value)
+    {
+        switch (value)
+        {
+            case null:
+                return null;
+            case string s when bool.TryParse(s, out var boolValue):
+                return JsonValue.Create(boolValue);
+            case string s:
+                return JsonValue.Create(s);
+            case bool b:
+                return JsonValue.Create(b);
+            case sbyte or byte or short or ushort or int or uint or long or ulong or float or double or decimal:
+                return JsonValue.Create(Convert.ToDouble(value, CultureInfo.InvariantCulture));
+            case IDictionary dictionary:
+            {
+                var obj = new JsonObject();
+                foreach (DictionaryEntry entry in dictionary)
+                {
+                    if (entry.Key is null)
+                    {
+                        continue;
+                    }
+
+                    obj[entry.Key.ToString()!] = ConvertYamlObject(entry.Value);
+                }
+
+                return obj;
+            }
+            case IEnumerable enumerable:
+            {
+                var array = new JsonArray();
+                foreach (var item in enumerable)
+                {
+                    array.Add(ConvertYamlObject(item));
+                }
+
+                return array;
+            }
+            default:
+                return JsonValue.Create(value.ToString());
+        }
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyScoringConfigDigest.cs

@@ -0,0 +1,100 @@
+using System;
+using System.Buffers;
+using System.Collections.Immutable;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text.Json;
+
+namespace StellaOps.Policy;
+
+public static class PolicyScoringConfigDigest
+{
+    public static string Compute(PolicyScoringConfig config)
+    {
+        ArgumentNullException.ThrowIfNull(config);
+
+        var buffer = new ArrayBufferWriter<byte>();
+        using (var writer = new Utf8JsonWriter(buffer, new JsonWriterOptions
+        {
+            SkipValidation = true,
+        }))
+        {
+            WriteConfig(writer, config);
+        }
+
+        var hash = SHA256.HashData(buffer.WrittenSpan);
+        return Convert.ToHexString(hash).ToLowerInvariant();
+    }
+
+    private static void WriteConfig(Utf8JsonWriter writer, PolicyScoringConfig config)
+    {
+        writer.WriteStartObject();
+        writer.WriteString("version", config.Version);
+
+        writer.WritePropertyName("severityWeights");
+        writer.WriteStartObject();
+        foreach (var severity in Enum.GetValues<PolicySeverity>())
+        {
+            var key = severity.ToString();
+            var value = config.SeverityWeights.TryGetValue(severity, out var weight) ? weight : 0;
+            writer.WriteNumber(key, value);
+        }
+        writer.WriteEndObject();
+
+        writer.WriteNumber("quietPenalty", config.QuietPenalty);
+        writer.WriteNumber("warnPenalty", config.WarnPenalty);
+        writer.WriteNumber("ignorePenalty", config.IgnorePenalty);
+
+        if (!config.TrustOverrides.IsEmpty)
+        {
+            writer.WritePropertyName("trustOverrides");
+            writer.WriteStartObject();
+            foreach (var pair in config.TrustOverrides.OrderBy(static kvp => kvp.Key, StringComparer.OrdinalIgnoreCase))
+            {
+                writer.WriteNumber(pair.Key, pair.Value);
+            }
+            writer.WriteEndObject();
+        }
+
+        if (!config.ReachabilityBuckets.IsEmpty)
+        {
+            writer.WritePropertyName("reachabilityBuckets");
+            writer.WriteStartObject();
+            foreach (var pair in config.ReachabilityBuckets.OrderBy(static kvp => kvp.Key, StringComparer.OrdinalIgnoreCase))
+            {
+                writer.WriteNumber(pair.Key, pair.Value);
+            }
+            writer.WriteEndObject();
+        }
+
+        writer.WritePropertyName("unknownConfidence");
+        writer.WriteStartObject();
+        writer.WriteNumber("initial", config.UnknownConfidence.Initial);
+        writer.WriteNumber("decayPerDay", config.UnknownConfidence.DecayPerDay);
+        writer.WriteNumber("floor", config.UnknownConfidence.Floor);
+
+        if (!config.UnknownConfidence.Bands.IsDefaultOrEmpty)
+        {
+            writer.WritePropertyName("bands");
+            writer.WriteStartArray();
+            foreach (var band in config.UnknownConfidence.Bands
+                         .OrderByDescending(static b => b.Min)
+                         .ThenBy(static b => b.Name, StringComparer.OrdinalIgnoreCase))
+            {
+                writer.WriteStartObject();
+                writer.WriteString("name", band.Name);
+                writer.WriteNumber("min", band.Min);
+                if (!string.IsNullOrWhiteSpace(band.Description))
+                {
+                    writer.WriteString("description", band.Description);
+                }
+                writer.WriteEndObject();
+            }
+            writer.WriteEndArray();
+        }
+
+        writer.WriteEndObject();
+        writer.WriteEndObject();
+        writer.Flush();
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyScoringSchema.cs

@@ -0,0 +1,27 @@
+using System;
+using System.IO;
+using System.Reflection;
+using System.Text;
+using System.Threading;
+using Json.Schema;
+
+namespace StellaOps.Policy;
+
+public static class PolicyScoringSchema
+{
+    private const string SchemaResourceName = "StellaOps.Policy.Schemas.policy-scoring-schema@1.json";
+
+    private static readonly Lazy<JsonSchema> CachedSchema = new(LoadSchema, LazyThreadSafetyMode.ExecutionAndPublication);
+
+    public static JsonSchema Schema => CachedSchema.Value;
+
+    private static JsonSchema LoadSchema()
+    {
+        var assembly = Assembly.GetExecutingAssembly();
+        using var stream = assembly.GetManifestResourceStream(SchemaResourceName)
+            ?? throw new InvalidOperationException($"Embedded resource '{SchemaResourceName}' was not found.");
+        using var reader = new StreamReader(stream, Encoding.UTF8, detectEncodingFromByteOrderMarks: true);
+        var schemaJson = reader.ReadToEnd();
+        return JsonSchema.FromText(schemaJson);
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/PolicySnapshot.cs

@@ -0,0 +1,29 @@
+using System;
+using System.Collections.Immutable;
+
+namespace StellaOps.Policy;
+
+public sealed record PolicySnapshot(
+    long RevisionNumber,
+    string RevisionId,
+    string Digest,
+    DateTimeOffset CreatedAt,
+    string? CreatedBy,
+    PolicyDocumentFormat Format,
+    PolicyDocument Document,
+    ImmutableArray<PolicyIssue> Issues,
+    PolicyScoringConfig ScoringConfig);
+
+public sealed record PolicySnapshotContent(
+    string Content,
+    PolicyDocumentFormat Format,
+    string? Actor,
+    string? Source,
+    string? Description);
+
+public sealed record PolicySnapshotSaveResult(
+    bool Success,
+    bool Created,
+    string Digest,
+    PolicySnapshot? Snapshot,
+    PolicyBindingResult BindingResult);

src/Policy/__Libraries/StellaOps.Policy/PolicySnapshotStore.cs

@@ -0,0 +1,101 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+
+namespace StellaOps.Policy;
+
+public sealed class PolicySnapshotStore
+{
+    private readonly IPolicySnapshotRepository _snapshotRepository;
+    private readonly IPolicyAuditRepository _auditRepository;
+    private readonly TimeProvider _timeProvider;
+    private readonly ILogger<PolicySnapshotStore> _logger;
+    private readonly SemaphoreSlim _mutex = new(1, 1);
+
+    public PolicySnapshotStore(
+        IPolicySnapshotRepository snapshotRepository,
+        IPolicyAuditRepository auditRepository,
+        TimeProvider? timeProvider,
+        ILogger<PolicySnapshotStore> logger)
+    {
+        _snapshotRepository = snapshotRepository ?? throw new ArgumentNullException(nameof(snapshotRepository));
+        _auditRepository = auditRepository ?? throw new ArgumentNullException(nameof(auditRepository));
+        _timeProvider = timeProvider ?? TimeProvider.System;
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public async Task<PolicySnapshotSaveResult> SaveAsync(PolicySnapshotContent content, CancellationToken cancellationToken = default)
+    {
+        if (content is null)
+        {
+            throw new ArgumentNullException(nameof(content));
+        }
+
+        var bindingResult = PolicyBinder.Bind(content.Content, content.Format);
+        if (!bindingResult.Success)
+        {
+            _logger.LogWarning("Policy snapshot rejected due to validation errors (Format: {Format})", content.Format);
+            return new PolicySnapshotSaveResult(false, false, string.Empty, null, bindingResult);
+        }
+
+        var digest = PolicyDigest.Compute(bindingResult.Document);
+
+        await _mutex.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            var latest = await _snapshotRepository.GetLatestAsync(cancellationToken).ConfigureAwait(false);
+            if (latest is not null && string.Equals(latest.Digest, digest, StringComparison.Ordinal))
+            {
+                _logger.LogInformation("Policy snapshot unchanged; digest {Digest} matches revision {RevisionId}", digest, latest.RevisionId);
+                return new PolicySnapshotSaveResult(true, false, digest, latest, bindingResult);
+            }
+
+            var revisionNumber = (latest?.RevisionNumber ?? 0) + 1;
+            var revisionId = $"rev-{revisionNumber}";
+            var createdAt = _timeProvider.GetUtcNow();
+
+            var scoringConfig = PolicyScoringConfig.Default;
+
+            var snapshot = new PolicySnapshot(
+                revisionNumber,
+                revisionId,
+                digest,
+                createdAt,
+                content.Actor,
+                content.Format,
+                bindingResult.Document,
+                bindingResult.Issues,
+                scoringConfig);
+
+            await _snapshotRepository.AddAsync(snapshot, cancellationToken).ConfigureAwait(false);
+
+            var auditMessage = content.Description ?? "Policy snapshot created";
+            var auditEntry = new PolicyAuditEntry(
+                Guid.NewGuid(),
+                createdAt,
+                "snapshot.created",
+                revisionId,
+                digest,
+                content.Actor,
+                auditMessage);
+
+            await _auditRepository.AddAsync(auditEntry, cancellationToken).ConfigureAwait(false);
+
+            _logger.LogInformation(
+                "Policy snapshot saved. Revision {RevisionId}, digest {Digest}, issues {IssueCount}",
+                revisionId,
+                digest,
+                bindingResult.Issues.Length);
+
+            return new PolicySnapshotSaveResult(true, true, digest, snapshot, bindingResult);
+        }
+        finally
+        {
+            _mutex.Release();
+        }
+    }
+
+    public Task<PolicySnapshot?> GetLatestAsync(CancellationToken cancellationToken = default)
+        => _snapshotRepository.GetLatestAsync(cancellationToken);
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyUnknownConfidenceConfig.cs

@@ -0,0 +1,37 @@
+using System;
+using System.Collections.Immutable;
+
+namespace StellaOps.Policy;
+
+public sealed record PolicyUnknownConfidenceConfig(
+    double Initial,
+    double DecayPerDay,
+    double Floor,
+    ImmutableArray<PolicyUnknownConfidenceBand> Bands)
+{
+    public double Clamp(double value)
+        => Math.Clamp(value, Floor, 1.0);
+
+    public PolicyUnknownConfidenceBand ResolveBand(double value)
+    {
+        if (Bands.IsDefaultOrEmpty)
+        {
+            return PolicyUnknownConfidenceBand.Default;
+        }
+
+        foreach (var band in Bands)
+        {
+            if (value >= band.Min)
+            {
+                return band;
+            }
+        }
+
+        return Bands[Bands.Length - 1];
+    }
+}
+
+public sealed record PolicyUnknownConfidenceBand(string Name, double Min, string? Description = null)
+{
+    public static PolicyUnknownConfidenceBand Default { get; } = new("unspecified", 0, null);
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyValidationCli.cs

@@ -0,0 +1,242 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.IO;
+using System.Linq;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Policy;
+
+public sealed record PolicyValidationCliOptions
+{
+    public IReadOnlyList<string> Inputs { get; init; } = Array.Empty<string>();
+
+    /// <summary>
+    /// Writes machine-readable JSON instead of human-formatted text.
+    /// </summary>
+    public bool OutputJson { get; init; }
+
+    /// <summary>
+    /// When enabled, warnings cause a non-zero exit code.
+    /// </summary>
+    public bool Strict { get; init; }
+}
+
+public sealed record PolicyValidationFileResult(
+    string Path,
+    PolicyBindingResult BindingResult,
+    PolicyDiagnosticsReport Diagnostics);
+
+public sealed class PolicyValidationCli
+{
+    private readonly TextWriter _output;
+    private readonly TextWriter _error;
+
+    public PolicyValidationCli(TextWriter? output = null, TextWriter? error = null)
+    {
+        _output = output ?? Console.Out;
+        _error = error ?? Console.Error;
+    }
+
+    public async Task<int> RunAsync(PolicyValidationCliOptions options, CancellationToken cancellationToken = default)
+    {
+        if (options is null)
+        {
+            throw new ArgumentNullException(nameof(options));
+        }
+
+        if (options.Inputs.Count == 0)
+        {
+            await _error.WriteLineAsync("No input files provided. Supply one or more policy file paths.");
+            return 64; // EX_USAGE
+        }
+
+        var results = new List<PolicyValidationFileResult>();
+        foreach (var input in options.Inputs)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var resolvedPaths = ResolveInput(input);
+            if (resolvedPaths.Count == 0)
+            {
+                await _error.WriteLineAsync($"No files matched '{input}'.");
+                continue;
+            }
+
+            foreach (var path in resolvedPaths)
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+
+                var format = PolicySchema.DetectFormat(path);
+                var content = await File.ReadAllTextAsync(path, cancellationToken);
+                var bindingResult = PolicyBinder.Bind(content, format);
+                var diagnostics = PolicyDiagnostics.Create(bindingResult);
+
+                results.Add(new PolicyValidationFileResult(path, bindingResult, diagnostics));
+            }
+        }
+
+        if (results.Count == 0)
+        {
+            await _error.WriteLineAsync("No files were processed.");
+            return 65; // EX_DATAERR
+        }
+
+        if (options.OutputJson)
+        {
+            WriteJson(results);
+        }
+        else
+        {
+            await WriteTextAsync(results, cancellationToken);
+        }
+
+        var hasErrors = results.Any(static result => !result.BindingResult.Success);
+        var hasWarnings = results.Any(static result => result.BindingResult.Issues.Any(static issue => issue.Severity == PolicyIssueSeverity.Warning));
+
+        if (hasErrors)
+        {
+            return 1;
+        }
+
+        if (options.Strict && hasWarnings)
+        {
+            return 2;
+        }
+
+        return 0;
+    }
+
+    private async Task WriteTextAsync(IReadOnlyList<PolicyValidationFileResult> results, CancellationToken cancellationToken)
+    {
+        foreach (var result in results)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var relativePath = MakeRelative(result.Path);
+            await _output.WriteLineAsync($"{relativePath} [{result.BindingResult.Format}]");
+
+            if (result.BindingResult.Issues.Length == 0)
+            {
+                await _output.WriteLineAsync("  OK");
+                continue;
+            }
+
+            foreach (var issue in result.BindingResult.Issues)
+            {
+                var severity = issue.Severity.ToString().ToUpperInvariant().PadRight(7);
+                await _output.WriteLineAsync($"  {severity} {issue.Path} :: {issue.Message} ({issue.Code})");
+            }
+        }
+    }
+
+    private void WriteJson(IReadOnlyList<PolicyValidationFileResult> results)
+    {
+        var payload = results.Select(static result => new
+            {
+                path = result.Path,
+                format = result.BindingResult.Format.ToString().ToLowerInvariant(),
+                success = result.BindingResult.Success,
+                issues = result.BindingResult.Issues.Select(static issue => new
+                {
+                    code = issue.Code,
+                    message = issue.Message,
+                    severity = issue.Severity.ToString().ToLowerInvariant(),
+                    path = issue.Path,
+                }),
+                diagnostics = new
+                {
+                    version = result.Diagnostics.Version,
+                    ruleCount = result.Diagnostics.RuleCount,
+                    errorCount = result.Diagnostics.ErrorCount,
+                    warningCount = result.Diagnostics.WarningCount,
+                    generatedAt = result.Diagnostics.GeneratedAt,
+                    recommendations = result.Diagnostics.Recommendations,
+                },
+            })
+            .ToArray();
+
+        var json = JsonSerializer.Serialize(payload, new JsonSerializerOptions
+        {
+            WriteIndented = true,
+        });
+        _output.WriteLine(json);
+    }
+
+    private static IReadOnlyList<string> ResolveInput(string input)
+    {
+        if (string.IsNullOrWhiteSpace(input))
+        {
+            return Array.Empty<string>();
+        }
+
+        var expanded = Environment.ExpandEnvironmentVariables(input.Trim());
+        if (File.Exists(expanded))
+        {
+            return new[] { Path.GetFullPath(expanded) };
+        }
+
+        if (Directory.Exists(expanded))
+        {
+            return Directory.EnumerateFiles(expanded, "*.*", SearchOption.TopDirectoryOnly)
+                .Where(static path => MatchesPolicyExtension(path))
+                .OrderBy(static path => path, StringComparer.OrdinalIgnoreCase)
+                .Select(Path.GetFullPath)
+                .ToArray();
+        }
+
+        var directory = Path.GetDirectoryName(expanded);
+        var searchPattern = Path.GetFileName(expanded);
+
+        if (string.IsNullOrEmpty(searchPattern))
+        {
+            return Array.Empty<string>();
+        }
+
+        if (string.IsNullOrEmpty(directory))
+        {
+            directory = ".";
+        }
+
+        if (!Directory.Exists(directory))
+        {
+            return Array.Empty<string>();
+        }
+
+        return Directory.EnumerateFiles(directory, searchPattern, SearchOption.TopDirectoryOnly)
+            .Where(static path => MatchesPolicyExtension(path))
+            .OrderBy(static path => path, StringComparer.OrdinalIgnoreCase)
+            .Select(Path.GetFullPath)
+            .ToArray();
+    }
+
+    private static bool MatchesPolicyExtension(string path)
+    {
+        var extension = Path.GetExtension(path);
+        return extension.Equals(".yaml", StringComparison.OrdinalIgnoreCase)
+               || extension.Equals(".yml", StringComparison.OrdinalIgnoreCase)
+               || extension.Equals(".json", StringComparison.OrdinalIgnoreCase)
+               || extension.Equals(".stella", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static string MakeRelative(string path)
+    {
+        try
+        {
+            var fullPath = Path.GetFullPath(path);
+            var current = Directory.GetCurrentDirectory();
+            if (fullPath.StartsWith(current, StringComparison.OrdinalIgnoreCase))
+            {
+                return fullPath[current.Length..].TrimStart(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+            }
+
+            return fullPath;
+        }
+        catch
+        {
+            return path;
+        }
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/PolicyVerdict.cs

@@ -0,0 +1,112 @@
+using System;
+using System.Collections.Immutable;
+
+namespace StellaOps.Policy;
+
+public enum PolicyVerdictStatus
+{
+    Pass,
+    Blocked,
+    Ignored,
+    Warned,
+    Deferred,
+    Escalated,
+    RequiresVex,
+}
+
+public sealed record PolicyVerdict(
+    string FindingId,
+    PolicyVerdictStatus Status,
+    string? RuleName = null,
+    string? RuleAction = null,
+    string? Notes = null,
+    double Score = 0,
+    string ConfigVersion = "1.0",
+    ImmutableDictionary<string, double>? Inputs = null,
+    string? QuietedBy = null,
+    bool Quiet = false,
+    double? UnknownConfidence = null,
+    string? ConfidenceBand = null,
+    double? UnknownAgeDays = null,
+    string? SourceTrust = null,
+    string? Reachability = null)
+{
+    public static PolicyVerdict CreateBaseline(string findingId, PolicyScoringConfig scoringConfig)
+    {
+        var inputs = ImmutableDictionary<string, double>.Empty;
+        return new PolicyVerdict(
+            findingId,
+            PolicyVerdictStatus.Pass,
+            RuleName: null,
+            RuleAction: null,
+            Notes: null,
+            Score: 0,
+            ConfigVersion: scoringConfig.Version,
+            Inputs: inputs,
+            QuietedBy: null,
+            Quiet: false,
+            UnknownConfidence: null,
+            ConfidenceBand: null,
+            UnknownAgeDays: null,
+            SourceTrust: null,
+            Reachability: null);
+    }
+
+    public ImmutableDictionary<string, double> GetInputs()
+        => Inputs ?? ImmutableDictionary<string, double>.Empty;
+}
+
+public sealed record PolicyVerdictDiff(
+    PolicyVerdict Baseline,
+    PolicyVerdict Projected)
+{
+    public bool Changed
+    {
+        get
+        {
+            if (Baseline.Status != Projected.Status)
+            {
+                return true;
+            }
+
+            if (!string.Equals(Baseline.RuleName, Projected.RuleName, StringComparison.Ordinal))
+            {
+                return true;
+            }
+
+            if (Math.Abs(Baseline.Score - Projected.Score) > 0.0001)
+            {
+                return true;
+            }
+
+            if (!string.Equals(Baseline.QuietedBy, Projected.QuietedBy, StringComparison.Ordinal))
+            {
+                return true;
+            }
+
+            var baselineConfidence = Baseline.UnknownConfidence ?? 0;
+            var projectedConfidence = Projected.UnknownConfidence ?? 0;
+            if (Math.Abs(baselineConfidence - projectedConfidence) > 0.0001)
+            {
+                return true;
+            }
+
+            if (!string.Equals(Baseline.ConfidenceBand, Projected.ConfidenceBand, StringComparison.Ordinal))
+            {
+                return true;
+            }
+
+            if (!string.Equals(Baseline.SourceTrust, Projected.SourceTrust, StringComparison.Ordinal))
+            {
+                return true;
+            }
+
+            if (!string.Equals(Baseline.Reachability, Projected.Reachability, StringComparison.Ordinal))
+            {
+                return true;
+            }
+
+            return false;
+        }
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/Schemas/policy-schema@1.json

@@ -0,0 +1,277 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.stella-ops.org/policy/policy-schema@1.json",
+  "title": "StellaOps Policy Schema v1",
+  "type": "object",
+  "required": ["version", "rules"],
+  "properties": {
+    "version": {
+      "type": ["string", "number"],
+      "enum": ["1", "1.0", 1, 1.0]
+    },
+    "description": {
+      "type": "string"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": {
+        "type": ["string", "number", "boolean"]
+      }
+    },
+    "exceptions": {
+      "type": "object",
+      "properties": {
+        "effects": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/exceptionEffect"
+          },
+          "uniqueItems": true
+        },
+        "routingTemplates": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/exceptionRoutingTemplate"
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "rules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/rule"
+      }
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "minLength": 1
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["Critical", "High", "Medium", "Low", "Informational", "None", "Unknown"]
+    },
+    "stringArray": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "exceptionEffect": {
+      "type": "object",
+      "required": ["id", "effect"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/identifier"
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "effect": {
+          "type": "string",
+          "enum": ["suppress", "defer", "downgrade", "requireControl"]
+        },
+        "downgradeSeverity": {
+          "$ref": "#/$defs/severity"
+        },
+        "requiredControlId": {
+          "$ref": "#/$defs/identifier"
+        },
+        "routingTemplate": {
+          "$ref": "#/$defs/identifier"
+        },
+        "maxDurationDays": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "effect": {
+                "const": "downgrade"
+              }
+            },
+            "required": ["effect"]
+          },
+          "then": {
+            "required": ["downgradeSeverity"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "effect": {
+                "const": "requireControl"
+              }
+            },
+            "required": ["effect"]
+          },
+          "then": {
+            "required": ["requiredControlId"]
+          }
+        }
+      ]
+    },
+    "exceptionRoutingTemplate": {
+      "type": "object",
+      "required": ["id", "authorityRouteId"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/identifier"
+        },
+        "description": {
+          "type": "string"
+        },
+        "authorityRouteId": {
+          "$ref": "#/$defs/identifier"
+        },
+        "requireMfa": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "rule": {
+      "type": "object",
+      "required": ["name", "action"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/identifier"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string"
+        },
+        "severity": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/severity"
+          },
+          "uniqueItems": true
+        },
+        "sources": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "vendors": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "licenses": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "tags": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "environments": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "images": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "repositories": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "packages": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "purls": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "cves": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "paths": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "layerDigests": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "usedByEntrypoint": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "justification": {
+          "type": "string"
+        },
+        "quiet": {
+          "type": "boolean"
+        },
+        "action": {
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": ["block", "fail", "deny", "ignore", "warn", "defer", "escalate", "requireVex"]
+            },
+            {
+              "type": "object",
+              "required": ["type"],
+              "properties": {
+                "type": {
+                  "type": "string"
+                },
+                "quiet": {
+                  "type": "boolean"
+                },
+                "until": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "justification": {
+                  "type": "string"
+                },
+                "severity": {
+                  "$ref": "#/$defs/severity"
+                },
+                "vendors": {
+                  "$ref": "#/$defs/stringArray"
+                },
+                "justifications": {
+                  "$ref": "#/$defs/stringArray"
+                },
+                "epss": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 1
+                },
+                "kev": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": true
+            }
+          ]
+        },
+        "expires": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "until": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {
+            "type": ["string", "number", "boolean"]
+          }
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

src/Policy/__Libraries/StellaOps.Policy/Schemas/policy-scoring-default.json

@@ -0,0 +1,51 @@
+{
+  "version": "1.0",
+  "severityWeights": {
+    "Critical": 90.0,
+    "High": 75.0,
+    "Medium": 50.0,
+    "Low": 25.0,
+    "Informational": 10.0,
+    "None": 0.0,
+    "Unknown": 60.0
+  },
+  "quietPenalty": 45.0,
+  "warnPenalty": 15.0,
+  "ignorePenalty": 35.0,
+  "trustOverrides": {
+    "vendor": 1.0,
+    "distro": 0.85,
+    "platform": 0.75,
+    "community": 0.65
+  },
+  "reachabilityBuckets": {
+    "entrypoint": 1.0,
+    "direct": 0.85,
+    "indirect": 0.6,
+    "runtime": 0.45,
+    "unreachable": 0.25,
+    "unknown": 0.5
+  },
+  "unknownConfidence": {
+    "initial": 0.8,
+    "decayPerDay": 0.05,
+    "floor": 0.2,
+    "bands": [
+      {
+        "name": "high",
+        "min": 0.65,
+        "description": "Fresh unknowns with recent telemetry."
+      },
+      {
+        "name": "medium",
+        "min": 0.35,
+        "description": "Unknowns aging toward action required."
+      },
+      {
+        "name": "low",
+        "min": 0.0,
+        "description": "Stale unknowns that must be triaged."
+      }
+    ]
+  }
+}

src/Policy/__Libraries/StellaOps.Policy/Schemas/policy-scoring-schema@1.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.stella-ops.org/policy/policy-scoring-schema@1.json",
+  "title": "StellaOps Policy Scoring Configuration v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "severityWeights"
+  ],
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "severityWeights": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "Critical",
+        "High",
+        "Medium",
+        "Low",
+        "Informational",
+        "None",
+        "Unknown"
+      ],
+      "properties": {
+        "Critical": {
+          "$ref": "#/$defs/weight"
+        },
+        "High": {
+          "$ref": "#/$defs/weight"
+        },
+        "Medium": {
+          "$ref": "#/$defs/weight"
+        },
+        "Low": {
+          "$ref": "#/$defs/weight"
+        },
+        "Informational": {
+          "$ref": "#/$defs/weight"
+        },
+        "None": {
+          "$ref": "#/$defs/weight"
+        },
+        "Unknown": {
+          "$ref": "#/$defs/weight"
+        }
+      }
+    },
+    "quietPenalty": {
+      "$ref": "#/$defs/penalty"
+    },
+    "warnPenalty": {
+      "$ref": "#/$defs/penalty"
+    },
+    "ignorePenalty": {
+      "$ref": "#/$defs/penalty"
+    },
+    "trustOverrides": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9_.-]*$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/trustWeight"
+      }
+    },
+    "reachabilityBuckets": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9_.-]*$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/reachabilityWeight"
+      }
+    },
+    "unknownConfidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "initial",
+        "decayPerDay",
+        "floor",
+        "bands"
+      ],
+      "properties": {
+        "initial": {
+          "$ref": "#/$defs/confidence"
+        },
+        "decayPerDay": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "floor": {
+          "$ref": "#/$defs/confidence"
+        },
+        "bands": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "name",
+              "min"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_.-]*$"
+              },
+              "min": {
+                "$ref": "#/$defs/confidence"
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 256
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "weight": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 100
+    },
+    "penalty": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 200
+    },
+    "trustWeight": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 5
+    },
+    "reachabilityWeight": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1.5
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    }
+  }
+}

src/Policy/__Libraries/StellaOps.Policy/StellaOps.Policy.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <LangVersion>preview</LangVersion>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.CommandLine" Version="2.0.0-beta5.25306.1" />
+    <PackageReference Include="YamlDotNet" Version="13.7.1" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0-rc.2.25502.107" />
+    <PackageReference Include="JsonSchema.Net" Version="5.3.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <EmbeddedResource Include="Schemas\policy-schema@1.json" />
+    <EmbeddedResource Include="Schemas\policy-scoring-default.json" />
+    <EmbeddedResource Include="Schemas\policy-scoring-schema@1.json" />
+  </ItemGroup>
+</Project>

src/Policy/__Libraries/StellaOps.Policy/Storage/IPolicySnapshotRepository.cs

@@ -0,0 +1,14 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Policy;
+
+public interface IPolicySnapshotRepository
+{
+    Task<PolicySnapshot?> GetLatestAsync(CancellationToken cancellationToken = default);
+
+    Task<IReadOnlyList<PolicySnapshot>> ListAsync(int limit, CancellationToken cancellationToken = default);
+
+    Task AddAsync(PolicySnapshot snapshot, CancellationToken cancellationToken = default);
+}

src/Policy/__Libraries/StellaOps.Policy/Storage/InMemoryPolicySnapshotRepository.cs

@@ -0,0 +1,65 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Policy;
+
+public sealed class InMemoryPolicySnapshotRepository : IPolicySnapshotRepository
+{
+    private readonly List<PolicySnapshot> _snapshots = new();
+    private readonly SemaphoreSlim _mutex = new(1, 1);
+
+    public async Task AddAsync(PolicySnapshot snapshot, CancellationToken cancellationToken = default)
+    {
+        if (snapshot is null)
+        {
+            throw new ArgumentNullException(nameof(snapshot));
+        }
+
+        await _mutex.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            _snapshots.Add(snapshot);
+            _snapshots.Sort(static (left, right) => left.RevisionNumber.CompareTo(right.RevisionNumber));
+        }
+        finally
+        {
+            _mutex.Release();
+        }
+    }
+
+    public async Task<PolicySnapshot?> GetLatestAsync(CancellationToken cancellationToken = default)
+    {
+        await _mutex.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            return _snapshots.Count == 0 ? null : _snapshots[^1];
+        }
+        finally
+        {
+            _mutex.Release();
+        }
+    }
+
+    public async Task<IReadOnlyList<PolicySnapshot>> ListAsync(int limit, CancellationToken cancellationToken = default)
+    {
+        await _mutex.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            IEnumerable<PolicySnapshot> query = _snapshots;
+            if (limit > 0)
+            {
+                query = query.TakeLast(limit);
+            }
+
+            return query.ToImmutableArray();
+        }
+        finally
+        {
+            _mutex.Release();
+        }
+    }
+}

src/Policy/__Libraries/StellaOps.Policy/TASKS.md

@@ -0,0 +1,38 @@
+# Policy Engine Task Board — Epic 1: Aggregation-Only Contract
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| POLICY-AOC-19-001 | TODO | Policy Guild | WEB-AOC-19-003 | Add Roslyn/CI lint preventing ingestion projects from referencing Policy merge/severity helpers; block forbidden writes at compile time. | Analyzer fails builds when ingestion projects set banned keys or reference Policy-only namespaces; CI pipeline wired. |
+| POLICY-AOC-19-002 | TODO | Policy Guild, Platform Security | AUTH-AOC-19-001 | Enforce `effective_finding_*` write gate ensuring only Policy Engine identity can create/update materializations. | Guard rejects non-Policy identities with `ERR_AOC_006`; integration tests validate authorized writes; logs contain audit trail. |
+| POLICY-AOC-19-003 | TODO | Policy Guild | CONCELIER-CORE-AOC-19-004, EXCITITOR-CORE-AOC-19-004 | Update readers/processors to consume only `content.raw`, `identifiers`, and `linkset`. Remove dependencies on legacy normalized fields and refresh fixtures. | All policy pipelines pass tests using raw inputs; fixture diff shows no derived data persisted in ingestion; docs updated. |
+| POLICY-AOC-19-004 | TODO | Policy Guild, QA Guild | POLICY-AOC-19-003 | Add regression tests ensuring policy derived outputs remain deterministic when ingesting revised raw docs (supersedes) and when violations occur. | Determinism suite passes; new fixtures prove policy recomputation handles append-only raw data and surfaces guard violations. |
+
+> Epic 2 service implementation tasks now live under `src/Policy/StellaOps.Policy.Engine/TASKS.md`. Keep library-specific work in this file.
+
+## Policy Engine + Editor v1 (Epic 5)
+
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| POLICY-SPL-23-001 | TODO | Policy Guild, Language Infrastructure Guild | POLICY-ENGINE-20-001 | Define SPL v1 YAML + JSON Schema, including advisory rules, VEX precedence, severity mapping, exceptions, and layering metadata. Publish schema resources and validation fixtures. | Schema files committed under `Schemas/`; validation tests cover representative policies; documentation draft ready. |
+| POLICY-SPL-23-002 | TODO | Policy Guild | POLICY-SPL-23-001 | Implement canonicalizer that normalizes policy packs (ordering, defaults), computes content hash, and prepares bundle metadata for AOC/signing. | Canonicalizer produces deterministic output (tests across permutations); hash matches spec; integration wired into compiler. |
+| POLICY-SPL-23-003 | TODO | Policy Guild | POLICY-SPL-23-001 | Build policy layering/override engine (global/org/project/env/exception) with field-level precedence matrices; add unit/property tests. | Layering engine honors override rules, rejects widening overrides; property tests ensure determinism. |
+| POLICY-SPL-23-004 | TODO | Policy Guild, Audit Guild | POLICY-SPL-23-002 | Design explanation tree model (rule hits, inputs, decisions) and persistence structures reused by runtime, UI, and CLI. | Explanation DTOs published; serialization deterministic; tests cover nested explanations. |
+| POLICY-SPL-23-005 | TODO | Policy Guild, DevEx Guild | POLICY-SPL-23-001 | Create migration tool to snapshot existing behavior into baseline SPL packs (`org.core.baseline`), including policy docs and sample bundles. | Tool emits baseline policy pack + tests verifying parity against legacy behavior; documentation updated. |
+
+## Exceptions v1 (Epic 7)
+
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| POLICY-EXC-25-001 | DONE (2025-10-27) | Policy Guild, Governance Guild | POLICY-SPL-23-001 | Extend SPL schema/spec to reference exception effects and routing templates; publish updated docs and validation fixtures. | Schema updated with exception references; validation tests cover effect types; docs draft ready. |
+
+## Reachability v1 (Epic 8)
+
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| POLICY-SPL-24-001 | TODO | Policy Guild, Signals Guild | SIGNALS-24-004 | Extend SPL schema to expose reachability/exploitability predicates and weighting functions; update documentation and fixtures. | Schema updated; validation fixtures for reachability rules; docs ready for review. |
+
+## Risk Profiles (Epic 18)
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| POLICY-RISK-66-004 | TODO | Policy Guild, Risk Profile Schema Guild | POLICY-RISK-66-001 | Extend Policy libraries to load/save RiskProfile documents, compute content hashes, and surface validation diagnostics. | Libraries serialize/deserialize profiles; hash deterministic; tests cover invalid input. |
+| POLICY-RISK-67-003 | TODO | Policy Guild, Risk Engine Guild | POLICY-RISK-66-004, RISK-ENGINE-69-001 | Provide policy-layer APIs to trigger risk simulations and return distributions/contribution breakdowns. | API returns simulation payload; golden tests match expected output. |
+| POLICY-RISK-68-002 | TODO | Policy Guild, Export Guild | POLICY-RISK-66-004 | Enable exporting/importing RiskProfiles with signatures via policy tooling (CLI + API). | Export/import round-trip tested; signatures verified; docs updated. |