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.
This commit is contained in:
Marco Allegretti 2026-10-08 23:40:08 +00:00
parent f70518b64e
commit 39869a2a38
No known key found for this signature in database
33 changed files with 2201 additions and 2 deletions

141
.agents/README.md Normal file
View file

@ -0,0 +1,141 @@
# WEFT OS contributor toolkit
Procedures, review roles, area knowledge and a verification runner for manual
and assisted contributions. [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.
A prompt that works in any assistant:
```text
Read AGENTS.md and .agents/README.md. Follow .agents/commands/implement.md for
this accepted scope: <issue URL or concrete task and acceptance criterion>.
Load the relevant skills and report the actual evidence and check results.
```
## Commands
Commands are portable Markdown procedures, not registered slash commands.
Supply their input in a prompt or follow them as a checklist.
| 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 tool-independent instructions for a separate session, a subagent or
a human reviewer. 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.
## Using different tools
| Tool | Setup |
|---|---|
| Codex | Reads root `AGENTS.md`. Load skills, commands and roles by path when the client does not discover them. |
| Claude Code | Keep a local, untracked `CLAUDE.md` that points to `AGENTS.md` and this file. Load shared files by path. |
| Cursor, Copilot or another assistant | Add a local instruction that reads `AGENTS.md` and this file, then supply the relevant paths. |
| Manual contribution | Follow the same checklists and run the same commands. |
Discovery of commands, roles and hooks varies by client. The path-based workflow
needs no plugin, provider configuration or subagent feature. Keep client
adapters local and do not fork copies of the contract or skills.
## 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.

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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 <base> <head>` 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.

View file

@ -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 <base> <head>` 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.

View file

@ -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.

View file

@ -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.

43
.agents/commands/scope.md Normal file
View file

@ -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.

View file

@ -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 <profiles>`, 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.

View file

@ -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())

View file

@ -0,0 +1,3 @@
markdown-it-py==4.2.0
mdurl==0.1.2
PyYAML==6.0.3

View file

@ -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```",
"<!-- [X](missing.md) -->", 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()

124
.agents/scripts/verify.py Normal file
View file

@ -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())

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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/<id>/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.

View file

@ -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.

View file

@ -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).

63
.github/ISSUE_TEMPLATE/change.yml vendored Normal file
View file

@ -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.

5
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View file

@ -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.

58
.github/ISSUE_TEMPLATE/decision.yml vendored Normal file
View file

@ -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

58
.github/ISSUE_TEMPLATE/maintenance.yml vendored Normal file
View file

@ -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

29
.github/pull_request_template.md vendored Normal file
View file

@ -0,0 +1,29 @@
## Problem and scope
<!-- The concrete problem and its present impact. Link the issue (Closes #...) or the accepted scope. For a material change of direction, link the decision that approved it. -->
## What changed
<!-- The resulting behavior or structure, for a reader without access to your working notes. State relevant exclusions. -->
## Ownership
<!-- The owning component and the public contracts touched (wapp.toml, WIT, shell protocol, IPC types, package format). Explain how ownership and compatibility are preserved, or how an approved change keeps them coherent. -->
## What proves it
<!-- The test, component fixture, integration fixture, pixel check or measurement that fails without this change and passes with it. Explain any changed expectation, fixture or signature. Compilation and mocks do not prove rendering, native input, isolation or persistence. -->
## Validation performed
<!-- Actual commands and results, e.g. python .agents/scripts/verify.py portable linux. Name the environment for integration evidence (backend, GPU or virtual device, VM). List checks not run and why. -->
## Manual verification
<!-- What automation cannot establish, the environment and scenario used, and the observed result. If none is needed, say why automated evidence covers the scope. -->
## Limitations and related issues
<!-- Limitations that affect evaluation or use. Link separately actionable problems as issues; do not store future work here or leave a supported path knowingly incomplete. -->
<!-- Keep this text about the project problem, change and evidence. No model or provider attribution, co-author or generated-by trailers, reviewer counts or personas, prompts or process narration. -->

View file

@ -111,3 +111,16 @@ jobs:
cargo check cargo check
-p weft-app-shell -p weft-app-shell
--features servo-embed --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

5
.gitignore vendored
View file

@ -1,4 +1,5 @@
/target/ /target/
__pycache__/
/.windsurf/ /.windsurf/
/docu_dev/ /docu_dev/
@ -6,3 +7,7 @@
/infra/vm/*.qcow2 /infra/vm/*.qcow2
Thumbs.db Thumbs.db
# Local assistant configuration; AGENTS.md is the shared contract.
/CLAUDE.md
/.codex/

369
AGENTS.md Normal file
View file

@ -0,0 +1,369 @@
# WEFT OS engineering contract
This is the single engineering contract for everyone who changes WEFT OS:
maintainers, external contributors and coding assistants of any vendor. 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. Client-specific instruction files may
point here; they 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 <base> <head>` 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.

79
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,79 @@
# Contributing to WEFT OS
[AGENTS.md](AGENTS.md) is the engineering contract for every contribution,
manual or assisted. [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. The same files work for manual
development and any coding assistant; its setup table covers client
differences.
## 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.

View file

@ -75,11 +75,12 @@ See `docs/building.md` for full instructions including Wasm component builds, Ni
## CI ## 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 - `cross-platform` — fmt, clippy, tests on Ubuntu and Windows
- `linux-only` — clippy and tests for compositor and shell crates - `linux-only` — clippy and tests for compositor and shell crates
- `servo-embed-linux` — `cargo check --features servo-embed` for both servo 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 ## Security
@ -98,3 +99,7 @@ See `docs/security.md`. Key points:
- Base revision: `04ca254f` - Base revision: `04ca254f`
- Patches: keyboard input, backdrop-filter in stylo - Patches: keyboard input, backdrop-filter in stylo
- See `crates/weft-servo-shell/SERVO_PIN.md` for Servo integration status and known limitations - 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`.

View file

@ -90,8 +90,9 @@ See `infra/nixos/weft-packages.nix` for the package derivations. The `outputHash
## CI ## 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) - `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` - `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 - `servo-embed-linux` — `cargo check --features servo-embed` for servo-shell and app-shell
- `contributor-toolkit` — `python .agents/scripts/verify.py toolkit`