Docs: restructure architecture and guides around CSSC stages

.github/actions/manage-failure-issue/action.yml

@@ -16,7 +16,7 @@
 # This is intentionally separate from `manage-issue` (which is specific to the
 # promotion override flow: a different title, label set, and a required embedded
 # metadata block). See
-# docs/architecture/workflows/ci-failure-notifications.md.
+# docs/architecture/cross-cutting/ci-failure-notifications.md.
 #
 # Terminology: see docs/reference/workflow-actions.md.
 name: manage-failure-issue

.github/workflows/_promote-from-quarantine-sbom.yml

@@ -18,7 +18,7 @@
 # aggregates the per-tag results.
 #
 # Terminology and the action catalogue: see docs/reference/workflow-actions.md.
-# See also docs/architecture/workflows/promote-from-quarantine-workflows.md.
+# See also docs/architecture/catalog/promote-from-quarantine-workflows.md.
 name: _reusable / promote-from-quarantine-sbom
 
 on:

.github/workflows/_promote-from-quarantine.yml

@@ -19,7 +19,7 @@
 #   5. deletes the promoted tag from quarantine (delete-image).
 #
 # Terminology and the action catalogue: see docs/reference/workflow-actions.md.
-# See also docs/architecture/workflows/promote-from-quarantine-workflows.md.
+# See also docs/architecture/catalog/promote-from-quarantine-workflows.md.
 name: _reusable / promote-from-quarantine
 
 on:

.github/workflows/_promote-override.yml

@@ -14,7 +14,7 @@
 #   4. deny: manage-issue close (promotion-denied) -> notify-slack (denied).
 #
 # Terminology and the action catalogue: see docs/reference/workflow-actions.md.
-# See also docs/architecture/workflows/promote-from-quarantine-override-approval.md.
+# See also docs/architecture/catalog/promote-from-quarantine-override-approval.md.
 name: _reusable / promote-override
 
 on:

.github/workflows/build-cssc-dashboard.yml

@@ -153,7 +153,7 @@ jobs:
             "org.opencontainers.image.title=CSSC Dashboard ${SERVICE}"
             "org.opencontainers.image.description=${desc}"
             "org.opencontainers.image.url=${SERVER_URL}/${REPO}"
-            "org.opencontainers.image.documentation=${SERVER_URL}/${REPO}/blob/main/docs/architecture/apps/cssc-dashboard.md"
+            "org.opencontainers.image.documentation=${SERVER_URL}/${REPO}/blob/main/docs/architecture/run/cssc-dashboard.md"
             "org.opencontainers.image.vendor=toddysm.com"
             "org.opencontainers.image.licenses=Apache-2.0"
             "org.opencontainers.image.base.name=${base_name}"

.github/workflows/promote-override.yml

@@ -10,7 +10,7 @@
 # the override itself is still gated by `verify-approver` inside the reusable
 # workflow.
 #
-# See docs/architecture/workflows/promote-from-quarantine-override-approval.md.
+# See docs/architecture/catalog/promote-from-quarantine-override-approval.md.
 name: promote override
 
 on:

.github/workflows/report-ci-failure.yml

@@ -13,7 +13,7 @@
 #
 # Note: runs that fail at startup (startup_failure) may not emit `workflow_run`
 # and can therefore be missed; see
-# docs/architecture/workflows/ci-failure-notifications.md.
+# docs/architecture/cross-cutting/ci-failure-notifications.md.
 name: report / ci-failure
 
 on:

apps/python-app/README.md

@@ -6,7 +6,7 @@ A scalable, Kubernetes-native demonstration app that visualizes the
 Container Registry (GHCR) packages and promotion tracking issues.
 
 See the full design in
-[docs/architecture/apps/cssc-dashboard.md](../../docs/architecture/apps/cssc-dashboard.md).
+[docs/architecture/run/cssc-dashboard.md](../../docs/architecture/run/cssc-dashboard.md).
 
 > Read-only demo. The dashboard never mutates packages or issues.
 

apps/python-app/libs/cssc_common/README.md

@@ -1,7 +1,7 @@
 # cssc_common
 
 Shared building blocks for the CSSC Dashboard microservices. See the
-[CSSC Dashboard design](../../../../docs/architecture/apps/cssc-dashboard.md).
+[CSSC Dashboard design](../../../../docs/architecture/run/cssc-dashboard.md).
 
 ## What's here
 

apps/python-app/services/dashboard-web/README.md

