diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 936e838..ed1f41a 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -2,8 +2,9 @@ Repository settings were inspected and recorded on 2026-10-07 before the Headless Community Bridge changes. The repository remains public, owned by -`TenchiNeko`, with `main` as its default branch. No collaborators, teams, -branches, tags, releases, issues, or historical commits were changed. +`TenchiNeko`, with `main` as its default branch. No ownership, collaborator, or +team changes were made, and no branch, tag, release, issue, or historical commit +was deleted. The feature branch was pushed and retained after its PR merge. ## Contribution and merge model @@ -42,14 +43,15 @@ The exact required check name, `build-test-format` (GitHub Actions app id it was required. The successful test-branch run was `37636367335` at commit `3a41dfcffef7b2407340f4b2af15c75e7e5d33f0`. The required `build-test-format` job runs the Release build, tests, formatting, and Windows artifact publish. It -depends on `windows-cli-smoke`, which runs the same automated suite plus the -headless self-test, including its Windows device-enumeration diagnostic, on a -Windows runner. +depends on `windows-cli-smoke`, which runs the automated suite plus the +headless self-test, including Windows device enumeration, on a Windows runner. +PR #1 passed both checks in run `37665751598`; post-merge main run `37666364932` +also passed both checks and uploaded the self-contained Windows artifact. GitHub Actions is enabled and allows all actions. Repository default workflow token permissions are read-only; workflows cannot approve pull requests. The CI workflow needs only repository contents read access. The Windows artifact -will use the workflow artifact service, with no repository contents write +uses the workflow artifact service, with no repository contents write permission. SHA pinning is not required by the current repository setting. ## Approval policy as maintainers emerge diff --git a/HEADLESS_BRIDGE_ACCEPTANCE.md b/HEADLESS_BRIDGE_ACCEPTANCE.md index b2e13ae..0eeac2d 100644 --- a/HEADLESS_BRIDGE_ACCEPTANCE.md +++ b/HEADLESS_BRIDGE_ACCEPTANCE.md @@ -13,9 +13,9 @@ must remain clearly marked for community testing until real evidence exists. | Teaching uses the existing engine for buttons, axes, triggers, hats, skip, calibration, preview, and local save | `DeviceTeachingSession`; replay-to-teaching tests; per-unit calibration is bound to its definition and local interface hash | Verified in deterministic fixtures | | Replayable raw-HID observations exercise the shared capture-to-teaching pipeline | `RawHidInputPipelineTests` replay buttons, D-pad, signed axes, and trigger observations through the existing teaching engine | Verified in deterministic fixtures | | Reports use an allowlist and exclude host identity, paths, serials, IP addresses, unrelated inventory, and credentials | `DeviceTeachingTests` and `RawHidInputPipelineTests` privacy assertions; strict report schema v3 | Verified locally | -| Windows experimental CLI artifact is built from source and contains build identity, dependency notices, and hashes | `.github/workflows/ci.yml`; self-contained `win-x64` publish and VM 101 artifact checks; clean checkout CI uploads the artifact | Local publish verified; required PR CI upload pending | -| Headless self-test covers runtime/script, synthetic teaching, report validation, output diagnostics, and device enumeration | Linux self-test passed 5/5; self-contained Windows CLI self-test passed 5/5 on VM 101 | Linux and Windows VM verified; required PR CI pending | -| Release solution build, all tests, and formatting pass | Local Release build; 47 automated tests; `dotnet format --verify-no-changes`; required clean-checkout CI | Local verified; VM 101 integration passed; clean-checkout CI pending | +| Windows experimental CLI artifact is built from source and contains build identity, dependency notices, and hashes | Main CI run `37666364932` uploaded a self-contained `win-x64` artifact from main commit `1d3d3f78475dc2610574dd1dc94260cf4cfcbbd4`; all 200 files and build identity verified | Verified in GitHub Actions and downloaded artifact | +| Headless self-test covers runtime/script, synthetic teaching, report validation, output diagnostics, and device enumeration | Linux and VM 101 self-tests passed 5/5; Windows smoke job passed on PR and main CI runs | Verified locally, on VM 101, and in CI | +| Release solution build, all tests, and formatting pass | Clean-checkout Release build; 47 tests; `dotnet format --verify-no-changes`; required PR check `build-test-format` passed | Verified locally and in required PR CI | | No P0/P1 issue remains and an independent review is complete | Independent HID review found and then verified fixes for multi-usage ranges and truthful cancellation evidence; no remaining P0/P1 issues found | Verified | | Documentation distinguishes maintainer-tested, contributor-tested, mapping-only, and unverified evidence | README, CONTRIBUTING, HARDWARE_REPORT, HARDWARE_CONTRIBUTION, and PROJECT_STATUS | Verified | @@ -34,7 +34,7 @@ must remain clearly marked for community testing until real evidence exists. teaching engine. They do not claim to replace testing Windows `HidP` parsing against physical report descriptors. -The phase is complete after the required PR CI and final independent review -pass, all implementation and documentation changes are committed through the -repository PR model, and remote `main` is verified at the merged commit. No -tag or GitHub Release is part of this acceptance document. +The phase completed through PR #1, merged by squash. The final independent +review found no P0/P1 issue, required PR checks passed, and remote `main` was +verified at `1d3d3f78475dc2610574dd1dc94260cf4cfcbbd4`. No tag or GitHub Release +was created. diff --git a/HEADLESS_BRIDGE_FINAL_REPORT.md b/HEADLESS_BRIDGE_FINAL_REPORT.md index b1fe264..63130dc 100644 --- a/HEADLESS_BRIDGE_FINAL_REPORT.md +++ b/HEADLESS_BRIDGE_FINAL_REPORT.md @@ -1,103 +1,78 @@ # Headless Community Bridge phase report -**Status: implementation, local validation, and Windows VM integration are -complete; repository CI and artifact acceptance are pending an -authentication-scope update.** This phase has not been marked complete or -merged. +**Status: complete.** The Headless Community Bridge merged to `main` through +PR [#1](https://github.com/TenchiNeko/ControllerOS/pull/1), and the post-merge +commit and CI run were verified. ## Source and governance - Base: public `main` at `a126a250e79411ca3fb8e6ceb55febaa2bf5a8b5`. -- Implementation commits include `4c3b60faba2cf6740d185e5acf4d732cf1dcce77`, - validation record `9d60607cbdc03cb3d93440cffef35e9cafa07bcc`, and reviewed - Windows HID follow-up `deb47eda637bb67bb34b9a9d8719acf171125bc3` on - `feature/headless-community-bridge`. -- `origin/main` remains at `a126a250e79411ca3fb8e6ceb55febaa2bf5a8b5`; the - remote feature branch remains at - `3a41dfcffef7b2407340f4b2af15c75e7e5d33f0` because GitHub rejected the - workflow-file push. -- Alpha 0.1 history is unchanged. No tag or GitHub Release was created. -- Governance settings were read from the live repository and configured as - recorded in GOVERNANCE.md. The authenticated user retained owner/admin - bypass access; ordinary main changes use the PR and required-check model. +- PR head: `aaaf2fba6e811050d5434337ac02068a5d0ef8e0`. +- Squash merge: `1d3d3f78475dc2610574dd1dc94260cf4cfcbbd4`. +- `origin/main` was verified at the squash merge commit. Alpha 0.1 history is + unchanged. No tag or GitHub Release was created. +- Live repository settings confirm public visibility, `main` as default, + squash/rebase enabled and merge commits disabled. Active ruleset + `main-protection` targets `main`, prevents deletion and force-push, requires + resolved review conversations and the exact `build-test-format` check, and + requires zero approvals. Owner/admin user id `256011908` retains `always` + bypass and the API reports `current_user_can_bypass=always`. +- Actions are enabled with read-only default workflow token permissions; the + workflows cannot approve pull requests. No repository administration setting + remained inaccessible. ## Delivered implementation -- Added a Windows headless CLI over existing ControllerOS services, including - device listing/inspection, guided teaching, validation, simulation, report +- Added a headless Windows CLI over existing ControllerOS services for device + listing and inspection, guided teaching, validation, simulation, report export, runtime start/stop, and self-test. -- Added selected-interface Windows HID report capture using Windows HID parser - capabilities, bounded input, cancellation/disconnection handling, scalar - controls, and supported eight-position D-pad hats. -- Routed replay and physical observations through the common raw-HID validation - boundary and existing teaching/calibration engine. Local calibration records - identify their mapping definition and bind to a local hash of the selected - HID interface path. That hash and path are not included in community reports. -- Added strict allowlisted report schema v3, privacy assertions, contribution - instructions, dependency/license/hash notes, and Windows artifact CI - packaging configuration. -- Added an idle runtime input pump so ControllerScript timers advance while a - change-only HID device is quiet. Regression coverage verifies a timed output - is released while the input stream is idle. +- Added selected-interface Windows HID capture with bounded reports, + cancellation/disconnection handling, scalar controls, and supported D-pad + hats. Raw observations use the existing validation and teaching engine. +- Added separate per-unit local calibration and strict allowlisted report + schema v3, privacy tests, contribution instructions, and CI packaging for a + self-contained Windows CLI artifact. +- Added an idle runtime input pump so ControllerScript timers progress while a + change-only HID stream is quiet. -## Local verification +## Validation -- Release solution build succeeded with zero warnings and errors. -- Automated tests passed: 47/47, including multi-usage HID range expansion, - repeated-usage array rejection, and capability expansion bounds. -- `dotnet format ControllerOS.sln --verify-no-changes --no-restore` passed. -- Linux `controlleros self-test --json` passed 5/5 applicable checks; Windows - output and HID enumeration were correctly reported as not applicable. -- A self-contained `win-x64` CLI package from commit - `deb47eda637bb67bb34b9a9d8719acf171125bc3` included the pinned dependency - and license notices. All 200 package files passed hash verification, and - `controlleros self-test --json` passed 5/5 checks on VM 101. -- The self-contained Windows integration probe passed on VM 101: it opened the - selected virtual Xbox HID interface, exposed 14 controls, canceled an idle - input read, verified XInput button/trigger/stick normalization, observed - disconnect neutralization, and confirmed virtual-interface removal. -- `git diff --check` passed. -- A detached clean checkout at `deb47eda637bb67bb34b9a9d8719acf171125bc3` - restored and passed the Release build, 47/47 tests, and format verification. -- Independent review identified a HID multi-usage-range capability gap and an - inaccurate cancellation success message. The parser now expands one scalar - target for each reported usage, keeps repeated-usage value arrays explicitly - unsupported, and bounds expansion to 128 fields. The VM probe now reports - cancellation success only after observing cancellation. Follow-up review - found no remaining P0/P1 issues. This distinction follows Microsoft's HID - documentation: each usage in a range has its own data field, while multiple - values for one usage require `HidP_GetUsageValueArray` ([HID value capability - arrays](https://learn.microsoft.com/en-us/windows-hardware/drivers/hid/value-capability-arrays)). +- Detached clean checkout at + `deb47eda637bb67bb34b9a9d8719acf171125bc3`: Release build passed with zero + warnings/errors, 47/47 tests passed, and format verification passed. +- Linux `controlleros self-test --json`: 5/5 applicable checks passed. +- Self-contained Windows CLI from the reviewed implementation commit passed + hash verification for 200 files and self-test 5/5 on VM 101. +- VM 101 Windows integration opened the virtual Xbox HID interface, enumerated + 14 controls, canceled a pending idle read, verified XInput button/trigger/ + stick normalization, observed disconnect neutralization, and confirmed + interface removal. +- Independent review found and verified fixes for multi-usage HID ranges and + accurate cancellation evidence; no P0/P1 issue remained. Repeated values for + one usage remain unsupported pending `HidP_GetUsageValueArray`, consistent + with [Microsoft's HID capability documentation](https://learn.microsoft.com/en-us/windows-hardware/drivers/hid/value-capability-arrays). +- PR run `37665751598` and post-merge main run `37666364932` passed both + `windows-cli-smoke` and `build-test-format`. The main run restored, built, + tested, formatted, published, and uploaded the Windows artifact. +- Downloaded main artifact + `controlleros-experimental-win-x64-1d3d3f78475dc2610574dd1dc94260cf4cfcbbd4`; + all 200 files passed SHA-256 verification, and `BUILD-INFO.txt` matched the + exact main commit. The package contains the pinned output dependency and + license notices. -## Pending checks and evidence limits +## Evidence limits -- The Windows smoke job, GitHub clean-checkout CI run, and workflow artifact - upload have not run for this implementation because the branch push was - rejected before a PR could be created. -- The workflow YAML parsed locally, and its self-contained publish, build - identity, license, and hash-manifest steps were reproduced from a clean - checkout. This does not substitute for a GitHub Actions run or artifact - upload. -- GitHub rejected the push because the authenticated OAuth App token lacks the - `workflow` scope required to create or update `.github/workflows/ci.yml`. - The live authentication still reports `repo`, `read:org`, and `gist` scopes. - No token was exposed, no alternate credential was used, and no bypass of the - repository governance model was attempted. The remote feature branch remains - at its earlier governance-documentation commit. -- VM 101 was reached through the documented Windows-worker route. It exposed - no generic gamepad/joystick collection; the integration probe used only the - Xbox virtual output device. Physical controller capture and teaching remain - **community-test-needed**. Replay fixtures validate the deterministic - raw-report-to-teaching path without claiming physical-device validation. -- The WPF UI was not interactively launched; visual behavior remains +- No physical controller was available. Physical button, stick, trigger, and + D-pad capture/teaching remains **community-test-needed**. VM 101 had no generic + gamepad or joystick collection; its integration probe used the virtual Xbox + device and did not claim physical-device validation. +- The WPF UI was not launched interactively; graphical behavior remains **interactive-test-needed**. +- No physical model is claimed as maintainer-tested. Contribution reports + distinguish maintainer-tested, contributor-tested, mapping-only, and + unverified evidence. -## Remaining completion steps - -The authenticated GitHub CLI session must be refreshed by the repository owner -with the `workflow` scope. Once that external action is complete, push the -existing branch, create a PR, wait for the required `build-test-format` check -and Windows smoke/artifact job, update this report and PROJECT_STATUS.md with -the actual CI evidence, then merge through the configured PR rules. Verify the -resulting `origin/main` SHA and stop. Physical hardware remains a community -test opportunity and does not block software completion. +No manual GitHub administration action remains. The OAuth HTTPS token still +lacks `workflow`, so the authorized existing SSH key was used for the Git push; +GitHub CLI/API administration access remained available and the configured +governance rules were enforced during the PR merge. diff --git a/PROJECT_STATUS.md b/PROJECT_STATUS.md index 94c64eb..a83df92 100644 --- a/PROJECT_STATUS.md +++ b/PROJECT_STATUS.md @@ -60,17 +60,17 @@ dotnet test ControllerOS.sln --configuration Release --no-build dotnet format ControllerOS.sln --verify-no-changes --no-restore ``` -The current workspace Release build passes with zero warnings/errors; the suite -passes 47/47 tests; format verification passes; and `controlleros self-test ---json` passes 5/5 applicable checks on Linux. A self-contained `win-x64` CLI -published from commit `deb47eda637bb67bb34b9a9d8719acf171125bc3` passed its -200-file artifact hash check and all 5 self-test checks on VM 101. A detached -clean checkout at that commit also passed the Release build, 47/47 tests, and -format verification. The Windows integration probe opened the virtual Xbox -HID interface, enumerated 14 controls, canceled an idle raw read, verified -normalized XInput output, and confirmed clean disconnect and interface removal. -No physical gamepad was attached; physical HID teaching remains -community-test-needed. +The Release build passes with zero warnings/errors; 47/47 tests pass; format +verification passes; and `controlleros self-test --json` passes 5/5 applicable +checks on Linux. A self-contained `win-x64` CLI published from commit +`deb47eda637bb67bb34b9a9d8719acf171125bc3` passed its 200-file artifact hash +check and all 5 self-test checks on VM 101. A detached clean checkout at that +commit passed the Release build, 47/47 tests, and format verification. The +Windows integration probe opened the virtual Xbox HID interface, enumerated +14 controls, canceled an idle raw read, verified normalized XInput output, and +confirmed clean disconnect and interface removal. The required PR CI checks +and post-merge main CI passed; main CI published and its downloadable artifact +was verified against the main commit. The phase acceptance ledger is HEADLESS_BRIDGE_ACCEPTANCE.md. Its final review evidence, CI artifact result, implementation summary, and limitations are in @@ -94,20 +94,14 @@ HEADLESS_BRIDGE_FINAL_REPORT.md. ## Completion state Alpha 0.1 history remains unchanged. The Headless Community Bridge -implementation is locally validated, including on VM 101, but is not -phase-complete: GitHub rejected the branch push because the authenticated OAuth -App token lacks the `workflow` scope required to update -`.github/workflows/ci.yml`. PR CI and the CI artifact upload therefore remain -unverified. The exact rejection and remaining completion steps are recorded in -HEADLESS_BRIDGE_FINAL_REPORT.md. The local branch includes reviewed -implementation commit `deb47eda637bb67bb34b9a9d8719acf171125bc3`; the remote -feature branch is still at `3a41dfcffef7b2407340f4b2af15c75e7e5d33f0`, and the -current token reports only `gist`, `read:org`, and `repo`. - -After the owner refreshes the existing GitHub CLI authentication with the -required scope, push the existing branch, complete the PR checks, merge under -the configured ruleset, and verify remote `main`. No AI integration, console -support, or unrelated phase work is included. No tag or GitHub Release has -been created. +implementation is COMPLETE. PR #1 merged by squash, and `origin/main` was +verified at `1d3d3f78475dc2610574dd1dc94260cf4cfcbbd4`. Required check +`build-test-format`, the Windows smoke job, and the post-merge main CI run all +passed. The main CI artifact is available for experimental community testing; +no public release or version tag was created. + +No physical controller was available, so physical HID behavior remains +community-test-needed. No AI integration, console support, or unrelated phase +work is included. The forward project direction remains documented in [VISION.md](VISION.md).