📦 deps(thirdparty): update snapshots

2026-07-18 00:02:59 +00:00
parent 82f7c6e56a
commit 47ce7f78dc
1446 changed files with 141041 additions and 6442 deletions
@@ -6,3 +6,11 @@

 # Documentation
 *.md @sickn33
+
+# AAS v1 independently frozen verifier baseline. Independent reviewer
+# attestations are content-addressed inside the protected baseline.
+/verification/aas-v1/ @sickn33
+/.github/workflows/aas-v1-baseline-check.yml @sickn33
+/.github/workflows/aas-v1-product-verifier.yml @sickn33
+/.github/workflows/aas-v1-verifier-harness.yml @sickn33
+/.github/CODEOWNERS @sickn33
@@ -20,7 +20,7 @@ There are 5 things that usually fail/get forgotten. **DO NOT FORGET THEM:**
 Committing is NOT enough. You must PUSH to the remote.

 - **BAD**: `git commit -m "feat: new skill"` (User sees nothing)
- **GOOD**: `git commit -m "..." && git push origin main`
+- **GOOD**: `git commit -m "..." && git push -u origin <topic-branch>` followed by a protected pull request

 ### 2. 🔄 SYNC GENERATED FILES (Avoid CI Drift)

@@ -52,11 +52,12 @@ it means the repository could not auto-sync generated artifacts cleanly and main
 - You must create/update `walkthrough.md` or `CHANGELOG.md` to document what changed.
 - If you made something new, **link it** in the artifacts.

-### 4. 🚫 NO BRANCHES
+### 4. 🛡️ PROTECTED MAIN

- **ALWAYS use the `main` branch.**
- NEVER create feature branches (e.g., `feat/new-skill`).
- We commit directly to `main` to keep history linear and simple.
+- **Never commit or push directly to `main`.** Branch protection applies to maintainers and administrators.
+- Make maintainer repairs on the contributor branch when allowed, or on a `codex/*`, `fix/*`, or release branch and open a pull request.
+- Merge accepted source PRs with `npm run merge:batch`; generated state follows through the protected `automation/canonical-repo-state` PR.
+- A request phrased as “push to main” names the final target state, not permission to bypass the protected PR lane.

 ### 5. 📦 RUNTIME DEPENDENCIES MUST BE RUNTIME DEPENDENCIES

