chore: engineering hygiene — version-sync, lint/type gate, reformat, supply-chain, OSS scaffolding (regenerated on current main)

.github/CODEOWNERS

@@ -0,0 +1,12 @@
+# Default owner for everything in the repo.
+* @abrichr
+
+# Safety-critical core: identity gate, resolution ladder, halt/postcondition
+# logic. Changes here warrant extra scrutiny (never-false-accept invariant).
+/openadapt_flow/runtime/identity.py   @abrichr
+/openadapt_flow/runtime/replayer.py   @abrichr
+/openadapt_flow/validation/           @abrichr
+
+# Release, CI, and supply-chain configuration.
+/.github/                             @abrichr
+/pyproject.toml                       @abrichr

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug report
+description: Report something that behaves incorrectly.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Please do **not** file security issues here —
+        see [SECURITY.md](https://github.com/OpenAdaptAI/openadapt-flow/blob/main/SECURITY.md).
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Ideally the exact `openadapt-flow` commands you ran.
+      placeholder: |
+        1. openadapt-flow demo-record --out rec
+        2. openadapt-flow compile rec --out bundle --name my-task
+        3. openadapt-flow replay bundle
+    validations:
+      required: true
+  - type: textarea
+    id: report
+    attributes:
+      label: Run report / logs
+      description: Attach the run's REPORT.md or report.json if you have one (scrub any PHI/PII first).
+  - type: input
+    id: version
+    attributes:
+      label: openadapt-flow version
+      description: "Output of: python -c \"import openadapt_flow; print(openadapt_flow.__version__)\""
+    validations:
+      required: true
+  - type: input
+    id: env
+    attributes:
+      label: OS + Python version
+      placeholder: "macOS 14 / Python 3.12"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/OpenAdaptAI/openadapt-flow/security/advisories/new
+    about: Please report security issues privately, not as public issues (see SECURITY.md).
+  - name: Question / discussion
+    url: https://github.com/OpenAdaptAI/openadapt-flow/discussions
+    about: Ask usage questions or discuss ideas here.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Suggest an improvement or new capability.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / use case
+      description: What are you trying to do, and what makes it hard today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to see? Alternatives you considered?
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Substrate (browser/desktop/RDP), scale, determinism/safety needs, etc.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## What & why
+
+<!-- What does this change and why? Link any issue: Closes #123 -->
+
+## Type of change
+
+<!-- Conventional Commit type; the PR title MUST match (feat:/fix:/docs:/…). -->
+
+- [ ] `fix:` bug fix
+- [ ] `feat:` new feature
+- [ ] `docs:` documentation only
+- [ ] `ci:` / `chore:` / `refactor:` / `test:` (no user-facing behavior change)
+
+## Checklist
+
+- [ ] PR title uses Conventional Commit format
+- [ ] `ruff check openadapt_flow` and `ruff format --check openadapt_flow` pass
+- [ ] `mypy` passes
+- [ ] `pytest -q` passes locally
+- [ ] Tests added/updated for behavior changes
+- [ ] Docs updated (README/DESIGN/docs) if behavior or contracts changed
+- [ ] If this touches the identity gate / resolution ladder / halt logic, I
+      explained why the never-false-accept invariant still holds
+
+## Notes for reviewers
+
+<!-- Anything that helps review: tradeoffs, follow-ups, out-of-scope items. -->

.github/dependabot.yml

@@ -0,0 +1,27 @@
+# Dependabot: keep the supply chain fresh. GitHub Actions are pinned by commit
+# SHA (see the workflows); Dependabot understands the trailing `# vX` comment
+# and proposes SHA bumps with the new version, so pinning does not freeze us on
+# stale, potentially-vulnerable action releases.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+    commit-message:
+      prefix: ci
+
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    # Group the minor/patch churn so we get one PR instead of a swarm; majors
+    # come as their own reviewable PRs.
+    groups:
+      python-minor:
+        update-types: ["minor", "patch"]
+    commit-message:
+      prefix: build

.github/workflows/ci.yml

@@ -27,6 +27,35 @@ concurrency:
 # version. Dependabot (.github/dependabot.yml) proposes SHA bumps.
 
 jobs:
+  # --- Lint + type check (ruff + mypy) -------------------------------------
+  # Runs on PRs (and post-merge/nightly). Deliberately a SEPARATE job from the
+  # required `test` gate: it must NOT be wired as a dependency of `test` (that
+  # would leave `test` reporting a compound context and break branch
+  # protection, whose required context is exactly `test`). Add `lint` as its
+  # own required context in branch protection if you want it to block merges.
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: pip install -e .[dev]
+
+      - name: Ruff lint
+        run: ruff check openadapt_flow
+
+      - name: Ruff format check
+        run: ruff format --check openadapt_flow tests
+
+      - name: Mypy
+        run: mypy
+
   # --- Required merge gate: FAST unit suite (ubuntu, single Python) ---------
   # This is the ONE required status check (branch protection context: "test").
   # It MUST stay a single, non-matrix job named exactly `test` so its reported

.github/workflows/release.yml

@@ -11,6 +11,12 @@ name: Release and PyPI Publish
 # Prerequisites (repo/org settings): secrets.ADMIN_TOKEN (org-level, visibility
 # "all") to push the release commit/tag past branch protection; PyPI Trusted
 # Publishing for openadapt-flow with environment "pypi".
+#
+# Supply chain: GitHub Actions below are pinned to full commit SHAs (not mutable
+# tags) with the human-readable version in a trailing comment; Dependabot
+# (.github/dependabot.yml) proposes SHA bumps. Follow-up (settings change, not
+# code): the org-wide ADMIN_TOKEN (visibility "all") should become a
+# repo-scoped fine-grained token or GitHub App to narrow its blast radius.
 
 on:
   push:
@@ -35,7 +41,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           fetch-depth: 0
           token: ${{ secrets.ADMIN_TOKEN }}
@@ -51,31 +57,31 @@ jobs:
 
       - name: Set up Python
         if: steps.check_skip.outputs.skip != 'true'
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.12"
 
       - name: Install uv
         if: steps.check_skip.outputs.skip != 'true'
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
 
       # Semantic Release computes the version, bumps pyproject, tags, AND runs
       # `build_command` (uv build) to populate dist/. There is deliberately no
       # separate build step — a second `uv build` would collide on dist/*.tar.gz.
       - name: Python Semantic Release
         if: steps.check_skip.outputs.skip != 'true'
         id: release
-        uses: python-semantic-release/python-semantic-release@v9.15.2
+        uses: python-semantic-release/python-semantic-release@7b3f71697ccfbaef884e1e754b6364e974b134cf # v9.15.2
         with:
           github_token: ${{ secrets.ADMIN_TOKEN }}
 
       - name: Publish to PyPI
         if: steps.check_skip.outputs.skip != 'true' && steps.release.outputs.released == 'true'
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
 
       - name: Publish GitHub Release
         if: steps.check_skip.outputs.skip != 'true' && steps.release.outputs.released == 'true'
-        uses: python-semantic-release/publish-action@v9.15.2
+        uses: python-semantic-release/publish-action@b9c41d4b0754dee5a6c7188d42b33f66e3a8aafd # v9.15.2
         with:
           github_token: ${{ secrets.ADMIN_TOKEN }}
 
@@ -89,20 +95,20 @@ jobs:
 
     steps:
       - name: Checkout the requested ref
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           ref: ${{ inputs.ref }}
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.12"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
 
       - name: Build package
         run: uv build
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

CODE_OF_CONDUCT.md

@@ -0,0 +1,67 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement privately through
+a [GitHub Security Advisory](https://github.com/OpenAdaptAI/openadapt-flow/security/advisories/new)
+or by contacting the maintainer [@abrichr](https://github.com/abrichr).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to openadapt-flow
+
+Thanks for your interest in improving openadapt-flow. This project compiles a
+recorded GUI demonstration into a deterministic, self-healing, locally-run
+script — so correctness, determinism, and honest measurement matter more here
+than raw feature count.
+
+## Development setup
+
+```bash
+git clone https://github.com/OpenAdaptAI/openadapt-flow && cd openadapt-flow
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+playwright install chromium
+pytest -q
+```
+
+Python 3.10–3.13 are supported and exercised in CI.
+
+## The checks CI runs (run them locally first)
+
+```bash
+ruff check openadapt_flow          # lint
+ruff format --check openadapt_flow # format (drop --check to auto-apply)
+mypy                               # type-check (config in pyproject.toml)
+pytest -q                          # tests
+```
+
+- **Lint/format:** `ruff`. Config lives in `[tool.ruff]` in `pyproject.toml`.
+- **Types:** `mypy` runs on the core package (not tests). It is deliberately
+  lenient today; a set of modules with known type debt is listed under
+  `[[tool.mypy.overrides]]`. Improving a module's annotations and removing it
+  from that list is a very welcome PR.
+- **Coverage:** CI reports coverage for visibility. There is no hard floor yet,
+  but new code should come with tests.
+
+## Pull request guidelines
+
+- **Conventional Commits** for titles and commits: `feat:`, `fix:`, `perf:`,
+  `docs:`, `ci:`, `chore:`, `refactor:`, `test:`. Releases are automated from
+  these — `feat:` → minor, `fix:`/`perf:` → patch, `BREAKING CHANGE` → major.
+- Keep PRs focused. Separate mechanical changes (formatting, renames) from
+  behavior changes so review stays legible.
+- Add or update tests for any behavior change. The suite mocks browsers/servers
+  where it can, so most of it runs with no live VM.
+- Update docs (`README.md`, `DESIGN.md`, `docs/`) when behavior or contracts
+  change. We prefer honest, measured claims — if something is experimental, say
+  so.
+
+## Safety-sensitive areas
+
+The identity gate, the resolution ladder, and the postcondition/halt logic are
+the safety core: the whole value proposition is that the tool halts instead of
+acting on the wrong target. Changes there deserve extra tests (see the
+`test_identity_*`, `test_resolver*`, and `*_fuzz` suites) and a clear
+explanation of why the never-false-accept invariant still holds.
+
+## Reporting security issues
+
+See [SECURITY.md](SECURITY.md) — do not file security problems as public issues.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).