prep docs and service updates

docs/modules/policy/prep/2025-11-20-advisory-ai-knobs-prep.md

@@ -0,0 +1,25 @@
+# Advisory AI Knobs Prep — PREP-POLICY-ENGINE-31-001-ADVISORY-AI-KNOBS-R
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Outline the configuration knobs for Advisory AI scoring once trust weighting (30-101) is defined.
+
+## Dependencies
+- Trust weighting API/contracts (30-101).
+- Advisory AI signal list and confidence model (not yet finalized).
+
+## Draft configuration fields
+- `weights` (from 30-101) applied to AI-produced signals.
+- `knobs[]` array of `{name, default_value, min, max, step, description}` for:
+  - `ai_signal_weight`
+  - `reachability_boost`
+  - `time_decay_half_life_days`
+  - `evidence_freshness_threshold_hours`
+- Output preview: recomputed severity/exploitability per advisory/component.
+
+## Acceptance to close PREP
+- Map knobs to actual AI signals once published; confirm allowed ranges.
+- Document schema at `docs/modules/policy/schemas/advisory-ai-knobs@draft.json` and sample request at `docs/modules/policy/samples/advisory-ai-knobs@draft.json`.
+
+## Handoff
+Use this document as the prep artefact for PREP-POLICY-ENGINE-31-001-ADVISORY-AI-KNOBS-R. Update with final signal list and ranges once trust weighting is frozen.

docs/modules/policy/prep/2025-11-20-batch-context-prep.md

@@ -0,0 +1,21 @@
+# Batch Context Endpoint Prep — PREP-POLICY-ENGINE-31-002-BATCH-CONTEXT-ENDPO
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Define the batch context endpoint contract that builds on Advisory AI knobs (31-001) and trust weighting outputs.
+
+## Dependencies
+- Final knobs list from 31-001.
+- Policy profile schema (hash + version) from 30-001 overlays.
+
+## Draft API surface
+- `POST /policy/batch/context` with payload: `{tenant_id, policy_profile_hash, knobs_version, overlay_hash, items:[{component_purl, advisory_id}], options:{include_reachability:boolean}}`.
+- Response: `{context_id, expires_at, knobs_version, overlay_hash, items:[{component_purl, advisory_id, status, trace_ref}]}`.
+- Determinism: items sorted by `(component_purl, advisory_id)`; `context_id` derived as hash of request payload.
+
+## Acceptance to close PREP
+- Align fields with 31-001 knobs and 30-001 overlay schema; record hashes/versions.
+- Save draft schema at `docs/modules/policy/schemas/policy-batch-context@draft.json` and sample at `docs/modules/policy/samples/policy-batch-context@draft.json`.
+
+## Handoff
+Use this document as the prep artefact for PREP-POLICY-ENGINE-31-002-BATCH-CONTEXT-ENDPO. Update when knobs and overlays freeze; then move implementation to DOING.

docs/modules/policy/prep/2025-11-20-change-events-prep.md

@@ -0,0 +1,23 @@
+# Change Events Prep — PREP-POLICY-ENGINE-30-003-CHANGE-EVENTS-DEPEN
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · Scheduler Guild · Cartographer Guild
+Scope: Define the change-event payload and scheduling expectations following simulation bridge (30-002).
+
+## Dependencies
+- Simulation bridge output schema (30-002).
+- Scheduler delivery channel (NATS/Redis) subject names and dedupe policy.
+
+## Draft event envelope
+- `event_type`: `policy.overlay.change`
+- Fields: `tenant_id`, `overlay_hash`, `policy_profile_hash`, `simulation_id?`, `changes[]` (array of `{component_purl, advisory_id, prev_status, new_status, severity_delta?, trace_ref}`), `occurred_at` (UTC), `event_id` (deterministic ID = hash of overlay_hash + timestamp).
+- Transport: propose NATS subject `policy.overlay.change` with durable stream; idempotency key = `event_id`.
+- Observability: counter `policy_overlay_change_total{tenant,result}`; log template includes overlay_hash, event_id, change_count.
+
+## Acceptance to close PREP
+- Subject/stream names confirmed with Scheduler.
+- JSON schema stub saved at `docs/modules/policy/schemas/policy-overlay-change@draft.json`.
+- Sample event at `docs/modules/policy/samples/policy-overlay-change@draft.json`.
+
+## Handoff
+This document serves as the prep artefact for PREP-POLICY-ENGINE-30-003-CHANGE-EVENTS-DEPEN. Update once 30-002 finalizes schema/subject; then unblock the implementation task.

docs/modules/policy/prep/2025-11-20-conflict-handling-prep.md

@@ -0,0 +1,21 @@
+# Conflict Handling Prep — PREP-POLICY-ENGINE-40-002-CONFLICT-HANDLING-D
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · Excititor Guild
+Scope: Define conflict-handling rules after severity fusion (40-001).
+
+## Dependencies
+- Severity fusion output schema (40-001).
+- Excititor/Console precedence context expectations for conflicts.
+
+## Draft approach
+- Detect conflicts when multiple fused severities differ for same `{component_purl, advisory_id}` across tenants or sources.
+- Emit conflict record: `{tenant_id, component_purl, advisory_id, conflicts:[{source, field, value, reason_code}] , resolved_status?, trace_ref}`.
+- Resolution policy: default “no auto-resolve”; optional operator override flag per policy profile.
+
+## Acceptance
+- Draft schema at `docs/modules/policy/schemas/policy-conflict@draft.json` and sample at `docs/modules/policy/samples/policy-conflict@draft.json`.
+- Mapping of reason codes to Excititor Console cache/RBAC needs documented once 23-003 finalizes.
+
+## Handoff
+This document is the prep artefact for PREP-POLICY-ENGINE-40-002-CONFLICT-HANDLING-D. Update once severity fusion rules are frozen and Console expectations are known; then move implementation to DOING.

docs/modules/policy/prep/2025-11-20-ledger-export-prep.md

