feat: publish a small qualified workflow library with THEBEST review signatures

Signed-off-by: HiTecHelpLLC <167040707+HiTecHelpLLC@users.noreply.github.com>

Author: HiTecHelpLLC

.gitattributes

@@ -0,0 +1,2 @@
+* text eol=lf
+workflows/*.json -text

.github/workflows/quality.yml

@@ -0,0 +1,53 @@
+name: Curated workflow qualification
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  qualify:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    env:
+      PYTHONUTF8: '1'
+      OPENADAPT_FLOW_NO_AUTO_INSTALL: '1'
+      GIT_CONFIG_COUNT: '1'
+      GIT_CONFIG_KEY_0: core.longpaths
+      GIT_CONFIG_VALUE_0: 'true'
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: '3.12'
+      - name: Validate reviewed content and rejection tests
+        shell: bash
+        run: |
+          python -m pip install -r requirements-verify.txt
+          python scripts/validate.py
+          python -m unittest discover -s tests -v
+      - name: Check helper code style
+        shell: bash
+        run: |
+          python -m pip install ruff==0.16.5
+          python -m ruff check scripts tests
+          python -m ruff format --check scripts tests
+      - name: Verify the pinned THEBEST curator attestation
+        shell: pwsh
+        run: |
+          $publicKey = Join-Path $env:RUNNER_TEMP 'thebest-review.pub'
+          [System.IO.File]::WriteAllText($publicKey, "800696f2b323bc64efc1a44c1220f64cf420aef73e1fe1631a720c7e75831a93`n", [System.Text.Encoding]::ASCII)
+          python scripts/attest.py verify --root . --attestation attestations/browser-poster-0.1.0.json --trusted-key $publicKey --expected-role curator --expected-identity thebest
+          exit $LASTEXITCODE
+      - name: Install pinned parent runtime for qualification
+        shell: bash
+        run: |
+          python -m pip install "git+https://github.com/HiTecHelpLLC/l1ght5p33d.git@e51098ffa1e7ca42b96d6372578876d1c32e632b#subdirectory=packages/l1ght5p33d"
+          python -m playwright install --with-deps chromium
+      - name: Execute exact workflow against the synthetic browser fixture
+        run: python scripts/qualify_browser.py --synthetic-fixture-only

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+*.pyc
+*.key
+*.pem
+*.png
+*.jpg
+*.wav
+*.mid
+profiles/
+receipts/

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing reviewed workflows
+
+Open an issue describing a useful, bounded task before adding a workflow. A small
+library with trustworthy behavior is the goal. Do not import bulk collections.
+
+Admission requires:
+
+1. Clear source provenance and an explicit compatible license. Public availability
+   alone does not grant redistribution permission. Retain authors' notices.
+2. ASCII JSON under 64 KiB; no credentials, browser profiles, screenshots, binaries,
+   personal content, arbitrary code, shell commands or hidden network activity.
+3. Named steps, semantic selectors first, explicit effects for every action,
+   bounded waits and failure behavior. Declare application/version assumptions.
+4. Closed metadata with version, exact SHA-256, source, runtime, defaults, test
+   scope, status, and a complete checklist of actions, arguments and effects.
+5. A reproducible local fixture qualification. Run the actual admitted workflow
+   and verify an independent outcome. Do not substitute a canned demo that skips
+   the submitted file. Document every environment substitution.
+6. Tests proving tampered content, unexpected actions, missing verification and
+   scope expansion are rejected. Passing tests do not replace curator review.
+7. A plain-language description of inputs, effects, filesystem/network scope,
+   cleanup, remaining limitations and required user approval.
+8. All checks passing on the declared platforms, followed by maintainer approval.
+
+Update the exact source allowlist when intentionally adding a file. Total source
+must remain under 1 MB. Update the schema and validator deliberately when adding
+a new application or graph construct; unsupported constructs fail closed.
+
+Only `fixture-qualified` is currently an admitted status. Do not claim live
+application verification from a mock fixture. BandLab and Windows workflows are
+pending separate qualification and must not be added as placeholder entries.
+
+No change to this repository may automatically grant a user execution permission.
+Signing, catalog publication, registry deployment and P2P seeding are separate
+operator actions and are not performed by the validator or qualification script.

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 OpenAdapt.AI (MLDSAI Inc.)
+Copyright (c) 2026 L1ght5p33d contributors (downstream additions)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,104 @@
+# L1ght5p33d Workflows
+
+A deliberately small, reviewed collection of local creation workflows. Quality
+and clear scope matter more than the number of entries. This initial library
+contains **one MIT-licensed workflow**, qualified against our own browser fixture.
+It does not contain a scraped collection of third-party scripts.
+
+The engine lives in [L1ght5p33d](https://github.com/HiTecHelpLLC/l1ght5p33d).
+This repository is an independent content library. `index.json` is a curator's
+index, **not a signed L1ght5p33d registry catalog**. Each admitted version has a
+separate [THEBEST review attestation](SIGNING.md) binding exact workflow, review
+metadata and test evidence. No public pinning service, automatic updater or
+execution permission is configured.
+
+## Admitted workflow: browser poster, version 0.1.0
+
+File: [`workflows/browser-poster.json`](workflows/browser-poster.json).
+Review: [`entries/browser-poster.json`](entries/browser-poster.json).
+Proof: [THEBEST attestation](attestations/browser-poster-0.1.0.json) and
+[Windows fixture evidence](evidence/browser-poster-windows-2026-09-03.json).
+
+This is the exact example copied from the parent project's pinned MIT source at
+commit `e51098ffa1e7ca42b96d6372578876d1c32e632b`. The original notices are retained
+in [LICENSE](LICENSE), and the source path and exact SHA-256 are in its metadata.
+
+The provider is `browser`. It opens an isolated headless Chromium context at
+`http://127.0.0.1:7332`, checks the title `L1ght5p33d Poster Studio`, and performs:
+
+| Step | Input and selector | Expected effect |
+| --- | --- | --- |
+| `name_poster` | Fill the field labelled `Poster title` using the `title` parameter | Read back `poster_title` equal to that parameter |
+| `choose_palette` | Select `Sunset` in the field labelled `Palette` | Read back `palette` equal to `Sunset` |
+| `save_poster` | Try button `Old save label`, then declared fallback `Save poster` | Read back `saved` equal to `Saved` |
+
+Default `title`: `Make something wonderful`. Every expected effect has a
+three-second verification timeout. A failed or ambiguous selector stops; this
+workflow makes no claim to repair itself. Qualification additionally reads the
+fixture server's `/state` endpoint and verifies the saved title and palette.
+
+Scope: synthetic fixture data, a temporary browser context, and local execution
+receipts. The fixture stores its saved state in memory until it shuts down. No
+personal files, accounts, login state, screenshots, publishing, music, purchases,
+deletion, or external service are part of this workflow. It does not create an
+exported poster image. The generic browser fixture is not a commercial design app.
+
+**A download or successful fixture test is not permission to run a user workflow.**
+Inspect the complete plan and grant explicit local approval before execution in
+your own environment. Changing selectors, URL, variables, application, or steps
+changes what must be reviewed. Never ask an AI to approve on your behalf.
+
+## Check the library without installing an automation runtime
+
+With Python 3.12, from this repository:
+
+```powershell
+python -m pip install -r requirements-verify.txt
+python scripts/validate.py
+python -m unittest discover -s tests -v
+```
+
+Checks enforce an explicit source-file allowlist, less than 1 MB of ASCII source,
+at most 64 KiB per workflow, hashes, paths, closed metadata, version/status,
+defaults, and agreement between actual steps/providers/selectors/effects and the
+review checklist. These checks detect drift; a reviewer must still assess intent.
+Signature verification additionally requires your separately pinned THEBEST public
+key; see [SIGNING.md](SIGNING.md). The tests include signature and tamper rejection.
+
+## Reproduce the synthetic browser qualification
+
+Use a dedicated Python 3.12 environment with the parent runtime from the exact
+commit recorded in the metadata. CI installs that revision as follows:
+
+```powershell
+python -m venv "$env:TEMP\l1ght5p33d-library-check"
+$env:GIT_CONFIG_COUNT = '1'
+$env:GIT_CONFIG_KEY_0 = 'core.longpaths'
+$env:GIT_CONFIG_VALUE_0 = 'true'
+& "$env:TEMP\l1ght5p33d-library-check\Scripts\python.exe" -m pip install "git+https://github.com/HiTecHelpLLC/l1ght5p33d.git@e51098ffa1e7ca42b96d6372578876d1c32e632b#subdirectory=packages/l1ght5p33d"
+& "$env:TEMP\l1ght5p33d-library-check\Scripts\python.exe" -m playwright install chromium
+& "$env:TEMP\l1ght5p33d-library-check\Scripts\python.exe" scripts/qualify_browser.py --synthetic-fixture-only
+```
+
+That explicit command authorizes only this fixed synthetic test. It validates the
+admitted bytes, starts the bundled fixture on a free loopback port, changes only
+the fixture URL in a temporary in-memory copy, and executes all original steps
+and defaults. It verifies three effects, the declared fallback, server state and
+zero model calls. Temporary run data are removed; no user policy is changed.
+The script accepts no arbitrary workflow, external URL or destination argument.
+
+## Admission and limitations
+
+Windows desktop and BandLab are **not admitted entries** in this initial library.
+Each needs its own reviewed metadata, fixtures and reproducible qualification.
+Live application claims additionally require evidence from the specified app and
+version. Existing examples in the engine repository are candidates, not implicit
+members of this curated collection.
+
+The initial CI targets Windows and Ubuntu with Python 3.12. Browser installation
+and CI dependency installation require network access; routine workflow execution
+does not require an AI connection. Metadata describe the test scope, not universal
+compatibility. There is no public workflow registry deployment in this repository.
+
+Unofficial and unaffiliated with BandLab, Suno, browser vendors, and other
+applications. Product names identify potential integrations only.

SECURITY.md

@@ -0,0 +1,21 @@
+# Security
+
+Treat workflow files, descriptions, effects and claimed verification as untrusted
+until reviewed. A hash detects content drift; it does not prove author identity,
+safe intent or that a workflow is suitable for your machine.
+
+The curator index is not signed and is not directly installable as a signed
+runtime catalog. Detached THEBEST review attestations bind exact versioned files
+and test evidence; verify them against a separately trusted public key as described
+in SIGNING.md. This repository contains no private signing key or persistent network
+service. Downloads and signatures do not grant permission or execute workflows.
+
+Do not submit secrets, cookies, profiles, private screenshots or personal media.
+Report vulnerabilities privately through the repository owner's GitHub security
+reporting channel when enabled. If unavailable, ask the maintainer for a private
+channel without posting exploit details or sensitive data publicly.
+
+The synthetic qualification script is opt-in developer tooling. It launches only
+the fixed local fixture and a temporary browser context. Do not modify it to run
+untrusted downloads. Runtime installations should use the recorded upstream commit
+and undergo the dependency checks of the parent project.

SIGNING.md

@@ -0,0 +1,73 @@
+# Author identity, curator review and execution approval
+
+These are three separate claims:
+
+1. An **author signature** identifies the key that published exact workflow bytes.
+   It is not a THEBEST test endorsement. Authors keep their own keys.
+2. A **THEBEST curator signature** binds a workflow version, its complete review
+   metadata, test evidence, source runtime commit, environment and qualified scope.
+   This library's initial attestation covers only our synthetic browser fixture.
+3. **Your run approval** confirms the complete proposed actions, effective inputs,
+   application and permissions on your machine. Neither kind of signature grants it.
+
+The initial entry has a THEBEST curator attestation. No separate upstream author
+signature is claimed. Test claims are evidence signed by the curator, not a
+cryptographic proof that a test was run or a promise that every environment is safe.
+
+## Verify an exact version
+
+Install `requirements-verify.txt`. Obtain THEBEST's public key through a channel
+you trust and pin a copy **outside this checkout**. The published key file is
+`trust/thebest-review-2026-09.pub`; this initial GitHub repository is the bootstrap
+publication channel. Verify its fingerprint before trusting it:
+
+```text
+SHA-256 of raw Ed25519 public key bytes:
+14c70511c35c423f046e79c1944cdc9ca8d06442202c516a18f67d6932895c84
+```
+
+Example after you have pinned the key at `C:\WorkflowTrust\thebest.pub`:
+
+```powershell
+python scripts/attest.py verify --root . --attestation attestations/browser-poster-0.1.0.json --trusted-key C:\WorkflowTrust\thebest.pub --expected-role curator --expected-identity thebest
+```
+
+The verifier checks the signature against that external trust anchor and hashes
+the exact workflow, metadata and evidence files. It rejects tampering, unknown
+fields, wrong keys/roles/identities, invalid dates, expiry and escaping paths.
+It does not run a workflow. Never accept a replacement key merely because it came
+with the same downloaded archive: an attacker could replace both.
+Use a reviewed verifier from a trusted, pinned checkout. Untrusted verification
+code from an arbitrary archive could simply lie about the result.
+
+The envelope uses Ed25519 through the maintained `cryptography` library, with a
+versioned, canonical ASCII JSON payload. Payload files are SHA-256 addressed.
+The human-readable entry contains descriptions, actual actions, selectors,
+defaults, verification, runtime, source and limitations. Changing any of those
+bytes invalidates this version's review attestation.
+
+## Publishing and key custody
+
+The private curator key is stored outside Git on the operator's computer, with
+Windows access restricted to that OS account. It is not uploaded to GitHub,
+placed in CI, served by THEBEST or distributed with workflows. CI verifies public
+proofs and reruns the fixture; it cannot sign new reviews.
+
+Maintainers review the exact files, run the qualification, preserve its sanitized
+report under `evidence/`, then use the local `sign` command. Signing requires the
+explicit identity, role, scope, environment, source commit and validity interval.
+The first curator review expires after 90 days; a fresh review and test run are
+needed to issue a new current attestation. Changes require another review and
+signature. Retain historical evidence rather than silently replacing its claims.
+
+For a suspected compromised key, stop trusting it locally and stop admitting new
+downloads signed by it. Announce a replacement through a separately trusted
+channel. Automatic key rotation, online revocation distribution and author key
+enrollment are future registry work. Offline verification cannot discover a new
+revocation by itself. This preview does not provide a transparency log or
+independent audit authority.
+
+The L1ght5p33d runtime already verifies native signed registry catalogs. These
+detached review attestations are an additional explicit verification tool; this
+repository's curator index is not yet wired into runtime discovery or THEBEST's
+P2P registry. No public P2P availability or automatic approval is implied.

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+The admitted workflow retains its original MIT copyright and license in LICENSE
+and records its exact upstream source in entries/browser-poster.json.
+
+The detached signature helper composes these installed dependencies; no library
+source is copied here:
+
+| Project | Version | License | Source |
+| --- | --- | --- | --- |
+| cryptography | 50.0.1 | Apache-2.0 OR BSD-3-Clause | https://github.com/pyca/cryptography |
+| cffi | 2.1.1 | MIT-0 | https://github.com/python-cffi/cffi |
+| pycparser | 3.0 | BSD-3-Clause | https://github.com/eliben/pycparser |
+
+The optional browser qualification installs the exact L1ght5p33d commit named
+in entry metadata. Its dependency and license notices are maintained at
+https://github.com/HiTecHelpLLC/l1ght5p33d/blob/e51098ffa1e7ca42b96d6372578876d1c32e632b/THIRD_PARTY_NOTICES.md .
+Browser binaries, Python, private keys, user recordings and third-party music are
+not included in this repository.

attestations/browser-poster-0.1.0.json

@@ -0,0 +1 @@
+{"algorithm":"Ed25519","payload_b64":"eyJldmlkZW5jZSI6eyJwYXRoIjoiZXZpZGVuY2UvYnJvd3Nlci1wb3N0ZXItd2luZG93cy0yMDI2LTA5LTAzLmpzb24iLCJzaGEyNTYiOiJmOGEzNTUxYzUyMTZiYzU0NDFhMGMzMzVmNzQ4NGJmZGMyMzNlMjRlMDhmOWU2MWE4NzE4ZjhlM2YxODU2ZTMxIn0sImV4cGlyZXNfYXQiOiIyMDI2LTEyLTAyVDIyOjA4OjM4WiIsImlkZW50aXR5IjoidGhlYmVzdCIsImlzc3VlZF9hdCI6IjIwMjYtMDktMDNUMjI6MDg6MzhaIiwibWV0YWRhdGEiOnsicGF0aCI6ImVudHJpZXMvYnJvd3Nlci1wb3N0ZXIuanNvbiIsInNoYTI1NiI6ImExMzhhM2VhMTBiNTJlYzRmMjg3NDUxYmEyNTQyMmViZWZmN2QwNmExNTUzYjVhNWY2M2UwNTBiYzhjZDU0MDEifSwicXVhbGlmaWNhdGlvbiI6eyJlbnZpcm9ubWVudCI6eyJjaHJvbWl1bSI6IjE1MS4wLjc5MjIuMzQiLCJwbGF0Zm9ybSI6IldpbmRvd3MtMTEtMTAuMC4yNjIwMC1TUDAiLCJwbGF5d3JpZ2h0IjoiMS42Mi4wIiwicHl0aG9uIjoiMy4xMi42In0sInNjb3BlIjoiU3ludGhldGljIGxvY2FsIGJyb3dzZXIgcG9zdGVyIGZpeHR1cmUgb25seTogdGhyZWUgZWZmZWN0cywgZGVjbGFyZWQgc2VsZWN0b3IgZmFsbGJhY2ssIGluZGVwZW5kZW50IHNhdmVkLXN0YXRlIHJlYWRiYWNrIGFuZCB6ZXJvIG1vZGVsIGNhbGxzOyBubyBsaXZlIGFwcGxpY2F0aW9uIHF1YWxpZmljYXRpb24uIiwic291cmNlX2NvbW1pdCI6ImU1MTA5OGZmYTFlN2NhNDJiOTZkNjM3MjU3ODg3NmQxYzMyZTYzMmIifSwicm9sZSI6ImN1cmF0b3IiLCJzY2hlbWFfdmVyc2lvbiI6ImwxZ2h0NXAzM2QtYXR0ZXN0YXRpb24tY2xhaW1zL3YxIiwid29ya2Zsb3ciOnsicGF0aCI6IndvcmtmbG93cy9icm93c2VyLXBvc3Rlci5qc29uIiwic2hhMjU2IjoiYTk4MjM4NzRmZjY0ODNiNWQzODA0ZGVmMTJjZmQzY2ExZGUyZmIzMmY3YWQxYjI5N2Q5NDNlN2I5NWRiNWQ3NyJ9fQ==","schema_version":"l1ght5p33d-attestation/v1","signature_b64":"iBYo3OX/U7MFgf2StYjHuf2VS2JhWJMY1AZ2Ta3t8/UI23KMGUN0sRpNuzRU71uLOtU0ceV3AGXV4G2zmvhwBQ=="}