forgeo-cli 0.10.0__tar.gz → 0.11.0__tar.gz

{forgeo_cli-0.10.0 → forgeo_cli-0.11.0}/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-08-31
+
+### Added
+
+- **REVIEW status with feature-branch workflow** (`review_mode: branch`). When enabled, a successful agent run no longer commits directly to `main` as `COMPLETED`: the engine creates a feature branch `forgeo/review/<TASK_ID>` (via `review_branch_prefix`, default `forgeo/review/`), commits there, pushes, and marks the task `REVIEW`. Tasks in `REVIEW` block dependants (like `BLOCKED`/`FAILED`) while independent tasks keep running.
+- Per-task `review_required` override (`bool | null`): `true` forces branch+REVIEW, `false` forces direct `COMPLETED`, `null` inherits `review_mode`. Editable via `PATCH /api/instances/<name>/tasks/<id>` and persisted across all providers (file/http body, hidden `<!-- forgeo: {...} -->` block on GitHub/GitLab, Jira issue property `review_branch`/`review_commit_sha`).
+- Engine-managed `review_branch` and `review_commit_sha` on `Task` (set on `REVIEW`, cleared on leave), carried through document stores (`DocumentBacklogStore.set_review`/`complete_review`/`request_changes`) and issue stores via `forgeo-review` label (`forgeo_labels()`) plus engine state.
+- Web console: dedicated **REVIEW** kanban column, review-branch display on cards/modals, and human-in-the-loop actions `Complete` (`POST …/complete-review` → `COMPLETED` after manual merge) and `Request changes` (`POST …/request-changes` → `OPEN` for rework). Issue providers also show `external_url`/board links for the branch.
+- Generic webhook now supports `review` event (`WEBHOOK_EVENTS += "review"`, `notify_webhook_events` validation), sent by `Forgeo._run_task` on the `REVIEW` transition via `GitManager.create_review_branch`/`a_create_review_branch` and `_commit_on_review_branch` (creates/resets branch, commits, pushes, switches back to `branch` and hard-resets `main`).
+- `HttpBacklog`/`JSONBacklog`/`IssueBacklogBase` now expose `set_review`/`complete_review`/`request_changes` and central dashboard routes `POST /api/instances/<name>/tasks/<id>/{complete-review,request-changes}`. Shared helpers `_issue_provider_base`, `_github_repo_root`, `_gitlab_issues_root`, `forgeo_labels`, `extract_issue_number/labels`, `bump_state_counter` unify Jira/GitHub/GitLab handling.
+- `config/forgeo.yaml` and `docs/configuration.md` document `review_mode` and `review_branch_prefix`; `mkdocs.yml` `site_description` updated.
+
+### Changed
+
+- Docs restructured and condensed (~55% shorter) while preserving full coverage: `README`, `docs/agent-contract.md`, `docs/backlog.md`, `docs/cli-reference.md`, `docs/configuration.md`, `docs/getting-started.md`, `docs/index.md`, `docs/web-console-api.md` rewritten for scannability (tables, endpoint summary, concise curl examples).
+- `docs/backlog.md`, `docs/configuration.md`, `docs/web-console-api.md`, and `README` document the new REVIEW workflow, `REVIEW` task lifecycle, and new `review`-related API fields.
+- Internal maintainability refactor: `backlog.py` helpers `_require_string`/`_require_string_list`/`_status_by_id`/`_set_agent_response`/`_blocked_notice`/`_blocker_sections`/`_render_block`, `forgeo.py` split of blocker/commit logic, `models.py` `_IssueFieldMappingBase`/`_IssueBacklogConfigBase`/`_PatAuthBase`/`_IssueWorkflowBase`/`_RepoBacklogConfigBase` extraction, `IssueBacklogBase` shared `_call`/`_labels`/`_get_issue`/`_search_all`/`_task_from_issue`/`list_tasks`/`get_task`/`validate_connection`/`bump_failed_wait`/`_update_issue_labels`, `GitManager.ensure_branch`/`current_branch`/`create_review_branch`/`commit_all_on_branch` plus async wrappers, `central.py` `_github_web_base` exact-host rewrite and `_external_board_url`/`_external_issue_url` helpers, `config.py` `_maybe_resolve`, `validate.py`/`daemon.py`/`runs.py`/`paths.py`/`io.py`/`web_common.py`/`setup.py` lint-driven cleanups.
+
+### Fixed
+
+- `ruff`/`mypy` compliance across the review branch (BLE001/S110/F541 suppressions in `setup.py`, type narrowing in `Forgeo`, `src/forgeo/backlog.py:21`, etc.); `pytest` green including new `REVIEW` column/counts and delete tests.
+
 ## [0.10.0] - 2026-08-24
 
 ### Added