@@ -144,10 +145,10 @@ Before ANY commit that adds/modifies skills, run the chain:
    git add README.md skills_index.json data/skills_index.json data/catalog.json data/bundles.json data/aliases.json CATALOG.md
    git commit -m "chore: sync generated files"
    ```
-    > 🔴 **CRITICAL for direct `main` work**: If you skip this on maintainer work that lands directly on `main`, CI will fail with "Detected uncommitted changes".
+    > 🔴 **CRITICAL for maintainer pull requests**: If you skip this, CI may detect canonical drift after merge and open a follow-up bot PR. Do not bypass protected `main`.
    > For contributor PRs, do **not** include derived registry artifacts. CI blocks direct edits to those files and previews drift separately.
    > See [`docs/maintainers/ci-drift-fix.md`](../docs/maintainers/ci-drift-fix.md) for details.
-    > `main` may still auto-commit canonical artifacts with `[ci skip]`, but only within the generated-files contract. If the sync leaves unmanaged drift, the workflow must fail instead of pushing a partial fix.
+    > Protected `main` never receives an automatic direct push. Canonical drift is published through the fixed `automation/canonical-repo-state` PR only when it stays inside the generated-files contract; unmanaged drift fails closed.

 ### B. When You Merge a PR (Step-by-Step)

@@ -155,6 +156,46 @@ Before ANY commit that adds/modifies skills, run the chain:

 **Before merging:**

+### Mandatory local reviewer gate for changed skills
+
+<!-- local-skill-reviewer-policy:v1 -->
+
+For every canonical `SKILL.md` change or change to one of its tracked bundle files, the maintainer must complete this local gate before the official merge gate:
+
+1. Stage only the exact changed skill and bundle blobs intended for review. The local reviewer reads the Git index; an unstaged correction is not reviewed, and unrelated paths must not be staged with it.
+2. Use a private result directory outside the repository and run:
+
+   ```bash
+   npm run review:skills:local -- review <skill-id> --merge-gate --result-dir <private-temp-dir>
+   ```
+
+3. Inspect `triage.reviewStatus`, `triage.priority`, and `triage.reasonCodes`. For P0/P1, uncertain, or locally namespaced `manual-review-required` results, choose exactly one semantic preparation route.
+
+   Single-skill semantic route (alternative to batch preparation):
+
+   ```bash
+   npm run review:skills:semantic:packet -- <skill-id> --result-dir <private-temp-dir>
+   ```
+
+   Obtain the Codex judgment for that packet, then import and verify it:
+
+   ```bash
+   npm run review:skills:semantic:import -- <skill-id> --input <codex-judgment.json> --result-dir <private-temp-dir>
+   npm run review:skills:semantic:verify -- <skill-id> --result-dir <private-temp-dir>
+   ```
+
+   Batch semantic route (alternative to the single-skill packet command):
+
+   ```bash
+   npm run review:skills:semantic:prepare -- --result-dir <private-temp-dir>
+   ```
+
+   For each escalated skill in that batch, obtain its Codex judgment, then run the same `semantic:import` and `semantic:verify` commands above. Never run `semantic:packet` and `semantic:prepare` for the same skill in the same result directory.
+
+4. After any correction, stage the exact intended blobs again and rerun the local reviewer, `npm run validate`, `npm run validate:references`, `npm run security:docs`, and the relevant tests.
+
+The local status is identified by `source: local-skill-reviewer`. It is triage and review support only: it does not replace Tessl, is not the CI status with the same name, and does not satisfy the exact-head attestation. A truthful Tessl `review` or the normal maintainer attestation bound to the full head SHA remains the official merge gate.
+
 1.  **CI is green** — Validation, warning-budget enforcement, README source-credit checks, reference checks, tests, and generated artifact steps passed (see [`.github/workflows/ci.yml`](workflows/ci.yml)). If the PR changes any `SKILL.md`, the separate [`skill-review` workflow](workflows/skill-review.yml) must also be green.
 2.  **Generated drift understood** — On pull requests, generator drift is informational only. Do not block a good PR solely because canonical artifacts would be regenerated. Also do not accept PRs that directly edit `CATALOG.md`, `skills_index.json`, or `data/*.json`; those files are `main`-owned.
 3.  **Quality Bar** — PR description confirms the [Quality Bar Checklist](.github/PULL_REQUEST_TEMPLATE.md) (metadata, risk label, credits if applicable).
@@ -176,9 +217,13 @@ This happens regularly on community PRs from forks. The common symptoms are:

 Use this playbook:

-1.  **Approve waiting fork runs** using the run id(s) from `gh run list`:
+1.  **Use the guarded maintainer command, never a raw run-approval API call.** It recomputes the complete base-to-head diff from exact Git objects, rejects unsafe paths/modes/types, validates workflow identity and PR metadata, and checks the head SHA again around approval:
    ```bash
-    gh api -X POST repos/<OWNER>/<REPO>/actions/runs/<RUN_ID>/approve
+    npm run merge:batch -- --prs <PR_NUMBER> --dry-run
+    ```
+    If canonical `SKILL.md` or its allowlisted supporting assets/references/resources changed, review the exact full head SHA shown by the command and supply it to the real run:
+    ```bash
+    npm run merge:batch -- --prs <PR_NUMBER> --reviewed-head <40-character-head-sha>
    ```
 2.  **Normalize the PR body** so it includes the repository template's `## Quality Bar Checklist ✅` section. If `gh pr edit` works, use it. If `gh pr edit` fails with the GraphQL `projectCards` / Projects Classic deprecation error, patch the PR body through the REST API instead:
    ```bash
@@ -190,8 +235,8 @@ Use this playbook:
    gh pr close <PR_NUMBER> --comment "Maintainer workflow refresh: closing and reopening to retrigger pull_request checks against the updated PR body."
    gh pr reopen <PR_NUMBER>
    ```
-5.  **Approve the newly created fork runs** after reopen. They will usually appear as a fresh pair of `action_required` runs for `Skills Registry CI` and `Skill Review`.
-6.  **Wait for the new checks only.** You may see older failed `pr-policy` runs in the rollup alongside newer green runs. Merge only after the fresh run set for the current PR state is fully green: `pr-policy`, `source-validation`, `artifact-preview`, and `review` when `SKILL.md` changed. `source-validation` now enforces the frozen warning budget and README source-credit coverage for changed skills, so missing `## When to Use` sections, missing README repo credits, or other new warning drift must be fixed before merge.
+5.  **Let `merge:batch` wait for and approve newly created fork runs** after reopen. GitHub Actions materializes those runs asynchronously, so an empty first lookup is not evidence that approval is unnecessary. Do not approve them directly by run ID; the command binds every approval to the current PR, exact head SHA, allowlisted workflow, locally recomputed diff, and the workflow/check-suite generation created after the reopen.
+6.  **Wait for the new checks only.** You may see older failed `pr-policy` runs in the rollup alongside newer green runs. Freshness is determined by workflow-run and check-suite IDs captured after the reopen, not by head SHA or completion time alone. Merge only after that fresh run set is fully green: `pr-policy`, `pr-evidence`, `source-validation`, `artifact-preview`, and a truthful skill-review outcome when `SKILL.md` changed. `review` means Tessl semantic review actually ran or reused a successful result for the identical skill-content fingerprint. `manual-review-required` means Tessl did not run because repository secrets or Tessl credits were unavailable and requires the exact-SHA maintainer attestation above. Never describe `manual-review-required` as a Tessl review, and never rerun Tessl merely because the PR head or base moved when the changed skill content is identical. `source-validation` enforces the frozen warning budget and README source-credit coverage for changed skills, so missing `## When to Use` sections, missing README repo credits, or other new warning drift must be fixed before merge.
 7.  **If `gh pr merge` says `Base branch was modified`**, refresh the PR state and retry. This is normal when you are merging a batch and `main` moved between attempts.

 **If a PR was closed after local integration (reopen and merge):**
@@ -238,7 +283,8 @@ We used this flow for PRs [#220](https://github.com/sickn33/agentic-awesome-skil
 **Maintainer shortcut for batched PRs:**

 - Use `npm run merge:batch -- --prs 450,449,446,451` to automate the ordered maintainer flow for multiple PRs. See [docs/maintainers/merge-batch.md](../docs/maintainers/merge-batch.md) for the short usage guide.
- The script keeps the GitHub-only squash merge rule, handles fork-run approvals and stale PR metadata refresh, waits only on fresh required checks, retries `Base branch was modified`, and runs the mandatory post-merge `sync:contributors` follow-up on `main`.
+- Pages is release-only: ordinary pushes to `main` never deploy it. Dispatch `.github/workflows/pages.yml` explicitly only at an approved publication gate. Canonical-sync merges still use `--skip-pages` and carry `[skip pages]` as a durable audit marker; required CI, the frozen AAS baseline, and CodeQL remain enforced.
+- The script keeps the GitHub-only squash merge rule, handles fork-run approvals and stale PR metadata refresh, waits only on fresh required checks, retries `Base branch was modified`, and runs the mandatory post-merge `sync:contributors` follow-up on `main`. The fork content allowlist applies only to external PRs; same-repository maintainer PRs may change repository-wide source while remaining subject to protected checks, trusted changed-skill evidence, exact-head review, and immutable PR identity.
 - It is intentionally not a conflict resolver. If a PR is conflicting, stop and follow the manual conflict playbook.

 ### C. Post-Merge Credits Sync (Mandatory After Every PR Merge)
@@ -270,9 +316,10 @@ Do this **immediately after each PR merge**. Do not defer it to release prep.
    - If the PR reveals that a credited repo is dead, renamed, archived, or overstated, fix the README entry in the same follow-up pass instead of leaving stale metadata behind.
    - Release notes are not a substitute for README attribution. If a repo appears in the merged work or planned release notes and belongs in credits, add it to the README at merge time.

-4.  **Commit and push README credit updates right away**:
-    - If `npm run sync:contributors` or the credit audit changed `README.md`, commit and push that follow-up immediately on `main`.
-    - Do not leave contributor or community-credit drift sitting locally until the next release.
+4.  **Publish README credit updates through the protected sync lane**:
+    - After the source batch, let the trusted canonical-sync workflow open or update `automation/canonical-repo-state` and merge that PR after its required checks.
+    - If an unmanaged credit repair is still required, make it on a topic branch and merge it by pull request; never push the follow-up directly to `main`.
+    - Do not leave contributor or community-credit drift until the next release.

 5.  **Then continue with normal maintenance**:
    - Verify Table of Contents if you touched headings.
@@ -393,11 +440,11 @@ Preflight verification → Changelog → `npm run release:prepare -- X.Y.Z` →
    npm run validate:strict
    ```
 2.  **Update Changelog**: Add the new release section to `CHANGELOG.md`.
-3.  **Prepare commit and tag locally**:
+3.  **Prepare the protected release PR**:
    ```bash
    npm run release:prepare -- X.Y.Z
    ```
-    This validates the release, aligns versioned files, writes the release notes artifact, creates the release commit, and creates the local tag.
+    This validates the release, aligns versioned files, writes the release notes artifact, creates the release commit on `release/vX.Y.Z`, pushes it, and opens the protected release PR. The tag is created only after that exact PR is merged.
 4.  **Create GitHub Release** (REQUIRED):

    > ⚠️ **CRITICAL**: Pushing a tag (`git push --tags`) is NOT enough. You must create a **GitHub Release Object** for it to appear in the sidebar and trigger the NPM publish workflow.
@@ -0,0 +1,193 @@
+name: AAS agent-first preview
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/aas-agent-first-preview.yml"
+      - "apps/web-app/**"
+      - "data/aas-v1/**"
+      - "schemas/aas-v1/**"
+      - "tools/bin/**"
+      - "tools/lib/**"
+      - "tools/scripts/tests/aas_v1_*.test.js"
+      - "verification/aas-preview/**"
+      - "package.json"
+      - "package-lock.json"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  candidate:
+    name: preview candidate
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    steps:
+      - name: Check out the exact candidate
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Use Node 22.23.1
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: 22.23.1
+          cache: npm
+
+      - name: Install without lifecycle scripts
+        run: npm ci --ignore-scripts
+
+      - name: Verify deterministic catalog and preview contracts
+        run: |
+          npm run check:aas-v1-catalog
+          npm run test:aas-v1
+          node --check verification/aas-preview/runner.mjs
+          node --check verification/aas-preview/aggregate.mjs
+          node --check verification/aas-preview/run-installed-candidate.mjs
+
+      - name: Pack the candidate without lifecycle scripts
+        run: npm pack --ignore-scripts
+
+      - name: Upload the exact candidate tarball
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: aas-preview-candidate
+          path: agentic-awesome-skills-*.tgz
+          if-no-files-found: error
+          retention-days: 7
+
+  functional:
+    name: ${{ matrix.job-id }}
+    needs: candidate
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - job-id: linux-node-22
+            os: ubuntu-24.04
+            node: 22.23.1
+          - job-id: linux-node-24
+            os: ubuntu-24.04
+            node: 24.18.0
+          - job-id: macos-node-22
+            os: macos-15-intel
+            node: 22.23.1
+          - job-id: macos-node-24
+            os: macos-15-intel
+            node: 24.18.0
+          - job-id: windows-node-22
+            os: windows-2025
+            node: 22.23.1
+          - job-id: windows-node-24
+            os: windows-2025
+            node: 24.18.0
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    steps:
+      - name: Check out the functional verifier
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+
+      - name: Use the exact matrix runtime
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Download the exact candidate
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: aas-preview-candidate
+          path: ${{ runner.temp }}/aas-preview-candidate
+
+      - name: Install and exercise the packed product
+        run: node verification/aas-preview/run-installed-candidate.mjs --artifact-root "${{ runner.temp }}/aas-preview-candidate" --install-root "${{ runner.temp }}/aas-preview-install" --work-root "${{ runner.temp }}/aas-preview-work" --job-id "${{ matrix.job-id }}" --out "${{ runner.temp }}/aas-preview-${{ matrix.job-id }}.json"
+
+      - name: Upload the functional receipt
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: aas-preview-${{ matrix.job-id }}
+          path: ${{ runner.temp }}/aas-preview-${{ matrix.job-id }}.json
+          if-no-files-found: error
+          retention-days: 7
+
+  workbench:
+    name: preview Workbench
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - name: Check out the exact candidate
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+
+      - name: Use Node 22.23.1
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: 22.23.1
+          cache: npm
+          cache-dependency-path: apps/web-app/package-lock.json
+
+      - name: Test and build the local review UI
+        run: |
+          npm ci --ignore-scripts
+          npm run app:install
+          npm run app:test
+          npm run app:build
+          node verification/aas-preview/write-workbench-receipt.mjs "$RUNNER_TEMP/aas-preview-workbench.json"
+
+      - name: Upload the Workbench receipt
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: aas-preview-workbench
+          path: ${{ runner.temp }}/aas-preview-workbench.json
+          if-no-files-found: error
+          retention-days: 7
+
+  aggregate:
+    name: aas-agent-first-preview
+    needs: [functional, workbench]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Check out the receipt aggregator
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+
+      - name: Use Node 22.23.1
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: 22.23.1
+
+      - name: Download all preview receipts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          pattern: aas-preview-*
+          path: ${{ runner.temp }}/aas-preview-receipts
+          merge-multiple: true
+
+      - name: Aggregate without weakening certified-v1 gates
+        shell: bash
+        run: |
+          set -euo pipefail
+          root="$RUNNER_TEMP/aas-preview-receipts"
+          node verification/aas-preview/aggregate.mjs \
+            --receipt "$root/aas-preview-linux-node-22.json" \
+            --receipt "$root/aas-preview-linux-node-24.json" \
+            --receipt "$root/aas-preview-macos-node-22.json" \
+            --receipt "$root/aas-preview-macos-node-24.json" \
+            --receipt "$root/aas-preview-windows-node-22.json" \
+            --receipt "$root/aas-preview-windows-node-24.json" \
+            --workbench "$root/aas-preview-workbench.json" \
+            --out "$RUNNER_TEMP/aas-agent-first-preview.json"
+
+      - name: Upload the aggregate preview receipt
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: aas-agent-first-preview-receipt
+          path: ${{ runner.temp }}/aas-agent-first-preview.json
+          if-no-files-found: error
+          retention-days: 30
@@ -0,0 +1,50 @@
+name: AAS v1 baseline freeze
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  baseline-freeze:
+    name: aas-v1-baseline
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Check out candidate baseline
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+
+      - name: Use the frozen verifier runtime
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: 22.23.1
+          cache: npm
+          cache-dependency-path: verification/aas-v1/verifier/package-lock.json
+
+      - name: Install verifier dependencies without lifecycle scripts
+        run: npm --prefix verification/aas-v1/verifier ci --ignore-scripts
+
+      - name: Run reference metric tests
+        run: npm --prefix verification/aas-v1/verifier test
+
+      - name: Validate frozen schemas and corpora
+        run: |
+          npm --prefix verification/aas-v1/verifier run check:schemas
+          npm --prefix verification/aas-v1/verifier run check:structure
+          npm --prefix verification/aas-v1/verifier run check:benchmark:frozen
+          npm --prefix verification/aas-v1/verifier run check:secondary:frozen
+
+      - name: Verify hostile fixtures and legacy snapshots
+        run: |
+          node verification/aas-v1/baseline/v1/hostile/verify-fixtures.mjs
+          node verification/aas-v1/baseline/v1/legacy/14.6.0/validate-snapshots.mjs
+
+      - name: Verify ownership, freeze readiness, and content digest
+        run: |
+          npm --prefix verification/aas-v1/verifier run check:freeze-ready
+          npm --prefix verification/aas-v1/verifier run freeze:check
@@ -0,0 +1,199 @@
+name: AAS v1 product verifier
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "tools/bin/aas.js"
+      - "tools/bin/aas-mcp.js"
+      - "tools/lib/aas-v1/**"
+      - "data/aas-v1/**"
+      - "schemas/aas-v1/**"
+      - "package.json"
+      - "package-lock.json"
+  workflow_dispatch:
+    inputs:
+      candidate_commit:
+        description: Full candidate commit SHA
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: aas-v1-product-${{ github.event.pull_request.head.sha || inputs.candidate_commit }}
+  cancel-in-progress: false
+
+jobs:
+  candidate-pack:
+    name: Candidate tarball
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    outputs:
+      commit: ${{ steps.identity.outputs.commit }}
+      verifier_commit: ${{ steps.identity.outputs.verifier_commit }}
+    steps:
+      - name: Resolve immutable candidate
+        id: identity
+        shell: bash
+        env:
+          PR_SHA: ${{ github.event.pull_request.head.sha }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          INPUT_SHA: ${{ inputs.candidate_commit }}
+          WORKFLOW_SHA: ${{ github.sha }}
+        run: |
+          sha="${PR_SHA:-$INPUT_SHA}"
+          verifier_sha="${BASE_SHA:-$WORKFLOW_SHA}"
+          [[ "$sha" =~ ^[0-9a-f]{40}$ ]] || exit 64
+          [[ "$verifier_sha" =~ ^[0-9a-f]{40}$ ]] || exit 64
+          echo "commit=$sha" >> "$GITHUB_OUTPUT"
+          echo "verifier_commit=$verifier_sha" >> "$GITHUB_OUTPUT"
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          ref: ${{ steps.identity.outputs.commit }}
+          path: candidate
+          persist-credentials: false
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: 24.18.0
+          cache: npm
+          cache-dependency-path: candidate/package-lock.json
+      - name: Pack without lifecycle execution
+        working-directory: candidate
+        shell: bash
+        run: |
+          mkdir -p "$RUNNER_TEMP/aas-candidate"
+          npm pack --ignore-scripts --json --pack-destination "$RUNNER_TEMP/aas-candidate" > "$RUNNER_TEMP/aas-pack.json"
+          test "$(find "$RUNNER_TEMP/aas-candidate" -maxdepth 1 -name '*.tgz' -type f | wc -l | tr -d ' ')" = 1
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: aas-v1-candidate-${{ steps.identity.outputs.commit }}
+          path: ${{ runner.temp }}/aas-candidate/*.tgz
+          if-no-files-found: error
+          retention-days: 14
+
+  verify:
+    name: ${{ matrix.id }}
+    needs: candidate-pack
+    env:
+      GIT_CONFIG_COUNT: 1
+      GIT_CONFIG_KEY_0: core.autocrlf
+      GIT_CONFIG_VALUE_0: "false"
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - id: linux-node-22
+            os: ubuntu-24.04
+            node: 22.23.1
+            fs_type: ext4
+            fs_case: sensitive
+          - id: linux-node-24
+            os: ubuntu-24.04
+            node: 24.18.0
+            fs_type: ext4
+            fs_case: sensitive
+          - id: macos-node-22
+            os: macos-15-intel
+            node: 22.23.1
+            fs_type: apfs
+            fs_case: insensitive-preserving
+          - id: macos-node-24
+            os: macos-15-intel
+            node: 24.18.0
+            fs_type: apfs
+            fs_case: insensitive-preserving
+          - id: windows-node-22
+            os: windows-2025
+            node: 22.23.1
+            fs_type: ntfs
+            fs_case: insensitive-preserving
+          - id: windows-node-24
+            os: windows-2025
+            node: 24.18.0
+            fs_type: ntfs
+            fs_case: insensitive-preserving
+    runs-on: ${{ matrix.os }}
+    continue-on-error: false
+    timeout-minutes: 45
+    steps:
+      - name: Checkout protected verifier revision
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          ref: ${{ needs.candidate-pack.outputs.verifier_commit }}
+          path: trusted
+          persist-credentials: false
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: aas-v1-candidate-${{ needs.candidate-pack.outputs.commit }}
+          path: ${{ runner.temp }}/candidate
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: trusted/verification/aas-v1/verifier/package-lock.json
+      - name: Install verifier dependencies only
+        working-directory: trusted/verification/aas-v1/verifier
+        run: npm ci --ignore-scripts
+      - name: Verify protected freeze before candidate execution
+        working-directory: trusted/verification/aas-v1/verifier
+        run: npm run freeze:check
+      - name: Run black-box verifier
+        shell: bash
+        env:
+          AAS_VERIFIER_RUNNER_LABEL: ${{ matrix.os }}
+          AAS_VERIFIER_FILESYSTEM_TYPE: ${{ matrix.fs_type }}
+          AAS_VERIFIER_FILESYSTEM_CASE: ${{ matrix.fs_case }}
+        run: |
+          tarball="$(find "$RUNNER_TEMP/candidate" -maxdepth 1 -name '*.tgz' -type f -print -quit)"
+          node trusted/verification/aas-v1/verifier/bin/verify-product.mjs \
+            --tarball "$tarball" \
+            --candidate-commit "${{ needs.candidate-pack.outputs.commit }}" \
+            --verifier-commit "${{ needs.candidate-pack.outputs.verifier_commit }}" \
+            --job-id "${{ matrix.id }}" \
+            --transaction-evidence "$RUNNER_TEMP/aas-transaction-evidence.json" \
+            --work-root "$RUNNER_TEMP/aas-v1-work" \
+            --out "$RUNNER_TEMP/aas-v1-${{ matrix.id }}.json"
+      - name: Upload immutable job receipt
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: aas-v1-receipt-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.id }}
+          path: ${{ runner.temp }}/aas-v1-${{ matrix.id }}.json
+          if-no-files-found: error
+          retention-days: 30
+
+  aggregate:
+    name: Aggregate exact matrix
+    if: always()
+    needs: [candidate-pack, verify]
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          ref: ${{ needs.candidate-pack.outputs.verifier_commit }}
+          path: trusted
+          persist-credentials: false
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          pattern: aas-v1-receipt-${{ github.run_id }}-${{ github.run_attempt }}-*
+          path: ${{ runner.temp }}/receipts
+          merge-multiple: true
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: 24.18.0
+      - name: Merge and enforce all six receipts
+        shell: bash
+        run: |
+          npm ci --ignore-scripts --prefix trusted/verification/aas-v1/verifier
+          node trusted/verification/aas-v1/verifier/bin/merge-product-evidence.mjs \
+            --out "$RUNNER_TEMP/aas-v1-evidence-bundle.json" \
+            "$RUNNER_TEMP"/receipts/*.json
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: aas-v1-evidence-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/aas-v1-evidence-bundle.json
+          if-no-files-found: error
+          retention-days: 30
@@ -0,0 +1,58 @@
+name: AAS v1 verifier harness
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "verification/aas-v1/**"
+      - ".github/workflows/aas-v1-verifier-harness.yml"
+      - ".github/workflows/aas-v1-product-verifier.yml"
+      - ".github/CODEOWNERS"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  harness:
+    name: ${{ matrix.id }}
+    env:
+      GIT_CONFIG_COUNT: 1
+      GIT_CONFIG_KEY_0: core.autocrlf
+      GIT_CONFIG_VALUE_0: "false"
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { id: linux-node-22, os: ubuntu-24.04, node: 22.23.1 }
+          - { id: linux-node-24, os: ubuntu-24.04, node: 24.18.0 }
+          - { id: macos-node-22, os: macos-15-intel, node: 22.23.1 }
+          - { id: macos-node-24, os: macos-15-intel, node: 24.18.0 }
+          - { id: windows-node-22, os: windows-2025, node: 22.23.1 }
+          - { id: windows-node-24, os: windows-2025, node: 24.18.0 }
+    runs-on: ${{ matrix.os }}
+    continue-on-error: false
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: verification/aas-v1/verifier/package-lock.json
+      - name: Install verifier without lifecycle execution
+        working-directory: verification/aas-v1/verifier
+        run: npm ci --ignore-scripts
+      - name: Schemas, structure, freeze and self-tests
+        working-directory: verification/aas-v1/verifier
+        shell: bash
+        run: |
+          npm run check:schemas
+          npm run check:structure
+          npm run freeze:check
+          npm test
+      - name: Platform-native observer sentinel
+        working-directory: verification/aas-v1/verifier
+        run: npm run test:platform -- --job-id ${{ matrix.id }}
@@ -21,13 +21,5 @@ jobs:
      - name: Checkout
        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5

-      - name: Download actionlint
-        env:
-          ACTIONLINT_VERSION: "1.7.12"
-        run: |
-          set -euo pipefail
-          curl -fsSLO "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
-          tar -xzf "actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
-
      - name: Run actionlint
-        run: ./actionlint -color
+        run: npm run lint:workflows
@@ -6,13 +6,22 @@ on:
  pull_request:
    branches: ["main"]
  workflow_dispatch:
+    inputs:
+      canonical_sync_pr:
+        description: Validate the trusted canonical-sync bot branch
+        required: false
+        default: false
+        type: boolean

 permissions:
  contents: read

+env:
+  IS_TRUSTED_CANONICAL_SYNC_PR: ${{ inputs.canonical_sync_pr == true || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.head_ref == 'automation/canonical-repo-state' && github.event.pull_request.user.login == 'github-actions[bot]') }}
+
 jobs:
  pr-policy:
-    if: github.event_name == 'pull_request'
+    if: github.event_name == 'pull_request' || inputs.canonical_sync_pr == true
    runs-on: ubuntu-latest
    outputs:
      primary_category: ${{ steps.intake.outputs.primary_category }}
@@ -32,14 +41,16 @@ jobs:
        with:
          node-version: "lts/*"

-      - name: Install npm dependencies
+      - name: Install PR policy dependencies
+        if: github.event_name == 'pull_request' && env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true'
        run: npm ci --ignore-scripts

      - name: Fetch base branch
-        run: git fetch origin "${{ github.base_ref }}"
+        run: git fetch origin "${{ github.base_ref || 'main' }}"

      - name: Intake PR change
        id: intake
+        if: github.event_name == 'pull_request' && env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true'
        run: |
          node tools/scripts/pr_preflight.cjs \
            --base "origin/${{ github.base_ref }}" \
@@ -49,14 +60,72 @@ jobs:
            --write-github-output \
            --write-step-summary

-      - name: Enforce PR source-only contract
+      - name: Validate canonical-sync path boundary
+        if: env.IS_TRUSTED_CANONICAL_SYNC_PR == 'true'
        run: |
-          if [ "${{ steps.intake.outputs.direct_derived_changes_count }}" != "0" ]; then
+          test "${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" = "automation/canonical-repo-state"
+          node tools/scripts/validate_canonical_sync_pr.cjs --base origin/main --head HEAD
+
+      - name: Validate protected release path boundary
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && startsWith(github.head_ref, 'release/v') && github.event.pull_request.user.login == github.repository_owner
+        run: |
+          trusted_root="$RUNNER_TEMP/release-policy-main"
+          git worktree add --detach "$trusted_root" origin/main
+          node "$trusted_root/tools/scripts/validate_canonical_sync_pr.cjs" \
+            --base origin/main \
+            --head HEAD \
+            --include-release-managed
+
+      - name: Set up Python for canonical reproduction
+        if: env.IS_TRUSTED_CANONICAL_SYNC_PR == 'true'
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.10"
+
+      - name: Reproduce canonical-sync tree from trusted main
+        if: env.IS_TRUSTED_CANONICAL_SYNC_PR == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          trusted_root="$RUNNER_TEMP/canonical-main"
+          git worktree add --detach "$trusted_root" origin/main
+          cd "$trusted_root"
+          pip install -r tools/requirements.txt
+          npm ci --ignore-scripts
+          npm run sync:repo-state
+
+          mapfile -t managed_files < <(node tools/scripts/generated_files.js --include-mixed)
+          git add -- "${managed_files[@]}" || true
+          if [ -n "$(git diff --name-only)" ] || [ -n "$(git ls-files --others --exclude-standard)" ]; then
+            echo "::error::Trusted canonical reproduction produced unmanaged drift."
+            git status --short
+            exit 1
+          fi
+
+          expected_tree=$(git write-tree)
+          actual_tree=$(git -C "$GITHUB_WORKSPACE" rev-parse 'HEAD^{tree}')
+          test "$expected_tree" = "$actual_tree"
+
+      - name: Install npm dependencies
+        if: env.IS_TRUSTED_CANONICAL_SYNC_PR == 'true'
+        run: npm ci --ignore-scripts
+
+      - name: Enforce PR source-only contract
+        if: github.event_name == 'pull_request' && env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true'
+        env:
+          IS_TRUSTED_RELEASE_PR: ${{ github.event.pull_request.head.repo.full_name == github.repository && startsWith(github.head_ref, 'release/v') && github.event.pull_request.user.login == github.repository_owner }}
+        run: |
+          if [ "${{ steps.intake.outputs.direct_derived_changes_count }}" != "0" ] && [ "$IS_TRUSTED_RELEASE_PR" != "true" ]; then
            echo "Pull requests must stay source-only."
            echo "Remove derived files and let main regenerate them after merge."
            exit 1
          fi

+          if [ "$IS_TRUSTED_RELEASE_PR" = "true" ]; then
+            echo "Protected same-repository release PR may include scripted release artifacts."
+          fi
+
          if [ "${{ steps.intake.outputs.has_quality_checklist }}" != "true" ]; then
            echo "PR body must include the Quality Bar Checklist from the template."
            exit 1
@@ -67,9 +136,9 @@ jobs:
          fi

  source-validation:
-    if: github.event_name == 'pull_request'
+    if: github.event_name == 'pull_request' || inputs.canonical_sync_pr == true
    runs-on: ubuntu-latest
-    needs: pr-policy
+    needs: [pr-policy, pr-evidence]
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
@@ -89,7 +158,7 @@ jobs:
          node-version: "lts/*"

      - name: Fetch base branch
-        run: git fetch origin "${{ github.base_ref }}"
+        run: git fetch origin "${{ github.base_ref || 'main' }}"

      - name: Install npm dependencies
        run: npm ci
@@ -110,6 +179,7 @@ jobs:
        run: npm run check:warning-budget

      - name: Verify README source credits for changed skills
+        if: github.event_name == 'pull_request' && env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true'
        run: npm run check:readme-credits -- --base "origin/${{ github.base_ref }}" --head HEAD

      - name: Validate references
@@ -119,6 +189,9 @@ jobs:
      - name: Audit npm dependencies
        run: npm audit --audit-level=high

+      - name: Refresh ephemeral derived sources for tests
+        run: npm run plugin-compat:sync && npm run index && npm run bundles:sync
+
      - name: Run tests
        run: npm run test

@@ -131,8 +204,101 @@ jobs:
      - name: Run docs security checks
        run: npm run security:docs

+  pr-evidence:
+    if: github.event_name == 'pull_request' || inputs.canonical_sync_pr == true
+    runs-on: ubuntu-latest
+    needs: pr-policy
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.10"
+
+      - name: Set up Node
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: "lts/*"
+
+      - name: Install trusted dependencies
+        run: |
+          pip install -r tools/requirements.txt
+          npm ci --ignore-scripts
+
+      - name: Fetch base branch
+        run: git fetch origin "${{ github.base_ref || 'main' }}"
+
+      - name: Generate PR intake JSON
+        if: github.event_name == 'pull_request' && env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true'
+        run: |
+          mkdir -p .tmp/pr-evidence
+          node tools/scripts/pr_preflight.cjs \
+            --base "origin/${{ github.base_ref }}" \
+            --head HEAD \
+            --event-path "$GITHUB_EVENT_PATH" \
+            --no-run \
+            --json > .tmp/pr-evidence/preflight.json
+
+      - name: Generate changed-skill evidence
+        id: changed_skill_evidence
+        if: github.event_name == 'pull_request' && env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true'
+        continue-on-error: true
+        run: |
+          node tools/scripts/run-python.js tools/scripts/changed_skill_evidence.py \
+            --base "origin/${{ github.base_ref }}" \
+            --head HEAD \
+            --output .tmp/pr-evidence/changed-skills.json
+
+      - name: Resolve advisory semantic-review state
+        id: semantic_review
+        if: github.event_name == 'pull_request' && env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true'
+        env:
+          HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
+          BASE_REPOSITORY: ${{ github.repository }}
+        run: |
+          if [ "$HEAD_REPOSITORY" != "$BASE_REPOSITORY" ]; then
+            echo "state=unavailable" >> "$GITHUB_OUTPUT"
+          else
+            echo "state=unknown" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Generate shadow decision manifest
+        id: decision_manifest
+        if: always() && hashFiles('.tmp/pr-evidence/changed-skills.json') != ''
+        run: |
+          node tools/scripts/pr_decision_manifest.cjs \
+            --preflight .tmp/pr-evidence/preflight.json \
+            --evidence .tmp/pr-evidence/changed-skills.json \
+            --semantic-review-state "${{ steps.semantic_review.outputs.state }}" \
+            --output .tmp/pr-evidence/decision-manifest.json \
+            --write-github-output \
+            --write-step-summary
+
+      - name: Upload advisory evidence
+        if: always() && github.event_name == 'pull_request' && env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: pr-evidence-${{ github.event.pull_request.number }}
+          path: .tmp/pr-evidence/
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Enforce deterministic changed-skill gate
+        if: github.event_name == 'pull_request' && env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true' && steps.changed_skill_evidence.outcome == 'failure'
+        run: |
+          echo "Changed-skill evidence reported a blocking regression or operational failure."
+          exit 1
+
+      - name: Record canonical-sync evidence boundary
+        if: env.IS_TRUSTED_CANONICAL_SYNC_PR == 'true'
+        run: echo "Canonical-sync content is verified by managed-path and reproducibility gates."
+
  artifact-preview:
-    if: github.event_name == 'pull_request'
+    if: github.event_name == 'pull_request' || inputs.canonical_sync_pr == true
    runs-on: ubuntu-latest
    needs: [pr-policy, source-validation]
    steps:
@@ -155,11 +321,18 @@ jobs:
        run: npm ci

      - name: Generate canonical artifacts preview
+        if: env.IS_TRUSTED_CANONICAL_SYNC_PR != 'true'
        run: |
          npm run chain
          npm run catalog
          npm run sync:web-assets

+      - name: Reproduce canonical-sync PR from main
+        if: env.IS_TRUSTED_CANONICAL_SYNC_PR == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: npm run sync:repo-state
+
      - name: Report generated drift
        run: |
          mapfile -t managed_files < <(node tools/scripts/generated_files.js --include-mixed)
@@ -184,6 +357,12 @@ jobs:
            exit 0
          fi

+          if [ "$IS_TRUSTED_CANONICAL_SYNC_PR" = "true" ]; then
+            echo "::error::Canonical-sync PR is not byte-for-byte reproducible from main."
+            printf '%s\n' "$drift_files"
+            exit 1
+          fi
+
          echo "::notice::Generated drift detected in artifact preview."
          {
            echo "- Generated drift: detected"
@@ -193,19 +372,20 @@ jobs:
          } >> "$GITHUB_STEP_SUMMARY"

  main-validation-and-sync:
-    if: github.event_name != 'pull_request'
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.canonical_sync_pr != true && github.ref == 'refs/heads/main')
    runs-on: ubuntu-latest
    concurrency:
      group: canonical-main-sync
      cancel-in-progress: false
    permissions:
+      actions: write
      contents: write
-    env:
-      GH_TOKEN: ${{ github.token }}
+      pull-requests: write
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          fetch-depth: 0
+          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
@@ -236,6 +416,8 @@ jobs:
        run: npm run validate:references

      - name: Run repo-state sync
+        env:
+          GH_TOKEN: ${{ github.token }}
        run: npm run sync:repo-state

      - name: Audit npm dependencies
@@ -253,16 +435,7 @@ jobs:
      - name: Run docs security checks
        run: npm run security:docs

-      - name: Set up GitHub credentials
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          set -euo pipefail
-          git config user.name 'github-actions[bot]'
-          git config user.email 'github-actions[bot]@users.noreply.github.com'
-          git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git
-          git fetch origin main
-
-      - name: Auto-commit canonical artifacts
+      - name: Validate canonical artifact boundary
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: |
          set -euo pipefail
@@ -291,17 +464,53 @@ jobs:
            exit 1
          fi

-          git commit -m "chore: sync repo state [ci skip]"
-          git pull origin main --rebase
-          git push origin HEAD
+      - name: Reject stale canonical-sync publication
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git fetch origin main
+          test "$GITHUB_SHA" = "$(git rev-parse origin/main)"
+
+      - name: Create or update canonical-sync PR
+        id: canonical_pr
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8
+        with:
+          token: ${{ github.token }}
+          branch: automation/canonical-repo-state
+          base: main
+          delete-branch: true
+          commit-message: "chore: synchronize canonical repository state"
+          title: "chore: synchronize canonical repository state"
+          body: |
+            Automated canonical artifacts regenerated from `main` by the trusted repository workflow.
+
+            <!-- canonical-sync-bot -->
+
+            ## Quality Bar Checklist
+
+            - [x] Contains only files declared by the generated-files contract.
+            - [x] Reproducibility is verified byte-for-byte by required CI.
+            - [x] No source or workflow changes are included.
+
+      - name: Merge canonical-sync PR after exact required checks
+        if: steps.canonical_pr.outputs.pull-request-number != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ steps.canonical_pr.outputs.pull-request-number }}
+          PR_HEAD: ${{ steps.canonical_pr.outputs.pull-request-head-sha }}
+        run: |
+          node tools/scripts/merge_canonical_sync_pr.cjs \
+            --repo "$GITHUB_REPOSITORY" \
+            --pr "$PR_NUMBER" \
+            --head "$PR_HEAD"

      - name: Check for uncommitted drift
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: |
          if ! git diff --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then
-            echo "❌ Detected leftover drift after the canonical bot sync."
+            echo "❌ Detected leftover drift after preparing the canonical-sync PR."
            echo
-            echo "The bot may only commit managed canonical files and must leave a clean tree."
+            echo "The bot may only publish managed canonical files and must leave a clean tree."
            echo "To fix locally, run the canonical maintainer flow:"
            echo "  npm run release:preflight"
            echo "  npm run sync:repo-state"
@@ -1,12 +1,10 @@
-# Build and deploy the web app to GitHub Pages.
+# Build and deploy the web app to GitHub Pages only after an explicit release dispatch.
 # Enable in repo: Settings → Pages → Source: GitHub Actions.
 # Site URL: https://<owner>.github.io/<repo>/

 name: Deploy Web App to GitHub Pages

 on:
-  push:
-    branches: ["main", "master"]
  workflow_dispatch:

 permissions:
@@ -94,10 +92,10 @@ jobs:
          test -f 404.html

      - name: Configure GitHub Pages
-        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

      - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: apps/web-app/dist

@@ -6,20 +6,22 @@ on:
    - cron: "0 7 * * 1"

 permissions:
+  actions: write
  contents: write
+  pull-requests: write

 jobs:
  sync-repo-state:
+    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    concurrency:
      group: canonical-main-sync
      cancel-in-progress: false
-    env:
-      GH_TOKEN: ${{ github.token }}
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          fetch-depth: 0
+          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
@@ -42,9 +44,11 @@ jobs:
        run: npm audit --audit-level=high

      - name: Run repo-state sync
+        env:
+          GH_TOKEN: ${{ github.token }}
        run: npm run sync:repo-state

-      - name: Commit and push if changed
+      - name: Validate canonical artifact boundary
        run: |
          set -euo pipefail

@@ -59,9 +63,6 @@ jobs:
            exit 0
          fi

-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git fetch origin main
          git add -- "${managed_files[@]}" || true

          if git diff --cached --quiet; then
@@ -76,6 +77,40 @@ jobs:
            exit 1
          fi

-          git commit -m "chore: scheduled repo hygiene sync [ci skip]"
-          git pull origin main --rebase
-          git push origin HEAD
+      - name: Reject stale canonical-sync publication
+        run: |
+          git fetch origin main
+          test "$GITHUB_SHA" = "$(git rev-parse origin/main)"
+
+      - name: Create or update canonical-sync PR
+        id: canonical_pr
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8
+        with:
+          token: ${{ github.token }}
+          branch: automation/canonical-repo-state
+          base: main
+          delete-branch: true
+          commit-message: "chore: synchronize canonical repository state"
+          title: "chore: synchronize canonical repository state"
+          body: |
+            Automated canonical artifacts regenerated from `main` by the trusted repository workflow.
+
+            <!-- canonical-sync-bot -->
+
+            ## Quality Bar Checklist
+
+            - [x] Contains only files declared by the generated-files contract.
+            - [x] Reproducibility is verified byte-for-byte by required CI.
+            - [x] No source or workflow changes are included.
+
+      - name: Merge canonical-sync PR after exact required checks
+        if: steps.canonical_pr.outputs.pull-request-number != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ steps.canonical_pr.outputs.pull-request-number }}
+          PR_HEAD: ${{ steps.canonical_pr.outputs.pull-request-head-sha }}
+        run: |
+          node tools/scripts/merge_canonical_sync_pr.cjs \
+            --repo "$GITHUB_REPOSITORY" \
+            --pr "$PR_NUMBER" \
+            --head "$PR_HEAD"
@@ -3,46 +3,168 @@ on:
  pull_request:
    paths: ['**/SKILL.md']

