jmjava · jmjava · Sep 17, 2026 · Sep 17, 2026
diff --git a/.github/workflows/cluster-regression.yml b/.github/workflows/cluster-regression.yml
@@ -1,8 +1,12 @@
-# Cluster-backed regression (S33). Not on pull requests — Kind/Tekton is too
-# slow and too easy to confuse with the PR-gated --local-only job.
+# Cluster-backed regression (S33). Kind/Tekton is too slow to run on every
+# pull request — local-regression.yml is the everyday gate.
 #
 # Runs: Playwright (no cluster) + Kind (isolation-eval --cluster, Phase 2
-# stack-dag-verify, Newman vs orchestrator).
+# stack-dag-verify, Newman vs orchestrator). Isolation-eval is skipped on
+# pull_request; nightly / dispatch / tags still measure it.
+#
+# pull_request paths below exercise this job when Helm or cluster-ci scripts
+# change. Everyday product PRs (tasks/, docs/, orchestrator/, …) do not match.
 name: cluster regression
 
 on:

diff --git a/.github/workflows/intercept-e2e.yml b/.github/workflows/intercept-e2e.yml
@@ -1,3 +1,8 @@
+# Weekly (and path-filtered) product-path evidence: trigger → StackRun →
+# operator → PR PipelineRun → intercept (Telepresence or mirrord) → tests.
+# Not the everyday PR gate — local-regression.yml is. Path filters still
+# start Kind when Helm/tasks/operator/orchestrator/pipeline/stacks or the
+# listed scripts change.
 name: intercept product E2E
 
 on:

diff --git a/.github/workflows/local-regression.yml b/.github/workflows/local-regression.yml
@@ -1,3 +1,6 @@
+# Everyday PR / main-push gate. Does not start Kind.
+# Kind jobs live in cluster-regression.yml, intercept-e2e.yml,
+# results-regression.yml, and operator.yml (path-filtered or scheduled).
 name: local regression
 
 on:

diff --git a/.github/workflows/results-regression.yml b/.github/workflows/results-regression.yml
@@ -1,3 +1,6 @@
+# Weekly (and path-filtered) pinned Results/Postgres + strict agent regression.
+# Not the everyday PR gate. Path filters cover Results installers and
+# run-regression-agent-full.sh.
 name: Tekton Results regression
 
 on:

diff --git a/DO-THIS-LOCAL.md b/DO-THIS-LOCAL.md
@@ -7,7 +7,7 @@ Cloud agents for this PR ran **`--local-only`** (no `kubectl` / Docker / Kind).
 ## Prerequisites
 
 - Kind (or equivalent) cluster with Tekton Pipelines installed