@@ -0,0 +1,21 @@
+# Ledger Export Prep — PREP-POLICY-ENGINE-34-101-LEDGER-EXPORT-REQUI
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Define ledger export requirements once worker results (33-101) exist.
+
+## Dependencies
+- Worker result schema (33-101).
+- Storage/ledger format choice (Mongo vs Postgres) and retention policy.
+
+## Draft export shape
+- Export file: NDJSON with entries `{tenant_id, job_id, context_id, component_purl, advisory_id, status, trace_ref, occurred_at}`.
+- Manifest: `{export_id, schema_version, generated_at, record_count, sha256}` with DSSE envelope optional.
+- Ordering: stable by `(tenant_id, job_id, component_purl, advisory_id)`.
+
+## Acceptance
+- Draft schema at `docs/modules/policy/schemas/policy-ledger-export@draft.json` and sample at `docs/modules/policy/samples/policy-ledger-export@draft.json`.
+- Retention knobs documented (TTL/size caps) once storage decision is made.
+
+## Handoff
+Use this as the prep artefact for PREP-POLICY-ENGINE-34-101-LEDGER-EXPORT-REQUI. Update with storage/retention decisions, then unblock implementation.

docs/modules/policy/prep/2025-11-20-orchestrator-job-schema-prep.md

@@ -0,0 +1,21 @@
+# Orchestrator Job Schema Prep — PREP-POLICY-ENGINE-32-101-ORCHESTRATOR-JOB-SC
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Outline the job schema needed for orchestrator scheduling once batch context (31-002) is available.
+
+## Dependencies
+- Batch context contract (31-002).
+- Orchestrator capsule envelope (Wave 150/140) for job submission fields.
+
+## Draft job schema
+- Fields: `job_id` (ULID), `tenant_id`, `context_id` (from 31-002), `policy_profile_hash`, `requested_at`, `priority`, `batch_items[]` referencing `{component_purl, advisory_id}`, `callbacks` (SSE/NATS subjects), `trace_ref` (dsse hash).
+- Status lifecycle: `queued` → `running` → `completed`|`failed`; deterministic transitions logged.
+- Determinism: job_id derived from hash of `(tenant_id, context_id, requested_at ISO)`, ordered batch_items.
+
+## Acceptance
+- Schema stub stored at `docs/modules/policy/schemas/orchestrator-job@draft.json` plus sample at `docs/modules/policy/samples/orchestrator-job@draft.json`.
+- Subject/callback expectations aligned with Orchestrator envelopes.
+
+## Handoff
+Prep artefact for PREP-POLICY-ENGINE-32-101-ORCHESTRATOR-JOB-SC. Update with final Orchestrator envelope fields and batch context hash once available.

docs/modules/policy/prep/2025-11-20-policy-airgap-56-002-prep.md

@@ -0,0 +1,21 @@
+# Policy AirGap Import Prep — PREP-POLICY-AIRGAP-56-002-DEPENDS-ON-56-001-B
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · Policy Studio Guild
+Scope: Define policy bundle import and DSSE signing expectations once mirror bundle schema (56-001) is fixed.
+
+## Dependencies
+- Mirror bundle schema from 56-001 (fields: bundle_id, provenance, policy_hash, trust_roots, retained_at).
+- DSSE signing profile and RootPack mapping.
+
+## Expected contract
+- Import endpoint: `POST /policy/airgap/import` accepting mirror bundle (file) + metadata.
+- Validation: verify DSSE, trust roots, policy hashes; reject on staleness over budget.
+- Response: `{bundle_id, policy_hash, imported_at, staleness_seconds}` ordered deterministically.
+
+## Acceptance
+- Once 56-001 schema is frozen, record hash+version here and in sprint Decisions.
+- Add sample request/response to `docs/modules/policy/design/policy-mirror-bundle-schema.md` and samples folder.
+
+## Handoff
+Use this doc as the prep artefact for PREP-POLICY-AIRGAP-56-002-DEPENDS-ON-56-001-B. Update with schema hash and DSSE profile when available, then move sprint task to DONE.

docs/modules/policy/prep/2025-11-20-policy-airgap-57-001-prep.md

@@ -0,0 +1,21 @@
+# Policy AirGap Sealed-Mode Prep — PREP-POLICY-AIRGAP-57-001-REQUIRES-SEALED-MOD
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · AirGap Policy Guild
+Scope: Define sealed-mode policy behaviour and error envelopes after mirror import (56-002).
+
+## Inputs needed
+- Sealed-mode error envelope standard (WEB-OAS-61-002) for consistency with Concelier/Web.
+- Staleness metadata fields from 56-002 (bundle provenance / time anchor).
+
+## Proposed behavior
+- When sealed mode active and non-mirror source requested, return error `POLICY_AIRGAP_EGRESS_BLOCKED` with remediation list and `staleness_seconds_remaining` if available.
+- Determinism: sorted remediation items; canonical JSON ordering.
+- Telemetry: counter `policy_airgap_egress_blocked_total{tenant,endpoint}` and event `policy.airgap.egress_blocked` with `{tenant_id, bundle_id?, policy_hash}`.
+
+## Acceptance
+- Envelope finalized in line with WEB-OAS-61-002; fields confirmed with AirGap Policy Guild.
+- Sample response stored at `docs/modules/policy/samples/policy-airgap-sealed@draft.json`.
+
+## Handoff
+Prep artefact for PREP-POLICY-AIRGAP-57-001-REQUIRES-SEALED-MOD. Update once error envelope and staleness fields are frozen; then mark task DONE and start implementation.

docs/modules/policy/prep/2025-11-20-policy-airgap-57-002-prep.md

