keel-workflow 0.6.0__tar.gz

keel_workflow-0.6.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work, excluding
+          those notices that do not pertain to any part of the Derivative
+          Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Berkay Turancı
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

keel_workflow-0.6.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: keel-workflow
+Version: 0.6.0
+Summary: Project-neutral, multi-agent workflow core: a fixed backbone of steps that drives an issue from backlog to done, customised per project via config + add-only Lego extensions.
+Author-email: Berkay Turancı <berkayturanci@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://berkayturanci.github.io/keel/
+Project-URL: Repository, https://github.com/berkayturanci/keel
+Project-URL: Issues, https://github.com/berkayturanci/keel/issues
+Project-URL: Changelog, https://github.com/berkayturanci/keel/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/berkayturanci/keel/tree/main/docs/keel
+Keywords: workflow,automation,ci,agents,code-review,github,merge-queue
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Dynamic: license-file
+
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="docs/assets/hero-light.svg">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero.svg">
+  <img src="docs/assets/hero.svg" alt="keel — a fixed backbone that drives a GitHub issue from backlog to merged">
+</picture>
+
+# keel ⚓
+
+[![CI](https://github.com/berkayturanci/keel/actions/workflows/ci.yml/badge.svg)](https://github.com/berkayturanci/keel/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/endpoint?url=https://berkayturanci.github.io/keel/coverage-badge.json)](https://berkayturanci.github.io/keel/coverage/)
+[![CodeQL](https://github.com/berkayturanci/keel/actions/workflows/codeql.yml/badge.svg)](https://github.com/berkayturanci/keel/actions/workflows/codeql.yml)
+[![PyPI](https://img.shields.io/pypi/v/keel-workflow)](https://pypi.org/project/keel-workflow/)
+[![Python](https://img.shields.io/pypi/pyversions/keel-workflow)](https://pypi.org/project/keel-workflow/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+> **keel** is a project-neutral, multi-agent **workflow core**. A *fixed backbone*
+> of steps drives a unit of work — a GitHub issue — from backlog to done
+> (branch → implement → CI → review → test → merge → close). Projects never fork the
+> backbone: they set per-project **values** in `project.yaml` and snap their own
+> **Lego pieces** into named extension slots.
+
+The keel is a ship's backbone — the fixed spine every project builds on. The flagship
+command is `keel:ship`; keel is where ships are built.
+
+> Formerly **`ai-infra`** (a one-way file-copy sync of "portable" commands). keel replaces
+> that with a thin-consumer model: the core is installed + pinned, never copied, so the
+> drift/overwrite class of bug is structurally gone. Background:
+> [`docs/proposals/divergence-audit-2035.md`](docs/proposals/divergence-audit-2035.md),
+> [`docs/proposals/keel-architecture.md`](docs/proposals/keel-architecture.md).
+
+## Three layers
+
+```
+Layer 3  EXTENSIONS   project-owned Lego pieces, ADD-ONLY into named slots
+Layer 2  CONFIG       project.yaml — per-project values (branch, build cmd, globs, agents…)
+Layer 1  BACKBONE     keel-core — fixed ordered step machine + invariants (this package)
+```
+
+Changing the backbone is a keel-core change. Projects only ever touch layers 2–3.
+
+### What you get
+
+- **One backbone, every agent** — install once; `/keel:<command>` runs as native Claude commands
+  *and* as a single shared skill set every other agent (Codex, Antigravity, Gemini) reads.
+- **Project Lego** — snap your own gates/steps into named hooks (`guard`, `tester`,
+  `pre-merge`, …) without forking the backbone; hard `block` gates are limited to the
+  documented blocking hooks.
+- **Opt-in `jury` gate** — runs the [ai-jury](https://github.com/berkayturanci/ai-jury) multi-agent
+  reviewer on the diff when installed; a fail-soft no-op otherwise.
+- **Safe merges by construction** — timezone-aware night no-merge window, `mkdir` merge lock,
+  risk-tier → reviewer count, hotfix bypass with an audit line, vendor+model attribution.
+
+### The backbone
+
+| step | name | primary hooks | |
+|---|---|---|---|
+| s0 | config | `after:config` | |
+| s1 | select | `before:select`, `select`, `after:select` | |
+| s2 | branch | `before:branch`, `after:branch` | |
+| s3 | guard | `guard` | |
+| s4 | implement | `before:implement`, `after-implement` | agent |
+| s5 | classify | `classify`, `after:classify` | agent |
+| s6 | ci | `before:ci`, `after:ci` | |
+| s7 | review | `reviewers`, `after:review` | agent |
+| s8 | test | `tester`, `test`, `after:test` | |
+| s9 | fixloop | `before:fixloop`, `fixloop`, `after:fixloop` | |
+| s10 | merge | `pre-merge`, `after:merge` | |
+| s11 | capture | `capture`, `post-merge` | |
+| s12 | close | `before:close`, `on-close`, `after:close` | |
+
+Invariants the backbone always preserves: merge lock, night no-merge window, fail-soft,
+orchestrator-only-writes, vendor+model attribution.
+
+## Install
+
+keel is a Python (≥3.11) package with one runtime dependency (PyYAML):
+
+```bash
+pip install keel-workflow                                     # from PyPI (provides the `keel` command)
+pip install "git+https://github.com/berkayturanci/keel@v0.6.0"  # or pin an existing git tag
+```
+
+In a cloud agent session, install it from a `SessionStart` hook (or add keel to the
+session's repo scope) so the selected core ref is available before a run.
+
+## Quickstart
+
+```bash
+keel validate projects/example-flutter.yaml          # validate a config against the schema
+keel plan      projects/example-flutter.yaml          # show the backbone plan for a project
+keel version
+```
+
+`keel plan` renders the fixed backbone with each project's gates/extensions slotted in —
+exactly what a dry-run executes:
+
+```
+keel plan — example-flutter
+  base_branch: main   core_version: ^0.6
+  backbone:
+     s4  implement  [agent]
+     ...
+     s8  test
+           - gate: build
+           - gate: lint
+           - gate: design-parity
+    s10  merge
+           - gate: design-parity-gate
+```
+
+## Invocation (`/keel:<command>`)
+
+The agentic workflows ship **with the package** as project-neutral adapters and install into
+the **two surfaces** agents actually read — so the same `/keel:<command>` works in every
+project; only that project's `.keel/project.yaml` + extensions change the behaviour:
+
+```bash
+keel install-adapter claude   # native Claude commands → /keel:ship, /keel:regression, …
+keel install-adapter skills   # one shared keel-<cmd> skill set under .agents/skills/
+#                               (read by every non-Claude agent: Codex, Antigravity, Gemini)
+keel install-adapter all      # both surfaces
+```
+
+**16 shipped commands** — `ship` (flagship), `ship-v2`, `implement`, `review-cycle`,
+`review-all-day`, `pr-loop`, `regression`, `triage`, `morning`, `overnight`, `wrap`,
+`ci-check`, `coverage`, `deps-audit`, `flake-audit`, `stale-prs`. Each is described in
+[`docs/keel/commands.md`](docs/keel/commands.md). The `keel` CLI does the deterministic work;
+the adapters are the agentic flows (per-round review, inline comments, delegation).
+
+## Dogfooding
+
+keel drives **itself**: its config is `projects/keel.yaml` (Python, `make test` + `make lint`
+gates) and CI runs keel on keel-core on every push —
+
+```bash
+keel plan      projects/keel.yaml          # render keel's own backbone
+keel run-gates projects/keel.yaml --root . # keel runs its own test + lint gates
+keel ship      projects/keel.yaml --root . # full dry assessment: tier, window, gates, decision
+#   risk tier     : TIER-3  → 3 reviewer(s)
+#   decision      : MERGE — clear to merge
+```
+
+If a step's gate fails, keel blocks its own merge — the same backbone every consumer gets.
+
+## Docs
+
+- 🌐 **Website + live coverage report** — `make site` builds the coverage HTML into
+  `website/coverage/` and serves the site at <http://localhost:8000>. (Publishing to GitHub
+  Pages is available via the manual `pages.yml` workflow once Pages is enabled.)
+- [`docs/keel/configuration.md`](docs/keel/configuration.md) — `project.yaml` reference
+- [`docs/keel/extensions.md`](docs/keel/extensions.md) — authoring Lego extensions
+- [`docs/keel/consumer-neutrality.md`](docs/keel/consumer-neutrality.md) — core vs project policy boundary
+- [`docs/keel/parity-matrix.md`](docs/keel/parity-matrix.md) — legacy-to-keel command parity status and owning issues
+- [`docs/keel/runtime-capabilities.md`](docs/keel/runtime-capabilities.md) — runtime capability detection and requirement declarations
+- [`docs/keel/github-transport.md`](docs/keel/github-transport.md) — GitHub transport selection and normalized operation capabilities
+- [`docs/keel/command-contracts.md`](docs/keel/command-contracts.md) — structured JSON plan/result contracts for adapters
+- [`docs/keel/operator-consent.md`](docs/keel/operator-consent.md) — live-run operator consent scopes and delegated-agent scope rules
+- [`docs/keel/cli.md`](docs/keel/cli.md) — CLI reference
+- [`docs/keel/commands.md`](docs/keel/commands.md) — the 16 `/keel:<command>` workflows, each with its description
+- [`docs/keel/cutover.md`](docs/keel/cutover.md) — staged guide to retire a project's copied command bodies (install → verify → retire), losing nothing
+- [`docs/keel/comparison.md`](docs/keel/comparison.md) — competitive landscape (Mergify, GitHub merge queue, Qodo/PR-Agent, CodeRabbit, Sweep, OpenHands, Danger, …) + ranked borrow-ideas
+- [`docs/keel/github-actions.md`](docs/keel/github-actions.md) — run keel live on GitHub's free runner (the `keel-ship` workflow)
+- [`docs/proposals/keel-architecture.md`](docs/proposals/keel-architecture.md) — full design
+
+## Development
+
+Stdlib-first, pure-core + thin-I/O, deterministic, fully covered (ai-jury ethos).
+
+```bash
+make test       # offline unit suite (no network, no credentials)
+make lint       # ruff
+make coverage   # coverage gate (fail_under in pyproject)
+make validate   # validate every projects/*.yaml
+make site       # build the coverage report + serve the website at localhost:8000
+```
+
+The pure core (`config`, `model`, `extensions`, `findings`, `gates`, `orchestrator`,
+`cli`) is held at **100% line + branch coverage**; the coverage gate (`fail_under = 95`)
+runs in CI.
+
+## Repo layout
+
+```
+src/keel/            the core package (config, model, extensions, findings, gates, orchestrator, cli)
+src/keel/schema/     project.schema.json (bundled)
+projects/*.yaml      example configs (example-android, example-flutter, keel)
+src/keel/adapters/   the packaged /keel:<command> bodies (install-adapter: claude commands + shared skills)
+adapters/            reference adapter (claude/keel-ship.md) + the adapter model (README)
+website/             static site + coverage report (make site)
+tests/               unit suite
+docs/                docs + proposals
+```

keel_workflow-0.6.0/README.md

@@ -0,0 +1,192 @@
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="docs/assets/hero-light.svg">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero.svg">
+  <img src="docs/assets/hero.svg" alt="keel — a fixed backbone that drives a GitHub issue from backlog to merged">
+</picture>
+
+# keel ⚓
+
+[![CI](https://github.com/berkayturanci/keel/actions/workflows/ci.yml/badge.svg)](https://github.com/berkayturanci/keel/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/endpoint?url=https://berkayturanci.github.io/keel/coverage-badge.json)](https://berkayturanci.github.io/keel/coverage/)
+[![CodeQL](https://github.com/berkayturanci/keel/actions/workflows/codeql.yml/badge.svg)](https://github.com/berkayturanci/keel/actions/workflows/codeql.yml)
+[![PyPI](https://img.shields.io/pypi/v/keel-workflow)](https://pypi.org/project/keel-workflow/)
+[![Python](https://img.shields.io/pypi/pyversions/keel-workflow)](https://pypi.org/project/keel-workflow/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+> **keel** is a project-neutral, multi-agent **workflow core**. A *fixed backbone*
+> of steps drives a unit of work — a GitHub issue — from backlog to done
+> (branch → implement → CI → review → test → merge → close). Projects never fork the
+> backbone: they set per-project **values** in `project.yaml` and snap their own
+> **Lego pieces** into named extension slots.
+
+The keel is a ship's backbone — the fixed spine every project builds on. The flagship
+command is `keel:ship`; keel is where ships are built.
+
+> Formerly **`ai-infra`** (a one-way file-copy sync of "portable" commands). keel replaces
+> that with a thin-consumer model: the core is installed + pinned, never copied, so the
+> drift/overwrite class of bug is structurally gone. Background:
+> [`docs/proposals/divergence-audit-2035.md`](docs/proposals/divergence-audit-2035.md),
+> [`docs/proposals/keel-architecture.md`](docs/proposals/keel-architecture.md).
+
+## Three layers
+
+```
+Layer 3  EXTENSIONS   project-owned Lego pieces, ADD-ONLY into named slots
+Layer 2  CONFIG       project.yaml — per-project values (branch, build cmd, globs, agents…)
+Layer 1  BACKBONE     keel-core — fixed ordered step machine + invariants (this package)
+```
+
+Changing the backbone is a keel-core change. Projects only ever touch layers 2–3.
+
+### What you get
+
+- **One backbone, every agent** — install once; `/keel:<command>` runs as native Claude commands
+  *and* as a single shared skill set every other agent (Codex, Antigravity, Gemini) reads.
+- **Project Lego** — snap your own gates/steps into named hooks (`guard`, `tester`,
+  `pre-merge`, …) without forking the backbone; hard `block` gates are limited to the
+  documented blocking hooks.
+- **Opt-in `jury` gate** — runs the [ai-jury](https://github.com/berkayturanci/ai-jury) multi-agent
+  reviewer on the diff when installed; a fail-soft no-op otherwise.
+- **Safe merges by construction** — timezone-aware night no-merge window, `mkdir` merge lock,
+  risk-tier → reviewer count, hotfix bypass with an audit line, vendor+model attribution.
+
+### The backbone
+
+| step | name | primary hooks | |
+|---|---|---|---|
+| s0 | config | `after:config` | |
+| s1 | select | `before:select`, `select`, `after:select` | |
+| s2 | branch | `before:branch`, `after:branch` | |
+| s3 | guard | `guard` | |
+| s4 | implement | `before:implement`, `after-implement` | agent |
+| s5 | classify | `classify`, `after:classify` | agent |
+| s6 | ci | `before:ci`, `after:ci` | |
+| s7 | review | `reviewers`, `after:review` | agent |
+| s8 | test | `tester`, `test`, `after:test` | |
+| s9 | fixloop | `before:fixloop`, `fixloop`, `after:fixloop` | |
+| s10 | merge | `pre-merge`, `after:merge` | |
+| s11 | capture | `capture`, `post-merge` | |
+| s12 | close | `before:close`, `on-close`, `after:close` | |
+
+Invariants the backbone always preserves: merge lock, night no-merge window, fail-soft,
+orchestrator-only-writes, vendor+model attribution.
+
+## Install
+
+keel is a Python (≥3.11) package with one runtime dependency (PyYAML):
+
+```bash
+pip install keel-workflow                                     # from PyPI (provides the `keel` command)
+pip install "git+https://github.com/berkayturanci/keel@v0.6.0"  # or pin an existing git tag
+```
+
+In a cloud agent session, install it from a `SessionStart` hook (or add keel to the
+session's repo scope) so the selected core ref is available before a run.
+
+## Quickstart
+
+```bash
+keel validate projects/example-flutter.yaml          # validate a config against the schema
+keel plan      projects/example-flutter.yaml          # show the backbone plan for a project
+keel version
+```
+
+`keel plan` renders the fixed backbone with each project's gates/extensions slotted in —
+exactly what a dry-run executes:
+
+```
+keel plan — example-flutter
+  base_branch: main   core_version: ^0.6
+  backbone:
+     s4  implement  [agent]
+     ...
+     s8  test
+           - gate: build
+           - gate: lint
+           - gate: design-parity
+    s10  merge
+           - gate: design-parity-gate
+```
+
+## Invocation (`/keel:<command>`)
+
+The agentic workflows ship **with the package** as project-neutral adapters and install into
+the **two surfaces** agents actually read — so the same `/keel:<command>` works in every
+project; only that project's `.keel/project.yaml` + extensions change the behaviour:
+
+```bash
+keel install-adapter claude   # native Claude commands → /keel:ship, /keel:regression, …
+keel install-adapter skills   # one shared keel-<cmd> skill set under .agents/skills/
+#                               (read by every non-Claude agent: Codex, Antigravity, Gemini)
+keel install-adapter all      # both surfaces
+```
+
+**16 shipped commands** — `ship` (flagship), `ship-v2`, `implement`, `review-cycle`,
+`review-all-day`, `pr-loop`, `regression`, `triage`, `morning`, `overnight`, `wrap`,
+`ci-check`, `coverage`, `deps-audit`, `flake-audit`, `stale-prs`. Each is described in
+[`docs/keel/commands.md`](docs/keel/commands.md). The `keel` CLI does the deterministic work;
+the adapters are the agentic flows (per-round review, inline comments, delegation).
+
+## Dogfooding
+
+keel drives **itself**: its config is `projects/keel.yaml` (Python, `make test` + `make lint`
+gates) and CI runs keel on keel-core on every push —
+
+```bash
+keel plan      projects/keel.yaml          # render keel's own backbone
+keel run-gates projects/keel.yaml --root . # keel runs its own test + lint gates
+keel ship      projects/keel.yaml --root . # full dry assessment: tier, window, gates, decision
+#   risk tier     : TIER-3  → 3 reviewer(s)
+#   decision      : MERGE — clear to merge
+```
+
+If a step's gate fails, keel blocks its own merge — the same backbone every consumer gets.
+
+## Docs
+
+- 🌐 **Website + live coverage report** — `make site` builds the coverage HTML into
+  `website/coverage/` and serves the site at <http://localhost:8000>. (Publishing to GitHub
+  Pages is available via the manual `pages.yml` workflow once Pages is enabled.)
+- [`docs/keel/configuration.md`](docs/keel/configuration.md) — `project.yaml` reference
+- [`docs/keel/extensions.md`](docs/keel/extensions.md) — authoring Lego extensions
+- [`docs/keel/consumer-neutrality.md`](docs/keel/consumer-neutrality.md) — core vs project policy boundary
+- [`docs/keel/parity-matrix.md`](docs/keel/parity-matrix.md) — legacy-to-keel command parity status and owning issues
+- [`docs/keel/runtime-capabilities.md`](docs/keel/runtime-capabilities.md) — runtime capability detection and requirement declarations
+- [`docs/keel/github-transport.md`](docs/keel/github-transport.md) — GitHub transport selection and normalized operation capabilities
+- [`docs/keel/command-contracts.md`](docs/keel/command-contracts.md) — structured JSON plan/result contracts for adapters
+- [`docs/keel/operator-consent.md`](docs/keel/operator-consent.md) — live-run operator consent scopes and delegated-agent scope rules
+- [`docs/keel/cli.md`](docs/keel/cli.md) — CLI reference
+- [`docs/keel/commands.md`](docs/keel/commands.md) — the 16 `/keel:<command>` workflows, each with its description
+- [`docs/keel/cutover.md`](docs/keel/cutover.md) — staged guide to retire a project's copied command bodies (install → verify → retire), losing nothing
+- [`docs/keel/comparison.md`](docs/keel/comparison.md) — competitive landscape (Mergify, GitHub merge queue, Qodo/PR-Agent, CodeRabbit, Sweep, OpenHands, Danger, …) + ranked borrow-ideas
+- [`docs/keel/github-actions.md`](docs/keel/github-actions.md) — run keel live on GitHub's free runner (the `keel-ship` workflow)
+- [`docs/proposals/keel-architecture.md`](docs/proposals/keel-architecture.md) — full design
+
+## Development
+
+Stdlib-first, pure-core + thin-I/O, deterministic, fully covered (ai-jury ethos).
+
+```bash
+make test       # offline unit suite (no network, no credentials)
+make lint       # ruff
+make coverage   # coverage gate (fail_under in pyproject)
+make validate   # validate every projects/*.yaml
+make site       # build the coverage report + serve the website at localhost:8000
+```
+
+The pure core (`config`, `model`, `extensions`, `findings`, `gates`, `orchestrator`,
+`cli`) is held at **100% line + branch coverage**; the coverage gate (`fail_under = 95`)
+runs in CI.
+
+## Repo layout
+
+```
+src/keel/            the core package (config, model, extensions, findings, gates, orchestrator, cli)
+src/keel/schema/     project.schema.json (bundled)
+projects/*.yaml      example configs (example-android, example-flutter, keel)
+src/keel/adapters/   the packaged /keel:<command> bodies (install-adapter: claude commands + shared skills)
+adapters/            reference adapter (claude/keel-ship.md) + the adapter model (README)
+website/             static site + coverage report (make site)
+tests/               unit suite
+docs/                docs + proposals
+```