-- This repo checked out on branch `cursor/m13-production-hardening-features-b923` (or `main` after merge)
+- This repo checked out (typically `main`, or the branch under test)
 - Python venv + tools from [docs/AGENT-REGRESSION.md](docs/AGENT-REGRESSION.md)
 
 ```bash

diff --git a/README.md b/README.md
diff --git a/docs/MAINTENANCE.md b/docs/MAINTENANCE.md
@@ -4,16 +4,17 @@ This document is a map of the **tekton-dag** repository: what each area does, ho
 
 ## Architecture overview
 
-The system wires **stack definitions** (YAML) to **Tekton** pipelines, with an in-cluster **orchestrator** that creates `PipelineRun` objects and optional **Neo4j** queries for test planning.
+The system wires **stack definitions** (YAML) to **Tekton** pipelines. The in-cluster **orchestrator** creates `StackRun` objects; the **operator** reconciles them to `PipelineRun`s. Optional **Neo4j** queries support test planning.
 
 | Area | Role |
 |------|------|
 | **`stacks/`** | Stack YAML: applications, build tool per app, downstream dependencies, test configuration. Often synced into the cluster via Helm ConfigMaps. |
 | **`tasks/`** | Tekton `Task` manifests: resolve stack, clone repos, compile (per tool), containerize, deploy intercepts / full stack, validate propagation, run tests, versioning, cleanup, graph helpers, etc. |
-| **`pipeline/`** | Tekton `Pipeline` definitions and trigger bindings. Core flows: PR test, bootstrap deploy, merge/release. Additional pipelines exist for continuation and DAG verification. |
+| **`pipeline/`** | Tekton `Pipeline` definitions and trigger bindings. Core flows: PR test, bootstrap deploy, merge/release, promote. Additional pipelines exist for continuation and DAG verification. |
+| **`operator/`** | Go Kubebuilder controller for `Stack`, `StackRun`, and `Team` (`tektondag.io/v1alpha1`). Canonical PipelineRun builder. |
 | **`orchestrator/`** | Flask service: `app.py` (config), `routes.py` (HTTP API), `stack_resolver.py` (repo → stack), `stackrun_builder.py` (StackRun CRs), `k8s_client.py`, `graph_client.py` (Neo4j). The legacy PipelineRun builder is a golden-contract oracle, not the runtime path. |
 | **`management-gui/`** | Vue 3 (Vite) frontend plus Flask backend for operating and observing pipelines, teams, and repos. |
-| **`helm/tekton-dag/`** | Helm chart: orchestrator, management GUI, RBAC, ConfigMaps for stacks/teams, optional PVCs, values for registry and defaults. |
+| **`helm/tekton-dag/`** | Helm chart: orchestrator, operator, management GUI, RBAC, ConfigMaps for stacks/teams, optional PVCs, values for registry and defaults. `operator.enabled` defaults **true**. |
 | **`scripts/`** | Bash utilities; new scripts should `source` **`scripts/common.sh`** for shared defaults (`NAMESPACE`, `GIT_URL`, port-forward helpers, etc.). |
 | **`build-images/`** | Parameterized Dockerfiles for compile-side images (Maven, Gradle, Node, Python, PHP, mirrord) and scripts to build/push them. |
 | **`teams/`** | Per-team metadata (`team.yaml`) and related values; orchestrator discovers teams under mounted paths (e.g. `/teams/<team>/team.yaml`). |
@@ -22,9 +23,10 @@ The system wires **stack definitions** (YAML) to **Tekton** pipelines, with an i
 
 | Pipeline | File | Purpose |
 |----------|------|---------|
-| `stack-pr-test` | `pipeline/stack-pr-pipeline.yaml` | PR path: resolve stack, build changed app, intercept deploy, tests, version bump, cleanup. |
+| `stack-pr-test` | `pipeline/stack-pr-pipeline.yaml` | PR path: resolve stack, snapshot-tag and build the changed app, intercept deploy, tests, PR comment, cleanup. **No** `versions.yaml` bump. |
 | `stack-bootstrap` | `pipeline/stack-bootstrap-pipeline.yaml` | Full stack bring-up / environment bootstrap. |
-| `stack-merge-release` | `pipeline/stack-merge-pipeline.yaml` | Post-merge release flow (images, tags, etc.). |
+| `stack-merge-release` | `pipeline/stack-merge-pipeline.yaml` | Post-merge release flow (images, tags, next-cycle version bump). |
+| `stack-promote` | `pipeline/stack-promote-pipeline.yaml` | Copy release images to a target registry (`stacks/registries.yaml`). |
 
 Other pipelines in `pipeline/` include **`stack-pr-continue`**, **`stack-dag-verify`**, and **`triggers.yaml`** (EventListener / bindings / templates) for webhook-style automation.
 
@@ -53,7 +55,7 @@ Tasks live under `tasks/` (see filenames for the canonical Tekton `metadata.name
 
 ### `orchestrator/`
 
-- **Contains:** Flask app, K8s and Neo4j clients, PipelineRun construction.
+- **Contains:** Flask app, K8s and Neo4j clients, StackRun construction (runtime) plus a contract-only PipelineRun builder (tests).
 - **Modify when:** New HTTP APIs, different default params on created runs, resolver rules, or graph behavior.
 
 ### `management-gui/`
