Chore/resync 20260820

.agents/skills/build-openshell-mxc-windows/reference.md

@@ -0,0 +1,230 @@
+# Reference: Windows MSVC maintenance lane
+
+Companion to [SKILL.md](SKILL.md). Use this file for quick lookup while
+maintaining the existing build-only Windows MSVC lane.
+
+## Lane Files
+
+| File | Purpose |
+|---|---|
+| `tasks/windows.toml` | Mise task definitions for `windows:*`. |
+| `tasks/scripts/windows-msvc.ps1` | Visual Studio environment discovery, rustup target setup, Cargo invocation, logs, artifact report. |
+| `.github/workflows/windows-msvc.yml` | Manual GitHub Actions x64 job and disabled ARM64 scaffold, each with an architecture-specific Rust dependency cache. |
+| `architecture/windows-msvc-build.md` | Human-readable design contract. |
+
+## Commands
+
+Use `--skip-tools` for all Windows mise tasks:
+
+```powershell
+mise run --skip-tools windows:check:x64
+mise run --skip-tools windows:check:arm64
+mise run --skip-tools windows:build:x64
+mise run --skip-tools windows:build:arm64
+mise run --skip-tools windows:test:x64
+mise run --skip-tools windows:test:arm64
+mise run --skip-tools windows:test:unsupported:x64
+mise run --skip-tools windows:test:unsupported:arm64
+mise run --skip-tools windows:ci
+```
+
+For host-native full validation, detect architecture first:
+
+```powershell
+$arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
+if ($arch -eq [System.Runtime.InteropServices.Architecture]::Arm64) {
+    mise run --skip-tools windows:check:arm64
+    mise run --skip-tools windows:build:arm64
+    mise run --skip-tools windows:test:arm64
+    mise run --skip-tools windows:test:unsupported:arm64
+    mise run --skip-tools windows:artifacts
+} else {
+    mise run --skip-tools windows:ci
+}
+```
+
+The native test tasks reject a target that does not match the host architecture.
+Do not report x64 compatibility-under-emulation coverage from an ARM64 run.
+
+The wrapper adds missing rustup targets and clears inherited
+`RUSTC_WRAPPER`. It does not install Visual Studio, Rust, Docker, Kubernetes,
+Podman, WSL, Hyper-V, or VM tooling.
+
+On Windows, `mise run pre-commit` routes `rust:check`, `rust:lint`, and
+`test:rust` through this wrapper for the host-native target. The shared task
+definitions retain their existing Unix commands. Only tests for Linux glibc
+installer behavior, Linux build-environment shell helpers, and Linux
+service/RPM packaging assets skip on Windows. The Windows Clippy command
+excludes unsupported runtime packages as top-level targets and allows only
+unused imports, dead code, and unused async functions caused by cfg-gated
+Windows stubs; other warnings remain errors.
+
+The wrapper limits Cargo to four jobs by default and serializes wrapper-owned
+Cargo commands with a host-local mutex. It does not set `CL` or `_CL_` because
+`clang-cl` also consumes them and can parse a global `/MP4` option as an input
+file.
+
+For ARM64, verify the Visual Studio instance contains the ARM64 MSVC tools,
+ARM64 Spectre-mitigated libraries, Clang tools, CMake tools, and a Windows SDK.
+Clang supplies host-native `libclang.dll` for `bindgen` and `clang-cl.exe` for
+ARM64 crypto dependencies such as `ring` and `aws-lc-sys`. Native ARM64 uses
+the normal bundled-Z3 CMake path. An x64-to-ARM64 check/build discovers and
+adds host-native Ninja to `PATH`, while the crypto crates select `clang-cl`.
+Bundled Z3 uses CMake's Visual Studio ARM64 generator with native MSVC `cl.exe`
+because `z3-sys 0.10.9` passes the MSBuild-only `-m` argument. Use a short
+`CARGO_TARGET_DIR` if Windows path-length limits are reached.
+
+## Unsupported Driver Rules
+
+Windows is a build target only. These runtimes remain unsupported:
+
+- Docker
+- Kubernetes
+- Podman
+- VM
+
+Rules:
+
+- Keep config/library stubs where the gateway needs them.
+- Return clear unsupported errors at runtime.
+- Do not build standalone Windows driver binaries.
+- Do not add Docker Desktop, WSL, Hyper-V, Podman machine, Podman Desktop, or
+  VM-backed execution as part of this skill.
+
+Current focused unsupported-contract tests:
+
+```text
+windows_builtin_compute_drivers_report_unsupported
+```
+
+Run them with the architecture-specific focused task on the native host.
+
+## Cargo Excludes
+
+The Windows wrapper intentionally excludes unsupported runtime packages as
+top-level workspace targets for check/test:
+
+```text
+--exclude openshell-driver-docker
+--exclude openshell-driver-kubernetes
+--exclude openshell-driver-kubernetes-secrets
+--exclude openshell-driver-podman
+--exclude openshell-driver-vault
+--exclude openshell-driver-vm
+--exclude openshell-sandbox
+--exclude openshell-supervisor-network
+--exclude openshell-supervisor-process
+--exclude openshell-vfio
+```
+
+The gateway keeps platform configuration and unsupported-operation contracts
+without depending on the Docker, Kubernetes, Podman, sandbox supervisor,
+process supervisor, VM, or VFIO runtime crates. The Kubernetes Secrets and
+Vault libraries still compile as gateway dependencies; only their standalone
+Unix-socket binaries and package-level tests are excluded as top-level targets.
+
+## Common Errors
+
+### Unix imports leak into Windows builds
+
+Symptoms:
+
+```text
+unresolved import std::os::unix
+unresolved import tokio::net::UnixListener
+unresolved import nix::...
+```
+
+Fix pattern:
+
+```rust
+#[cfg(unix)]
+use tokio::net::{UnixListener, UnixStream};
+```
+
+Move Unix-only functions into Unix-only modules, or add a Windows stub that
+returns an unsupported error.
+
+### Linux-only dependency reaches Windows
+
+Symptoms:
+
+```text
+failed to run custom build command for libseccomp-sys
+pkg-config could not find libsecret
+```
+
+Fix pattern:
+
+```toml
+[target.'cfg(target_os = "linux")'.dependencies]
+libseccomp = "..."
+```
+
+Only gate the dependency if no Windows path should use it.
+
+### ARM64 check fails but x64 passes
+
+Likely causes:
+
+- Native dependency does not support `aarch64-pc-windows-msvc`.
+- ARM64 MSVC or Spectre-mitigated libraries are missing.
+- Host-native `clang-cl`, Ninja, or CMake is missing during an x64-to-ARM64 build.
+- `CL` or `_CL_` injects a global MSVC option such as `/MP4` into `clang-cl`.
+- Build script assumes x64 tools.
+- Inline assembly or prebuilt artifact lacks ARM64 handling.
+
+Do not skip ARM64 silently. Either fix the target handling or report the exact
+blocked dependency.
+
+### Focused tests report many filtered-out tests
+
+This is expected for `windows:test:unsupported:x64`. Cargo runs one named test
+and filters the other `openshell-server` tests. Report these as filtered, not
+ignored.
+
+## Reporting Counts
+
+Use the log summaries from:
+
+| Log | Count source |
+|---|---|
+| `test-x86_64-pc-windows-msvc.log` | Full x64 workspace test pass. |
+| `test-aarch64-pc-windows-msvc.log` | Full native ARM64 workspace test pass. |
+| `test-x86_64-pc-windows-msvc-unsupported-*.log` | Focused unsupported-contract re-runs and filtered counts. |
+| `test-aarch64-pc-windows-msvc-unsupported-*.log` | Focused native ARM64 re-runs and filtered counts. |
+
+Separate:
+
+- passed
+- failed
+- ignored
+- filtered out
+- cfg-gated zero-test targets
+- package-level excludes
+
+Package-level excludes are not printed as ignored tests by Cargo.
+
+## Final Sanity Checks
+
+Before committing Windows-lane changes, choose checks based on the host
+architecture:
+
+```powershell
+cargo fmt --all
+git diff --check
+$arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
+if ($arch -eq [System.Runtime.InteropServices.Architecture]::Arm64) {
+    mise run --skip-tools windows:check:arm64
+    mise run --skip-tools windows:build:arm64
+    mise run --skip-tools windows:test:arm64
+    mise run --skip-tools windows:test:unsupported:arm64
+} else {
+    mise run --skip-tools windows:check:x64
+    mise run --skip-tools windows:check:arm64
+    mise run --skip-tools windows:test:unsupported:x64
+}
+```
+
+Run the full x64-host `windows:ci` lane when build or test behavior changed and
+the host can run that lane natively.