@@ -0,0 +1,21 @@
+# Policy Staleness Fallback Prep — PREP-POLICY-AIRGAP-57-002-NEEDS-STALENESS-FAL
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · AirGap Time Guild
+Scope: Define staleness/fallback data contract for policy responses once sealed-mode (57-001) is defined.
+
+## Dependencies
+- Sealed-mode error envelope (57-001).
+- Time anchor/staleness metadata from AirGap Controller/Time (56-002 chain).
+
+## Proposed additions
+- Response headers: `x-policy-bundle-id`, `x-policy-staleness-seconds-remaining`.
+- Body enrichment: `staleness_seconds_remaining`, `bundle_id`, optional `time_anchor_id` in error responses or health endpoints.
+- Determinism: values sourced from stored bundle metadata; no wall-clock dependencies beyond persisted timestamps.
+
+## Acceptance
+- Confirm header names with AirGap Time Guild and align with Concelier Web sealed responses.
+- Sample response documented under `docs/modules/policy/samples/policy-staleness@draft.json`.
+
+## Handoff
+Use this prep doc to satisfy PREP-POLICY-AIRGAP-57-002-NEEDS-STALENESS-FAL. Update with final header names and sample once 57-001 and 56-002 stabilize; then mark task DONE.

docs/modules/policy/prep/2025-11-20-policy-airgap-58-001-prep.md

@@ -0,0 +1,21 @@
+# Policy AirGap Notifications Prep — PREP-POLICY-AIRGAP-58-001-NOTIFICATION-SCHEMA
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · Notifications Guild
+Scope: Define notification schema and staleness signals after staleness fallback (57-002).
+
+## Dependencies
+- Staleness metadata fields from 57-002.
+- Notifications envelope alignment with Orchestrator/Notifications schema.
+
+## Draft notification
+- Event: `policy.airgap.bundle.updated`
+- Fields: `tenant_id`, `bundle_id`, `policy_hash`, `staleness_seconds_remaining`, `time_anchor_id?`, `occurred_at`, `event_id`.
+- Transport: NATS subject `policy.airgap.bundle.updated`; durable stream; idempotency via `event_id` (hash of bundle_id + occurred_at).
+
+## Acceptance
+- Schema sample stored at `docs/modules/policy/samples/policy-airgap-notification@draft.json`.
+- Subject/retention agreed with Notifications Guild.
+
+## Handoff
+Prep artefact for PREP-POLICY-AIRGAP-58-001-NOTIFICATION-SCHEMA. Fill in schema hash/subject once 57-002 finalizes; then move to DONE.

docs/modules/policy/prep/2025-11-20-policy-aoc-19-001-prep.md

@@ -0,0 +1,17 @@
+# Policy Linting Prep — PREP-POLICY-AOC-19-001-NEEDS-AGREED-LINTING-T
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Define lint/analyzer targets for Policy AOC ingestion paths to unblock linting tasks.
+
+## Required decisions
+- Target projects: `StellaOps.Policy.Engine`, `StellaOps.Policy.*` libraries to include; excluded generated files.
+- Rule set: nullability, async/sync mix, determinism (no DateTime.Now/Guid.NewGuid), ordering, and JSON property ordering rules.
+- CI wiring: which pipeline, severity thresholds, baselines.
+
+## Acceptance
+- Publish agreed rule set and target list in `docs/modules/policy/design/policy-aoc-linting-rules.md`.
+- Add baseline suppressions file path if needed.
+
+## Handoff
+Use this doc as the prep artefact for PREP-POLICY-AOC-19-001-NEEDS-AGREED-LINTING-T. Update with agreed rule set; then mark the sprint task DONE.

docs/modules/policy/prep/2025-11-20-policy-aoc-19-002-prep.md

@@ -0,0 +1,20 @@
+# Policy AOC Gate Prep — PREP-POLICY-AOC-19-002-DEPENDS-ON-19-001-LINT
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · Platform Security
+Scope: Capture gate requirements after linting rules (19-001) are defined.
+
+## Dependencies
+- Agreed lint rule set from 19-001.
+- Authority contract for `effective:write` gate.
+
+## Proposed gate
+- CI gate checks lint + determinism rules; blocks PRs without suppressions approval.
+- Requires `effective:write` or similar scope for rule bypass; audit logged.
+
+## Acceptance
+- Document gate behavior in `docs/modules/policy/design/policy-aoc-gate.md` and add sample CI snippet.
+- Record Authority scope names once confirmed.
+
+## Handoff
+Use this prep doc for PREP-POLICY-AOC-19-002-DEPENDS-ON-19-001-LINT. Update when lint rules and auth scopes are finalized; then mark task DONE and unblock implementation.

docs/modules/policy/prep/2025-11-20-policy-aoc-19-003-prep.md

@@ -0,0 +1,21 @@
+# Policy Normalized Field Removal Prep — PREP-POLICY-AOC-19-003-REQUIRES-DECISIONED-NO
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Define decisioned normalized-field removal once gate (19-002) is in place.
+
+## Dependencies
+- Gate/lint outcomes from 19-002.
+- Decision on which normalized fields to drop vs keep (need product/architecture sign-off).
+
+## Draft plan
+- Candidate fields to remove: legacy `normalized_score`, deprecated `source_rank`, any duplicated severity fields.
+- Keep: deterministic canonical severity, policy profile hashes.
+- Output: migration plan + fixtures showing before/after payloads.
+
+## Acceptance
+- Agree field list and migration steps; document in `docs/modules/policy/design/policy-normalized-field-removal.md`.
+- Fixtures placed under `docs/modules/policy/samples/policy-normalized-field-removal*.json`.
+
+## Handoff
+Prep artefact for PREP-POLICY-AOC-19-003-REQUIRES-DECISIONED-NO. Update with final field list once decisions made; then mark sprint task DONE.

docs/modules/policy/prep/2025-11-20-policy-aoc-19-004-prep.md

