code-task

# code-task

Solve a real-repository coding task end to end: clone the repo to a
disposable working directory, run an OpenSquilla agent to make the change on
a task branch, then **independently verify** it with a red→green→regression
loop. Host mode (no Docker) in v1.

## Use this — do not hand-edit the repo yourself

When the user asks to fix/add/implement/change code in a repository they
name by path or URL, route it through `opensquilla code-task solve` — even
if the change looks small enough to do by hand. Editing the files yourself
in this session is **not equivalent**: it skips the disposable clone, the
task branch, and (most importantly) the runner-verified red→green→regression
proof, so neither you nor the user gets evidence the change actually works.
Answer inline (no code-task) ONLY for truly trivial one-liners, pseudocode, or
conceptual / non-deterministic questions. For self-contained TESTABLE code from
scratch with no repo named, use `code-task solve --task "..." --verification-mode
scratch` (no --repo): it writes the code plus a test and verifies it green-only
(no red/regression -- there is nothing pre-existing to regress). When a real repo
is named, prefer code-task red-green.

## Translating the user's request

The user speaks naturally ("fix issue 412 in github.com/acme/widgets",
"add CSV BOM support to my project at ~/code/foo"). Map that to the command:

```
opensquilla code-task solve --repo <url-or-path> ( --issue N | --task "<text>" | --task-file <path> ) [--yes]
```

> Invocation: do NOT assume a bare `opensquilla` (or bare `python`) is on PATH —
> the gateway commonly runs from an absolute interpreter path. When coding mode
> is active it injects the EXACT, resolved, PATH-independent command: use ONLY
> that. Otherwise invoke via an ABSOLUTE interpreter, e.g.
> `/abs/path/python -P -m opensquilla.cli.main code-task solve ...`. Never
> `pip install` OpenSquilla or run an installer to "get" the command; if it
> cannot be run, stop and report the environment is broken.

- **A GitHub issue** → `--issue N` (needs `gh`; see below).
- **A short request in the message** → `--task "<their request>"`.
- **A long spec, or pasted from Jira/GitLab/内网** → save it to a file and
  use `--task-file <path>`.
- Pass `--repo` for changes to an EXISTING repo. Omit it for
  `--verification-mode scratch` (from-scratch code) and for a from-scratch
  `--verification-mode build` (a brand-new app) — both scaffold their own repo.
  If the user is already in a local checkout, use that path; otherwise the URL.
- Pass `--yes` to skip the interactive trusted-host confirmation (you are
  acting on the user's behalf), but only after the safety check below.

## Before you run — two checks

1. **Trusted repo**: code-task runs an agent on the host that may install
   dependencies and execute the repo's code. It is NOT a sandbox. Only run
   it against repositories the user trusts. If the repo's provenance is
   unclear, ask first.
2. **Enough information**: you must be able to state the expected behavior
   change ("what is wrong/missing now, what should be true after"). If the
   request is too vague to write an acceptance test for, ask the user to
   clarify BEFORE running — do not burn a run on a guess.
   - **Build-from-scratch (`--verification-mode build`)** has no acceptance
     test. Decide by whether you know WHAT THE APP SHOULD DO, not just its kind.
     If the request is only a broad app type/goal with no concrete features,
     target user, or scope (e.g. "make me an English-learning app", "a drawing
     app"), ask 1-2 focused questions (core features/screens and who it's for),
     then STOP — do not run code-task until answered. If it already names
     concrete features, scope, or target users, do NOT ask — build it with
     sensible defaults and state your assumptions. Never ask about
     platform/framework/styling. At most 2 questions; never interrogate.

## GitHub issue mode needs `gh`

`--issue` shells out to the GitHub CLI (`gh`). If `gh` is missing or not
authenticated, tell the user to `gh auth login`, or fall back: have them
paste the issue text and use `--task` / `--task-file` instead. The issue
body AND comments are pulled in (comments often hold the repro steps).

## While it runs — watch the run dir, not the source repo

code-task clones the `--repo` source into an isolated run directory and does
all its work there. The **source repo stays empty until a run finishes and
VERIFIES**, at which point (build mode, local source) the change is committed
back. Therefore:

- Do NOT judge progress by the source repo's contents, and do NOT conclude the
  run is "stuck" because the source still looks empty — that is expected.
- A run takes several minutes. Let it finish: `process(action="wait")` on the
  background session. Do NOT kill it, do NOT "clean and retry", and do NOT
  launch the same task again while one is still running.
- The run prints its run directory on startup and writes a live
  `<run_dir>/status.json` (phase = preparing → agent_running → collecting_change
  → verifying → completed). Watch that if you want progress.
- Decide success only from the returned result `state` and
  `build.installer_path` (which points into the run dir, not the source).

## Reading the result

`--json` prints a result object; key fields:

- `state`: `verified` (acceptance test went red→green, no regressions),
  `already_satisfied` (the behavior already held on the base commit),
  `not_testable` (work done but not expressible as a test),
  `environment_blocked` (could not build/test the repo),
  `invalid_acceptance_test` (agent produced no valid verification manifest),
  `failed` (acceptance not green or a regression appeared).
- `branch`, `commits`, `files_changed`, `diffstat`, `patch_path`.
- `acceptance`: each test with `before`→`after` (e.g. `fail`→`pass`).
- `regression`: existing-suite result and `new_failures`.
- `assumptions`: **surface these to the user** — a wrong assumption me