feat: add CLI-first GitHub repository enhancement workflow

.github/workflows/docs-sync.yml

@@ -1,24 +1,17 @@
 name: docs-sync
 
 on:
-  pull_request:
-  push:
-    branches:
-      - main
+  workflow_call:
   workflow_dispatch:
-  merge_group:
 
 permissions:
   contents: read
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref || github.run_id }}
-  cancel-in-progress: true
-
 jobs:
   verify-generated-docs:
     name: generated docs drift
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.github/workflows/pr-validation.yml

@@ -20,9 +20,12 @@ jobs:
     name: dependency manifest validation
     if: ${{ github.event_name == 'pull_request' && (github.actor == 'dependabot[bot]' || startsWith(github.head_ref, 'dependabot/')) }}
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Setup Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
@@ -48,6 +51,7 @@ jobs:
   generated-docs-and-version:
     name: generated docs and version sync
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -102,26 +106,36 @@ jobs:
           echo "Checking version plan from ${base_sha} to ${HEAD_SHA}"
           uv run --frozen python ls/tools/localsetup.py --source-root . version-plan --base "$base_sha" --head "$HEAD_SHA"
           uv run --frozen python ls/tools/localsetup.py --source-root . version-sync --check --base "$base_sha" --head "$HEAD_SHA"
-          uv run --frozen python ls/tools/generate_docs_artifacts.py --repo-root .
-          uv run --frozen python ls/tools/localsetup.py --source-root . generate-docs
           git diff --exit-code
 
-  framework-validation:
-    name: framework validation py${{ matrix.python-version }}
+  documentation:
+    name: documentation
+    uses: ./.github/workflows/docs-sync.yml
+
+  quality:
+    name: quality
+    uses: ./.github/workflows/qc-ci.yml
+
+  framework-prerequisites:
+    name: framework prerequisites
+    permissions:
+      contents: read
+      actions: read
+    needs: [generated-docs-and-version, shell-smoke-and-audit, documentation, quality]
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version:
-          - "3.12"
+    timeout-minutes: 15
+    outputs:
+      reuse: ${{ steps.evidence.outputs.reuse }}
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Setup Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.12"
 
       - name: Setup uv
         uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
@@ -140,6 +154,9 @@ jobs:
       - name: Validate product branding
         run: uv run --frozen python ls/tools/validate_branding.py --repo-root . --strict
 
+      - name: Validate Python architecture
+        run: uv run --frozen python ls/tools/python_architecture_check.py --repo-root . --baseline ls/config/python-architecture-baseline.json
+
       - name: Validate catalogs and migration boundaries
         run: |
           uv run --frozen python ls/tools/localsetup.py --source-root . validate-catalog
@@ -151,17 +168,99 @@ jobs:
           uv run --frozen python ls/tools/localsetup.py --source-root . adopt --target-directory .
           uv run --frozen python ls/tools/localsetup.py --source-root . sbom --out /tmp/localsetup-source.cdx.json
 
+
+      - name: Reuse successful validation of this exact commit
+        id: evidence
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CANDIDATE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: |
+          set -euo pipefail
+          python ls/tools/ci_evidence.py --repository "$GITHUB_REPOSITORY" \
+            --sha "$CANDIDATE_SHA" --exclude-run-id "$GITHUB_RUN_ID" \
+            --job 'framework validation py3.12' \
+            --job 'shell smoke and framework audit' \
+            --job 'generated docs and version sync' \
+            --job 'documentation / generated docs drift' \
+            --job 'quality / deterministic qc' > /tmp/ci-evidence.json
+          cat /tmp/ci-evidence.json >> "$GITHUB_STEP_SUMMARY"
+          if [[ "$GITHUB_EVENT_NAME" = workflow_dispatch ]]; then
+            echo "reuse=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "reuse=$(python -c 'import json; print(str(json.load(open("/tmp/ci-evidence.json"))["ok"]).lower())')" >> "$GITHUB_OUTPUT"
+
+  framework-validation:
+    name: framework shard ${{ matrix.shard }} py${{ matrix.python-version }}
+    needs: framework-prerequisites
+    if: needs.framework-prerequisites.outputs.reuse != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12"]
+        shard: [0, 1, 2, 3, 4, 5, 6, 7]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Setup Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.11.21"
+          prune-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --frozen --all-groups --python python3
+
       - name: Run pytest
