Working on an approved plan

Once a person approves a plan in the web app, it becomes a task with one writer at a time. The writer is your coding tool or the WeHarness cloud.

Before the plan

1. Your tool connects the project (project_connect_local, or project_inspect for an existing one).
2. If cloud verification is wanted, it proposes how the repository is set up and checked in a fresh sandbox (environment_propose), and, for your agent’s behaviour, how a scenario case runs and the cases (eval_runner_propose, eval_case_propose).
3. It starts a plan with plan_propose, follows it with run_status, and reads it with plan_get. If the plan asks questions, your tool asks you and passes your answers with plan_answer.
4. You decide on the plan (it includes the detected setup and checks), the runner and the cases in your coding tool’s WeHarness view or its confirmation prompt; the project’s session in the web app (the approve_in link) is the fallback. approvals_get lists what still waits for you.

Build the task

1. task_get returns the task: what to build, which paths it may change, the acceptance tests, the skills by digest, the recipe that checks it, and the exact code it starts from (its base revision). Reading claims nothing.
2. task_claim makes your tool the task’s one writer and returns a fencing token. While it holds the task, another writer is refused. With takeover=true, the same person moves the task from another tool or the cloud, which stops the old writer. If your tool reconnects with the same sign-in, it carries on with its token.
3. Your tool builds the change, with guidance for each part, and keeps its claim with task_heartbeat: a claim lasts 10 minutes from the last heartbeat or report. If the plan changed meanwhile, the heartbeat answers PLAN_CHANGED: read the new task before editing more.
4. Write each acceptance test first and run it once on the unchanged code: it must fail. Report that run with phase: before, then the passing run after your change; a test that already passed proves nothing. task_next shows the work’s parallel waves, the steps that already passed (frozen) and any test your change broke.
5. task_report sends local command results and finished step ids. It can be metadata-only. To send changed file contents (null to delete), request a task_report file scope and pass its approved transfer_id. A local report stays reported and starts no sandbox.
6. Call task_next after reading a task and after every report. It checks missing acceptance evidence, selected skill versions and repeated failures, then directs implementation, testing, diagnosis or replanning. plan_propose can take up to three report ids and three application trace ids to include their scoped evidence in the next plan.
7. Independent cloud verification is optional: with authorized changed files and an approved recipe, a person chooses Verify in cloud in the task panel. This reserves cloud credits and reproduces that candidate. Only these checks can produce verified. The host cannot approve this action; its own passing results remain host-reported.
8. A verified report for the latest candidate that covers every step finishes the task. task_release gives the task back if your tool stops.

If your tool said its checks passed and they fail in the sandbox, the report says so. A mandatory case that fails fails the report, and cases you hold out appear only as counts.

What is refused

Unauthorized file transfers are rejected before storing their contents. An authorized report is refused but kept with its files when it comes from a writer that no longer holds the task, for another version of the task, or touches paths outside the plan. The checks belong to WeHarness, not to the writer:

• A report that changes a check’s file is refused. If the approved check or the scenario runner runs a file, a report that changes that file is refused and kept. Changing the checks is a change of scope, which a person approves in the app.
• Unsafe paths are refused, and so is a report with a path inside git’s own folder (in any spelling) or with an invisible character in it.
• Verification stops after two failures. When two reproductions in a row fail because of the writer’s changes, the task stops as Not verified. It is never accepted. WeHarness’s own trouble, such as no free sandbox, does not count. Further reports are refused until a person chooses Allow 2 more attempts in the app.

The task closes when its plan is replaced or its approval revoked, or when the code it starts from changes.

The cloud as the writer

A plan you approve in a session you started in the app is built by WeHarness there: the session holds the task, its agent builds it in the session’s draft, runs its checks, and sends the draft as the task’s report, through the same steps. A plan your coding tool asked for stays your tool’s to build.

In the plan panel, Work on it in the cloud moves the task to the session, and the tool that had it stops. Send the draft to the task sends the session’s draft as the report yourself. If your tool took the task back while the cloud worked, the cloud’s report is refused and kept, and the session’s draft keeps the changes.

The app shows the task with each report under the approved plan, and the session says when a report is verified or fails.

Pushing the result

A verified task does not change your repository by itself.

• Your tool built it: the changes are in your working copy. Commit and push them as you usually do.
• The cloud built it: WeHarness asks to push from the session, and a person approves it, as for any push. See GitHub.

Your tool reads a session’s pull request with session_pr_get or the pr prompt. It never pushes or approves a push.