@@ -407,7 +429,8 @@ Initial release of the scheduled, agent-driven software forgeo.
   overlapping-run skipping.
 - Dogfooding docs removed; local configs kept out of the repository.
 
-[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/lucaGazzola/forgeo/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/lucaGazzola/forgeo/compare/v0.9.0...v0.10.0
 [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

forgeo_cli-0.11.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: forgeo-cli
+Version: 0.11.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
+Project-URL: Repository, https://github.com/lucaGazzola/forgeo
+Project-URL: Issues, https://github.com/lucaGazzola/forgeo/issues
+Author: Forgeo Contributors
+License: MIT License
+        
+        Copyright (c) 2026 Software Forgeo Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,ai,automation,backlog,orchestration,scheduler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<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)
+
+<div align="center">
+  <img src="docs/img/demo.gif" alt="Forgeo running a backlog task end to end" width="720">
+</div>
+
+**Forgeo is a software factory for your coding agent.**
+
+Give it a backlog and an agent CLI — Forgeo picks the next runnable task, runs the agent, and commits the result. It tracks progress in plain files and a web dashboard, and only interrupts you when a human decision is needed.
+
+- **One task at a time** — oldest `OPEN` task whose dependencies are `COMPLETED` (or a `run_at` schedule). `REVIEW` blocks dependants but not independent tasks.
+- **Agent-agnostic** — any CLI that reads `FORGEO_TASK` (aider, Claude, custom script).
+- **Refactors when idle** — runs a refactoring pass when the backlog is empty.
+- **Handles failure gracefully** — `BLOCKED` for human input (`BLOCKER.md`), `FAILED` with retry policy, snapshots for file backlogs, Telegram/webhook notifications.
+- **Optional review** — `review_mode: branch` commits to `forgeo/review/TASK-001`, marks `REVIEW`, pushes and waits for human merge → `Complete`.
+
+Requires a terminal, a git repo, and an agent CLI.
+
+## Quickstart
+
+Full walkthrough: [Getting Started](docs/getting-started.md).
+
+### 1. Install
+
+Pick one (no root; re-run to upgrade):
+
+```bash
+brew install lucaGazzola/forgeo/forgeo          # Homebrew, no Python needed
+curl -fsSL https://forgeo.org/install.sh | bash  # binary or pip fallback
+pipx install forgeo-cli                          # Python 3.11+
+```
+
+### 2. Init
+
+```bash
+forgeo init
+```
+
+Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For `github` it auto-detects `owner/repo` and can persist `GITHUB_TOKEN` to `~/.config/forgeo/`.
+
+### 3. Fill the backlog
+
+```bash
+# file provider: edit .forgeo/backlog.json (see Backlog format)
+# github/gitlab/jira/http: configured in forgeo.yaml, then:
+forgeo validate
+
+# or add tasks from the dashboard:
+forgeo web      # http://0.0.0.0:8790  (use -d to keep it running)
+```
+
+![Forgeo web console](docs/img/console.png)
+
+### 4. Start
+
+```bash
+forgeo validate   # dry run: config, repo, backlog, agent, locks
+forgeo start      # daemon in background, one cycle per interval_minutes
+```
+
+Each cycle: pick task → run agent → commit/push (or `REVIEW` branch when `review_mode: branch`). Empty backlog → refactoring pass.
+
+### Day-to-day
+
+```bash
+forgeo status              # config, counts, next task, daemon state, last outcome
+forgeo once                # one cycle in foreground, no daemon
+forgeo run --task TASK-012 # run a specific OPEN task now
+forgeo stop / restart      # stop or restart daemon
+forgeo web                 # dashboard for all instances
+```
+
+`forgeo web` is open by default on `0.0.0.0:8790`. On a shared host use `forgeo web --token` for bearer auth — see [Web console](docs/web-console-api.md).
+
+### Docker sandbox
+
+Run the agent isolated:
+
+```yaml
+agent_sandbox: docker
+agent_sandbox_image: your-image   # must contain agent CLI + sh
+agent_sandbox_network: none       # default, no network
+agent_sandbox_mounts: [~/.claude] # read-only mounts
+```
+
+Repo is bind-mounted at the same path; task arrives as `FORGEO_TASK`. See [Configuration](docs/configuration.md).
+
+### Multiple repos
+
+One config per repo, fully independent (own backlog, logs, locks). Use the instance registry:
+
+```bash
+forgeo instance add site-a --config /path/to/site-a/forgeo.yaml
+forgeo start --name site-a
+forgeo list          # all instances
+forgeo web           # aggregate dashboard
+```
+
+## Documentation
+
+| Topic | Doc |
+| --- | --- |
+| Install, init, first cycle | [Getting Started](docs/getting-started.md) |
+| All `forgeo.yaml` keys | [Configuration](docs/configuration.md) |
+| Task schema & statuses | [Backlog format](docs/backlog.md) |
+| Agent env, exit codes, timeouts | [Agent contract](docs/agent-contract.md) |
+| All CLI commands | [CLI reference](docs/cli-reference.md) |
+| Dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
+
+**Backlog providers:** [file](docs/backlog.md#a-json-file-backlog) · [HTTP](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/HTTP exchange the full document; Jira/GitHub/GitLab sync issues individually. File backlogs are snapshotted (`backlog.json.bak`) before each run and restored if corrupt.
+
+**Dashboard:** `forgeo web` aggregates every instance. For `file`/`http` it is the primary editor; for `jira`/`github`/`gitlab` it is a read-mostly mirror (links to native issues, surfaces `BLOCKED`/`FAILED` reasons and retry state).
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) (quality gates: `pytest`, `ruff check`, `mypy src/forgeo`).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

forgeo_cli-0.11.0/README.md

@@ -0,0 +1,134 @@
+<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)
+
+<div align="center">
+  <img src="docs/img/demo.gif" alt="Forgeo running a backlog task end to end" width="720">
+</div>
+
+**Forgeo is a software factory for your coding agent.**
+
+Give it a backlog and an agent CLI — Forgeo picks the next runnable task, runs the agent, and commits the result. It tracks progress in plain files and a web dashboard, and only interrupts you when a human decision is needed.
+
+- **One task at a time** — oldest `OPEN` task whose dependencies are `COMPLETED` (or a `run_at` schedule). `REVIEW` blocks dependants but not independent tasks.
+- **Agent-agnostic** — any CLI that reads `FORGEO_TASK` (aider, Claude, custom script).
+- **Refactors when idle** — runs a refactoring pass when the backlog is empty.
+- **Handles failure gracefully** — `BLOCKED` for human input (`BLOCKER.md`), `FAILED` with retry policy, snapshots for file backlogs, Telegram/webhook notifications.
+- **Optional review** — `review_mode: branch` commits to `forgeo/review/TASK-001`, marks `REVIEW`, pushes and waits for human merge → `Complete`.
+
+Requires a terminal, a git repo, and an agent CLI.
+
+## Quickstart
+
+Full walkthrough: [Getting Started](docs/getting-started.md).
+
+### 1. Install
+
+Pick one (no root; re-run to upgrade):
+
+```bash
+brew install lucaGazzola/forgeo/forgeo          # Homebrew, no Python needed
+curl -fsSL https://forgeo.org/install.sh | bash  # binary or pip fallback
+pipx install forgeo-cli                          # Python 3.11+
+```
+
+### 2. Init
+
+```bash
+forgeo init
+```
+
+Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For `github` it auto-detects `owner/repo` and can persist `GITHUB_TOKEN` to `~/.config/forgeo/`.
+
+### 3. Fill the backlog
+
+```bash
+# file provider: edit .forgeo/backlog.json (see Backlog format)
+# github/gitlab/jira/http: configured in forgeo.yaml, then:
+forgeo validate
+
+# or add tasks from the dashboard:
+forgeo web      # http://0.0.0.0:8790  (use -d to keep it running)
+```
+
+![Forgeo web console](docs/img/console.png)
+
+### 4. Start
+
+```bash
+forgeo validate   # dry run: config, repo, backlog, agent, locks
+forgeo start      # daemon in background, one cycle per interval_minutes
+```
+
+Each cycle: pick task → run agent → commit/push (or `REVIEW` branch when `review_mode: branch`). Empty backlog → refactoring pass.
+
+### Day-to-day
+
+```bash
+forgeo status              # config, counts, next task, daemon state, last outcome
+forgeo once                # one cycle in foreground, no daemon
+forgeo run --task TASK-012 # run a specific OPEN task now
+forgeo stop / restart      # stop or restart daemon
+forgeo web                 # dashboard for all instances
+```
+
+`forgeo web` is open by default on `0.0.0.0:8790`. On a shared host use `forgeo web --token` for bearer auth — see [Web console](docs/web-console-api.md).
+
+### Docker sandbox
+
+Run the agent isolated:
+
+```yaml
+agent_sandbox: docker
+agent_sandbox_image: your-image   # must contain agent CLI + sh
+agent_sandbox_network: none       # default, no network
+agent_sandbox_mounts: [~/.claude] # read-only mounts
+```
+
+Repo is bind-mounted at the same path; task arrives as `FORGEO_TASK`. See [Configuration](docs/configuration.md).
+
+### Multiple repos
+
+One config per repo, fully independent (own backlog, logs, locks). Use the instance registry:
+
+```bash
+forgeo instance add site-a --config /path/to/site-a/forgeo.yaml
+forgeo start --name site-a
+forgeo list          # all instances
+forgeo web           # aggregate dashboard
+```
+
+## Documentation
+
+| Topic | Doc |
+| --- | --- |
+| Install, init, first cycle | [Getting Started](docs/getting-started.md) |
+| All `forgeo.yaml` keys | [Configuration](docs/configuration.md) |
+| Task schema & statuses | [Backlog format](docs/backlog.md) |
+| Agent env, exit codes, timeouts | [Agent contract](docs/agent-contract.md) |
+| All CLI commands | [CLI reference](docs/cli-reference.md) |
+| Dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
+
+**Backlog providers:** [file](docs/backlog.md#a-json-file-backlog) · [HTTP](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/HTTP exchange the full document; Jira/GitHub/GitLab sync issues individually. File backlogs are snapshotted (`backlog.json.bak`) before each run and restored if corrupt.
+
+**Dashboard:** `forgeo web` aggregates every instance. For `file`/`http` it is the primary editor; for `jira`/`github`/`gitlab` it is a read-mostly mirror (links to native issues, surfaces `BLOCKED`/`FAILED` reasons and retry state).
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) (quality gates: `pytest`, `ruff check`, `mypy src/forgeo`).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

