Commit Graph

11 Commits

Author SHA1 Message Date
alan 5090f1cf4e Pipelines skill: outcome-first output, aligned review and loop guidance, operator material moved to docs
Rewrite format.md around turn files, the output.md order (# outcome, edge word, # handoff, detail), checks, configs, human stages and the land stage delivery gate (sh -c in a fresh detached worktree, clean checkouts incl. untracked, 64 KB output cap, opencode only). Align review guidance across practices, verification, orchestration and the feedback-loop example. Fix loop-limit semantics in control.md against runner.go, budget_tokens sizing, read for large inputs, blocked-else-error and one stage naming set. Move dated verification logs to docs/verification-history.md and brokered chat, TUI keys and harness internals to docs/operator-reference.md; label operator-only references in SKILL.md.
2026-11-04 17:27:01 +00:00
alan 72aecd8b1f Remove resource pools, leases and wait queues
Drop the resource allocation feature end to end: store tables and migration, runner scheduling and cleanup, protocol types and commands, CLI commands, TUI screens, tests and docs. Existing databases open cleanly and definitions carrying a retired resources block still validate.
2026-10-19 22:27:27 +01:00
alan bfcfcde415 Rewrite agent rules for accountable direct recovery and small parallel work 2026-10-18 23:05:40 +01:00
alan 01d5dad9b9 docs: describe the agent-driven workflow, drop the scripted driver model
Rewrite the workflow documentation to describe how the system actually works:
the agent (the session) is the brain and advances the queue by hand through the
`pipelines` CLI. There is no orchestration script, no driver, no polling loop and
no lane machinery, and none may be written.

- references/work.md: rewritten end to end. The queue-driver script
  (drivers/workd.sh), the claim-file ledger with atomic renames, the PAUSED
  marker and the poll loop are gone. State is now the server (authoritative for
  run state), the queue file (authoritative for intent) and the conversation.
  The agent reads the queue, picks the item, creates its worktree/branch and
  launches it with `pipelines run <pipeline> <brief> --json --yes`; progress is
  event-driven via a background `pipelines wait <run-id> [...]` (never polled);
  on completion the agent reconciles with `pipelines inspect <run-id> --json`,
  verifies it landed and starts the next item.
- references/queue.md: the landing gate runs the command directly
  (`git merge-base --is-ancestor <branch> main`, exit 0 = landed) instead of a
  `land-check.sh` helper; the never-delete-branch / never-remove-worktree rules
  are kept, and the waiting section states the agent advances the queue by hand.
- references/orchestration.md: intro and "Running and watching" state the
  agent-driven, event-driven model; "Pipeline choice" names the current set
  (Android, TUI, Server, Generic, Plan and land, UI sweep, Probe) by area and
  records the retired names.
- references/debugging.md: "Duplicated work after a driver restart" became
  "…after a session restart", resuming from the queue file not a cursor file.
- SKILL.md: the routing row no longer says "queue driver".
- AGENTS.md: the maintenance workflow names the current pipeline set instead of
  the retired `Pipelines maintenance - plan implement review`.
- internal/tui/AGENTS.md: the restart line no longer names lanes.
- docs/notes/agent-driven-work-model.md: the docs-fold note recording that
  docs/cli.md needs its "Scripted runs"/`--wait` framing aligned to the
  event-driven model, and that the dated evidence docs stay as they are.

Checked before committing: no packaged template directory exists in this repo, so
none needed updating; internal/author/install.go's managed file inventory needs no
change (no packaged reference was added or removed — the 13 listed files all
match internal/author/skill/references/); no stale `queue driver`/`workd.sh`/
`claim-file` references remain anywhere under internal/author. Genuine device
tooling (android/scripts/capture_png.sh-style) and server-side polling prose were
left alone.

Checks: `go test ./internal/author -count=1` ok; `go build ./...` clean;
`go vet ./...` clean; `gofmt -l .` clean.
2026-10-18 01:50:55 +01:00
alan 8f3ebf74ad skill: replace the lane model with the work queue
The lane machinery is gone: work is a markdown queue, items run in parallel in
their own worktrees, the committer stage lands its own work, land-check.sh gates
cleanup, branches are never deleted, and pipelines wait (rather than a driver
script) is what wakes a session. references/lanes.md becomes references/queue.md;
the remaining lane references in work/orchestration/debugging/delivery/format and
SKILL.md are rewritten, and the installer now prunes a managed file it no longer
bundles when the copy is unmodified.
2026-10-18 01:12:21 +01:00
alan 7b72b8f20f stage: retry pre-admission harness reach failures and widen repair deadline
Treat a failure to reach the harness before any prompt or tool call is
admitted (connecting or creating the session) as a distinct retryable
reach failure, so a transport blip at the first stage no longer ends a
mutating run; keep post-admission readback/poll/agent failures retried
only on an explicit read-only stage and never replay admitted tool work.
Preserve the true cause when the context is already done (join ctx.Err
with the typed transport error) and report a sanitized unknown provider
error name/status instead of a blanket summary.

Make the isolated format-repair deadline proportional to the stage
timeout (floored, capped and clamped to remaining minus a margin) so a
slow-but-repairable result is recovered without ever extending the stage
deadline; the bounded ladder, value guard, deny-all formatter session,
cumulative usage accounting and no-tool-replay rule are unchanged.

Update docs/model-results.md, docs/pipeline-performance-review.md and the
packaged skill references; add stage, opencode and server fixtures.
2026-10-17 14:51:09 +01:00
alan 8c1eea53a9 Report a stale client and refuse an unreadable newer server
Exchange a build/protocol identity so an older CLI can no longer talk to a
newer native server silently:

- protocol carries ProtocolVersion and every server frame (including the
  unsolicited welcome) is stamped with the server build and protocol, so a
  client that never pings still learns the server identity.
- buildinfo.Compare classifies the relationship as InSync/Warn/Refuse and
  names both builds; the client Watch reports one warning per connection and
  returns a hard error when the server speaks a newer, uninterpretable
  protocol so the caller never acts on the frame.
- client.ReceiveNotice decodes the raw frame so an unmodeled top-level field
  produces a one-time "unrecognized field(s)" notice instead of being dropped
  silently (the case that hid the artifacts field).
- CLI routes warnings to stderr, keeps machine JSON stdout clean and fails
  non-zero on a refused mismatch; ping/connection print the client/server
  relationship. The TUI surfaces the same notices through the shared log.
- scripts/setup-native.py now warns when an older `pipelines` earlier on PATH
  shadows prefix/bin/pipelines, naming both paths and versions, without
  installing or modifying anything else.
- Docs, the packaged debugging skill reference and README no longer imply the
  installed CLI always matches the server.

Tests cover the comparison table, unknown-field detection and caching, the
server identity stamping on pong and welcome, the CLI/TUI reporting paths and
the installer PATH shadowing warning.
2026-10-16 18:37:01 +01:00
alan 1b4674d22c Show the derived stage verdict atop the stage view in the run detail
Move a completed stage visit's derived verdict out of the Progress summary
and into the top of the selected stage's Result section, so the chosen
option, its concise reason and the referenced artifacts are visible where
the stage is inspected.

- Add stageVerdictLines, which renders one line "Verdict: <option> · <reason>"
  (still stating the option when the reason is absent) plus a following
  "Referenced artifacts:" line only when artifacts exist, and returns nil
  for a nil verdict so nothing extra is shown.
- Prepend those lines in runSectionLines after the stage state and before
  the stage output and evidence, without adding a section or changing the
  panel layout.
- Update the TUI test to render through the run-detail view, asserting the
  option, reason and artifact names appear, and that a nil verdict adds
  nothing; document the TUI placement in the debugging skill reference.

Omni-search work already present in the working tree (including the
runDuration→protocol.Duration refactor in run_detail.go) is unrelated to
this change and is left uncommitted.
2026-10-16 15:12:23 +01:00
alan e79ff9585f Derive a plain-language verdict for every completed stage visit
Each completed step now exposes a verdict: the chosen option (outcome -> target),
a bounded one-line reason with model/fallback/absent provenance, and the recorded
artifacts the reason refers to. The store persists only the model-generated line
in a new step_verdicts table and derives the fallback at read time (no backfill);
the server generates the line once at completion, best-effort; the TUI renders it
in the stage progress summary. The packaged debugging reference documents it.
2026-10-16 13:54:48 +01:00
alan 9f88e4ff71 Recover malformed model-stage results with a bounded, work-preserving repair
A model stage whose final result was malformed failed the whole run even when
the work and evidence had survived, because the only recovery was an isolated
formatter call on a fixed 30-second deadline that could time out on its own
(run 55, ui_reviewer of pipeline 9 v6).

Add an ordered, deterministic local repair pass (internal/stage/result_repair.go)
that runs before any model call: (a) append missing closing delimiters via the
existing closeJSONContainers; (b) remove one unambiguous trailing comma before a
closing } or ]; (c) insert exactly the single comma/colon the JSON parser reported
at its byte offset. Every candidate must pass losslessSyntaxRepair(original,
candidate) and decodeModelResult before it is accepted, so no field value is
invented, removed, reordered or rewritten. Ambiguous payloads (an unescaped quote
or colon inside a string value, or a stray delimiter with no single completion)
return not-ok and fall through to the bounded model re-emit rather than guessing.
stageResultText still strips surrounding prose and a single code fence first;
model_prompt.go now also strips prose around a single balanced-but-malformed
object span so the deterministic pass sees just the object.