.agents/skills/create-github-issue/SKILL.md

@@ -17,22 +17,27 @@ This project uses YAML form issue templates. When creating issues, match the tem
 
 ### Bug Reports
 
-Do not add a type label automatically. The body must include an **Agent Diagnostic** section — this is required by the template and enforced by project convention. Apply area or topic labels only when they are clearly known.
+Do not add a type label automatically. The body must include a **User Story**, **Problem Statement**, **Impact / Why This Matters**, and **Acceptance Criteria**, followed by bug-specific reproduction steps and environment details. Logs are optional and must be concise and redacted. Apply area or topic labels only when they are clearly known.
 
 ```bash
 gh issue create \
   --title "bug: <concise description>" \
   --body "$(cat <<'EOF'
-## Agent Diagnostic
+## User Story
 
-<Paste the output from the agent's investigation. What skills were loaded?
-What was found? What was tried?>
+As a <persona>, I want <capability or outcome>, so that <benefit or impact>.
 
-## Description
+## Problem Statement
+
+<Summarize what is broken or missing in OpenShell's current behavior and when the issue occurs>
+
+## Impact / Why This Matters
 
-**Actual behavior:** <what happened>
+<Explain the consequences for users, the current workaround, and why that workaround is insufficient>
 
-**Expected behavior:** <what should happen>
+## Acceptance Criteria
+
+- [ ] <observable outcome that demonstrates the bug is fixed>
 
 ## Reproduction Steps
 
@@ -41,43 +46,54 @@ What was found? What was tried?>
 
 ## Environment
 
-- OS: <os>
-- Docker: <version>
 - OpenShell: <version>
+- OS: <os>
+- Runtime, deployment, or integration: <relevant details>
 
 ## Logs
 
 ```
