forgeo-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{forgeo_cli-0.5.0 → forgeo_cli-0.7.0}/CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-08-16
+
+### Added
+
+- `task_context` config key: a path to a file (e.g. `CONTEXT.md`) whose
+  contents are prepended to every agent instruction — tasks and refactoring
+  runs alike — before the task description. The agent gets the high-level
+  project overview instead of only the isolated task; the file is re-read on
+  every run, so the agent's own updates are picked up on the next cycle. A
+  missing or unreadable file never fails a cycle: it is logged, `forgeo
+  validate` reports it as a warning, and the run proceeds with the bare
+  instruction.
+- The default agent prompt (used by `forgeo init`) now tells the agent to
+  read `AGENTS.md` (and `CONTEXT.md` if present) at the start of the session
+  and to keep them updated when a change materially affects the project
+  overview.
+
+- `forgeo run --task <id>` runs exactly one specific `OPEN` task by id and
+  exits, instead of letting `forgeo once` pick the oldest one — for triage:
+  rerun a `FAILED` task (after reopening it) or try a risky task now. It
+  shares the same per-forgeo lock as the daemon and `forgeo once`, so it
+  never overlaps them; it refuses with a clear error when the task does not
+  exist or is not `OPEN`, and while another daemon/`once`/`run` holds the
+  lock.
+
+## [0.6.0] - 2026-08-14
+
+### Added
+
+- The backlog can now live in another application instead of a file: set
+  `backlog:` to an `http(s)` URL and Forgeo reads the whole document with
+  `GET` on every read and writes it back with `POST` on every change, using
+  the same JSON shape as `backlog.json`. The endpoint replaces its task list
+  with the body it receives. A request that fails (network error, 5xx,
+  malformed body) fails the cycle and is retried on the next interval — it is
+  never read as an empty backlog, which would start a refactoring pass and let
+  the next `POST` overwrite the remote task list with nothing.
+
+- `backlog_auth`: OAuth2 client-credentials access for a backlog URL behind an
+  identity provider such as Keycloak. Forgeo obtains an access token for a
+  confidential client (a service account, not a human login) and sends it as a
+  bearer on every backlog request; tokens are cached in memory, renewed before
+  they expire, and refreshed once with a retry when the endpoint answers 401 or
+  403. The client secret is never a config value: `client_secret_env` names the
+  environment variable holding it, so it stays out of `forgeo.yaml`.
+
+- `state_dir`: where Forgeo's own runtime files go (`backlog.lock`,
+  `backlog.run`, `backlog.state.json`, `backlog.update.json`, `runs.jsonl`).
+  It only matters with a backlog URL, where there is no backlog file for them
+  to sit beside; it then defaults to the directory holding `forgeo.yaml`. With
+  a backlog file those paths are unchanged.
+
+- `forgeo validate` now checks a backlog URL by fetching it once (a plain
+  `GET`, with `backlog_auth` credentials when configured), so an unreachable
+  endpoint or a rejected token is reported by the dry run instead of by the
+  first cycle. A file backlog is still read from disk, and nothing is written
+  either way.
+
 ## [0.5.0] - 2026-08-14
 
 ### Added
@@ -250,7 +308,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.5.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/lucaGazzola/forgeo/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/lucaGazzola/forgeo/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/lucaGazzola/forgeo/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/lucaGazzola/forgeo/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/lucaGazzola/forgeo/compare/v0.2.0...v0.3.0

