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

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

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-08-23
+
+### Added
+
+- GitHub Issues and GitLab Issues task providers. Set `backlog_provider: github`
+  or `gitlab` and point `backlog:` at the API base URL
+  (`https://api.github.com` or `https://github.example.com/api/v3` for
+  Enterprise; `https://gitlab.com` or a self-hosted root for GitLab). Issue
+  numbers/`iid`s become Forgeo task ids, `open`/`opened` vs `closed` maps to
+  `OPEN`/`COMPLETED`, and `forgeo-running`/`forgeo-blocked`/`forgeo-failed`
+  labels (configurable via `label_prefix`) represent the remaining states.
+  Engine state — blocker and failure reasons, retry counters, claim time,
+  dependencies, and bounded agent output — is stored in a hidden
+  `<!-- forgeo: {...} -->` block inside the issue body/description, so the
+  visible text stays human-readable and no custom fields or issue properties
+  are required.
+- `github` and `gitlab` config blocks: `repo` (`owner/repo` or project path/id),
+  `token_env` (PAT from an environment variable, never stored in the file),
+  `label_prefix`/`property_key`, pagination, timeouts, stale-claim recovery
+  via `claim_timeout_seconds`, and optional workflow/field mappings mirroring
+  the Jira provider.
+- Shared issue-provider helpers extracted to `backlog_issue_base` and a new
+  `DocumentBacklogStore` / `IssueBacklogBase` split in `backlog.py`,
+  unifying claim, label, and engine-state handling across Jira, GitHub, and
+  GitLab. `forgeo validate` now checks any remote backlog with a
+  provider-specific message, and `config/forgeo.yaml`, the README, and the
+  backlog/configuration docs list and document all five providers
+  (`file`, `http`, `jira`, `github`, `gitlab`).
+
+## [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 +389,9 @@ 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.9.0...HEAD
+[0.9.0]: https://github.com/lucaGazzola/forgeo/compare/v0.8.0...v0.9.0
+[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.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.7.3
+Version: 0.9.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` / `github` / `gitlab` and set `backlog` to the provider base URL
+# (see the backlog documentation for Jira/GitHub/GitLab).
+
 # 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,21 @@ 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
-`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.
+Everything is stored in plain files: the local backlog, `forgeo.log`, and
+`BLOCKER.md` whenever a decision is pending. Backlog providers (see
+[Backlog format](docs/backlog.md)):
+
+- [JSON file](docs/backlog.md#a-json-file-backlog)
+- [HTTP endpoint](docs/backlog.md#a-backlog-over-http)
+- [Jira](docs/backlog.md#a-jira-backlog)
+- [GitHub](docs/backlog.md#a-github-backlog)
+- [GitLab](docs/backlog.md#a-gitlab-backlog)
+
+File and HTTP backlogs exchange the complete task document; Jira/GitHub/GitLab issues are read and transitioned
+individually with workflow state and engine metadata stored on the issue. 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.9.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` / `github` / `gitlab` and set `backlog` to the provider base URL
+# (see the backlog documentation for Jira/GitHub/GitLab).
+
 # 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,21 @@ 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
-`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.
+Everything is stored in plain files: the local backlog, `forgeo.log`, and
+`BLOCKER.md` whenever a decision is pending. Backlog providers (see
+[Backlog format](docs/backlog.md)):
+
+- [JSON file](docs/backlog.md#a-json-file-backlog)
+- [HTTP endpoint](docs/backlog.md#a-backlog-over-http)
+- [Jira](docs/backlog.md#a-jira-backlog)
+- [GitHub](docs/backlog.md#a-github-backlog)
+- [GitLab](docs/backlog.md#a-gitlab-backlog)
+
+File and HTTP backlogs exchange the complete task document; Jira/GitHub/GitLab issues are read and transitioned
+individually with workflow state and engine metadata stored on the issue. 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.9.0}/docs/backlog.md

@@ -1,12 +1,24 @@
 # Backlog format
 
-The backlog is a **plain JSON document**. By default it is a file you edit by
-hand, living wherever `backlog:` points in [forgeo.yaml](configuration.md) —
-`backlog.json` at the project root, or `.forgeo/backlog.json` when generated by
-`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.
+- [JSON file](#a-json-file-backlog)
+- [HTTP endpoint](#a-backlog-over-http)
+- [Jira](#a-jira-backlog)
+- [GitHub](#a-github-backlog)
+- [GitLab](#a-gitlab-backlog)
+
+The backlog is a **plain JSON document** — a list of tasks Forgeo works through
+one by one.
+
+## A JSON file backlog
+
+By default the backlog is a file you edit by hand, living wherever `backlog:`
+points in [forgeo.yaml](configuration.md) — `backlog.json` at the project root,
+or `.forgeo/backlog.json` when generated by `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, or it
+can be sourced directly from [Jira](#a-jira-backlog),
+[GitHub](#a-github-backlog) or [GitLab](#a-gitlab-backlog).
 
 ```json
 {
@@ -287,7 +299,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 +361,150 @@ 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.
+
+## A GitHub backlog
+
+Set `backlog_provider: github` and point `backlog:` at the GitHub API base URL:
+
+```yaml
+backlog_provider: github
+backlog: https://api.github.com
+
+github:
+  repo: owner/repo
+  token_env: GITHUB_TOKEN
+  label_prefix: forgeo
+```
+
+Use `https://api.github.com` for github.com or `https://github.example.com/api/v3` for Enterprise.
+
+### Mapping and lifecycle
+
+- GitHub issue numbers are Forgeo task ids.
+- `title`, `body` (visible part), `created_at` and `updated_at` map to task fields.
+- `state` `open` maps to `OPEN`; `closed` maps to `COMPLETED`.
+- Labels `forgeo-running`, `forgeo-blocked`, `forgeo-failed` (prefix configurable via `label_prefix`) represent running, blocked, and failed tasks. An open issue carrying `forgeo-running` is considered claimed and filtered from picking.
+- Closing an issue completes its task; reopening it moves the task back to `OPEN`.
+
+Forgeo stores blocker reasons, failure reasons, retry counters, claim time, dependencies, and bounded agent output in a hidden JSON block inside the issue body: `<!-- forgeo: {...} -->`. The visible body remains human-readable; the hidden block is stripped on read and merged on write. No GitHub issue property or custom field is required. Set `github.property_key` only for symmetry; the marker key is `forgeo` by default.
+
+Dependencies are persisted via the hidden block's `dependencies` list; no GitHub issue links are required.
+
+### Authentication
+
+GitHub credentials are never stored in `forgeo.yaml`:
+
+- `token_env` names the environment variable holding a personal-access token (classic or fine-grained). The token is sent as `Authorization: Bearer <token>`.
+
+### Runtime behavior
+
+The daemon lists GitHub issues with paginated `GET /repos/{owner}/{repo}/issues?state=all`. A task is claimed by adding the `forgeo-running` label and persisting `claimed_at` in the hidden block. If a process dies while holding a claim, a later cycle releases claims older than `claim_timeout_seconds` and removes the running label. An unavailable GitHub endpoint fails the cycle.
+
+## A GitLab backlog
+
+Set `backlog_provider: gitlab` and point `backlog:` at the GitLab base URL:
+
+```yaml
+backlog_provider: gitlab
+backlog: https://gitlab.example.com
+
+gitlab:
+  repo: group/project   # or numeric project id
+  token_env: GITLAB_TOKEN
+  label_prefix: forgeo
+```
+
+GitLab base URL is the instance root (e.g. `https://gitlab.com`); the client appends `/api/v4`.
+
+### Mapping and lifecycle
+
+- GitLab issue `iid`s are Forgeo task ids.
+- `title`, `description` (visible part), `created_at` and `updated_at` map to task fields.
+- `state` `opened` maps to `OPEN`; `closed` maps to `COMPLETED`.
+- Labels `forgeo-running`, `forgeo-blocked`, `forgeo-failed` represent running, blocked, and failed tasks, like GitHub. An `opened` issue with `forgeo-running` is filtered as claimed.
+- Closing/reopening via `state_event` transitions the task to `COMPLETED`/`OPEN`.
+
+Forgeo stores engine state the same way as GitHub: a hidden `<!-- forgeo: {...} -->` block inside `description`. Dependencies and other task attributes are kept there; no GitLab custom fields are required.
+
+### Authentication
+
+- `token_env` names the environment variable holding a personal-access token. Sent as `PRIVATE-TOKEN` and `Authorization: Bearer`.
+
+### Runtime behavior
+
+Paginated `GET /api/v4/projects/:id/issues?state=all`. Claiming adds `forgeo-running` and `claimed_at`; stale claims older than `claim_timeout_seconds` are released. An unavailable GitLab endpoint fails the cycle.

{forgeo_cli-0.7.3 → forgeo_cli-0.9.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.9.0}/docs/configuration.md

@@ -22,9 +22,13 @@ 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_auth`</span> | — | OAuth2 client credentials for a backlog URL that requires them (see [below](#backlog_auth)). |
+| <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 base URL for `jira`/`github`/`gitlab` providers. |
+| <span style="white-space: nowrap">`backlog_provider`</span> | `auto` | `auto` infers file/HTTP from `backlog`, or `jira`/`github`/`gitlab` when the corresponding block is present; explicitly choose `file`, `http`, `jira`, `github`, or `gitlab`. |
+| <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)). Only for `http` provider. |
+| <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">`github`</span> | — | GitHub REST settings. Required when `backlog_provider: github`. |
+| <span style="white-space: nowrap">`gitlab`</span> | — | GitLab REST settings. Required when `backlog_provider: gitlab`. |
 | <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 +71,126 @@ 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. |
+
+### GitHub backlog
+
+Forgeo can read and update GitHub issues directly. Set `backlog_provider: github` and make `backlog` the GitHub API base URL. Issue numbers become task ids. Labels and a hidden JSON block in the issue body hold Forgeo's engine state.
+
+```yaml
+backlog_provider: github
+backlog: https://api.github.com
+github:
+  repo: owner/repo
+  token_env: GITHUB_TOKEN
+  label_prefix: forgeo
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `github.repo` | — | Required owner/repo. |
+| `github.auth` | — | Required PAT env var `token_env`. |
+| `github.label_prefix` | `forgeo` | Prefix for running/blocked/failed labels. |
+| `github.property_key` | `forgeo` | Marker key for hidden body block (symmetry). |
+| `github.page_size` | `30` | Issues per page. |
+| `github.max_issues` | `1000` | Max issues read. |
+| `github.timeout_seconds` | `30` | HTTP timeout. |
+| `github.claim_timeout_seconds` | `86400` | Stale claim timeout. |
+| `github.workflow` | defaults | State/label mapping. |
+| `github.fields` | — | Optional field mappings. |
+
+### GitLab backlog
+
+```yaml
+backlog_provider: gitlab
+backlog: https://gitlab.example.com
+gitlab:
+  repo: group/project
+  token_env: GITLAB_TOKEN
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `gitlab.repo` | — | Required project path or numeric id. |
+| `gitlab.auth` | — | Required PAT env var `token_env`. |
+| `gitlab.label_prefix` | `forgeo` | Prefix for labels. |
+| `gitlab.property_key` | `forgeo` | Marker key. |
+| `gitlab.page_size` | `30` | Issues per page. |
+| `gitlab.max_issues` | `1000` | Max issues. |
+| `gitlab.timeout_seconds` | `30` | HTTP timeout. |
+| `gitlab.claim_timeout_seconds` | `86400` | Stale claim timeout. |
+| `gitlab.workflow` | defaults | State mapping. |
+| `gitlab.fields` | — | Optional field mappings. |
+
 ## Key details
 
 ### `backlog_auth`
@@ -385,7 +509,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.9.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.9.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.9.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.9.0}/install.sh

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