forgeo-cli 0.7.3__tar.gz → 0.8.0__tar.gz

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-21
+
+### Added
+
+- A Jira task provider selected with `backlog_provider: jira`, including Jira
+  Cloud cursor pagination, workflow-based claiming, optional custom-field
+  mappings, issue-property engine state, stale-claim recovery, and bearer or
+  basic authentication from environment variables.
+- A provider-level claim hook so remote task sources can prevent duplicate
+  agent runs while preserving the existing JSON and HTTP backlog behavior.
+
 ## [0.7.3] - 2026-08-19
 
 ### Added
@@ -349,7 +360,8 @@ Initial release of the scheduled, agent-driven software forgeo.
   overlapping-run skipping.
 - Dogfooding docs removed; local configs kept out of the repository.
 
-[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.7.3...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/lucaGazzola/forgeo/compare/v0.7.3...v0.8.0
 [0.7.3]: https://github.com/lucaGazzola/forgeo/compare/v0.7.2...v0.7.3
 [0.7.2]: https://github.com/lucaGazzola/forgeo/compare/v0.7.1...v0.7.2
 [0.7.1]: https://github.com/lucaGazzola/forgeo/compare/v0.7.0...v0.7.1

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.7.3
+Version: 0.8.0
 Summary: A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input.
 Project-URL: Homepage, https://forgeo.org
 Project-URL: Documentation, https://forgeo.org
@@ -121,6 +121,9 @@ configuration, start the daemon.
 # Backlog format), created on first use:
 #   .forgeo/backlog.json
 
+# Or: configure `backlog_provider: jira` and set `backlog` to a Jira base URL
+# (see the Jira backlog documentation).
+
 # Or: add tasks from the web console once your forgeo is registered
 # (first `forgeo start` registers it automatically):
 forgeo web      # dashboard at http://0.0.0.0:8790, or keep it on with `forgeo web -d`
@@ -167,6 +170,27 @@ shared host protect it with `forgeo web --token` (requires
 `Authorization: Bearer <token>` on every `/api/*` route — see
 [Web console & HTTP API](docs/web-console-api.md)).
 
+### Running the agent in a container
+
+By default Forgeo runs the agent directly on the host. To run it inside a
+Docker container instead, set `agent_sandbox: docker` in `forgeo.yaml`:
+
+```yaml
+agent_sandbox: docker
+agent_sandbox_image: your-image
+agent_sandbox_network: none   # default; set bridge/host to allow network
+agent_sandbox_mounts:         # optional, read-only, e.g. ~/.claude
+  - ~/.claude
+```
+
+The image must already contain the agent CLI your `agent_command` uses plus a
+shell (nothing is installed at run time). Forgeo bind-mounts the repository
+into the container at the same path, so the agent's edits land on your
+checkout and are committed as usual; the task is passed through as
+`FORGEO_TASK`. Networking is off by default (`none`) and nothing else is
+visible inside the container unless you list it in `agent_sandbox_mounts`.
+See the [Configuration](docs/configuration.md) docs for details.
+
 ### Multiple repositories (instances)
 
 Run several factories at once, one per repository; each config is fully
@@ -186,14 +210,15 @@ and get one aggregate overview with the central dashboard, `forgeo web`.
 | All CLI commands | [CLI reference](docs/cli-reference.md) |
 | Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
 
-Everything is stored in plain files: the backlog, `forgeo.log`, and
+Everything is stored in plain files: the local backlog, `forgeo.log`, and
 `BLOCKER.md` whenever a decision is pending. The backlog can also live in
-another application behind an `http(s)` URL — Forgeo reads the whole task
-document with `GET` and writes it back with `POST`, with optional OAuth2
-client-credentials auth (see [Backlog format](docs/backlog.md)). A *file*
-backlog is snapshotted (rotating `backlog.json.bak` files) before every
-agent run and on daemon startup, and restored automatically if it is ever
-found corrupt — a bad write never loses your tasks.
+another application behind an `http(s)` URL, or in Jira. HTTP backlogs
+exchange the complete task document; Jira issues are read and transitioned
+individually with workflow state and engine metadata stored on the issue (see
+[Backlog format](docs/backlog.md)). A *file* backlog is snapshotted (rotating
+`backlog.json.bak` files) before every agent run and on daemon startup, and
+restored automatically if it is ever found corrupt — a bad write never loses
+your tasks.
 
 ## Develop
 

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/README.md

@@ -67,6 +67,9 @@ configuration, start the daemon.
 # Backlog format), created on first use:
 #   .forgeo/backlog.json
 
+# Or: configure `backlog_provider: jira` and set `backlog` to a Jira base URL
+# (see the Jira backlog documentation).
+
 # Or: add tasks from the web console once your forgeo is registered
 # (first `forgeo start` registers it automatically):
 forgeo web      # dashboard at http://0.0.0.0:8790, or keep it on with `forgeo web -d`
@@ -113,6 +116,27 @@ shared host protect it with `forgeo web --token` (requires
 `Authorization: Bearer <token>` on every `/api/*` route — see
 [Web console & HTTP API](docs/web-console-api.md)).
 
+### Running the agent in a container
+
+By default Forgeo runs the agent directly on the host. To run it inside a
+Docker container instead, set `agent_sandbox: docker` in `forgeo.yaml`:
+
+```yaml
+agent_sandbox: docker
+agent_sandbox_image: your-image
+agent_sandbox_network: none   # default; set bridge/host to allow network
+agent_sandbox_mounts:         # optional, read-only, e.g. ~/.claude
+  - ~/.claude
+```
+
+The image must already contain the agent CLI your `agent_command` uses plus a
+shell (nothing is installed at run time). Forgeo bind-mounts the repository
+into the container at the same path, so the agent's edits land on your
+checkout and are committed as usual; the task is passed through as
+`FORGEO_TASK`. Networking is off by default (`none`) and nothing else is
+visible inside the container unless you list it in `agent_sandbox_mounts`.
+See the [Configuration](docs/configuration.md) docs for details.
+
 ### Multiple repositories (instances)
 
 Run several factories at once, one per repository; each config is fully
@@ -132,14 +156,15 @@ and get one aggregate overview with the central dashboard, `forgeo web`.
 | All CLI commands | [CLI reference](docs/cli-reference.md) |
 | Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
 
-Everything is stored in plain files: the backlog, `forgeo.log`, and
+Everything is stored in plain files: the local backlog, `forgeo.log`, and
 `BLOCKER.md` whenever a decision is pending. The backlog can also live in
-another application behind an `http(s)` URL — Forgeo reads the whole task
-document with `GET` and writes it back with `POST`, with optional OAuth2
-client-credentials auth (see [Backlog format](docs/backlog.md)). A *file*
-backlog is snapshotted (rotating `backlog.json.bak` files) before every
-agent run and on daemon startup, and restored automatically if it is ever
-found corrupt — a bad write never loses your tasks.
+another application behind an `http(s)` URL, or in Jira. HTTP backlogs
+exchange the complete task document; Jira issues are read and transitioned
+individually with workflow state and engine metadata stored on the issue (see
+[Backlog format](docs/backlog.md)). A *file* backlog is snapshotted (rotating
+`backlog.json.bak` files) before every agent run and on daemon startup, and
+restored automatically if it is ever found corrupt — a bad write never loses
+your tasks.
 
 ## Develop
 

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/docs/backlog.md

@@ -6,7 +6,7 @@ hand, living wherever `backlog:` points in [forgeo.yaml](configuration.md) —
 `forgeo init`. Keep it outside the repository if you can so the agent never
 touches it. It can also be [served over HTTP](#a-backlog-over-http) by another
 application, in which case the document below is exactly what that endpoint
-exchanges with Forgeo.
+exchanges with Forgeo, or it can be sourced directly from [Jira](#a-jira-backlog).
 
 ```json
 {
@@ -287,7 +287,7 @@ favor of an older valid one; when no snapshot exists, the forgeo falls back to
 an empty store exactly as before. A missing backlog is a no-op — no snapshot
 is created for a file that does not exist.
 
-This whole section is about a backlog *file*. A backlog URL is owned by the
+This whole section is about a backlog *file*. A remote backlog is owned by the
 application serving it, which keeps its own history, so Forgeo neither
 snapshots nor repairs it — see below.
 
@@ -349,3 +349,78 @@ There is no backlog file for Forgeo's own runtime files to sit beside, so
 `runs.jsonl` go into `state_dir`, which defaults to the directory holding
 `forgeo.yaml`. No snapshots are written: the document belongs to the remote
 application, so rolling it back is that application's job, not Forgeo's.
+
+## A Jira backlog
+
+Set `backlog_provider: jira` and point `backlog:` at the Jira base URL:
+
+```yaml
+backlog_provider: jira
+backlog: https://jira.example.com
+
+jira:
+  jql: 'project = APP AND labels = forgeo'
+  project_key: APP
+  auth:
+    scheme: basic
+    username_env: JIRA_USER
+    token_env: JIRA_TOKEN
+  workflow:
+    open_statuses: ["10000", "10001"]
+    open_status: "10000"
+    running_status: "3"
+    completed_status: "10002"
+```
+
+The JQL is the provider's scope. It should include open, running, blocked and
+completed issues so Forgeo can see dependencies and render the dashboard
+correctly. Jira status references can be names or ids; ids are more stable.
+
+### Mapping and lifecycle
+
+- Jira issue keys are Forgeo task ids.
+- `summary`, `description`, `created` and `updated` map to the corresponding task fields.
+- `open_statuses` identifies issues eligible for picking.
+- `running_status` is applied before the agent starts, preventing a second worker from claiming the same issue.
+- `completed_status` is applied after a successful commit.
+- `blocked_status` is optional; the `forgeo-blocked` label is always applied when the agent needs human input.
+- `failed_status` is optional; without it, the `forgeo-failed` label represents a failed task while the issue returns to the configured open status.
+
+Forgeo stores blocker reasons, failure reasons, retry counters, claim time and
+bounded agent output in the Jira issue property named `forgeo` by default.
+Set `jira.property_key` to change it. Optional Jira custom fields can carry
+`acceptance_criteria`, `dependencies`, `files_to_modify`, per-task agent
+settings, `run_at`, and `retries_left`. If no custom `run_at` field is
+configured, Jira's native `duedate` is used at midnight UTC:
+
+```yaml
+jira:
+  fields:
+    acceptance_criteria: customfield_10042
+    dependencies: customfield_10043
+```
+
+Dependencies may also be inferred from Jira issue links whose link type is
+`blocks`. The issue that is blocked is treated as depending on the issue that
+blocks it.
+
+### Authentication
+
+Jira credentials are never stored directly in `forgeo.yaml`:
+
+- `basic` uses `username` or `username_env` plus an API token named by `token_env`.
+- `bearer` uses a personal-access token named by `token_env`.
+
+The client uses Jira REST API v3 by default, including Jira Cloud's
+`/search/jql` endpoint and cursor pagination via `nextPageToken`. Set
+`jira.api_version: 2` for Jira installations that expose the older offset-based
+search endpoint and v2 comment/description format.
+
+### Runtime behavior
+
+The daemon reads Jira with paginated JQL searches. A task is claimed by
+rechecking it and transitioning it to `running_status` before the agent runs.
+If a process dies while holding a claim, a later cycle releases claims older
+than `claim_timeout_seconds` and returns them to the configured open status.
+An unavailable Jira endpoint fails the cycle; it is never treated as an empty
+backlog.

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/docs/cli-reference.md

@@ -184,8 +184,9 @@ It validates, reporting **all** problems at once:
   would refuse as dirty — make an initial commit first
   (`git add -A && git commit -m "Initial commit"`);
 - the remote resolves when `remote` is set (`git remote get-url`);
-- the backlog parses and every task is valid (a missing backlog is fine: it
-  is treated as empty on the first cycle);
+- the backlog parses and every task is valid (a missing file backlog is fine:
+  it is treated as empty on the first cycle; HTTP and Jira providers are
+  contacted read-only and must answer);
 - the run lock state (`backlog.lock`); a held lock is a warning, since
   `forgeo start`/`forgeo once` will refuse to run until it is released.
 

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/docs/configuration.md

@@ -22,9 +22,11 @@ paths), so `forgeo restart` is still used for those.
 | <span style="white-space: nowrap">`interval_minutes`</span> | `60` | How often Forgeo runs (≥ 1). |
 | <span style="white-space: nowrap">`branch`</span> | `main` | The single branch everything is committed to. |
 | <span style="white-space: nowrap">`remote`</span> | — | Remote to push to (e.g. `origin`); omit to only commit locally. |
-| <span style="white-space: nowrap">`backlog`</span> | `backlog.json` | The task backlog: the path of a JSON file (keep it outside the repo if you can), or an `http(s)` URL serving the same document — see [a backlog over HTTP](backlog.md#a-backlog-over-http). |
-| <span style="white-space: nowrap">`state_dir`</span> | — | Directory for Forgeo's runtime files (locks, run history, daemon state). Only meaningful with a backlog URL, where it defaults to the directory of `forgeo.yaml`. |
+| <span style="white-space: nowrap">`backlog`</span> | `backlog.json` | The task backlog: the path of a JSON file, an HTTP endpoint serving the same document, or a Jira base URL when `backlog_provider: jira`. |
+| <span style="white-space: nowrap">`backlog_provider`</span> | `auto` | `auto` infers file/HTTP from `backlog`, or Jira when a `jira` block is present; explicitly choose `file`, `http`, or `jira` when preferred. |
+| <span style="white-space: nowrap">`state_dir`</span> | — | Directory for Forgeo's runtime files (locks, run history, daemon state). Remote backlogs default this to the directory of `forgeo.yaml`. |
 | <span style="white-space: nowrap">`backlog_auth`</span> | — | OAuth2 client credentials for a backlog URL that requires them (see [below](#backlog_auth)). |
+| <span style="white-space: nowrap">`jira`</span> | — | Jira REST, workflow, authentication, and custom-field settings. Required when `backlog_provider: jira`. |
 | <span style="white-space: nowrap">`blocker_file`</span> | `BLOCKER.md` | Where `BLOCKER.md` is written. Keep it outside the repo so it is never committed. |
 | <span style="white-space: nowrap">`agent_command`</span> | — | The coding agent: any shell command (string) or argv list. **Required.** |
 | <span style="white-space: nowrap">`agent_timeout_seconds`</span> | — | Optional: kill the agent after this many seconds (`null` = never). |
@@ -67,6 +69,77 @@ refactor_prompt: >
   behavior, run the test suite, and apply safe changes.
 ```
 
+## Jira backlog
+
+Forgeo can read and update Jira issues directly. Set `backlog_provider: jira`
+and make `backlog` the Jira base URL. Jira issue keys become task ids. The JQL
+should include every lifecycle state that should be visible to Forgeo; do not
+filter it to only `To Do`, or completed and blocked issues will disappear from
+the dashboard and dependency checks.
+
+```yaml
+backlog_provider: jira
+backlog: https://jira.example.com
+state_dir: .forgeo
+
+jira:
+  jql: 'project = APP AND labels = forgeo'
+  project_key: APP                 # Needed for task creation from the web UI.
+  issue_type: Task
+  auth:
+    scheme: basic                  # Jira Cloud; use bearer for a Server/DC PAT.
+    username_env: JIRA_USER
+    token_env: JIRA_TOKEN
+  workflow:
+    open_statuses: ["10000", "10001"]
+    open_status: "10000"
+    running_status: "3"
+    completed_status: "10002"
+    blocked_status: null            # Optional Jira workflow transition.
+    failed_status: null             # Failed is represented by a Forgeo label.
+  fields:
+    acceptance_criteria: customfield_10042
+    dependencies: customfield_10043
+```
+
+Status values may be names, but stable Jira status ids are preferred. Forgeo
+adds `forgeo-running`, `forgeo-blocked`, and `forgeo-failed` labels as needed.
+Engine-managed details (`blocker_reason`, failure details, retry counters and
+the bounded agent response) are stored in a Jira issue property, whose key is
+`forgeo` by default. A Jira workflow does not need a custom `FAILED` status.
+
+Before starting the daemon, set the configured environment variables and run:
+
+```bash
+export JIRA_USER='automation@example.com'
+export JIRA_TOKEN='...'
+forgeo validate
+```
+
+Forgeo transitions an issue to `running_status` before invoking the agent and
+releases stale claims after `claim_timeout_seconds` (one day by default). The
+web console can create, edit, reopen, and delete Jira issues when the required
+project and custom-field mappings are configured; Jira remains the source of
+truth for human changes.
+
+### Jira settings
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `jira.jql` | — | Required JQL scope. Include all lifecycle states that Forgeo must see. |
+| `jira.auth` | — | Required credentials. Use `basic` with a username and API-token environment variable, or `bearer` with a token environment variable. |
+| `jira.project_key` | — | Jira project key used when the web console creates issues. |
+| `jira.issue_type` | `Task` | Jira issue type name used for creation. |
+| `jira.api_version` | `3` | API version. v3 uses Jira Cloud's cursor-based `/search/jql`; v2 uses offset-based search. |
+| `jira.page_size` | `50` | Issues requested per search page, from 1 to 100. |
+| `jira.max_issues` | `1000` | Maximum issues read from one JQL search. |
+| `jira.timeout_seconds` | `30` | Timeout for each Jira REST request. |
+| `jira.claim_timeout_seconds` | `86400` | Age after which an abandoned running claim is released. |
+| `jira.label_prefix` | `forgeo` | Prefix for the running, blocked, and failed labels. |
+| `jira.property_key` | `forgeo` | Jira issue-property key holding Forgeo engine state. |
+| `jira.workflow` | defaults | Status ids or names for open, running, blocked, completed, and failed transitions. |
+| `jira.fields` | — | Optional custom-field ids for task attributes such as acceptance criteria and dependencies. |
+
 ## Key details
 
 ### `backlog_auth`
@@ -385,7 +458,7 @@ Each registered instance is fully independent: every instance owns its own
 **backlog**, **logs** (`log_file`), **run history** (`runs.jsonl`), **locks**
 (`backlog.lock` and the per-iteration `backlog.run`), and a
 **`backlog.state.json`** with its live state. Those runtime files sit next to
-the backlog file, or — when the backlog is a URL — in `state_dir`, which
+the backlog file, or — when the backlog is remote — in `state_dir`, which
 defaults to the directory of that instance's `forgeo.yaml`. Because relative
 paths resolve against each config file's own directory, two configs in
 different directories can never share state.

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/docs/getting-started.md

@@ -82,7 +82,13 @@ the file configured as `backlog:` in your `forgeo.yaml` — by default
 `.forgeo/backlog.json`. Once Forgeo is running you can also add tasks
 from the [web console](web-console-api.md) — no file editing needed. (If your
 tasks already live in another application, `backlog:` also accepts an
-[HTTP endpoint](backlog.md#a-backlog-over-http) instead of a file.)
+[HTTP endpoint](backlog.md#a-backlog-over-http) or a [Jira source](backlog.md#a-jira-backlog)
+instead of a file.)
+
+For Jira, set `backlog_provider: jira`, point `backlog:` at the Jira base URL,
+configure `jira.jql` and the workflow mappings, export the credentials named in
+`jira.auth`, and run `forgeo validate` before starting the daemon. See [Jira
+backlogs](backlog.md#a-jira-backlog) for the complete configuration.
 
 ```json
 {

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/docs/index.md

@@ -36,12 +36,12 @@ Forgeo is deliberately single-purpose:
 ## Where state lives
 
 - `forgeo.yaml` — the config (see [Configuration](configuration.md)).
-- `backlog.json` (configurable) — the task backlog, a file or an HTTP
-  endpoint (see [Backlog format](backlog.md)).
+- `backlog.json` (configurable) — the task backlog, a file, an HTTP endpoint,
+  or Jira (see [Backlog format](backlog.md)).
 - `backlog.json.bak`, `backlog.json.bak.1`, ... — rotating snapshots of a
   *file* backlog, written before every agent run and on daemon startup so a
   bad write can always be rolled back (see [Backlog format](backlog.md)). A
-  URL backlog is owned by the remote application and is never snapshotted.
+  remote backlog is owned by its provider and is never snapshotted locally.
 - `BLOCKER.md` (configurable) — written when a human decision is needed; keep
   it outside the repo so it is never committed.
 - `forgeo.log` — rotating daemon log (5 MB × 3), also served over HTTP.
@@ -58,8 +58,8 @@ Forgeo is deliberately single-purpose:
   token (`forgeo web --token`): when present, every `/api/*` route requires
   `Authorization: Bearer <token>`; with no file the dashboard stays open.
 
-The runtime files above sit next to the backlog file; with a backlog URL they
-go in `state_dir`, which defaults to the directory holding `forgeo.yaml`.
+The runtime files above sit next to the backlog file; with a remote backlog
+they go in `state_dir`, which defaults to the directory holding `forgeo.yaml`.
 
 ## Next steps
 

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/docs/web-console-api.md

@@ -6,9 +6,9 @@ just schedules cycles and writes its live state to `daemon.state.json`. The
 dashboard reads every registered instance's data straight from its files
 (`backlog.json`, `runs.jsonl`, `forgeo.log`, `BLOCKER.md`,
 `daemon.state.json`), so it works whether or not each instance's daemon is
-running. An instance whose `backlog` is an HTTP endpoint is the exception: its
-tasks are fetched from there, and an endpoint that cannot be reached answers
-`502` rather than showing an empty board.
+running. HTTP and Jira backlogs are fetched from their providers instead, and
+a remote source that cannot be reached answers `502` rather than showing an
+empty board.
 
 ```bash
 forgeo web               # default 0.0.0.0:8790, foreground
@@ -153,10 +153,9 @@ curl http://127.0.0.1:8790/api/instances
 ```
 
 Each row also carries `backlog_error`: `null` normally, and the reason when
-that instance's backlog could not be read (only possible for a backlog served
-over HTTP). Its counts are zero in that case — the row reports a backlog it
-could not reach, not an empty one. One unreachable endpoint never fails the
-whole listing.
+that instance's remote backlog could not be read. Its counts are zero in that
+case — the row reports a backlog it could not reach, not an empty one. One
+unreachable provider never fails the whole listing.
 
 ### `GET /api/instances/<name>/tasks`
 
@@ -189,8 +188,8 @@ curl http://127.0.0.1:8790/api/instances/my-repo/tasks
 ]
 ```
 
-A backlog served over HTTP is fetched on each request; when the endpoint is
-unreachable the response is `502` with the reason in `error`.
+A remote backlog is fetched on each request; when the provider is unreachable
+the response is `502` with the reason in `error`.
 
 ### `GET /api/instances/<name>/tasks/{id}`
 

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/install.sh

@@ -14,7 +14,7 @@ set -eu
 
 REPO_OWNER="lucaGazzola"
 REPO_NAME="forgeo"
-DEFAULT_VERSION="0.7.3"
+DEFAULT_VERSION="0.8.0"
 MIN_PYTHON="3.11"
 PYPI_PACKAGE="forgeo-cli"
 PREFIX="${FORGEO_PREFIX:-${HOME:-}/.local}"

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.7.3"
+version = "0.8.0"
 description = "A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input."
 readme = "README.md"
 requires-python = ">=3.11"

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/src/forgeo/__init__.py

@@ -7,4 +7,4 @@ try:
 
     __version__ = _pkg_version("forgeo-cli")
 except PackageNotFoundError:  # standalone binary: no installed package metadata
-    __version__ = "0.7.3"
+    __version__ = "0.8.0"

{forgeo_cli-0.7.3 → forgeo_cli-0.8.0}/src/forgeo/backlog.py

@@ -5,19 +5,20 @@ from here (an optional ``run_at`` one-shot schedule overrides the oldest-first
 order). The tasks live in a single JSON document — ``{"tasks": [...]}`` — which
 is either a local file you can edit by hand (add, remove, or set a ``BLOCKED``
 task back to ``OPEN`` once you have provided the input it needed) or an HTTP
-endpoint owned by another application, see :mod:`forgeo.backlog_http`.
+endpoint owned by another application, see :mod:`forgeo.backlog_http`. A Jira
+provider implements the same task-level contract through issue operations.
 
-Everything above the storage layer is shared: :class:`BacklogStore` holds all
-the task manipulation and the asyncio lock that serializes writes, and leaves
-exactly two operations to its subclasses — load the document, store the
-document.
+Everything above the document-storage layer is shared: :class:`BacklogStore`
+holds the task manipulation and the asyncio lock that serializes writes. File
+and HTTP document providers implement load/store; issue providers override the
+task-level operations that cannot be represented as a whole-document write.
 
 A file backlog is the single source of truth, so it is guarded against bad
 writes: before every agent run (and on daemon startup) a rotating snapshot is
 written next to it (``backlog.json.bak``, ``backlog.json.bak.1``, ...) and a
 read that finds a corrupt store restores the newest valid snapshot in place
-instead of silently starting from an empty one. A URL backlog is owned by the
-remote application, which keeps its own history, so it is never snapshotted.
+instead of silently starting from an empty one. A remote backlog is owned by
+the provider, which keeps its own history, so it is never snapshotted.
 """
 
 from __future__ import annotations
@@ -59,6 +60,41 @@ EDITABLE_TASK_FIELDS = frozenset(
 )
 
 
+def validate_task_updates(updates: dict[str, Any]) -> None:
+    """Validate fields accepted by the task-editing API.
+
+    Providers use the same validation before translating updates into their
+    native API. Keeping it here prevents a remote provider from accepting a
+    task shape that a local backlog would reject.
+    """
+    unknown = set(updates) - EDITABLE_TASK_FIELDS
+    if unknown:
+        raise ValueError(f"unknown task field(s): {', '.join(sorted(unknown))}")
+    for field in ("title", "description"):
+        if field in updates and not isinstance(updates[field], str):
+            raise ValueError(f"{field} must be a string")
+    if "title" in updates and not updates["title"].strip():
+        raise ValueError("title must be a non-blank string")
+    if "description" in updates and not updates["description"].strip():
+        raise ValueError("description must be a non-blank string")
+    for field in ("acceptance_criteria", "dependencies", "files_to_modify"):
+        if field in updates and (
+            not isinstance(updates[field], list)
+            or not all(isinstance(item, str) for item in updates[field])
+        ):
+            raise ValueError(f"{field} must be a list of strings")
+    if "retries_left" in updates and updates["retries_left"] is not None and (
+        not isinstance(updates["retries_left"], int)
+        or isinstance(updates["retries_left"], bool)
+        or updates["retries_left"] < 0
+    ):
+        raise ValueError("retries_left must be a non-negative integer or null")
+    if "run_at" in updates and updates["run_at"] is not None and not isinstance(
+        updates["run_at"], str
+    ):
+        raise ValueError("run_at must be an ISO-8601 datetime string or null")
+
+
 def _join_output_logs(result: ExecutionResult, cap: int | None = None) -> str | None:
     """The agent's output as one newline-joined string, ``None`` when empty.
 
@@ -229,9 +265,10 @@ def normalize_store(data: Any) -> dict[str, Any]:
 class BacklogStore(ABC):
     """A backlog of tasks, independent of where the document is kept.
 
-    Subclasses implement :meth:`_read` and :meth:`_write`; everything else —
-    the task transitions, their validation, and the lock that serializes
-    concurrent mutations within one process — lives here.
+    Document subclasses implement :meth:`_read` and :meth:`_write`; an issue
+    provider may override task-level methods when its native API has no
+    whole-document mutation. The shared validation and local lock still live
+    here.
     """
 
     def __init__(self, *, output_cap: int | None = None) -> None:
@@ -255,6 +292,38 @@ class BacklogStore(ABC):
         store = await self._read()
         return [self._to_task(entry) for entry in store["tasks"]]
 
+    async def claim_task(self, task: Task) -> Task | None:
+        """Claim ``task`` immediately before an agent starts working on it.
+
+        A local document is protected by Forgeo's per-instance run lock, so a
+        claim only needs to re-check that the task is still ``OPEN``. Remote
+        providers override this with an atomic or workflow-backed claim (for
+        example, a Jira transition to ``In Progress``). Returning ``None``
+        means another worker won the race and the caller must not run the
+        agent or start a refactoring pass for this selection.
+        """
+        async with self._lock:
+            store = await self._read()
+            entry = self._entry_by_id(store, task.id)
+            if entry is None:
+                return None
+            current = self._to_task(entry)
+            if current.status is not TaskStatus.OPEN:
+                return None
+            return current
+
+    async def recover_claims(self) -> None:
+        """Recover stale remote claims before a new cycle starts.
+
+        File and document backends have no claim state to recover. Providers
+        with an external workflow may override this to release claims left by
+        a crashed process after their configured lease expires.
+        """
+
+    async def validate_connection(self) -> None:
+        """Verify that this provider can be read without mutating it."""
+        await self.list_tasks()
+
     async def snapshot(self) -> None:
         """Take a rollback copy of the backlog before it is written to.
 
@@ -430,34 +499,7 @@ class BacklogStore(ABC):
         """
         if not isinstance(updates, dict):
             raise TypeError("updates must be a dict of task fields")
-        unknown = set(updates) - EDITABLE_TASK_FIELDS
-        if unknown:
-            raise ValueError(
-                f"unknown task field(s): {', '.join(sorted(unknown))}"
-            )
-        for field in ("title", "description"):
-            if field in updates and not isinstance(updates[field], str):
-                raise ValueError(f"{field} must be a string")
-        if "title" in updates and not updates["title"].strip():
-            raise ValueError("title must be a non-blank string")
-        if "description" in updates and not updates["description"].strip():
-            raise ValueError("description must be a non-blank string")
-        for field in ("acceptance_criteria", "dependencies", "files_to_modify"):
-            if field in updates and (
-                not isinstance(updates[field], list)
-                or not all(isinstance(item, str) for item in updates[field])
-            ):
-                raise ValueError(f"{field} must be a list of strings")
-        if "retries_left" in updates and updates["retries_left"] is not None and (
-            not isinstance(updates["retries_left"], int)
-            or isinstance(updates["retries_left"], bool)
-            or updates["retries_left"] < 0
-        ):
-            raise ValueError("retries_left must be a non-negative integer or null")
-        if "run_at" in updates and updates["run_at"] is not None and not isinstance(
-            updates["run_at"], str
-        ):
-            raise ValueError("run_at must be an ISO-8601 datetime string or null")
+        validate_task_updates(updates)
 
         async with self._lock:
             store = await self._read()
@@ -659,7 +701,12 @@ class JSONBacklog(BacklogStore):
 
 
 def open_backlog(config: ForgeoConfig) -> BacklogStore:
-    """The backlog store ``config`` points at: a JSON file or an HTTP endpoint."""
+    """The task provider selected by ``config``."""
+    if config.backlog_is_jira:
+        from forgeo.backlog_jira import JiraBacklog
+
+        assert config.jira is not None
+        return JiraBacklog(str(config.backlog), config.jira, output_cap=config.agent_response_lines)
     if config.backlog_is_url:
         # Imported here: the HTTP backend builds on BacklogStore, so importing
         # it at module level would close an import cycle.