Files
alan 9130ae8c7a Add stage-exclusive resource waiting
Add durable FIFO capacity-one resource leases for executable stages, including cleanup-confirmed release, conservative restart quarantine, queue state events, and CLI/TUI/Android waiting presentation. Add scheduler, cleanup, protocol, client, and Android coverage plus a proposed Android v3 resource draft.

Checked packaged templates and authoring skill references: neither needs updating in this item. The per-item docs note records the shared documentation that docs-fold must update; no shared README or packaged reference was edited.
2026-10-18 12:30:30 +01:00

11 KiB

stage implementer

{"max_visits":5,"on":["blocked_retryable"]}
{"task": "input.prompt", "code_findings": "reviewer.findings?", "ui_findings": "ui_reviewer.findings?"}
{ task, acceptance_checks, changed_files, implementation_summary, new_helpers }
Implement input.prompt in the run directory using the repository's actual languages and
file types; create files as needed.

Read android/AGENTS.md first. It is the map of this project - how to build, test, run and capture here, where
the pieces live, and the conventions that apply. Do not re-derive what it tells you and do not go
looking for what it already names; if it is wrong or out of date, say so in your output.

Read the surrounding code before editing so you extend the existing helpers and patterns rather than
duplicating them. Keep each change as small as the task allows and follow the repository's own
conventions and error handling.

This is the Android app. Build and test it with the project's own Gradle invocation as the map
gives it, and treat the map's geometry tokens as the only source of dimensions - a UI change that
adds a raw value fails the repository's own check. A change with a rendered surface is verified on
the device the map names (never an emulator), capturing what the map says to capture.

Record the acceptance checks in acceptance_checks, the actual changes in changed_files, and any new
shared helper in new_helpers. Verify with the checks this repository uses - as the map gives them -
and report the exact commands and observed output. Address any concrete findings the runner supplies
and note the actual fixes. Return blocked if the required scope or tools are unavailable. Do not
commit or push; the committer stage lands the work.
read
glob
grep
edit
shell
provider=openai
model=gpt-6.1-sol-fast
retries=1
timeout=30m
success -> reviewer
blocked_retryable -> implementer
blocked -> #failure
error -> #failure

stage reviewer

{"max_visits": 3, "on": ["rejected"]}
{"task": "input.prompt", "acceptance_checks": "implementer.acceptance_checks", "changed_files": "implementer.changed_files", "implementation": "implementer.implementation_summary?"}
{ summary, changed_files, verification_evidence, duplication_review, performance_review, findings }
Verify with the build and the unit tests as android/AGENTS.md gives them, and for a
change with a rendered surface check the captures against the running app on the device the map
names. Enforce the map's geometry-token rule: a raw dimension outside the token file is a must-fix
finding.

Review the actual changes against the task in input.prompt and the acceptance
checks the implementer recorded. Run the repository's relevant verification checks
with the stage tools (for example build, lint, tests or type checks) and report the
exact commands and observed results in verification_evidence.

Independently assess code quality:
- Duplication: search the run directory for repeated or near-identical functions,
  blocks and copy-pasted logic introduced by the change; identify code that should be
  shared and record concrete locations in duplication_review.
- Performance and resources: flag redundant computation, unnecessary dependencies,
  and repeated I/O or database/filesystem work that wastes time, CPU or memory;
  record it in performance_review.
- Workarounds: flag hacks, suppressed errors and shortcuts that trade reliability for
  speed in findings.

Keep verification proportionate to the change: exercise the files and screens the diff
actually touches, capture at most one screenshot per changed surface plus one regression
screen, and do not repeat sweeps or measurements that an earlier visit already recorded.

Return rejected ONLY when at least one must-fix finding exists: a defect that blocks
acceptance and that you can locate concretely (file and line), with evidence and a
remedy. Do not return rejected for advisory-only, cosmetic or nit items. When there
is no must-fix finding but you have non-blocking notes (duplication, performance or
workaround observations), record them in findings and return advisory, which
continues the run without another implementer visit. Return success only when the
observed checks pass and you have nothing further to record. Do not edit files or
claim unexecuted checks.
read
glob
grep
shell
provider=openai
model=gpt-6.1-sol-fast
retries=1
timeout=45m
success -> ui_reviewer
advisory -> ui_reviewer
rejected -> implementer
error -> #failure

stage ui_reviewer

{"max_visits": 3, "on": ["rejected"]}
{"task": "input.prompt", "acceptance_checks": "implementer.acceptance_checks", "changed_files": "implementer.changed_files", "implementation": "implementer.implementation_summary?"}
{ summary, changed_files, ui_applicable, screenshots, ui_review, platform_conventions, findings }
Decide whether this change touches a user-facing UI. If it does not (a backend,
library, CLI, config or data-only change with no rendered surface), set
ui_applicable=false, explain briefly in summary, and return skipped. Do not invent
screenshots or visual work.

