Merge branch 'main' into fix/selfhost-pr-state-review-cache

Author: JSONbored

.claude/skills/contributing-to-gittensory/reference.md

@@ -26,12 +26,14 @@ path filter matched; on push to `main`, everything runs.
 | changes | `git diff --check` + path filter | `git diff --check` | trailing whitespace / conflict markers |
 | lint → actionlint | workflow lint | `npm run actionlint` | any `.github/workflows/*.yml` violation |
 | lint → migrations | migration guard | `npm run db:migrations:check` | duplicate/gap/misnamed migration number |
+| lint → cf-typegen | worker types drift | `npm run cf-typegen:check` | committed `worker-configuration.d.ts` is stale (run `npm run cf-typegen`) |
 | lint → typecheck | `tsc --noEmit` | `npm run typecheck` | any backend type error |
 | test (1/2) | sharded vitest + coverage | `npm run test:coverage` (unsharded) | any failing `test/**/*.test.ts` (excl. `test/workers/**`) |
 | workers | workers-pool vitest | `npm run test:workers` | any failing `test/workers/**` |
 | mcp → build | MCP pkg build | `npm run build:mcp` | MCP package build error |
 | mcp → pack | tarball hygiene | `npm run test:mcp-pack` | unexpected/forbidden file or stale README in the npm tarball |
 | ui → openapi drift | spec check | `npm run ui:openapi:check` | committed `openapi.json` is stale (run `npm run ui:openapi`) |
+| ui → openapi settings-parity | schema/type structural diff | `npm run ui:openapi:settings-parity` | `RepositorySettingsSchema` (src/openapi/schemas.ts) is missing a field the `RepositorySettings` type has |
 | ui → version audit | MCP version copy | `npm run ui:version-audit` | stale MCP version strings / non-`@latest` install copy (hits npm registry) |
 | ui → lint | `eslint .` (UI) | `npm run ui:lint` | ESLint **incl. Prettier formatting** + design-token rules |
 | ui → typecheck | `tsc --noEmit` (UI) | `npm run ui:typecheck` | UI type error |

.github/workflows/ci.yml

@@ -56,6 +56,8 @@ jobs:
               - 'scripts/**'
               - 'migrations/**'
               - '.github/workflows/**'
+              - 'wrangler.jsonc'
+              - 'worker-configuration.d.ts'
             # The UI's own app/extension code -- triggers the FULL toolchain (lint/typecheck/test/build).
             # A dependency bump (package.json/package-lock.json) stays here too since it can break the UI
             # build or types in ways only that full toolchain would catch.
@@ -190,6 +192,12 @@ jobs:
       - name: Check migrations
         if: ${{ github.event_name == 'push' || needs.changes.outputs.backend == 'true' }}
         run: npm run db:migrations:check
+      # Guards against the same staleness-drift class as db:migrations:check/ui:openapi:check: two PRs that
+      # each independently add a wrangler.jsonc binding can both pass CI in isolation, then merge sequentially
+      # and leave a stale committed worker-configuration.d.ts with zero prior gate signal (#2557).
+      - name: cf-typegen drift check
+        if: ${{ github.event_name == 'push' || needs.changes.outputs.backend == 'true' }}
+        run: npm run cf-typegen:check
       - name: Typecheck
         if: ${{ github.event_name == 'push' || needs.changes.outputs.backend == 'true' }}
         run: npm run typecheck
@@ -336,6 +344,12 @@ jobs:
       - name: OpenAPI drift check
         if: ${{ github.event_name == 'push' || needs.changes.outputs.ui == 'true' || needs.changes.outputs.uiContract == 'true' }}
         run: npm run ui:openapi:check
+      # #2556: RepositorySettingsSchema (hand-authored Zod) can silently drift from the actual
+      # RepositorySettings TS type -- the OpenAPI drift check above only verifies the generated spec
+      # matches the Zod schema, never that the schema matches the type the API actually serializes.
+      - name: OpenAPI settings-parity check
+        if: ${{ github.event_name == 'push' || needs.changes.outputs.ui == 'true' || needs.changes.outputs.uiContract == 'true' }}
+        run: npm run ui:openapi:settings-parity
       # Checks apps/gittensory-ui/src' known-latest MCP version string against the published package, so
       # its dependency is `ui` (the file it scans) + `mcp` (the package it checks against) -- NOT the
       # OpenAPI contract, which this script never reads.

.github/workflows/release-selfhost.yml