@@ -0,0 +1,20 @@
+# Policy Determinism Fixtures Prep — PREP-POLICY-AOC-19-004-DEPENDENT-ON-19-003-DA
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · QA Guild
+Scope: Define data shape and determinism fixtures after normalized-field decisions (19-003).
+
+## Dependencies
+- Field removal list from 19-003.
+- Deterministic ordering/canonical JSON rules.
+
+## Plan
+- Prepare fixtures showing deterministic ordering and absence of removed fields.
+- Add test harness notes for `StellaOps.Policy` libraries to validate canonical JSON and stable sorting.
+
+## Acceptance
+- Fixtures placed under `docs/modules/policy/samples/policy-determinism-fixtures@draft.json`.
+- Update `docs/modules/policy/design/policy-determinism-tests.md` with expectations.
+
+## Handoff
+Use this prep doc for PREP-POLICY-AOC-19-004-DEPENDENT-ON-19-003-DA. Update once field removal list is frozen; then mark task DONE and unblock implementation tests.

docs/modules/policy/prep/2025-11-20-policy-attest-73-001-prep.md

@@ -0,0 +1,29 @@
+# Policy Attestation Prep — PREP-POLICY-ATTEST-73-001
+
+Status: **Ready for implementation** (2025-11-20)
+Owners: Policy Guild · Attestor Service Guild
+Scope: Define VerificationPolicy schema + persistence/DTOs for policy-engine to verify attestation results from Attestor.
+
+## Requirements
+- Schema `VerificationPolicy` with fields:
+  - `id` (string), `tenantId`, `name`, `description`, `createdAtUtc`, `updatedAtUtc` (ISO-8601 UTC)
+  - `subjects`: array of `{ subjectRef, matchKind: digest|purl|nevra }`
+  - `requiredAttestors`: array of `{ name, keyId, threshold }`
+  - `transparency`: `{ required: bool, log: string? }`
+  - `validity`: `{ notBeforeUtc, notAfterUtc }`
+- DTOs for API/SDK must preserve deterministic ordering of arrays (sorted by `subjectRef`, then `name`).
+- Store in Mongo `verificationPolicies` collection with unique index on `(tenantId, id)`.
+
+## API surface (policy-engine)
+- `POST /v1/policy/verification-policies` create; `GET /v1/policy/verification-policies/{id}` fetch; `GET /v1/policy/verification-policies` list with pagination; `DELETE /v1/policy/verification-policies/{id}`.
+- Standard error envelope; headers align with existing policy API (ETag on GET; `Last-Modified`).
+
+## Persistence rules
+- Immutable `createdAtUtc`; `updatedAtUtc` set on mutations; soft-delete not required.
+- Validation: `requiredAttestors.threshold >=1`, unique `keyId` per policy, `validity.notAfterUtc` > `notBeforeUtc`.
+
+## Acceptance criteria
+- Schema & API documented and linked from sprint tracker; no code changes yet.
+- Examples use fixed timestamps `2025-01-01T00:00:00Z` and sample hashes `sha256:0123...`.
+- Collections/indexes specified; DTO ordering deterministic.
+

docs/modules/policy/prep/2025-11-20-policy-attest-73-002-prep.md

@@ -0,0 +1,15 @@
+# Policy Attestation Prep — PREP-POLICY-ATTEST-73-002
+
+Status: **Ready for implementation** (2025-11-20)
+Owners: Policy Guild
+Scope: Define editor DTOs/validation schema for linking VerificationPolicy (73-001) into policy-engine UI/SDK.
+
+## Requirements
+- Editor DTO `VerificationPolicyUpdate` with fields mirroring 73-001 schema; arrays sorted.
+- Validation rules: same as 73-001, plus max subjects = 500, max requiredAttestors = 20.
+- Error codes: `ValidationFailed`, `DuplicateKey`, `NotFound`.
+
+## Acceptance criteria
+- DTOs + validation rules documented; examples with fixed timestamps and hashes.
+- SDK notes: generated models should expose immutable collections and validation annotations.
+

docs/modules/policy/prep/2025-11-20-policy-attest-74-001-prep.md

@@ -0,0 +1,15 @@
+# Policy Attestation Prep — PREP-POLICY-ATTEST-74-001
+
+Status: **Ready for implementation** (2025-11-20)
+Owners: Policy Guild · Attestor Service Guild
+Scope: Define policy-engine surface to consume attestation verification results (from 73-002) and expose in reports/notifications.
+
+## Requirements
+- Add projection schema `PolicyAttestationResult` with fields `{ policyId, verificationPolicyId, attestationId, status: passed|failed|pending, verifiedAtUtc, evidenceBundleId?, notes }`.
+- API endpoint `GET /v1/policy/attestations/{policyId}` returning paged results; supports filters `status`, `verificationPolicyId`.
+- Timeline/notification hook placeholder (depends on envelope schemas) noted; not required to implement now.
+
+## Acceptance criteria
+- Schema, endpoint, filters documented with deterministic examples (timestamps `2025-01-01T00:00:00Z`).
+- Status set to DONE once doc published; code follows in dependent tasks.
+

docs/modules/policy/prep/2025-11-20-policy-attest-74-002-prep.md

@@ -0,0 +1,15 @@
+# Policy Attestation Prep — PREP-POLICY-ATTEST-74-002
+
+Status: **Ready for implementation** (2025-11-20)
+Owners: Policy Guild · Console Guild
+Scope: Surface 74-001 attestation results into Console verification reports.
+
+## Requirements
+- Console payload extension: add `policyAttestations` array to verification report DTO with `{ policyId, verificationPolicyId, status, verifiedAtUtc }`.
+- Sorting: order by `policyId` then `verifiedAtUtc`.
+- Backward compatibility: field optional; default empty array.
+
+## Acceptance criteria
+- DTO change documented; examples with fixed timestamp; no code yet.
+- Update sprint tracker once doc published.
+

docs/modules/policy/prep/2025-11-20-policy-engine-20-002-prep.md