When the change does affect a user-facing UI, verify it visually:
- Build and launch the application the way the repository actually does it, then
  capture screenshots of every relevant screen, state and viewport (default, empty,
  loading, error, long content, small and large sizes) with the target platform's
  screenshot tooling through shell. Prefer a headless or scripted capture when the
  project supports one. Save the images under the run directory and list the exact
  capture commands and image paths in screenshots.
- Read the captured images and review them as a UI/UX designer: layout, spacing,
  alignment, typographic hierarchy, color and contrast, iconography, interaction
  and focus states, loading/empty/error states, accessibility, and consistency.
- Judge the UI against established industry patterns and, above all, the native
  conventions of the platform the app targets (operating system, toolkit or web
  standards). Record the platform you reviewed against in platform_conventions,
  and any deviations and concrete fixes in findings. Infer the target platform from
  the task and the repository's actual UI toolkit when it is unstated.
- Approve only when the screenshots show the task and the acceptance checks are met
  and the UI is correct, consistent and native to the target platform; otherwise
  return rejected with specific, actionable findings the implementer can fix.

Keep the capture pass proportionate: capture each changed state once (for example one
collapsed and one expanded section, one run state, one stuck header) instead of every
screen at multiple viewports or pan directions, and reuse what this run already captured
rather than re-doing it.

If the change is UI-facing but screenshots genuinely cannot be captured
(for example no runnable UI or no display), return blocked rather than approving.
Do not edit files, and do not approve a UI you did not actually see.

Return rejected only for a must-fix visual defect with a concrete location, evidence
and remedy; record non-blocking polish, duplication or convention notes in findings
and return advisory, which continues the run without another implementer visit.
read
glob
grep
shell
provider=openai
model=gpt-6.1-sol-fast
retries=1
timeout=45m
skipped -> committer
approved -> committer
advisory -> committer
rejected -> implementer
blocked -> #failure
error -> #failure

stage committer

{"task": "input.prompt", "changed_files": "implementer.changed_files", "review": "reviewer.summary?", "ui_review": "ui_reviewer.summary?"}
{ commit, files, conflicts_resolved, summary }
Commit the work this run produced, and resolve any conflict that is present. This stage
runs after the reviews have approved and is the only stage allowed to commit.

Before committing, check that the change is reflected where it belongs: the packaged
templates, the packaged
authoring skill references. Update anything the change makes stale, and state in the
commit body what you checked, saying explicitly when none of them needs updating.

Stage exactly the files this run changed - the paths in changed_files that still exist -
using the repository's own version control commands, and commit them as one commit whose
subject says what the change does and whose body summarises it. Do not stage unrelated
files, generated or ignored files, or anything another change owns. Do not invent work
that was not done; describe what is actually in the diff.

If the workspace is in a conflicted state - unmerged paths, or a merge, rebase or
cherry-pick left unfinished - resolve each conflict: keep both intents where they are
compatible, and choose the result that satisfies the task where they are not, then
complete the operation so the tree is clean and the commit is finished. Never commit
conflict markers, and never discard the other side's work silently; record what you
resolved.

Do not push, tag, revert, or rewrite unrelated history. If there is nothing to commit,
report that instead of creating an empty commit. Report the commit identifier, the files
committed, whatever you resolved, and anything you deliberately left uncommitted.


Finally, bring this branch up to date with main, in this same stage. After committing the work
above, merge main into this branch here, resolve any conflict here - keeping both intents where they
are compatible, and choosing the result that satisfies this task where they are not - run the
repository's checks again after resolving, and commit the completed merge with a message naming what
was combined. The point is that this branch can later be merged back without conflict: leave the
tree clean and the merge finished. Never leave conflict markers, never discard the other side's work
silently. If the merge genuinely cannot be completed, say so with the path and the reason instead of
leaving the merge half-finished.

Then land it: this branch is the work and main is where it belongs, so merge this branch into main
as the last act of this stage. Find the repository's main working tree with `git worktree list` (the
entry checked out on main, not this one) and merge this branch into it there with `--no-ff`, with a
message saying what the change does. Two lanes can land at the same moment, so take a lock first -
`mkdir` a lock directory beside main's `git` directory in a bounded retry loop, and remove it when
done - and retry briefly if another lane holds it. Then verify with
`git merge-base --is-ancestor <this branch> main` and report the commit main now has. If main cannot
be updated, say exactly why and leave this branch committed and clean rather than leaving main
half-merged. There is no separate merge pipeline and nothing to hand this to: if it cannot be landed
here, it is reported here.


Do not edit README or other shared documentation files: an item records what it changed and which documentation is now stale in its own commit body, and the shared documents are folded by a single writer.

read
glob
grep
edit
shell
provider=openai
model=gpt-6.1-sol-fast
retries=1
timeout=30m
success -> #success
blocked -> #failure
error -> #failure