hjozwiak
f44d0144bf
Maintainer decision, 2026-11-02: the core implementation and basic live behavior are sufficient for this stage. The original exhaustive done checklist was not fully satisfied and the contract is not marked Final; unfinished verification and known failures remain visible as future work.
611 lines
29 KiB
Markdown
611 lines
29 KiB
Markdown
# Wine/Proton phase handoffs
|
|
|
|
Status: Draft execution ledger. This document is operational, not
|
|
normative. The settled decisions, scope boundary, and done checklist
|
|
live in [wine-proton.md](wine-proton.md); if this handoff document and
|
|
that contract ever disagree, the contract wins and this document must
|
|
be corrected.
|
|
|
|
Creating a branch or a session does not activate a phase. A phase
|
|
starts only when the maintainer explicitly activates it in that
|
|
phase's session.
|
|
|
|
## Branch and session model
|
|
|
|
- Keep each repository's `hunter` branch as the public integration
|
|
branch. Do implementation work only on the active phase branch.
|
|
- Merge a phase into `hunter` only after its tests and human review
|
|
pass and the maintainer says that step may land. Do not merge phase
|
|
branches directly into `testing`; `testing` receives the work only
|
|
through the maintainer's chosen later integration from `hunter`.
|
|
- Create one fresh Muse Code session per phase, just in time. Do not
|
|
fork phase sessions from the long planning session; a fork inherits
|
|
its history, while a fresh session can be briefed from the contract
|
|
and the relevant phase entry below.
|
|
- A lean coordinator session may track status and review handoffs,
|
|
but it should not be a second writer. Name live sessions stably,
|
|
for example `wine-master-<unique-suffix>` and
|
|
`wine-<phase>-<unique-suffix>`, so they can be found again.
|
|
- A Muse session does not own a Git branch or checkout. If two
|
|
writing sessions are live at once, each needs its own worktree. If
|
|
work is strictly serial in one checkout, the active session must
|
|
verify the repository, branch, and working-tree state before it
|
|
edits anything.
|
|
- Local graph and patch artifacts are not phase deliverables. Leave
|
|
untracked `graphify-out/`, format-patch files, and other local
|
|
material untouched and unstaged unless the maintainer opens a
|
|
separate hygiene task for them.
|
|
|
|
## Maintainer amendments for this batch (2026-11-01, master session)
|
|
|
|
These rulings override conflicting text below and conflicting
|
|
repository synchronization procedure for this batch of work only.
|
|
Subordinate (phase) sessions must honor them:
|
|
|
|
- Cross-repository work is permitted. A phase session may touch both
|
|
Cthulhu and wine-access as its scope requires; the two repositories
|
|
are not gated apart for this batch.
|
|
- Serial work in the single existing checkout of each repository is
|
|
the approved model, for coherent interactive validation and
|
|
testing. Separate worktrees are not required. The active session
|
|
must still verify repository, branch, and working-tree state
|
|
before editing.
|
|
- Synchronization is waived for this batch. Do not run
|
|
`git pull --ff-only`, `git fetch`, or merges of `origin/testing`
|
|
or `hunter`, and do not "refresh" a placeholder branch, whether
|
|
repository guidelines (`AGENTS.md`, `CONTRIBUTING.md`) or this
|
|
ledger's phase entries say to. Those instructions are to be
|
|
disregarded by subordinate sessions for this batch. Start from
|
|
the recorded branch tips; if a branch lacks a named prerequisite
|
|
commit, stop and report to the master session instead of fixing
|
|
it by merging.
|
|
- Pre-Phase-0 work is stacked under the Phase 0 commits: both
|
|
repositories' phase branches sit on their then-current `hunter`
|
|
tips, and later sessions pick that base up from the branch tips.
|
|
At the maintainer's direction the master session fast-forward
|
|
merged wine-access `wine/native-hook-exclusions` (`78b70e1`) into
|
|
`hunter` and stacked `wine/ready-and-spawn-evidence` on it. No
|
|
push was made. Cthulhu needed no merge: `hunter` and every
|
|
placeholder already share `6ed0e36`.
|
|
- The master/coordinator session may update this ledger once a
|
|
phase handoff report is accepted.
|
|
|
|
## Known branch state when this ledger was created
|
|
|
|
Recorded on 2026-11-01. Re-verify every value when a phase is
|
|
activated; this section is a snapshot, not a substitute for Git.
|
|
|
|
### Cthulhu
|
|
|
|
- `hunter`: `6ed0e36`, seven commits ahead of `origin/hunter` and
|
|
then equal to `origin/testing`.
|
|
- Placeholder branches, all also at `6ed0e36` when created:
|
|
`wine/ready-and-spawn-evidence`, `wine/live-settings`,
|
|
`wine/preferences-tab`, and `wine/verification`.
|
|
- The contract was an untracked working-tree file when the branches
|
|
were created, so it followed checkouts in this working tree rather
|
|
than belonging to any one branch's history.
|
|
|
|
### Wine-access
|
|
|
|
- `hunter`: `0db42de`, equal to `origin/hunter` when checked.
|
|
- `wine/native-hook-exclusions`: `78b70e1`
|
|
("Add native per-program hook exclusions"), committed locally and
|
|
not yet landed on `hunter`.
|
|
- `wine/ready-and-spawn-evidence`: `0db42de`; it does not yet contain
|
|
`78b70e1`.
|
|
|
|
Superseded for wine-access by the Phase 0 merges recorded in the
|
|
maintainer amendments above: `hunter`,
|
|
`wine/native-hook-exclusions`, and `wine/ready-and-spawn-evidence`
|
|
all stand at `78b70e1`, not pushed.
|
|
|
|
## Phase activation checklist
|
|
|
|
At the start of every phase session:
|
|
|
|
1. Read the repository guidelines for each repository the phase will
|
|
touch, then read the contract decisions named in the phase entry.
|
|
2. Inspect `git status --short --branch` in each touched repository.
|
|
Preserve unrelated changes and untracked files; never make the
|
|
tree look clean by discarding, stashing, or hiding them.
|
|
3. Confirm the checked-out branch is exactly the branch named for
|
|
the phase. Stop if it is `hunter`, another phase branch, or a
|
|
different worktree than the session was briefed for.
|
|
4. Confirm the phase's base includes every prerequisite commit named
|
|
below. Per the maintainer amendments above, synchronization is
|
|
waived for this batch: do not pull, fetch, refresh, recreate, or
|
|
merge other branches to repair a stale base. If a prerequisite
|
|
commit is missing, stop and report to the master session.
|
|
5. Record the starting commit of each touched repository in the
|
|
phase's handoff notes before editing.
|
|
6. Work only inside the phase scope. Do not commit, merge, push, or
|
|
announce readiness to another maintainer unless the maintainer
|
|
explicitly asks for that exact act in that session.
|
|
|
|
## Phase index
|
|
|
|
| Phase | Purpose | Cthulhu branch | Wine-access branch | Status |
|
|
|---|---|---|---|---|
|
|
| 0 | Native exclusion foundation | none | `wine/native-hook-exclusions` | Fast-forward merged into wine-access `hunter`; not pushed |
|
|
| 1 | Ready record, spawn evidence, mixed-prefix spawn semantics | `wine/ready-and-spawn-evidence` | `wine/ready-and-spawn-evidence` | Accepted and merged into `hunter` in both repositories; not pushed |
|
|
| 2 | Live Wine settings | `wine/live-settings` | none | Accepted and merged into `hunter`; not pushed |
|
|
| 3 | Wine preferences tab | `wine/preferences-tab` | none | Accepted and merged into `hunter`; not pushed |
|
|
| 4 | Live verification and final results | `wine/verification` | Defect branch only for a proven helper cause | Closed by maintainer as accepted with known limitations, 2026-11-02; original checklist not fully satisfied; not pushed |
|
|
|
|
## Phase 0: native hook-exclusions foundation
|
|
|
|
Status: committed locally on `wine/native-hook-exclusions` as
|
|
`78b70e1`. On 2026-11-01, at the maintainer's direction, the master
|
|
session fast-forward merged it into wine-access `hunter` and
|
|
fast-forward stacked `wine/ready-and-spawn-evidence` on the same
|
|
commit. Not pushed.
|
|
|
|
Contents: the helper parses repeated `--exclude-hook-program`
|
|
arguments, withholds foreground native hooks from listed processes,
|
|
suppresses dialog reading for their windows, forwards the list to
|
|
the 32-bit hook host, and the then-current Orca extension emits the
|
|
flags. Native and manager regression tests and user documentation
|
|
were included.
|
|
|
|
Gate into Phase 1: satisfied. `78b70e1` is now the tip of
|
|
wine-access `hunter`, `wine/native-hook-exclusions`, and
|
|
`wine/ready-and-spawn-evidence`, so the Phase 1 wine-access base
|
|
contains it. Do not begin Phase 1 wine-access work from a base that
|
|
lacks this commit; if a checkout shows otherwise, stop and report
|
|
to the master session (do not merge to repair it; synchronization
|
|
is waived for this batch).
|
|
|
|
## Phase 1: ready record, spawn evidence, mixed-prefix semantics
|
|
|
|
Status: not started. Contract decisions: 2, 5, 16, 17, 18, 24.
|
|
|
|
Branches: `wine/ready-and-spawn-evidence` in both repositories,
|
|
after the Phase 0 gate above and after the Cthulhu branch has been
|
|
refreshed from the then-current `hunter`.
|
|
|
|
In scope:
|
|
|
|
- Wine-access helper only: add the `hook_exclusions` count to the
|
|
ready record, with targeted helper coverage. No Orca manager work.
|
|
- Cthulhu: recognize the plain exclusion-count startup line as info,
|
|
keep the invalid-exclusion line a warning, parse the ready count,
|
|
and include the mirrored `programs=[...] extra=[...]` text in the
|
|
helper-start record.
|
|
- Cthulhu: stop passing prefix-wide `--no-dialog-reader` merely
|
|
because a listed program is present. Other programs in the prefix
|
|
retain dialog reading while the listed program is gated natively.
|
|
- Cthulhu: retain wholesale mode only for the global
|
|
controller-only switch, the environment override, and a helper
|
|
whose ready record does not confirm the exclusions sent. Remember
|
|
an unconfirmed binary so later spawns do not double-start.
|
|
- Cthulhu: when a newly listed, currently discovered program lacks
|
|
its flag in the running helper, restart that helper once in the
|
|
same mode to deliver the flag. Never downgrade a running helper
|
|
when a listing is removed or the global switch is cleared.
|
|
|
|
Out of scope: live-settings plumbing beyond what spawn decisions
|
|
already read, the preferences tab, any new D-Bus protocol surface,
|
|
and any Orca change or Orca acceptance gate.
|
|
|
|
Required evidence before handoff:
|
|
|
|
- Focused Cthulhu tests for diagnostics, spawn arguments, and the
|
|
mixed-prefix transition: launcher only, listed game appears,
|
|
ordinary program remains readable by construction of the launch
|
|
arguments and mode, listed game disappears without a downgrade.
|
|
- The wine-access helper build and CTest suite.
|
|
- Test suites for every other Cthulhu package actually touched.
|
|
- A maintainer-run live smoke check is useful here, but the stage's
|
|
formal live acceptance remains Phase 4.
|
|
|
|
Stop boundary: report the diff and evidence. Do not proceed into
|
|
live settings or preferences work in the same session.
|
|
|
|
### Accepted handoff (2026-11-01)
|
|
|
|
- Session: `wine-1-corpsegrinder` (`fir-aphelion`,
|
|
01a19a46-8ac2-7e80-b847-5a8574f85dd9); coordinated from the master
|
|
session (`still-enceladus`).
|
|
- Starting commits: Cthulhu `6ed0e36`; wine-access `78b70e1`.
|
|
- Committed after maintainer acceptance: Cthulhu `7109328`
|
|
("Add Wine ready-record and mixed-prefix spawn semantics") on
|
|
`wine/ready-and-spawn-evidence`, 5 files under `internal/wine`,
|
|
+459/-55; wine-access `20d2169` ("Report hook exclusion count in
|
|
ready record") on `wine/ready-and-spawn-evidence`, 3 files,
|
|
+32/-1. This ledger and the contract ride a separate docs commit
|
|
on the Cthulhu phase branch. Both phase branches were then merged
|
|
into `hunter` in their repository at the maintainer's direction.
|
|
Not pushed.
|
|
- Automated evidence (phase session; `internal/wine` suite
|
|
independently re-run green by the master session): race-enabled
|
|
`go test ./internal/wine/` including mixed-prefix,
|
|
unconfirmed-helper, diagnostics, and start-record tests;
|
|
`go build ./...`, `go vet ./internal/wine/`, gofmt clean;
|
|
`go test ./internal/config/`; wine-access build and CTest 7/7.
|
|
One `internal/app` failure (`TestEchoSpeakerSwitchesBothVoicesTransactionally`)
|
|
was reproduced on clean HEAD under the sandbox (unix socket listen
|
|
not permitted) and is recorded as pre-existing environmental, not
|
|
a Phase 1 regression.
|
|
- Live evidence, by kind: installed-binary — maintainer-rebuilt
|
|
Cthulhu from the phase tree. Audible speech — maintainer smoke
|
|
check, 2026-11-01: with Diablo IV running under Proton (app
|
|
2344520) and excluded, `protontricks-launch --appid 2344520
|
|
notepad` spoke in the same prefix, and Diablo IV remained running
|
|
(interval not timed; formal normal-session and per-application
|
|
acceptance remain Phase 4). A first attempt the same evening was
|
|
invalid: it ran a stale pre-Phase-1 reader binary, whose helper
|
|
correctly showed the old wholesale `--no-dialog-reader` behavior.
|
|
Physical input beyond launching, and Braille-display evidence:
|
|
none this phase.
|
|
- Not exercised: full live regression corpus, Braille regression,
|
|
preferences round trip (all Phase 4); full `go test ./...`.
|
|
- Known limitation carried to Phase 2: decision 17's restart is
|
|
implemented and tested, but the governing list is still the
|
|
manager's startup snapshot until live settings land.
|
|
- Ready for maintainer review: yes. Accepted by the maintainer on
|
|
2026-11-01 ("sufficiently satisfied"), who directed the commits
|
|
above and their merge into `hunter` in each repository.
|
|
|
|
## Phase 2: live Wine settings
|
|
|
|
Status: not started. Contract decisions: 3, 4, 16, 17, 19.
|
|
|
|
Branch: `wine/live-settings` in Cthulhu only, refreshed from
|
|
`hunter` after Phase 1 has landed there.
|
|
|
|
In scope:
|
|
|
|
- Replace the Wine manager's startup snapshot with the reader's live
|
|
settings, read at poll and spawn, so Apply and equivalent reload
|
|
paths need no reader restart.
|
|
- Read the active/global profile's Wine values only. Per-application
|
|
profile switching must never change which Wine list governs a
|
|
prefix.
|
|
- Preserve decision 17's "at the moment it matters" restart for a
|
|
newly listed running program, and the absolute no-downgrade rule
|
|
for removals.
|
|
- Exercise the behavior through TOML/settings application before the
|
|
preferences tab exists.
|
|
|
|
Out of scope: any preferences UI, any Orca work, and any helper
|
|
protocol change.
|
|
|
|
Required evidence: focused tests proving that additions take effect
|
|
without a reader restart, removals do not downgrade a running
|
|
helper, and moving focus between applications with different
|
|
profiles cannot change the governing Wine list.
|
|
|
|
Stop boundary: report the diff and evidence. Do not begin the
|
|
preferences tab in the same session.
|
|
|
|
### Accepted handoff (2026-11-01)
|
|
|
|
- Session: `wine-2-jefferson` (`fallow-puppis`,
|
|
01a19a90-0c47-71a3-931e-404257a1fefe); coordinated from the master
|
|
session (`still-enceladus`).
|
|
- Starting commit: Cthulhu `a60a251` on `wine/live-settings`.
|
|
Wine-access untouched (Cthulhu-only phase).
|
|
- Committed after maintainer acceptance: Cthulhu `9a10a15`
|
|
("Read Wine settings live at poll and spawn"), 13 files,
|
|
+327/-51, then merged into `hunter` at the maintainer's
|
|
direction. This ledger update rides a separate docs commit on
|
|
the phase branch. Not pushed.
|
|
- Behavior: the manager reads a live global-only Wine snapshot once
|
|
per poll and uses it for that poll's restart/spawn decisions;
|
|
global applies republish it (`setGlobalSettings`), per-application
|
|
profile switching never does. Decision 17 restart-on-addition and
|
|
the absolute no-downgrade rule are preserved and now live-driven.
|
|
- Automated evidence (phase session; `internal/wine`,
|
|
`internal/config`, the focused app live-settings tests, `go vet`,
|
|
and gofmt independently re-run green by the master session at
|
|
landing): race-enabled wine suite including live-source
|
|
transitions; TOML → config store → global apply test proving an
|
|
addition governs the same manager with no reader restart and that
|
|
application-profile switching cannot change the governing list;
|
|
build and brlapi-tagged wine/config suites. One `internal/app`
|
|
failure (`TestEchoSpeakerSwitchesBothVoicesTransactionally`,
|
|
sandbox unix-socket restriction) reproduced on clean `a60a251`;
|
|
recorded as pre-existing environmental, as in Phase 1.
|
|
- Live evidence, by kind: installed-binary — maintainer-rebuilt
|
|
Cthulhu from the phase tree. Audible speech — maintainer smoke,
|
|
2026-11-01: baseline Wine Notepad read normally beside Diablo IV;
|
|
after adding Notepad itself to the exclusions and reloading the
|
|
reader, Notepad no longer spoke (expected native gating); after
|
|
removing it and reopening, reading returned. An attempt to edit
|
|
the settings file externally while the reader stayed alive did
|
|
not take effect; this was investigated and recorded as a
|
|
methodological note, not a defect: neither Go nor legacy Python
|
|
Cthulhu has ever auto-reloaded the main settings file on external
|
|
edit (legacy reloads on explicit triggers such as preferences
|
|
Apply/`loadUserSettings`), and decision 3's live trigger is
|
|
preferences Apply, whose Wine values arrive with the Phase 3 tab.
|
|
Physical input beyond launching, and Braille-display evidence:
|
|
none this phase.
|
|
- Not exercised: a user-accessible no-restart Wine addition (no
|
|
Wine control exists until Phase 3; the backend chain is covered
|
|
by the applyNext-level test), full `go test ./...`, the Phase 4
|
|
live corpus and Braille regression.
|
|
- Ready for maintainer review: yes. Accepted by the maintainer on
|
|
2026-11-01 ("a good state for phase two") after the external-edit
|
|
question was settled as above.
|
|
|
|
## Phase 3: Wine preferences tab
|
|
|
|
Status: not started. Contract decisions: 6, 9, 13, 19.
|
|
|
|
Branch: `wine/preferences-tab` in Cthulhu only, refreshed from
|
|
`hunter` after Phase 2 has landed there.
|
|
|
|
In scope:
|
|
|
|
- A global-preferences Wine tab modeled on the Pronunciation page: a
|
|
controller-only checkbox and an editable program list with New
|
|
and Delete.
|
|
- Entries are typed only. No running-program picker and no file
|
|
browser.
|
|
- Validate each entry as edited; name the offending entry and block
|
|
Apply for paths, blanks, and overlong names. Collapse
|
|
case-insensitive duplicates. Never silently drop an invalid entry.
|
|
- Preserve the repository's preferences accessibility rules,
|
|
including focus traversal, popup behavior where applicable, and
|
|
settings round-tripping through persistence and the runtime.
|
|
|
|
Out of scope: per-application Wine editing, any helper or manager
|
|
behavior change, and any Orca work.
|
|
|
|
Required evidence: automated preferences/persistence coverage and a
|
|
keyboard-only round trip in Phase 4—Tab and Shift+Tab through the
|
|
tab, edit the list, Apply, and confirm a newly started helper uses
|
|
the result with no reader restart.
|
|
|
|
Stop boundary: report the diff and evidence. Do not begin the live
|
|
regression in the same session.
|
|
|
|
### Accepted handoff (2026-11-01)
|
|
|
|
- Session: `wine-3-growler` (`vivid-antlia`,
|
|
01a19aed-ae17-7ea0-8e69-0a430cf8c4ab); coordinated from the master
|
|
session (`still-enceladus`).
|
|
- Starting commit: Cthulhu `dc6a961` on `wine/preferences-tab`.
|
|
Wine-access untouched (Cthulhu-only phase).
|
|
- Committed after maintainer acceptance: Cthulhu `75f34ea`
|
|
("Add global Wine preferences tab"), 15 files, +543/-5, then
|
|
merged into `hunter` at the maintainer's direction. This ledger
|
|
update rides a separate docs commit on the phase branch. Not
|
|
pushed.
|
|
- Automated evidence (phase session; preferences/config/wine
|
|
suites, the focused global-apply app test, `go vet`, gofmt, and
|
|
the harness compile independently re-run green by the master
|
|
session at landing): Values round-trip and ownership, duplicate
|
|
collapse, invalid entries rejected by name with prior settings
|
|
intact, global Apply governing the same manager and persisting
|
|
through TOML, app-scoped Apply unable to change governing/global/
|
|
app-profile Wine, build. Full `internal/app` shows only the
|
|
pre-existing sandbox socket failure recorded in Phases 1-2 (not
|
|
re-verified on a clean tree this session).
|
|
- Not exercised by the phase session: the native preferences
|
|
harness could not run in its environment (Xvfb/session failures
|
|
reproduced identically with the pre-Phase-3 binary, so no Phase 3
|
|
signal); the added `CTHULHU_PREFS_WINE_ONLY` mode is unverified.
|
|
Keyboard-only round trip remains Phase 4.
|
|
- Live evidence, by kind: installed-binary — maintainer-rebuilt
|
|
Cthulhu from the phase tree. Audible speech / physical input —
|
|
maintainer flesh test, 2026-11-01, Diablo IV kept alive in the
|
|
same prefix throughout: baseline Notepad reading; adding
|
|
`notepad.exe` in the Wine tab and Applying (no reader restart)
|
|
took effect — save/close dialog no longer spoke, a freshly
|
|
launched Notepad did not read, and Diablo IV survived the
|
|
addition-triggered helper restart. Removing the entry did not
|
|
restore reading while Diablo kept the prefix/helper alive,
|
|
which is the decision 4/17 no-downgrade rule, not a failure.
|
|
Braille-display evidence: none this phase.
|
|
- Recorded caveat, carried to Phase 4 (not a Phase 3 defect): in
|
|
the same live test, the already-running Notepad instance's edit
|
|
text remained readable long after Apply, including after focus
|
|
excursions into Diablo's menus. Master-session code inspection
|
|
confirmed the mechanism: the helper's edit subclass is installed
|
|
in the target process on first focus `SetWindowSubclass` in
|
|
wine-access `edit_hook.c`, module pinned until the control is
|
|
destroyed, so it survives the helper restart; it finds the new
|
|
helper's bridge dynamically by window class, and the new
|
|
helper's text-event presentation in `main.cpp` does not check
|
|
the exclusion list, while dialog WinEvents and new foreground
|
|
hooks are correctly gated. Fresh instances are fully gated.
|
|
Classified as a Phase 0/1 dynamic-addition gap: exclusion is
|
|
enforced at foreground-hook install and dialog presentation, but
|
|
not against a pre-attached edit subclass. Note also that the
|
|
subclass DLL remains mapped in the already-running process until
|
|
it exits, so event gating alone cannot make an already-running
|
|
anti-tamper program retroactively clean; listing before launch
|
|
remains fully protected. Phase 4 must decide the remedy (at
|
|
minimum, presentation-side gating of stale-subclass text events
|
|
in the replacement helper, with a regression: editor focused,
|
|
then listed, helper restarted, focus away and back) and record
|
|
the outcome; Wine review remaining available for listed
|
|
programs is accepted behavior and is not this caveat.
|
|
- Ready for maintainer review: yes. Accepted by the maintainer on
|
|
2026-11-01 with the caveats above recorded ("record these and
|
|
move on").
|
|
|
|
## Phase 4: live verification and final results
|
|
|
|
Status: closed by the maintainer on 2026-11-02 as accepted with
|
|
known limitations, following the interim pause recorded below.
|
|
The original exhaustive done checklist was not fully satisfied,
|
|
and the contract is not Final. Contract decisions: 7, 8, 10, 11,
|
|
12, 14, 15, 24, subject to the maintainer closure amendment in
|
|
the contract.
|
|
|
|
Branch: `wine/verification` in Cthulhu, refreshed from `hunter`
|
|
after Phase 3 has landed there. Open a narrow wine-access defect
|
|
branch only if the regression proves a root cause there; do not
|
|
create one speculatively.
|
|
|
|
Known starting item (recorded at Phase 3 acceptance): the
|
|
pre-attached edit-subclass caveat in the Phase 3 accepted handoff
|
|
above. Its root cause is already localized to wine-access
|
|
(`edit_hook.c` subclass persistence plus ungated text-event
|
|
presentation in `main.cpp`).
|
|
|
|
Session-model amendment, 2026-11-01: the maintainer elected to
|
|
conduct Phase 4 in the master/coordinator session
|
|
(`still-enceladus`) rather than a fresh phase session. The
|
|
maintainer runs the live corpus and reports results; the master
|
|
session records them in the contract and runs automated checks.
|
|
No implementation is planned in this phase; if a regression needs
|
|
code, a fresh narrow defect session is spawned on the relevant
|
|
branch at that point, and the master session remains
|
|
coordinator/recorder rather than implementer.
|
|
|
|
Maintainer disposition, 2026-11-01: **deferred; do not fix in
|
|
Phase 4 and do not open a wine-access defect branch for it.**
|
|
Rationale: tearing down helper/subclass state early risks
|
|
disturbing programs that rely on the live helper's controller and
|
|
review services; fresh processes are fully gated, and restarting
|
|
the prefix restores the expected state. The surprise for an
|
|
unsuspecting user who lists an already-running editor is
|
|
acknowledged and must be recorded honestly in the Phase 4
|
|
results, not silently treated as passing. Future work item,
|
|
outside this stage unless the maintainer reopens it: teach
|
|
wine-access dynamic add/remove of hook exclusions inside the
|
|
running helper—updating foreground gating and silencing or
|
|
detaching pre-attached edit subclasses—rather than relying only
|
|
on helper restart plus fresh-process semantics.
|
|
|
|
Interim results recorded through the 2026-11-02 pause (detail and
|
|
evidence in the contract's Phase 4 results section, currently
|
|
through `d6a54fc` plus this freeze record):
|
|
|
|
- Automated baseline: full Cthulhu suite passes unsandboxed;
|
|
vet, parity, and brlapi-tagged suites pass. Wine-access CTest
|
|
is display-environment sensitive (review-capture versus
|
|
foreground-focus invert between the live desktop and bare
|
|
Xvfb); a single-environment 7/7 run has not been established
|
|
on this Wayland system and may need a purpose-built private
|
|
compositor/XWayland harness rather than an idle live desktop.
|
|
- Passed so far live: Diablo IV, Mistworld, Wine Notepad
|
|
mixed-prefix, keyboard-only preferences round trip, preliminary
|
|
Braille movement/edit navigation, and basic Notepad++
|
|
navigation/editing/Braille tracking.
|
|
- Open at the pause and then superseded as closure gates by the
|
|
maintainer's later accepted-with-limitations decision: the
|
|
localized Wine window-title failure (no fix session or defect
|
|
branch started); Battle.net login not reading, with
|
|
investigation deferred by the maintainer; and completion of
|
|
the physical-Braille pass, including menus. These remain real
|
|
unfinished items, not passes.
|
|
Cut, undo, menu return, copious Unicode, read-only mode, and a
|
|
very long line in Notepad++ were not separately reported and
|
|
are not claimed.
|
|
- The maintainer's debug log used to localize the title failure
|
|
remains a local, uncommitted diagnostic file in the Cthulhu
|
|
checkout; preserve it.
|
|
|
|
Interim Phase 4 documentation/results commits are fast-forwarded
|
|
into `hunter` at this pause so other folks review the same state.
|
|
That fast-forward is not Phase 4 acceptance. Nothing is pushed;
|
|
pushing and marking the contract Final remain separate maintainer
|
|
acts.
|
|
|
|
Fixed live corpus:
|
|
|
|
- Diablo IV: excluded, anti-tamper path; controller speech by ear
|
|
and a normal-length session.
|
|
- Mistworld: controller-endpoint sensitivity; no avoidable helper
|
|
restart while it is running.
|
|
- Wine Notepad: menus and plain edits, including the mixed-prefix
|
|
case while an excluded program is present and unaffected.
|
|
- Notepad++: Scintilla edits.
|
|
- Battle.net bootstrapper: the UIA path.
|
|
|
|
Also required:
|
|
|
|
- The full physical-Braille Wine regression—review cursor, window
|
|
titles, menus, and edits across the corpus—passing clean. Every
|
|
failure blocks, whenever it was introduced, and is fixed wherever
|
|
its root cause lies. There is no baseline carve-out and no escape
|
|
hatch.
|
|
- The keyboard-only preferences round trip from Phase 3.
|
|
- Per-application results written into the contract document, not
|
|
left only in a session transcript or terminal scrollback.
|
|
- Separate reporting of automated, installed-binary,
|
|
physical-input, audible-speech, and Braille-display evidence. A
|
|
log line never substitutes for the maintainer hearing or reading
|
|
the result.
|
|
|
|
If a corpus application becomes unusable for reasons unrelated to
|
|
the reader, stop and have the maintainer choose and record its
|
|
replacement. Never silently shrink the corpus.
|
|
|
|
Stop boundary: the stage is done only when every item in the
|
|
contract's done checklist passes. Marking the contract Final is a
|
|
separate maintainer act after those results are recorded.
|
|
|
|
Closure record, 2026-11-02: the maintainer superseded that stop
|
|
boundary for this stage and closed it as accepted with known
|
|
limitations, judging the original planning more expansive and
|
|
pessimistic than the core objective requires. The delivered
|
|
implementation and basic live behavior are accepted as working
|
|
well enough. Unfinished verification and known failures remain
|
|
visible in the contract and ledger as future work; they were not
|
|
converted into passes. The contract was not marked Final, Phase 4
|
|
was not represented as conventionally complete, and nothing was
|
|
pushed by the master session.
|
|
|
|
## Fresh-session startup template
|
|
|
|
Adapt the phase number, branches, and decision list. Keep the rest
|
|
verbatim unless the maintainer directs otherwise in that session.
|
|
|
|
```text
|
|
Implement only Phase <N> from
|
|
docs/testing/wine-proton-phases.md.
|
|
|
|
Before editing, read the repository guidelines for every repository
|
|
you will touch and the named decisions in
|
|
docs/testing/wine-proton.md. Verify the current directory,
|
|
repository, branch, starting commit, and working-tree state. Stop
|
|
and report if the checkout is not on the exact phase branch, if the
|
|
branch lacks a named prerequisite commit, or if unrelated changes
|
|
would be overwritten. Synchronization is waived for this batch:
|
|
do not run git pull or git fetch, and do not merge origin/testing,
|
|
hunter, or any other branch, even if repository guidelines say to.
|
|
|
|
Work only within this phase's scope. Run the evidence named for the
|
|
phase. Stop at its boundary and report the diff, tests, blockers,
|
|
and anything not exercised. Do not commit, merge, push, switch to
|
|
another phase, or announce readiness unless I explicitly tell you
|
|
to in this session.
|
|
```
|
|
|
|
If the phase session runs in a separate worktree where this file is
|
|
absent, paste the relevant phase entry into its startup prompt or
|
|
point it at the copy in the coordinator's checkout. Do not assume
|
|
an untracked document followed it there.
|
|
|
|
## Handoff report template
|
|
|
|
Each phase session ends by filling this in, in chat and, once the
|
|
maintainer accepts the report, in the phase entry above:
|
|
|
|
```text
|
|
Phase:
|
|
Session name:
|
|
Repositories and branches:
|
|
Starting commits:
|
|
Ending commits or diff state:
|
|
Files changed:
|
|
Behavior changed:
|
|
Tests and checks run, with results:
|
|
Live evidence, reported separately by kind:
|
|
Not exercised, and why:
|
|
Blockers or surprises:
|
|
Ready for maintainer review: yes/no
|
|
Merged into hunter: no, unless explicitly directed otherwise
|
|
```
|
|
|
|
Update statuses only from observed evidence. "Implemented,"
|
|
"committed locally," "merged into hunter," "pushed," and "landed in
|
|
testing" are different states; never use one to imply another.
|