WEFT_OS/AGENTS.md
Marco Allegretti 39869a2a38
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.
2026-10-08 23:40:08 +00:00

19 KiB

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/ 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
Implemented behavior Source code and the checks that actually executed against it
Public contracts Package manifests (wapp.toml), WIT, the shell protocol, IPC types and the versioned specifications that replace them
Selected dependency APIs 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.

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 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. 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. 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 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/ 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, 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 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 runs the repository's actual check profiles; verify maps changes to profiles and to evidence the runner cannot provide. CI 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: 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:

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