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

{forgeo_cli-0.7.2 → forgeo_cli-0.8.0}/.gitignore

@@ -29,6 +29,7 @@ dist/
 # AI assistant context
 AGENTS.md
 CONTEXT.md
+CLAUDE.md
 
 # Local deploy script (server-specific paths)
-scripts/deploy-docs.sh
+scripts/deploy-docs.sh

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

@@ -7,6 +7,29 @@ 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
+
+- The agent's stdout/stderr is now persisted on the task as `agent_response`
+  when a task transitions (BLOCKED/FAILED/COMPLETED), shown in the web
+  console's task modal. A transition that carries no output never wipes a
+  previously stored response.
+- `agent_response_lines` config key: how many agent output lines the task's
+  `agent_response` keeps on a status transition. Unbounded by default; `0`
+  disables persisting agent output on the task.
+
 ## [0.7.2] - 2026-08-18
 
 ### Added
@@ -337,7 +360,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.2...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
 [0.7.0]: https://github.com/lucaGazzola/forgeo/compare/v0.6.0...v0.7.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.7.2
+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.2 → 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.2 → 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
 {
@@ -43,6 +43,7 @@ Each entry in `tasks` is a task object:
 | <span style="white-space: nowrap">`blocker_reason`</span> | list[string] | `[]` | Engine-managed: the agent's explanation (its questions, falling back to captured output) when the task becomes `BLOCKED`. Cleared on reopen; not editable via `PATCH`. |
 | <span style="white-space: nowrap">`blocked_count`</span> | integer | `0` | Engine-managed: how many times the task has transitioned into `BLOCKED`. Kept as history when the task is reopened, so you can see a task that keeps blocking needs splitting or rewriting rather than a blind retry. Not editable via `PATCH`. |
 | <span style="white-space: nowrap">`failure_reason`</span> | list[string] | `[]` | Engine-managed: the agent's error when the task becomes `FAILED` (e.g. a timeout message or a non-zero exit code). Shown in the web console's task modal so you can see why a task failed without opening the logs. Cleared when the task leaves the `FAILED` state; not editable via `PATCH`. |
+| <span style="white-space: nowrap">`agent_response`</span> | string / `null` | `null` | Engine-managed: the agent's last stdout/stderr, stripped of its stream prefixes and persisted on the task's status transitions (bounded by `agent_response_lines` when set). Shown in the web console's task modal; not editable via `PATCH`. |
 | <span style="white-space: nowrap">`retries_left`</span> | integer / `null` | `null` | Per-task override of the automatic-retry budget (`failed_retry_max` in the config): how many times this task may be retried after a failure. `null` falls back to the config; `0` disables retries for this task. Editable via `PATCH`. |
 | <span style="white-space: nowrap">`retry_count`</span> | integer | `0` | Engine-managed: how many times this task has already been retried. Shown in `runs.jsonl` and the web console; reset when a human reopens a `FAILED` task. Not editable via `PATCH`. |
 | <span style="white-space: nowrap">`failed_wait_cycles`</span> | integer | `0` | Engine-managed: how many cycles this task has been `FAILED` awaiting a retry (backed off by `failed_retry_wait_cycles`). Reset when the task leaves `FAILED`. Not editable via `PATCH`. |
@@ -286,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.
 
@@ -348,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.2 → 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.2 → 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). |
@@ -40,6 +42,7 @@ paths), so `forgeo restart` is still used for those.
 | <span style="white-space: nowrap">`log_file`</span> | `forgeo.log` | Where the daemon writes its log. |
 | <span style="white-space: nowrap">`run_history_keep`</span> | `2000` | How many finished runs `runs.jsonl` keeps (oldest trimmed atomically on append). `0` disables retention (file grows forever). |
 | <span style="white-space: nowrap">`run_output_lines`</span> | `200` | How many agent output lines each run record keeps in `runs.jsonl` (the bounded tail of the agent's stdout/stderr). `0` disables persisting agent output. |
+| <span style="white-space: nowrap">`agent_response_lines`</span> | — (unbounded) | How many agent output lines the task's `agent_response` keeps on a status transition (the bounded tail of the agent's stdout/stderr, shown in the task modal / available to a backlog consumer). Omit = unbounded; `0` disables persisting agent output on the task. |
 | <span style="white-space: nowrap">`failed_retry_max`</span> | `0` | How many times a `FAILED` task is retried automatically. `0` (default) = a `FAILED` task stays `FAILED` until a human reopens it, exactly as before. A task may override this budget per-task with `retries_left`. |
 | <span style="white-space: nowrap">`failed_retry_wait_cycles`</span> | `1` | How many cycles a retry-eligible `FAILED` task waits (backoff) before it is moved back to `OPEN`. |
 | <span style="white-space: nowrap">`no_changes_retry_max`</span> | `0` | How many times a task whose agent exits `0` without producing any code changes is re-run immediately, in the same cycle, before the task is marked `BLOCKED` for human review. `0` (default) = a silent no-change SUCCESS is marked `BLOCKED` on the first attempt. |