+permissions:
+  contents: read
+
 jobs:
-  review:
+  review-state:
    runs-on: ubuntu-latest
+    outputs:
+      configured: ${{ steps.state.outputs.configured }}
+    env:
+      TESSL_TOKEN_CONFIGURED: ${{ (secrets.TESSL_TOKEN != '' || secrets.TESSL_API_TOKEN != '') && 'true' || 'false' }}
+    steps:
+      - name: Resolve semantic review availability
+        id: state
+        run: echo "configured=${TESSL_TOKEN_CONFIGURED}" >> "$GITHUB_OUTPUT"
+
+  review-attempt:
+    needs: review-state
+    if: ${{ needs.review-state.outputs.configured == 'true' }}
+    runs-on: ubuntu-latest
+    outputs:
+      outcome: ${{ steps.outcome.outputs.outcome }}
    env:
      TESSL_REVIEW_THRESHOLD: '80'
-      TESSL_TOKEN_CONFIGURED: ${{ (secrets.TESSL_TOKEN != '' || secrets.TESSL_API_TOKEN != '') && 'true' || 'false' }}
-      TESSL_WORKSPACE: agentic-awesome-skills
+      TESSL_REVIEW_CACHE_VERSION: '1'
+      # Tessl workspaces are account-scoped; keep the repository variable as
+      # an override so a future workspace migration does not require code changes.
+      TESSL_WORKSPACE: ${{ vars.TESSL_WORKSPACE || 'antigravity-awesome-skills' }}
    permissions:
      contents: read
    steps:
-      - name: Require Tessl token for repository branches
-        if: ${{ env.TESSL_TOKEN_CONFIGURED != 'true' && github.event.pull_request.head.repo.full_name == github.repository }}
-        run: |
-          echo "::error title=Missing Tessl token::Configure TESSL_TOKEN, or keep the legacy TESSL_API_TOKEN secret until the migration is complete."
-          exit 1
-      - name: Skip Tessl Review for fork PRs without secrets
-        if: ${{ env.TESSL_TOKEN_CONFIGURED != 'true' && github.event.pull_request.head.repo.full_name != github.repository }}
-        run: |
-          echo "::warning title=Tessl Review skipped::GitHub does not expose repository secrets to this fork PR. Maintainers must review the changed SKILL.md files manually."
+      - name: Checkout pull request content
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
      - name: Checkout trusted base scripts
        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        if: ${{ env.TESSL_TOKEN_CONFIGURED == 'true' }}
        with:
          fetch-depth: 0
          ref: ${{ github.event.pull_request.base.sha }}
          path: trusted-base
-      - name: Checkout pull request content
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        if: ${{ env.TESSL_TOKEN_CONFIGURED == 'true' }}
+          persist-credentials: false
+      - name: Fingerprint changed skill content
+        id: plan
+        run: node trusted-base/tools/scripts/review_changed_skills.cjs --plan
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      - name: Restore successful Tessl review
+        id: review-cache
+        if: ${{ steps.plan.outputs.has-skills == 'true' }}
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
-          fetch-depth: 0
-          ref: ${{ github.event.pull_request.head.sha }}
-      - uses: tesslio/setup-tessl@25ec223fc0da33b41b8044ff5ab2b85235f4f91e
-        if: ${{ env.TESSL_TOKEN_CONFIGURED == 'true' }}
+          path: .tmp/tessl-review-cache
+          key: tessl-review-v1-${{ steps.plan.outputs.fingerprint }}
+      - name: Set up Tessl
+        if: ${{ steps.plan.outputs.has-skills == 'true' && steps.review-cache.outputs.cache-hit != 'true' }}
+        uses: tesslio/setup-tessl@25ec223fc0da33b41b8044ff5ab2b85235f4f91e
        with:
          token: ${{ secrets.TESSL_TOKEN || secrets.TESSL_API_TOKEN }}
      - name: Review changed skills
