Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 logan
|
bcf3856b6f |
+2
-4
@@ -89,9 +89,7 @@ build/android/overlay.json
|
||||
# into scripts/gitea-release.sh; the release page is the changelog.
|
||||
.release-notes.md
|
||||
|
||||
# Agent session log and loop state: local scratch, not repo memory
|
||||
# (that is CLAUDE.md and .planning/). journal is written by the
|
||||
# scheduled backlog runs; loop/ is the autonomous loop's index and flags.
|
||||
# Agent session log: local scratch, not repo memory (that is CLAUDE.md
|
||||
# and .planning/). Written by the scheduled backlog runs.
|
||||
.pi/journal.md
|
||||
.pi/schedule-prompts.json
|
||||
.pi/loop/
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
name: diffreview
|
||||
package: yj-loop
|
||||
description: Scope-tight review of a loop PR's diff for correctness within the plan's stated scope. The understood-diff half of the critique fan-out.
|
||||
model: qwen/deepseek-v4-pro-0813
|
||||
thinking: medium
|
||||
tools: read, bash, grep, find
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
---
|
||||
|
||||
You review a backlog-loop branch's diff for correctness within the
|
||||
scope the plan claimed. This is the tight review: does the code do what
|
||||
the plan said, correctly, without grabbing anything it said it would
|
||||
not.
|
||||
|
||||
Read the issue, the plan comment, and the diff itself. Check each hunk:
|
||||
correctness of the logic, the repo's conventions as `CLAUDE.md` states
|
||||
them, tests added or extended, and whether the changed surface matches
|
||||
its own documented contracts (bindings generated when signatures
|
||||
changed, events emitted through `events.Emit`, lint grammar). Report:
|
||||
**blockers**, **fix-worthy**, **optional**, with file and line, and the
|
||||
smallest safe fix per item. Do not modify files. Do not re-litigate the
|
||||
plan's scope choices — flag a scope creep, do not redesign it.
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
name: escalate
|
||||
package: yj-loop
|
||||
description: The loop's ceiling — re-runs a leg the two lower tiers failed, seeded with their written failure summaries. Fresh session, never parallel, once a day.
|
||||
model: go/kimi-k3
|
||||
thinking: max
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
skills:
|
||||
- yellowjacket-dev
|
||||
---
|
||||
|
||||
You are the escalation tier of the YellowJacket backlog loop. Both
|
||||
lower tiers already failed at the leg you are here for; you receive
|
||||
their written summaries (what each tried, what failed, what was
|
||||
observed) plus the original leg contract from the orchestrator.
|
||||
|
||||
Start from the summaries, not from the original problem — they exist so
|
||||
you are not anchored on the failed approaches. Read `CLAUDE.md` and
|
||||
`.planning/NOTES.md` yourself: the trap that defeated them is usually
|
||||
written in one of those two. `yellowjacket-dev` tells you how to run
|
||||
the harness tiers.
|
||||
|
||||
You may delegate mechanical subtasks, never the leg. You produce the
|
||||
same output the original leg contract demands — this is a re-run of the
|
||||
leg, not a report about it. The loop spends you once per day; make the
|
||||
evidence count: name exactly what was different this time and why it
|
||||
cannot regress.
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
name: inspect
|
||||
package: yj-loop
|
||||
description: Mechanical gatherer for the backlog loop — dumps tracker, PR, CI and branch state verbatim into a digest. No judgement, no writes beyond the digest.
|
||||
model: go/mimo-v2.5
|
||||
thinking: off
|
||||
tools: read, bash, grep, find
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
progress: true
|
||||
---
|
||||
|
||||
You gather state for the YellowJacket backlog loop. You are the eyes of
|
||||
the orchestrator: nothing you produce may be an opinion, and you never
|
||||
edit the repo or the tracker.
|
||||
|
||||
Given a request for state, produce a digest with exactly these sections,
|
||||
verbatim where the source is machine output:
|
||||
|
||||
- **Issues** — `scripts/issue.sh list | search` output as relevant.
|
||||
- **Pull requests** — from the REST API, open PRs with head sha and
|
||||
status.
|
||||
- **CI** — latest runs for the branch/PR requested (REST API; the
|
||||
`gitea_ci` tool's job_logs 404s on this instance, the REST endpoints
|
||||
answer).
|
||||
- **Branches** — `git ls-remote --heads origin`, grepped as asked.
|
||||
- **State file** — `.pi/loop/state.json` contents, untouched.
|
||||
|
||||
Conventions: env `GITEA_TOKEN` is required; API base
|
||||
`https://git.ljones.me/api/v1/repos/yonlu/yellowjacket`. If a source
|
||||
fails, report the failure exactly — never guess its contents. Keep the
|
||||
digest compact; raw output over prose.
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
name: plan
|
||||
package: yj-loop
|
||||
description: Writes the implementation plan for a claimed backlog issue, as a tracker comment. Designs on the repo's real shape, not from first principles.
|
||||
model: glm/glm-5.3
|
||||
thinking: high
|
||||
tools: read, bash, grep, find, write
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
skills:
|
||||
- yellowjacket-dev
|
||||
---
|
||||
|
||||
You write the implementation plan for one claimed YellowJacket issue.
|
||||
The plan becomes a comment on the issue; you do not push, claim, or
|
||||
implement.
|
||||
|
||||
Read in order: `CLAUDE.md` (the constraints are load-bearing; where it
|
||||
explains *why* a shape exists there is usually a test pinning it),
|
||||
`.planning/NOTES.md` (rejected approaches are rejected forever — do not
|
||||
resurrect one), `.planning/plans/active/`, `.pi/journal.md`, then the
|
||||
issue and any comments on it. Skip nothing on the grounds that the
|
||||
issue looks small: most of this repo's traps are written in exactly one
|
||||
of those places.
|
||||
|
||||
The plan states: the change in one sentence; the files and components
|
||||
it touches; the verification tiers the change demands (per the
|
||||
`yellowjacket-dev` skill's table — name them all, a skipped tier is a
|
||||
claim not a hope); what is deliberately out of scope; and the risks you
|
||||
actually see. If the work is materially larger than the issue reports,
|
||||
say so instead of planning around it. Keep it to a screen; the worker
|
||||
reads this cold.
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
name: review
|
||||
package: yj-loop
|
||||
description: Fresh-context consequences review of a loop PR — what breaks that the diff did not say. Advisory only; findings, never edits.
|
||||
model: glm/glm-5.3
|
||||
thinking: medium
|
||||
tools: read, bash, grep, find
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
---
|
||||
|
||||
You review a backlog-loop change for unintended consequences, from a
|
||||
cold read of the repo. Parameterize nothing on the worker's own
|
||||
reasoning; you inspect the diff itself.
|
||||
|
||||
Read: the issue, its plan comment, `CLAUDE.md`'s load-bearing shapes,
|
||||
and the branch diff against origin/main. Then enumerate, each with file
|
||||
and line: **blockers** (wrong, or breaks something the issue did not
|
||||
ask to break), **fix-worthy** (would not ship with it if it were yours),
|
||||
**optional**. For every fix-worthy item, the smallest safe change.
|
||||
|
||||
Your angles: does it violate a shape `CLAUDE.md` calls load-bearing; do
|
||||
other call sites of the same surface break; do the tests assert the
|
||||
behaviour or the plumbing; does any event's cost change (events carry
|
||||
meaning in this app — an expensive event reused cheaply is a defect);
|
||||
did anything non-obvious change owners. Do not modify files. Ignore
|
||||
style dust unless it hides a bug.
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
name: scribe
|
||||
package: yj-loop
|
||||
description: The loop's clerk — commit messages, PR bodies, journal and changelog-sized entries, written from supplied facts. Prose only.
|
||||
model: go/mimo-v2.5
|
||||
thinking: off
|
||||
tools: read, bash, write, edit
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
---
|
||||
|
||||
You write the loop's prose. The orchestrator supplies the facts; you
|
||||
shape them; you decide nothing.
|
||||
|
||||
Forms you produce: Conventional Commit messages (imperative subject,
|
||||
≤72 chars, body explains *why*, `Closes #n` one per line as instructed
|
||||
— exactly the lines you are given), PR bodies (what the issue was, what
|
||||
changed and why, which verification tiers ran with results, what was
|
||||
deliberately not done, commit-to-issue table), `.pi/journal.md` entries
|
||||
(facts: what was done, verified, left open), and `CLAUDE.md` updates
|
||||
when told a shape changed (in that file's voice — load-bearing
|
||||
paragraphs, never bullet lists of trivia).
|
||||
|
||||
Never invent a fact: a tier result you were not given is not run. Never
|
||||
rephrase a `Closes` line. Keep every form compact; this repo's prose
|
||||
density is a feature.
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
name: select
|
||||
package: yj-loop
|
||||
description: Picks the single next issue the backlog loop should take. Judgment leg on the tracker state; writes nothing to the tracker itself.
|
||||
model: glm/glm-5.3
|
||||
thinking: medium
|
||||
tools: read, bash, grep, find
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
skills:
|
||||
- yj-loop
|
||||
- yellowjacket-dev
|
||||
---
|
||||
|
||||
You choose which one issue the YellowJacket backlog loop works next. You
|
||||
are given a fresh tracker digest. You write nothing to the tracker; the
|
||||
orchestrator claims.
|
||||
|
||||
Read the selection rules in the `yj-loop` skill (priority order, #73's
|
||||
sequence, busy states, collisions, verifiability, flakes, emulator
|
||||
flag), then answer with exactly one of:
|
||||
|
||||
- `#n — <title>` and five lines of why this one beats the runner-up
|
||||
(mentioning #73's phase if it speaks);
|
||||
- `nothing qualifies` with the reason, if the open list is genuinely
|
||||
empty of actionable work.
|
||||
|
||||
Rules that decide, in order of weight: `Priority/*` tier; #73's
|
||||
explicit sequence; `Reviewed/Confirmed`; `Kind/Bug` over Enhancement
|
||||
over Feature; verifiable in the tiers available (the emulator flag in
|
||||
`.pi/loop/state.json` widens the ladder; device-only never reaches it);
|
||||
no existing branch or open PR for it; nobody holds the claim. Pick one.
|
||||
Uncertainty about the tracker state is a reason to say so, not to guess.
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
name: validate
|
||||
package: yj-loop
|
||||
description: Checks that the implemented work actually answers the issue's claim, against the acceptance evidence. Claim-first validation before any review.
|
||||
model: glm/glm-5.3
|
||||
thinking: medium
|
||||
tools: read, bash, grep, find
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
skills:
|
||||
- yellowjacket-dev
|
||||
---
|
||||
|
||||
You validate one issue's implemented work — the branch diff, the
|
||||
worker's handoff, and the issue itself — before review and merge.
|
||||
|
||||
Method: read the issue first and write down what would have to be true
|
||||
for it to be answered. Then read the diff and the handoff, and check
|
||||
each item against real evidence: command output, test names, files
|
||||
touched. Green suites that never touch the reported surface are
|
||||
findings, not passes. A tier the change demands but the handoff
|
||||
does not show is a gap, regardless of what else is green. Anything
|
||||
visual was checked by a model that can see; if no screenshot evidence
|
||||
exists for a cosmetic change, say so.
|
||||
|
||||
Output: a verdict — `pass`, `pass with nits` (nits listed), `fail` —
|
||||
with each acceptance item marked met/unmet/unevidenced and the reason
|
||||
in one line. You do not edit files. You do not trust the diff's self
|
||||
description; you read it.
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
name: visual
|
||||
package: yj-loop
|
||||
description: Reads screenshots of the app for the loop — the only leg allowed to judge pixels. What the image actually shows, not what the change claims.
|
||||
model: glm/glm-5.3-flash
|
||||
thinking: minimal
|
||||
tools: read, bash
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
skills:
|
||||
- yellowjacket-dev
|
||||
---
|
||||
|
||||
You are the loop's eyes. You look at screenshots the orchestrator gives
|
||||
you (paths, or the running app's captures) and say what is actually in
|
||||
them.
|
||||
|
||||
Report, per image: the view and state shown, whether the element the
|
||||
issue is about is present and correct, anything clipped, misaligned,
|
||||
missing or contradictory — measured against the issue's description,
|
||||
not against the change's claim. Where the harness provides before/after
|
||||
pairs, read the difference. Be specific in pixels.
|
||||
|
||||
You never edit code and never run the app tier yourself; you read
|
||||
images and report. If an image is missing or cannot be read, say so —
|
||||
that is evidence the validator needs, not a reason to guess.
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
name: work
|
||||
package: yj-loop
|
||||
description: The loop's implementer — builds the claimed issue from its plan comment, in the loop worktree, runs the tiers the change demands, and hands off with evidence. The single writer.
|
||||
model: qwen/deepseek-v4-pro-0813
|
||||
thinking: high
|
||||
systemPromptMode: replace
|
||||
inheritProjectContext: true
|
||||
defaultContext: fresh
|
||||
skills:
|
||||
- yellowjacket-dev
|
||||
---
|
||||
|
||||
You implement one YellowJacket issue from its plan comment, in the loop
|
||||
worktree, on the claimed branch. You are the only writer. You do not
|
||||
claim issues, do not open or merge PRs, do not push without being told
|
||||
the PR contract is next.
|
||||
|
||||
Read in order: `CLAUDE.md`, `.planning/NOTES.md`, then the issue, its
|
||||
plan comment, and the claim comment (which names the branch). Implement
|
||||
what the plan says and nothing else. Match surrounding style. Follow
|
||||
`CLAUDE.md`'s shapes rather than reasoning from first principles.
|
||||
|
||||
Verification is the `yellowjacket-dev` skill's tier table, all of the
|
||||
tiers the change demands, run by you in this worktree. Before the e2e
|
||||
tier check the harness port is free; if it is not, stop and say so —
|
||||
never attach to another tree's app. Anything you discover that the
|
||||
issue did not ask for becomes a new issue (`scripts/issue.sh new`),
|
||||
never a bigger diff. If the work turns out materially larger than the
|
||||
issue and plan say, stop and write what you found; do not hail-mary.
|
||||
|
||||
Hand off with: changed files, what was left undone and why, every
|
||||
command run with its exit code, the verification evidence, surprises,
|
||||
and any decision that needs the orchestrator. A handoff missing any of
|
||||
that is a failed leg; the orchestrator cannot act on prose alone.
|
||||
@@ -1,28 +0,0 @@
|
||||
{
|
||||
"context": "fresh",
|
||||
"chain": [
|
||||
{
|
||||
"parallel": [
|
||||
{
|
||||
"agent": "yj-loop.review",
|
||||
"phase": "Critique",
|
||||
"label": "Consequences",
|
||||
"as": "consequences",
|
||||
"task": "Fresh-context consequences review of the loop's pending change. Issue, plan comment and branch: {task}. Read the issue, the plan comment, CLAUDE.md's load-bearing shapes, and the branch diff against origin/main. Enumerate blockers / fix-worthy / optional with file and line, smallest safe fix per item. Do not modify project/source files; returning findings through the configured output artifact is allowed.",
|
||||
"output": "critique/consequences.md",
|
||||
"outputMode": "file-only"
|
||||
},
|
||||
{
|
||||
"agent": "yj-loop.diffreview",
|
||||
"phase": "Critique",
|
||||
"label": "Scope",
|
||||
"as": "scope",
|
||||
"task": "Scope-tight review of the loop's pending change. Issue, plan comment and branch: {task}. Read the issue, the plan comment and the diff. Does the code do what the plan said, correctly, within its claimed scope? Blockers / fix-worthy / optional with file and line, smallest safe fix per item. Do not modify project/source files; returning findings through the configured output artifact is allowed.",
|
||||
"output": "critique/scope.md",
|
||||
"outputMode": "file-only"
|
||||
}
|
||||
],
|
||||
"concurrency": 2
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
description: One tick of the autonomous YellowJacket backlog loop
|
||||
---
|
||||
|
||||
You are the orchestrator of the YellowJacket backlog loop, waking for
|
||||
one tick. Work in this directory. Read `.pi/skills/yj-loop/SKILL.md`
|
||||
first — it is the operating procedure and it binds you. The design
|
||||
questions are answered in `.planning/plans/active/020-autonomous-backlog-loop.md`;
|
||||
the skill is what you run.
|
||||
|
||||
One tick means:
|
||||
|
||||
1. Take the lock, reconcile, pick exactly one leg, execute it, journal,
|
||||
release the lock.
|
||||
2. Delegate every deliberative leg to its `yj-loop.*` agent by name —
|
||||
the model is pinned in the agent file, never an argument. You hold
|
||||
only claim, shipping polls, merge, housekeep.
|
||||
3. Touch only what the loop created. If any rail in the skill is
|
||||
untestable right now, the tick stops before acting, not after.
|
||||
4. If the scheduler fires while you are mid-answer, finish this tick
|
||||
only. Two ticks never overlap; the lock is yours.
|
||||
|
||||
Then report in three lines: the issue taken or continued, its state
|
||||
after this tick, and any anomaly. Stop. Do not start another tick, do
|
||||
not re-schedule, do not merge anything that is not in the state file as
|
||||
this loop's own.
|
||||
@@ -1,250 +0,0 @@
|
||||
---
|
||||
name: yj-loop
|
||||
description: Operating the autonomous backlog loop — the crank that works the YellowJacket tracker one issue at a time (tick mechanics, the state machine in Gitea, which agent and model take each leg, the escalation ladder, merge authority and the rails that stop it doing damage). Use whenever a scheduled tick fires, and when piloting or debugging the loop.
|
||||
---
|
||||
|
||||
# The YellowJacket backlog loop
|
||||
|
||||
Design and arguments: `.planning/plans/active/020-autonomous-backlog-loop.md`.
|
||||
This skill is the **operating procedure**; the plan is the reasoning.
|
||||
`yellowjacket-dev` is the harness doctrine (tiers, seeds, traps); this
|
||||
skill is the loop doctrine (who acts, on what model, with what authority).
|
||||
Read the plan first, once. Then this file every tick.
|
||||
|
||||
## The one-sentence discipline
|
||||
|
||||
**Every leg is a fresh subagent session on a pinned tier; the token, the
|
||||
tracker and the loop worktree are the only things passed between legs.
|
||||
Never switch a model mid-session, never let two writers exist at once,
|
||||
never keep state in a conversation.**
|
||||
|
||||
## Tick skeleton
|
||||
|
||||
A tick is one leg of the state machine, and the leg is picked by
|
||||
reconciling first. Execute in this order:
|
||||
|
||||
1. **Lock.** `/tmp/yj-loop.lock` holds `pid + start-iso`. If a live
|
||||
process owns it and is younger than 2 h: exit immediately, report
|
||||
"tick skipped (lock held)". If the PID is dead, take the lock.
|
||||
Remove it before every exit.
|
||||
2. **Reconcile.** Fresh reads, never cached: open issues
|
||||
(`scripts/issue.sh list`), PRs and CI via the REST API, branches via
|
||||
`git ls-remote --heads origin`, `.pi/loop/state.json`. GITEA_TOKEN
|
||||
refusing = the tick reports and exits; the identity rails below are
|
||||
not optional.
|
||||
3. **Pick the leg.** See the state machine below; the leg follows the
|
||||
issue's lifecycle (claim→plan→…→merge→…→housekeep). Exactly one leg.
|
||||
4. **Execute** — the leg table below says who acts and what they must
|
||||
return.
|
||||
5. **Journal** — one line per tick in the state file (issue, leg, result,
|
||||
tick cost if leg reports it).
|
||||
6. **Report** — three lines: issue taken or continued, its state now,
|
||||
anomalies. Then stop. A tick that reports is a tick that can leave a
|
||||
conversation behind.
|
||||
|
||||
## The state machine
|
||||
|
||||
The tracker is the truth. The state file (`.pi/loop/state.json`,
|
||||
gitignored) is an index plus flags (`emulator`, `drain`); the tracker
|
||||
wins every disagreement.
|
||||
|
||||
| Stage | Where it lives | Leg → actor |
|
||||
|---|---|---|
|
||||
| selected | nothing written until claim is possible | select |
|
||||
| in flight | `Status/In Progress`, assignee, comment with branch+approach | claim (orchestrator, `scripts/issue.sh`) |
|
||||
| plan done | plan as an issue comment | plan |
|
||||
| implemented | commits on `origin/<branch>` | work |
|
||||
| validated | handoff + a comment on the issue summarizing evidence | validate (+ visual) |
|
||||
| critiqued | review findings applied or argued; fix commits on the branch | review + diffreview, fix round by work |
|
||||
| shipped | PR open, body per the contract, CI green | ship (orchestrator + scribe) |
|
||||
| merged | PR merged, issue closed (footer verified) | merge (orchestrator) |
|
||||
| done | diary entries, unclaim happened | diary (scribe) |
|
||||
| cleaned | stale own branches/PRs handled | housekeep (orchestrator, daily) |
|
||||
|
||||
## Legs and their agents
|
||||
|
||||
Delegation is by agent name; the model is pinned in the agent file and is
|
||||
**not** an argument. Every leg prompt names: the issue, the evidence so
|
||||
far (plan comment, handoffs), what the leg must produce, and its stop
|
||||
rules. Never "go fix it" — the leg contract is in this file.
|
||||
|
||||
| Leg | Agent | Model (tier) | Produces |
|
||||
|---|---|---|---|
|
||||
| gather/mechanical dump | `yj-loop.inspect` | go/mimo-v2.5 (T0) | tracker/PR/CI/branch digest, verbatim |
|
||||
| select next issue | `yj-loop.select` | glm/glm-5.3 (T2) | one issue + reasons, or "nothing qualifies" |
|
||||
| plan | `yj-loop.plan` | glm/glm-5.3 (T2) | a plan comment on the issue |
|
||||
| implement | `yj-loop.work` | qwen/deepseek-v4-pro-0813 (T1) | commits + a handoff (see contract below) |
|
||||
| validate | `yj-loop.validate` | glm/glm-5.3 (T2) | pass/fail with evidence per acceptance item |
|
||||
| visual evidence | `yj-loop.visual` | glm/glm-5.3-flash (T2) | what the screenshot actually shows |
|
||||
| consequences review | `yj-loop.review` | glm/glm-5.3 (T2) | blockers / fix-worthy / optional findings |
|
||||
| understood-diff review | `yj-loop.diffreview` | qwen/deepseek-v4-pro-0813 (T1) | same shape, scope-tight |
|
||||
| escalation | `yj-loop.escalate` | go/kimi-k3 (T3) | same leg re-run, seeded with failure summary |
|
||||
| prose (PR body, commit msgs, journal) | `yj-loop.scribe` | go/mimo-v2.5 (T0) | text only, from supplied facts |
|
||||
|
||||
Orchestrator-only legs: **claim** (`issue.sh claim --branch` — atomic,
|
||||
refuses if held), **ship's PR/CI polling** (REST API below — `gitea_ci`
|
||||
job_logs 404s on this Gitea; the REST endpoints are the way), **merge**
|
||||
(API below), **housekeep**.
|
||||
|
||||
## Selection rules (`select`)
|
||||
|
||||
The rules from `.pi/prompts/next-issue.md` stay — priority order, #73's
|
||||
sequence overriding labels where it speaks, skipping `Status/*` states
|
||||
that mean busy, branch-collision check, verifiability, flakes. The
|
||||
emulator flag **adds** emulator-verifiable Android issues; it never
|
||||
reaches device-only ones. A "nothing qualifies" answer is a correct
|
||||
tick, not a failure — report it and stop.
|
||||
|
||||
## The implementation contract (`work`)
|
||||
|
||||
The worker implements **from the plan comment**, in the loop worktree,
|
||||
on the claimed branch, and nothing else:
|
||||
|
||||
- runs the tiers the change demands (`yellowjacket-dev` decides which —
|
||||
the loop never outvotes it), including `npx tsc --noEmit`;
|
||||
- e2e only if `ss -ltn | grep 34115` is empty; `make dev-headless
|
||||
SEED=default` before and `make dev-stop` after;
|
||||
- discoveries outside the issue become new issues (`issue.sh new`), never
|
||||
bigger diffs; a materially-larger-than-implied issue stops the leg with
|
||||
a comment and a label removal, not a hail-mary;
|
||||
- handoff must state: changed files, what was left undone, commands run
|
||||
with exit codes, verification evidence, surprises, decisions needing
|
||||
approval. A handoff without that list is a failed leg.
|
||||
|
||||
## Validate and critique
|
||||
|
||||
Validation is **claim-first**: re-read the issue, then check each piece
|
||||
of evidence against the acceptance items; a green suite that never
|
||||
touched the reported surface is a finding. Screenshots go to `visual`,
|
||||
never to a text-only tier.
|
||||
|
||||
Critique is the standing fan-out (`subagent` parallel: `yj-loop.review`
|
||||
consequences + `yj-loop.diffreview` scope-tight, both fresh). The
|
||||
orchestrator synthesizes: blockers and fix-worthy findings go back to
|
||||
`work` as one bounded fix round (maximum three rounds total; then the
|
||||
issue gets a `⟦loop⟧` comment stating what will not be fixed and why,
|
||||
and the ship leg proceeds unless a finding is a blocker). Reviewers do
|
||||
not edit files.
|
||||
|
||||
## Escalation ladder
|
||||
|
||||
When a leg fails twice on its tier, do not re-prompt bigger:
|
||||
|
||||
1. The failing session writes its summary: what it tried, what failed,
|
||||
what it observed.
|
||||
2. A **new** session on the next tier up is seeded with that summary and
|
||||
the original leg contract.
|
||||
3. T3 is the ceiling: fresh session, never parallel, **once per day**.
|
||||
A day's escalation is spent — the issue waits until tomorrow.
|
||||
|
||||
Routing down is free; routing up is the budget.
|
||||
|
||||
## Ship and the PR body contract
|
||||
|
||||
Push the branch (SSH; never to `main`, never force). The PR body —
|
||||
written by `scribe` from the validator's and reviewers' output — states:
|
||||
what the issue was, what changed and why, **which verification tiers ran
|
||||
and their results**, what was deliberately not done, the commit-to-issue
|
||||
table, and `Closes #n`. `Closes` also sits one-per-line in a commit body
|
||||
**inside the branch** — both, regardless of merge strategy, because the
|
||||
pairing was measured.
|
||||
|
||||
Poll CI until `check` and `e2e` finish. On failure: read the log via
|
||||
`GET /api/v1/repos/yonlu/yellowjacket/actions/runs/<run>/jobs` (per-step)
|
||||
and `…/actions/jobs/<id>/logs` (full). Fix on the branch. **Two
|
||||
consecutive identical failures = stop**: comment what is known on the
|
||||
PR and the issue, leave both, report. Do not burn ticks on a red wall.
|
||||
|
||||
## Merge authority
|
||||
|
||||
Merge when, and only when, **all** hold:
|
||||
|
||||
- the PR was opened by this loop (it is in the state file's index);
|
||||
- the protection contexts `CI / check` and `CI / e2e` are green on the
|
||||
PR's head, read from the API, not from the PR page's badge;
|
||||
- the PR reports mergeable;
|
||||
- the critique leg ran and no open blocker stands.
|
||||
|
||||
```
|
||||
curl -sS -X POST -H "Authorization: token $GITEA_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
https://git.ljones.me/api/v1/repos/yonlu/yellowjacket/pulls/<n>/merge \
|
||||
-d '{"Do":"merge","merge_message_field":"default","force_manually_merged":false}'
|
||||
```
|
||||
|
||||
Afterwards: `scripts/issue.sh list --state open` and check the footer
|
||||
took. Close stragglers with `issue.sh close`, naming the merge commit.
|
||||
`unclaim.yml` handles the label; it is not instant; reopening does not
|
||||
restore it. Merging fans out to nothing (releases are the manual
|
||||
`release.yml`, which the loop never runs) — the criticism stands before
|
||||
the merge because nothing stands after it.
|
||||
|
||||
## Rails — the loop's absolute rules
|
||||
|
||||
1. **Touch only its own.** Issues it claimed, branches it made, PRs it
|
||||
opened. `issue.sh claim` enforces the front gate; never work around a
|
||||
refusal.
|
||||
2. **One writer, one issue.** The loop worktree is the only dirty tree.
|
||||
3. **Never merge a PR it did not open.** Any merge that violates this is
|
||||
a hard stop.
|
||||
4. **Human work is holy.** Human branches, PRs, assignees: leave exactly
|
||||
as found. Cleanup never names them.
|
||||
5. **The token is identity.** If GITEA_TOKEN misbehaves, the tick stops.
|
||||
6. **New findings are new issues**, never scope creep. The tracker
|
||||
vocabulary (`Kind/`, `Area/`, `Priority/`) stays intact in one
|
||||
taxonomy; use `scripts/issue.sh new` with correct labels.
|
||||
7. **Conventional Commits**, enforced by `scripts/commit-check.sh`; the
|
||||
type list and `.releaserc.yml`'s must agree — a loop commit is a
|
||||
release grammar token even after months of no manual releases.
|
||||
8. **Tiers over vibes.** `yellowjacket-dev`'s tier table decides what a
|
||||
change must pass; a skipped tier is stated, never silent.
|
||||
9. **Two strikes on CI, three rounds of critique, one kimi a day.** The
|
||||
loop's patience is finite on purpose.
|
||||
10. **Every leg writes its evidence.** A leg that leaves nothing behind
|
||||
is indistinguishable from a leg that did not run — which is how the
|
||||
next tick re-does it.
|
||||
11. **The loop may not re-schedule itself** (the scheduler refuses it
|
||||
anyway — treat as an invariant, not a limitation).
|
||||
12. **Drain means drain.** `drain: true` = finish in flight, take
|
||||
nothing new, then stop.
|
||||
|
||||
## Emulator mode
|
||||
|
||||
Flag `emulator: true` in the state file **and** an already-booted
|
||||
emulator (`adb devices` answers) opts in: `make android` (build), `make
|
||||
android-install`, `make android-smoke` (crash check — the same pid
|
||||
surviving is the only signal that means started), `make
|
||||
android-screenshot` and `make android-eval` as evidence for `visual`.
|
||||
The loop never boots or stops an emulator; that is the user's machine.
|
||||
Device-only issues stay open under either setting. One-time setup the
|
||||
user performs: `make android-setup` (~3.5 GB, creates the `yj-test`
|
||||
AVD), then `make android-emulator` per session.
|
||||
|
||||
## ON / OFF / drain
|
||||
|
||||
- **Worktree:** `git worktree add ~/.paseo/worktrees/loop/jumpy-hound
|
||||
origin/main` (from any clone; branch from origin/main in the loop
|
||||
tree, never `git checkout main`).
|
||||
- **Session:** pi in that worktree, `/name loop`. Add the job via
|
||||
`/schedule-prompt` (name `yj-loop`, cron
|
||||
`0 0 10-18 * * 1-5`, prompt: "Read `.pi/skills/yj-loop/SKILL.md` and
|
||||
run exactly one tick. Stop.") — session-bound by default.
|
||||
- **OFF:** toggle the job, or close the session. **ON:** `pi --resume
|
||||
loop` in the worktree, job enabled. Courses of the tick appear in
|
||||
that session's transcript.
|
||||
- **Tune in:** the same resume. Talk to it only between; a tick is
|
||||
atomic.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- `issue.sh: GITEA_TOKEN is not set` or a 401 — the token is the whole
|
||||
identity (rails 5). Stop, do not fall back to anything.
|
||||
- `gitea_ci`'s job log 404s — the REST endpoints above answer; this is
|
||||
a Gitea build, not a fault.
|
||||
- A spec fails that the tier doc says can fail from stale backend state
|
||||
— restart the app tier before believing it (`yellowjacket-dev`).
|
||||
- A tick that "did nothing" — reconcile again; the tracker usually says
|
||||
which leg it really is.
|
||||
- The job did not fire — the scheduler fires only while a session is
|
||||
open in its directory (documented); "the loop is off" is the correct
|
||||
reading, not a bug.
|
||||
@@ -1,228 +0,0 @@
|
||||
# 020 — The autonomous backlog loop
|
||||
|
||||
**Issue:** #236 (`Kind/Enhancement`, `Priority/Low`)
|
||||
**Status:** active — phase 0, supervised pilot
|
||||
**Relates:** #73 (the roadmap the loop follows), plan 005 (the harness the
|
||||
loop drives). Cost and model-tier doctrine is the `pi-session-reference`
|
||||
card handed to the session that designed this; the loop's copies of it
|
||||
are deliberate one-paragraph summaries, not the authority.
|
||||
|
||||
A pi coding-agent configuration that, toggled on, works the Gitea tracker
|
||||
one issue at a time — triage, claim, plan, implement, validate, critique,
|
||||
PR, CI, merge, verify-close, diary — and then does it again. The tracker is
|
||||
the state machine: whoever reads Gitea sees exactly where the loop is,
|
||||
which is the property this document's rails exist to protect.
|
||||
|
||||
---
|
||||
|
||||
## The shape: a crank, not a resident brain
|
||||
|
||||
Half the design is that **nothing lives in a conversation**. Each tick is a
|
||||
fresh, bounded unit of work; every transition writes evidence to Gitea
|
||||
(label, comment, branch, PR) or to the loop's own state file; a tick that
|
||||
dies mid-leg loses nothing, because the next tick resumes from what Gitea
|
||||
says.
|
||||
|
||||
The other half is that **no leg trusts the one before it**. The worker
|
||||
implements from the plan, not from the issue alone; the validator checks
|
||||
the *claim*, not the green CI row; the merger merges only after reading the
|
||||
protection contexts itself; the diary leg is what makes the next issue's
|
||||
triage cheaper.
|
||||
|
||||
One issue in flight at a time. That is a pacing decision, not a
|
||||
concurrency limit of the tooling — CI has a capacity-1 runner and the e2e
|
||||
tier owns one headless port on this machine, so two writers would serialize
|
||||
on infrastructure they cannot see and appear to be doing fine.
|
||||
|
||||
## The state machine
|
||||
|
||||
| Leg | Writes | Actor / model |
|
||||
|---|---|---|
|
||||
| reconcile | — | orchestrator + `inspect` (mimo-v2.5) |
|
||||
| select | nothing on the tracker; decision logged in the tick transcript | `select` (glm-5.3) |
|
||||
| claim | assignee + `Status/In Progress` + comment naming branch & approach | `scripts/issue.sh claim` |
|
||||
| plan | plan as an issue comment | `plan` (glm-5.3) |
|
||||
| implement | commits on the issue branch, in the loop worktree | `work` (qwen/deepseek-v4-pro-0813) |
|
||||
| validate | verification evidence in the handoff | `validate` (glm-5.3), `visual` (glm-5.3-flash) for screenshots |
|
||||
| critique | review findings; fix commits | `review` (glm-5.3) + `diffreview` (qwen) + fix round by `work` |
|
||||
| ship | push, PR with body contract, CI read + fixes | orchestrator + `scribe` (mimo-v2.5) |
|
||||
| merge | the merge; post-merge issue verification | orchestrator |
|
||||
| diary | `.pi/journal.md`, `CLAUDE.md` if structural | `scribe` |
|
||||
| housekeep | stale-branch/PR cleanup, state-file prune | orchestrator |
|
||||
|
||||
### Legs that are the orchestrator's alone
|
||||
|
||||
The orchestrator (the loop session) delegates every deliberative leg and
|
||||
keeps three for itself because they are script-shaped and must not be
|
||||
re-implemented by a model: claim (`issue.sh claim`, which refuses when
|
||||
someone else holds the issue — the backstop), merge (API calls below), and
|
||||
housekeep (branch deletion). If a tick does nothing else, it reconciles.
|
||||
|
||||
## Model routing
|
||||
|
||||
The routing authority is the card's four tiers, reproduced here as the
|
||||
loop's assignment, not as an argument:
|
||||
|
||||
- **T0 `go/mimo-v2.5`** — mechanical gathering, commit/PR/journal prose,
|
||||
any fan-out. Effectively free; wrong only where wrongness costs a
|
||||
debugging session, so nothing above takes its word for a *fact*.
|
||||
- **T1 `qwen/deepseek-v4-pro-0813`** — implement-from-a-written-plan,
|
||||
understood-diff review, the orchestrator itself. The default session
|
||||
model; half price 10:00–20:00 EDT, which the cron is shaped around.
|
||||
- **T2 `glm/glm-5.3`** — repo-scale reasoning: selection, planning,
|
||||
consequences review, validation judgement. Weekly credits with no
|
||||
rollover: the loop draws them every week by construction, which is the
|
||||
correct posture. **`glm-5.3-flash`** for anything multimodal
|
||||
(screenshots, UI inspection).
|
||||
- **T3 `go/kimi-k3`** — escalation only: two lower tiers already failed,
|
||||
or the issue is a named gnarly one. A fresh session seeded with the
|
||||
failing tier's own summary, never a mid-session switch, never parallel,
|
||||
at most once per day.
|
||||
|
||||
The invariant behind all four, from the card: **routing down is cheap,
|
||||
routing up is expensive.** An implementation that stalls is escalated by
|
||||
having the T1 session write *what it tried, what failed, what it observed*
|
||||
and handing that to a new session one tier up. Escalating a session in
|
||||
place is forbidden in both directions.
|
||||
|
||||
Fan-out is allowed on T0 and T1 only (the Go plan's $12/5 h constraint
|
||||
makes T3 fan-out self-defeating). Critique is the one standing fan-out:
|
||||
two reviewers, two angles, one synthesis.
|
||||
|
||||
## Scheduling
|
||||
|
||||
`0 0 10-18 * * 1-5` (local = EDT): hourly on weekdays inside Qwen's
|
||||
half-price window, clear of the card's ⚠ 2–6am band (DeepSeek peaks, GLM
|
||||
loses its off-peak discount — the window the old `yj-backlog` cron sat in,
|
||||
which this replaces as the loop supersedes it).
|
||||
|
||||
- A tick takes a lock (`/tmp/yj-loop.lock`, PID + timestamp). An overrun
|
||||
tick makes the next fire exit immediately; serialization survives
|
||||
whatever the scheduler does with overlapping fires.
|
||||
- ~9 ticks/day; an issue is 2–5 ticks; **one to two issues per day** is
|
||||
the natural rate. That also paces the bills without a budget flag.
|
||||
- The port check is part of reconcile: if `34115` is occupied, the tick
|
||||
refuses any leg that needs the headless app and defers to the next
|
||||
tick, without complaint. A human's interactive tier always wins.
|
||||
|
||||
## Runtime and ON/OFF
|
||||
|
||||
The scheduler (`pi-schedule-prompt`) fires only while a pi session is open
|
||||
in the job's directory — that limitation is the switch:
|
||||
|
||||
- **Worktree:** `git worktree add` a dedicated clone at
|
||||
`~/.paseo/worktrees/loop/jumpy-hound`. Loop edits happen only there; a
|
||||
dirty tree there is the loop's business and nobody else's.
|
||||
- **Session:** pi in that worktree, `/name loop`. The job is bound to that
|
||||
session, so another pi elsewhere in the same directory does not
|
||||
double-fire it.
|
||||
- **ON:** resume the loop session (`pi --resume loop`) and enable the job.
|
||||
**OFF:** toggle the job off in `/schedule-prompt`, or close the session.
|
||||
**Drain** (stop taking new work, finish in flight): set `drain: true` in
|
||||
the state file.
|
||||
- **Tune in:** the same `pi --resume loop` — the chat transcript *is* the
|
||||
loop's log, each tick's reasoning inline, each leg reporting in.
|
||||
|
||||
## Identity, claims, and what the loop may touch
|
||||
|
||||
The loop operates **as the owner** via `GITEA_TOKEN` (scopes: `read:user`,
|
||||
`write:issue`, `write:pull`, `write:repository`); pushes ride SSH and need
|
||||
no token. Every tracker comment the loop writes is prefixed `⟦loop⟧`, so
|
||||
the collaborator reads it as the pump and not as a person.
|
||||
|
||||
It may only ever touch work it created: issues it claimed, branches it
|
||||
made, PRs it opened. Two mechanisms make that enforced rather than
|
||||
intentional: `issue.sh claim` refuses an issue somebody else holds, and
|
||||
reconcile checks `git ls-remote --heads origin` so a branch name collision
|
||||
from a concurrent session is caught before the first edit.
|
||||
|
||||
## Merge lifecycle
|
||||
|
||||
- **Only PRs the loop opened.** A collaborator's PR is never merged, never
|
||||
commented on for pressure, never touched.
|
||||
- The gate is the protection rule itself, read from the API: contexts
|
||||
`CI / check*` and `CI / e2e*` green, PR mergeable. (Required approvals
|
||||
is 0 today; if a second person changes protection rules, the merge
|
||||
endpoint refuses and the tick stops and reports — human business.)
|
||||
- `Closes #n` goes **in a commit body inside the branch, one line per
|
||||
issue, and in the PR body**. Both, because a squash route and a merge
|
||||
route parse different texts, and this pairing was measured: a comma
|
||||
list partially matched, five of ten issues.
|
||||
- After merging: verify against `issue.sh list --state open` that the
|
||||
issue actually closed; close any straggler naming the merge commit.
|
||||
`unclaim.yml` strips `Status/In Progress` automatically; it is not
|
||||
instant, and a re-open does not restore it — the verification is
|
||||
against the open list, not against the label.
|
||||
- Merging to `main` fans out to nothing: releases are the manual
|
||||
`release.yml`, which this loop never runs. The blast radius of a
|
||||
merge is the main branch's CI, and the critique leg is what stands
|
||||
before it.
|
||||
|
||||
## Verification contract
|
||||
|
||||
The tier table is `yellowjacket-dev`'s; the loop re-states nothing above
|
||||
it except the *division of duty*: the worker runs the tiers the change
|
||||
demands, and the validator re-reads the issue and checks that the tier
|
||||
evidence actually answers the claim — a green suite that never touched
|
||||
the reported surface is a finding, not a pass. Cosmetics are read by a
|
||||
model that can see (`visual`, the multimodal tier); a change that moves
|
||||
geometry refreshes its `ui-visual` baseline in the same commit.
|
||||
`tsc --noEmit` is part of the gate and nothing else runs it. The e2e app
|
||||
is seeded (`SEED=default`) and stopped after.
|
||||
|
||||
## Android / emulator mode
|
||||
|
||||
The loop is **device-free by default**: issues whose verification is
|
||||
physical-device behaviour stay open for humans (the repo's own tags say
|
||||
which those are). One step of the ladder exists for the rest:
|
||||
|
||||
- `{"emulator": true}` in `.pi/loop/state.json` **plus an already-booted
|
||||
emulator** (`adb devices` answers) opts the loop into building the APK
|
||||
and using `android-smoke` (crash verification), and `android-screenshot`
|
||||
/ `android-eval` as rendering evidence for `visual`.
|
||||
- The loop **never boots or stops an emulator** — that is the user's
|
||||
machine and their gesture. Boot it with `make android-emulator`
|
||||
(one-time `make android-setup`, ~3.5 GB, creates the AVD), and
|
||||
`make android-emulator-stop` when done.
|
||||
- Real-device-only issues are skipped under either setting.
|
||||
|
||||
## Budgets and pacing
|
||||
|
||||
Expected spend: dominated by the T1 implementation leg inside the
|
||||
half-price window (pennies to tens of cents) and T2 on weekly credits;
|
||||
T3 bounded at one fresh call per day. The card's numbers ($12 per rolling
|
||||
5 h, $30/week as burst headroom not allowance, GLM reset weekly) are the
|
||||
sanity cells; the loop's own weekly check compares against them rather
|
||||
than against the month.
|
||||
|
||||
## Cleanup (housekeep leg, once per day)
|
||||
|
||||
- Loop-owned branches whose commits are in `origin/main`: deleted, local
|
||||
and remote.
|
||||
- Loop-owned PRs open >7 days or red on a second identical CI cause:
|
||||
commented with what is known (`⟦loop⟧`), and left — never silently
|
||||
deleted.
|
||||
- Anything not the loop's (assignee, branch, PR): left exactly as found.
|
||||
|
||||
## Pilot phases
|
||||
|
||||
- **P0 — supervised.** One tick, user watching the transcript: reconcile,
|
||||
select, claim, plan. No merge.
|
||||
- **P1 — observed.** Two ticks ending in the loop's first merge, watched
|
||||
through CI → merge → verify-close.
|
||||
- **P2 — unattended.** The schedule left on. Weekly check against the
|
||||
card's two-minute ritual.
|
||||
- **Hard stops** (any of these halts the loop and leaves a comment, never
|
||||
a silent retry): a tick dies twice with no explanation; a merge happens
|
||||
for a PR the loop did not open; spend outside the cells above by 2×.
|
||||
|
||||
## Not now, on purpose
|
||||
|
||||
- **Parallel worktrees** — blocked on e2e's exclusive port; viable only
|
||||
with per-worktree headless ports or CI-only e2e. The shape (
|
||||
supervisor + per-issue worktrees) is the target, not the first cut.
|
||||
- **Weekend batch refactors** — DeepSeek off-peak is real but is a
|
||||
scheduling knob on top of a working pump.
|
||||
- **More chain files** — the critique fan-out is a chain; the rest stay
|
||||
orchestrator-legs until two weeks of unattended runs say which legs
|
||||
are actually fixed-shape.
|
||||
@@ -138,17 +138,6 @@ has started is a second, staler answer to "what are we doing next".
|
||||
Numbering is sequential and stable across status moves (a plan keeps
|
||||
its `NNN-` prefix). Abandoned plans are deleted.
|
||||
|
||||
**The autonomous loop** (plan 020, `.pi/skills/yj-loop/`) is the pi
|
||||
configuration that works the tracker one issue at a time — a cron tick
|
||||
in a dedicated worktree and session, with the tracker labels as its
|
||||
state machine. It claims with `issue.sh` like anyone, merges only PRs
|
||||
it opened once the protection contexts are green, and files what it
|
||||
finds. Its switch is `.pi/schedule-prompts.json` (gitignored): it runs
|
||||
only while that pi session is open, and that limitation is the whole
|
||||
on/off design. Where a loop discovery contradicts this file, this file
|
||||
is wrong and should be fixed by the diary leg — the loop never quietly
|
||||
decides otherwise.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
@@ -673,6 +662,28 @@ rather than renaming them.
|
||||
one of the shell's rows, which is what the skip link is absolutely
|
||||
positioned to avoid.
|
||||
- `config` — TOML-based settings. Settings page uses HTMX + templ for server-rendered HTML fragments.
|
||||
|
||||
**A setter that can reject its argument puts the old value back**, and
|
||||
that is a correctness rule rather than hygiene (#231). `Save()`
|
||||
validates the *whole* config, so a value left behind by a failed write
|
||||
does not merely fail its own call: it fails every later save, of every
|
||||
unrelated setting — theme, launch page, shortcuts, libraries — for the
|
||||
rest of the session. Nothing reaches disk, so a restart clears it,
|
||||
which is exactly what makes the fault invisible and unreportable. One
|
||||
rejected track-list column list was enough to stop the app saving
|
||||
anything at all.
|
||||
|
||||
Two shapes are safe and a third is the trap. A setter that assigns and
|
||||
*then* validates snapshots the field first and restores it on the
|
||||
error path — seven do. `SetLibraryDirectory` is the better shape where
|
||||
the value can be built on its own: it validates a candidate *before*
|
||||
assigning, so there is nothing to undo. And a setter whose argument no
|
||||
validation inspects needs neither — the bools, the favourites playlist
|
||||
id and the shortcut bindings, plus `SetViewVisible`, which refuses an
|
||||
unknown, non-hideable or launch-page view up front so
|
||||
`GeneralConfig.Validate` never sees one it would fail on. Which set a
|
||||
new setter joins is decided by whether its own `Validate` can reject
|
||||
it, not by preference.
|
||||
- `playlist` / `smartplaylist` — Playlist CRUD and rule-based smart playlists.
|
||||
- `mediacontrols` — OS media controls behind one `Handler`: MPRIS over
|
||||
D-Bus on desktop Linux, a MediaSession on Android, a no-op stub
|
||||
|
||||
@@ -303,6 +303,24 @@ func (c *Config) GetLibraryDirectory() string {
|
||||
return string(c.Library.DirectoryPath)
|
||||
}
|
||||
|
||||
// A rejected setter puts the old value back, and that is not tidiness
|
||||
// (#231). Save validates the *whole* config, so a value left behind by
|
||||
// a failed write does not merely fail its own call: it fails every
|
||||
// later save, of every unrelated setting, silently and for the rest of
|
||||
// the session. Nothing reaches disk, so a restart clears it -- which
|
||||
// is exactly what makes the fault hard to see and impossible to report.
|
||||
//
|
||||
// The setters below that assign and then validate therefore snapshot
|
||||
// the field first and restore it on the error path. SetLibraryDirectory
|
||||
// is the other safe shape and the better one where the value can be
|
||||
// built on its own: it validates a candidate *before* assigning
|
||||
// anything, so there is nothing to undo.
|
||||
//
|
||||
// Not every setter needs either. A bool, an int64 and the shortcut
|
||||
// bindings pass through no validation that can reject them, and
|
||||
// SetViewVisible refuses an unknown, non-hideable or launch-page view
|
||||
// up front, so GeneralConfig.Validate never sees one it would fail on.
|
||||
|
||||
// SetLibraryDirectory validates and saves a new library directory,
|
||||
// then emits the LibraryConfigChanged event so listeners (e.g. the
|
||||
// Library scanner) can react.
|
||||
@@ -360,11 +378,14 @@ func (c *Config) SetScanConcurrency(mode string) error {
|
||||
c.Library.ApplyDefaults()
|
||||
}
|
||||
|
||||
previous := c.Library.ScanConcurrency
|
||||
c.Library.ScanConcurrency = library.ScanConcurrency(
|
||||
mode,
|
||||
)
|
||||
|
||||
if err := c.Library.Validate(); err != nil {
|
||||
c.Library.ScanConcurrency = previous
|
||||
|
||||
return fmt.Errorf(
|
||||
"invalid scan concurrency mode: %w", err,
|
||||
)
|
||||
@@ -455,9 +476,12 @@ func (c *Config) SetThemeAccentColor(
|
||||
c.Theme.ApplyDefaults()
|
||||
}
|
||||
|
||||
previous := c.Theme.AccentColor
|
||||
c.Theme.AccentColor = color
|
||||
|
||||
if err := c.Theme.Validate(); err != nil {
|
||||
c.Theme.AccentColor = previous
|
||||
|
||||
return fmt.Errorf(
|
||||
"invalid theme accent color: %w", err,
|
||||
)
|
||||
@@ -488,9 +512,12 @@ func (c *Config) SetThemeBackgroundShade(
|
||||
c.Theme.ApplyDefaults()
|
||||
}
|
||||
|
||||
previous := c.Theme.BackgroundShade
|
||||
c.Theme.BackgroundShade = theme.BackgroundShade(shade)
|
||||
|
||||
if err := c.Theme.Validate(); err != nil {
|
||||
c.Theme.BackgroundShade = previous
|
||||
|
||||
return fmt.Errorf(
|
||||
"invalid theme background shade: %w", err,
|
||||
)
|
||||
@@ -544,9 +571,12 @@ func (c *Config) SetDefaultPage(page string) error {
|
||||
c.General.ApplyDefaults()
|
||||
}
|
||||
|
||||
previous := c.General.DefaultPage
|
||||
c.General.DefaultPage = View(page)
|
||||
|
||||
if err := c.General.Validate(); err != nil {
|
||||
c.General.DefaultPage = previous
|
||||
|
||||
return fmt.Errorf(
|
||||
"invalid default page: %w", err,
|
||||
)
|
||||
@@ -591,9 +621,12 @@ func (c *Config) SetQueueFallback(mode string) error {
|
||||
c.General.ApplyDefaults()
|
||||
}
|
||||
|
||||
previous := c.General.QueueFallback
|
||||
c.General.QueueFallback = QueueFallback(mode)
|
||||
|
||||
if err := c.General.Validate(); err != nil {
|
||||
c.General.QueueFallback = previous
|
||||
|
||||
return fmt.Errorf(
|
||||
"invalid queue fallback: %w", err,
|
||||
)
|
||||
@@ -801,9 +834,12 @@ func (c *Config) SetTrackListColumns(
|
||||
c.TrackList = &tracklist.Config{}
|
||||
}
|
||||
|
||||
previous := c.TrackList.Columns
|
||||
c.TrackList.Columns = columns
|
||||
|
||||
if err := c.TrackList.Validate(); err != nil {
|
||||
c.TrackList.Columns = previous
|
||||
|
||||
return fmt.Errorf(
|
||||
"invalid track-list columns: %w", err,
|
||||
)
|
||||
@@ -901,9 +937,12 @@ func (c *Config) SetFavoritesIconStyle(
|
||||
c.Favorites.ApplyDefaults()
|
||||
}
|
||||
|
||||
previous := c.Favorites.IconStyle
|
||||
c.Favorites.IconStyle = favorites.IconStyle(style)
|
||||
|
||||
if err := c.Favorites.Validate(); err != nil {
|
||||
c.Favorites.IconStyle = previous
|
||||
|
||||
return fmt.Errorf(
|
||||
"invalid favorites icon style: %w", err,
|
||||
)
|
||||
|
||||
@@ -0,0 +1,262 @@
|
||||
package config
|
||||
|
||||
import (
|
||||
"log/slog"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
|
||||
"yellowjacket/backend/library"
|
||||
"yellowjacket/backend/tracklist"
|
||||
)
|
||||
|
||||
// newSavableConfig builds a loaded, valid config in a temp directory,
|
||||
// so Save() writes rather than refusing with errSaveBeforeLoad.
|
||||
//
|
||||
// The library directory is real and set, because Config.Validate only
|
||||
// validates the Library section when DirectoryPath is non-empty -- an
|
||||
// empty one would hide a poisoned ScanConcurrency from the whole-config
|
||||
// save that is the symptom under test.
|
||||
func newSavableConfig(t *testing.T) *Config {
|
||||
t.Helper()
|
||||
|
||||
c := &Config{
|
||||
logger: slog.Default(),
|
||||
filePath: filepath.Join(t.TempDir(), "config.toml"),
|
||||
Library: &library.Config{
|
||||
DirectoryPath: library.Directory(t.TempDir()),
|
||||
},
|
||||
}
|
||||
|
||||
c.applyDefaults()
|
||||
|
||||
if err := c.Load(); err != nil {
|
||||
t.Fatalf("Load() error: %v", err)
|
||||
}
|
||||
|
||||
if err := c.Save(); err != nil {
|
||||
t.Fatalf("Save() on a fresh config error: %v", err)
|
||||
}
|
||||
|
||||
return c
|
||||
}
|
||||
|
||||
// TestSetterRejectionDoesNotPoisonTheConfig is the whole of #231.
|
||||
//
|
||||
// Every setter here assigns to the in-memory config and then validates.
|
||||
// When the validation rejects the argument, the rejected value has to go
|
||||
// back -- not because the caller sees it (it gets an error either way),
|
||||
// but because Config.Save() validates the *whole* config. A value left
|
||||
// behind by a failed setter therefore fails every later save, of every
|
||||
// unrelated setting, silently and for the rest of the session.
|
||||
//
|
||||
// So each case asserts three things in order: the setter reports the
|
||||
// error, the getter still reports the old value, and an unrelated save
|
||||
// still works. The third is the one the user feels.
|
||||
func TestSetterRejectionDoesNotPoisonTheConfig(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
cases := []struct {
|
||||
name string
|
||||
// reject calls the setter with an argument its own Validate
|
||||
// refuses.
|
||||
reject func(*Config) error
|
||||
// read reports the value the setter writes, so the rollback is
|
||||
// asserted on the config rather than only on the save.
|
||||
read func(*Config) string
|
||||
}{
|
||||
{
|
||||
name: "scan concurrency",
|
||||
reject: func(c *Config) error {
|
||||
return c.SetScanConcurrency("telepathy")
|
||||
},
|
||||
read: (*Config).GetScanConcurrency,
|
||||
},
|
||||
{
|
||||
name: "theme accent colour",
|
||||
reject: func(c *Config) error {
|
||||
return c.SetThemeAccentColor("not-a-hex")
|
||||
},
|
||||
read: (*Config).GetThemeAccentColor,
|
||||
},
|
||||
{
|
||||
name: "theme background shade",
|
||||
reject: func(c *Config) error {
|
||||
return c.SetThemeBackgroundShade("chartreuse")
|
||||
},
|
||||
read: (*Config).GetThemeBackgroundShade,
|
||||
},
|
||||
{
|
||||
name: "default page",
|
||||
reject: func(c *Config) error {
|
||||
return c.SetDefaultPage("nowhere")
|
||||
},
|
||||
read: (*Config).GetDefaultPage,
|
||||
},
|
||||
{
|
||||
name: "queue fallback",
|
||||
reject: func(c *Config) error {
|
||||
return c.SetQueueFallback("improvise")
|
||||
},
|
||||
read: (*Config).GetQueueFallback,
|
||||
},
|
||||
{
|
||||
name: "favorites icon style",
|
||||
reject: func(c *Config) error {
|
||||
return c.SetFavoritesIconStyle("asterisk")
|
||||
},
|
||||
read: (*Config).GetFavoritesIconStyle,
|
||||
},
|
||||
{
|
||||
name: "track-list columns",
|
||||
reject: func(c *Config) error {
|
||||
// titleArtist is a drawing definition, not a
|
||||
// configurable column (#197), so it is exactly what
|
||||
// the frontend used to be able to send.
|
||||
return c.SetTrackListColumns([]tracklist.Column{
|
||||
{ID: "titleArtist"},
|
||||
})
|
||||
},
|
||||
read: func(c *Config) string {
|
||||
return columnIDs(c.GetTrackListColumns())
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "track-list columns, duplicated",
|
||||
reject: func(c *Config) error {
|
||||
// The route #197 closed was one invalid id; a
|
||||
// duplicate is the one still reachable from a client
|
||||
// that assembles the list itself.
|
||||
return c.SetTrackListColumns([]tracklist.Column{
|
||||
{ID: tracklist.ColTrackName},
|
||||
{ID: tracklist.ColTrackName},
|
||||
})
|
||||
},
|
||||
read: func(c *Config) string {
|
||||
return columnIDs(c.GetTrackListColumns())
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
c := newSavableConfig(t)
|
||||
before := tc.read(c)
|
||||
|
||||
if err := tc.reject(c); err == nil {
|
||||
t.Fatal("setter accepted an invalid value, want an error")
|
||||
}
|
||||
|
||||
if after := tc.read(c); after != before {
|
||||
t.Errorf(
|
||||
"value after a rejected write = %q, want the previous %q",
|
||||
after, before,
|
||||
)
|
||||
}
|
||||
|
||||
// The symptom: an unrelated setting can no longer be saved.
|
||||
if err := c.SetPopupVolume(true); err != nil {
|
||||
t.Errorf("an unrelated setter failed after a rejected write: %v", err)
|
||||
}
|
||||
|
||||
if err := c.Save(); err != nil {
|
||||
t.Errorf("Save() failed after a rejected write: %v", err)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestRejectedSetterLeavesNothingOnDisk pairs with the sweep above: the
|
||||
// rollback must not be undone by what the file already holds, so a
|
||||
// config reloaded from disk after a rejected write agrees with memory.
|
||||
func TestRejectedSetterLeavesNothingOnDisk(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
c := newSavableConfig(t)
|
||||
|
||||
if err := c.SetThemeAccentColor("#123456"); err != nil {
|
||||
t.Fatalf("SetThemeAccentColor() error: %v", err)
|
||||
}
|
||||
|
||||
if err := c.SetThemeAccentColor("not-a-hex"); err == nil {
|
||||
t.Fatal("SetThemeAccentColor accepted a non-colour, want an error")
|
||||
}
|
||||
|
||||
reloaded := &Config{logger: slog.Default(), filePath: c.filePath}
|
||||
reloaded.applyDefaults()
|
||||
|
||||
if err := reloaded.Load(); err != nil {
|
||||
t.Fatalf("Load() error: %v", err)
|
||||
}
|
||||
|
||||
if got := reloaded.GetThemeAccentColor(); got != "#123456" {
|
||||
t.Errorf("accent colour on disk = %q, want %q", got, "#123456")
|
||||
}
|
||||
|
||||
if c.GetThemeAccentColor() != reloaded.GetThemeAccentColor() {
|
||||
t.Errorf(
|
||||
"in-memory accent %q disagrees with disk %q after a rejected write",
|
||||
c.GetThemeAccentColor(), reloaded.GetThemeAccentColor(),
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSetLibraryDirectoryValidatesBeforeAssigning pins the precedent the
|
||||
// seven rolled-back setters follow: this one has always built and
|
||||
// validated a candidate before assigning, so a bad path never reaches
|
||||
// the config at all.
|
||||
func TestSetLibraryDirectoryValidatesBeforeAssigning(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
c := newSavableConfig(t)
|
||||
before := c.GetLibraryDirectory()
|
||||
|
||||
if err := c.SetLibraryDirectory(filepath.Join(t.TempDir(), "no-such-dir")); err == nil {
|
||||
t.Fatal("SetLibraryDirectory accepted a missing directory, want an error")
|
||||
}
|
||||
|
||||
if after := c.GetLibraryDirectory(); after != before {
|
||||
t.Errorf("library directory = %q, want the previous %q", after, before)
|
||||
}
|
||||
|
||||
if err := c.Save(); err != nil {
|
||||
t.Errorf("Save() failed after a rejected library directory: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSetViewVisibleRefusesBeforeAssigning covers the other setter left
|
||||
// out of the rollback pass: it guards its own argument up front, so
|
||||
// GeneralConfig.Validate never sees a view it would reject.
|
||||
func TestSetViewVisibleRefusesBeforeAssigning(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
c := newSavableConfig(t)
|
||||
|
||||
if err := c.SetViewVisible("no-such-view", false); err == nil {
|
||||
t.Fatal("SetViewVisible accepted an unknown view, want an error")
|
||||
}
|
||||
|
||||
if err := c.SetViewVisible(c.GetDefaultPage(), false); err == nil {
|
||||
t.Fatal("SetViewVisible hid the launch page, want an error")
|
||||
}
|
||||
|
||||
if err := c.Save(); err != nil {
|
||||
t.Errorf("Save() failed after a refused view visibility change: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// columnIDs renders a column list for comparison in the table above.
|
||||
func columnIDs(cols []tracklist.Column) string {
|
||||
ids := make([]byte, 0, len(cols)*8)
|
||||
|
||||
for i, col := range cols {
|
||||
if i > 0 {
|
||||
ids = append(ids, ',')
|
||||
}
|
||||
|
||||
ids = append(ids, col.ID...)
|
||||
}
|
||||
|
||||
return string(ids)
|
||||
}
|
||||
Reference in New Issue
Block a user