@@ -0,0 +1,18 @@
+# Deterministic Evaluator Prep — PREP-POLICY-ENGINE-20-002-BUILD-DETERMINISTIC
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Capture contract and constraints for deterministic policy evaluator before implementation.
+
+## Requirements
+- Deterministic execution: no wall-clock, no RNG, no network; inputs must be content-addressed.
+- Ordering: lexical rule ordering; first-match semantics; stable reduction order over inputs.
+- Safe value types: disallow floats where not needed; prefer decimal with fixed scale.
+- Timestamps: if required, use supplied `context.now` injected value, not system clock.
+
+## Deliverables
+- Document evaluator contract and constraints in `docs/modules/policy/design/deterministic-evaluator.md`.
+- Provide sample config and test vectors under `docs/modules/policy/samples/deterministic-evaluator/` (hashes recorded in the design doc).
+
+## Handoff
+Use this doc as the prep artefact for PREP-POLICY-ENGINE-20-002-BUILD-DETERMINISTIC. Once constraints and samples are frozen, mark the sprint task DONE and unblock POLICY-ENGINE-20-002.

docs/modules/policy/prep/2025-11-20-policy-engine-29-002-prep.md

@@ -0,0 +1,44 @@
+# Policy Engine · Path/Scope Schema Prep (POLICY-ENGINE-29-002)
+
+- **Date:** 2025-11-20
+- **Working directory:** `src/Policy/StellaOps.Policy.Engine`
+- **Purpose:** Unblock path-aware evaluation chain (tasks 29-003/004 and overlays 30-001..30-003) by freezing the canonical path/scope schema and examples.
+
+## Schema (authoritative fields)
+`PathScope` object used across evaluator inputs, telemetry, and snapshots:
+- `tenant` (string, required) — tenant isolation key.
+- `subject` (object) — affected asset:
+  - `purl` (string) or `cpe` (string) — at least one required.
+  - `packagePath` (string, optional) — normalized module path within package (e.g., `lib/utils/a.js`).
+  - `osImage` (string, optional) — container image ref if OS-level advisory.
+- `locator` (object) — where evidence was found:
+  - `filePath` (string, required) — repo or image path using POSIX separators.
+  - `digest` (string, optional) — SHA-256 of file content; hex, lowercase.
+  - `treeDigest` (string, optional) — Merkle root for build tree snapshot.
+- `vulnerability` (object) — identifiers present in evidence (facts only): `cve`, `ghsa`, `osv`, `advisoryId`, `source`.
+- `provenance` (object) — `ingestedAt` (ISO-8601 UTC), `evidenceHash` (hex), `connectorId` (string), `dsseEnvelopeHash` (optional hex) for replay.
+- `scope` (object) — evaluation bounding box:
+  - `pathMatch` (enum) `exact|prefix|glob` with `pattern` (string) using POSIX separators.
+  - `confidence` (float 0..1) — how confident the analyzer is about the path binding.
+  - `depthLimit` (int, optional) — maximum traversal depth for prefix/glob bindings.
+
+## Determinism
+- Canonical ordering: subject fields ordered as listed; pathMatch evaluation uses lexical order, then `confidence` desc, then `filePath` asc for tie-breaking.
+- Hashing: `evidenceHash` = SHA-256 over normalized JSON of the observation with sorted properties and UTF-8 encoding.
+
+## Sample payload
+```json
+{
+  "tenant": "acme",
+  "subject": {"purl": "pkg:npm/lodash@4.17.21", "packagePath": "lib/isEqual.js"},
+  "locator": {"filePath": "src/lib/isEqual.js", "digest": "c1ab..."},
+  "vulnerability": {"ghsa": "GHSA-35jh-r3h4-6jhm", "source": "ghsa"},
+  "provenance": {"ingestedAt": "2025-11-20T00:00:00Z", "evidenceHash": "4f9b...", "connectorId": "excititor-ghsa"},
+  "scope": {"pathMatch": "prefix", "pattern": "src/lib/", "confidence": 0.92, "depthLimit": 3}
+}
+```
+
+## Acceptance for prep completion
+- Path/Scope schema above is frozen for sprint 0125; downstream tasks must align or update this doc and sprint risks if changes occur.
+- Sample payload provided for fixtures/tests; hashing and ordering rules documented for determinism.
+

docs/modules/policy/prep/2025-11-20-policy-engine-29-004-prep.md

@@ -0,0 +1,25 @@
+# Policy Engine · Path-Aware Observability Prep (POLICY-ENGINE-29-004)
+
+- **Date:** 2025-11-20
+- **Depends on:** Path/Scope schema (29-002)
+- **Working directory:** `src/Policy/StellaOps.Policy.Engine`
+
+## Metrics (Meter prefix `StellaOps.Policy.Engine`)
+- `policy.path.eval.total` (counter) — tags: `tenant`, `subject` (purl/cpe simplified), `result` (`allow|deny|error`), `ruleId` (short slug), `pathMatch` (`exact|prefix|glob`).
+- `policy.path.eval.duration.ms` (histogram) — tags: `tenant`, `subject`, `ruleId`.
+- `policy.path.eval.cache.hit` (counter) — tags: `tenant`, `cache` (`rule|decision`), `hit` (`true|false`).
+- `policy.path.eval.scope.mismatch` (counter) — tags: `tenant`, `reason` (`no-scope|depth-limit|confidence-low`).
+- `policy.path.eval.coverage` (gauge/exported via observable gauge) — value: % of observations with matching scope; tags: `tenant`, `source`.
+
+## Logs
+- Structured log name `Policy.PathEval` with fields: `tenant`, `ruleId`, `subject` (purl/cpe), `filePath`, `pathMatch`, `pattern`, `confidence`, `decision`, `durationMs`, `evidenceHash`, `correlationId`.
+- Errors must include `errorCode` (enum: `scope-missing`, `scope-conflict`, `rule-missing`, `runtime-error`).
+
+## Events (optional OTEL spans)
+- Span name: `policy.path.evaluate`; attributes mirror log fields plus `ruleVersion`, `treeDigest?`, `dsseEnvelopeHash?` for replay traces.
+
+## Acceptance for prep completion
+- Metric/log/span names and required tags are frozen for downstream instrumentation.
+- Implementations must use path/scope schema from 29-002 for tag normalization.
+- Targets max cardinality: ruleId short slug (<=32 chars), subject truncated to package name (no version) to keep series bounded.
+

