Main-is-released check, and the codified star-chart shape (#34)

* ci(standards): assert main points at a release tag

Reusable workflow for the invariant behind "main is the released version,
not the newest work": every commit on main is a tagged release, so an
untagged main head is itself the alarm. Callers pin it by SHA and run it
on a schedule plus push to main.

It separates three states that all look like "not tagged" from the
outside. A repository with zero tags cannot be evaluated at all and says
so rather than reporting drift. A drifted main reports the newest
reachable tag and how many commits it is behind. A prerelease on main is
its own failure by default, since a release candidate on the default
branch is the exact drift this exists to catch.

Read-only: contents: read, egress blocked to github.com, and no
credentials persisted through checkout. fetch-depth: 0 because tags only
travel with full history and a shallow clone would fail for the wrong
reason and read as real drift.

* ci(starchart): render the codified chart shape in both themes

Scott drew the target and it is now the renderer. The chart reads as
native GitHub UI rather than as a third-party embed: a 900x460 card on
GitHub's own border colour, sans for the words and mono for every
number, a 2px accent line over a faint gradient, interior gridlines and
a solid baseline. The accent is the repository's logo colour, passed as
a new required input, and an accent that is not a colour now fails
instead of drawing a chart with no line.

Three behaviours the renderer decides rather than hard-codes, each
because the naive version produced something wrong on a real repository.
The y-axis searches step-and-tick-count pairs, since rounding the step
alone put drydock's 239 stars on a 0-400 axis with the curve in the
bottom 60% of the plot. The curve is a monotone cubic, since a cardinal
spline overshoots on a curve this flat and an overshoot on a cumulative
count draws a dip that never happened. X labels drop to day precision
when month names collide, which is the actual condition rather than a
guessed span threshold.

Two files ship now, not one. GitHub's theme toggle does not reach a
media query inside an <img>-embedded SVG, so a self-theming file shows a
white card to anyone reading GitHub dark with a light OS. It does drive
a <picture> element in the README, so the pair is generated from one
fetch and the markup chooses. They commit together or not at all: a
<picture> with a fresh light chart and a stale dark one shows two
different histories depending on who is looking, and nothing reports it.

The documented trigger moves from a cron to the release cut. A committed
artifact refreshed on a schedule mutates underneath a tag, which is what
the main-is-released rule forbids.

The renderer block is generated from ops render-chart.mjs by
splice-into-workflow.mjs rather than hand-copied, and byte parity with
that module was verified against live drydock data before this landed.
Also fixes an assertion in the main-is-released test that sliced the
whole if-block as the decisive expression and so could never pass.

* docs(onboarding): add the main-is-released caller to the section 4 checklist

Author: scttbnsn

.github/tests/main_is_released_contract_test.py

@@ -0,0 +1,93 @@
+from pathlib import Path
+import re
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+WORKFLOW = ROOT / ".github/workflows/main-is-released.yml"
+
+
+class MainIsReleasedContractTest(unittest.TestCase):
+    def test_reusable_workflow_shape_and_read_only_permissions(self):
+        workflow = self.read_workflow()
+
+        for expected in (
+            "  workflow_call:\n",
+            "permissions: {}",
+            "    runs-on: ubuntu-24.04",
+            "uses: step-security/harden-runner@",
+            "egress-policy: block",
+            "github.com:443",
+            "      contents: read",
+        ):
+            self.assertIn(expected, workflow)
+
+        # This check only ever reads. Any write scope here would be a
+        # scheduled job with credentials to change the thing it audits.
+        self.assertNotIn(": write", workflow)
+        self.assertNotIn("persist-credentials: true", workflow)
+
+    def test_the_invariant_is_an_exact_tag_match(self):
+        workflow = self.read_workflow()
+
+        self.assertIn("git describe --exact-match --tags HEAD", workflow)
+        # --abbrev=0 alone answers "what tag is nearest", which is true of a
+        # drifted main too. It may only be used to report inside the failure
+        # branch, never in the condition that decides pass or fail — so the
+        # decisive slice is the condition line, not the whole if-block.
+        decisive = workflow.split("if ! tag=", 1)[1].split("\n", 1)[0]
+        self.assertIn("--exact-match", decisive)
+        self.assertNotIn("--abbrev=0", decisive)
+
+    def test_no_tags_is_reported_as_unevaluable_not_as_drift(self):
+        """A repo with zero tags produces the same 'not tagged' as one that
+        drifted. Those need different answers, so the measurement proves it
+        could have worked before its result is trusted."""
+        workflow = self.read_workflow()
+
+        self.assertIn('if [ -z "$(git tag)" ]; then', workflow)
+        self.assertLess(
+            workflow.index('if [ -z "$(git tag)" ]'),
+            workflow.index("git describe --exact-match"),
+        )
+
+    def test_shallow_checkout_would_break_the_measurement(self):
+        """describe needs tags and history; a shallow clone fails for the
+        wrong reason and reads as real drift."""
+        workflow = self.read_workflow()
+        self.assertIn("fetch-depth: 0", workflow)
+
+    def test_a_prerelease_on_main_fails_by_default(self):
+        """A release candidate on the default branch is the exact drift this
+        exists to catch: drydock's main sat on v1.7.0-rc.2."""
+        workflow = self.read_workflow()
+
+        self.assertIn("        default: false\n", workflow)
+        self.assertIn('if [ "$ALLOW_PRERELEASE" != "true" ]', workflow)
+        self.assertIn("ALLOW_PRERELEASE: ${{ inputs.allow-prerelease }}", workflow)
+
+    def test_failures_say_what_to_do_next(self):
+        workflow = self.read_workflow()
+
+        for expected in ("::error::", "cut a release", "dev branch"):
+            self.assertIn(expected, workflow)
+        self.assertIn("set -euo pipefail", workflow)
+
+    def test_workflow_pins_actions_and_is_run_by_standards_validation(self):
+        workflow = self.read_workflow()
+        actions = re.findall(r"^\s+uses: ([^\s#]+)", workflow, re.MULTILINE)
+
+        self.assertTrue(actions)
+        for action in actions:
+            self.assertRegex(action, r"^[^@]+@[0-9a-f]{40}$")
+
+        validation = (ROOT / ".github/workflows/standards-validation.yml").read_text()
+        self.assertIn("main_is_released_contract_test.py", validation)
+
+    def read_workflow(self):
+        self.assertTrue(WORKFLOW.is_file(), f"missing workflow: {WORKFLOW}")
+        return WORKFLOW.read_text()
+
+
+if __name__ == "__main__":
+    unittest.main()

.github/tests/starchart_refresh_contract_test.py

@@ -20,6 +20,7 @@ def test_reusable_workflow_shape_and_narrow_permissions(self):
             "        required: true\n",
             "      output-path:\n",
             "        default: docs/assets/star-history.svg\n",
+            "      accent:\n",
             "      max-pages:\n",
             "        type: number\n",
             "permissions: {}",
@@ -62,10 +63,12 @@ def test_untrusted_input_is_read_from_the_environment(self):
         for expected in (
             "TARGET_REPO: ${{ github.repository }}",
             "OUTPUT_PATH: ${{ inputs.output-path }}",
+            "ACCENT: ${{ inputs.accent }}",
             "MAX_PAGES: ${{ inputs.max-pages }}",
             "TARGET_BRANCH: ${{ inputs.branch }}",
             "const repo = process.env.TARGET_REPO",
             "const out = process.env.OUTPUT_PATH",
+            "const accent = process.env.ACCENT",
         ):
             self.assertIn(expected, workflow)
 
@@ -78,8 +81,13 @@ def test_chart_is_self_contained_with_no_external_references(self):
         workflow = self.read_workflow()
 
         self.assertIn("<svg xmlns=", workflow)
-        self.assertIn("prefers-color-scheme: light", workflow)
         self.assertIn('role="img"', workflow)
+
+        # No media query, deliberately. GitHub's theme toggle does not reach
+        # one inside an <img>-embedded SVG, so a self-theming file shows a
+        # white card to anyone reading GitHub dark with a light OS. Two files
+        # and a README <picture> is the mechanism that does follow the toggle.
+        self.assertNotIn("prefers-color-scheme", workflow)
         for forbidden in ("<script", "xlink:href", "<foreignObject", "@import"):
             self.assertNotIn(forbidden, workflow)
 
@@ -136,6 +144,60 @@ def test_generator_rejects_traversal_and_a_non_positive_page_cap(self):
         self.assertNotIn("Math.min(Math.ceil(total / 100), maxPages)", workflow)
         self.assertNotIn("::warning::capping", workflow)
 
+    def test_an_accent_that_is_not_a_colour_fails_rather_than_drawing_nothing(self):
+        """An unset or malformed accent reaches the SVG as stroke="" and
+        renders a chart with no line: a green run producing a broken image,
+        which is the silent-success shape this whole workflow exists to kill.
+        """
+        workflow = self.read_workflow()
+
+        self.assertIn("/^#[0-9a-fA-F]{6}$/.test(accent ?? '')", workflow)
+        # Required with no default, so a caller cannot inherit someone else's
+        # brand colour by forgetting to pass its own.
+        accent_block = workflow.split("      accent:\n", 1)[1].split("      max-pages:", 1)[0]
+        self.assertIn("required: true", accent_block)
+        self.assertNotIn("default:", accent_block)
+
+    def test_both_themes_are_written_and_committed_together(self):
+        """A <picture> that gained a fresh light chart and kept a stale dark
+        one shows two different histories depending on who is looking, and
+        nothing reports it as wrong."""
+        workflow = self.read_workflow()
+
+        self.assertIn("writeFileSync(target, light)", workflow)
+        self.assertIn("writeFileSync(darkTarget, dark)", workflow)
+        self.assertIn('DARK_PATH="${OUTPUT_PATH%.svg}-dark.svg"', workflow)
+        self.assertIn('git add -- "$OUTPUT_PATH" "$DARK_PATH"', workflow)
+        self.assertIn('git status --porcelain -- "$OUTPUT_PATH" "$DARK_PATH"', workflow)
+
+        # Both derivations strip a .svg suffix, so the input has to have one.
+        self.assertIn("!out.endsWith('.svg')", workflow)
+
+    def test_the_documented_trigger_is_the_release_cut_not_a_cron(self):
+        """A committed artifact refreshed on a schedule mutates underneath a
+        tag, which is what 'main is the released version' forbids."""
+        workflow = self.read_workflow()
+
+        example = workflow.split("#   on:\n", 1)[1].split("#   permissions:", 1)[0]
+        self.assertIn("release:", example)
+        self.assertIn("types: [published]", example)
+        self.assertIn('#         accent: "#49bcfb"', workflow)
+        self.assertNotIn("cron", example)
+        self.assertNotIn("schedule:", example)
+
+    def test_the_embedded_renderer_names_its_source(self):
+        """The same renderer exists here and in ops. Hand-copying is how they
+        drift, so the block is generated and says so."""
+        workflow = self.read_workflow()
+
+        self.assertIn("// BEGIN GENERATED FROM ops scripts/starchart/render-chart.mjs", workflow)
+        self.assertIn("// END GENERATED", workflow)
+        self.assertIn("splice-into-workflow.mjs", workflow)
+        self.assertLess(
+            workflow.index("// BEGIN GENERATED"),
+            workflow.index("// END GENERATED"),
+        )
+
     def test_too_few_stars_is_a_clean_exit_not_a_failure(self):
         """A young repo having one star is a real state, not a broken build.
         Reporting red there trains people to ignore the signal."""

.github/workflows/main-is-released.yml

@@ -0,0 +1,92 @@
+name: Main Is Released
+
+# Asserts the one invariant behind "main is the released version, not the
+# newest work": every commit on main is a tagged release, so an untagged main
+# head is itself the alarm (REPOSITORY_ONBOARDING.md section 3).
+#
+# Callers declare their own triggers and pin this file by full commit SHA:
+#
+#   on:
+#     schedule: [{cron: "23 7 * * *"}]
+#     push:
+#       branches: [main]
+#     workflow_dispatch:
+#   permissions: {}
+#   jobs:
+#     released:
+#       uses: CodesWhat/.github/.github/workflows/main-is-released.yml@<full SHA>
+#
+# Continuously deployed repositories that never tag (a website, a meta repo)
+# should not call this at all rather than calling it with a carve-out input.
+# For them "main equals production" is enforced by the deploy, not by a tag.
+
+on:
+  workflow_call:
+    inputs:
+      allow-prerelease:
+        description: >
+          Accept a prerelease tag (-rc.N, -beta.N) as satisfying the invariant.
+          Defaults false: a release candidate on main is the exact drift this
+          check exists to catch.
+        required: false
+        default: false
+        type: boolean
+
+permissions: {}
+
+jobs:
+  released:
+    name: Main Is Released
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: read # Read main and its tags.
+
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: block
+          allowed-endpoints: >
+            github.com:443
+
+      - name: Check out main with tags
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          # Tags only travel with full history; a shallow clone would make
+          # describe fail for the wrong reason and read as real drift.
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Assert main points at a release tag
+        env:
+          ALLOW_PRERELEASE: ${{ inputs.allow-prerelease }}
+        run: |
+          set -euo pipefail
+
+          # Prove the measurement can work before trusting its result. A repo
+          # with no tags at all reports the same "not tagged" as one that
+          # drifted, and those need different answers.
+          if [ -z "$(git tag)" ]; then
+            echo "::error::no tags in this repository, so the invariant cannot be evaluated; a repository that never releases should not call this workflow" >&2
+            exit 1
+          fi
+
+          if ! tag="$(git describe --exact-match --tags HEAD 2>/dev/null)"; then
+            latest="$(git describe --tags --abbrev=0 HEAD 2>/dev/null || echo '<none reachable>')"
+            ahead="$(git rev-list --count "${latest}..HEAD" 2>/dev/null || echo '?')"
+            echo "::error::main is not a tagged release. Newest reachable tag is ${latest}, and main is ${ahead} commit(s) past it. Either cut a release or move the unshipped work to a dev branch." >&2
+            exit 1
+          fi
+
+          case "$tag" in
+            *-*)
+              if [ "$ALLOW_PRERELEASE" != "true" ]; then
+                echo "::error::main points at prerelease ${tag}. Prereleases belong on the dev branch; main carries what users actually run." >&2
+                exit 1
+              fi
+              echo "::warning::main points at prerelease ${tag}, accepted because allow-prerelease is set" ;;
+          esac
+
+          echo "main is released at ${tag}"

.github/workflows/standards-validation.yml

@@ -54,6 +54,7 @@ jobs:
           python3 .github/tests/quality_report_contract_test.py
           python3 .github/tests/reusable_ci_contract_test.py
           python3 .github/tests/starchart_refresh_contract_test.py
+          python3 .github/tests/main_is_released_contract_test.py
 
       - name: Lint Markdown
         run: |