@@ -140,7 +142,7 @@ Implement a Tekton `Task`, install it in the cluster, then set the pipeline para
 | Orchestrator unit tests | `cd orchestrator && python3 -m pytest tests/ -v` | **108** tests at the M17 baseline. |
 | Management GUI backend | `cd management-gui/backend && python3 -m pytest tests/ -v` | **68** tests at the M17 baseline. |
 | Management GUI frontend (E2E) | `cd management-gui/frontend && npx playwright test` | **70** tests at the M17 baseline. |
-| Newman / Postman (cluster) | `./scripts/run-orchestrator-tests.sh --all` | Requires running orchestrator (and Neo4j for graph collection); see script header for prerequisites. |
+| Newman / Postman (cluster) | `./scripts/run-orchestrator-tests.sh --all` | 20 requests / 38 assertions in `tests/postman/orchestrator-tests.json`. Requires a running orchestrator (and Neo4j for graph collection); see script header. |
 
 ---
 

diff --git a/docs/README-FULL.md b/docs/README-FULL.md
@@ -1,5 +1,7 @@
 # Tekton Job Standardization
 
+> **Historical long-form design.** Runtime control plane is now CRD-primary (`Stack` / `StackRun` via the operator). PR runs use **snapshot image tags** and do **not** bump `versions.yaml`. For current behavior start at the root [README](../README.md), [DAG-AND-PROPAGATION.md](DAG-AND-PROPAGATION.md), and [milestones/milestone-14.md](../milestones/milestone-14.md).
+
 One universal Tekton pipeline system that adapts to any combination of applications — single services, multi-tier stacks, or fan-out graphs — while managing versioning, build toolchains, header propagation, and container image lifecycle automatically.
 
 ## Problem

diff --git a/docs/README.md b/docs/README.md
@@ -11,7 +11,8 @@ This folder contains design, operations, and verification docs for the tekton-da
 | **Archive (not maintained)** | [archive/](archive/) — obsolete session plans and similar |
 | **Customization & ops** | [CUSTOMIZATION.md](CUSTOMIZATION.md), [MAINTENANCE.md](MAINTENANCE.md) |
 | **Teams: stacks + baggage libs** | [TEAM-ONBOARDING-STACKS-AND-BAGGAGE.md](TEAM-ONBOARDING-STACKS-AND-BAGGAGE.md) — header libraries per runtime, new stack checklist |
-| **Demo toolchain (M8)** | [demos/](demos/) — [demos/README.md](demos/README.md), `generate-all.sh`; [milestones/milestone-8.md](../milestones/milestone-8.md) |
+| **Demo toolchain (M8)** | [demos/](demos/) — [demos/README.md](demos/README.md) (`docgen` CLI; `generate-all.sh` is a thin wrapper); [milestones/milestone-8.md](../milestones/milestone-8.md) |
+| **GitHub Actions** | [REGRESSION.md](REGRESSION.md) — which workflows run on every PR vs schedule/path filters |
 | **GitHub Pages** | [GITHUB-PAGES.md](GITHUB-PAGES.md) — how the demo site is deployed; fix 404 |
 | **Illustrations & logo** | [assets/README.md](assets/README.md) — composite PNGs + **split panels** in `assets/panels/` for READMEs and demos |
 | **Agents / regression loop** | [AGENT-REGRESSION.md](AGENT-REGRESSION.md) — iterate until full regression green; [../AGENTS.md](../AGENTS.md) |

diff --git a/docs/REGRESSION.md b/docs/REGRESSION.md
@@ -11,9 +11,24 @@ Do **not** confuse these:
 | Scope | What runs | Typical trigger |
 |-------|-----------|-----------------|
 | **Application PR** (`stack-pr-test` on an **app** repo) | Stack-defined tests only — e.g. that app’s Newman/Playwright/Artillery as declared in `stacks/*.yaml`, against the intercept build. | Every PR on the **application** repository (when webhooks/Tekton are wired). |
