jobwright 0.0.1__tar.gz

jobwright-0.0.1/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "jobwright",
+  "owner": { "name": "Kyle Chalmers" },
+  "description": "jobwright — govern, validate, and safely ship data-orchestration jobs with Claude Code.",
+  "plugins": [
+    {
+      "name": "jobwright",
+      "source": "./",
+      "description": "A jobs index, architecture-compliance scanning, a live-vs-repo deploy-safety guard, and per-job validation for Databricks / Airflow / dbt / Snowflake Tasks job repos."
+    }
+  ]
+}

jobwright-0.0.1/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "jobwright",
+  "displayName": "jobwright",
+  "version": "0.0.1",
+  "description": "Govern, validate, and safely ship data-orchestration jobs (Databricks, Airflow, dbt, Snowflake Tasks) with Claude Code: a jobs index, architecture-compliance scanning, a live-vs-repo deploy-safety guard, and per-job validation.",
+  "author": { "name": "Kyle Chalmers" },
+  "homepage": "https://github.com/kyle-chalmers/jobwright",
+  "repository": "https://github.com/kyle-chalmers/jobwright",
+  "license": "MIT",
+  "keywords": ["databricks", "airflow", "dbt", "snowflake", "orchestration", "governance", "data-engineering"],
+  "hooks": "./hooks/hooks.json"
+}

jobwright-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (editable, with dev extras)
+        run: pip install -e ".[dev]"
+
+      # bin/selftest.sh runs ruff + pytest + the adapter-contract + skill-leak checks.
+      - name: Selftest
+        run: bash bin/selftest.sh

jobwright-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+# Manual trigger so cutting a GitHub release never auto-fails before PyPI is configured.
+# After registering the PyPI Trusted Publisher (see docs/PUBLISHING.md), run this workflow
+# from the Actions tab (or switch the trigger to `release: [published]`).
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for PyPI Trusted Publishing — no API token stored
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist + wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

jobwright-0.0.1/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+
+# Never commit a real, org-specific config at the repo root.
+# Root-anchored so the example fixtures under examples/ ARE tracked.
+# The documented template lives at jobwright.config.example.yaml.
+/jobwright.config.yaml

jobwright-0.0.1/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to jobwright are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow semver.
+
+## [0.0.1] — 2026-06-27
+
+First public alpha. Generalized from a production Databricks data-jobs repo and
+stripped of all org-specific values.
+
+### Added
+
+- **Two-seam architecture** — a `platform` seam (orchestrator lifecycle) and a
+  `warehouse`/`architecture` seam (static schema policy), expressed in a typed,
+  validated `jobwright.config.yaml`.
+- **Platform adapters** across all three deploy models via a `JobPlatformAdapter`
+  contract: Databricks Jobs (`api-reset`), Snowflake Tasks (`sql-ddl`), Apache
+  Airflow (`git-sync`), and dbt (`git-sync`). Each ships a markdown playbook.
+- **Deploy-safety guard** (`PreToolUse` hook) — asks before destructive job/SQL
+  commands (e.g. `databricks jobs reset/update/delete`, `DROP TASK`, `dbt … --target
+  prod`, destructive warehouse SQL incl. SQL in `-f` files). Stdlib-only, fail-open,
+  zero-cost outside a jobwright repo; defends against shell-quote and full-path evasion.
+- **Generic checks** (`check syntax | job-defs | deps | architecture | docs`) plus a
+  composite `validate-job` PASS/FAIL gate scoped to one job.
+- **Deterministic jobs index** — `jobs-index` renders `JOBS.md` + `OBJECTS.md`
+  (recall-before-rebuild; surfaces deprecated-schema migration debt), with a `--check`
+  CI gate.
+- **Scaffolder** — `new-job` creates a governed job folder (claude.md + notebook
+  header + a deploy-model-appropriate definition stub); `gen-agents` renders an
+  `AGENTS.md` rulebook from config.
+- **Hooks** — SessionStart skill/catalog pointer + PostToolUse jobs-index regen.
+- **10 tool-agnostic skills** (onboard, start-job, scaffold-job, document-job,
+  validate-job, architecture-audit, build-jobs-index, safe-deploy, triage-failure,
+  configure-workspace).
+- **Claude Code plugin** manifests (`.claude-plugin/`), `bin/selftest.sh` (lint +
+  tests + adapter-contract + skill-leak checks), and a CI workflow.
+
+[0.0.1]: https://github.com/kyle-chalmers/jobwright/releases/tag/v0.0.1

