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

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

@@ -7,6 +7,46 @@ 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
+
+- `forgeo init` now asks for **backlog provider** (`file`/`github`/`gitlab`/`jira`/`http`). For `github` it auto-detects `owner/repo` from `git remote origin`, prompts for `token_env` (`GITHUB_TOKEN`) and can persist a pasted classic PAT (`ghp_...`, scope `repo`) to `~/.config/forgeo/github_token_env.sh` (600, wired to `~/.bashrc`). Same for `gitlab` (`GITLAB_TOKEN`, base URL) and `jira`/`http`. The wizard writes `backlog: https://api.github.com`, `backlog_provider: github`, `github: {repo, auth: {token_env}}` and `state_dir: .forgeo` automatically.
+- Web console now treats `jira`/`github`/`gitlab` as a **read-mostly mirror** instead of a replacement: the home page cards show `Open in Jira/GitHub/GitLab ↗` (via `external_board_url`/`external_board_label`), the instance page shows a top banner linking to the native board, and each task card/modal links to the native issue (`external_url`). Document backlogs (`file`/`http`) keep the existing primary-editor behaviour. Creating/editing still works through the dashboard, but triage is expected in the native tracker where Forgeo-specific state (BLOCKED/FAILED reasons, `agent_response`, retry budget) is now surfaced on the mirror.
+- Central API now exposes `backlog_provider`, `backlog`, `backlog_is_issue_provider`, `external_board_url`/`external_board_label` on `GET /api/instances` and `GET /api/instances/<name>/status`, and `external_url` per task on `GET /api/instances/<name>/tasks` (+ single-task) for issue providers. Covers `https://api.github.com` → `https://github.com` and `https://…/api/v3` → web base mapping for GitHub Enterprise, and `https://jira…/issues/?jql=` / `https://gitlab…/{repo}/-/issues` board links.
+
+### Fixed
+
+- GitHub provider now encodes `owner/repo` as two path segments (`quote` per segment, keeping `/`) instead of `quote(repo, safe='')` which produced `owner%2Frepo` and 404 on every `GET /repos/{owner%2Frepo}/issues`.
+
+### Changed
+
+- `README`, `docs/backlog.md`, `docs/getting-started.md` and `docs/web-console-api.md` document the mirror vs editor split and the new `external_*` API fields.
+- `src/forgeo/central.py` deduplicates provider metadata via `_backlog_meta()` and centralises GitHub web-base handling; `instance-card` is now a `div[role=link]` to allow nested external links without invalid HTML.
+- `README`, `docs/getting-started.md` and `docs/cli-reference.md` document the new backlog-provider step in `forgeo init` and the `GITHUB_TOKEN` PAT setup (`https://github.com/settings/tokens/new`, scope `repo`).
+
 ## [0.9.0] - 2026-08-23
 
 ### Added
@@ -389,7 +429,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.9.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
 [0.7.3]: https://github.com/lucaGazzola/forgeo/compare/v0.7.2...v0.7.3

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.