-<relevant output>
+<optional minimal, redacted output>
 ```
 EOF
 )"
 ```
 
 ### Feature Requests
 
-Do not add a type label automatically. The body must include a **Proposed Design** — not a "please build this" request. Apply area or topic labels only when they are clearly known.
+Do not add a type label automatically. The body must include a **User Story**, **Problem Statement**, **Impact / Why This Matters**, **Proposed Design**, **Acceptance Criteria**, and **Alternatives Considered**. The proposed design should define the user-facing workflow and externally observable behavior without prescribing internal implementation. Agent investigation is optional. Apply area or topic labels only when they are clearly known.
 
 ```bash
 gh issue create \
   --title "feat: <concise description>" \
   --body "$(cat <<'EOF'
+## User Story
+
+As a <persona>, I want <capability or outcome>, so that <benefit or impact>.
+
 ## Problem Statement
 
-<What problem does this solve? Why does it matter?>
+<Summarize the capability or behavior missing from OpenShell today>
+
+## Impact / Why This Matters
+
+<Explain what users must do today, why it is insufficient, and the operational cost, risk, blocked workflow, or adoption barrier>
 
 ## Proposed Design
 
-<How should this work? Describe the system behavior, components involved,
-and user-facing interface.>
+<The desired user-facing workflow and externally observable behavior, without prescribing internal implementation>
+
+## Acceptance Criteria
+
+- [ ] <specific, observable outcome>
 
 ## Alternatives Considered
 
-<What other approaches were evaluated? Why is this design better?>
+<Other user-facing workflows or behaviors considered and why this approach best satisfies the user story>
 
 ## Agent Investigation
 
-<If the agent explored the codebase to assess feasibility, paste findings here.>
+<Optional findings from codebase exploration>
 EOF
 )"
 ```
