diff --git a/CONTRIBUTOR_TASKS.md b/CONTRIBUTOR_TASKS.md index 12749691d..ad095e939 100644 --- a/CONTRIBUTOR_TASKS.md +++ b/CONTRIBUTOR_TASKS.md @@ -37,26 +37,67 @@ into a mirror of maintainer scratch state. 5. If a task is `Maintainer-owned`, do not duplicate the work. Ask whether there is a public helper slice instead. -## Current Public Tasks - -Start with **Starter** tasks if this is your first contribution. Choose -**Focused** tasks if you are comfortable running local smokes. Pick **Advanced** -tasks only when you are ready to touch shared state, adapters, or concurrency. -Use **Design/RFC** tasks to shape direction before implementation. +## Project Development Direction + +LoopX is becoming a management surface for long-running agent work: the control +plane owns verified state transitions, typed settlement, and public evidence, +while operators and contributors interact through compact read models and +bounded commands. Pick work that advances one of the directions below; avoid +parallel abstractions or a second source of truth. + +1. **From control-plane library to management surface.** Make kernel objects + (work items, owners, decisions, evidence, budgets, risk, next actions) + legible through dashboards, global manager commands, and showcase + walkthroughs. Prefer synthetic, provider-neutral surfaces; public first + viewports stay maintainer-preview work. +2. **Effect Program runtime maturity.** A shared typed Effect Program now + drives quota, Turn, and task-lease settlement; the scheduler remains outside + settlement. The next milestone (RFC M7) is a verified vertical slice: + parity fixtures for partial execution, retry, cancellation, permission + denial, budget rejection, and replay mismatch; a read-only replay lens; and + a second adapter consuming the same plan/receipt algebra. Only then may a + shared executor be extracted, and only if two adapters share execution + ownership. +3. **Verified state transitions.** "done" must mean verified, not claimed: + wire caller-approved `validation_command` into self-reported completion + (#3082), keep typed receipts for writeback and spend, and make replay + safe under lease fencing (#3074). +4. **Operator observability.** Give operators per-goal token/cost/duration and + legible governance (who can act, who must approve, what was spent) from + existing compact projections (#3085); do not create a second ledger. +5. **Contributor and operator experience.** Make first-run onboarding durable + (#3092), complete the canonical read-only global command set, keep CLI + output budget-aware and readable (#2881), and close the release docs + timeline gap. +6. **Maintainability.** Keep hot modules bounded, ratchet debt low, and smokes + deterministic (no wall-clock oracles). Extract cohesive rule groups into + bounded modules; never into generic helper layers. + +## Priority Queue + +| Priority | Slice | Issue / PR | Status | +| --- | --- | --- | --- | +| P0 | Wire caller-approved `validation_command` into self-reported completion | #3082 | Needs design | +| P0 | Turn fencing convergence: M7.1 parity fixtures and replay lens | #3074, RFC M7.1 | Available | +| P1 | Fresh-project `/loopx` onboarding regression fixture | #3092 / #3093 | Available | +| P1 | Per-goal token/cost/duration dashboard projection | #3085 | Needs design | +| P1 | One budget-aware CLI output ergonomics slice | #2881 | Needs design | +| P2 | Release docs timeline v0.2.6 -> v0.4.4 | GH-C04 | Available | +| P2 | CLI ownership and hot-module extraction | GH-C06 | Available | ## Product Manager Cut -LoopX is currently converging from a control-plane library into a management -surface for long-running agent work. Product-capability contributions should -prefer slices that make existing kernel objects understandable to users instead -of adding another source of truth. +LoopX is converging from a control-plane library into a management surface for +long-running agent work. Product-capability contributions should prefer slices +that make existing kernel objects understandable to users instead of adding +another source of truth. | Product slice | Current substrate | Contributor-sized next cut | | --- | --- | --- | | Management frontstage | Goals, todos, gates, claims, evidence, quota, run history, `goal_channel_projection_v0`, `task_graph_projection_v0`, `issue_fix_outcome_projection_v0`, `agent_management_projection_v0`, and same-source Explore views are already compact read models. The public homepage, hosted docs, and localized dashboard now expose these surfaces. | Translate the read models into stable operator concepts such as work item, owner, decision, evidence, budget, risk, and next action; preserve lineage, keep raw machine fields in drill-downs, and do not create a second task or case store. Changes to a public first viewport remain maintainer-preview work. | -| Conversational commands | `global_manager_command_v0` defines read-only commands such as `/loopx-global-summary`, `/loopx-global-gates`, and `/loopx-global-todos` (all implemented), plus `/loopx-global-risks`; legacy `/loop-global-*` forms are only migration aliases. | Implement `/loopx-global-risks` next with a public-safe smoke and no alias sprawl. Unknown commands should fail closed with help. | -| Runtime connector modes | `host_mode_plan_v0` selects visible, isolated-headless, gateway, service, and hybrid modes over the connector catalog. Host-loop activation now covers Codex surfaces, Claude Code, OpenCode, TraeX, Pi, Gemini, Cursor, and custom agents; a scheduler-hint-aware external worker demonstrates one signed headless route. LoopX Turn remains one isolated request/effect/receipt transaction rather than a recurring loop. | Add one provider-neutral parity slice for route preservation, skill delivery/readback, continuation deadlines, signed primary actions, or stage/receipt visibility. Keep host wake/process ownership outside LoopX core and do not create a second scheduler or duplicate controller. | -| Planner-worker mode | The experimental planner-worker contract now supports one bounded plan, one selected worker step, an allowlisted validation set, a clean-worktree boundary, and a typed receipt; the TraeX probe is only one extension provider. | Add provider-neutral usage and failure guidance around the shipped fake runtime. Keep model routing explicit, validation caller-approved, and recurring scheduling or broad multi-agent orchestration outside this mode. | +| Conversational commands | `global_manager_command_v0` defines read-only commands such as `/loopx-global-summary`, `/loopx-global-gates`, and `/loopx-global-todos` (all implemented), plus `/loopx-global-risks`; legacy `/loop-global-*` forms are only migration aliases. | Implement `/loopx-global-risks` next (PR #3075 is approved), one canonical command at a time with a public-safe smoke and no alias sprawl. Unknown commands should fail closed with help. | +| Runtime connector modes | `host_mode_plan_v0` selects visible, isolated-headless, gateway, service, and hybrid modes over the connector catalog. Host-loop activation covers Codex surfaces, Claude Code, OpenCode, TraeX, Pi, Gemini, Cursor, and custom agents; a scheduler-hint-aware external worker demonstrates one signed headless route. LoopX Turn remains one isolated request/effect/receipt transaction rather than a recurring loop. | Add one provider-neutral parity slice for route preservation, skill delivery/readback, continuation deadlines, signed primary actions, or stage/receipt visibility. Keep host wake/process ownership outside LoopX core and do not create a second scheduler or duplicate controller. | +| Planner-worker mode | The experimental planner-worker contract supports one bounded plan, one selected worker step, an allowlisted validation set, a clean-worktree boundary, and a typed receipt; the TraeX probe is only one extension provider. | Add provider-neutral usage and failure guidance around the shipped fake runtime. Keep model routing explicit, validation caller-approved, and recurring scheduling or broad multi-agent orchestration outside this mode. | | Visible governance | Quota, scheduler hints, authoritative interaction contracts, decision scopes, user gates, peer claims, optional task leases, repository policy, interface budgets, and provider-neutral PR program snapshots already exist in machine contracts. A shared-goal authority/state-provider RFC now defines the next coordination boundary without making the proposal runtime authority. | Show who can act, who must approve, which decision scope applies, what budget was spent, and how pause/override/terminate decisions map back to LoopX state. Keep proposal state, claims, leases, and PR program observations from becoming a new runtime hierarchy or write authority. | | Decision and material quality | Decision Context and Material Lifecycle are experimental, built-in, default-off capabilities. They separate revision-bound evidence, advisory proposals, material planning, owner-gated apply, and private cursor/source state. | Build synthetic, no-provider walkthroughs that make these boundaries visible. Do not add private adapters, source bodies, provider payloads, or a second lifecycle store. | | Memory and content workflows | Agent Turn Recall composes quota-selected work with scoped Reward Memory, while `content_ops_item_v0` preserves stable item identity, revision-bound approval, delivery/readback receipts, and supersession. Both remain advisory or preview-level and add no provider authority. | Add synthetic walkthroughs and negative fixtures that prove identity, revision, and failure boundaries. Keep provider payloads, draft bodies, credentials, raw sessions, and external writes outside LoopX state. | @@ -69,23 +110,22 @@ points: | Area | Landed | Contributor implication | | --- | --- | --- | -| Decision, content, issue-fix, and PR productization | The revision-bound content-item lifecycle is shipped. Current `main` also guards discovered issue promotion, pins approved issue-fix base snapshots before branch creation, and adds provider-neutral PR program snapshot/diff tracking. | Add one synthetic lifecycle walkthrough or missing negative fixture. Keep activation explicit and leave source bodies, draft bodies, review text, provider payloads, private locators, cursor state, and apply/publish authority outside public fixtures. | -| Public surfaces and showcases | The public homepage, hosted documentation site, Dev Book with control-plane course chapters, Chinese operator dashboard, and stable README entry points are shipped. The Auto Research course, catalog, and long-horizon public evidence remain the reusable showcase path. | Improve deterministic evidence, accessible navigation, Dev Book locale parity, or readability using existing surfaces and synthetic data. Do not alter the README or public homepage first screen without maintainer preview, or couple a renderer to one delivery provider. | -| Host loops and orchestration | A bounded external scheduler worker, TraeX Turn adapter, Pi Goal host, Gemini/Cursor/OpenCode host surfaces, adaptive child-admission, and Auto Research stop/state-aware wake transitions have landed. They preserve signed actions, explicit identity/capabilities, repository conflict checks, and one bounded child/Turn receipt. | Add cross-host fake-fixture parity for skill delivery, action provenance, timeout/termination, or replan handoff, or a docs walkthrough for the shipped stop/takeover path. Do not infer child capability, treat a resumable session as authority, or embed a resident scheduler in LoopX. | -| Shared coordination and review | Peer claims remain routing signals. Provider-neutral PR program tracking and a shared-goal authority/state-provider RFC now make coordination state more reviewable, while PR review guidance requires causal and execution chains. | Add synthetic conformance and negative cases around observation, authority, and lineage. The RFC is not a grant to write remote state, and PR review snapshots must not retain private review bodies or provider payloads. | -| Status, quota, and monitors | Paused goals are authoritative terminal decisions, file-lock acquisition is bounded, registry CLI ownership budgets are restored, monitor no-change replan streaks default to 5, completed-chain evidence windows are preserved, causal vision wait lineage is required, and monitor/selected-todo projections preserve capability provenance. Dedicated hot-path budget and todo-detail cold-path smokes remain the reference. | Extend one measured performance, detail-readback, lock-timeout, or malformed-state case. Keep default output bounded, cold-path detail available, and unavailable capabilities visible without adding another projection source. | -| Turn and effect settlement | A shared typed Effect Program now drives quota, Turn, and task-lease settlement. Cross-adapter conformance, legal-prefix fault/replay, mutation guards, and public-safe incident replays cover effect identity, writeback-before-spend, failure short-circuiting, and at-most-once settlement; legacy plans without typed settlement fail closed with an actionable upgrade path. Task lease keeps eligibility, conflict, locking, CAS, and persistence in its owning bounded context. The scheduler remains outside settlement. | Evaluate another existing core side-effect path only when it has a real caller, stable identity, ordered durable receipts, replay requirements, and duplicate settlement truth that the change can remove. Preserve the owning interpreter; do not force pure decision logic into Kleisli form or extract a shared executor without shared execution ownership. | -| Benchmark boundary | Shared lifecycle, readiness, ledger, and reducer contracts are the public seam; Terminal-Bench, ALE, and EdgeBench now sit on the same seams as SkillsBench. Generic Effect Program conformance and replay tests harden settlement infrastructure but do not change benchmark scoring or authorize live runs. Live scored comparisons are currently held until a fresh task-free runner lifecycle receipt proves readiness; the pure Turn Loop Controller is still coordination-required. | Extend synthetic setup/termination attribution, or add a SWE adapter only when a second SWE route needs shared launch/observe/ingest behavior. Do not launch scoring, duplicate the controller, or expose raw task text, logs, trajectories, verifier tails, credentials, uploads, or local paths. | -| Validation and change quality | Python tests are green on the latest runtime-bearing `main` change; public smoke parity and the frontstage Pages build are restored, and a public good-smoke guide now defines the semantic-oracle, durability, and public-safety checklist. The earlier KNN timing oracle still needs deterministic coverage. | Replace timing as a semantic oracle, retain negative/mutation coverage, and distinguish infrastructure outages from product regressions. Keep live model/provider checks explicit and low-frequency. | +| Turn and settlement | Typed quota/Turn settlement is shipped for CLI and Codex App routes; task-lease CLI acquire routes through typed settlement (#3091), verified leases release when completion commits (#3040), cross-turn completion replay is fenced (#3049), and fine-grained turn mode landed (#3087). Fencing remote execution and terminal writeback (#3074) is under changes-requested review. | Add one replay-reuse or typed receipt readback negative fixture without a second settlement ledger, a model call, or double quota spend. | +| Effect program runtime | A shared typed Effect Program now drives quota, Turn, and task-lease settlement. The RFC roadmap and M7 status were refreshed (#3063), and the Dev Book course now teaches the current Effect Program runtime (#3097). The turn driver is the second real consumer of the typed settlement algebra. The scheduler remains outside settlement. | Provide M7.1 parity fixtures and a read-only replay lens. do not force pure decision logic into Kleisli form or extract a shared executor without shared execution ownership; do not build a shared interpreter/executor protocol before both adapters consume the same plan/receipt algebra. | +| Review quality | PR review now requires scope-fit evidence for production surface changes (#3090), and the review contract test carries scope-fit evidence (#3096). | Add synthetic conformance and negative cases around scope-fit evidence, causal chains, and exact-head review packets. | +| Task leases | Typed task-lease CLI with preserved legacy error codes landed (#3095); on-disk hard leases surface in goal-channel projection (#3039); Turn fencing uses lease fences plus an append-only journal. | Extend lease adoption to one more host integration or add a transfer/overlap-write-scope fixture. Keep soft-claim routing and undeclared-lease authority unchanged. | +| Status, quota, monitors | Monitor and repeated-stall replans are hardened (#3089); compact scheduler-hint and heartbeat-prompt budgets were raised above the shipped `fallback_hint` size (#3062, #3068); hot-path budget and todo-detail cold-path smokes remain the reference. | Extend one measured performance, detail-readback, lock-timeout, or malformed-state case. Keep default output bounded and cold-path detail available. | +| Governance and productization | A synthetic visible-governance slice landed (#3086); decision-context evidence cursors settle (#3079); material and PR-program walkthroughs are approved (#3070, #3071); the homepage React rebuild (#3098) is under review. | Add one synthetic lifecycle walkthrough or missing negative fixture. Keep activation explicit and leave source bodies, draft bodies, review text, provider payloads, private locators, cursor state, and apply/publish authority outside public fixtures. | +| Benchmark boundary | Shared lifecycle, readiness, ledger, and reducer contracts are the public seam; Terminal-Bench, ALE, and EdgeBench now sit on the same seams as SkillsBench. Generic Effect Program conformance and replay tests harden settlement infrastructure but do not change benchmark scoring or authorize live runs. Live scored comparisons stay held until a fresh task-free runner lifecycle receipt proves readiness. | Extend synthetic setup/termination attribution, or add a SWE adapter only when a second SWE route needs shared launch/observe/ingest behavior. Do not launch scoring, duplicate the controller, or expose raw task text, logs, trajectories, verifier tails, credentials, uploads, or local paths. | +| Validation and change quality | Python tests are green on the latest runtime-bearing `main` change; public smoke parity and the frontstage Pages build are restored. The KNN timing oracle still needs deterministic coverage. | Replace timing as a semantic oracle, retain negative/mutation coverage, and distinguish infrastructure outages from product regressions. Keep live model/provider checks explicit and low-frequency. | | Release and install | v0.4.4 is the latest public tag and package version. `main` now contains post-v0.4.4 product and public-surface changes, while `docs/product/release-readiness.md` still stops at v0.2.6. | Close the v0.2.7-v0.4.4 timeline gap from tagged release evidence, preserve tagged stable versus post-tag `main`, and improve contributor-safe update recovery without adding a parallel release checklist. | -| Public docs and onboarding | Hosted docs, a public homepage, the Dev Book, localized dashboard copy, public/private boundary examples, GitHub issue forms, and a PR/issue label taxonomy have landed. Slash-command installation now exposes the canonical global manager command set with summary and gates implemented. | Keep contributor, release, protocol, course, and showcase surfaces concise and linked to public evidence; add navigation/locale checks and implement one missing read-only manager command at a time instead of appending status narratives or aliases. | ## Turn Loop Controller Plan `loopx turn run-once` remains the atomic governed executor: decide, execute one bounded host segment, validate independently, write back, spend once, and project the latest scheduler contract. Host-loop activation, the external -scheduler worker, and visible Pi/TraeX integrations now provide concrete outer +scheduler worker, and visible Pi/TraeX integrations provide concrete outer loops, but they do not make LoopX a resident scheduler. The maintainer-owned pure controller and replan transition are still in hardening, so contributors should focus on independently derived decision tables, cross-host parity, @@ -111,7 +151,8 @@ points for contributors who are still learning the repository. | ID | Area | Task | Validation | | --- | --- | --- | --- | -| GH-C02 | tests | Add or extend a focused smoke test around todo archive/completion behavior. Prefer copying the style of `examples/control_plane/todo-lifecycle-cli-smoke.py`. | `python3 examples/control_plane/todo-lifecycle-cli-smoke.py` and `python3 -m py_compile loopx/*.py` | +| GH-C02 | tests | Add or extend a focused smoke test around todo archive/completion behavior. Prefer copying the style of `examples/control_plane/todo-lifecycle-cli-smoke.py`. Currently claimed in issue #3056; coordinate before duplicating. | `python3 examples/control_plane/todo-lifecycle-cli-smoke.py` and `python3 -m py_compile loopx/*.py` | +| GH-C87 | onboarding | Add a durable regression fixture for the fresh-project `/loopx` guided-todo-template and `agent-onboard` failure (#3092): fresh project, no existing goal, guided todo add, agent registration readback, and a clean second run after the approved fix (#3093) merges. | Focused pytest or CLI smoke plus `loopx check --scan-path examples/control_plane --scan-path CONTRIBUTOR_TASKS.md` | | GH-C04 | docs | Refresh install, activation, and recovery guidance through v0.4.4: add concise v0.2.7-v0.4.4 timeline summaries from tagged release evidence, preserve tagged stable vs post-tag `main` and release-snapshot vs canary distinctions, cover installed-runtime activation recovery, and link rather than duplicate the release body's bilingual optional-capability usage guidance. | `python3 examples/fresh-clone-quickstart-smoke.py`, `python3 examples/loopx-update-smoke.py`, `python3 examples/release/release-readiness-doc-smoke.py`, `python3 examples/release/release-version-contract-smoke.py`, and `loopx check --scan-path docs/product/release-readiness.md --scan-path CONTRIBUTING.md` | | GH-C80 | docs | Add a hosted-docs navigation and locale-parity check across `mkdocs.yaml`, `docs/index.md`, `docs/book/index.md`, the docs catalog, and stable README entry links. Catch broken or orphaned public pages without changing the README or homepage first viewport. | `python3 examples/docs-governance-smoke.py`, `python3 examples/frontstage-pages-workflow-smoke.py`, a strict MkDocs build, and `loopx check --scan-path docs --scan-path mkdocs.yaml --scan-path README.md --scan-path README.zh-CN.md` | | GH-C64 | release docs | Add a contributor-safe atomic-promotion failure matrix around the shipped release lock/concurrency smoke: explain which failures happen before the symlink swap, how a waiter recovers, and when contributors must stop before maintainer-only promotion state. Extend the existing fixture only for a durable missing case. | `python3 examples/release/release-promotion-concurrency-smoke.py`, `python3 examples/release/local-install-promotion-boundary-smoke.py`, and `loopx check --scan-path docs/product/release-readiness.md --scan-path CONTRIBUTOR_TASKS.md` | @@ -125,14 +166,17 @@ for contributors who can run local CLI smokes and keep changes scoped. | ID | Area | Task | Validation | | --- | --- | --- | --- | | GH-C06 | cli | Characterize one remaining oversized CLI ownership seam after the recent quota, status, todo, history, and scheduler command-plumbing extractions, then move only a cohesive command or rule group into its bounded module. Preserve public invocations, avoid compatibility wrappers without a real caller, and keep the module-size/import budget honest. | Command-specific smoke, `python3 examples/cli-command-module-size-ownership-command-modularization-smoke.py`, `python3 regression/cli-command-module-contract.py`, and focused pytest if rules move | +| GH-C83 | turn / effect program | Add M7.1 parity fixtures for the fenced Turn settlement vertical slice: partial execution, retry, cancellation, permission denial, budget rejection, and owner/key-mismatched replay. Derive expectations from the typed settlement contract (RFC M7.1), not from implementation output. | `python3 -m pytest -q tests/test_loopx_turn_driver.py tests/test_loopx_turn_executor.py tests/test_loopx_turn_journal.py tests/test_loopx_turn_transaction.py` and `loopx check --scan-path docs/architecture/rfcs/agent-loop-effect-interpreter-v0.md --scan-path CONTRIBUTOR_TASKS.md` | +| GH-C84 | turn / effect program | Add a read-only `interpret_turn_journal` lens over the fenced journal trace: replay legality, owner/key matching, tombstone retention, and phase-order invariants. Mirror `interpret_quota_should_run_packet`; do not introduce an executor or write path. | Focused pytest, `python3 examples/loopx-turn-fake-host-walkthrough-smoke.py`, and `loopx check --scan-path docs/reference/effect-interpreter-packet.md --scan-path CONTRIBUTOR_TASKS.md` | +| GH-C85 | validation | Wire caller-approved `validation_command` into the self-reported completion path (#3082): optional public-safe field on the completion request, reuse the existing independent task-validation phase, require a validation receipt before durable writeback, block and surface typed failure, keep the no-command fast path unchanged. | Focused pytest with a negative case, `python3 examples/loopx-turn-fake-host-walkthrough-smoke.py`, and `loopx check --scan-path loopx/capabilities/issue_fix --scan-path CONTRIBUTOR_TASKS.md` | +| GH-C86 | dashboard | Surface per-goal token/cost/duration in the existing dashboard from compact quota/run-history projections (#3085). Keep raw machine fields in drill-downs, add an explicit projection source, and do not create a second ledger. | Frontstage route/browser smokes plus `loopx check --scan-path apps/presentation/dashboard --scan-path CONTRIBUTOR_TASKS.md` | +| GH-C88 | cli | Implement one budget-aware CLI output ergonomics slice for #2881: shorter default summaries with a typed `--json` escape hatch on one command family, keeping hot-path payload budgets and differential allowances intact. | `python3 examples/control_plane/cli-output-budget-regression-smoke.py`, focused command smoke, and `loopx check --scan-path docs/status-data-contract.md --scan-path CONTRIBUTOR_TASKS.md` | | GH-C43 | showcase | Add a contributor-facing walkthrough for the shipped Auto Research stop/takeover and state-aware wake transitions. Reuse the current command path and synthetic/redacted evidence; do not add a second launcher or alter the README first screen without maintainer preview. | `python3 examples/showcase-catalog-smoke.py`, `python3 examples/auto-research-demo-e2e-worker-loop-smoke.py`, `python3 examples/auto-research-visible-worker-hook-smoke.py`, `python3 examples/auto-research-stop-marker-smoke.py`, `python3 examples/auto-research-state-aware-wake-smoke.py`, `python3 examples/auto-research-quota-pause-smoke.py`, and `loopx check --scan-path docs/showcases --scan-path docs/guides` | | GH-C49 | dashboard | Polish the shipped `/frontstage` goal-channel board: improve visual acceptance, local demo fixture clarity, and operator onboarding while keeping browser data read-only and making outcome, lease, capability-wait, and workspace-repair states legible. | `npm run smoke:frontstage-route`, `npm run smoke:frontstage-browser`, and `loopx check --scan-path apps/presentation/dashboard --scan-path docs/product/roadmaps/dashboard-frontend-selection.md` | -| GH-C50 | control plane | Implement the first generic `observable_artifact_handle_v0` slice from `docs/product/domain-capability-packs.md`: compact handle, allowed poll command, artifact refs, terminal markers, and read-boundary flags for long-running work without assuming a benchmark, CI, deployment, or ML experiment adapter. | Focused fixture smoke plus `loopx check --scan-path docs/product/domain-capability-packs.md --scan-path CONTRIBUTOR_TASKS.md` | | GH-C74 | productization | Add one public synthetic walkthrough from a revision-bound Decision Context packet to a Material Lifecycle rerank preview. Prove stale/conflicting evidence stays visible, source bodies and private locators stay absent, and apply/cursor commits remain separate owner-gated actions. | `python3 examples/decision-context-contract-smoke.py`, `python3 examples/material-lifecycle-contract-smoke.py`, focused capability pytest, and `loopx check --scan-path docs/capabilities/decision-context --scan-path docs/capabilities/material-lifecycle --scan-path CONTRIBUTOR_TASKS.md` | | GH-C60 | workflow | Add one focused fake-fixture parity slice across Codex App heartbeat, Codex CLI TUI, LoopX Turn, Claude Code, OpenCode, TraeX, Pi, Gemini, Cursor, Ark Managed Agent, the external shell worker, HTTP webhook, and worker bridge. Cover one missing explicit capability route, signed primary action, scoped identity, skill delivery/readback, typed Goal continuation, runtime-owned cadence, no-spend transition, workspace repair, or private-boundary case. | `python3 examples/host-mode-plan-smoke.py`, `python3 examples/project/host-mode-plan-cli-smoke.py`, `python3 examples/control_plane/agent-onboard-host-loop-activation-smoke.py`, focused host bridge tests, `python3 -m pytest -q tests/test_loopx_turn_transaction.py tests/test_external_scheduler_worker.py tests/test_pi_goal_mode.py tests/test_gemini_cursor_host_surfaces.py`, and `loopx check --scan-path docs/integrations/runtime-connector-catalog.md --scan-path docs/reference/protocols/host-mode-plan-v0.md --scan-path CONTRIBUTOR_TASKS.md` | | GH-C59 | status | Extend the shipped hot-path performance and todo-detail cold-path contracts with one large ignored-state-tree, bounded drill-down, or malformed-state case so `status` / `quota` stay fast without dropping public-safe backlog detail. | `python3 examples/control_plane/status-quota-perf-budget-smoke.py`, `python3 examples/control_plane/todo-detail-cold-path-contract-smoke.py`, focused fixture coverage, and `loopx check --scan-path docs/status-data-contract.md --scan-path CONTRIBUTOR_TASKS.md` | -| GH-C61 | cli | Implement the remaining canonical `/loopx-global-risks` command, keep it read-only, source it from compact status/quota/todo/run-history projections, and make unknown aliases fail closed with help instead of broad dumps. `/loopx-global-summary`, `/loopx-global-gates`, and `/loopx-global-todos` are already shipped. | Focused command smoke plus `python3 examples/project/global-manager-command-protocol-smoke.py`, `python3 examples/project/global-manager-command-cli-smoke.py`, and `loopx check --scan-path docs/reference/protocols/global-manager-command-v0.md --scan-path CONTRIBUTOR_TASKS.md` | -| GH-C62 | governance | Add a synthetic visible-governance slice that relates per-goal/per-agent claims, optional task leases, quota, scheduler hints, decision scopes, and the shared-goal RFC's proposed authority/state-provider boundary. Make proposal versus shipped truth explicit; do not add a browser write API, infer scopes from prose, or present provider observations or leases as runtime authority. | Focused fixture smoke, `python3 -m pytest -q tests/control_plane/test_todo_decision_scope_lifecycle.py`, and `loopx check --scan-path docs/status-data-contract.md --scan-path docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md --scan-path CONTRIBUTOR_TASKS.md` | +| GH-C61 | cli | Implement `/loopx-global-risks` as the next canonical global manager command after summary, gates, and todos (all implemented). Keep it read-only, source it from compact status/quota/todo/run-history projections, and make unknown aliases fail closed with help instead of broad dumps. | Focused command smoke plus `python3 examples/project/global-manager-command-protocol-smoke.py`, `python3 examples/project/global-manager-command-cli-smoke.py`, and `loopx check --scan-path docs/reference/protocols/global-manager-command-v0.md --scan-path CONTRIBUTOR_TASKS.md` | | GH-C68 | validation | Move the stable pure rules from one oversized control-plane smoke, preferably `quota-scheduler-state-ack-smoke.py`, into independently derived pytest decision tables while retaining a thin CLI/public-behavior seam. Add at least one negative or mutation case so current implementation output cannot become the oracle. | Focused pytest, the retained smoke, `python3 examples/full-public-smokes-workflow-smoke.py`, and `git diff --check` | | GH-C69 | explore | Add a public-safe local fixture and contributor walkthrough for canonical, executive, and semantic owner-board Explore views. Prove decision/evidence lineage and readability without enabling an external sink or depending on local/private graph sources. | `python3 examples/explore-result-layer-smoke.py`, `python3 -m pytest -q tests/test_explore_presentation_views.py`, and `loopx check --scan-path docs/capabilities/explore --scan-path CONTRIBUTOR_TASKS.md` | | GH-C70 | runtime | Add a provider-neutral host-loop parity walkthrough that runs the same synthetic task through the external scheduler worker plus one visible host such as Pi or TraeX. Compare signed action selection, compact Turn receipts, independent validation, recoverable timeout/termination, replan, and terminal no-followup behavior without retaining raw sessions or host-local paths. | Focused fake-host smoke, `python3 -m pytest -q tests/test_loopx_turn_driver.py tests/test_external_scheduler_worker.py tests/test_pi_goal_mode.py`, and `loopx check --scan-path docs/reference/protocols/loopx-turn-v0.md --scan-path docs/integrations/runtime-connector-catalog.md --scan-path CONTRIBUTOR_TASKS.md` | @@ -142,6 +186,7 @@ for contributors who can run local CLI smokes and keep changes scoped. | GH-C78 | productization | Add a public synthetic walkthrough for `content_ops_item_v0`: stable item identity, revision-bound approval invalidation, delivery/readback receipts, and supersession. Keep provider calls, draft bodies, credentials, private locators, and publish authority outside the fixture. | `python3 -m pytest -q tests/test_content_ops_item_lifecycle.py` and `loopx check --scan-path docs/capabilities/content-ops --scan-path docs/reference/protocols/content-ops-item-lifecycle-v0.md --scan-path CONTRIBUTOR_TASKS.md` | | GH-C79 | validation / onboarding | Make agent onboarding skill-delivery expectations follow the canonical release and active project-skill manifests. Cover the shipped PR program skill, missing/stale skill readback, and custom-host delivery; install dedupe and cwd isolation now ship, so canonical manifests remain the source of truth rather than ambient global installations. | `python3 examples/control_plane/agent-onboard-host-loop-activation-smoke.py`, `python3 examples/control_plane/peer-agent-runtime-v1-smoke.py`, `python3 -m pytest -q tests/test_slash_command_install.py`, focused project-skill delivery pytest, and `loopx check --scan-path loopx/agent_onboarding.py --scan-path examples/control_plane/agent-onboard-host-loop-activation-smoke.py --scan-path CONTRIBUTOR_TASKS.md` | | GH-C81 | workflow | Add a public synthetic walkthrough for provider-neutral PR program tracking: stable program identity, observed head snapshots, compact diff classification, review/CI transition lineage, and fail-closed unknown state. Keep provider payloads, review bodies, credentials, local paths, and merge authority outside the snapshot. | `python3 -m pytest -q tests/test_pr_program_snapshot_diff.py`, a focused skill script fixture, and `loopx check --scan-path skills/loopx-pr-program --scan-path CONTRIBUTOR_TASKS.md` | +| GH-C50 | control plane | `observable_artifact_handle_v0` first slice is implemented in approved PR #3080. When it merges, add the next consumer slice: a provider-neutral poll walkthrough that reads one compact handle, runs its allowed poll command, and stops at a terminal marker without assuming a benchmark, CI, deployment, or ML adapter. | Focused fixture smoke plus `loopx check --scan-path docs/product/domain-capability-packs.md --scan-path CONTRIBUTOR_TASKS.md` | ### Advanced Implementation @@ -153,7 +198,7 @@ and keep the first PR as a narrow slice. | GH-C07 | state | Add structured-state write serialization for todo/refresh/history writers using a per-goal lock or optimistic revision guard. Include a concurrent todo add/update regression. | New concurrency regression plus `python3 -m py_compile loopx/*.py` | | GH-C15 | benchmark | Implement benchmark ledger drift warning: when compact run history has a benchmark result but `benchmark-run-ledger.json/md` lacks the row, status should warn or closeout should auto-upsert. Keep raw task/log/trajectory material out. | `python3 examples/benchmark-run-ledger-smoke.py` | | GH-C16 | benchmark | Add a public-safe trajectory-summary contract for non-SkillsBench adapters so Terminal-Bench/SWE/ALE/EdgeBench can expose comparable counters without raw task text, logs, verifier output, or trajectory bodies. | New unit/fake fixture smoke | -| GH-C47 | state | Adopt the shipped optional `task_lease_v0` in one real host integration: advertise the capability explicitly, preserve soft-claim routing, expose acquire/renew/transfer/release outcomes, and prove overlapping write scopes fail without making `quota should-run` enforce undeclared lease authority. | `python3 examples/control_plane/task-lease-runtime-smoke.py`, `python3 -m pytest -q tests/control_plane/test_task_lease.py`, and a host-focused fake fixture | +| GH-C47 | state | Task leases now back Turn fencing and typed CLI acquire/release. Adopt the shipped `task_lease_v0` in one more real host integration (for example Pi or TraeX): advertise the capability explicitly, preserve soft-claim routing, expose acquire/renew/transfer/release outcomes, and prove overlapping write scopes fail without making `quota should-run` enforce undeclared lease authority. | `python3 examples/control_plane/task-lease-runtime-smoke.py`, `python3 -m pytest -q tests/control_plane/test_task_lease.py tests/test_loopx_turn_driver.py`, and a host-focused fake fixture | ### Design / RFC @@ -162,6 +207,7 @@ before implementation. | ID | Area | Task | Validation | | --- | --- | --- | --- | +| GH-C89 | governance | Respond to the AGE-style attractor proposal (#2831): anchor goal direction to repository owner docs so the control plane can validate semantic drift, not just execution state. Define the read boundary, the drift signal, and what must remain advisory; do not make repository docs a write authority. | Public design note with a synthetic drift fixture plan plus `loopx check --scan-path docs/architecture/rfcs --scan-path CONTRIBUTOR_TASKS.md` | | GH-C35 | integration | Design the next provider-neutral external-host adapter on top of LoopX Turn and TurnEnvelope, using the shipped external worker, Pi, and TraeX routes as conformance examples rather than special cases. Map compact session events into requests, planned effects, committed receipts, independent validation, recovery, and attention items while keeping raw transcripts, credentials, billing, permissions, and product frontstage outside LoopX. | Public design note with adapter-neutral fake-host smoke plan plus `loopx check --scan-path docs/integrations/runtime-connector-catalog.md --scan-path CONTRIBUTOR_TASKS.md` | | GH-C37 | interaction model | Curate the interaction pattern catalog with one new public-safe good/bad case, including trigger signals, user channel, agent channel, state contract, bad smell, and validation reference. Do not copy raw chat, private benchmark artifacts, or internal links. | `loopx check --scan-path docs/concepts/interaction-pattern-catalog.md` |