@@ -4,7 +4,7 @@ CSSC Dashboard web tier: the stage registry, the Acquisition stage provider, and
 the Jinja2/htmx UI. It is a backend-for-frontend that aggregates the
 `packages-service` and `issues-service` capability services — it never calls
 GitHub directly. See the
-[CSSC Dashboard design](../../../../docs/architecture/apps/cssc-dashboard.md).
+[CSSC Dashboard design](../../../../docs/architecture/run/cssc-dashboard.md).
 
 ## Routes
 

apps/python-app/services/issues-service/README.md

@@ -2,7 +2,7 @@
 
 CSSC Dashboard capability service that reads promotion tracking issues and
 parses the `blocking_cves` recorded in their `cssc-metadata` block. See the
-[CSSC Dashboard design](../../../../docs/architecture/apps/cssc-dashboard.md).
+[CSSC Dashboard design](../../../../docs/architecture/run/cssc-dashboard.md).
 
 ## API
 

apps/python-app/services/packages-service/README.md

@@ -2,7 +2,7 @@
 
 CSSC Dashboard capability service that lists GHCR container packages and their
 tags via the GitHub Packages API. See the
-[CSSC Dashboard design](../../../../docs/architecture/apps/cssc-dashboard.md).
+[CSSC Dashboard design](../../../../docs/architecture/run/cssc-dashboard.md).
 
 ## API
 

docs/README.md

@@ -1,32 +1,41 @@
 # Documentation
 
-Documentation for the `cssc-framework` repository. Content is organized by
-topic so each area can grow independently.
+Documentation for the `cssc-framework` repository. The **architecture** and
+**guides** are organized around the **CSSC framework stages** — Acquire,
+Catalog, Build, Deploy, and Run — and, within each stage, grouped under two
+cross-cutting themes where they apply: **Authenticity and Integrity** and
+**Supply Chain Observability**. Reference material and contributing conventions
+are kept as cross-cutting areas.
 
 ## Structure
 
 | Folder | Purpose |
 | ------ | ------- |
-| [`contributing/`](contributing/) | Guides and conventions for people contributing to this repository. |
-| [`architecture/`](architecture/) | Design and architecture documentation. |
-| [`guides/`](guides/) | How-to and operational guides. |
-| [`reference/`](reference/) | Reference material and conventions. |
+| [`architecture/`](architecture/) | Design and architecture docs, organized by stage. |
+| [`guides/`](guides/) | How-to and operational guides, organized by stage. |
+| [`reference/`](reference/) | Reference material and conventions (cross-cutting). |
+| [`contributing/`](contributing/) | Conventions for contributing to this repository. |
 
-## Guides
+## Stages
 
-- [Mirroring base images from Docker Hub to GHCR](guides/mirroring-base-images.md)
-  — how the mirror actions work and how to add a new mirror for another image or
-  tag.
+| Stage | Architecture | Guides |
+| ----- | ------------ | ------ |
+| **Acquire** | [architecture/acquire/](architecture/acquire/) | [guides/acquire/](guides/acquire/) |
+| **Catalog** | [architecture/catalog/](architecture/catalog/) | [guides/catalog/](guides/catalog/) |
+| **Build** | [architecture/build/](architecture/build/) | [guides/build/](guides/build/) |
+| **Deploy** | [architecture/deploy/](architecture/deploy/) | [guides/deploy/](guides/deploy/) |
+| **Run** | [architecture/run/](architecture/run/) | [guides/run/](guides/run/) |
 
-## Architecture docs
+Design docs that span stages live under
+[architecture/cross-cutting/](architecture/cross-cutting/).
 
-- [Image mirror workflows](architecture/workflows/image-mirror-workflows.md) —
-  how the Docker Hub → GHCR mirroring GitHub Actions are structured, the tooling
-  they use, and what they do and do not do.
-- [CSSC Dashboard application](architecture/apps/cssc-dashboard.md) — a
-  microservices web app that visualizes the CSSC framework stage by stage.
+## Reference
 
-## Contributing docs
+- [Workflow actions and terminology](reference/workflow-actions.md)
+- [Image annotations](reference/image-annotations.md)
+- [Image attestations](reference/image-attestations.md)
+
+## Contributing
 
 - [Workflow naming conventions](contributing/workflow-naming.md) — how GitHub
   Actions workflows are named and organized in this repository.

docs/architecture/README.md