{forgeo_cli-0.5.0 → forgeo_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.5.0
+Version: 0.7.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
@@ -83,50 +83,93 @@ agent CLI.
 
 The full walkthrough is in [Getting started](docs/getting-started.md).
 
-```bash
-# 1. Install (any one of these)
+### 1. Install the CLI
+
+Pick any one installer (no root needed; re-running it upgrades Forgeo).
 
-# Homebrew (macOS / Linux)
+```bash
+# Homebrew (macOS / Linux): prebuilt binary, no Python required
 brew install lucaGazzola/forgeo/forgeo
 
-# or: the one-liner (prebuilt binary, no Python required)
+# One-liner (Linux / macOS / Windows): prebuilt binary, falls back to pip
 curl -fsSL https://forgeo.org/install.sh | bash
 
-# or: pipx
+# pip (Python 3.11+)
 pipx install forgeo-cli
+```
 
-# 2. Create your Forgeo (guided wizard, run from your project root)
-forgeo init
+### 2. Create your Forgeo
 
-# 3. Start Forgeo (detached in the background; exits immediately)
-forgeo start   # every interval_minutes, implement the oldest OPEN task (dependencies first)
-forgeo stop    # stop the daemon again
+```bash
+forgeo init
 ```
 
-`forgeo init` writes `forgeo.yaml` and a `.forgeo/` folder for the backlog
-and logs. Fill the backlog with plain JSON tasks (see
-[Backlog format](docs/backlog.md)) or add them from the web console while
-it runs, Forgeo does the rest. Open the dashboard with `forgeo web` (default <http://0.0.0.0:8790>), or keep it always-on with `forgeo web -d` (stop it with `forgeo web stop`, check it with `forgeo web status`):
+Guided wizard, run from your project root. Writes `forgeo.yaml` (the
+config) and a `.forgeo/` folder for the backlog, logs and blocker files.
+
+The base flow is then three steps: fill the backlog, check the
+configuration, start the daemon.
+
+### 3. Fill the backlog
+
+```bash
+# Either: edit the backlog file by hand — a plain JSON task list (see
+# Backlog format), created on first use:
+#   .forgeo/backlog.json
+
+# 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`
+```
 
 ![Forgeo web console](docs/img/console.png)
 
-By default the dashboard is open to anyone who can reach the port. On a
-shared host, protect it with bearer-token auth: `forgeo web --token`
-generates a token (printed once, saved to `~/.config/forgeo/web.toml`) and
-requires `Authorization: Bearer <token>` on every `/api/*` route — see
-[Web console & HTTP API](docs/web-console-api.md).
+### 4. Check the configuration
+
+```bash
+forgeo validate
+```
+
+Read-only dry run before the first start: verifies `forgeo.yaml`, the git
+repo, branch and remote, that the backlog parses (fetching it once when it
+is an HTTP endpoint), the agent command, and the lock state. Never invokes
+the agent and writes nothing.
+
+### 5. Start the daemon
+
+```bash
+forgeo start
+```
+
+Starts the daemon **detached in the background** and exits. Every
+`interval_minutes` it runs one cycle: pick the oldest `OPEN` task whose
+dependencies are all `COMPLETED`, run your coding agent on it, commit the
+result. When the backlog is empty, the same agent runs a refactoring pass
+over the codebase instead.
+
+### Day-to-day commands
+
+```bash
+forgeo status    # Config, backlog counts, next runnable task, daemon running?, last outcome
+forgeo once      # Run exactly one cycle in the foreground, no daemon left behind
+forgeo run --task SELF-012  # Run one specific OPEN task now (triage)
+forgeo stop      # Stop the background daemon
+forgeo restart   # Stop and start again (re-reads forgeo.yaml after edits)
+forgeo web       # Dashboard: every instance's backlog, run history and logs
+```
+
+`forgeo web` defaults to an open dashboard on `http://0.0.0.0:8790`; on a
+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)).
 
-One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
-`forgeo validate` (read-only dry run before starting), `forgeo stop`,
-`forgeo restart`, every command is in the
-[CLI reference](docs/cli-reference.md).
+### Multiple repositories (instances)
 
-You can run several factories at once, one per repository, each config is
-fully independent (own backlog, logs, locks). Register each `forgeo.yaml`
-in the instance registry with `forgeo instance add NAME --config PATH`,
-manage any of them by name with `forgeo start/status/stop --name NAME`,
-list them all with `forgeo list`, and get one aggregate overview with the
-central dashboard, `forgeo web`.
+Run several factories at once, one per repository; each config is fully
+independent (own backlog, logs, locks). Register each `forgeo.yaml` with
+`forgeo instance add NAME --config PATH`, manage any of them by name with
+`forgeo start/status/stop --name NAME`, list them all with `forgeo list`,
+and get one aggregate overview with the central dashboard, `forgeo web`.
 
 ## Documentation
 
@@ -140,10 +183,13 @@ central dashboard, `forgeo web`.
 | 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 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.
+`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.
 
 ## Develop
 

forgeo_cli-0.7.0/README.md

@@ -0,0 +1,153 @@
+<div align="center">
+  <img src="docs/img/logo.png" alt="Forgeo logo" width="128">
+</div>
+
+<div align="center">
+  <img src="docs/img/title.svg" alt="Forgeo" width="128">
+</div>
+
+
+[![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Forgeo is a software factory for your coding-agent.**
+You're already working with an AI coding agent, prompting it task by task
+or giving it a goal. Forgeo organizes your work in a structured way with
+a backlog, and it decides what to work on next, runs your
+agent on it, and commits the result. Progress, pending decisions, and history
+are tracked in plain files you can inspect at any time, plus a web dashboard.
+Forgeo only interrupts you when a decision is genuinely yours to
+make, everything else happens autonomously. Transient failures (a network
+blip, a flaky test) are retried automatically when the retry policy is
+enabled, and only a task that keeps failing or genuinely needs a human
+decision ever reaches you.
+
+All you need is basic comfort with a terminal, a git repository, and any coding
+agent CLI.
+
+## Quickstart
+
+The full walkthrough is in [Getting started](docs/getting-started.md).
+
+### 1. Install the CLI
+
+Pick any one installer (no root needed; re-running it upgrades Forgeo).
+
+```bash
+# Homebrew (macOS / Linux): prebuilt binary, no Python required
+brew install lucaGazzola/forgeo/forgeo
+
+# One-liner (Linux / macOS / Windows): prebuilt binary, falls back to pip
+curl -fsSL https://forgeo.org/install.sh | bash
+
+# pip (Python 3.11+)
+pipx install forgeo-cli
+```
+
+### 2. Create your Forgeo
+
+```bash
+forgeo init
+```
+
+Guided wizard, run from your project root. Writes `forgeo.yaml` (the
+config) and a `.forgeo/` folder for the backlog, logs and blocker files.
+
+The base flow is then three steps: fill the backlog, check the
+configuration, start the daemon.
+
+### 3. Fill the backlog
+
+```bash
+# Either: edit the backlog file by hand — a plain JSON task list (see
+# Backlog format), created on first use:
+#   .forgeo/backlog.json
+
+# 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`
+```
+
+![Forgeo web console](docs/img/console.png)
+
+### 4. Check the configuration
+
+```bash
+forgeo validate
+```
+
+Read-only dry run before the first start: verifies `forgeo.yaml`, the git
+repo, branch and remote, that the backlog parses (fetching it once when it
+is an HTTP endpoint), the agent command, and the lock state. Never invokes
+the agent and writes nothing.
+
+### 5. Start the daemon
+
+```bash
+forgeo start
+```
+
+Starts the daemon **detached in the background** and exits. Every
+`interval_minutes` it runs one cycle: pick the oldest `OPEN` task whose
+dependencies are all `COMPLETED`, run your coding agent on it, commit the
+result. When the backlog is empty, the same agent runs a refactoring pass
+over the codebase instead.
+
+### Day-to-day commands
+
+```bash
+forgeo status    # Config, backlog counts, next runnable task, daemon running?, last outcome
+forgeo once      # Run exactly one cycle in the foreground, no daemon left behind
+forgeo run --task SELF-012  # Run one specific OPEN task now (triage)
+forgeo stop      # Stop the background daemon
+forgeo restart   # Stop and start again (re-reads forgeo.yaml after edits)
+forgeo web       # Dashboard: every instance's backlog, run history and logs
+```
+
+`forgeo web` defaults to an open dashboard on `http://0.0.0.0:8790`; on a
+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)).
+
+### Multiple repositories (instances)
+
+Run several factories at once, one per repository; each config is fully
+independent (own backlog, logs, locks). Register each `forgeo.yaml` with
+`forgeo instance add NAME --config PATH`, manage any of them by name with
+`forgeo start/status/stop --name NAME`, list them all with `forgeo list`,
+and get one aggregate overview with the central dashboard, `forgeo web`.
+
+## Documentation
+
+| Topic | Where |
+| --- | --- |
+| Install, init, first cycle | [Getting started](docs/getting-started.md) |
+| Every `forgeo.yaml` key | [Configuration](docs/configuration.md) |
+| Task schema and statuses | [Backlog format](docs/backlog.md) |
+| How the agent is invoked (env, exit codes, timeouts) | [Agent contract](docs/agent-contract.md) |
+| 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.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, quality
+gates (`pytest`, `ruff check`, `mypy src/forgeo`), and the pull-request
+process.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{forgeo_cli-0.5.0 → forgeo_cli-0.7.0}/docs/agent-contract.md

@@ -19,18 +19,28 @@ the process environment is augmented as follows:
 
 | Variable | Meaning |
 | --- | --- |
-| `FORGEO_TASK` | The full instruction for this run: title, blank line, description, and an "Acceptance criteria:" list when present. |
-| `FORGEO_REPO` | The absolute path of the repository. |
-| `FORGEO_BRANCH` | The branch everything is committed to (default `main`). |
-| *every `agent_env` key* | Any extra variables from `agent_env` in the config. |
-| *inherited environment* | The daemon's own environment. |
+| <span style="white-space: nowrap">`FORGEO_TASK`</span> | The full instruction for this run: the project context when `task_context` is configured, then title, blank line, description, and an "Acceptance criteria:" list when present. |
+| <span style="white-space: nowrap">`FORGEO_REPO`</span> | The absolute path of the repository. |
+| <span style="white-space: nowrap">`FORGEO_BRANCH`</span> | The branch everything is committed to (default `main`). |
+| <span style="white-space: nowrap">*every `agent_env` key*</span> | Any extra variables from `agent_env` in the config. |
+| <span style="white-space: nowrap">*inherited environment*</span> | The daemon's own environment. |
 
 `FORGEO_*` variables are set unconditionally and take precedence over both the
 inherited environment and `agent_env`.
 
+### The task is not the whole picture
+
+A task description is isolated by design: it describes one unit of work, not
+the project. When `task_context` is set (see
+[Configuration](configuration.md#task_context)), Forgeo prepends the contents
+of that file — the high-level project overview — to `FORGEO_TASK` before the
+task, under a `# Project context` heading, followed by the task under a
+`# Task` heading. The file is re-read on every run, so an agent's own updates
+to it are seen by the next cycle.
+
 For a refactoring run (empty backlog) the same contract applies: the refactor
-prompt arrives as `FORGEO_TASK` with the task id `REFACTOR` and title
-"Refactoring pass".
+prompt arrives as `FORGEO_TASK` (with the context prepended when configured),
+with the task id `REFACTOR` and title "Refactoring pass".
 
 ## Exit codes
 
@@ -38,10 +48,10 @@ The exit code decides the outcome of the run:
 
 | Exit code | Outcome | What happens |
 | --- | --- | --- |
-| `0` | **SUCCESS** | Everything is committed (`git add -A && git commit`) with the message `<title> (#<id>)`, pushed when a remote is set, and the task is marked `COMPLETED`. |
-| `no_changes_exit_code` (default `3`) | **SUCCESS, no changes** | The agent explicitly reports the task needs **no code change**: the task is marked `COMPLETED` without a commit (and the run record notes why). Only accepted when the working tree is clean. |
-| `blocked_exit_code` (default `2`) | **BLOCKED** | The agent needs a human decision. Partial work is committed as `<title> [partial]`, the agent's reason is persisted on the task (`blocker_reason`), optional Telegram and/or webhook notifications are sent, and the task is marked `BLOCKED`. `BLOCKER.md` is rendered from the backlog's `BLOCKED` tasks on the next cycle — real per-task reasons, never generic text — and disappears once the last one is resolved (reopen it from the web console). |
-| anything else | **ERROR** | Changes are discarded (`git reset --hard` + `git clean -fd`), the failure is logged, and the task is marked `FAILED`. |
+| <span style="white-space: nowrap">`0`</span> | **SUCCESS** | Everything is committed (`git add -A && git commit`) with the message `<title> (#<id>)`, pushed when a remote is set, and the task is marked `COMPLETED`. |
+| <span style="white-space: nowrap">`no_changes_exit_code` (default `3`)</span> | **SUCCESS, no changes** | The agent explicitly reports the task needs **no code change**: the task is marked `COMPLETED` without a commit (and the run record notes why). Only accepted when the working tree is clean. |
+| <span style="white-space: nowrap">`blocked_exit_code` (default `2`)</span> | **BLOCKED** | The agent needs a human decision. Partial work is committed as `<title> [partial]`, the agent's reason is persisted on the task (`blocker_reason`), optional Telegram and/or webhook notifications are sent, and the task is marked `BLOCKED`. `BLOCKER.md` is rendered from the backlog's `BLOCKED` tasks on the next cycle — real per-task reasons, never generic text — and disappears once the last one is resolved (reopen it from the web console). |
+| <span style="white-space: nowrap">anything else</span> | **ERROR** | Changes are discarded (`git reset --hard` + `git clean -fd`), the failure is logged, and the task is marked `FAILED`. |
 
 The blocked exit code is configurable via `blocked_exit_code` in
 [forgeo.yaml](configuration.md), and the no-change exit code via
@@ -125,6 +135,8 @@ agent_command: >
   Make the code changes requested below and nothing else. Do NOT run
   git commit, git push, or git add -A — Forgeo commits your work.
   Verify with the test suite where applicable.
+  Read AGENTS.md (and CONTEXT.md if present) at the start of the session;
+  if your change materially affects the project overview, keep them updated.
   $FORGEO_TASK"
 ```
 

{forgeo_cli-0.5.0 → forgeo_cli-0.7.0}/docs/backlog.md

@@ -1,10 +1,12 @@
 # Backlog format
 
-The backlog is a **plain JSON file** you edit by hand. It lives wherever
-`backlog:` points in [forgeo.yaml](configuration.md) — by default
-`backlog.json` at the project root, and `.forgeo/backlog.json` when generated
-by `forgeo init`. Keep it outside the repository if you can so the agent never
-touches it.
+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
 {
@@ -78,10 +80,10 @@ cheap/fast model and hard ones to a frontier model:
 
 | Status | Meaning |
 | --- | --- |
-| `OPEN` | To be picked by Forgeo. |
-| `BLOCKED` | Waiting on a human decision; Forgeo pauses while any task is blocked. |
-| `COMPLETED` | The agent finished and the work was committed (and pushed). |
-| `FAILED` | The agent errored; changes were discarded and the reason is recorded in `failure_reason`. |
+| <span style="white-space: nowrap">`OPEN`</span> | To be picked by Forgeo. |
+| <span style="white-space: nowrap">`BLOCKED`</span> | Waiting on a human decision; Forgeo pauses while any task is blocked. |
+| <span style="white-space: nowrap">`COMPLETED`</span> | The agent finished and the work was committed (and pushed). |
+| <span style="white-space: nowrap">`FAILED`</span> | The agent errored; changes were discarded and the reason is recorded in `failure_reason`. |
 
 ## Retrying a failed task
 
@@ -258,8 +260,9 @@ The backlog is the single source of truth, so it is guarded on both ends:
 
 - a missing file is treated as an empty backlog (and is created on first
   write);
-- a corrupt file is renamed to `backlog.json.corrupt-<timestamp>` and the
-  forgeo starts from an empty store — nothing is silently discarded;
+- a corrupt file is renamed to `backlog.json.corrupt-<timestamp>` and replaced
+  by the newest valid snapshot, or by an empty store when there is none —
+  nothing is silently discarded;
 - an unparsable task row is kept as a `FAILED` task rather than killing the
   whole store;
 - before every agent run (and on daemon startup) the current backlog is
@@ -282,3 +285,66 @@ in place automatically and the corrupt file is preserved under
 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
+application serving it, which keeps its own history, so Forgeo neither
+snapshots nor repairs it — see below.
+
+## A backlog over HTTP
+
+Setting `backlog:` to an `http(s)` URL moves the backlog into another
+application — typically one that already displays and edits work items. Forgeo
+then treats that endpoint exactly like the file:
+
+| When | Request |
+| --- | --- |
+| <span style="white-space: nowrap">Every read</span> | `GET <url>` returns the whole document |
+| <span style="white-space: nowrap">Every write</span> | `POST <url>` sends the whole document back |
+
+```yaml
+backlog: https://api.example.com/api/forgeo/backlog
+```
+
+Add [`backlog_auth`](configuration.md#backlog_auth) when the endpoint requires
+a token. Everything else is unchanged: the same task schema, the same
+oldest-first ordering, the same status transitions.
+
+### What the endpoint must do
+
+- **Return the document under `tasks`**, as above. A response that is not a
+  JSON object, or whose `tasks` is not a list, reads as an empty backlog.
+- **Replace, never append.** The POST body is the complete task list as it
+  should be after the change; an endpoint that appends will duplicate every
+  task on every cycle.
+- **Send dates as ISO-8601 strings**, not epoch numbers. Jackson (and several
+  other serializers) emit `java.time` values as numeric timestamps by default;
+  Forgeo would read those as Unix timestamps, dating every task to 1970 and
+  inverting the oldest-first ordering.
+- **Never send `null` for a list field.** `dependencies`,
+  `acceptance_criteria`, `files_to_modify`, `blocker_reason` and
+  `failure_reason` accept a list or nothing at all — an explicit `null` makes
+  that row unparsable, and it comes back as a `FAILED` placeholder task.
+- **Preserve `agent_command`'s shape.** A string is run through a shell, a list
+  is executed directly; turning `"claude -p ..."` into `["claude -p ..."]`
+  makes Forgeo look for a binary with that entire name.
+- **Store the engine-managed fields it receives** (`status`, `updated_at`,
+  `blocker_reason`, `blocked_count`, `failure_reason`) and hand them back
+  unchanged. That is how a blocked task keeps its explanation.
+
+### When the endpoint is down
+
+A failed request **fails the cycle**: the daemon logs the error and retries on
+the next interval, leaving the remote backlog untouched. It is never read as an
+empty backlog — that would start a refactoring pass and let the POST at the end
+of the cycle overwrite the real task list with nothing. `forgeo status` and
+`forgeo once` report `Backlog unavailable: ...` and exit `1`; the web console
+answers `502` for that instance's tasks and flags it on the home page instead
+of showing an empty board.
+
+### Runtime files
+
+There is no backlog file for Forgeo's own runtime files to sit beside, so
+`backlog.lock`, `backlog.run`, `backlog.state.json`, `backlog.update.json` and
+`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.