-        if: ${{ env.TESSL_TOKEN_CONFIGURED == 'true' }}
-        run: node trusted-base/tools/scripts/review_changed_skills.cjs
+        id: tessl-review
+        if: ${{ steps.plan.outputs.has-skills == 'true' && steps.review-cache.outputs.cache-hit != 'true' }}
+        run: |
+          set +e
+          node trusted-base/tools/scripts/review_changed_skills.cjs
+          status=$?
+          set -e
+
+          if [ "$status" -eq 0 ]; then
+            echo "result=reviewed" >> "$GITHUB_OUTPUT"
+          elif [ "$status" -eq 75 ]; then
+            echo "result=quota" >> "$GITHUB_OUTPUT"
+            echo "::warning title=Tessl quota unavailable::A maintainer must review and attest to this exact head SHA before merge."
+          else
+            exit "$status"
+          fi
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
+      - name: Mark successful review for reuse
+        if: ${{ steps.tessl-review.outputs.result == 'reviewed' }}
+        run: |
+          mkdir -p .tmp/tessl-review-cache
+          echo "${{ steps.plan.outputs.fingerprint }}" > .tmp/tessl-review-cache/fingerprint
+      - name: Save successful Tessl review
+        if: ${{ steps.tessl-review.outputs.result == 'reviewed' }}
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: .tmp/tessl-review-cache
+          key: tessl-review-v1-${{ steps.plan.outputs.fingerprint }}
+      - name: Resolve review outcome
+        id: outcome
+        env:
+          CACHE_HIT: ${{ steps.review-cache.outputs.cache-hit }}
+          HAS_SKILLS: ${{ steps.plan.outputs.has-skills }}
+          TESSL_RESULT: ${{ steps.tessl-review.outputs.result }}
+        run: |
+          if [ "$HAS_SKILLS" != "true" ] || [ "$CACHE_HIT" = "true" ] || [ "$TESSL_RESULT" = "reviewed" ]; then
+            echo "outcome=reviewed" >> "$GITHUB_OUTPUT"
+          elif [ "$TESSL_RESULT" = "quota" ]; then
+            echo "outcome=quota" >> "$GITHUB_OUTPUT"
+          else
+            echo "::error title=Unresolved review state::The Tessl review did not produce a trustworthy outcome."
+            exit 1
+          fi
+
+  review:
+    needs: [review-state, review-attempt]
+    if: ${{ always() && needs.review-attempt.result == 'success' && needs.review-attempt.outputs.outcome == 'reviewed' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Confirm semantic review
+        env:
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          echo "Semantic review passed for changed skill content at ${HEAD_SHA}."
+          {
+            echo "## Skill review passed"
+            echo
+            echo "The changed skill content passed Tessl review or reused an identical previously successful review."
+            echo
+            echo "- Head SHA: \`${HEAD_SHA}\`"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  manual-review-required:
+    needs: [review-state, review-attempt]
+    if: ${{ always() && ((needs.review-state.outputs.configured != 'true' && github.event.pull_request.head.repo.full_name != github.repository) || needs.review-attempt.outputs.outcome == 'quota') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Record exact head requiring maintainer review
+        env:
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          REVIEW_OUTCOME: ${{ needs.review-attempt.outputs.outcome }}
+        run: |
+          if [ "$REVIEW_OUTCOME" = "quota" ]; then
+            reason="the Tessl credit quota is unavailable"
+          else
+            reason="repository secrets are unavailable to this fork pull request"
+          fi
+          echo "::warning title=Manual skill review required::Semantic review is unavailable because ${reason}. A maintainer must attest to the exact head SHA before merge: ${HEAD_SHA}."
+          {
+            echo "## Manual skill review required"
+            echo
+            echo "- Head SHA: \`${HEAD_SHA}\`"
+            echo "- Reason: ${reason}."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  missing-review-credentials:
+    needs: [review-state, review-attempt]
+    if: ${{ always() && needs.review-state.outputs.configured != 'true' && github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Require Tessl token for repository branches
+        run: |
+          echo "::error title=Missing Tessl token::Configure TESSL_TOKEN, or keep the legacy TESSL_API_TOKEN secret until the migration is complete."
+          exit 1