From 01a707f17096a21984742c7356800722cb4d695a Mon Sep 17 00:00:00 2001 From: Thijs Damsma Date: Fri, 23 Oct 2026 13:03:20 +0200 Subject: [PATCH 1/2] docs: propose scoped claims for completion work Co-Authored-By: OpenAI Codex --- AGENTS.md | 50 +++++++++++++++++++++++++++++++++++++++++--------- README.md | 20 ++++++++++++++------ 2 files changed, 55 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2f3a23067..680d1d93b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -141,7 +141,11 @@ Every ported file starts with: Unit list and states: `plan/units/.toml`, one file per unit (format: `plan/modules.schema.md`, order: `plan/order.md`). **`plan/PROGRESS.md` is the checklist** (regenerated on `main` by CI; -never edit it in a PR). **Any `todo` unit can be claimed.** A unit is *ready* when its `depends_on` are all +never edit it in a PR). **Any `todo` unit or unclaimed completion task can be claimed.** A claim reserves +its stated scope, not every future change to the unit. Missing functions, back-edge +wiring, exact runner imports, fixtures and demonstrated parity bugs remain useful +work in `partial` and `green` units; inspect source and reports, not status alone. +A unit is *ready* when its `depends_on` are all `green` or `partial` (`soft_depends_on` never blocks; see section 4a); ready units are the easiest, lowest `layer` first. Claiming a unit that is not ready is fine: - Calls into a missing dependency are stubbed (`UNPORTED()`, cases deferred; 4a). @@ -156,14 +160,42 @@ the easiest, lowest `layer` first. Claiming a unit that is not ready is fine: into `upstream/` (see README), then run `scripts/fetch-cpp.sh`, or `nice -n 10 harness/cpp/build.sh --jobs 6` to build from source. -1. **Claim = a draft PR.** Check nobody has it: - `gh pr list --state open --search " in:title"`. If none, branch from the - latest `main` (`git fetch origin && git switch -c unit/ origin/main`), - `git commit --allow-empty -m "claim: "`, push, and open a draft PR titled - exactly **`port: `**. **The lowest-numbered open PR for a unit wins**; if - yours lost, close it. Do not edit `plan/units/` to claim. Push WIP at least - daily; a draft PR with no pushes for 48 h may be taken over (comment on it first). - If the unit's `notes` mention a WIP branch on `origin`, start from it. +1. **Claim = a scoped draft PR.** Search open PR titles and bodies for the unit, + symbols and affected paths, including `wire:`, `fix:` and `difftest:` work; a title + search for `port:` alone misses completion work. Branch from the latest `main`. + Do not edit `plan/units/` to claim. + Initial whole-unit ports keep the title **`port: `**. For completion work, + use a descriptive title such as **`wire: — `** and name + the unit in the body. An empty claim commit is sufficient to open a draft. + + Include this scope in the PR body (update it as the work changes): + ```text + Units: + In scope: upstream symbols, Rust functions and intended behavior + Expected edits: paths and shared interfaces + Evidence: failing/deferred case IDs or missing branches; validation planned + Related PRs / dependencies: + Available follow-ups: independent work others can take + Status / blockers / next step: + ``` + The earliest open claim wins only for overlapping work. Non-overlapping work in + the same unit is welcome. Link the related PR and state the boundary before + starting; independent work need not wait for a whole-unit owner to reply. + If work changes the same function or shared interface, agree on a split in the + existing PR first, or build on its branch and document the dependency. If the + boundary is unclear, ask there and take a different independent task meanwhile. + Never implement a competing version of an actively claimed change. + + Push WIP or post a concrete progress update at least daily while implementing. + After 48 h without either, comment with the exact scope you propose to take over + and allow 24 h for a response; then continue from published WIP, crediting its + author. Do not take over a PR merely because it awaits review or CI: offer review, + conflict resolution or a coordinated follow-up instead. A blocker update should + identify what is blocked and release independent work, rather than reserve the + whole unit indefinitely. When pausing, release the scope and link the WIP. + Existing PR authors retain their active scope; this is not a reset of claims. + If the unit's notes mention a WIP branch, inspect it before starting. + 2. **Port** the upstream functions the unit owns (listed in `harness/callgraph/units.json`) into its `rust_module`, plus the C++ shim (`harness/cpp/shim/.cpp`, functions `sc__`, plain diff --git a/README.md b/README.md index 2f36611e7..31cdc0848 100644 --- a/README.md +++ b/README.md @@ -107,12 +107,20 @@ so they are cached like the Rust crates. ## Contributing -Contributions are pull requests, one per port unit, and AI agents are welcome: - -1. Pick any unclaimed unit in [`plan/PROGRESS.md`](plan/PROGRESS.md). "Ready" ones are - easiest; the others need stubs or co-porting of missing dependencies. -2. Claim it by opening a draft PR titled `port: ` (lowest-numbered PR wins). -3. Port it, prove it with difftest against the C++ reference, mark the PR ready. +Contributions are pull requests, and AI agents are welcome: + +1. Find an unclaimed unit in [`plan/PROGRESS.md`](plan/PROGRESS.md), or a concrete + completion task in an existing unit: a missing function, back-edge, exact runner + import, coverage gap or parity bug. Green reports alone do not prove every + upstream branch is exercised. +2. Search open PR titles and bodies for the unit, symbols and paths. Claim the + specific work in a draft PR; initial ports use `port: `. A claim covers + its stated scope, so independent tasks in the same unit remain available. + Coordinate overlapping functions or shared interfaces in the existing PR first. +3. Describe the intended behavior, affected paths, related PRs and validation in the + draft, and list independent follow-ups others can take. Prove the change against + the C++ reference before marking it ready. See [AGENTS.md, section 4](AGENTS.md#4-porting-a-unit-pr-workflow) + for the claim template, handoffs and inactivity rules. To keep parallel PRs from conflicting: edit only your unit's `plan/units/.toml`, never commit `reports/difftest/` (CI generates them), and only append to From 2755b050211761afc01d0405f08533a357be6966 Mon Sep 17 00:00:00 2001 From: Thijs Damsma Date: Fri, 23 Oct 2026 13:08:51 +0200 Subject: [PATCH 2/2] docs: clarify precedence for overlapping port claims Co-Authored-By: OpenAI Codex --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 680d1d93b..56288c2d0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -178,7 +178,9 @@ into `upstream/` (see README), then run `scripts/fetch-cpp.sh`, or Available follow-ups: independent work others can take Status / blockers / next step: ``` - The earliest open claim wins only for overlapping work. Non-overlapping work in + For overlapping whole-unit `port:` claims, the lowest-numbered open PR wins. + For completion tasks, the earliest open claim wins only for overlapping work. + Non-overlapping work in the same unit is welcome. Link the related PR and state the boundary before starting; independent work need not wait for a whole-unit owner to reply. If work changes the same function or shared interface, agree on a split in the