From dcc09f319d533ea1af2bdd615060f621e5d080a1 Mon Sep 17 00:00:00 2001 From: Marco Allegretti Date: Thu, 8 Oct 2026 23:40:08 +0000 Subject: [PATCH] docs: add engineering contract, contributor toolkit and templates Add AGENTS.md as the single engineering contract: sources of truth, evidence and proof requirements, ownership, working modes, the reviewed change loop, maintenance isolation, decision authority, dependency and fork rules, the 0.0.x to 0.1.0 release progression, and branch and publication rules. Add .agents/ with scope, implement, verify, maintenance and release procedures; reviewer, architecture debt scout, simplicity and refactoring roles; skills for the compositor, Servo rendering, runtime capabilities, appd sessions, packages and data, Linux deployment, integration verification and documentation; and verify.py, which runs the existing check profiles with --locked from any directory, stops on the first failure and supports --dry-run. check_toolkit.py validates local links and heading anchors, metadata, catalog coverage and issue forms. A new contributor-toolkit CI job runs both. The structure follows the Resina Design System toolkit at 1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT. Validation, against the committed lockfiles: - verify.py toolkit: checker passes, 28 runner/checker tests pass - verify.py portable, demos, packages: pass - verify.py linux, runtime, servo-embed: fail on existing defects (clippy collapsible_if in the winit backend, three clippy lints in weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo revision's servo-layout); the runner reports the failing status Add CONTRIBUTING.md, issue forms for defects and changes, maintenance problems and decisions of direction, and a pull request template asking for ownership, proof and the validation actually performed. README.md links the contribution guide. --- .agents/README.md | 119 ++++++ .agents/agents/architecture-debt-scout.md | 39 ++ .agents/agents/continuous-refactoring.md | 30 ++ .agents/agents/continuous-simplicity.md | 26 ++ .agents/agents/reviewer.md | 56 +++ .agents/commands/implement.md | 56 +++ .agents/commands/maintenance.md | 36 ++ .agents/commands/release.md | 43 ++ .agents/commands/scope.md | 43 ++ .agents/commands/verify.md | 43 ++ .agents/scripts/check_toolkit.py | 174 +++++++++ .agents/scripts/requirements.txt | 3 + .agents/scripts/test_toolkit.py | 239 ++++++++++++ .agents/scripts/verify.py | 124 ++++++ .agents/skills/weft-appd-sessions/SKILL.md | 59 +++ .agents/skills/weft-compositor-input/SKILL.md | 55 +++ .agents/skills/weft-documentation/SKILL.md | 53 +++ .../weft-integration-verification/SKILL.md | 54 +++ .agents/skills/weft-linux-deployment/SKILL.md | 53 +++ .agents/skills/weft-packages-data/SKILL.md | 57 +++ .../skills/weft-runtime-capabilities/SKILL.md | 58 +++ .agents/skills/weft-servo-rendering/SKILL.md | 72 ++++ .github/ISSUE_TEMPLATE/change.yml | 63 +++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/decision.yml | 58 +++ .github/ISSUE_TEMPLATE/maintenance.yml | 58 +++ .github/pull_request_template.md | 29 ++ .github/workflows/ci.yml | 13 + .gitignore | 2 + AGENTS.md | 368 ++++++++++++++++++ CONTRIBUTING.md | 77 ++++ README.md | 7 +- docs/building.md | 3 +- 33 files changed, 2173 insertions(+), 2 deletions(-) create mode 100644 .agents/README.md create mode 100644 .agents/agents/architecture-debt-scout.md create mode 100644 .agents/agents/continuous-refactoring.md create mode 100644 .agents/agents/continuous-simplicity.md create mode 100644 .agents/agents/reviewer.md create mode 100644 .agents/commands/implement.md create mode 100644 .agents/commands/maintenance.md create mode 100644 .agents/commands/release.md create mode 100644 .agents/commands/scope.md create mode 100644 .agents/commands/verify.md create mode 100644 .agents/scripts/check_toolkit.py create mode 100644 .agents/scripts/requirements.txt create mode 100644 .agents/scripts/test_toolkit.py create mode 100644 .agents/scripts/verify.py create mode 100644 .agents/skills/weft-appd-sessions/SKILL.md create mode 100644 .agents/skills/weft-compositor-input/SKILL.md create mode 100644 .agents/skills/weft-documentation/SKILL.md create mode 100644 .agents/skills/weft-integration-verification/SKILL.md create mode 100644 .agents/skills/weft-linux-deployment/SKILL.md create mode 100644 .agents/skills/weft-packages-data/SKILL.md create mode 100644 .agents/skills/weft-runtime-capabilities/SKILL.md create mode 100644 .agents/skills/weft-servo-rendering/SKILL.md create mode 100644 .github/ISSUE_TEMPLATE/change.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/decision.yml create mode 100644 .github/ISSUE_TEMPLATE/maintenance.yml create mode 100644 .github/pull_request_template.md create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md diff --git a/.agents/README.md b/.agents/README.md new file mode 100644 index 0000000..650536b --- /dev/null +++ b/.agents/README.md @@ -0,0 +1,119 @@ +# WEFT OS contributor toolkit + +Procedures, review roles, area knowledge and a verification runner for +contributors. [AGENTS.md](../AGENTS.md) is the engineering +contract; [BLUEPRINT.md](../BLUEPRINT.md) is the accepted product direction; +[CONTRIBUTING.md](../CONTRIBUTING.md) is the maintainer-facing summary. + +These files help apply the contract. They do not grant permissions, approve +decisions, schedule work or change the [working mode](../AGENTS.md#4-working-modes). +If a guide here seems to disagree with `AGENTS.md`, the contract wins and the +guide needs fixing. + +## Start + +1. Read `AGENTS.md`, identify the accepted scope and the owning component. +2. Load only the skills that match the boundary you are changing. +3. Use [scope](commands/scope.md) for an unverified report or proposal, and + [implement](commands/implement.md) for accepted, verifiable work. +4. Select checks and evidence with [verify](commands/verify.md), then have the + [reviewer](agents/reviewer.md) inspect the actual diff. + +## Commands + +Commands are portable Markdown procedures. Follow them as checklists. + +| Command | Input | Result | +|---|---|---| +| [scope](commands/scope.md) | Report, defect or proposal | Evidence-backed issue draft with owner, acceptance criterion and proof | +| [implement](commands/implement.md) | Issue or accepted scope | Reviewed atomic change on a descriptive branch | +| [verify](commands/verify.md) | Scope or diff | Coverage map and actual check results | +| [maintenance](commands/maintenance.md) | One named maintenance role | One justified issue, or one isolated reviewed change | +| [release](commands/release.md) | Milestone scope and candidate commit | Candidate evidence and a promotion recommendation | + +## Roles + +Roles are checklists for a reviewer or a focused pass over the code. A role +file does nothing until a task invokes it. + +| Role | Responsibility | +|---|---| +| [reviewer](agents/reviewer.md) | Review a specified diff for correctness, scope, ownership and evidence without editing it | +| [architecture-debt-scout](agents/architecture-debt-scout.md) | Report the strongest present ownership or boundary problem; never edit repository files | +| [continuous-simplicity](agents/continuous-simplicity.md) | Remove one duplicated decision, unnecessary state or misleading fallback path | +| [continuous-refactoring](agents/continuous-refactoring.md) | Resolve one structural problem while preserving behavior, ownership and proof | + +## Skills + +Each skill is a `SKILL.md` with `name` and `description` metadata. The `weft-` +prefix keeps them distinct from skills installed by other projects. + +| Skill | Load when changing | +|---|---| +| [weft-compositor-input](skills/weft-compositor-input/SKILL.md) | Smithay compositor, Wayland protocols, surfaces, focus, geometry, input, DRM or winit backends | +| [weft-servo-rendering](skills/weft-servo-rendering/SKILL.md) | Servo embedding, painting and presentation, the Servo fork and Stylo overrides, system UI and app pages | +| [weft-runtime-capabilities](skills/weft-runtime-capabilities/SKILL.md) | Wasmtime host, WIT, WASI preopens, host imports, grants, file portal, seccomp | +| [weft-appd-sessions](skills/weft-appd-sessions/SKILL.md) | Session lifecycle, readiness, child supervision, cleanup, appd IPC, WebSocket bridge | +| [weft-packages-data](skills/weft-packages-data/SKILL.md) | Manifests, `weft-pack`, signing and trust, installation, updates, app data, EROFS images | +| [weft-linux-deployment](skills/weft-linux-deployment/SKILL.md) | Nix flake and VM, systemd units, native dependencies, installed paths and endpoints | +| [weft-integration-verification](skills/weft-integration-verification/SKILL.md) | End-to-end fixtures, pixels and input, failure injection, reliability and evidence records | +| [weft-documentation](skills/weft-documentation/SKILL.md) | Public documentation, the blueprint, this toolkit, templates and the runner | + +## Verification runner + +[`scripts/verify.py`](scripts/verify.py) runs the repository's actual check +profiles. It needs Python 3.10 or newer. It works from any directory, runs fixed +argument arrays from the repository root without a shell, stops at the first +failure and returns its status. It never formats files, installs packages or +toolchain targets, regenerates expectations, signs packages, commits or +publishes. + +```sh +python .agents/scripts/verify.py --help +python .agents/scripts/verify.py portable linux --dry-run +python .agents/scripts/verify.py portable linux +``` + +| Profile | Runs | Prerequisites | +|---|---|---| +| `toolkit` | Link, anchor, metadata, catalog and issue-form checks; runner tests | `pip install -r .agents/scripts/requirements.txt` | +| `portable` | `cargo fmt --check`; Clippy and tests for crates built on every host | Pinned toolchain | +| `linux` | Clippy and tests for `weft-compositor` and the feature-disabled shells | Linux Wayland, input, DRM and systemd development libraries | +| `servo-embed` | `cargo check` of both Servo hosts with the real renderer feature | As `linux`, plus the Servo build dependencies; long first build | +| `runtime` | Clippy and tests for `weft-runtime` with `wasmtime-runtime,net-fetch` | Pinned toolchain | +| `demos` | `cargo check` of the demo components for `wasm32-wasip2` | `rustup target add wasm32-wasip2` | +| `packages` | `weft-pack check` and `weft-pack verify` of the demo packages | Pinned toolchain | + +All Cargo commands use `--locked`. Local `[patch]` overrides used for +cross-repository development change the resolved graph and make locked checks +fail; run the runner without them for evidence about the committed graph. + +The runner covers compilation, lints, unit tests and package checks. It does not +run a compositor, render pixels, launch a session, boot the VM or exercise a +real component's host imports. Select that evidence with +[verify](commands/verify.md). Profiles are not a replacement for +[CI](../.github/workflows/ci.yml), and a passing profile is not approval to +publish, merge or release. No hooks are installed by this toolkit; if you call +the runner from a local hook, configure it in your own client or Git setup. + +## Maintaining the toolkit + +Put area knowledge in a skill, repeatable steps in a command, review criteria in +a role and executable checks in `scripts/`. Link to the contract and to the +owning source instead of restating policy or freezing implementation status. +List every command, role and skill in its table above; `toolkit` fails when a +document is not linked from this catalog. Changes to the runner need a test +showing failure behavior. + +`check_toolkit.py` parses CommonMark links, images and reference links in this +directory and in the top-level contributor documents. It ignores code spans, +code blocks and HTML comments. It checks that local targets exist inside the +repository, that `#fragment` links into Markdown files match a GitHub-style +heading anchor, that metadata is a YAML mapping with unique string `name` and +`description` fields and a `name` matching its path, and that issue forms parse. +External URLs, raw HTML and the truth of the instructions still need review. + +The structure follows the +[Resina Design System contributor toolkit](https://github.com/marcoallegretti/Resina-Design_System/tree/1e768064f57a1e403ab271822383e732795905a6/.agents) +at revision `1e768064f57a1e403ab271822383e732795905a6`. WEFT's contract, +ownership and evidence requirements determine its contents. diff --git a/.agents/agents/architecture-debt-scout.md b/.agents/agents/architecture-debt-scout.md new file mode 100644 index 0000000..8cb89ea --- /dev/null +++ b/.agents/agents/architecture-debt-scout.md @@ -0,0 +1,39 @@ +--- +name: architecture-debt-scout +description: Find the strongest present ownership or boundary problem in WEFT OS with evidence and report it; never edit repository files. +--- + +# Architecture debt scout + +Run through [maintenance](../commands/maintenance.md) under the contract's +[maintenance rules](../../AGENTS.md#8-maintenance). You may read the whole +repository and its history. You edit no repository files and create no branches, +commits or pull requests. + +Look for present consequences at WEFT's boundaries: + +- Responsibility held by the wrong owner, or two owners for one decision: session + state in both appd and the shell, package roots rediscovered by each child, + geometry decided outside the compositor. +- Authority taken from untrusted input: caller-supplied session IDs, PIDs, + window titles or stdout text treated as identity or readiness. +- Grants declared but not enforced at a host entry, or enforced differently in + WASI, the file portal and the renderer. +- Synthetic success: feature-disabled or fallback paths that report readiness, + delivery or verification. +- Contract drift between bridge and daemon messages, manifest and runtime + loading, image builder and loader, documentation and code. +- Dependency use that differs from the selected revision, or overrides that do + not reach the consuming workspace. + +Check the blueprint's [baseline findings](../../BLUEPRINT.md#32-findings-that-determine-the-implementation-order) +and existing issues first: a known, already-scoped problem is not a new finding, +and one owned by the active goal is fixed there. + +Apply the threshold: a named affected party, repository evidence, present cost +and an independent acceptance criterion. Return the single highest-value +qualifying problem with file and line evidence, owner and boundary, present +cost, acceptance criterion, expected proof and, where a decision is needed, the +meaningful alternatives. Create or update its issue only within granted +authority. When nothing qualifies, say so and stop. Do not decide architecture +or launch speculative work. diff --git a/.agents/agents/continuous-refactoring.md b/.agents/agents/continuous-refactoring.md new file mode 100644 index 0000000..2368a78 --- /dev/null +++ b/.agents/agents/continuous-refactoring.md @@ -0,0 +1,30 @@ +--- +name: continuous-refactoring +description: Resolve one concrete structural problem in WEFT OS while preserving accepted behavior, ownership and proof. +--- + +# Continuous refactoring + +Run through [maintenance](../commands/maintenance.md) under the contract's +[maintenance rules](../../AGENTS.md#8-maintenance). Establish the affected +caller, contract or test harness, the present cost and an independent acceptance +criterion. + +Valid targets are demonstrated: duplicated logic with a working path on both +sides, coupled responsibilities that prevent testing, repeated conversions, +modules with several reasons to change, or structure that blocks a required +fixture. The blueprint names candidates that become justified once working paths +and regression evidence exist: shared package resolution, one effective-grants +model, one session cleanup owner, one bridge message contract and common Servo +host and input behavior. Extract a boundary only when that evidence exists. + +Behavior, public contracts and ownership stay unchanged. Moving responsibility +between owners or changing a public contract needs a +[decision](../../AGENTS.md#9-decisions-and-authority): record it and stop the +change. Scope follows the acceptance criterion and ownership, not a file or line +budget. + +Establish preservation proof first, refactor completely, run +[verify](../commands/verify.md) and have the [reviewer](reviewer.md) inspect the +committed range. Return the structural result, the contracts left unchanged and +the actual checks. Stop after one result. diff --git a/.agents/agents/continuous-simplicity.md b/.agents/agents/continuous-simplicity.md new file mode 100644 index 0000000..8f3c3c4 --- /dev/null +++ b/.agents/agents/continuous-simplicity.md @@ -0,0 +1,26 @@ +--- +name: continuous-simplicity +description: Remove one evidenced duplicated decision, unnecessary state or misleading fallback path while preserving WEFT OS behavior and ownership. +--- + +# Continuous simplicity + +Run through [maintenance](../commands/maintenance.md) under the contract's +[maintenance rules](../../AGENTS.md#8-maintenance). Establish the affected +caller, contributor or contract, the present cost and the acceptance criterion +before changing anything. + +Candidates are concrete: the same decision computed in two places, state that +can disagree with its source, a fallback that hides a failure or reports success +it did not achieve, an obsolete path, indirection without a second caller, or +documentation that restates and contradicts code. Prefer deletion and existing +concepts. Do not optimize for line count, merge distinct privileges or failure +domains, or replace explicit errors and authority checks with something shorter. + +Removing a misleading fallback can change observable behavior from silent +success to explicit failure. That is in scope when the fallback contradicts the +contract; state the change and prove the new failure mode. + +Establish preservation evidence first, implement, run [verify](../commands/verify.md) +and have the [reviewer](reviewer.md) inspect the committed range. Stop after one +issue and pull request result; simplification never becomes the primary goal. diff --git a/.agents/agents/reviewer.md b/.agents/agents/reviewer.md new file mode 100644 index 0000000..efa62b9 --- /dev/null +++ b/.agents/agents/reviewer.md @@ -0,0 +1,56 @@ +--- +name: reviewer +description: Review a specified WEFT OS diff for correctness, ownership, scope and evidence without editing it. +--- + +# Review a change + +Input: the acceptance criterion, a base/head range or pull request diff, and the +validation evidence claimed. Read [AGENTS.md](../../AGENTS.md) and the +[skills](../README.md#skills) for the boundaries touched. + +Inspect the actual change first: `git diff ` for commits, or both +`git diff --staged` and `git diff` for uncommitted work. An empty `git diff HEAD` +after a commit means the wrong range was chosen, not that nothing changed. Read +the surrounding code and contracts needed to understand the behavior; do not turn +the review into repository-wide cleanup. + +You report findings. You do not edit the change, approve decisions or releases, +or publish anything beyond the authority granted for the review. + +Check: + +1. **Behavior.** Does the change do what the acceptance criterion says on every + path, including errors, cancellation, timeouts, partial failure and teardown? + Are resources (processes, sockets, relays, mounts, temporary files) settled? +2. **Proof.** Would the named tests or fixtures fail if the behavior broke? Do + they exercise the real boundary, or a mock, a feature-disabled build or a log + line? Were expectations, fixtures or signatures changed with a contractual + reason? Were the claimed checks actually run, against the committed graph? +3. **Ownership.** Does each responsibility stay with its owner from the + [blueprint](../../BLUEPRINT.md#4-architecture-and-ownership)? Is a second + source of truth created for session state, grants, package resolution or + geometry? Is a decision of direction hidden inside cleanup? +4. **Trust and data.** Can application content, a forged session identifier or a + symlink obtain access it was not granted? Is user data preserved across + failure, update and uninstall? Are secrets and payloads kept out of logs? +5. **Compatibility.** Are manifest, WIT, protocol, IPC and package format changes + deliberate, versioned or converted? Do documentation and code agree? +6. **Dependencies.** Is every external API used as it exists in the revision the + lockfile selects? Are overrides applied at the workspace root? +7. **Scope and quality.** Is the change focused and atomic, free of unrelated + edits, generated or local-environment files, synthetic success paths and + unjustified abstraction? Are commit and pull request texts free of + attribution, trailers and process narration? + +Each finding states severity, file and line, the concrete consequence, the +evidence you read or ran, and the required correction. Separate verified defects +from suspicions. **Blocking** findings concern correctness, promised behavior, +trust, data preservation, compatibility, accepted scope or required evidence. +Lower-impact findings are nonblocking. Do not manufacture findings or raise +preferences to blockers; unrelated debt does not block this change. + +Return the findings, the checks you performed and whether any blocking finding +remains. Say so only after completing the review. State if you authored the +change or share its context, so the limitation can be reported honestly. Keep +this output separate from published pull request text. diff --git a/.agents/commands/implement.md b/.agents/commands/implement.md new file mode 100644 index 0000000..cbd51ec --- /dev/null +++ b/.agents/commands/implement.md @@ -0,0 +1,56 @@ +--- +name: implement +description: Carry accepted scope through proof, implementation, validation and diff review to one atomic result. +--- + +# Implement accepted scope + +Input: an issue or an explicitly accepted task with an acceptance criterion. +Read [AGENTS.md](../../AGENTS.md) and the matching [skills](../README.md#skills). +This procedure applies the [reviewed change loop](../../AGENTS.md#5-reviewed-change-loop) +to contribution work and to each step of primary development. It adds no +approval layer: in primary development, continue to the next accepted step after +each accepted result. + +1. **Inspect and confirm scope.** Verify the problem against current source and + evidence. If the acceptance criterion or proof is missing, use + [scope](scope.md). An issue is not a decision; if one is required and + unresolved, prepare it and work on something independent. +2. **Prepare the branch.** Inspect `git status`, the current branch, worktrees and + remotes. Fetch `main` and branch from it, or from the unmerged branch the work + depends on, with a descriptive + [branch name](../../AGENTS.md#14-branches-commits-and-publication). Preserve + unrelated changes; never commit contribution work directly to `main`. +3. **Review the plan.** Name the owner, the boundary touched, compatibility + promises affected and the proof. Check uncertain APIs in the dependency + source selected by the lockfile. Fix it here if the design crosses ownership. +4. **Establish proof.** Reproduce a defect first. For new behavior, add the + fixture or contract case that fails without the change. Identify which + evidence needs a real environment (compositor, renderer, VM) and whether it is + available. +5. **Implement** the smallest complete change. Keep manifests, WIT, protocol, + IPC types, documentation and callers coherent. No synthetic success paths. +6. **Validate** with [verify](verify.md): the smallest sufficient profiles plus + any boundary-specific evidence. Fix failures within scope. Explain every + changed expectation; never re-bless output to make it pass. +7. **Review the actual diff** with the [reviewer](../agents/reviewer.md), from a + reviewer who did not write it when available, otherwise as a fresh separate + pass whose limitation you state. Review `git diff ` for commits, + or both staged and unstaged diffs before committing. +8. **Correct, revalidate and re-review** until no blocking finding remains. + Recheck after material corrections, rebases and conflict resolutions. +9. **Commit atomically.** Inspect `git status` and the complete diff; exclude + generated, transient and local-environment files (for example lockfile changes + caused by local `[patch]` overrides). Write the message for maintainers. +10. **Publish within authority.** If pushing or opening a pull request is + authorized and available, fill the + [pull request template](../../.github/pull_request_template.md) and inspect + automated review integrations first. Otherwise return the local result and + the prepared description. +11. **Reassess** the goal from the new repository state and continue with the + next dependent step. + +Report what changed, what proves it, the checks actually run with results, and +material limitations. A separately actionable problem found on the way goes +through the [maintenance threshold](../../AGENTS.md#8-maintenance) instead of +the pull request body. Completing a change grants no merge or release authority. diff --git a/.agents/commands/maintenance.md b/.agents/commands/maintenance.md new file mode 100644 index 0000000..7a09acb --- /dev/null +++ b/.agents/commands/maintenance.md @@ -0,0 +1,36 @@ +--- +name: maintenance +description: Run one maintenance role for one qualifying problem from the verified current main, isolated from primary development. +--- + +# Run one maintenance task + +Input: one named role, [architecture-debt-scout](../agents/architecture-debt-scout.md), +[continuous-simplicity](../agents/continuous-simplicity.md) or +[continuous-refactoring](../agents/continuous-refactoring.md), and optionally a +candidate problem. Read [maintenance](../../AGENTS.md#8-maintenance) in the +contract and load the role. + +1. **Verify the base.** Fetch `main` and record its revision. If freshness cannot + be verified, state the revision you used and the limitation. Never switch, + reset or edit the active development checkout. +2. **Apply the threshold.** Find the strongest problem that has a named affected + party, present repository evidence, present cost and an independent acceptance + criterion. A problem inside the active goal's acceptance criterion belongs to + that goal, not here. If nothing qualifies, report that and stop. +3. **Check for existing work.** Search issues and pull requests for the same + underlying problem and update the existing one instead of duplicating. Report + incomplete duplicate checking when access is unavailable. +4. **Record it.** Draft the issue with [scope](scope.md) and the + [maintenance form](../../.github/ISSUE_TEMPLATE/maintenance.yml), creating or + updating it only within granted authority. The scout stops here. +5. **Isolate.** For simplicity or refactoring, add a worktree from the fetched + `main`, for example `git worktree add ../weft-share-package-resolution -b refactor/share-package-resolution origin/main`. + Use a branch name that describes the change, not the role. +6. **Change and review.** Follow [implement](implement.md) from proof to one + reviewed pull request, or to a prepared local result when publication is not + authorized. If the change turns out to need a + [decision](../../AGENTS.md#9-decisions-and-authority), stop it and record + the decision needed. +7. **Stop.** One run handles one problem. Do not continue collecting + opportunities, and do not merge. diff --git a/.agents/commands/release.md b/.agents/commands/release.md new file mode 100644 index 0000000..a9c7182 --- /dev/null +++ b/.agents/commands/release.md @@ -0,0 +1,43 @@ +--- +name: release +description: Prepare a 0.0.x or 0.1.0 candidate's evidence and recommend promotion without promoting it automatically. +--- + +# Prepare a release stage + +Input: the milestone scope, the target version and stage, and the exact +candidate commit. Read [versions and releases](../../AGENTS.md#13-versions-and-releases), +the blueprint's [version progression](../../BLUEPRINT.md#121-version-progression) +and, for stable `0.1.0`, the [stable release gate](../../BLUEPRINT.md#14-stable-release-gate). + +1. **Inventory.** List existing tags, published releases and the versions in + `Cargo.toml`, crate manifests and package manifests. Choose the next unused + `0.0.x` for an accepted milestone scope; never reuse, move or rewrite a + published tag or release. Record how the unreleased workspace value `0.1.0` + is reconciled. +2. **Check the stage contract.** `alpha.N` needs defined scope, ownership and + fixtures with incompleteness stated. `beta.N` needs the declared scope + implemented, relevant integration and failure paths passing and interfaces, + support scope and budgets frozen. `rc.N` needs the exact candidate complete + for its scope, the required matrix passing, independent technical review and + ready artifacts and migration behavior. Final, released as the plain version + without a `-final` suffix, needs every scoped promise to pass. +3. **Collect candidate evidence** for that exact commit with [verify](verify.md): + every applicable runner profile plus the blueprint fixtures and target + environments in scope. Record commit, environment, features, commands, results + and artifact digests. A missing environment leaves the gate incomplete. +4. **Obtain independent technical review** of the candidate with the + [reviewer](../agents/reviewer.md), aimed at showing it is not ready. A self + review does not satisfy a release gate; an unavailable reviewer leaves the gate + pending while other authorized work continues. +5. **Resolve or scope.** Blocking findings prevent promotion. Corrections after + review invalidate the affected evidence: rebuild the candidate, rerun the + affected checks and re-review. Unsupported features are excluded explicitly, + not left as silent success paths. +6. **Prepare release notes** for maintainers: scope, support matrix, known + limitations, compatibility and migration notes, commit and artifact digests, + and the evidence actually executed. +7. **Recommend.** Return the evidence, open findings and a recommendation. + Promotion, tagging and publication happen only under granted release + authority, and publish the artifact that was tested. If final metadata + requires a rebuild, verify that rebuilt artifact before publishing it. diff --git a/.agents/commands/scope.md b/.agents/commands/scope.md new file mode 100644 index 0000000..c544ef1 --- /dev/null +++ b/.agents/commands/scope.md @@ -0,0 +1,43 @@ +--- +name: scope +description: Establish a reported problem or proposal and draft verifiable scope with owner, acceptance criterion and proof. +--- + +# Establish the scope + +Input: a defect report, desired behavior or proposal. Read +[AGENTS.md](../../AGENTS.md), the relevant sections of +[BLUEPRINT.md](../../BLUEPRINT.md) and the matching +[skills](../README.md#skills). The result is a draft; this procedure neither +implements it nor authorizes publication. + +1. **Inspect.** Read the implemented source, the public contract involved + (manifest, WIT, shell protocol, IPC types) and the selected dependency source + when an external API matters. Check whether the blueprint already records the + problem, for example in its [baseline findings](../../BLUEPRINT.md#32-findings-that-determine-the-implementation-order). +2. **Reproduce** where practical, with the exact commit, environment, features + and command. Separate observations from assumptions and say which level of + [evidence](../../BLUEPRINT.md#111-evidence-levels) each observation reached. +3. **Name the owner** from the + [ownership table](../../BLUEPRINT.md#4-architecture-and-ownership) and the + affected user, caller or contract. If nobody is worse off today, stop: there + is no issue. +4. **Check for duplicates** among existing issues and pull requests. If access is + unavailable, say that duplicate checking is incomplete. +5. **Decide the path.** Ordinary work within accepted architecture becomes a + change. A material departure from accepted direction, compatibility, trust, + support scope or data policy needs a + [decision](../../AGENTS.md#9-decisions-and-authority): prepare the evidence, + alternatives and trade-offs and mark implementation as waiting for it. +6. **Draft** against the matching form: + [defect or change](../../.github/ISSUE_TEMPLATE/change.yml), + [maintenance](../../.github/ISSUE_TEMPLATE/maintenance.yml) or + [decision](../../.github/ISSUE_TEMPLATE/decision.yml). + +The draft states observed and expected behavior, evidence with file and line +references, owner and affected boundary, present impact, one acceptance +criterion, the proof that would fail today and pass afterwards, and relevant +non-goals. A claim without a verification surface is unfinished scope. + +Return the draft plus any missing evidence or decision. Create or update an +issue only when that is part of the authorized task. diff --git a/.agents/commands/verify.md b/.agents/commands/verify.md new file mode 100644 index 0000000..cbea344 --- /dev/null +++ b/.agents/commands/verify.md @@ -0,0 +1,43 @@ +--- +name: verify +description: Map a change to the evidence that proves it, run the applicable checks and report actual results and gaps. +--- + +# Select and run the evidence + +Input: accepted scope and a diff or explicit base/head range. Read the +[proof rules](../../AGENTS.md#6-proof-before-implementation), the blueprint's +[verification profiles](../../BLUEPRINT.md#112-verification-profiles) and +[acceptance fixtures](../../BLUEPRINT.md#113-required-acceptance-fixtures), and +[CI](../../.github/workflows/ci.yml). + +List the observable behaviors the change affects, not the files. For each, +name the check that would fail if it were wrong and classify it as direct proof, +incidental coverage or missing. Then select: + +| Affected area | Runner profiles | Evidence the runner cannot provide | +|---|---|---| +| Portable crates (`weft-appd`, `weft-pack`, `weft-ipc-types`, `weft-file-portal`, `weft-mount-helper`, `weft-build-meta`, `weft-runtime` stub) | `portable` | Child processes, sockets and filesystems exercised for real where the change depends on them | +| `weft-compositor` | `portable linux` | Nested winit session with real clients; DRM session on the declared target | +| Servo hosts | `linux servo-embed` | Painted and presented pixels, input, resize and idle wakeup on a running compositor | +| `weft-runtime` engine or host imports | `portable runtime` | Actual component fixtures for allowed, denied and failure paths; a Linux build of the `seccomp` feature when it is touched | +| WIT, demo components | `demos packages` | Instantiating the rebuilt component under `weft-runtime` | +| Package tooling, signing, demo packages | `portable packages` | Tamper, interruption and data-retention fixtures | +| Dependency or fork change | Every profile whose crates resolve the changed package | Resolved graph inspection; the rendered or runtime behavior the change claims | +| Nix, systemd, VM | None directly | `infra/vm/build.sh` and a booted graphical image | +| Contributor documentation and toolkit | `toolkit` | Manual consistency with `AGENTS.md` and the blueprint | + +Run the selected profiles with `python .agents/scripts/verify.py `, or +the equivalent commands directly, and record actual exit results. Run them +against the committed graph, without local `[patch]` overrides. + +A missing native library, toolchain target, display, GPU, VM or Nix installation +is unavailable evidence: name it and the boundary left unverified. Never count a +skip, a feature-disabled build or a mocked boundary as proof of the real path. +Choose expensive checks by risk; do not repeat unrelated ones once the risk is +resolved. Release gates need the complete matrix in [release](release.md). + +Return a compact table of behaviors, proof and status; the commands actually run +with results; remaining gaps; and the single most valuable missing check if one +exists. Do not change product code to probe coverage unless that experiment is +authorized and isolated. diff --git a/.agents/scripts/check_toolkit.py b/.agents/scripts/check_toolkit.py new file mode 100644 index 0000000..e90b2a0 --- /dev/null +++ b/.agents/scripts/check_toolkit.py @@ -0,0 +1,174 @@ +"""Check contributor documents: local links and anchors, toolkit metadata, catalog and issue forms.""" + +import re +import sys +from pathlib import Path +from urllib.parse import unquote, urlsplit + +try: + import yaml + from markdown_it import MarkdownIt +except ImportError as error: + sys.exit(f"{error}; install .agents/scripts/requirements.txt to run the toolkit checks") + + +ROOT = Path(__file__).resolve().parents[2] +MARKDOWN = MarkdownIt("commonmark") +FRONTMATTER = re.compile(r"\A---\n(.*?)\n---(?:\n|\Z)", re.DOTALL) +CATALOGUED = ("commands", "agents", "skills") +TOP_LEVEL = ("AGENTS.md", "CONTRIBUTING.md", "README.md", "BLUEPRINT.md", + ".github/pull_request_template.md") +SLUG_DROP = re.compile(r"[^\w\- ]", re.UNICODE) + + +def body(source): + match = FRONTMATTER.match(source) + return source[match.end():] if match else source + + +def tokens(source): + for block in MARKDOWN.parse(body(source)): + yield block + yield from block.children or [] + + +def local_links(path, source, *, images=True): + """Yield (target, resolved path, fragment) for each relative link or image.""" + for token in tokens(source): + if token.type == "link_open": + target = token.attrGet("href") + elif images and token.type == "image": + target = token.attrGet("src") + else: + continue + if not target: + continue + url = urlsplit(target) + if url.scheme or url.netloc: + continue + resolved = (path.parent / unquote(url.path)).resolve() if url.path else path.resolve() + yield target, resolved, unquote(url.fragment) + + +def anchors(source): + """Return GitHub-style heading anchors, including numbered duplicates.""" + result, seen = set(), {} + blocks = MARKDOWN.parse(body(source)) + for index, block in enumerate(blocks): + if block.type != "heading_open": + continue + inline = blocks[index + 1] + text = "".join(child.content for child in inline.children or [] + if child.type in ("text", "code_inline")) + slug = SLUG_DROP.sub("", text.strip().lower()).replace(" ", "-") + count = seen.get(slug, 0) + seen[slug] = count + 1 + result.add(slug if count == 0 else f"{slug}-{count}") + return result + + +def metadata_fields(source): + """Return name/description from a YAML mapping with unique string fields, else None.""" + try: + node = yaml.compose(source, Loader=yaml.SafeLoader) + except yaml.YAMLError: + return None + if not isinstance(node, yaml.MappingNode): + return None + fields = {} + for key, value in node.value: + if (not isinstance(key, yaml.ScalarNode) or key.tag != "tag:yaml.org,2002:str" + or key.value in fields): + return None + fields[key.value] = value + result = {} + for name in ("name", "description"): + value = fields.get(name) + if not isinstance(value, yaml.ScalarNode) or value.tag != "tag:yaml.org,2002:str": + return None + result[name] = value.value + return result + + +def check_issue_forms(root): + errors = [] + for path in sorted((root / ".github/ISSUE_TEMPLATE").glob("*.yml")): + label = path.relative_to(root) + try: + form = yaml.safe_load(path.read_text(encoding="utf-8")) + except yaml.YAMLError as error: + errors.append(f"{label}: invalid YAML: {error}") + continue + if path.name == "config.yml": + if not isinstance(form, dict) or "blank_issues_enabled" not in form: + errors.append(f"{label}: missing blank_issues_enabled") + continue + if (not isinstance(form, dict) or not isinstance(form.get("name"), str) + or not isinstance(form.get("description"), str) + or not isinstance(form.get("body"), list) or not form["body"]): + errors.append(f"{label}: issue form needs name, description and a nonempty body") + continue + ids = [item.get("id") for item in form["body"] + if isinstance(item, dict) and item.get("type") != "markdown"] + if None in ids or len(ids) != len(set(ids)): + errors.append(f"{label}: every input needs a unique id") + return errors + + +def check(root): + root = root.resolve() + toolkit = root / ".agents" + catalog_path = toolkit / "README.md" + if not catalog_path.is_file(): + return ["missing .agents/README.md"] + catalog = catalog_path.read_text(encoding="utf-8") + catalog_targets = {resolved for _, resolved, _ in local_links(catalog_path, catalog, + images=False)} + errors = [] + documents = sorted(toolkit.rglob("*.md")) + [root / name for name in TOP_LEVEL] + anchor_cache = {} + for path in documents: + label = path.relative_to(root) + if not path.is_file(): + errors.append(f"missing {label}") + continue + source = path.read_text(encoding="utf-8") + for target, resolved, fragment in local_links(path, source): + if not resolved.is_relative_to(root) or not resolved.exists(): + errors.append(f"{label}: broken local link {target}") + continue + if fragment and resolved.suffix == ".md": + if resolved not in anchor_cache: + anchor_cache[resolved] = anchors(resolved.read_text(encoding="utf-8")) + if fragment not in anchor_cache[resolved]: + errors.append(f"{label}: missing anchor {target}") + relative = path.relative_to(toolkit) if path.is_relative_to(toolkit) else None + if relative and relative.parts[0] in CATALOGUED: + match = FRONTMATTER.match(source) + if not match: + errors.append(f"{label}: missing front matter") + continue + fields = metadata_fields(match[1]) + expected = path.parent.name if path.name == "SKILL.md" else path.stem + if not fields or fields["name"] != expected or not fields["description"].strip(): + errors.append(f"{label}: name must match path and description must be nonempty; " + "use a YAML mapping with unique string fields") + if path.resolve() not in catalog_targets: + errors.append(f"{label}: absent from toolkit catalog") + for kind in CATALOGUED: + if not list((toolkit / kind).rglob("*.md")): + errors.append(f"no documents in .agents/{kind}") + return errors + check_issue_forms(root) + + +def main(): + errors = check(ROOT) + if errors: + print("\n".join(errors), file=sys.stderr) + return 1 + print("Contributor toolkit links, anchors, metadata, catalog and issue forms passed.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.agents/scripts/requirements.txt b/.agents/scripts/requirements.txt new file mode 100644 index 0000000..b118050 --- /dev/null +++ b/.agents/scripts/requirements.txt @@ -0,0 +1,3 @@ +markdown-it-py==4.2.0 +mdurl==0.1.2 +PyYAML==6.0.3 diff --git a/.agents/scripts/test_toolkit.py b/.agents/scripts/test_toolkit.py new file mode 100644 index 0000000..8f1cf34 --- /dev/null +++ b/.agents/scripts/test_toolkit.py @@ -0,0 +1,239 @@ +import contextlib +import importlib.util +import io +import subprocess +import sys +import tempfile +import unittest +from pathlib import Path +from unittest.mock import patch + + +HERE = Path(__file__).resolve().parent +ROOT = HERE.parents[1] + + +def load(name): + spec = importlib.util.spec_from_file_location(f"weft_toolkit_{name}", HERE / f"{name}.py") + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +checker = load("check_toolkit") +verify = load("verify") + +SKILL = "---\nname: example\ndescription: An example skill.\n---\n[Contract](../../../AGENTS.md)\n" +COMMAND = "---\nname: run\ndescription: An example command.\n---\n# Run\n" +ROLE = "---\nname: role\ndescription: An example role.\n---\n# Role\n" +CATALOG = ("[Example](skills/example/SKILL.md)\n[Run](commands/run.md)\n" + "[Role](agents/role.md)\n") +FORM = ("name: Change\ndescription: A change.\nbody:\n" + " - type: markdown\n attributes:\n value: Intro\n" + " - type: textarea\n id: observed\n attributes:\n label: Observed\n") + + +class ToolkitCheck(unittest.TestCase): + def setUp(self): + directory = tempfile.TemporaryDirectory() + self.addCleanup(directory.cleanup) + self.root = Path(directory.name) + for name in checker.TOP_LEVEL: + path = self.root / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text("# Contract\n\n## 2. Evidence levels\n", encoding="utf-8") + self.skill = self.write(".agents/skills/example/SKILL.md", SKILL) + self.write(".agents/commands/run.md", COMMAND) + self.write(".agents/agents/role.md", ROLE) + self.catalog = self.write(".agents/README.md", CATALOG) + self.form = self.write(".github/ISSUE_TEMPLATE/change.yml", FORM) + self.write(".github/ISSUE_TEMPLATE/config.yml", "blank_issues_enabled: false\n") + + def write(self, relative, text): + path = self.root / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") + return path + + def errors_containing(self, text): + return [error for error in checker.check(self.root) if text in error] + + def append_to_skill(self, text): + self.skill.write_text(SKILL + text + "\n", encoding="utf-8") + + def test_valid_toolkit_passes(self): + self.assertEqual(checker.check(self.root), []) + + def test_missing_contract_breaks_links(self): + (self.root / "AGENTS.md").unlink() + self.assertTrue(self.errors_containing("broken local link")) + + def test_link_outside_repository_is_rejected(self): + self.append_to_skill("[Outside](../../../../outside.md)") + self.assertTrue(self.errors_containing("broken local link")) + + def test_existing_and_missing_anchors(self): + self.append_to_skill("[Levels](../../../AGENTS.md#2-evidence-levels)") + self.assertEqual(checker.check(self.root), []) + self.append_to_skill("[Levels](../../../AGENTS.md#3-missing)") + self.assertTrue(self.errors_containing("missing anchor")) + + def test_same_document_anchor(self): + self.skill.write_text(SKILL + "## Local `code` heading\n[Here](#local-code-heading)\n", + encoding="utf-8") + self.assertEqual(checker.check(self.root), []) + self.skill.write_text(SKILL + "[Here](#absent)\n", encoding="utf-8") + self.assertTrue(self.errors_containing("missing anchor")) + + def test_duplicate_headings_receive_numbered_anchors(self): + self.skill.write_text(SKILL + "## Step\n## Step\n[Second](#step-1)\n", encoding="utf-8") + self.assertEqual(checker.check(self.root), []) + + def test_literal_examples_are_not_links(self): + for example in ["`[X](missing.md)`", "```md\n[X](missing.md)\n```", + "", r"\[X](missing.md)"]: + with self.subTest(example=example): + self.append_to_skill(example) + self.assertEqual(checker.check(self.root), []) + + def test_reference_links_are_checked(self): + self.append_to_skill("[Missing][doc]\n\n[doc]: missing.md") + self.assertTrue(self.errors_containing("broken local link")) + + def test_metadata_must_match_path_and_be_unique_strings(self): + for fields in ["name: other\ndescription: Example.", "name: example\ndescription:", + "name: example\ndescription: 42", "name: example\nname: example\n" + "description: Example.", "name: example\ndescription: [unterminated"]: + with self.subTest(fields=fields): + self.skill.write_text(f"---\n{fields}\n---\n", encoding="utf-8") + self.assertTrue(self.errors_containing("name must match path")) + + def test_missing_front_matter_is_rejected(self): + self.skill.write_text("# No metadata\n", encoding="utf-8") + self.assertTrue(self.errors_containing("missing front matter")) + + def test_uncatalogued_document_is_rejected(self): + self.catalog.write_text("[Example](skills/example/SKILL.md)\n", encoding="utf-8") + errors = self.errors_containing("absent from toolkit catalog") + self.assertEqual(len(errors), 2) + + def test_catalog_needs_a_visible_link(self): + self.catalog.write_text("`[Example](skills/example/SKILL.md)`\n" + "[Run](commands/run.md)\n[Role](agents/role.md)\n", + encoding="utf-8") + self.assertTrue(self.errors_containing("absent from toolkit catalog")) + + def test_empty_toolkit_directory_is_rejected(self): + (self.root / ".agents/agents/role.md").unlink() + self.catalog.write_text("[Example](skills/example/SKILL.md)\n[Run](commands/run.md)\n", + encoding="utf-8") + self.assertTrue(self.errors_containing("no documents in .agents/agents")) + + def test_issue_forms_are_validated(self): + self.form.write_text("name: Change\nbody: []\n", encoding="utf-8") + self.assertTrue(self.errors_containing("issue form needs")) + self.form.write_text(FORM + " - type: input\n id: observed\n", encoding="utf-8") + self.assertTrue(self.errors_containing("unique id")) + self.form.write_text("name: [unterminated\n", encoding="utf-8") + self.assertTrue(self.errors_containing("invalid YAML")) + + def test_repository_toolkit_passes(self): + self.assertEqual(checker.check(ROOT), []) + + def test_missing_dependencies_fail_with_instructions(self): + result = subprocess.run([sys.executable, "-I", "-S", "-B", str(HERE / "check_toolkit.py")], + capture_output=True, text=True, check=False) + self.assertEqual(result.returncode, 1) + self.assertIn("requirements.txt", result.stderr) + + +class Runner(unittest.TestCase): + def run_quietly(self, argv): + with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()): + return verify.main(argv) + + def test_dry_run_from_another_directory_executes_nothing(self): + with tempfile.TemporaryDirectory() as directory: + result = subprocess.run( + [sys.executable, str(HERE / "verify.py"), "portable", "demos", "--dry-run"], + cwd=directory, capture_output=True, text=True, check=False, + ) + self.assertEqual(list(Path(directory).iterdir()), []) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("cargo fmt --all --check", result.stdout) + self.assertIn("--target wasm32-wasip2", result.stdout) + + def test_dry_run_calls_no_subprocess(self): + with patch.object(verify.subprocess, "run") as run: + self.assertEqual(self.run_quietly(list(verify.PROFILES) + ["--dry-run"]), 0) + run.assert_not_called() + + def test_commands_run_from_repository_root(self): + with patch.object(verify.subprocess, "run") as run: + run.return_value = subprocess.CompletedProcess([], 0) + self.assertEqual(self.run_quietly(["servo-embed"]), 0) + self.assertEqual(run.call_count, 2) + for call in run.call_args_list: + self.assertEqual(call.kwargs["cwd"], ROOT) + self.assertIsInstance(call.args[0], list) + + def test_failure_stops_remaining_checks_and_keeps_status(self): + with patch.object(verify.subprocess, "run") as run: + run.return_value = subprocess.CompletedProcess([], 7) + self.assertEqual(self.run_quietly(["portable", "linux"]), 7) + self.assertEqual(run.call_count, 1) + + def test_failure_in_later_command_stops_profile(self): + statuses = [subprocess.CompletedProcess([], 0), subprocess.CompletedProcess([], 101)] + with patch.object(verify.subprocess, "run", side_effect=statuses) as run: + self.assertEqual(self.run_quietly(["portable", "linux"]), 101) + self.assertEqual(run.call_count, 2) + + def test_signal_termination_is_failure(self): + with patch.object(verify.subprocess, "run") as run: + run.return_value = subprocess.CompletedProcess([], -9) + self.assertEqual(self.run_quietly(["toolkit"]), 1) + + def test_missing_executable_is_failure(self): + with patch.object(verify.subprocess, "run", side_effect=FileNotFoundError("cargo")): + self.assertEqual(self.run_quietly(["linux"]), 1) + + def test_real_failing_command_propagates(self): + failing = {"failing": ("fails", [[sys.executable, "-c", "raise SystemExit(3)"]])} + with patch.dict(verify.PROFILES, failing): + self.assertEqual(self.run_quietly(["failing"]), 3) + + def test_unknown_profile_is_rejected_before_execution(self): + with patch.object(verify.subprocess, "run") as run: + with self.assertRaises(SystemExit) as error: + self.run_quietly(["unknown"]) + self.assertEqual(error.exception.code, 2) + run.assert_not_called() + + def test_repeated_profiles_run_once(self): + with patch.object(verify.subprocess, "run") as run: + run.return_value = subprocess.CompletedProcess([], 0) + self.run_quietly(["servo-embed", "servo-embed"]) + self.assertEqual(run.call_count, 2) + + def test_profiles_never_mutate_install_or_publish(self): + forbidden = {"install", "add", "update", "fix", "publish", "push", "commit", "sign", + "uninstall", "--bless", "--fix", "--allow-dirty"} + for name, (_, commands) in verify.PROFILES.items(): + for command in commands: + with self.subTest(profile=name, command=command): + self.assertTrue(all(isinstance(part, str) for part in command)) + self.assertFalse(forbidden.intersection(command)) + if command[:2] == ["cargo", "fmt"]: + self.assertIn("--check", command) + + def test_cargo_checks_use_the_locked_graph(self): + for name, (_, commands) in verify.PROFILES.items(): + for command in commands: + if command[0] == "cargo" and command[1] != "fmt": + with self.subTest(profile=name, command=command): + self.assertIn("--locked", command) + + +if __name__ == "__main__": + unittest.main() diff --git a/.agents/scripts/verify.py b/.agents/scripts/verify.py new file mode 100644 index 0000000..c6207fa --- /dev/null +++ b/.agents/scripts/verify.py @@ -0,0 +1,124 @@ +"""Run WEFT OS verification profiles without installing, formatting or publishing anything. + +Each profile is a fixed list of argument arrays executed from the repository root. +The runner stops at the first failing command and returns its exit status. +""" + +import argparse +import subprocess +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] + +LINUX_CRATES = ["weft-compositor", "weft-servo-shell", "weft-app-shell"] +DEMOS = ["examples/org.weft.demo.counter", "examples/org.weft.demo.notes"] +DEMO_KEY = "examples/keys/weft-sign.pub" +RUNTIME_FEATURES = "wasmtime-runtime,net-fetch" + + +def _packages(flag, crates): + return [part for crate in crates for part in (flag, crate)] + + +PROFILES = { + "toolkit": ( + "Contributor toolkit links, catalog, metadata and runner tests", + [ + [sys.executable, "-B", ".agents/scripts/check_toolkit.py"], + [sys.executable, "-B", "-m", "unittest", "discover", "-s", ".agents/scripts", + "-p", "test_*.py"], + ], + ), + "portable": ( + "Formatting, Clippy and tests for crates built on every host (CI cross-platform)", + [ + ["cargo", "fmt", "--all", "--check"], + ["cargo", "clippy", "--workspace", *_packages("--exclude", LINUX_CRATES), + "--all-targets", "--locked", "--", "-D", "warnings"], + ["cargo", "test", "--workspace", *_packages("--exclude", LINUX_CRATES), "--locked"], + ], + ), + "linux": ( + "Clippy and tests for the Wayland compositor and feature-disabled shells (CI linux-only)", + [ + ["cargo", "clippy", *_packages("-p", LINUX_CRATES), "--all-targets", "--locked", + "--", "-D", "warnings"], + ["cargo", "test", *_packages("-p", LINUX_CRATES), "--locked"], + ], + ), + "servo-embed": ( + "Type-check both Servo hosts with the real renderer feature (CI servo-embed-linux)", + [ + ["cargo", "check", "-p", "weft-servo-shell", "--features", "servo-embed", "--locked"], + ["cargo", "check", "-p", "weft-app-shell", "--features", "servo-embed", "--locked"], + ], + ), + "runtime": ( + "Clippy and tests for weft-runtime with the Wasmtime engine and fetch enabled", + [ + ["cargo", "clippy", "-p", "weft-runtime", "--features", RUNTIME_FEATURES, + "--all-targets", "--locked", "--", "-D", "warnings"], + ["cargo", "test", "-p", "weft-runtime", "--features", RUNTIME_FEATURES, "--locked"], + ], + ), + "demos": ( + "Check the demo components for wasm32-wasip2 against their own lockfiles", + [ + ["cargo", "check", "--locked", "--manifest-path", f"{demo}/Cargo.toml", + "--target", "wasm32-wasip2", "--target-dir", "target/examples"] + for demo in DEMOS + ], + ), + "packages": ( + "Validate the demo packages and verify their committed signatures with weft-pack", + [ + command + for demo in DEMOS + for command in ( + ["cargo", "run", "--quiet", "--locked", "-p", "weft-pack", "--", "check", demo], + ["cargo", "run", "--quiet", "--locked", "-p", "weft-pack", "--", "verify", demo, + "--key", DEMO_KEY], + ) + ], + ), +} + + +def describe(): + width = max(map(len, PROFILES)) + lines = [f" {name:<{width}} {summary}" for name, (summary, _) in PROFILES.items()] + return "profiles:\n" + "\n".join(lines) + + +def main(argv=None): + parser = argparse.ArgumentParser( + description=__doc__, + epilog=describe(), + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + parser.add_argument("profiles", nargs="+", choices=PROFILES, metavar="profile", + help="one or more profiles, run in the given order") + parser.add_argument("--dry-run", action="store_true", + help="print the commands without running them") + args = parser.parse_args(argv) + + for profile in dict.fromkeys(args.profiles): + for command in PROFILES[profile][1]: + print(f"[{profile}] {subprocess.list2cmdline(command)}", flush=True) + if args.dry_run: + continue + try: + result = subprocess.run(command, cwd=ROOT, check=False) + except OSError as error: + print(f"[{profile}] cannot run {command[0]}: {error}", file=sys.stderr) + return 1 + if result.returncode != 0: + print(f"[{profile}] failed with exit status {result.returncode}", file=sys.stderr) + return result.returncode if result.returncode > 0 else 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.agents/skills/weft-appd-sessions/SKILL.md b/.agents/skills/weft-appd-sessions/SKILL.md new file mode 100644 index 0000000..b5103f7 --- /dev/null +++ b/.agents/skills/weft-appd-sessions/SKILL.md @@ -0,0 +1,59 @@ +--- +name: weft-appd-sessions +description: Use for weft-appd session lifecycle, readiness, child supervision and cleanup, the appd IPC and WebSocket bridge, and compositor association. +--- + +# Appd sessions and IPC + +Owner: `weft-appd` owns resolved package selection, effective grants, session +identity, child supervision, readiness and cleanup. The shells display that +state; they do not keep a second authoritative copy. Read the blueprint's +[resolved package descriptor](../../../BLUEPRINT.md#41-one-resolved-package-descriptor), +[role-separated protocol](../../../BLUEPRINT.md#61-role-separated-protocol) and +[single lifecycle owner](../../../BLUEPRINT.md#62-single-lifecycle-owner). + +## Where things live + +| Concern | Source | +|---|---| +| Daemon, session registry, request dispatch | [appd main.rs](../../../crates/weft-appd/src/main.rs) | +| Child spawning, preopens, systemd wrapping, data paths | [runtime.rs](../../../crates/weft-appd/src/runtime.rs) | +| Unix socket messages | [ipc.rs](../../../crates/weft-appd/src/ipc.rs) | +| Browser-facing WebSocket server | [ws.rs](../../../crates/weft-appd/src/ws.rs) | +| Compositor association client | [compositor_client.rs](../../../crates/weft-appd/src/compositor_client.rs), [weft-ipc-types](../../../crates/weft-ipc-types/src/lib.rs) | +| Image mount path | [mount.rs](../../../crates/weft-appd/src/mount.rs) | +| Injected app bridge | [app-shell embedder](../../../crates/weft-app-shell/src/embedder.rs) | +| Shell-side client | [system-ui.html](../../../infra/shell/system-ui.html) | + +## Working rules + +- One session model: `Starting -> Running -> Stopping -> Stopped`, with + structured terminal reasons. `Running` requires the component initialized, + session IPC connected, the document and bridge initialized and the surface's + first frame presented. Stdout text cannot establish readiness. +- Every exit path enters the same cleanup: spawn failure, invalid package, + initialization failure, timeout, cancellation, guest trap, child crash, + explicit close and daemon shutdown. Owned resources include both children, + portals, relays, sockets, compositor associations, temporary directories and + mounts. +- Use a process-group or systemd mechanism that is valid for the selected + systemd and preserves ownership; verify `systemd-run` argument combinations + against the installed version. Terminate gracefully for a bounded time, then + forcibly, and await settlement instead of sleeping. +- A caller-supplied `session_id` is a routing claim. Bind role, session and + generation on the server, authenticate the browser bootstrap, and never + deliver private payloads to unrelated subscribers. +- The bridge and daemon share one versioned semantic envelope. Bound frame size, + queued messages and bytes and concurrency; preserve partial frames across + cancellation; do not hold the registry lock across awaits; remove closed + relays; resynchronize from a snapshot after overflow. +- Default logs exclude application payloads, clipboard contents, saved notes and + credentials. + +## Evidence + +`python .agents/scripts/verify.py portable` runs the appd and IPC unit tests. +Lifecycle and protocol claims need fixtures with real child processes and +sockets: each startup phase failing or cancelled, children crashing, fragmented +and concurrent frames, full queues, forged and stale credentials, and checks that +no owned process, socket, relay or mount remains. diff --git a/.agents/skills/weft-compositor-input/SKILL.md b/.agents/skills/weft-compositor-input/SKILL.md new file mode 100644 index 0000000..75475fd --- /dev/null +++ b/.agents/skills/weft-compositor-input/SKILL.md @@ -0,0 +1,55 @@ +--- +name: weft-compositor-input +description: Use for the Smithay compositor, Wayland protocols, surfaces, focus, geometry, input routing and the DRM and winit backends. +--- + +# Compositor, Wayland and input + +Owner: `weft-compositor` owns surfaces, accepted geometry, focus, stacking, work +areas, input routing and presentation. Appd owns session identity; the shells +request and render. Read the blueprint's +[surface and window contract](../../../BLUEPRINT.md#72-surface-and-window-contract), +[input requirements](../../../BLUEPRINT.md#73-required-input-and-accessibility-behavior) +and [backend completion](../../../BLUEPRINT.md#74-backend-specific-completion). + +## Where things live + +| Concern | Source | +|---|---| +| Wayland globals and handlers (xdg-shell, layer-shell, DMA-BUF state, presentation) | [state.rs](../../../crates/weft-compositor/src/state.rs) | +| Keyboard, pointer and wheel routing | [input.rs](../../../crates/weft-compositor/src/input.rs) | +| `zweft-shell-unstable-v1` server side | [protocols/mod.rs](../../../crates/weft-compositor/src/protocols/mod.rs), [protocol XML](../../../protocol/weft-shell-unstable-v1.xml) | +| Appd association channel | [appd_ipc.rs](../../../crates/weft-compositor/src/appd_ipc.rs), [weft-ipc-types](../../../crates/weft-ipc-types/src/lib.rs) | +| Nested backend | [backend/winit.rs](../../../crates/weft-compositor/src/backend/winit.rs) | +| DRM/KMS, udev, libinput, session | [backend/drm.rs](../../../crates/weft-compositor/src/backend/drm.rs), [backend/drm_device.rs](../../../crates/weft-compositor/src/backend/drm_device.rs) | + +## Working rules + +- Verify Smithay behavior in the `smithay 0.7` source selected by `Cargo.lock` + (output frame submission, DMA-BUF global creation, seat and focus handling), + not in newer upstream examples. Advertise only globals the compositor actually + serves. +- Bind surfaces to sessions through trusted launch or connection evidence and + observed client identity, with opaque IDs and generations. A PID, title or + custom shell-protocol request is not authority. Only the trusted shell acquires + privileged roles such as `panel`. +- Effective xdg geometry and acknowledged configure state must agree; echoing a + `set_geometry` request does not move a surface. +- Prevent stuck keys and buttons after focus loss, client exit, drag + cancellation and output changes. Keep logical and physical coordinates + consistent across scale changes. +- DRM paths need the frame completion transition, presentation feedback, + idle and empty-frame scheduling that resumes on commits, session pause and + activation, and error recovery. Do not replace existing layer rendering on a + false premise. + +## Evidence + +`python .agents/scripts/verify.py portable linux` covers compilation, lints and +the protocol unit tests in `protocols/mod.rs`. It does not run a compositor. +Geometry, focus, stacking, input and presentation claims need a nested winit +session with real clients, and DRM claims need a DRM session on the declared +target; see [integration verification](../weft-integration-verification/SKILL.md). +The compositor and both shells generate their protocol code from the same XML, +so a protocol change affects all three; check them with the `linux` and +`servo-embed` profiles and keep the interface version deliberate. diff --git a/.agents/skills/weft-documentation/SKILL.md b/.agents/skills/weft-documentation/SKILL.md new file mode 100644 index 0000000..aa26fc7 --- /dev/null +++ b/.agents/skills/weft-documentation/SKILL.md @@ -0,0 +1,53 @@ +--- +name: weft-documentation +description: Use for WEFT OS public documentation, the blueprint, this contributor toolkit, issue and pull request templates and the verification runner. +--- + +# Documentation and the toolkit + +[AGENTS.md](../../../AGENTS.md) is the only policy source. The +[blueprint](../../../BLUEPRINT.md) holds accepted direction. Public documentation +in [README.md](../../../README.md) and [docs/](../../../docs/architecture.md) +describes implemented behavior and must agree with source. + +## Working rules + +- Verify every command, path, feature, environment variable and API you document + against the current source, and run commands where practical. Keep blueprint + intent, implemented behavior and executed evidence distinct: "implemented", + "verified" and "planned" are different claims. +- Correct documentation that contradicts source instead of working around it; + for example, a pin file that disagrees with `Cargo.lock`, or a signing + description that differs from the implemented inventory. +- Link durable decisions and requirements to their owning artifact. Toolkit files + provide procedures and area knowledge, never a second policy, permissions, + schedules or an internal log. +- Write issues, pull requests, commits and release notes for maintainers: the + problem, the resulting behavior and the evidence. No attribution, trailers, + prompts or process narration. +- Keep Markdown portable: standard CommonMark links and tables, YAML front matter + with `name` and `description` only, no client-specific syntax required to + follow a procedure. + +## Toolkit changes + +Add area knowledge in a skill, repeatable steps in a command, review criteria in +a role and executable checks in `.agents/scripts/`. Update the +[catalog](../../README.md) for every new document. Then run: + +```sh +pip install -r .agents/scripts/requirements.txt +python .agents/scripts/verify.py toolkit +``` + +That checks links, anchors, metadata, catalog coverage and issue forms, and runs +the runner tests. For runner changes, add tests for failure propagation, +unknown input, missing executables and execution from another directory. Review +the instructions manually against `AGENTS.md`, the blueprint and CI; passing +checks does not establish that the instructions are true. + +Changes to the blueprint or contract are governance changes: follow the +[reviewed loop](../../../AGENTS.md#5-reviewed-change-loop), check every document +that links to the changed sections, and seek a +[decision](../../../AGENTS.md#9-decisions-and-authority) for a material change of +direction. diff --git a/.agents/skills/weft-integration-verification/SKILL.md b/.agents/skills/weft-integration-verification/SKILL.md new file mode 100644 index 0000000..912a1d3 --- /dev/null +++ b/.agents/skills/weft-integration-verification/SKILL.md @@ -0,0 +1,54 @@ +--- +name: weft-integration-verification +description: Use for end-to-end and visual evidence in WEFT OS — real sessions, pixels and native input, failure injection, reliability runs and evidence records. +--- + +# Integration and visual verification + +Integration evidence shows what unit tests cannot: real frames, native input, +real child processes, real components and an installed system. Read the +blueprint's [evidence levels](../../../BLUEPRINT.md#111-evidence-levels), +[verification profiles](../../../BLUEPRINT.md#112-verification-profiles), +[acceptance fixtures](../../../BLUEPRINT.md#113-required-acceptance-fixtures) and +[user journeys](../../../BLUEPRINT.md#22-required-user-journeys). + +## Fixture design + +- Choose the fixture before implementing. It must fail when the promised + behavior breaks and must not restate the implementation or only grep a success + log. +- For rendering, use a deterministic page with known color regions, text, + scrolling content, a text field, an interactive counter and a controlled + animation. Compare actual pixels read back after painting at the relevant + scales and sizes, including first frame, resize and idle wakeup. +- For input, drive the real native path on a running compositor: key press and + release, modifiers, declared US and Italian layouts with non-ASCII text, + buttons, motion, wheel, focus changes and scale changes. Check for stuck input + after focus loss and client exit. +- For lifecycle, inject failures at each startup phase and after `Running`: + missing binary, invalid package, renderer failure, runtime trap, crash, + cancellation and timeout. Assert a terminal reason and that no owned process, + socket, relay or mount remains. +- For data, use Notes with empty, non-ASCII, multi-line, quoted and literal + backslash text, delayed replies, failed writes and competing writers; repeat + after close, daemon restart, update and reboot. +- Counter and Notes are conformance applications: their happy paths are + necessary but insufficient. + +## Running and recording + +The [runner](../../scripts/verify.py) provides only build, lint, unit and +package checks. Integration fixtures run in the environment they claim: a nested +winit session for nested-desktop evidence, a DRM session on the declared target, +the booted reference image for installed behavior. Keep captures and logs under +ignored paths such as `target/`; commit fixtures, not their outputs. + +Record for each run the commit, environment (host, compositor backend, GPU or +virtual device, Mesa, kernel), enabled features, exact command, observed result +and diagnostics. A screenshot shows pixels, not input routing or accessibility. +An unavailable display, GPU or VM leaves the gate incomplete; say which boundary +remained unverified. + +Reliability qualification follows the blueprint targets: repeated clean boots, +launch and close cycles without orphans, mixed interactive and idle runs. +Performance and budget claims need measurements on the reference target. diff --git a/.agents/skills/weft-linux-deployment/SKILL.md b/.agents/skills/weft-linux-deployment/SKILL.md new file mode 100644 index 0000000..9b53ab9 --- /dev/null +++ b/.agents/skills/weft-linux-deployment/SKILL.md @@ -0,0 +1,53 @@ +--- +name: weft-linux-deployment +description: Use for the Nix flake and reference VM, systemd units, native dependencies, installed paths, endpoints and service activation. +--- + +# Linux deployment + +Owner: Linux and systemd own the seat, session substrate, service lifecycle and +process and resource boundaries. The installed closure must carry the real +feature-enabled product. Read the blueprint's +[release profile](../../../BLUEPRINT.md#21-required-release-profile), +[installed session](../../../BLUEPRINT.md#102-installed-session) and +[developer workflow](../../../BLUEPRINT.md#103-diagnostics-and-developer-workflow). + +## Where things live + +| Concern | Source | +|---|---| +| Flake, toolchain, dev shell | [flake.nix](../../../flake.nix), [flake.lock](../../../flake.lock) | +| Package derivations and features | [weft-packages.nix](../../../infra/nixos/weft-packages.nix) | +| VM configuration | [configuration.nix](../../../infra/nixos/configuration.nix) | +| VM build and run | [build.sh](../../../infra/vm/build.sh), [run.sh](../../../infra/vm/run.sh) | +| Service units | [infra/systemd](../../../infra/systemd/weft-appd.service) | +| Native build dependencies | [building.md](../../../docs/building.md), [CI](../../../.github/workflows/ci.yml) | +| Environment variables | [architecture.md](../../../docs/architecture.md) and the `std::env` reads in each crate | + +## Working rules + +- Keep one authoritative Nix and systemd configuration; make development units + and scripts consistent with it. +- The closure includes the feature-enabled binaries (`servo-embed` for both + shells, `wasmtime-runtime` for the runtime), the shell HTML and UI assets at + installed paths, reference packages with an explicit trust configuration, the + binary paths appd needs, and explicit activation and dependencies. +- Pass the real compositor display and daemon endpoints; never guess names such + as `wayland-1`. Keep persistent data and ephemeral runtime storage separate. +- Fill fixed-output hashes, including Servo's git `outputHashes`, from an actual + build, never by copying an unrelated value. +- Never fabricate `pkg-config` files or library versions to satisfy a build. + Repair the environment or exclude the feature explicitly. Do not commit + machine-specific usernames or checkout paths. +- Record the exact VM machine, graphics device, kernel, Mesa, CPU and memory + used for evidence. A headless VM or a successful evaluation is not graphical + acceptance. + +## Evidence + +The runner has no Nix or VM profile. Build with `bash infra/vm/build.sh` and run +with `bash infra/vm/run.sh` where Nix with flakes is available, and record the +environment. Installed-system claims need a fresh graphical boot that starts the +complete system without checkout paths or manual repair, plus persistence across +reboot and update. A missing Nix installation or virtualization support is +unavailable evidence. diff --git a/.agents/skills/weft-packages-data/SKILL.md b/.agents/skills/weft-packages-data/SKILL.md new file mode 100644 index 0000000..3c7003c --- /dev/null +++ b/.agents/skills/weft-packages-data/SKILL.md @@ -0,0 +1,57 @@ +--- +name: weft-packages-data +description: Use for wapp.toml manifests, weft-pack, signing and trust, installation and updates, app data storage and EROFS dm-verity images. +--- + +# Packages, trust, data and updates + +Owner: package tooling owns manifest validation, content identity, trust, +staging, activation and retention. User data has its own lifecycle and is never +owned by installed package bytes. Read the blueprint's +[packages, trust, storage and updates](../../../BLUEPRINT.md#9-packages-trust-storage-and-updates) +and [Notes requirements](../../../BLUEPRINT.md#82-notes). + +## Where things live + +| Concern | Source | +|---|---| +| `check`, `info`, `install`, `uninstall`, `list`, `generate-key`, `sign`, `verify`, `bundle`, `unbundle`, `build-image`, `build-verity` | [weft-pack](../../../crates/weft-pack/src/main.rs) | +| Manifests | [counter wapp.toml](../../../examples/org.weft.demo.counter/wapp.toml), [notes wapp.toml](../../../examples/org.weft.demo.notes/wapp.toml) | +| Demo signing fixture keys | [examples/keys](../../../examples/keys/weft-sign.pub) | +| Data and package roots used at launch | [appd runtime.rs](../../../crates/weft-appd/src/runtime.rs) | +| Image mount and privileged helper | [appd mount.rs](../../../crates/weft-appd/src/mount.rs), [weft-mount-helper](../../../crates/weft-mount-helper/src/main.rs) | + +## Working rules + +- The implemented signature covers the recursively enumerated package inventory, + including UI content and excluding the signature file, and both demo + signatures verify under it. Preserve that compatibility deliberately when + formalizing the format; do not re-sign demos to match a different description. + Correct documentation that describes a narrower inventory. +- Demo keys are fixtures and never production signing authority. Release + private keys stay outside the repository. +- Separate verified and development installation policies. Verified installs + fail closed on invalid, missing, revoked or untrusted signatures; development + installs are explicit and visibly marked. +- Validate IDs, entry containment, duplicates, link policy and the actual + component before trust decisions. Bind each app ID and its retained data to a + publisher key policy. +- Install and update through staging, validation, verification, immutable + content and atomic activation. Failure preserves the previous active revision + and user data; a live session stays pinned to its revision; uninstall keeps + data unless an explicit purge is requested. +- Migrating the existing `apps//data` layout needs detection, backup, conflict + handling and a test proving Notes contents survive. Keep it out of unrelated + cleanups. +- Verified image mode never falls back to a mutable directory, and the privileged + helper is enabled only after its caller authorization and failure paths are + specified and tested. + +## Evidence + +`python .agents/scripts/verify.py portable packages` runs the package unit tests +and checks and verifies the committed demo packages. Trust, install and update +claims need tamper, interruption, publisher-ownership, active-update and +uninstall fixtures from the blueprint's +[acceptance list](../../../BLUEPRINT.md#113-required-acceptance-fixtures), and +persistence claims need reruns after reinstall, restart and reboot. diff --git a/.agents/skills/weft-runtime-capabilities/SKILL.md b/.agents/skills/weft-runtime-capabilities/SKILL.md new file mode 100644 index 0000000..602a887 --- /dev/null +++ b/.agents/skills/weft-runtime-capabilities/SKILL.md @@ -0,0 +1,58 @@ +--- +name: weft-runtime-capabilities +description: Use for the Wasmtime runtime, WIT host imports, WASI preopens, effective grants, the file portal and seccomp. +--- + +# Runtime, WASI and capabilities + +Owner: `weft-runtime` instantiates the component and enforces every host call; +appd derives the effective grants once from the resolved package. Portals and +host services act only on explicitly granted resources. Read the blueprint's +[security and capability contract](../../../BLUEPRINT.md#5-security-and-capability-contract) +and [component compatibility](../../../BLUEPRINT.md#42-manifest-and-component-compatibility). + +## Where things live + +| Concern | Source | +|---|---| +| Engine setup, linker, host imports, preopens, seccomp | [weft-runtime main.rs](../../../crates/weft-runtime/src/main.rs) | +| Host WIT (`weft:app@0.1.0`: notify, ipc, fetch, notifications, clipboard) | [weft-app.wit](../../../crates/weft-runtime/wit/weft-app.wit) | +| Demo copies of the WIT | `examples/*/wit/deps/weft-app/weft-app.wit` | +| Capability strings accepted at package check | `is_known_capability` and its `EXACT` list in [weft-pack](../../../crates/weft-pack/src/main.rs) | +| Capability to preopen mapping at launch | [appd runtime.rs](../../../crates/weft-appd/src/runtime.rs) | +| File portal | [weft-file-portal](../../../crates/weft-file-portal/src/main.rs) | + +## Working rules + +- Features: `wasmtime-runtime` enables the engine, `net-fetch` the fetch import, + `seccomp` the syscall blocklist. Without `wasmtime-runtime` the binary prints + READY and exits; that path is a limited build fixture, never product + evidence. +- Verify Wasmtime and wasmtime-wasi behavior in the version `Cargo.lock` + selects, including how the linker treats differing WIT patch versions. A + textual version difference is not an ABI defect until an actual component + shows it. +- Every advertised import checks the effective grant on every call. Absent or + unsupported operations fail explicitly; they are not successful no-ops. +- Keep read-only and read/write access distinct through preopens and the + portal. Confinement uses descriptor-relative or equivalent kernel-enforced + operations; lexical prefix checks and `canonicalize()` followed by reopening + are not sufficient against symlinks and replacement races. +- Fetch needs explicit schemes, destinations, methods, deadlines, size limits + and redirect authorization; keep HTTP errors distinct from transport errors. +- Keep one canonical WIT source with a checked synchronization mechanism for its + copies. +- Do not describe the seccomp blocklist or process separation as complete + confinement. + +## Evidence + +`python .agents/scripts/verify.py portable runtime` covers the stub and the +engine-enabled build, lints and unit tests. It does not instantiate a component. +Host import behavior needs an actual component fixture for the allowed, denied +and failure paths of each import; confinement needs traversal, symlink and +race cases against the real portal and preopens. No profile or CI job compiles +the `seccomp` feature; check it on Linux with +`cargo clippy -p weft-runtime --features wasmtime-runtime,seccomp --all-targets --locked -- -D warnings` +and prove filtering with a component or process fixture, not by compilation. +Rebuild demo components with the `demos` profile when the WIT changes. diff --git a/.agents/skills/weft-servo-rendering/SKILL.md b/.agents/skills/weft-servo-rendering/SKILL.md new file mode 100644 index 0000000..263cf93 --- /dev/null +++ b/.agents/skills/weft-servo-rendering/SKILL.md @@ -0,0 +1,72 @@ +--- +name: weft-servo-rendering +description: Use for the Servo embedders, painting and presentation, the Servo fork and Stylo overrides, the system UI and application pages. +--- + +# Servo rendering and the forks + +Owners: `weft-servo-shell` renders trusted system chrome; `weft-app-shell` +renders one untrusted application document and its narrow bridge. Neither holds +session lifecycle. Read the blueprint's +[Servo host contract](../../../BLUEPRINT.md#71-servo-host-contract), +[system interface](../../../BLUEPRINT.md#8-system-interface-and-application-behavior) +and [build policy](../../../BLUEPRINT.md#101-one-reproducible-product-build). + +## Where things live + +| Concern | Source | +|---|---| +| System shell host and event loop | [weft-servo-shell embedder](../../../crates/weft-servo-shell/src/embedder.rs), [main.rs](../../../crates/weft-servo-shell/src/main.rs) | +| Application host, `resolve_weft_app_url` (app ID and `ui.entry` to a `file://` URL), injected bridge | [weft-app-shell embedder](../../../crates/weft-app-shell/src/embedder.rs), [main.rs](../../../crates/weft-app-shell/src/main.rs) | +| Key mapping | [servo-shell keyutils](../../../crates/weft-servo-shell/src/keyutils.rs), [app-shell keyutils](../../../crates/weft-app-shell/src/keyutils.rs) | +| Shell protocol clients | [servo-shell client](../../../crates/weft-servo-shell/src/shell_client.rs), [app-shell client](../../../crates/weft-app-shell/src/shell_client.rs) | +| System UI page and UI kit | [system-ui.html](../../../infra/shell/system-ui.html), [weft-ui-kit.js](../../../infra/shell/weft-ui-kit.js) | +| Pin notes (not authoritative for the selected revision) | [SERVO_PIN.md](../../../crates/weft-servo-shell/SERVO_PIN.md) | + +## Selected revisions + +The Servo and Stylo revisions are the ones `Cargo.lock` records for the `servo` +and `stylo` packages, not a branch name or `SERVO_PIN.md`. Servo comes from the +`marcoallegretti/servo` fork; Stylo currently comes from upstream `servo/stylo`, +because no root-level override selects the `marcoallegretti/stylo` fork. Inspect +them with: + +```sh +grep -A2 'name = "servo"' Cargo.lock +grep -A2 'name = "stylo"' Cargo.lock +``` + +Read the `servo` crate (`components/servo`), shared embedder input types and +rendering contexts at that revision before using an API. Servo's own `[patch]` +tables do not apply to WEFT: a Stylo override that a Servo-fork feature depends +on must be declared in WEFT's root `Cargo.toml` and confirmed in the resolved +graph. Each fork patch keeps a purpose, upstream status and removal condition. + +For cross-repository work, clone the forks next to WEFT and point Cargo at them +with local `[patch]` entries outside the repository. Those overrides rewrite +`Cargo.lock`; never commit that change, and rerun checks without the overrides +before reporting evidence for the committed graph. + +## Working rules + +- A frame exists only after `WebView::paint` and the backend's present + operation. Event-loop progress, a READY message or a softbuffer present of an + unpainted buffer is not a rendered frame. Readback follows painting. +- Handle zero-size and minimized windows, resize, output scale, first frame, + idle wakeup and shutdown without continuous unbounded repainting. +- Keep the trust distinction: system-control endpoints and credentials never + reach application documents. Policy for package resources, navigation, + downloads, file URLs and network requests is enforced in the engine or OS, not + in page JavaScript. +- Treat manifest names, descriptions and icons as untrusted in the launcher; no + unsafe HTML injection. Use one endpoint configuration and bridge. +- Extract common host, render and input code only after one working path exists + in both hosts. + +## Evidence + +`python .agents/scripts/verify.py servo-embed` type-checks both hosts with the +real renderer. Without `servo-embed` the shells build as stubs; their success is +not rendering evidence. Rendering, input and backdrop or transparency claims need +the deterministic page and pixel checks described in +[integration verification](../weft-integration-verification/SKILL.md). diff --git a/.github/ISSUE_TEMPLATE/change.yml b/.github/ISSUE_TEMPLATE/change.yml new file mode 100644 index 0000000..47f4260 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/change.yml @@ -0,0 +1,63 @@ +name: Defect or change +description: Report a concrete defect or propose an ordinary change within accepted architecture. +body: + - type: markdown + attributes: + value: | + Use a title that states the defect or the behavior that should hold. Search existing issues + and pull requests first. Use the Decision form for a material change of product direction, + public compatibility, trust boundaries, support scope or data policy. + - type: textarea + id: observed + attributes: + label: Observed + description: What happens now, and who or what is affected (user journey, caller, contract, test harness, contributor). + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected + description: What should hold instead. Cite the implemented contract or the BLUEPRINT.md section, and say which one applies. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Evidence + description: Commit, environment (host, compositor backend, GPU or VM), enabled features, exact reproduction steps and actual output, with file and line references. + validations: + required: true + - type: textarea + id: owner + attributes: + label: Owner and boundary + description: The owning component (compositor, servo-shell, app-shell, appd, runtime, package tooling, portal, deployment) and any public contract touched (wapp.toml, WIT, shell protocol, IPC types). + validations: + required: true + - type: textarea + id: impact + attributes: + label: Why it matters now + description: The concrete present impact. A hypothetical future need or a stylistic preference is not enough. + validations: + required: true + - type: textarea + id: acceptance + attributes: + label: Acceptance criterion + description: One independently checkable condition that resolves this issue. Keep unrelated work out of scope. + validations: + required: true + - type: textarea + id: proof + attributes: + label: Expected proof + description: The test, component or integration fixture, pixel check or measurement that fails today and will pass afterwards, and the environment it needs. Compilation and mocks do not prove rendering, input, isolation or persistence. + validations: + required: true + - type: textarea + id: scope + attributes: + label: Scope and related work + description: Related issues, pull requests or blueprint findings, and explicit non-goals. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..9bbaced --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Contribution guide + url: https://github.com/marcoallegretti/WEFT_OS/blob/main/CONTRIBUTING.md + about: Read the contribution workflow, ownership and validation guidance before opening an issue or pull request. diff --git a/.github/ISSUE_TEMPLATE/decision.yml b/.github/ISSUE_TEMPLATE/decision.yml new file mode 100644 index 0000000..4f88287 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/decision.yml @@ -0,0 +1,58 @@ +name: Decision +description: Request a maintainer decision on a material change of direction, compatibility, trust boundaries, support scope or data policy. +body: + - type: markdown + attributes: + value: | + This form requests a decision before implementation; opening it does not approve the change. + Ordinary implementation of an accepted BLUEPRINT.md boundary does not need this form. + Search existing decisions and issues first. + - type: textarea + id: observed + attributes: + label: Observed + description: The current problem and the concrete affected user, caller or contract. + validations: + required: true + - type: textarea + id: direction + attributes: + label: Accepted direction affected + description: The BLUEPRINT.md section, public contract or support promise this would change, and how. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Evidence + description: Commit, source references, executed checks and the selected dependency revisions that establish the problem. Separate verified facts from assumptions. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives and trade-offs + description: Viable options including keeping the current direction, with their costs for ownership, security, data, compatibility and schedule. + validations: + required: true + - type: textarea + id: decision + attributes: + label: Decision requested + description: The specific decision needed and the work it unblocks. Independent authorized work continues meanwhile. + validations: + required: true + - type: textarea + id: acceptance + attributes: + label: Acceptance criterion + description: The independently evaluable outcome an accepted option must satisfy. + validations: + required: true + - type: textarea + id: proof + attributes: + label: Expected proof + description: The fixtures, measurements or integration evidence that will show the chosen option works. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/maintenance.yml b/.github/ISSUE_TEMPLATE/maintenance.yml new file mode 100644 index 0000000..1520440 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/maintenance.yml @@ -0,0 +1,58 @@ +name: Maintenance +description: Report one present duplication, structural or misleading-fallback problem that is independent of active development. +body: + - type: markdown + attributes: + value: | + Search existing issues and pull requests for the same underlying problem first. Maintenance + preserves accepted behavior, public contracts and ownership; use the Decision form if + resolving the problem changes them. One problem maps to one branch and one pull request. + - type: textarea + id: observed + attributes: + label: Observed + description: One concrete duplicated decision, unnecessary state, misleading fallback, coupling or obsolete path, and who or what it affects today. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected + description: The intended structure and the behavior, contracts and ownership that must stay unchanged. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Evidence + description: Commit and file and line references that demonstrate the problem and its present cost. + validations: + required: true + - type: textarea + id: owner + attributes: + label: Owner and boundary + description: The owning component and why the problem can be resolved without a decision of direction. + validations: + required: true + - type: textarea + id: impact + attributes: + label: Why it matters now + description: The observable present cost. Generic cleanup wishes and speculative abstractions do not qualify. + validations: + required: true + - type: textarea + id: acceptance + attributes: + label: Acceptance criterion + description: One independently verifiable outcome. + validations: + required: true + - type: textarea + id: proof + attributes: + label: Expected proof + description: The checks or fixtures that show the problem is resolved and the accepted behavior is preserved. + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..a5d1d63 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,29 @@ +## Problem and scope + + + +## What changed + + + +## Ownership + + + +## What proves it + + + +## Validation performed + + + +## Manual verification + + + +## Limitations and related issues + + + + diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0c131fe..12e1b8c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -111,3 +111,16 @@ jobs: cargo check -p weft-app-shell --features servo-embed + + # Contributor contract, toolkit documents and verification runner. + contributor-toolkit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - name: install toolkit check dependencies + run: python -m pip install -r .agents/scripts/requirements.txt + - name: check contributor toolkit + run: python .agents/scripts/verify.py toolkit diff --git a/.gitignore b/.gitignore index 0bea95b..19b91a3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /target/ +__pycache__/ /.windsurf/ /docu_dev/ @@ -6,3 +7,4 @@ /infra/vm/*.qcow2 Thumbs.db + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..024aa02 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,368 @@ +# WEFT OS engineering contract + +This is the single engineering contract for everyone who changes WEFT OS: +maintainers and external contributors. It governs scope, evidence, review, validation, branches and publication. + +[`.agents/`](.agents/README.md) contains linked procedures, review roles, area +knowledge and a verification runner. Those files help apply this contract. They +do not define competing policy, grant permissions, schedule work, change the +active working mode or add approval steps. Local tool configuration may point +here; it must not restate, weaken or reinterpret these rules. + +## 1. Sources of truth + +| Question | Authority | +|---|---| +| Accepted product direction, ownership, support scope and completion criteria | [BLUEPRINT.md](BLUEPRINT.md) | +| Implemented behavior | Source code and the checks that actually executed against it | +| Public contracts | Package manifests (`wapp.toml`), [WIT](crates/weft-runtime/wit/weft-app.wit), the [shell protocol](protocol/weft-shell-unstable-v1.xml), [IPC types](crates/weft-ipc-types/src/lib.rs) and the versioned specifications that replace them | +| Selected dependency APIs | [Cargo.lock](Cargo.lock) and the demo lockfiles, at the exact selected revisions | +| Engineering process | This file | + +The blueprint describes where WEFT is going. It is not evidence that a behavior +exists. Code that resembles a blueprint requirement does not satisfy it until +the requirement's acceptance evidence passes. Existing documentation, pin files +and version labels cannot establish behavior on their own; where they disagree +with source or executed checks, the documentation is wrong and needs correcting. + +Before changing a public contract, inspect existing compatibility promises and +callers. Preserve compatibility deliberately or provide a tested conversion or +error path. + +When evidence contradicts the blueprint, preserve its intent, establish why the +discrepancy exists and choose the maintainable evidence-backed solution. A +material change of direction follows [section 9](#9-decisions-and-authority). + +## 2. Evidence + +Never invent an API, protocol behavior, platform guarantee, capability or +measurement. Verify uncertain assumptions against the selected dependency +revision before relying on them: read the source of the crate version recorded +in the lockfile (Servo, Stylo, Smithay, Wasmtime, wasmtime-wasi, Tokio, winit, +surfman and others), not current upstream documentation or memory. Record the +revision used when the result matters to the change. + +Research order: repository contracts and evidence, selected dependency source, +upstream documentation for that version, relevant standards or protocols, +comparable mature implementations, then a measured experiment. + +The blueprint's [evidence levels](BLUEPRINT.md#111-evidence-levels) define what +each kind of check can establish. In particular: + +- Compilation, type-checking and clippy prove that code builds, not that it + renders, routes input, isolates, persists or recovers. +- Mocked sockets, DOMs, processes or compositors prove the logic exercised + against the mock, not the real boundary. +- A capability string in a manifest, a host function registration or a + frontend check does not prove enforcement. +- A success log line, `READY` message or exit code `0` from a feature-disabled + build does not prove readiness of the product path. +- A skipped check, missing environment or unavailable device is an incomplete + gate, never a pass. + +Record the commit, environment, enabled features, exact command or harness, +result and useful diagnostics for evidence other contributors will rely on. +Distinguish tests that executed from tests that were only designed. + +## 3. Ownership + +Every change has an owner from the +[blueprint ownership table](BLUEPRINT.md#4-architecture-and-ownership). Identify +it before implementation. Do not let a component implicitly acquire +responsibility that belongs elsewhere: + +- `weft-compositor` owns surfaces, geometry, focus, stacking, input routing and + presentation. +- `weft-appd` owns package selection, effective grants, session identity, child + supervision, readiness and cleanup. +- `weft-runtime` owns component instantiation and enforced host calls. +- `weft-servo-shell` and `weft-app-shell` render; they hold no second copy of + session lifecycle and no authority the session did not grant. +- Package tooling owns validation, content identity, trust, staging and + activation; it does not own user data. + +Keep the UI and Wasm runtime in separate processes. Share code where behavior is +actually common, without merging privileges or failure domains. Do not replace +the compositor, browser engine or runtime as a shortcut around finishing their +contracts. Introduce a shared crate or abstraction only when it removes present +duplication or establishes a single source of truth. + +## 4. Working modes + +The modes below do not mix silently. Loading an `.agents/` file never switches +mode. + +**Primary development** advances the blueprint under maintainer direction. A +goal may span many consecutive changes. At the start of a new goal, read the +blueprint and inspect the relevant source, manifests, tests, CI, lockfiles, +pins and Git state. Afterwards, reinspect the changed boundary and new evidence +for each step instead of repeating full discovery. Continue autonomously through +successive accepted changes while authorized independent work remains; do not +stop after a single patch or pull request. Fix related debt inside the active +acceptance criterion. + +**Contribution** carries one issue or explicitly accepted scope through an +isolated branch to a pull request. + +**Maintenance** handles exactly one qualifying problem that is unrelated to the +active goal, under [section 8](#8-maintenance). It never modifies the active +development checkout. + +## 5. Reviewed change loop + +Apply this loop to every workflow: primary development, fixes, simplification, +refactoring, dependency changes, build and packaging, documentation, governance +and release preparation. + +1. **Inspect** current evidence and the implemented and accepted contract. +2. **State** the present problem, owner, bounded scope, observable acceptance + criterion and the proof that will show it. +3. **Review scope** — ownership, proof and design — before changing the affected + boundary. +4. **Implement** one coherent result, preserving unrelated work. +5. **Validate** with the smallest sufficient checks for the changed behavior and + its concrete risks. +6. **Review the actual diff** against acceptance, compatibility, security, data + and failure behavior. +7. **Correct** findings, revalidate and review the corrected content. +8. **Accept** an atomic result only when no blocking finding remains, then + **reassess** the next dependent step from the new repository state. + +Do not stop after planning when implementation and verification are possible. +Do not advance dependent work while a blocking finding is open. + +## 6. Proof before implementation + +Identify what proves a change before or alongside implementing it. For a defect, +reproduce the failure first. For new behavior, establish the fixture, contract +case or invariant that will fail when the behavior is wrong. Proof must fail +when the promised behavior breaks; a test that restates the implementation or +only inspects a success log is not proof. + +| Change | Expected proof | +|---|---| +| Parser, serialization, state machine | Unit or contract tests with accepting and rejecting cases | +| Host import or capability | Actual component fixture: allowed, denied and failure paths | +| IPC or session protocol | Integration test over the real transport: framing, authorization, limits, cancellation | +| Session lifecycle | Child-process fixtures for each start, failure, cancellation and teardown path, checking owned resources settle | +| Rendering or presentation | Deterministic page with known pixels on the supported backend; readback after paint | +| Input or window management | Native input and geometry on a real compositor backend | +| Filesystem confinement | Traversal, symlink and replacement-race cases against the real implementation | +| Package trust, install or update | Tamper, interruption and data-retention fixtures | +| Installed system | Built and booted reference image | +| Dependency change | Resolved graph inspection plus the checks of every affected boundary | +| Performance claim | Repeatable measurement on the named target | +| Documentation or toolkit | Claims checked against source; links, catalog and metadata checks | + +A change without an identifiable proof surface is not ready unless the +limitation is intrinsic and stated in the result. Never update expected output, +re-sign fixtures or regenerate artifacts merely to turn a failing check green; +explain the contractual reason for every changed expectation. + +## 7. Definition of done + +A change is done when its contract is coherent and evidenced, not when it +compiles. + +- No synthetic success: feature-disabled builds, stubs and fallbacks must not + report readiness, success or enforcement they do not provide. +- No silent no-ops for unsupported operations; fail explicitly with a useful + diagnostic. +- No product UI or documentation that promises unavailable behavior. +- No placeholder paths left knowingly incomplete in a supported product path. +- Security and data preservation are part of the first implementation, not a + later hardening stage. +- Accessibility, keyboard operation, scaling and declared keyboard layouts are + product requirements where the change touches them. + +Prefer small explicit APIs, deletion over new abstraction and existing concepts +over new ones. Add a dependency only for concrete value. + +## 8. Maintenance + +Maintenance work never rides inside an unrelated development branch and never +switches or edits the active development checkout. + +An issue is justified only when all of these hold: a concrete affected user, +caller, contract, test harness or contributor can be named; repository evidence +demonstrates the problem; it matters in the current state; and it has an +independently verifiable acceptance criterion. Stylistic preferences, +hypothetical future needs and generic cleanup wishes do not qualify. Search for +an existing issue or pull request first and update it instead of duplicating. + +One maintenance run handles one qualifying problem: + +1. Verify the current default branch (`main`) by fetching it. If freshness + cannot be verified, state the actual revision and the limitation. +2. Create one isolated worktree and one descriptive branch from it. +3. Follow the [reviewed loop](#5-reviewed-change-loop) to one reviewed pull + request, or to a prepared local result when publication is not authorized. +4. Stop. Do not continue collecting opportunities. + +The maintenance roles in [`.agents/agents/`](.agents/README.md#roles) apply this +section: + +- **Architecture debt scout** inspects and reports the strongest justified + issue. It edits no repository files and creates no implementation branches or + commits. It may prepare or publish that issue only within granted authority. + When nothing meets the threshold, it says so and stops. +- **Continuous simplicity** removes duplicated decisions, unnecessary state and + misleading fallback paths without changing accepted behavior. +- **Continuous refactoring** changes internal structure while preserving accepted + behavior, ownership and proof. + +Neither simplification nor refactoring is a license for repeated architecture +replacement or line-count optimization at the expense of explicit authority, +errors or useful tests. If a maintenance change turns out to need a decision +under [section 9](#9-decisions-and-authority), stop it and record the decision +needed. + +## 9. Decisions and authority + +Make ordinary engineering decisions within accepted architecture without asking. +Decisions already accepted in the blueprint and authorization already granted +remain effective; do not request them again. + +Seek a maintainer decision only for a material departure from accepted product +direction, public compatibility promises, trust boundaries, support scope or +destructive data policy, or when required authority is missing. Prepare the +problem, evidence, alternatives and trade-offs first, and continue independent +authorized work meanwhile. Do not disguise a change of direction as cleanup or +an implementation detail. + +Publication, merge, release and deployment follow the authority actually +granted for them. A successful review, green CI or a passing hook grants none of +them by itself. Preserve branch protections, existing branches, other +contributors' work and unrelated working-tree changes. + +## 10. Review + +Review the actual change: a staged and unstaged diff, or an explicit +`git diff ` range. An empty `git diff HEAD` after committing is not +a review of the committed change. Recheck material corrections, rebases and +conflict resolutions before integration, and review the final aggregate change +for cross-step effects before a pull request or release candidate. + +Prefer a reviewer who did not author the change. When none is available, use a +fresh, separate critical pass and state that limitation honestly. Never present +self-review as independent review. + +A **blocking** finding concerns correctness, promised behavior, trust, data +preservation, compatibility, accepted scope or required evidence. Fix it before +dependent work advances. An unrelated improvement goes to separately scoped +maintenance. Preferences are not blockers and findings are not a quota. + +[Reviewer](.agents/agents/reviewer.md) describes the review procedure. + +## 11. Validation + +Run the smallest sufficient set for the change and expand it for a concrete +affected boundary, regression risk or release gate. Do not repeatedly run +unrelated expensive suites once the remaining risk is resolved, and never weaken, +skip or re-bless a required check to make it pass. + +The [verification runner](.agents/scripts/verify.py) runs the repository's +actual check profiles; [verify](.agents/commands/verify.md) maps changes to +profiles and to evidence the runner cannot provide. [CI](.github/workflows/ci.yml) +remains the integration gate. Demo applications are separate workspaces; root +workspace tests do not cover them. Feature-disabled builds cannot stand in for +the `servo-embed` or `wasmtime-runtime` product paths. + +## 12. Dependencies and forks + +Servo is consumed from the `marcoallegretti/servo` fork (`servo-weft` branch). +Stylo currently resolves to upstream `servo/stylo`; the `marcoallegretti/stylo` +fork applies to WEFT only once a root-level override selects it and the resolved +graph confirms it. The selected revisions are those in `Cargo.lock`, not +`SERVO_PIN.md` or a branch name. + +- Apply required Cargo overrides at the consuming workspace root. A dependency's + own `[patch]` table does not apply transitively. Inspect the resolved graph and + verify each claimed fix on the selected code. +- Keep a purpose, upstream status and removal condition for every retained fork + patch. +- Local path overrides used for cross-repository development change the resolved + graph. Do not commit the lockfile changes they cause and do not present + results from them as evidence for the committed graph. +- A dependency update needs scope, compatibility evidence, relevant security + review and the same reviewed loop as product code. +- Never fabricate `pkg-config` metadata, native library versions or readiness + messages to make a build pass. Repair the supported environment or exclude + the unsupported feature explicitly. +- Do not copy machine-specific usernames or checkout paths into documented + workflows. + +## 13. Versions and releases + +Follow the blueprint's [version progression](BLUEPRINT.md#121-version-progression): +scoped `0.0.x` releases toward stable `0.1.0`, each moving through +`alpha.N -> beta.N -> rc.N -> final`, where final is the plain version without +a `-final` suffix. Assign the next `0.0.x` to an accepted +milestone scope after inspecting existing tags and published releases. Reconcile +the unreleased workspace value `0.1.0` deliberately. + +Promotion is an explicit evidence-based decision under release authority. No +label, test count, absence of bug reports or successful build promotes a +candidate automatically. A release candidate requires the complete evidence for +its scope and an independent technical review of that exact candidate; an +unavailable required reviewer leaves the gate pending. Corrections after +candidate approval invalidate the affected evidence. Never rewrite or move +published tags or releases. Publish the artifact that was tested. + +## 14. Branches, commits and publication + +Branch from the verified current `main` unless the work depends on another +unmerged branch; then say so. Name every branch after the concrete change, +with a type prefix: + +```text +fix/authorize-session-messages +refactor/share-servo-frame-loop +feat/keyboard-app-switching +build/enable-servo-vm-packages +test/reject-portal-symlink-escapes +docs/add-weft-contribution-contract +``` + +Reject task numbers, lane, phase or role labels, model or provider names and +generic names such as `maintenance`, `stability` or `cleanup`. Link the issue +from the pull request instead of naming the branch after it. + +Commits are atomic, focused and revertible. Before committing, inspect +`git status` and the complete diff, and confirm no generated, transient or +local-environment files are included. Keep subjects short and technical; add a +body when it explains the problem, resulting behavior or evidence. + +Branch names, commit messages, issues, pull requests, review comments and +release notes are written for maintainers: the concrete problem, the resulting +behavior, the affected boundaries and the validation actually performed. Do not +include model or provider attribution, co-author or generated-by trailers, +reviewer counts or personas, prompts, internal role handoffs or process +narration. A technical validation section with real commands and results is +useful. + +Reusable governance files, the adopted blueprint and protocol or product +documentation are intentional tracked artifacts. Temporary plans, transcripts, +review notes, scratch output and internal progress reports stay out of Git. +A decision that exists only in a conversation does not exist for the project: +record durable decisions in the owning public artifact. + +Before an action that can trigger automated public review or publication, +inspect the repository's integrations. Do not knowingly trigger publication that +conflicts with this section or bypass a required protection to avoid it. + +## 15. Code + +Follow the workspace configuration: edition 2024, the pinned toolchain in +[`rust-toolchain.toml`](rust-toolchain.toml) and `unsafe_code = "forbid"` where +crates inherit workspace lints. Keep `cargo fmt` and `clippy -D warnings` +clean. Do not silence a diagnostic without understanding its cause. + +Product, helper and privileged subprocesses use exact executable paths and +argument arrays. Bound queues, frames, payloads and operation lifetimes. Keep +secrets, application payloads, clipboard contents and saved user data out of +default logs. + +Prefer self-explanatory names and structure. Comment non-obvious invariants, +protocol constraints and safety reasoning; avoid narrative comments. Remove dead +code instead of commenting it out. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..140cbf2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,77 @@ +# Contributing to WEFT OS + +[AGENTS.md](AGENTS.md) is the engineering contract for every contribution. +[BLUEPRINT.md](BLUEPRINT.md) describes the accepted product direction toward +`0.1.0`. This guide points to the workflow; the contract +defines the requirements. + +The [contributor toolkit](.agents/README.md) provides procedures, review roles, +area knowledge and a verification runner. + +## Describe a verifiable change + +Search [existing issues](https://github.com/marcoallegretti/WEFT_OS/issues) and +pull requests first, then open a +[new issue](https://github.com/marcoallegretti/WEFT_OS/issues/new/choose): + +- **Defect or change** for a concrete problem or ordinary work within accepted + architecture. +- **Maintenance** for one present duplication, structural or misleading-fallback + problem outside active development. +- **Decision** for a material change of product direction, public compatibility, + trust boundaries, support scope or data policy. Opening it does not approve the + change. + +Each form asks for observed and expected behavior, evidence, the owning +component, present impact, an acceptance criterion and the proof that would +show the change works. The [maintenance threshold](AGENTS.md#8-maintenance) +separates a present problem from a cleanup preference. + +## Find the owner + +Each component owns specific responsibilities, listed in the blueprint's +[ownership table](BLUEPRINT.md#4-architecture-and-ownership). Public contracts +are the package manifests, the [host WIT](crates/weft-runtime/wit/weft-app.wit), +the [shell protocol](protocol/weft-shell-unstable-v1.xml) and the +[IPC types](crates/weft-ipc-types/src/lib.rs). Selected dependency APIs are +those in [Cargo.lock](Cargo.lock), including the Servo fork and the Stylo revision. + +## Prove and implement the change + +Follow the [reviewed change loop](AGENTS.md#5-reviewed-change-loop): confirm +scope, name the proof, implement, validate, review the actual diff, correct and +commit atomically. Reproduce a defect before fixing it. Compilation, mocks and +capability declarations do not prove rendering, native input, isolation or +persistence; see [proof before implementation](AGENTS.md#6-proof-before-implementation). + +Branch from the current `main` with a descriptive name such as +`fix/authorize-session-messages` or `refactor/share-servo-frame-loop`; the +[branch rules](AGENTS.md#14-branches-commits-and-publication) list what to avoid. + +Install the native dependencies from [docs/building.md](docs/building.md) and +run the relevant [runner](.agents/README.md#verification-runner) profiles, for +example: + +```sh +python .agents/scripts/verify.py portable linux +python .agents/scripts/verify.py servo-embed +pip install -r .agents/scripts/requirements.txt +python .agents/scripts/verify.py toolkit +``` + +[verify](.agents/commands/verify.md) maps each kind of change to its profiles and +to the evidence the runner cannot provide, such as a running compositor, real +pixels, actual components or a booted image. Report checks that could not run +and why. + +## Submit a pull request + +The [pull request template](.github/pull_request_template.md) asks for the +problem and scope, what changed, ownership, what proves it, the validation +actually performed, manual verification and material limitations. Write for a +maintainer who has no access to your working notes: no attribution, generated-by +or co-author trailers, prompts or process narration. + +Contribution work is reviewed from its actual diff, preferably by someone who +did not write it. Maintainers decide merges and release promotion; a green CI +run or a review does not merge or release anything by itself. diff --git a/README.md b/README.md index ae036f9..27c3143 100644 --- a/README.md +++ b/README.md @@ -75,11 +75,12 @@ See `docs/building.md` for full instructions including Wasm component builds, Ni ## CI -Three jobs on every push and pull request: +Four jobs on every push and pull request: - `cross-platform` — fmt, clippy, tests on Ubuntu and Windows - `linux-only` — clippy and tests for compositor and shell crates - `servo-embed-linux` — `cargo check --features servo-embed` for both servo crates +- `contributor-toolkit` — links, metadata and catalog of the contributor toolkit, and runner tests ## Security @@ -98,3 +99,7 @@ See `docs/security.md`. Key points: - Base revision: `04ca254f` - Patches: keyboard input, backdrop-filter in stylo - See `crates/weft-servo-shell/SERVO_PIN.md` for Servo integration status and known limitations + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). [AGENTS.md](AGENTS.md) is the engineering contract and [BLUEPRINT.md](BLUEPRINT.md) the accepted direction toward `0.1.0`. diff --git a/docs/building.md b/docs/building.md index 96f1359..cb1d602 100644 --- a/docs/building.md +++ b/docs/building.md @@ -90,8 +90,9 @@ See `infra/nixos/weft-packages.nix` for the package derivations. The `outputHash ## CI -Three jobs run on every push to `main` and on pull requests: +Four jobs run on every push to `main` and on pull requests: - `cross-platform` — fmt, clippy, tests on Ubuntu and Windows (excludes Wayland crates) - `linux-only` — clippy and tests for `weft-compositor`, `weft-servo-shell`, `weft-app-shell` - `servo-embed-linux` — `cargo check --features servo-embed` for servo-shell and app-shell +- `contributor-toolkit` — `python .agents/scripts/verify.py toolkit`