docs/modules/policy/prep/2025-11-20-policy-engine-30-001-prep.md

@@ -0,0 +1,32 @@
+# Policy Engine · Overlay Projection Prep (POLICY-ENGINE-30-001)
+
+- **Date:** 2025-11-20
+- **Depends on:** Path/Scope schema (29-002) and observability contract (29-004)
+- **Working directory:** `src/Policy/StellaOps.Policy.Engine`
+
+## Projection contract
+- Input: `PathScope` documents (see 29-002) + `PolicyRule` definitions.
+- Output: `OverlayProjection` objects stored/snapshotted for replay:
+  - `tenant` (string)
+  - `ruleId` (string)
+  - `subject` (purl/cpe, optional packagePath)
+  - `scope` (copied from input)
+  - `decision` (`allow|deny|warn|defer`)
+  - `reasons[]` (machine-readable codes; e.g., `path-match`, `severity-threshold`, `capability-needed`)
+  - `artifacts` (hash list) — `evidenceHash`, `treeDigest?`, `dsseEnvelopeHash?` used in evaluation
+  - `effectiveAt` (ISO-8601 UTC) — time projection became active
+  - `expiresAt?` (ISO-8601 UTC) — optional
+  - `version` (int) — monotonic per ruleId
+
+## Ordering & determinism
+- Projection list sorted by (`ruleId`, `subject.purl|cpe`, `scope.pathMatch`, `scope.pattern`, `effectiveAt`).
+- Hash for `artifacts.evidenceHash` reused from input to keep replay stable.
+
+## Storage hints
+- Persist overlays as NDJSON under `overlay/{tenant}/{ruleId}/{version}.ndjson` for air-gapped export.
+- Snapshots include header line with schema version `overlay-projection-v1` followed by sorted projections.
+
+## Acceptance for prep completion
+- Projection shape, ordering, and filenames are frozen for implementation tasks 30-001..30-003.
+- Downstream simulation/change-event work (30-002/30-003) must emit/consume this structure without mutation.
+

docs/modules/policy/prep/2025-11-20-policy-engine-30-002-prep.md

@@ -0,0 +1,27 @@
+# Policy Engine · Simulation Bridge Prep (POLICY-ENGINE-30-002)
+
+- **Date:** 2025-11-20
+- **Depends on:** Overlay projection (30-001)
+- **Working directory:** `src/Policy/StellaOps.Policy.Engine`
+
+## Simulation request schema
+- `tenant` (string)
+- `rules[]` (string) — ruleIds to simulate; if empty, simulate all active rules.
+- `overlays[]` (optional) — inline `OverlayProjection` objects to test hypothetical changes without persisting.
+- `paths[]` — array of `PathScope` inputs.
+- `mode` (`preview|whatif`) — `preview` returns decisions only; `whatif` also returns delta vs current overlays.
+- `seed` (int, optional) — for deterministic randomization if simulations sample paths.
+
+## Response schema
+- `decisions[]` — per PathScope result: `pathScope`, `decision`, `reasons[]`, `ruleId`, `version`, `effectiveAt`.
+- `deltas[]` (only for `whatif`) — entries with `ruleId`, `baselineDecision`, `candidateDecision`, `diffReason`.
+- `metrics` — echo of counters: `evaluated`, `allowed`, `denied`, `warned`, `deferred` for quick UI.
+
+## Determinism rules
+- When `seed` absent, use fixed seed `0xC0DEC0DE` for any randomized sampling.
+- Responses ordered by input `paths[]` index, then `ruleId`.
+
+## Acceptance for prep completion
+- Simulation schemas are frozen; downstream UI/CLI harnesses can rely on shapes and ordering.
+- Delta semantics clarified to unblock change-event publication (30-003).
+

docs/modules/policy/prep/2025-11-20-policy-engine-30-003-prep.md

@@ -0,0 +1,30 @@
+# Policy Engine · Change Events Prep (POLICY-ENGINE-30-003)
+
+- **Date:** 2025-11-20
+- **Depends on:** Overlay projection (30-001) and simulation bridge (30-002)
+- **Working directory:** `src/Policy/StellaOps.Policy.Engine`
+
+## Event envelope
+- Topic: `policy.overlay.changed`
+- Payload fields:
+  - `tenant` (string)
+  - `ruleId` (string)
+  - `version` (int) — matches projection version
+  - `changeType` (`created|updated|deprecated|deleted`)
+  - `projection` (OverlayProjection) — single item; for `deleted`, include last-known `projection` with `decision: "defer"`.
+  - `delta` (object, optional) — produced when triggered from simulation `whatif`: `baselineDecision`, `candidateDecision`, `diffReason`.
+  - `artifacts` — `evidenceHash`, `treeDigest?`, `dsseEnvelopeHash?`
+  - `emittedAt` (ISO-8601 UTC)
+  - `correlationId` (string) — propagate from incoming request or run id.
+
+## Delivery guarantees
+- At-least-once on the bus; projection storage is source of truth. Events carry idempotency key `tenant:ruleId:version`.
+- Ordering per `ruleId` is preserved by publishing after storage commit.
+
+## Consumers
+- Scheduler uses events to enqueue re-evaluation jobs keyed by `tenant` + `ruleId`.
+- UI/CLI preview listens for `changeType` ≠ `created` to refresh overlays without polling.
+
+## Acceptance for prep completion
+- Topic, payload, and idempotency key are fixed; downstream scheduler/UI/CLI can wire without further contract churn.
+

docs/modules/policy/prep/2025-11-20-severity-fusion-prep.md

