Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Autonomous work contract

This document exists so agents and maintainers can make progress without re-asking project-direction questions.

Decision policy

Until alpha, continue without asking unless a change would alter architecture. Architecture changes include:

  • a new JS runtime target or abstraction,
  • a rendered frontend other than ADR-022's Flutter formatter/shell/automation host,
  • a second render/paint path,
  • a bridge that moves navigation, DOM/runtime, policy, persistence, web-event semantics, or accessibility meaning out of BrowserCore,
  • a layout architecture outside ADR-022's mutation/commit ownership,
  • a core dependency that changes binary-size or subsystem ownership materially,
  • a security-policy change that makes behavior less fail-closed.

For ordinary implementation details, choose the safest path aligned with PROJECT_DIRECTION.md, document assumptions briefly, and keep moving.

Commit and push policy

  • Automatic commits are allowed when the batch is coherent and gates pass.
  • Automatic pushes are allowed when hk pre-push gates pass.
  • Prefer milestone commits over tiny churn commits.
  • Do not bypass hk. If hk fails, fix the issue or report the blocker.

Gate policy

Linux agents and maintainers run on a host with the native packages documented in docs/guidance/mise.md; a Distrobox is not required. Before reporting a local Linux gate, record PRETTY_NAME from /etc/os-release and ensure Mise was activated in the shell that ran it. Debian, Fedora, and Ubuntu 26.04 are optional compatibility runs; release-builder recipes retain their separately pinned environment.

  • Inner loop: focused cargo check/cargo test/just gate-phaseN as needed.
  • Before commit: hk pre-commit hook; it should stay quick and fix formatting.
  • Before push: hk pre-push hook; long gates run here because iteration speed matters.
  • Release: ACCEPTANCE.md gates plus measured size/compatibility reports.

The checked-in Linux Flutter slice uses an exact ignored SDK checkout and just gate-flutter-shell; bootstrap it with just setup-flutter. Do not report Rust/GTK checks as Flutter proof, or Dart/widget checks as Linux package proof. Platform work follows ROADMAP.md and FLUTTER_SHELL.md: ADR-022 R1–R8 are complete. Post-R7 compatibility/release/frame/GPU checkpoints and the real Linux Mozc corridor are recorded. The official stable SDK migration preserves the process-filtered AT-SPI name gate and native-pointer focus on GTK3; broader role/state/bounds/action claims require fresh migrated evidence. Keep the executable gates intact while shared-core reductions proceed one proven host family at a time before broader shell/platform expansion. A2 static same-origin/file module dependency graphs now use the shared resource loader; continue that family with CORS enforced before V8 exposure and eligible HTTP(S) cache entries conditionally revalidated under current policy. One bounded pre-module inline import map now resolves through the same policy-bound loader. Page-module dynamic imports retain bounded graph provenance and cancellation across later roots/tasks. Parser classics and BrowserCore automation now also register exact source/document policy before dynamic import, including accepted redirect URLs and retained import maps. A shared bounded private-cache decision now gives page fetch/XHR and module loads Date/Age plus max-age/Expires freshness, effective request directives, simultaneous exact Vary variants, and bounded permanent same-origin redirect aliases. The transport now performs bounded incremental body reads and publishes progress/completion through ReadableStream, XHR, BrowserCore/C ABI, and CDP. Page fetch/XHR now use a bounded asynchronous realm owner; active AbortSignal, XHR abort, stop/deadline, and realm teardown drop transport without late profile effects. Ordinary policy-accepted response heads now resolve before body completion and feed an eight-message backpressured stream; abort after resolution rejects body reads with the same JS reason, while integrity, 304 revalidation, and opaque responses remain buffered. Exact static/dynamic JSON import attributes now use that source, policy, profile, limit, and cancellation provenance plus strict JSON response typing; unsupported keys and types are rejected before transport. External classic/module root SRI now verifies raw bytes before V8, cookies, or cache insertion. Bounded import-map integrity now applies exact normalized-URL metadata to root fallback and graph dependencies at the same boundary. Up to 64 inline maps now merge first-wins under a 512 KiB normalized-state cap and a 2,048-entry/1 MiB successful-resolution set; static parser-position snapshots remain stable while later dynamic imports see the latest map. Continue A2 by carrying authored script/module referrer policy and fetch priority through roots, redirects, dependencies, and diagnostics.

The project owns hook definitions in hk.pkl. just owns command recipes; hk owns when those recipes run in the git lifecycle.

Reporting format

Final handoff should be terse and evidence-first:

  • objective completed,
  • changed files,
  • checks run and pass/fail status,
  • commit hash and push status when applicable,
  • remaining known gaps or next slice.

For large compatibility work, update COMPAT.md from actual fixture/WPT output rather than prose guesses.

Documentation rule

Prefer ADR-style docs that explain why and point to code for how. Avoid parallel prose that must be maintained beside source unless it records product direction, architecture constraints, compatibility results, or gate policy.