@@ -4,6 +4,12 @@
 #   git tag orb-v0.1.0 && git push origin orb-v0.1.0
 #
 # Pull:  docker pull ghcr.io/<owner>/gittensory-selfhost:orb-v0.1.0
+#
+# Prerelease tags (#1937): orb-v0.1.0-rc.1 / orb-v0.1.0-beta.1 run the identical pipeline but never move
+# `latest` and are marked prerelease on the GitHub Release -- for beta-testing an image before it becomes
+# the stable/latest recommendation.
+#
+#   git tag orb-v0.1.0-rc.1 && git push origin orb-v0.1.0-rc.1
 name: release-orb
 
 on:
@@ -13,7 +19,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Version to publish (e.g. 0.1.0)"
+        description: "Version to publish (e.g. 0.1.0, or a prerelease 0.1.0-rc.1 / 0.1.0-beta.1)"
         required: true
 
 permissions:
@@ -66,14 +72,23 @@ jobs:
               *) echo "expected an orb-v<semver> tag, got $REF_NAME" >&2; exit 1 ;;
             esac
           fi
-          if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
-            echo "expected semver version X.Y.Z, got $VERSION" >&2
+          # #1937: a stable X.Y.Z tag is the only kind that ever moved `latest` or an unmarked GitHub
+          # Release; a prerelease tag (X.Y.Z-rc.N / X.Y.Z-beta.N) publishes the SAME image/provenance/SBOM/
+          # Sentry pipeline below, just flagged as prerelease and never pushed under `latest` (see the
+          # "Resolve image tags" and "GitHub Release" steps).
+          if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-(rc|beta)\.[0-9]+)?$'; then
+            echo "expected semver version X.Y.Z, or a prerelease X.Y.Z-rc.N / X.Y.Z-beta.N, got $VERSION" >&2
             exit 1
           fi
+          PRERELEASE=false
+          if printf '%s' "$VERSION" | grep -Eq -- '-(rc|beta)\.[0-9]+$'; then
+            PRERELEASE=true
+          fi
           {
             echo "v=${VERSION}"
             echo "tag=orb-v${VERSION}"
             echo "release=gittensory-orb@${VERSION}"
+            echo "prerelease=${PRERELEASE}"
           } >> "$GITHUB_OUTPUT"
 
       # Release jobs receive publishing/Sentry credentials, so avoid shared dependency caches here.
@@ -139,15 +154,31 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      # #1937: `latest` must never move to a prerelease build -- an operator who blindly pulls `latest`
+      # for a trial should always land on the newest STABLE image, not an in-flight rc/beta.
+      - name: Resolve image tags
+        id: tags
+        env:
+          PRERELEASE: ${{ steps.version.outputs.prerelease }}
+          VERSION_TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          {
+            echo "list<<GTORBTAGS"
+            echo "type=raw,value=${VERSION_TAG}"
+            if [ "$PRERELEASE" != "true" ]; then
+              echo "type=raw,value=latest"
+            fi
+            echo "type=sha,format=short"
+            echo "GTORBTAGS"
+          } >> "$GITHUB_OUTPUT"
+
       - name: Image metadata
         id: meta
         uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6
         with:
           images: ghcr.io/${{ github.repository_owner }}/gittensory-selfhost
-          tags: |
-            type=raw,value=${{ steps.version.outputs.tag }}
-            type=raw,value=latest
-            type=sha,format=short
+          tags: ${{ steps.tags.outputs.list }}
           labels: |
             org.opencontainers.image.title=gittensory-orb
             org.opencontainers.image.description=Self-hostable Gittensory review engine
@@ -210,6 +241,7 @@ jobs:
           RELEASE_TAG: ${{ steps.version.outputs.tag }}
           RELEASE_ID: ${{ steps.version.outputs.release }}
           REPOSITORY_OWNER: ${{ github.repository_owner }}
+          PRERELEASE: ${{ steps.version.outputs.prerelease }}
         run: |
           set -euo pipefail
           NOTES="$(cat <<EOF