forgeo_cli-0.11.0/docs/agent-contract.md

@@ -0,0 +1,78 @@
+# Agent contract
+
+The coding agent is **any shell command** that can:
+
+1. Read the task from `FORGEO_TASK`.
+2. Work on the repository in the current directory.
+3. Report its outcome via **exit code**.
+
+```yaml
+agent_command: "claude -p \"$FORGEO_TASK\""
+```
+
+## Environment
+
+Launched with the repo as cwd and:
+
+| Variable | Value |
+| --- | --- |
+| `FORGEO_TASK` | Full instruction — project context (if `task_context`), title, description, and "Acceptance criteria:" when present. |
+| `FORGEO_REPO` | Absolute repo path. |
+| `FORGEO_BRANCH` | Target branch (default `main`). |
+| `agent_env` keys | Extra vars from config. |
+| Inherited env | Daemon's own environment. |
+
+`FORGEO_*` always wins. For refactoring runs (empty backlog), `FORGEO_TASK` carries the `refactor_prompt` (task ID `REFACTOR`).
+
+When `task_context` is set, its file contents are prepended under `# Project context` before `# Task`. Re-read each run; missing file is a warning.
+
+## Exit codes
+
+| Code | Outcome | What happens |
+| --- | --- | --- |
+| `0` | **SUCCESS** | `git add -A && git commit` as `<title> (#<id>)`, push if `remote` set, task → `COMPLETED`. |
+| `no_changes_exit_code` (default `3`) | **SUCCESS, no changes** | Task → `COMPLETED` without commit. Tree must be clean. |
+| `blocked_exit_code` (default `2`) | **BLOCKED** | Partial work committed as `<title> [partial]`, `blocker_reason` saved, notifications sent, task → `BLOCKED`, `BLOCKER.md` rendered next cycle. |
+| anything else | **ERROR** | Changes discarded (`git reset --hard` + `clean -fd`), task → `FAILED`, `failure_reason` saved. |
+
+`FAILED` stays `FAILED` until human reopens (or auto-retried via `failed_retry_max`). `BLOCKED` is never auto-retried.
+
+## The no-change contract
+
+Forgeo cannot distinguish "deliberately no changes" from "did nothing":
+
+- Exit `0` with **unchanged tree** → retried `no_changes_retry_max` times in the same cycle, then `BLOCKED` (never `FAILED` or silent `COMPLETED`).
+- To complete without code change, exit `no_changes_exit_code` with a **clean tree**. Reporting no-change while leaving uncommitted work → `FAILED`.
+
+Refactoring passes are exempt — a refactor finding nothing to improve is a normal success.
+
+## Timeouts
+
+`agent_timeout_seconds` kills the agent after N seconds (`error: timed out after <n>s`). Unset = no timeout. A run overrunning `interval_minutes` is never killed — the next cycle is skipped. Tip: leave unset for long agents and rely on skip-on-overlap.
+
+## Output
+
+Stdout/stderr are prefixed `[stdout]`/`[stderr]` and the last **1000 lines** are kept. On `BLOCKED`, the agent's questions (or output) become `blocker_reason` and the `BLOCKER.md` section (last 10 lines). Per-run tails go to `runs.jsonl` (`run_output_lines`); per-task `agent_response` is bounded by `agent_response_lines`.
+
+## Git contract
+
+The agent should **not** run `git` itself — Forgeo handles it:
+
+- Make changes in the repo.
+- Do not `git add`/`commit`/`push`/`reset`.
+- Exit `0` for commit, `no_changes_exit_code` for intentional no-op, `blocked_exit_code` for human input, anything else for discard.
+
+Embed the contract in your prompt:
+
+```yaml
+agent_command: >
+  opencode run --auto "Work on the repository at the current working directory.
+  Make the requested changes and nothing else. Do NOT run git commit/push/add.
+  Verify with tests. Read AGENTS.md and CONTEXT.md if present; update them
+  if your change affects the overview.
+  $FORGEO_TASK"
+```
+
+## Concurrency
+
+One agent per Forgeo: `backlog.lock` prevents a second `start`/`once`, and `backlog.run` makes a waking daemon skip while a run is active.