@@ -1,14 +1,23 @@
 # Architecture
 
-Design and architecture documentation for the `cssc-framework` repository.
-
-## Topics
-
-- [Workflow architecture](workflows/) — GitHub Actions workflows.
-  - [Image mirror workflows](workflows/image-mirror-workflows.md) — mirroring
-    upstream base images from Docker Hub into GHCR.
-  - [Build workflows](workflows/build-workflows.md) — building the demo apps into
-    versioned, multi-arch images with supply-chain metadata.
-- [Application architecture](apps/) — sample applications.
-  - [CSSC Dashboard](apps/cssc-dashboard.md) — microservices web app that
-    visualizes the CSSC framework stage by stage.
+Design and architecture documentation for the `cssc-framework` repository,
+organized around the **CSSC framework stages**. Within each stage, documents are
+grouped under two cross-cutting themes where they apply: **Authenticity and
+Integrity** and **Supply Chain Observability**.
+
+## Stages
+
+- [Acquire](acquire/) — mirroring upstream base images into a controlled
+  namespace.
+- [Catalog](catalog/) — scanning quarantined images and promoting the ones that
+  pass a vulnerability policy into `golden/*`.
+- [Build](build/) — building the demo apps into versioned, multi-arch images
+  with supply-chain metadata.
+- [Deploy](deploy/) — deploying the demo apps (currently the Helm charts under
+  `apps/*/deploy`).
+- [Run](run/) — the running applications, including the CSSC Dashboard.
+
+## Cross-cutting
+
+- [Cross-cutting](cross-cutting/) — design docs that span stages, such as
+  CI-failure notifications.

docs/architecture/acquire/README.md

@@ -0,0 +1,10 @@
+# Acquire — architecture
+
+Design docs for the **Acquire** stage: bringing upstream artifacts into a
+controlled namespace before they are used.
+
+## Authenticity and Integrity
+
+- [Image mirror workflows](image-mirror-workflows.md) — how the Docker Hub →
+  GHCR mirroring actions are structured, the tooling they use, and what they do
+  and deliberately do not do.

docs/architecture/build/README.md

@@ -0,0 +1,14 @@
+# Build — architecture
+
+Design docs for the **Build** stage: building the demo apps on trusted bases and
+attaching portable supply-chain metadata.
+
+## Authenticity and Integrity
+
+- [Build workflows](build-workflows.md) — how the demo applications are built
+  into multi-arch OCI images, tagged with the semantic-version set, pinned to a
+  digest-addressed base, and stamped with annotations, SBOM, and provenance.
+  (The SBOM, provenance, and annotations also serve **Supply Chain
+  Observability** — see the reference docs
+  [image annotations](../../reference/image-annotations.md) and
+  [image attestations](../../reference/image-attestations.md).)

docs/architecture/workflows/build-workflows.md → docs/architecture/build/build-workflows.md

@@ -186,5 +186,5 @@ dependency resolution (for example `pip`).
 - [`build / cssc-dashboard` workflow](../../../.github/workflows/build-cssc-dashboard.yml)
 - [Image annotations (reference)](../../reference/image-annotations.md)
 - [Image attestations (reference)](../../reference/image-attestations.md)
-- [CSSC Dashboard application architecture](../apps/cssc-dashboard.md)
+- [CSSC Dashboard application architecture](../run/cssc-dashboard.md)
 - [Workflow naming conventions](../../contributing/workflow-naming.md)

docs/architecture/catalog/README.md

@@ -0,0 +1,15 @@
+# Catalog — architecture
+
+Design docs for the **Catalog** stage: scanning quarantined images, gating them
+on a vulnerability policy, and promoting the ones that pass into `golden/*`.
+
+## Authenticity and Integrity
+
+- [Promote-from-quarantine workflows](promote-from-quarantine-workflows.md) —
+  how quarantined images are scanned with Trivy, gated on a severity threshold
+  plus CVE exceptions, promoted with a scan-report referrer, and removed from
+  quarantine. (The scan-report referrer also serves **Supply Chain
+  Observability**.)
+- [Promotion override approval](promote-from-quarantine-override-approval.md) —
+  the human-in-the-loop approve/deny path for promoting an image that a policy
+  would otherwise block.

docs/architecture/workflows/promote-from-quarantine-workflows.md → docs/architecture/catalog/promote-from-quarantine-workflows.md