@@ -224,14 +256,23 @@ jobs:
           Sentry release id baked into the image: \`${RELEASE_ID}\`.
           EOF
           )"
+          # #1937: a prerelease tag never becomes the repo's "Latest release" and is visibly marked as such
+          # on GitHub -- distinct from the image-tag `latest` decision above (Resolve image tags), which
+          # this flag also drives at the version-resolution step.
+          PRERELEASE_ARGS=()
+          if [ "$PRERELEASE" = "true" ]; then
+            PRERELEASE_ARGS=(--prerelease --latest=false)
+          fi
           if gh release view "$REF_NAME" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
             gh release edit "$REF_NAME" --repo "$GITHUB_REPOSITORY" \
               --title "gittensory-orb ${RELEASE_TAG}" \
-              --notes "$NOTES"
+              --notes "$NOTES" \
+              "${PRERELEASE_ARGS[@]}"
           else
             gh release create "$REF_NAME" --repo "$GITHUB_REPOSITORY" \
               --verify-tag \
               --title "gittensory-orb ${RELEASE_TAG}" \
+              "${PRERELEASE_ARGS[@]}" \
               --notes "$NOTES" \
               --generate-notes
           fi

.gittensory.yml.example

@@ -135,6 +135,14 @@ gate:
     # the gate. Bool. Default: false.
     aiAdvisory: false
 
+  # Oversized-PR gate. A PR at/above BOTH the file-count and line-count thresholds
+  # (engine defaults, not configurable here) gets a manual-review HOLD finding —
+  # never a hard blocker, so it's dry-run/advisory friendly regardless of mode.
+  # off | advisory | block. Default: off. Config-as-code only — no DB column or
+  # dashboard toggle; this can only be set here.
+  size:
+    mode: off
+
   # Composite merge-readiness gate (no min score).
   # off | advisory | block. Default: off.
   mergeReadiness: off
@@ -145,6 +153,19 @@ gate:
   # off | advisory | block. Default: off.
   manifestPolicy: off
 
+  # Self-authored-linked-issue gate — blocks (or advises on) a PR whose only
+  # linked issue was opened by the PR's own author, which the readiness/quality
+  # signals can't otherwise catch. off | advisory | block. Default: advisory.
+  # DB-backed (dashboard-settable too); this overrides the stored value.
+  selfAuthoredLinkedIssue: advisory
+
+  # Gate-wide dry-run. When true, the gate evaluates and posts its verdict as
+  # normal but never actually blocks/merges/closes based on it — useful for
+  # trialing a stricter pack or mode change against real traffic before
+  # enforcing it. Bool. Default: false. Config-as-code only — no DB column or
+  # dashboard toggle; this can only be set here.
+  dryRun: false
+
   # First-time-contributor grace. RESERVED / currently INERT: this value is
   # parsed and stored, but the gate does not read it — a first-time
   # contributor with a real blocker is one-shot closed the same as a
@@ -162,6 +183,15 @@ gate:
   # PR, so it is opt-in rather than a new default.
   premergeContentRecheck: false
 
+  # Force-rebase-before-merge window in minutes (#2552, anti-race). When the base branch has advanced within
+  # this many minutes of the actual merge-decision moment, an agent-driven merge forces an update_branch +
+  # fresh CI recheck cycle before merging, instead of trusting a mergeable_state: clean read that may already
+  # be stale relative to a sibling commit that just landed on the base. A bounded retry cap prevents a
+  # fast-moving base from live-locking the PR — after a few forced attempts it falls through to a normal
+  # merge with an audit note. Positive integer (minutes), or omit/null. Default: null (never force).
+  # DB-backed (dashboard-settable too); this overrides the stored value.
+  requireFreshRebaseWindow: 10
+
   # AI maintainer review. Opt-in; the AI capabilities are switched on at the
   # deployment level.
   aiReview:
@@ -188,6 +218,11 @@ gate:
     # String or null. Default: null (the key record's model, else a conservative
     # per-provider default).
     model: null
+    # Minimum calibrated AI-reviewer confidence (0-1) for a consensus defect to
+    # become a blocker; below this it stays advisory-only. Number 0–1, or null.
+    # Default: null (engine uses 0.93). Config-as-code only — no DB column or
+    # dashboard toggle; this can only be set here.
+    closeConfidence: null
 
 
 # ----------------------------------------------------------------------------

apps/gittensory-ui/public/openapi.json

@@ -8631,6 +8631,63 @@
           },
           "contributorCapLabel": {
             "type": "string"
+          },
+          "sizeGateMode": {
+            "type": "string",
+            "enum": [
+              "off",
+              "advisory",
+              "block"
+            ]
+          },
+          "gateDryRun": {
+            "type": "boolean"
+          },
+          "premergeContentRecheck": {
+            "type": "boolean"
+          },
+          "aiReviewMode": {
+            "type": "string",
+            "enum": [
+              "off",
+              "advisory",
+              "block"
+            ]
+          },
+          "aiReviewByok": {
+            "type": "boolean"
+          },
+          "aiReviewProvider": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "anthropic",
+              "openai",
+              null
+            ]
+          },
+          "aiReviewModel": {
+            "type": "string",
+            "nullable": true
+          },
+          "aiReviewAllAuthors": {
+            "type": "boolean"
+          },
+          "aiReviewCloseConfidence": {
+            "type": "number",
+            "nullable": true
+          },
+          "closeOwnerAuthors": {
+            "type": "boolean"
+          },
+          "badgeEnabled": {
+            "type": "boolean"
+          },
+          "requireFreshRebaseWindowMinutes": {
+            "type": "integer",
+            "nullable": true,
+            "minimum": 0,
+            "exclusiveMinimum": true
           }
         },
         "required": [
@@ -8651,6 +8708,10 @@
           "selfAuthoredLinkedIssueGateMode",
           "firstTimeContributorGrace",
           "slopAiAdvisory",
+          "aiReviewMode",
+          "aiReviewByok",
+          "aiReviewAllAuthors",
+          "closeOwnerAuthors",
           "autoLabelEnabled",
           "gittensorLabel",
           "blacklistLabel",
@@ -9260,6 +9321,31 @@
               },
               "blacklistLabel": {
                 "type": "string"
+              },
+              "badgeEnabled": {
+                "type": "boolean"
+              },
+              "aiReviewMode": {
+                "type": "string",
+                "enum": [
+                  "off",
+                  "advisory",
+                  "block"
+                ]
+              },
+              "aiReviewByok": {
+                "type": "boolean"
+              },
+              "aiReviewProvider": {
+                "type": "string",
+                "nullable": true
+              },
+              "aiReviewModel": {
+                "type": "string",
+                "nullable": true
+              },
+              "aiReviewAllAuthors": {
+                "type": "boolean"
               }
             },
             "required": [
@@ -9285,6 +9371,12 @@
               "createMissingLabel",
               "includeMaintainerAuthors",
               "requireLinkedIssue",
+              "badgeEnabled",
+              "aiReviewMode",
+              "aiReviewByok",
+              "aiReviewProvider",
+              "aiReviewModel",
+              "aiReviewAllAuthors",
               "commandAuthorization"
             ]
           },

apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx

@@ -42,7 +42,7 @@ function SelfHostingReleases() {
           {
             title: "latest",
             description:
-              "Moves with the newest release. Useful for trials, not for controlled production.",
+              "Moves with the newest STABLE release only — never a prerelease. Useful for trials, not for controlled production.",
           },
           {
             title: "sha",
@@ -56,6 +56,22 @@ function SelfHostingReleases() {
 docker pull ghcr.io/jsonbored/gittensory-selfhost:latest`}
       />
 