@@ -0,0 +1,21 @@
+# Severity Fusion Prep — PREP-POLICY-ENGINE-40-001-SEVERITY-FUSION-DEP
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · Concelier Guild
+Scope: Capture severity fusion requirements using violation events (38-201).
+
+## Dependencies
+- Violation event schema (38-201).
+- Concelier severity sources + lattice rules; Policy weighting outputs (30-101).
+
+## Draft fusion rules
+- Inputs: violation events with status + severity + advisory/confidence.
+- Rules: deterministic lattice; combine source severities with weights from 30-101; tie-break via Concelier source ranking; emit `severity_fused`, `reason_codes[]`, `sources[]` with weights.
+- Determinism: sort sources lexicographically; fixed numeric precision (scale 3).
+
+## Acceptance
+- Schema draft at `docs/modules/policy/schemas/severity-fusion@draft.json` and sample at `docs/modules/policy/samples/severity-fusion@draft.json`.
+- Document weight caps and rounding rules.
+
+## Handoff
+Prep artefact for PREP-POLICY-ENGINE-40-001-SEVERITY-FUSION-DEP. Finalize once violation events and Concelier severity ranking are frozen.

docs/modules/policy/prep/2025-11-20-simulation-bridge-prep.md

@@ -0,0 +1,26 @@
+# Simulation Bridge Prep — PREP-POLICY-ENGINE-30-002-SIMULATION-BRIDGE-C
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild · Cartographer Guild
+Scope: Capture the required simulation bridge inputs and outputs so POLICY-ENGINE-30-002 can start once overlay schema (30-001) lands.
+
+## Dependencies
+- Overlay projection contract (30-001) — needs metrics/log schema from 29-004.
+- Cartographer graph API shape for reachability overlays.
+
+## Proposed contract (to validate once 30-001 freezes)
+- Input: overlay projection payload from 30-001 plus reachability summaries from Cartographer.
+- Output (draft schema):
+  - `simulation_id` (ULID), `tenant_id`, `scenario` descriptor.
+  - `inputs`: overlay snapshot hash, policy profile hash, reachability baseline hash.
+  - `results[]`: `{component_purl, advisory_id, status_before, status_after, reason, trace_ref}`.
+  - `metrics`: duration, rule_eval_count, graph_nodes_touched.
+- Determinism: stable ordering by `(tenant_id, component_purl, advisory_id)`; timestamps UTC RFC3339.
+
+## Acceptance to flip PREP to DONE
+- Overlay schema (30-001) version/Hash referenced in this file.
+- Draft JSON schema for simulation bridge saved under `docs/modules/policy/schemas/simulation-bridge@draft.json`.
+- Sample payload placed under `docs/modules/policy/samples/simulation-bridge@draft.json`.
+
+## Handoff
+Use this as the prep artefact for PREP-POLICY-ENGINE-30-002-SIMULATION-BRIDGE-C. Update hashes and samples once 30-001 publishes the overlay schema; then move the implementation task to DOING.

docs/modules/policy/prep/2025-11-20-snapshot-api-prep.md

@@ -0,0 +1,21 @@
+# Snapshot API Prep — PREP-POLICY-ENGINE-35-201-SNAPSHOT-API-WAITS-
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Describe the snapshot API contract that follows ledger export (34-101).
+
+## Dependencies
+- Ledger export schema (34-101).
+- Snapshot stream parameters (retention, pagination) from Policy data store.
+
+## Draft API surface
+- `GET /policy/snapshots?tenant_id=&after_cursor=&limit=` → returns `{items:[{snapshot_id, generated_at, ledger_export_id, overlay_hash, status_counts}], next_cursor}`.
+- `GET /policy/snapshots/{snapshot_id}` → returns snapshot detail with materialized results (same ordering as ledger export).
+- Determinism: snapshot_id = hash of ledger_export_id + overlay_hash; ordering by `generated_at` then `snapshot_id`.
+
+## Acceptance
+- Draft schema at `docs/modules/policy/schemas/policy-snapshot@draft.json` and sample at `docs/modules/policy/samples/policy-snapshot@draft.json`.
+- Cursor format defined (opaque base64 of `(generated_at, snapshot_id)` suggested).
+
+## Handoff
+This document is the prep artefact for PREP-POLICY-ENGINE-35-201-SNAPSHOT-API-WAITS-. Update with cursor and retention details once ledger export shape is frozen.

docs/modules/policy/prep/2025-11-20-trust-weighting-prep.md

@@ -0,0 +1,25 @@
+# Trust Weighting UI/API Prep — PREP-POLICY-ENGINE-30-101-TRUST-WEIGHTING-UI-
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Capture the UI/API surfaces for trust weighting once change events (30-003) are available.
+
+## Dependencies
+- Change events payload (30-003) and overlay schema (30-001).
+- UI design tokens/UX from Console/Policy surfaces (not yet provided).
+
+## Proposed API surface (draft)
+- `GET /policy/trust-weighting` → returns current weights per source (`cartographer`, `concelier`, `scanner`, `advisory_ai`, etc.) and effective profile hash.
+- `PUT /policy/trust-weighting` → accepts deterministic payload sorted by `source` with fields: `{source, weight, justification?, updated_at}`.
+- `GET /policy/trust-weighting/preview?overlay_hash=` → previews recalculated statuses using supplied weights (calls simulation bridge under the hood).
+
+## Determinism & validation
+- Weights are decimals with fixed scale 3; sum not required to 1 but capped at max per policy profile.
+- Payloads canonical JSON ordering; timestamps UTC.
+
+## Acceptance to close PREP
+- Align sources list with 30-003 change event fields and overlay inputs.
+- Document schema at `docs/modules/policy/schemas/trust-weighting@draft.json` and sample at `docs/modules/policy/samples/trust-weighting@draft.json`.
+
+## Handoff
+Treat this as the prep artefact for PREP-POLICY-ENGINE-30-101-TRUST-WEIGHTING-UI-. Finalize once 30-003 is frozen and UI tokens arrive; then move implementation to DOING.

docs/modules/policy/prep/2025-11-20-violation-events-prep.md