@@ -12,7 +12,7 @@ scan the container images sitting in a `quarantine/<image>` repository and
 For naming and file-system conventions, see
 [workflow naming conventions](../../contributing/workflow-naming.md). For the
 mirror workflows that populate quarantine in the first place, see
-[image mirror workflows](image-mirror-workflows.md).
+[image mirror workflows](../acquire/image-mirror-workflows.md).
 
 ## Purpose
 
@@ -182,7 +182,7 @@ Distroless images such as [Docker Hardened Images](https://docs.docker.com/dhi/)
 packages. Those images instead carry their package inventory as an **SBOM
 attestation** — an in-toto statement attached to each platform manifest as an
 OCI referrer. The mirror copies these referrers into quarantine (see
-[`copy_referrers`](image-mirror-workflows.md)), and a dedicated reusable
+[`copy_referrers`](../acquire/image-mirror-workflows.md)), and a dedicated reusable
 workflow, `_promote-from-quarantine-sbom.yml`, gates on the SBOM rather than the image
 filesystem.
 

docs/architecture/cross-cutting/README.md

@@ -0,0 +1,9 @@
+# Cross-cutting — architecture
+
+Design docs that span multiple stages rather than belonging to a single one.
+
+## Supply Chain Observability
+
+- [CI failure notifications](ci-failure-notifications.md) — how a `workflow_run`
+  monitor opens and closes per-workflow CI-failure tracking issues (and optional
+  Slack alerts) across all monitored workflows when a run fails or recovers.

docs/architecture/workflows/ci-failure-notifications.md → docs/architecture/cross-cutting/ci-failure-notifications.md

@@ -27,7 +27,7 @@ issue** — opened by the `notify` job of the promote-from-quarantine reusable
 workflows ([`_promote-from-quarantine.yml`](../../../.github/workflows/_promote-from-quarantine.yml)
 and [`_promote-from-quarantine-sbom.yml`](../../../.github/workflows/_promote-from-quarantine-sbom.yml))
 when an image is *policy-blocked* (and only with `enable_approval`). See the
-[override-approval design](promote-from-quarantine-override-approval.md).
+[override-approval design](../catalog/promote-from-quarantine-override-approval.md).
 
 A *policy-blocked image* is not a CI failure — it is an expected outcome of a
 **successful** run. A genuine CI failure (a crashed step, an authentication
@@ -184,7 +184,7 @@ more common case of a run that starts and then fails.
   [workflow naming conventions](../../contributing/workflow-naming.md), document
   `manage-failure-issue` in the
   [workflow actions reference](../../reference/workflow-actions.md), and link this
-  document from the [workflow architecture index](README.md).
+  document from the [architecture index](../README.md).
 
 ## Security considerations
 

docs/architecture/deploy/README.md

@@ -0,0 +1,7 @@
+# Deploy — architecture
+
+Design docs for the **Deploy** stage: deploying the demo applications.
+
+_No architecture documents yet._ Deployment is currently handled by the Helm
+charts under `apps/*/deploy`; design docs will be added here as the deploy story
+grows.

docs/architecture/run/README.md

@@ -0,0 +1,9 @@
+# Run — architecture
+
+Design docs for the **Run** stage: the running applications and how they surface
+supply-chain state.
+
+## Supply Chain Observability
+
+- [CSSC Dashboard](cssc-dashboard.md) — a microservices web app that visualizes
+  the CSSC framework stage by stage.

docs/contributing/workflow-naming.md

@@ -95,7 +95,7 @@ images).
 - **Auth.** GHCR scan/copy/attach use the built-in `GITHUB_TOKEN`
   (`packages: write`). Deleting quarantine tags needs a separate
   `delete:packages` PAT (see the
-  [promote-from-quarantine architecture](../architecture/workflows/promote-from-quarantine-workflows.md)).
+  [promote-from-quarantine architecture](../architecture/catalog/promote-from-quarantine-workflows.md)).
 
 ### Adding a new promote-from-quarantine workflow
 
@@ -120,7 +120,7 @@ subscribes to the mirror, promote-from-quarantine, and promote-override workflow
 via the `workflow_run` event and opens (or, on recovery, closes) a
 `CI failure: <workflow>` issue. It uses the `report-<purpose>.yml` filename and
 the `report / <subject>` display name. See the
-[CI failure notifications design](../architecture/workflows/ci-failure-notifications.md).
+[CI failure notifications design](../architecture/cross-cutting/ci-failure-notifications.md).
 
 ## Composite actions