Replace the fixed 30-second formatter deadline with repairDeadline(payloadBytes,
remaining), which grows monotonically with payload size, has a floor, and is
clamped to the attempt's remaining budget minus a safety margin, so the stage
context remains the outer bound and a large result is not guaranteed to time out.
The one-request-per-attempt, 32 KiB bound and the deny-all, retained, new-session
property of RepairFormat are unchanged for OpenCodeClient and PiClient.

Record an explicit recovery status on every terminal path: repaired, partial or
unrecoverable, plus a byte offset. A candidate that is valid JSON but still fails
envelope validation is marked partial and never returned as a completed result;
the unrecoverable path retains the bounded original payload, the precise parse
error (including its byte offset) and surfaces the status in the FINAL RESULT
VALIDATION diagnostic.

safeToReplay is intentionally unchanged. The deterministic local repair and the
fresh deny-all, no-tools, retained formatter session are independent of the
stage's tool set and never re-prompt or replay the admitted agent session, so a
shell-enabled review stage gains malformed-result recovery without any replay of
admitted work. Risk: no change to mutation safety; the only added cost is one
bounded formatter call, already budgeted. Replayability is not extended for shell
stages.

Docs and packaged skill references (docs/model-results.md,
internal/author/skill/references/{format,debugging,verification}.md) describe the
three-tier recovery, the status words and the derived deadline; the safeToReplay
decision and its risk are recorded there alongside the commit.

Tests add mocked, offline coverage for the deterministic and partial paths, a
repairDeadline monotonicity/floor/clamp table, and a shell-stage regression
proving a recoverable malformed result does not fail the run or replay tool work.
2026-10-16 13:02:53 +01:00
alan a625dbe055 Teach the pipelines skill to manage runs instead of implementing
Rewrite SKILL.md to state the stance (reconnoitre, then route all work
through Pipelines runs; manage and debug, never implement), keep the
existing authoring/operations index, and route to four new references.

Add references/orchestration.md (stance, work items, brief template,
hard constraints, pipeline choice, running and watching),
references/lanes.md (worktrees, devices, sync/merge, restart-replay
cursor fix), references/debugging.md (eight symptom/confirm/do
playbooks) and references/delivery.md (artifacts, LAN URLs, WIP naming,
install boundaries), each with a clearly labelled project example where
Android/device specifics apply.

Append orchestration verification habits to references/verification.md
and add the four new files to install.go's managed inventory.
2026-10-16 03:12:32 +01:00