+        env:
+          CANDIDATE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
         run: |
+          set -euo pipefail
+          test "$(git rev-parse HEAD)" = "$CANDIDATE_SHA"
           workers="$(uv run --frozen python ls/tools/localsetup.py --source-root . test-workers)"
-          uv run --frozen --group s3-sdk pytest -n "$workers" ls/tests -q
+          uv run --frozen --group s3-sdk pytest -n "$workers" ls/tests -q \
+            --ci-shard=${{ matrix.shard }} --ci-shards=8 --maxfail=1 --durations=20
+
+  framework-result:
+    name: framework validation py3.12
+    needs: [framework-prerequisites, framework-validation]
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Require all shards or verified prior success
+        env:
+          PREREQUISITES: ${{ needs.framework-prerequisites.result }}
+          REUSED: ${{ needs.framework-prerequisites.outputs.reuse }}
+          SHARDS: ${{ needs.framework-validation.result }}
+        run: |
+          set -euo pipefail
+          test "$PREREQUISITES" = success
+          if [[ "$REUSED" = true ]]; then
+            test "$SHARDS" = skipped
+          else
+            test "$SHARDS" = success
+          fi
 
   shell-smoke-and-audit:
     name: shell smoke and framework audit
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Setup Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0

.github/workflows/publish.yml

@@ -23,7 +23,7 @@ jobs:
     name: verify committed release documentation
     if: github.ref == 'refs/heads/main' || inputs.mode == 'qualify'
     runs-on: ubuntu-latest
-    timeout-minutes: 165
+    timeout-minutes: ${{ inputs.mode == 'qualify' && 165 || 15 }}
     permissions:
       contents: write
     outputs:
@@ -146,6 +146,12 @@ jobs:
     needs: prepare-documentation
     if: github.ref == 'refs/heads/main' && inputs.mode == 'release'
     name: publish release
+    permissions:
+      contents: write
+      actions: read
+      id-token: write
+      attestations: write
+    timeout-minutes: 45
     env:
       RELEASE_DOCS_STATE: ${{ needs.prepare-documentation.outputs.state }}
     runs-on: ubuntu-latest
@@ -225,18 +231,19 @@ jobs:
           git -c gpg.format=openpgp -c gpg.program=gpg verify-commit --raw "$RELEASE_COMMIT" > "$RELEASE_DOCS_STATE/commit-status" 2>&1
           grep -Eq "^\[GNUPG:\] VALIDSIG ${signer}( |$)" "$RELEASE_DOCS_STATE/commit-status"
 
-      - name: Run publish validation
+      - name: Require successful validation of this exact commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CANDIDATE_SHA: ${{ needs.prepare-documentation.outputs.head }}
         run: |
           set -euo pipefail
-          uv run --frozen python ls/tools/generate_docs_artifacts.py --repo-root .
-          uv run --frozen python ls/tools/localsetup.py --source-root . generate-docs
-          git diff --exit-code
-          uv run --frozen python ls/tools/localsetup.py --source-root . validate-catalog
-          uv run --frozen python ls/tools/python_architecture_check.py --repo-root . --baseline ls/config/python-architecture-baseline.json
-          uv run --frozen python ls/skills/ls-framework-audit/scripts/run_framework_audit.py --output /tmp/ls-framework-audit.md
-          workers="$(uv run --frozen python ls/tools/localsetup.py --source-root . test-workers)"
-          uv run --frozen --group s3-sdk pytest -n "$workers" ls/tests -q
-          uv run --frozen ./ls/tests/automated_test.sh
+          python ls/tools/ci_evidence.py --repository "$GITHUB_REPOSITORY" \
+            --sha "$CANDIDATE_SHA" --require \
+            --job 'framework validation py3.12' \
+            --job 'shell smoke and framework audit' \
+            --job 'generated docs and version sync' \
+            --job 'documentation / generated docs drift' \
+            --job 'quality / deterministic qc'
           git diff --check
 
       - name: Build public artifact

