From c2c5e3c74890433068aaf8db788cf96713799724 Mon Sep 17 00:00:00 2001 From: Threepwood-7 Date: Wed, 11 Nov 2026 14:35:16 +0100 Subject: [PATCH 1/3] docs(workstreams): describe withdrawn history recovery refs (Build #55) --- docs/reference/GUIDE-PARALLEL-WORKSTREAMS.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/reference/GUIDE-PARALLEL-WORKSTREAMS.md b/docs/reference/GUIDE-PARALLEL-WORKSTREAMS.md index 3900699f..061c91da 100644 --- a/docs/reference/GUIDE-PARALLEL-WORKSTREAMS.md +++ b/docs/reference/GUIDE-PARALLEL-WORKSTREAMS.md @@ -246,7 +246,15 @@ python -m emule_workspace workstream remove sample-fix --owner parent-agent Removal must refuse dirty worktrees, unpublished commits, and unresolved pull requests. The normal removal path requires the branch's changes to be integrated. An explicitly abandoned assignment can use `--abandoned` after its pull requests -are closed and its work is published. Removal retains Git branches; the parent -reviews and removes integrated or superseded local and remote branches separately. +are closed, including work that was never published. This explicit parent path +retains each exact checkout head and its reachable history in the canonical +repository's local `refs/recovery/abandoned//` +reference before any runtime or checkout removal. It verifies the source head +and recovery reference with Git compare-and-swap; a conflicting recovery reference +refuses cleanup. Dirty, untracked or ignored files and open or unknown pull-request +state still refuse removal. Withdrawn code is not pushed by this operation. +Removal retains Git branches; the parent reviews the recovery refs and removes +integrated or superseded local and remote branches separately using exact-head +leases. Ordinary removal and `remove-repo` still refuse unpublished work. The parent resolves each blocker explicitly. Do not switch canonical checkouts to complete a worker's lifecycle or remove another agent's worktree. From ca4ddfb12f22a186cd6b0353c8ca26d74098c39c Mon Sep 17 00:00:00 2001 From: Threepwood-7 Date: Wed, 11 Nov 2026 14:57:32 +0100 Subject: [PATCH 2/3] docs(pm): persist coordination mandate and closure policy (Build #55) --- docs/WORKSPACE-POLICY.md | 3 + docs/reference/PM-COORDINATION-POLICY.md | 112 +++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 116 insertions(+) create mode 100644 docs/reference/PM-COORDINATION-POLICY.md diff --git a/docs/WORKSPACE-POLICY.md b/docs/WORKSPACE-POLICY.md index fa6935c8..f989c331 100644 --- a/docs/WORKSPACE-POLICY.md +++ b/docs/WORKSPACE-POLICY.md @@ -29,6 +29,9 @@ policy rather than choosing one silently. that will be read for current-state decisions or edited. - Read the nearest repo-local `AGENTS.md` after this core. Do not sweep `repos`, `workspaces`, or dormant products after the focus is known. +- A parent acting as PM or engineering coordinator also reads the + [PM Coordination Policy](reference/PM-COORDINATION-POLICY.md) before assigning + work. It owns the coordination mandate, decision boundaries and closure check. - Treat historical notes under `docs\history` as provenance, not current authority. Revalidate backlog and release documents against current `main`, dependency pins, and policy before implementation. diff --git a/docs/reference/PM-COORDINATION-POLICY.md b/docs/reference/PM-COORDINATION-POLICY.md new file mode 100644 index 00000000..db4d46ec --- /dev/null +++ b/docs/reference/PM-COORDINATION-POLICY.md @@ -0,0 +1,112 @@ +# PM Coordination Policy + +Read the [Workspace Policy](../WORKSPACE-POLICY.md) first. This annex applies to +the parent agent coordinating backlog, engineering delivery and worker agents. +Refresh it after a context reset before allocating or reprioritizing work. + +## Mission + +Act as the accountable PM, engineering director and product coordinator. Turn +the operator's goals into prioritized, independently reviewable work; delegate +implementation, resolve dependencies and carry delivery through qualification, +integration and cleanup. Keep one parent coordinator and a clear owner for every +active worker and validation run. + +The [Product Direction](../active/PRODUCT-DIRECTION.md) and +[Rust Release Scope](../products/emulebb-rust/RELEASE-SCOPE.md) own product scope. +The delivery target is a stable, efficient, long-running eD2K/Kad client capable +of sharing 100,000+ files, with coherent configuration, REST and database design. +Treat these as acceptance goals, not claims that every gap is already fixed. +Linux and Windows lead; other platforms advance in parallel under the actual +merge and publication policies. + +## Current Operator Mandate + +1. Finish consolidation of all existing development lanes and Dependabot updates + using the current required gates. Reach clean, qualified canonical mains with + no dangling topic branches, pull requests, worker checkouts or worker agents. + Preserve explicitly withdrawn or superseded work as recovery history. +2. Only after that checkpoint, add a fast Clippy/type-check preflight before the + full platform matrix, reusing existing gate commands. Coordinate compatible + changes into batches for final integration testing as a PM responsibility. + +This is the approved performance follow-up scope. New capacity, machines or +additional orchestration programs need a new operator decision. Batching and +working-hour preferences must not become Python queues, Windows scheduled tasks +or automatic clock-based policies. + +Beta 3 promotion and APK/signing remain on hold. The long soak follows accepted +bug and gap fixes, with current aMule and Rust eD2K-server provenance qualified +under the product and harness policies. Preserve the accepted fresh-profile +policy and old profiles for rollback; do not invent migration work. + +For this consolidation only, the operator approved parent-coordinated rebases of +published worker and Dependabot PR branches. Preserve exact recovery refs, +authorship and exact-head leases; require fresh applicable checks. This does not +authorize rewriting protected main or release tags. Follow the +[Delivery Policy](DELIVERY-POLICY.md) for all other Git rules. + +## Coordination Mode + +- Parallel work is standard for independent outcomes. Assign one worker per + checkout, an owning issue, reserved files, acceptance criteria and a concrete + next deliverable. Use the managed + [workstream lifecycle](GUIDE-PARALLEL-WORKSTREAMS.md). +- The parent owns priorities, dependency and merge order, shared Git operations, + contract/schema/lockfile coordination and final acceptance. Workers own scoped + implementation, granular commits, normal pushes, checks and review repairs. + Routine repairs within an assignment do not wait for repeated parent approval. +- Ask the operator about consequential product scope, unresolved tradeoffs, + spending or irreversible actions. Honor decisions already made; continue + independent authorized work while a needed answer is pending. +- Keep source revisions clean and frozen during selected validation. Coordinate + companion refreshes explicitly; a canonical main update does not update an + existing worker companion. Preserve inherited operator environment state. +- Use GitHub for background platform qualification and hosted provenance. + Schedule useful local proof through the existing owners and shared lock. + Preferred development hours of roughly 06:00 to midnight guide the PM; longer + local tests are permitted whenever needed. Overnight availability is capacity, + not an automatic machine schedule. +- Keep all worker and monitoring tasks under the existing parent. Do not create + another master task. An agent waiting on GitHub still needs an explicit owner + and next action; finish it once its assignment and monitoring handoff are done. + +## Batches And Integration + +Choose batches from dependency, file ownership and risk before expensive final +qualification. Preserve individual authored commits and review evidence. Prefer +a stable combined source tip for additional integration, package and nightly +proof rather than repeating that extra proof after every small source edit. + +Batching does not waive repository-required checks or permit borrowing a pass +from another head. Keep each PR's actual gates and cross-repository prerequisites +explicit. Distinguish scoped local proof, hosted qualification, merge and actual +published-artifact verification. Do not start a new feature wave while the +consolidation checkpoint is incomplete. + +## Status And Closure + +Status updates identify the owner, branch/head or PR, local machine versus +GitHub run, actual running or queued stage, observed results, next dependency and +an evidence-based ETA range. Diagnose cancelled superseded runs, monitoring +timeouts and product failures separately. Use the persisted observer and exact +run selection described in the Delivery Policy. + +Before declaring consolidation complete, the parent verifies: + +- All in-scope changes are integrated and qualified; every PR has a final + disposition and every support dependency uses an accepted source revision. +- Canonical checkouts are clean on current remote main. Integrated or reviewed + superseded topic refs, managed checkouts, registrations and owned runtime + stages are retired; recovery history is deliberately retained. +- Required combined-main and publication evidence is accounted for. Remaining + non-gating or external-setting follow-ups are explicit owning-issue items, + never hidden behind a completion claim. +- Owned test peers, browsers, compilers and monitors have ended, workspace locks + are released, and worker agents have finished. Preserve operator processes, + profiles and unrelated work. + +GitHub Project #3 and owning issues remain backlog/status authority. This page +owns the PM mandate, not a duplicate progress ledger. Update the mandate when the +operator changes it, and refresh actual issue, PR, source and runtime state before +resuming work; historical handoffs do not override current evidence. diff --git a/mkdocs.yml b/mkdocs.yml index a881eaf5..232acd1d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -140,6 +140,7 @@ nav: - Frozen Surfaces: active/FROZEN-SURFACES.md - Developer And Workspace: - Workspace Policy: WORKSPACE-POLICY.md + - PM Coordination Policy: reference/PM-COORDINATION-POLICY.md - Workspace Operations Policy: reference/WORKSPACE-OPERATIONS-POLICY.md - Public Presence Contract: reference/PUBLIC-PRESENCE-CONTRACT.md - Delivery Policy: reference/DELIVERY-POLICY.md From 3163951a9511910123b83e0052be4c3f4d2c5fef Mon Sep 17 00:00:00 2001 From: Threepwood-7 Date: Wed, 11 Nov 2026 15:00:32 +0100 Subject: [PATCH 3/3] docs(pm): link the parent coordination entrypoint (Build #55) --- docs/INDEX.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/INDEX.md b/docs/INDEX.md index 3ad6b940..b510fc65 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -90,6 +90,7 @@ workspace and release controls instead of the product manual: | Role | Start Here | |---|---| | Contributor or AI agent | [Workspace Policy](WORKSPACE-POLICY.md), then only its task-routed annexes; use the [Agent Checklist](reference/AGENT-CHECKLIST.md) when useful | +| Parent PM or engineering coordinator | [PM Coordination Policy](reference/PM-COORDINATION-POLICY.md), after the workspace core | | Routine developer | [Development Guide](reference/DEVELOPMENT-GUIDE.md) | | Backlog owner | [Active Backlog](active/INDEX.md) and [Backlog Process](reference/BACKLOG-PROCESS.md) | | Release operator | [0.7.3 Proof Summary](history/releases/0.7.3/RELEASE-0.7.3-PROOF-SUMMARY.md) |