@@ -66,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`
@@ -226,6 +300,18 @@ Set `0` to stop persisting agent output entirely (run records stay small and
 the History tab shows nothing for them). Old run records written before this
 field existed simply have no output.
 
+### `agent_response_lines`
+
+Alongside the per-run record above, Forgeo persists the agent's output on the
+task itself (`agent_response`, shown in the task modal and available to a
+backlog consumer served over HTTP). Unlike `run_output_lines` it is **unbounded
+by default**: the whole stdout/stderr is stored, overwritten on each status
+transition (a transition that carries no output never wipes a previously
+stored response).
+
+Set a positive value to keep only the last that many lines; set `0` to stop
+persisting agent output on the task entirely.
+
 ### `failed_retry_max` / `failed_retry_wait_cycles`
 
 Some failures are transient — a network blip, a flaky test, a dependency
@@ -372,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.2 → 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.2 → 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.2 → 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`
 
@@ -177,6 +176,7 @@ curl http://127.0.0.1:8790/api/instances/my-repo/tasks
     "blocker_reason": [],
     "blocked_count": 0,
     "failure_reason": [],
+    "agent_response": null,
     "created_at": "2026-07-31T10:00:00Z",
     "updated_at": "2026-07-31T10:00:00Z",
     "run_at": null,
@@ -188,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}`
 
@@ -258,6 +258,7 @@ curl -X POST http://127.0.0.1:8790/api/instances/my-repo/tasks \
   "blocker_reason": [],
   "blocked_count": 0,
   "failure_reason": [],
+  "agent_response": null,
   "created_at": "2026-08-01T12:00:00Z",
   "updated_at": "2026-08-01T12:00:00Z",
   "run_at": "2026-08-20T12:30:00Z",
@@ -300,6 +301,7 @@ curl -X POST http://127.0.0.1:8790/api/instances/my-repo/tasks/TASK-001/reopen
   "blocker_reason": [],
   "blocked_count": 1,
   "failure_reason": [],
+  "agent_response": null,
   "created_at": "2026-07-31T10:00:00Z",
   "updated_at": "2026-08-01T12:00:00Z",
   "dependencies": [],
@@ -329,8 +331,9 @@ budget override; a non-negative integer or `null`), and `run_at` (the
 optional one-shot schedule; an ISO-8601 datetime string or `null` to clear
 it). The request body is a JSON object; omitted fields are left unchanged
 and `id`, `status`, `blocker_reason`, `blocked_count`, `failure_reason`,
-`retry_count`, `failed_wait_cycles`, and `created_at` are always preserved
-(they are engine-managed — `PATCH` rejects them like it rejects `status`).
+`agent_response`, `retry_count`, `failed_wait_cycles`, and `created_at` are
+always preserved (they are engine-managed — `PATCH` rejects them like it
+rejects `status`).
 `agent_command` may be a string, an array, or `null` (clear the per-task
 override); `agent_timeout_seconds` may be a positive number or `null`.
 `updated_at` is bumped to the current time.
@@ -350,6 +353,7 @@ curl -X PATCH http://127.0.0.1:8790/api/instances/my-repo/tasks/TASK-001 \
   "blocker_reason": [],
   "blocked_count": 0,
   "failure_reason": [],
+  "agent_response": null,
   "created_at": "2026-07-31T10:00:00Z",
   "updated_at": "2026-08-01T12:00:00Z",
   "dependencies": [],
@@ -364,8 +368,8 @@ Errors:
 
 - `400` with `{"error": "..."}` — unparseable or non-object body, an empty
   body, an unknown field (e.g. `status`, `blocker_reason`, `blocked_count`,
-  `failure_reason`), or an invalid value (blank `title`, wrong field types, a
-  non-positive `agent_timeout_seconds`).
+  `failure_reason`, `agent_response`), or an invalid value (blank `title`,
+  wrong field types, a non-positive `agent_timeout_seconds`).
 - `404` with `{"error": "not found"}` — the task id does not exist in that
   instance's backlog.
 - `404` with `{"error": "unknown instance"}` — the instance is not

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

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.7.2"
+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.2 → 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.2"
+    __version__ = "0.8.0"