@@ -107,6 +123,8 @@ EOF
 
 GitHub built-in issue types (`Bug`, `Feature`, `Task`) should come from the matching issue template when possible, or be set manually afterward. Do not try to emulate them through labels.
 
+Creating an issue does not accept it or queue agent work. Agents never apply `state:accepted`, the `roadmap` label, add issues to the roadmap project, or apply `agent:plan-requested` or `agent:implementation-requested`. Community issues proceed through `triage-issue`; a human accepts technically validated work with `state:accepted` or roadmap placement. The request labels queue work for unattended agents; a user may instead direct an agent to a specific issue.
+
 ## Useful Options
 
 | Option              | Description                        |

.agents/skills/create-github-pr/SKILL.md

@@ -11,7 +11,7 @@ Create pull requests on GitHub using the `gh` CLI.
 
 - The `gh` CLI must be authenticated (`gh auth status`)
 - You must have commits on a branch that's pushed to the remote
-- Branch should follow naming convention: `<issue-number>-<description>/<username>`
+- For issue-backed work, the branch should follow `<issue-number>-<description>/<username>`. Exempt issue-less changes may use `<description>/<username>`.
 
 ## Before Creating a PR
 
@@ -24,6 +24,10 @@ in the same branch. If the change affects user-facing compute-driver setup,
 also update `docs/reference/sandbox-compute-drivers.mdx` or the relevant
 deployment docs.
 
+### Check Agent Infrastructure
+
+Use the `sync-agent-infra` skill's maintenance map to identify related skill updates when the branch changes behavior, commands, or development workflows. Run its full consistency check when the branch adds, removes, or renames skills or crates; changes workflow relationships or skill coverage; modifies issue or PR templates; or changes agent cross-references. Resolve any drift before creating the PR.
+
 ### Run Pre-commit Checks
 
 Run the local pre-commit task before opening a PR:
@@ -43,7 +47,7 @@ Before creating a PR, verify:
    git branch --show-current
    ```
 
-2. **Branch follows naming convention** - Format: `<issue-number>-<description>/<initials>`
+2. **Branch follows naming convention** - Use `<issue-number>-<description>/<initials>` for issue-backed work or `<description>/<initials>` for an exempt issue-less change.
 
    ```bash
    # Example: 1234-add-pagination/jd
@@ -110,7 +114,7 @@ gh pr create --title "PR title" --body "PR description"
 
 ### Link to an Issue
 
-Use `Closes #<issue-number>` in the body to auto-close the issue when merged:
+Features, user-visible behavior changes, public API changes, architecture changes, and multi-PR efforts must link an accepted issue. Use `Closes #<issue-number>` in the body to auto-close the issue when merged:
 
 ```bash
 gh pr create \
@@ -122,6 +126,8 @@ gh pr create \
 - Returns 400 instead of 500"
 ```
 
+Small documentation fixes, mechanical maintenance, and obvious localized bug fixes may omit a separate issue when the PR contains enough context to review the decision and implementation together. In that case, write `No issue required: <brief reason>` in the Related Issue section. Do not use this exception for security fixes; follow `SECURITY.md`.
+
 ### Create as Draft
 
 For work-in-progress that's not ready for review:
@@ -153,7 +159,7 @@ PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEM
 <!-- 1-3 sentences: what this PR does and why -->
 
 ## Related Issue
-<!-- Fixes #NNN or Closes #NNN -->
+<!-- Fixes #NNN / Closes #NNN, or "No issue required: <reason>" for an exempt change -->
 
 ## Changes
 <!-- Bullet list of key changes -->