WEFT_OS/.agents/commands/maintenance.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

2.1 KiB

name description
maintenance 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, continuous-simplicity or continuous-refactoring, and optionally a candidate problem. Read 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 and the maintenance form, 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 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, stop it and record the decision needed.
  7. Stop. One run handles one problem. Do not continue collecting opportunities, and do not merge.