Charon/docs/plans/current_spec.md

## 1. Introduction

### Overview
Compatibility rollout for Caddy `2.11.1` is already reflected in the build
default (`Dockerfile` currently sets `ARG CADDY_VERSION=2.11.1`).

This plan is now focused on rollout verification and regression-proofing, not
changing the default ARG.

### Objective
Establish deterministic, evidence-backed gates that prove published images and
security artifacts are fresh, digest-bound, and aligned across registries for
the Caddy `2.11.1` rollout.

## 2. Current State (Verified)

1. `Dockerfile` default is already `CADDY_VERSION=2.11.1`.
2. `ARCHITECTURE.md` now reports Caddy `2.11.1`.
3. Existing scan artifacts can become stale if not explicitly tied to pushed
   digests.

## 3. Technical Specification (EARS)

1. WHEN image builds run without an explicit `CADDY_VERSION` override, THE
   SYSTEM SHALL continue producing Caddy `2.11.1`.
2. WHEN an image tag is pushed, THE SYSTEM SHALL validate index digest parity
   between GHCR and Docker Hub for that same tag.
3. WHEN multi-arch images are published, THE SYSTEM SHALL validate per-arch
   digest parity across GHCR and Docker Hub for each platform present.
4. WHEN vulnerability and SBOM scans execute, THE SYSTEM SHALL scan
   `image@sha256:<index-digest>` instead of mutable tags.
5. WHEN scan artifacts are generated, THE SYSTEM SHALL prove artifacts were
   produced after the push event in the same validation run.
6. IF a verification gate fails, THEN THE SYSTEM SHALL block rollout sign-off
   until all gates pass.

## 4. Scope and Planned Edits

### In scope
1. `docs/plans/current_spec.md` (this plan refresh).
2. `ARCHITECTURE.md` version sync is already complete (`2.11.1`); no pending
   update is required in this plan.
3. Verification workflow/checklist updates needed to enforce deterministic gates.

### Out of scope
1. No functional Caddy build logic changes unless a verification failure proves
   they are required.
2. No plugin list or patch-scenario refactors.

## 5. Deterministic Acceptance Gates

### Gate 1: Digest Freshness (pre/post push)
1. Capture pre-push index digest for target tag on GHCR and Docker Hub.
2. Push image.
3. Capture post-push index digest on GHCR and Docker Hub.
4. Pass criteria:
   - Post-push index digest changed as expected from pre-push (or matches
     intended new digest when creating new tag).
   - GHCR and Docker Hub index digests are identical for the tag.
   - Per-arch digests are identical across registries for each published
     platform.

### Gate 2: Digest-Bound Rescan
1. Resolve the post-push index digest.
2. Run all security scans against immutable ref:
   - `ghcr.io/<owner>/<repo>@sha256:<index-digest>`
   - Optional mirror check against Docker Hub digest ref.
3. Pass criteria:
   - No scan uses mutable tags as the primary target.
   - Artifact metadata and logs show digest reference.

### Gate 3: Artifact Freshness
1. Record push timestamp and digest capture timestamp.
2. Generate SBOM and vuln artifacts after push in the same run.
3. Pass criteria:
   - Artifact generation timestamps are greater than push timestamp.
   - Artifacts are newly created/overwritten in this run.
   - Evidence ties each artifact to the scanned digest.

### Gate 4: Evidence Block (mandatory)
Every validation run must include a structured evidence block with:
1. Tag name.
2. Index digest.
3. Per-arch digests.
4. Scan tool versions.
5. Push and scan timestamps.
6. Artifact file names produced in this run.

## 6. Implementation Plan

### Phase 1: Baseline Capture
1. Confirm current `Dockerfile` default remains `2.11.1`.
2. Capture pre-push digest state for target tag across both registries.

### Phase 2: Docs Sync
1. Confirm `ARCHITECTURE.md` remains synced at Caddy `2.11.1`.

### Phase 3: Push and Verification
1. Push validation tag.
2. Execute Gate 1 (digest freshness and parity).
3. Execute Gate 2 (digest-bound rescan).
4. Execute Gate 3 (artifact freshness).
5. Produce Gate 4 evidence block.

### Phase 4: Sign-off
1. Mark rollout verified only when all gates pass.
2. If any gate fails, open follow-up remediation task before merge.

## 7. Acceptance Criteria

1. Plan and execution no longer assume Dockerfile default is beta.
2. Objective is rollout verification/regression-proofing for Caddy `2.11.1`.
3. `ARCHITECTURE.md` version metadata is included in required docs sync.
4. Digest freshness gate passes:
   - Pre/post push validation completed.
   - GHCR and Docker Hub index digest parity confirmed.
   - Per-arch digest parity confirmed.
5. Digest-bound rescan gate passes with `image@sha256` scan targets.
6. Artifact freshness gate passes with artifacts produced after push in the same
   run.
7. Evidence block is present and complete with:
   - Tag
   - Index digest
   - Per-arch digests
   - Scan tool versions
   - Timestamps
   - Artifact names

## 8. PR Slicing Strategy

### Decision
Single PR.

### Trigger Reasons
1. Scope is narrow and cross-cutting risk is low.
2. Verification logic and docs sync are tightly coupled.
3. Review size remains small and rollback is straightforward.

### PR-1
1. Scope:
   - Refresh `docs/plans/current_spec.md` to verification-focused plan.
   - Sync `ARCHITECTURE.md` Caddy version metadata.
   - Add/adjust verification checklist content needed for gates.
2. Dependencies:
   - Existing publish/scanning pipeline availability.
3. Validation gates:
   - Gate 1 through Gate 4 all required.

## 9. Rollback and Contingency

1. If verification updates are incorrect or incomplete, revert PR-1.
2. If rollout evidence fails, hold release sign-off and keep last known-good
   digest as active reference.
3. Re-run verification with corrected commands/artifacts before reattempting
   sign-off.