-| **Platform regression** (`scripts/run-regression*.sh` on **this** repo) | **System / integration** tiers: Phase 1 + orchestrator + shared libs + GUI pytest, Playwright for **management-gui**, real **`stack-dag-verify`** PipelineRun, Newman against **orchestrator** API, optional Tekton Results, optional Kind E2E. | **PRs / `main`:** [`.github/workflows/local-regression.yml`](../.github/workflows/local-regression.yml) runs **`--local-only --require-lang-tests`**. **Nightly / dispatch / `v*` tags:** [`.github/workflows/cluster-regression.yml`](../.github/workflows/cluster-regression.yml) runs Playwright + Kind. **Weekly / dispatch:** [`intercept-e2e.yml`](../.github/workflows/intercept-e2e.yml) runs both intercept backends and [`results-regression.yml`](../.github/workflows/results-regression.yml) runs strict Results/Postgres verification. |
+| **Platform regression** (`scripts/run-regression*.sh` on **this** repo) | **System / integration** tiers: Phase 1 + orchestrator + shared libs + GUI pytest, Playwright for **management-gui**, real **`stack-dag-verify`** PipelineRun, Newman against **orchestrator** API, optional Tekton Results, optional Kind E2E. | See the GitHub Actions table below. |
 
-So: **not all tests run on every PR.** `--local-only` (including Java/PHP/operator) is PR-gated. Playwright, Newman, Phase 2, and Kind isolation measurements run on **cluster-regression** (nightly / `workflow_dispatch` / version tags), not on pull requests. The slower Telepresence and mirrord product paths run weekly and on dispatch. App PRs run a narrower, stack-scoped test stage.
+**GitHub Actions — what runs when (Kind is not every PR):**
+
+| Workflow | Every PR / every `main` push | Also runs |
+|----------|------------------------------|-----------|
+| **local regression** | Yes (`--local-only --require-lang-tests`) | dispatch |
+| **docgen demo-function** | Yes (cheap smoke) | |
+| **dependency review** | PRs only | |
+| **operator** | Only if `operator/**` (or `install-tekton.sh`) changed — unit/envtest plus Kind domain E2E | dispatch |
+| **cluster regression** | No | Nightly cron, `v*` tags, dispatch, or PRs that touch Helm / `scripts/run-cluster-ci.sh` / `scripts/bootstrap-namespace.sh` / this workflow file. Isolation-eval is **skipped** on pull_request. |
+| **intercept product E2E** | No | Weekly cron, dispatch, or PRs/pushes matching [intercept-e2e.yml](../.github/workflows/intercept-e2e.yml) path filters (Helm, tasks, operator, orchestrator, pipeline, stacks, listed install/E2E scripts). |
+| **Tekton Results** | No | Weekly cron, dispatch, or PRs that touch Results installers / `run-regression-agent-full.sh` / `run-lang-unit-tests.sh` |
+| **Pages** | No | `main` pushes that touch `docs/**` |
+
+The Actions sidebar can still list **deleted** workflow names (compatibility matrix, demo validation, Graph/GUI Newman, static quality, supply-chain scan). Those files are gone; disable them in the repo **Actions → workflow → ⋯ → Disable**. **Dependabot Updates** is GitHub-managed, not a repo workflow.
+
+So: **not all tests run on every PR.** `--local-only` (including Java/PHP/Go) is the default gate. Playwright (management-gui) plus Kind Phase 2 plus Newman run on **cluster-regression** (nightly / tags / Helm-or-cluster-script PRs). Telepresence/mirrord and Results/Postgres are **weekly**, plus their own path filters. App PRs run a narrower, stack-scoped test stage.
 
 The existence of the intercept workflow is not proof that either backend is
 currently healthy. Treat only a recent successful matrix job and its retained