.github/workflows/qc-ci.yml

@@ -1,27 +1,22 @@
 name: qc-ci
 
 on:
-  pull_request:
-  push:
-    branches:
-      - main
-  merge_group:
+  workflow_call:
   workflow_dispatch:
 
 permissions:
   contents: read
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref || github.run_id }}
-  cancel-in-progress: true
-
 jobs:
   qc-ci:
     name: deterministic qc
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Setup Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
@@ -44,7 +39,9 @@ jobs:
         run: uv run --frozen python tools/qc_patrol/cli.py deterministic --repo . --profile ci --out qc-out/ledger.json
 
       - name: Run QC tests
-        run: uv run --frozen pytest -q ls/tests/test_qc_patrol.py
+        run: |
+          workers="$(uv run --frozen python ls/tools/localsetup.py --source-root . test-workers)"
+          uv run --frozen pytest -n "$workers" -q ls/tests/test_qc_patrol.py --maxfail=1
 
       - name: Summarize QC
         run: |

.localsetup-release.json

@@ -2,9 +2,9 @@
   "schema_version": 2,
   "policy": "sequential-logical-slices",
   "anchor": {
-    "commit": "561abefe0ab59029bf3ef1ebca76d73c119008e7",
-    "version": "4.44.1",
-    "tag": "v4.44.1"
+    "commit": "b4273c1a246a47e32b6d50381db54ddb60099a5c",
+    "version": "4.44.3",
+    "tag": "v4.44.3"
   },
   "overrides": [],
   "major_line": 4,

AGENTS.md

@@ -117,6 +117,31 @@ Add or update tests under `ls/tests/` for changes to path resolution, discovery,
 
 - Use the full Python suite as final consolidation verification for broad framework changes, shared runtime behavior, release/publish work, dependency changes, or explicit user requests. Compute the default worker count with `localsetup test-workers`: `max(1, floor(available CPU cores / 3))`. Worker-consuming tests must not overlap unless they share that aggregate budget. Do not run the full suite as the default first-pass validation for routine daily work; the codebase is large and full-suite runs have noticeable CPU cost. Windows support is WSL2-only in the current framework.
 
+## Publishing Without Repeated Validation
+
+Use one authoritative full-suite result for an exact candidate commit. Hosted
+CI may supply that result; do not require an additional local full suite before
+pushing for CI, or repeat it merely because the same commit reaches main or
+release preparation. Focused local tests and static checks come first. Reuse
+successful evidence only when the tested commit, workflow, required jobs, and
+execution environment remain applicable; changed inputs invalidate that proof.
+
+Run cheap audit, catalog, version, and documentation checks before expensive
+validation. Hosted Python validation partitions all collected cases across eight
+isolated runners; each runner retains the normal worker budget. Each shard stops
+on its first failure, reports slow cases, and has a 60-minute job deadline. A
+failed or empty shard cannot satisfy the aggregate check. Rerun failed jobs after
+an understood transient failure; do not restart successful jobs without a reason.
+
+Finish a coherent source slice, update its release record, and generate docs once
+before the final push. Do not create cycles of source rebinding, regeneration,
+full tests, and reviews for unchanged content. One final material review covers
+the slice; small follow-up fixes need only affected checks. Model-assisted release
+prose is optional; reviewed source records and deterministic rendering are enough.
+Preserve exact-commit evidence, signed commits/tags, version arithmetic, and final
+artifact checks. Missing evidence is a concrete failure, never a reason to bypass
+a check or automatically start another hours-long release test run.
+
 ## Unit-Test Concurrency Policy
 
 Unless a repository explicitly defines a stricter policy, every unit-test runner—regardless of language or framework—MUST use an aggregate concurrency budget of `max(1, floor(available CPU cores / 3))`. Always round down before applying the minimum of one worker. Concurrent unit-test processes share that one budget; they MUST NOT each claim the full allowance.