forgeo_cli-0.11.0/docs/backlog.md

@@ -0,0 +1,217 @@
+# Backlog format
+
+The backlog is a **plain JSON document** — a list of tasks Forgeo works through one by one. It can live as:
+
+- [JSON file](#a-json-file-backlog) — local file
+- [HTTP endpoint](#a-backlog-over-http) — another app serving the same document
+- [Jira](#a-jira-backlog) / [GitHub](#a-github-backlog) / [GitLab](#a-gitlab-backlog) — native issues
+
+## A JSON file backlog
+
+Default is a file wherever `backlog:` points (`backlog.json` or `.forgeo/backlog.json` from `forgeo init`). Keep it outside the repo if possible.
+
+```json
+{
+  "tasks": [
+    {
+      "id": "TASK-001",
+      "title": "Implement fibonacci module",
+      "description": "Write a fibonacci module with memoization and tests.",
+      "status": "OPEN",
+      "created_at": "2026-07-31T10:00:00Z"
+    }
+  ]
+}
+```
+
+## Task schema
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | string | — | Unique task ID. Duplicates rejected. |
+| `title` | string | — | Short title (logs, commits, status). |
+| `description` | string | — | Full instruction for the agent. Must be non-blank. |
+| `status` | `OPEN`/`REVIEW`/`BLOCKED`/`COMPLETED`/`FAILED` | `OPEN` | Task state. |
+| `created_at` | ISO-8601 | now (UTC) | Creation time; controls oldest-first order. |
+| `updated_at` | ISO-8601 | now (UTC) | Bumped on status changes. |
+| `run_at` | ISO-8601 / `null` | `null` | One-shot schedule — earliest pick time. Past = fire now; future = wait. |
+| `dependencies` | string[] | `[]` | Task IDs that must be `COMPLETED` first (`REVIEW` not satisfied). |
+| `acceptance_criteria` | string[] | `[]` | Rendered under "Acceptance criteria:" in `FORGEO_TASK`. |
+| `files_to_modify` | string[] | `[]` | Hint for the agent. |
+| `agent_command` | string / string[] | — | Per-task agent override. |
+| `agent_timeout_seconds` | number | — | Per-task timeout override. |
+| `blocker_reason` | string[] | `[]` | Engine-managed: reason when `BLOCKED`. |
+| `blocked_count` | int | `0` | Engine-managed: times transitioned to `BLOCKED`. |
+| `failure_reason` | string[] | `[]` | Engine-managed: error when `FAILED`. |
+| `agent_response` | string / `null` | `null` | Engine-managed: agent output on transitions. |
+| `retries_left` | int / `null` | `null` | Per-task retry budget override (`null` = config default, `0` = no retries). |
+| `retry_count` | int | `0` | Engine-managed: retries already attempted. |
+| `failed_wait_cycles` | int | `0` | Engine-managed: cycles waiting for retry. |
+| `review_required` | bool / `null` | `null` | Per-task review override (`null` = inherit `review_mode`). |
+| `review_branch` | string / `null` | `null` | Engine-managed: feature branch for `REVIEW`. |
+| `review_commit_sha` | string / `null` | `null` | Engine-managed: commit SHA on review branch. |
+
+Only `id`, `title`, `description` are required.
+
+### Per-task agent routing
+
+```json
+{
+  "tasks": [
+    {"id": "TASK-001", "title": "Add docstrings", "agent_command": "claude -p \"$FORGEO_TASK\" --model haiku"},
+    {"id": "TASK-002", "title": "Rearchitect cache", "agent_command": "claude -p \"$FORGEO_TASK\" --model opus"}
+  ]
+}
+```
+
+## Statuses
+
+| Status | Meaning |
+| --- | --- |
+| `OPEN` | To be picked. |
+| `REVIEW` | Awaiting human review on feature branch; blocks dependants, not independent tasks. |
+| `BLOCKED` | Needs human decision; Forgeo pauses. |
+| `COMPLETED` | Agent finished, committed and pushed (or review approved). |
+| `FAILED` | Agent errored; changes discarded, `failure_reason` recorded. |
+
+### Review workflow
+
+With `review_mode: branch` (and per-task `review_required` override) a successful task is committed on `review_branch_prefix + id` (default `forgeo/review/TASK-001`), pushed if `remote` set, and marked `REVIEW`. Independent `OPEN` tasks continue; dependants wait until `REVIEW` → `COMPLETED`.
+
+Human merges the branch manually (PR or `git merge`), then marks **Complete** (`POST .../tasks/<id>/complete-review` → `COMPLETED`, clears `review_branch/sha`) or **Request changes** (`POST .../tasks/<id>/request-changes` → `OPEN`). `REVIEW` tasks are deletable and show `review_branch`/`review_commit_sha`. Issue providers use label `forgeo-review`.
+
+### Retrying failed tasks
+
+With `failed_retry_max` set, a `FAILED` task is moved back to `OPEN` after `failed_retry_wait_cycles` cycles and `retry_count` is incremented. Exhausted tasks stay `FAILED`. `BLOCKED` is never auto-retried.
+
+Per-task override via `retries_left`:
+
+```json
+{"id": "TASK-001", "title": "Flaky test", "retries_left": 0},
+{"id": "TASK-002", "title": "Migrate cache", "retries_left": 3}
+```
+
+Retry state is visible in `runs.jsonl` and the dashboard (task card/modal, History **retry** column). Reopening a `FAILED` task manually (edit backlog or dashboard) resets `retry_count`.
+
+### Resolving blocked tasks
+
+On `BLOCKED`, Forgeo commits partial work as `[partial]` and records `blocker_reason`. `BLOCKER.md` is a derived view — re-rendered each cycle, auto-removed when no `BLOCKED` tasks remain.
+
+Reopen via dashboard (**Reopen** button) or `POST /api/.../tasks/<id>/reopen` — clears `blocker_reason`, keeps `blocked_count`. Editing the file's `status` back to `OPEN` does *not* clear `blocker_reason`; prefer the Reopen action.
+
+### Resolving review tasks
+
+On `REVIEW`, code is on the feature branch. Merge manually, then **Complete** (`POST .../tasks/<id>/complete-review`) or **Request changes** (`POST .../tasks/<id>/request-changes` → `OPEN`). Webhook `review` event fires on entry to `REVIEW` when enabled.
+
+## Picking order
+
+Forgeo picks the **oldest runnable `OPEN` task** — smallest `created_at` whose dependencies are all `COMPLETED` (`REVIEW` does not satisfy) and whose `run_at` is not in the future.
+
+- `run_at` in the **past** → picked before tasks without `run_at` (most overdue first); daemon wakes early for it.
+- `run_at` in the **future** → skipped until that moment; daemon sleeps only until then.
+- `null` / omitted → plain oldest-first.
+- Dependencies: missing or non-`COMPLETED` dependencies keep the task waiting forever. Surfaced in `forgeo status` (`waiting on:`) and the dashboard's *Waiting on dependencies* banner.
+
+## One-shot scheduling
+
+```json
+{"id": "TASK-001", "title": "Regenerate docs", "run_at": "2026-08-21T09:00:00Z"}
+```
+
+Use for time-sensitive work ("run after deploy"). Ignored for non-`OPEN` tasks or tasks with unmet dependencies. Set/clear via dashboard Create/Edit forms (`PATCH`).
+
+## Dependencies
+
+```json
+{"id": "TASK-003", "title": "Deploy", "dependencies": ["TASK-001", "TASK-002"]}
+```
+
+Oldest-first among *runnable* tasks — if the oldest `OPEN` task is blocked, the next runnable one is picked. Cyclic or permanently blocked dependencies yield no runnable task → refactoring pass until resolved.
+
+## Execution
+
+Once picked, the task goes to the agent as `FORGEO_TASK`; exit code decides commit/push vs `BLOCKED` vs discarded. See [Agent contract](agent-contract.md).
+
+## File backlog: corruption tolerance & snapshots
+
+- Missing file → empty backlog (created on first write).
+- Corrupt file → renamed to `backlog.json.corrupt-<timestamp>`, restored from newest valid snapshot or empty.
+- Unparsable row → kept as `FAILED` placeholder, not a store failure.
+- Before every agent run (and on daemon start), the backlog is copied to `backlog.json.bak` / `backlog.json.bak.1` (rotating, keeps last 2). On corrupt read, newest valid snapshot is restored. No snapshots for remote backlogs.
+
+## A backlog over HTTP
+
+```yaml
+backlog: https://api.example.com/backlog
+```
+
+| Operation | Request |
+| --- | --- |
+| Every read | `GET <url>` returns `{"tasks": [...]}` |
+| Every write | `POST <url>` sends the full document |
+
+Add `backlog_auth` for OAuth2. Same schema and ordering. Endpoint must:
+
+- Return `{"tasks": [...]}`; non-object or non-list → empty.
+- Replace, not append — POST body is the complete list.
+- Send dates as ISO-8601 strings (not epoch numbers).
+- Never send `null` for list fields.
+- Preserve `agent_command` shape (string vs list).
+- Store and return engine fields (`status`, `blocker_reason`, `failure_reason`, etc.).
+
+A failed request fails the cycle (retried next interval), never treated as empty — otherwise a `POST` would overwrite the remote with nothing. Dashboard shows `502` for unreachable instances.
+
+Runtime files (`backlog.lock`, `runs.jsonl`, etc.) go in `state_dir` (defaults to config dir).
+
+## A Jira backlog
+
+```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"}
+```
+
+- Jira keys → task IDs; `summary`/`description`/`created`/`updated` → task fields.
+- `open_statuses` = pickable; `running_status` = claimed before agent runs; `completed_status`/`blocked_status`/`failed_status` = terminal (blocked/failed optional — labels `forgeo-blocked`/`forgeo-failed` always applied).
+- Engine state (`blocker_reason`, `retry_count`, `agent_response`, etc.) in Jira issue property `forgeo`.
+- Optional `jira.fields` maps custom fields for `acceptance_criteria`, `dependencies`, etc. Without `run_at` mapping, Jira `duedate` is used at midnight UTC. Dependencies also inferred from `blocks` issue links.
+- Auth from env vars: `basic` (username + token) or `bearer` (PAT). Uses REST API v3 (`/search/jql` + cursor) by default; set `api_version: 2` for older servers.
+- Daemon paginates JQL; stale claims released after `claim_timeout_seconds`. Unavailable Jira fails the cycle.
+
+## A GitHub backlog
+
+```yaml
+backlog_provider: github
+backlog: https://api.github.com   # or https://github.example.com/api/v3
+github: {repo: owner/repo, token_env: GITHUB_TOKEN}
+```
+
+- Issue numbers → task IDs; `title`/`body`/`created_at`/`updated_at` → task fields.
+- `open` → `OPEN`, `closed` → `COMPLETED`; labels `forgeo-running`/`blocked`/`failed` for the rest.
+- Engine state in hidden `<!-- forgeo: {...} -->` block inside the body.
+- Paginated `GET /repos/{owner}/{repo}/issues?state=all`; claiming adds `forgeo-running` + `claimed_at`.
+
+Test live with `scripts/test-github-backlog-e2e.sh`:
+
+```bash
+GITHUB_TOKEN=... ./scripts/test-github-backlog-e2e.sh
+```
+
+## A GitLab backlog
+
+```yaml
+backlog_provider: gitlab
+backlog: https://gitlab.example.com   # instance root, /api/v4 appended
+gitlab: {repo: group/project, token_env: GITLAB_TOKEN}
+```
+
+- `iid` → task ID; `opened`/`closed` → `OPEN`/`COMPLETED`; same hidden-block and label mechanics as GitHub.
+- Paginated `GET /api/v4/projects/:id/issues?state=all`.
+
+## Managing tasks
+
+Edit the file directly, or use the dashboard: **Create** form (`POST /api/instances/<name>/tasks` → auto `WEB-###` ID, `review_required` checkbox), task modal **Edit** (`PATCH` including `review_required`), **Delete** (`DELETE` for `OPEN`/`BLOCKED`/`REVIEW`), **Reopen** for `BLOCKED`, **Complete** / **Request changes** for `REVIEW`. For `jira`/`github`/`gitlab` the dashboard is a read-mostly mirror with links to native issues and banners to the native board.