+      <h2>Prerelease (beta/rc) images</h2>
+      <p>
+        A tag like <code>orb-v0.1.0-rc.1</code> or <code>orb-v0.1.0-beta.1</code> runs the identical
+        build/provenance/SBOM/Sentry pipeline as a stable release, but is marked prerelease on
+        GitHub and is never pushed under <code>latest</code>. External beta testers should pull the
+        exact prerelease tag, not <code>latest</code>.
+      </p>
+      <CodeBlock
+        lang="bash"
+        code={`docker pull ghcr.io/jsonbored/gittensory-selfhost:orb-v0.1.0-rc.1`}
+      />
+      <Callout variant="note">
+        Stable release behavior is unchanged: a plain <code>X.Y.Z</code> tag still moves{" "}
+        <code>latest</code> and publishes an unmarked (non-prerelease) GitHub Release.
+      </Callout>
+
       <h2>Upgrade flow</h2>
       <ol>
         <li>Read release notes for env, migration, or behavior changes.</li>

migrations/0093_gate_require_fresh_rebase_window.sql

@@ -0,0 +1,5 @@
+-- Force-rebase-before-merge gate (#2552): optional per-repo window (minutes). NULL (the default) means the
+-- gate never forces a rebase -- byte-identical behavior for every existing row. When set, an agent-driven
+-- merge whose base branch advanced within this window forces an update_branch + fresh CI recheck before
+-- merging, instead of trusting a mergeable_state: clean read that may already be stale relative to the base.
+ALTER TABLE repository_settings ADD COLUMN require_fresh_rebase_window_minutes INTEGER;