jobwright-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to jobwright
+
+## Ground rules
+
+1. **One implementation, many consumers.** Logic lives in the `jobwright` package. The CLI, the Claude Code skills, the hooks, and CI all call it — they never re-implement a check. A skill is a thin playbook that shells out to `jobwright ...`; it never embeds the check logic in prose.
+2. **Skills call verbs, never tools.** Skills and commands use the abstract platform verbs (`diff_live_vs_repo`, `list_active_runs`, …) and the generic checks. They must not hardcode `databricks` / `airflow` / `dbt` by name — that belongs in an adapter. `bin/selftest.sh` greps for platform-name leaks.
+3. **No org-specific values in code.** Schema names, profiles, account locators, channels — everything that varies by repo — goes in `jobwright.config.yaml`. The package ships only the *schema* and generic rules.
+4. **Secrets never in the repo.** Not in config, not in tests, not in docs. Config holds names/profiles only.
+
+## Adding a platform adapter
+
+A platform adapter is two files:
+
+- `jobwright/platforms/<kind>.py` — a `JobPlatformAdapter` subclass implementing the mandatory verbs (see `jobwright/platforms/base.py`, `MANDATORY_VERBS`). Set `kind`, `deploy_model`, and `destructive_patterns`. Register it in `jobwright/platforms/__init__.py`. **This is the single source of truth for `destructive_patterns`.**
+- `adapters/platform/<kind>.md` — a markdown playbook: frontmatter (`seam`, `kind`, `transport`, `deploy_model`, `requires`, `auth`, `destructive_patterns`) + a `## verb:` section per verb. The `destructive_patterns` here must mirror the Python class; `bin/selftest.sh` checks they agree.
+
+Verbs that don't apply to a platform (e.g. `get_live_definition` / `diff_live_vs_repo` on a `git-sync` platform where git is the source of truth) should raise `ManualFallback` with a message telling the human what to do instead.
+
+## Dev setup
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+ruff check . && ruff format --check .
+pytest
+bash bin/selftest.sh
+```
+
+## Provenance
+
+jobwright was generalized from a production Databricks data-jobs repo. Every check and safety rule was earned against real jobs and real failures before being lifted here — and stripped of all org-specific values on the way out.

jobwright-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Chalmers
+
+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.

jobwright-0.0.1/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: jobwright
+Version: 0.0.1
+Summary: Open-source AI layer for governing, validating, and safely shipping data-orchestration jobs (Databricks, Airflow, dbt, Snowflake Tasks) with Claude Code
+Project-URL: Homepage, https://github.com/kyle-chalmers/jobwright
+Project-URL: Repository, https://github.com/kyle-chalmers/jobwright
+Project-URL: Issues, https://github.com/kyle-chalmers/jobwright/issues
+Author: Kyle Chalmers
+License: MIT
+License-File: LICENSE
+Keywords: airflow,ci,claude-code,data-engineering,databricks,dbt,governance,orchestration,snowflake
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# jobwright
+
+[![CI](https://github.com/kyle-chalmers/jobwright/actions/workflows/ci.yml/badge.svg)](https://github.com/kyle-chalmers/jobwright/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/jobwright.svg)](https://pypi.org/project/jobwright/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+**An open-source AI layer for governing, validating, and safely shipping data-orchestration jobs with Claude Code.**
+
+jobwright treats your *jobs* — Databricks Jobs, Airflow DAGs, dbt jobs, Snowflake Tasks — as deployable artifacts that deserve a governed lifecycle: a catalog you can recall before you rebuild, architecture-compliance scanning, a per-job validation gate, and a deploy-safety guard that prompts for confirmation before known destructive commands (so a stale-definition overwrite can't happen unattended).
+
+It is the third in a family of Claude Code "AI layer" kits:
+
+| Kit | Domain |
+|---|---|
+| [ticketwright](https://github.com/kyle-chalmers/ticketwright) | ticket-driven data work (plan → implement → validate) |
+| [streamsnow](https://github.com/kyle-chalmers/streamsnow) | Streamlit-in-Snowflake apps (build → govern → ship) |
+| **jobwright** | **data-orchestration jobs (govern → validate → safely ship)** |
+
+> **Complementary, not overlapping with ticketwright.** ticketwright's Databricks adapter is about *querying* a warehouse while doing a ticket. jobwright is about the *jobs themselves* — their definitions, architecture compliance, and safe deploy. ticketwright's "pause before any prod job deploy" gotcha is exactly the hand-off point to jobwright's `diff-job` + deploy-safety guard.
+
+## Why
+
+- **A deploy-safety guard.** A `PreToolUse` hook asks for confirmation before destructive orchestration commands (`databricks jobs reset`/`delete`, `airflow dags delete`, `DROP TASK`, …) and before destructive warehouse SQL — including SQL hidden in a `-f` file. On `api-reset` platforms it specifically blocks a reset from a possibly-stale repo definition until you've run a live-vs-repo diff. This turns a prose rule into a runtime gate.
+- **A jobs index.** A deterministic `JOBS.md` + `OBJECTS.md` over every job in the repo — ticket, purpose, schedule, owner, status, and architecture-compliance flags — so you (and the agent) recall prior work before rebuilding, and see migration debt at a glance.
+- **Architecture compliance.** A static scan of job code for deprecated-schema references and layer-referencing violations, driven by config — no database connection.
+- **Per-job validation.** A local PASS/FAIL gate that runs the same checks your CI does, scoped to one job.
+
+## Two seams
+
+jobwright has two orthogonal abstraction axes, expressed as two config blocks:
+
+- **platform** — the orchestrator a job *runs on* (`databricks` / `airflow` / `dbt` / `snowflake_tasks` / …). Owns the lifecycle verbs. Its `deploy_model` (`api-reset` | `git-sync` | `sql-ddl`) decides whether live-vs-repo drift even applies.
+- **warehouse / architecture** — the store a job *reads/writes* and the static schema-reference rules. Policy only; jobwright never opens a database connection.
+
+The platform seam is pluggable via thin adapters (a Python class implementing the verb contract + a markdown playbook). Shipped adapters span all three deploy models:
+
+| Platform | `deploy_model` | Drift detection |
+|---|---|---|
+| Databricks Jobs (reference) | `api-reset` | yes — live can drift from repo |
+| Snowflake Tasks | `sql-ddl` | yes — live DDL vs repo DDL |
+| Apache Airflow | `git-sync` | n/a — git is the source of truth |
+| dbt | `git-sync` | n/a — project is the source of truth |
+
+The generic checks (`syntax`, `deps`, `architecture`, `docs`) and the deploy-safety guard are platform-agnostic — see [`examples/`](examples/) for a Databricks repo and an Airflow + BigQuery repo. Adding a platform is two files (a `JobPlatformAdapter` subclass + a markdown playbook); see [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Install
+
+```bash
+pip install jobwright          # or: uvx jobwright
+# Claude Code plugin (skills + hooks):
+#   /plugin marketplace add kyle-chalmers/jobwright
+#   /plugin install jobwright@jobwright
+```
+
+## Quickstart
+
+```bash
+cp jobwright.config.example.yaml jobwright.config.yaml   # edit for your repo
+jobwright doctor                                         # check config + environment
+jobwright jobs-index                                     # render jobs/JOBS.md + OBJECTS.md
+jobwright diff-job BI-813                                # live-vs-repo drift for one job
+```
+
+See [`jobwright.config.example.yaml`](jobwright.config.example.yaml) for the full, documented config (including an Airflow + BigQuery variant) and [`examples/`](examples/) for a runnable sample repo.
+
+## Status
+
+Alpha. Shipped: the deploy-safety guard, the jobs index, four platform adapters (Databricks, Snowflake Tasks, Airflow, dbt) across all three deploy models, the generic checks (`syntax` / `job-defs` / `deps` / `architecture` / `docs`) + composite `validate-job`, the job scaffolder + generated `AGENTS.md`, the SessionStart + index-regen hooks, and 10 lifecycle skills. Publishing is gated on a security/leak review — see [`docs/PUBLISHING.md`](docs/PUBLISHING.md).
+
+### CLI
+
+```
+jobwright doctor | init | jobs-index [--check] | validate-job <folder> [--offline]
+          check {syntax|job-defs|deps|architecture|docs} <paths>
+          new-job <ticket> "<name>" | gen-agents | diff-job <job>
+```
+
+MIT licensed.

jobwright-0.0.1/README.md

@@ -0,0 +1,80 @@
+# jobwright
+
+[![CI](https://github.com/kyle-chalmers/jobwright/actions/workflows/ci.yml/badge.svg)](https://github.com/kyle-chalmers/jobwright/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/jobwright.svg)](https://pypi.org/project/jobwright/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+**An open-source AI layer for governing, validating, and safely shipping data-orchestration jobs with Claude Code.**
+
+jobwright treats your *jobs* — Databricks Jobs, Airflow DAGs, dbt jobs, Snowflake Tasks — as deployable artifacts that deserve a governed lifecycle: a catalog you can recall before you rebuild, architecture-compliance scanning, a per-job validation gate, and a deploy-safety guard that prompts for confirmation before known destructive commands (so a stale-definition overwrite can't happen unattended).
+
+It is the third in a family of Claude Code "AI layer" kits:
+
+| Kit | Domain |
+|---|---|
+| [ticketwright](https://github.com/kyle-chalmers/ticketwright) | ticket-driven data work (plan → implement → validate) |
+| [streamsnow](https://github.com/kyle-chalmers/streamsnow) | Streamlit-in-Snowflake apps (build → govern → ship) |
+| **jobwright** | **data-orchestration jobs (govern → validate → safely ship)** |
+
+> **Complementary, not overlapping with ticketwright.** ticketwright's Databricks adapter is about *querying* a warehouse while doing a ticket. jobwright is about the *jobs themselves* — their definitions, architecture compliance, and safe deploy. ticketwright's "pause before any prod job deploy" gotcha is exactly the hand-off point to jobwright's `diff-job` + deploy-safety guard.
+
+## Why
+
+- **A deploy-safety guard.** A `PreToolUse` hook asks for confirmation before destructive orchestration commands (`databricks jobs reset`/`delete`, `airflow dags delete`, `DROP TASK`, …) and before destructive warehouse SQL — including SQL hidden in a `-f` file. On `api-reset` platforms it specifically blocks a reset from a possibly-stale repo definition until you've run a live-vs-repo diff. This turns a prose rule into a runtime gate.
+- **A jobs index.** A deterministic `JOBS.md` + `OBJECTS.md` over every job in the repo — ticket, purpose, schedule, owner, status, and architecture-compliance flags — so you (and the agent) recall prior work before rebuilding, and see migration debt at a glance.
+- **Architecture compliance.** A static scan of job code for deprecated-schema references and layer-referencing violations, driven by config — no database connection.
+- **Per-job validation.** A local PASS/FAIL gate that runs the same checks your CI does, scoped to one job.
+
+## Two seams
+
+jobwright has two orthogonal abstraction axes, expressed as two config blocks:
+
+- **platform** — the orchestrator a job *runs on* (`databricks` / `airflow` / `dbt` / `snowflake_tasks` / …). Owns the lifecycle verbs. Its `deploy_model` (`api-reset` | `git-sync` | `sql-ddl`) decides whether live-vs-repo drift even applies.
+- **warehouse / architecture** — the store a job *reads/writes* and the static schema-reference rules. Policy only; jobwright never opens a database connection.
+
+The platform seam is pluggable via thin adapters (a Python class implementing the verb contract + a markdown playbook). Shipped adapters span all three deploy models:
+
+| Platform | `deploy_model` | Drift detection |
+|---|---|---|
+| Databricks Jobs (reference) | `api-reset` | yes — live can drift from repo |
+| Snowflake Tasks | `sql-ddl` | yes — live DDL vs repo DDL |
+| Apache Airflow | `git-sync` | n/a — git is the source of truth |
+| dbt | `git-sync` | n/a — project is the source of truth |
+
+The generic checks (`syntax`, `deps`, `architecture`, `docs`) and the deploy-safety guard are platform-agnostic — see [`examples/`](examples/) for a Databricks repo and an Airflow + BigQuery repo. Adding a platform is two files (a `JobPlatformAdapter` subclass + a markdown playbook); see [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Install
+
+```bash
+pip install jobwright          # or: uvx jobwright
+# Claude Code plugin (skills + hooks):
+#   /plugin marketplace add kyle-chalmers/jobwright
+#   /plugin install jobwright@jobwright
+```
+
+## Quickstart
+
+```bash
+cp jobwright.config.example.yaml jobwright.config.yaml   # edit for your repo
+jobwright doctor                                         # check config + environment
+jobwright jobs-index                                     # render jobs/JOBS.md + OBJECTS.md
+jobwright diff-job BI-813                                # live-vs-repo drift for one job
+```
+
+See [`jobwright.config.example.yaml`](jobwright.config.example.yaml) for the full, documented config (including an Airflow + BigQuery variant) and [`examples/`](examples/) for a runnable sample repo.
+
+## Status
+
+Alpha. Shipped: the deploy-safety guard, the jobs index, four platform adapters (Databricks, Snowflake Tasks, Airflow, dbt) across all three deploy models, the generic checks (`syntax` / `job-defs` / `deps` / `architecture` / `docs`) + composite `validate-job`, the job scaffolder + generated `AGENTS.md`, the SessionStart + index-regen hooks, and 10 lifecycle skills. Publishing is gated on a security/leak review — see [`docs/PUBLISHING.md`](docs/PUBLISHING.md).
+
+### CLI
+
+```
+jobwright doctor | init | jobs-index [--check] | validate-job <folder> [--offline]
+          check {syntax|job-defs|deps|architecture|docs} <paths>
+          new-job <ticket> "<name>" | gen-agents | diff-job <job>
+```
+
+MIT licensed.

jobwright-0.0.1/adapters/platform/airflow.md

@@ -0,0 +1,45 @@
+---
+seam: platform
+kind: airflow
+transport: cli
+deploy_model: git-sync
+requires: []
+auth: |
+  Airflow CLI talks to the configured Airflow environment (AIRFLOW_HOME / connection).
+  Verify: `airflow dags list`.
+destructive_patterns:
+  # MUST stay in sync with AirflowAdapter.destructive_patterns (jobwright/platforms/airflow.py).
+  - 'airflow\s+dags\s+delete\b'
+  - 'airflow\s+db\s+(reset|clean|downgrade)\b'
+---
+
+# Apache Airflow adapter
+
+Deploy model **git-sync**: DAGs are code, so the repo file *is* the definition. There is
+no live-vs-repo drift — `get_live_definition` / `diff_live_vs_repo` raise ManualFallback
+and point at `git diff`. "Deploy" is a git push / DAG-folder sync, not an API call.
+
+## verb: list_jobs
+```bash
+airflow dags list -o json
+```
+
+## verb: get_job_definition
+Reads the DAG `.py` from the configured `dags_dir`.
+
+## verb: get_live_definition / diff_live_vs_repo
+N/A (git-sync) — use `git status` / `git diff`.
+
+## verb: list_active_runs
+```bash
+airflow dags list-runs -d <dag_id> --state running -o json
+```
+
+## verb: trigger_run
+Checks active runs first, then `airflow dags trigger <dag_id>`.
+
+## verb: get_run / get_run_output
+Need dag_id (+ task_id): `airflow dags list-runs -d <dag_id>`, `airflow tasks logs <dag_id> <task_id> <run_id>`.
+
+## Gotchas
+- Airflow's REST API has no delete-DAG endpoint by design — deletion is a code/file operation.

jobwright-0.0.1/adapters/platform/databricks.md

@@ -0,0 +1,72 @@
+---
+seam: platform
+kind: databricks
+transport: cli
+deploy_model: api-reset
+requires: [profile]
+auth: |
+  Databricks CLI profile in ~/.databrickscfg (host + token), selected by
+  `platform.profile` in jobwright.config.yaml. Verify: `databricks jobs list --profile <p>`.
+  jobwright never stores the token — only the profile NAME.
+destructive_patterns:
+  # MUST stay in sync with DatabricksAdapter.destructive_patterns (jobwright/platforms/databricks.py).
+  # selftest.sh checks both lists agree.
+  - 'databricks\s+jobs\s+reset\b'
+  - 'databricks\s+jobs\s+delete\b'
+  - 'databricks\s+jobs\s+update\b'
+  - 'databricks\s+jobs\s+(run-now|submit)\b'
+---
+
+# Databricks Jobs adapter
+
+Reference implementation of the jobwright platform verb contract. Deploy model is
+**api-reset**: the live job definition can drift from the repo JSON, so drift
+detection is mandatory and `databricks jobs reset` is guarded.
+
+> **The incident this guards against:** `databricks jobs reset` is a *full replace*
+> of a job from the file you pass. Repo JSONs can be stale (jobs are sometimes
+> edited in the UI). Resetting from a stale JSON has overwritten correct live state
+> and broken production jobs. Always `diff-job` before a reset.
+
+## verb: list_jobs
+**Out:** `[{job_id, name, paused, schedule}]`
+```bash
+databricks jobs list -o json --profile <p>
+```
+
+## verb: get_job_definition
+**In:** ref (ticket / job name / filename stem) · **Out:** repo-side definition
+Resolves the JSON under `platform.job_def_dirs` by filename stem, ticket-key prefix, or `name` field.
+
+## verb: get_live_definition
+**In:** ref · **Out:** live definition from the workspace
+```bash
+databricks jobs get <job_id> -o json --profile <p>
+```
+
+## verb: diff_live_vs_repo
+**In:** ref (+ optional repo_path) · **Out:** `{drift, added, removed, changed, detail}`
+Normalizes both sides (unwraps `settings`, drops volatile keys: job_id, created_time, creator_user_name, run_as, …) then compares dotted paths.
+
+## verb: list_active_runs
+**In:** ref · **Out:** `[{run_id, state, started}]`
+```bash
+databricks jobs list-runs --job-id <id> --active-only -o json --profile <p>
+```
+
+## verb: deploy
+Withheld as a one-shot — use the `/safe-deploy` skill (diff → confirm → reset). The guard hook backstops any raw `databricks jobs reset`.
+
+## verb: trigger_run
+Checks `list_active_runs` first (refuses if a run is active), then `databricks jobs run-now <id>`.
+
+## verb: get_run / get_run_output
+```bash
+databricks jobs get-run <run_id> -o json --profile <p>
+databricks jobs get-run-output <run_id> -o json --profile <p>
+```
+
+## Gotchas
+- Repo JSONs are the *unwrapped* settings (top-level `name`, `schedule`, `tasks`); the API returns them under `settings`.
+- Repo JSONs have **no** `job_id`; jobwright resolves the live job by matching `name`.
+- A `run-now` timeout does **not** mean the run failed to start — check `list-runs --active-only` before retrying.

jobwright-0.0.1/adapters/platform/dbt.md

@@ -0,0 +1,40 @@
+---
+seam: platform
+kind: dbt
+transport: cli
+deploy_model: git-sync
+requires: []
+auth: |
+  `dbt` CLI with a configured profiles.yml. Verify: `dbt debug`.
+destructive_patterns:
+  # MUST stay in sync with DbtAdapter.destructive_patterns (jobwright/platforms/dbt.py).
+  - 'dbt\b(?=.*\b(?:run|build|seed|snapshot)\b)(?=.*(?:--target|-t)[=\s]+prod(?![\w-]))'
+  - 'dbt\b(?=.*\brun-operation\b)'
+---
+
+# dbt adapter
+
+Deploy model **git-sync**: the dbt project is the source of truth. dbt's unit is a model,
+not a standalone job, so discovery/run map best-effort to the CLI and drift verbs raise
+ManualFallback. The guard is the high-value piece: a `--target prod` run/build, or any
+`run-operation`, mutates the warehouse and must be confirmed.
+
+## verb: list_jobs
+```bash
+dbt ls --resource-type model --output name
+```
+
+## verb: get_job_definition
+Reads the model `.sql` from the models dir (configured via `dags_dir`).
+
+## verb: get_live_definition / diff_live_vs_repo
+N/A (git-sync) — use `git diff`.
+
+## verb: trigger_run
+`dbt build --select <model>` (default target; a prod target is caught by the guard).
+
+## verb: list_active_runs / get_run / get_run_output
+dbt core has no run registry — read `target/run_results.json`, or use the dbt Cloud Runs API.
+
+## Gotchas
+- A bare `dbt run` uses the default target; only `--target prod` (or `-t prod`) trips the guard.

jobwright-0.0.1/adapters/platform/snowflake_tasks.md

@@ -0,0 +1,51 @@
+---
+seam: platform
+kind: snowflake_tasks
+transport: cli
+deploy_model: sql-ddl
+requires: [profile]
+auth: |
+  `snow` CLI connection (named by platform.profile). Verify: `snow sql -q "SHOW TASKS"`.
+destructive_patterns:
+  # MUST stay in sync with SnowflakeTasksAdapter.destructive_patterns (jobwright/platforms/snowflake_tasks.py).
+  - '\bDROP\s+TASK\b'
+  - '\bCREATE\s+OR\s+REPLACE\s+TASK\b'
+  - '\bALTER\s+TASK\b'
+---
+
+# Snowflake Tasks adapter
+
+Deploy model **sql-ddl**: a task is defined by DDL and the live object can drift from
+the repo DDL — so drift detection applies and replace/drop/alter are guarded.
+
+## verb: list_jobs
+```sql
+SHOW TASKS
+```
+
+## verb: get_job_definition
+Reads the task DDL `.sql` from the configured `job_def_dirs`.
+
+## verb: get_live_definition
+```sql
+SELECT GET_DDL('TASK', '<task_name>')
+```
+
+## verb: diff_live_vs_repo
+Normalizes whitespace/case of repo DDL vs live `GET_DDL` and reports drift.
+
+## verb: list_active_runs
+```sql
+SELECT QUERY_ID, STATE FROM TABLE(INFORMATION_SCHEMA.TASK_HISTORY(TASK_NAME => '<task>')) WHERE STATE = 'EXECUTING'
+```
+
+## verb: trigger_run
+```sql
+EXECUTE TASK <task_name>
+```
+
+## verb: get_run / get_run_output
+Query `TASK_HISTORY` / `QUERY_HISTORY` by `QUERY_ID`.
+
+## Gotchas
+- `CREATE OR REPLACE TASK` silently overwrites the live definition — always `diff-job` first.

jobwright-0.0.1/bin/selftest.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# jobwright kit self-test — run before committing / publishing.
+# Verifies: lint, the Phase 0 contract tests (adapter verb coverage,
+# md/py destructive-pattern sync, the deploy-safety guard, index determinism),
+# and that no platform names leak into the skills (skills call verbs, not tools).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+PY="${PYTHON:-python3}"
+if [ -x .venv/bin/python ]; then PY=".venv/bin/python"; fi
+
+echo "==> ruff"
+"$PY" -m ruff check . || { echo "FAIL: ruff"; exit 1; }
+
+echo "==> pytest (Phase 0 contract)"
+"$PY" -m pytest -q || { echo "FAIL: pytest"; exit 1; }
+
+echo "==> skill leak check"
+if [ -d skills ] && [ -n "$(find skills -name '*.md' -print -quit 2>/dev/null)" ]; then
+  if grep -rEli '\b(databricks|airflow|dbt|dagster|prefect|snowflake_tasks|glue)\b' skills/ >/dev/null 2>&1; then
+    echo "FAIL: a platform name leaked into skills/ — skills must call abstract verbs, not name tools"
+    grep -rEli '\b(databricks|airflow|dbt|dagster|prefect|snowflake_tasks|glue)\b' skills/ || true
+    exit 1
+  fi
+fi
+
+echo "OK: jobwright selftest passed"