@@ -0,0 +1,22 @@
+# Violation Events Prep — PREP-POLICY-ENGINE-38-201-VIOLATION-EVENTS-DE
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Define violation event payloads emitted after snapshot stream (35-201).
+
+## Dependencies
+- Snapshot API/stream shape (35-201).
+- Severity fusion rules (40-001) to know which fields to emit.
+
+## Draft event
+- `event_type`: `policy.violation.detected`
+- Fields: `tenant_id`, `snapshot_id`, `policy_profile_hash`, `component_purl`, `advisory_id`, `violation_code`, `severity`, `status`, `trace_ref`, `occurred_at`, `event_id` (hash of snapshot_id + component_purl + advisory_id).
+- Transport: NATS subject `policy.violation.detected`; durable stream; idempotency via `event_id`.
+- Metrics: `policy_violation_events_total{tenant,violation_code}`.
+
+## Acceptance
+- Draft schema at `docs/modules/policy/schemas/policy-violation-event@draft.json` and sample at `docs/modules/policy/samples/policy-violation-event@draft.json`.
+- Confirm subject + retention with Scheduler/Notify.
+
+## Handoff
+Use this doc as the prep artefact for PREP-POLICY-ENGINE-38-201-VIOLATION-EVENTS-DE. Update once snapshot stream and fusion rules are frozen; then unblock implementation.

docs/modules/policy/prep/2025-11-20-worker-implementation-prep.md

@@ -0,0 +1,22 @@
+# Worker Implementation Prep — PREP-POLICY-ENGINE-33-101-WORKER-IMPLEMENTATI
+
+Status: Draft (2025-11-20)
+Owners: Policy Guild
+Scope: Define worker execution contract that consumes orchestrator jobs (32-101).
+
+## Dependencies
+- Job schema from 32-101.
+- Overlay + batch context schemas (30-001, 31-002).
+
+## Draft execution contract
+- Worker input: job document with `context_id`, `batch_items`, `policy_profile_hash`, `callbacks`.
+- Output record: `{job_id, worker_id, started_at, completed_at, results[]}` where each result mirrors change-event format `{component_purl, advisory_id, status, trace_ref}`.
+- Idempotency: result hash over sorted results; retries compare hash and skip duplicate emission.
+- Metrics: `policy_worker_jobs_total{result}`, `policy_worker_duration_seconds` (histogram), `policy_worker_results_total{status}`.
+
+## Acceptance
+- Save schema draft at `docs/modules/policy/schemas/policy-worker-result@draft.json` and sample result at `docs/modules/policy/samples/policy-worker-result@draft.json`.
+- Confirm dedupe strategy with Scheduler/Orchestrator.
+
+## Handoff
+Prep artefact for PREP-POLICY-ENGINE-33-101-WORKER-IMPLEMENTATI. Finalize once job schema is fixed and dedupe/metric names are agreed.

docs/modules/policy/prep/2025-11-21-policy-metrics-29-004-prep.md

@@ -0,0 +1,23 @@
+# Policy Metrics/Logging Prep — PREP-POLICY-ENGINE-29-004
+
+Status: Draft (2025-11-21)
+Owners: Policy Guild · Observability Guild
+Scope: Define metrics/logging outputs for path/scope-aware evaluation (POLICY-ENGINE-29-004) so downstream overlays/simulations can consume stable counters and traces.
+
+Needs / open points
+- Ingest output shape from POLICY-ENGINE-29-003 (path/scope evaluator) to enumerate metric dimensions and labels.
+- Confirm sampling, cardinality guardrails, and redaction rules for evidence payloads.
+- Decide OpenTelemetry/ADI schema version and offline export format (NDJSON) for air-gapped runs.
+- Align log event IDs with change-event pipeline (30-003) to ensure replay determinism.
+
+Draft contract (initial)
+- Metrics namespace: `stellaops.policy.eval.*`
+- Required counters: total_evaluations, policy_matches, policy_denies, evaluation_failures, overlay_projections_emitted.
+- Dimensions (tentative): tenant_id, policy_pack_id, overlay_id, scope_path, scheduler_job_id, evaluator_version, schema_version, environment (online/offline).
+- Logs: structured JSON; fields include evaluation_id (ULID), scope_path, matched_policies[], deny_reasons[], duration_ms, trace_id (optional), schema_version.
+- Export: NDJSON batch with deterministic ordering by evaluation_id; batching bounded by 1 MiB or 1k records; integrity hash (SHA256) over batch.
+
+Next actions
+- Await path/scope payloads from POLICY-ENGINE-29-003 to lock dimensions and sample payloads.
+- Publish sample metric set and log envelope once upstream confirms.
+- Mirror into sprint execution log once finalized.

docs/modules/policy/prep/2025-11-21-policy-path-scope-29-002-prep.md

@@ -0,0 +1,17 @@
+# Policy Path/Scope Schema Prep — PREP-POLICY-ENGINE-29-002
+
+Status: Draft (2025-11-21)
+Owners: Policy Guild · SBOM Service Guild
+Scope: Define path/scope-aware evaluation schema (inputs/outputs) for POLICY-ENGINE-29-002 so downstream metrics, overlays, and simulations can bind to stable shapes.
+
+Needs / open points
+- Enumerate canonical path selectors (SBOM node types, package coords, file paths) and disambiguation rules.
+- Decide scope precedence and evaluation order (lexical vs explicit priority).
+- Provide JSON Schema for evaluation request/response, including error surfaces and determinism requirements (ordering, nullability, defaults).
+- Align with SBOM Service envelopes and Graph coordinates to avoid divergent node IDs.
+- Sample payloads for common cases: single package, path tree, mixed ecosystem nodes.
+
+Next actions
+- Draft initial JSON Schema and sample payloads once SBOM Service shares coordinate mapping rules.
+- Review with Observability Guild to ensure fields required by metrics/logging (29-004) are present.
+- Publish finalized schema to unblock 29-003 and downstream tasks.