diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 4278dd438..4df184e93 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,6 +1,8 @@ # Repository governance files remain owned by the lead maintainer. /.github/CODEOWNERS @huangruiteng /.github/GOVERNANCE.md @huangruiteng +/CONTRIBUTOR_TASKS.md @huangruiteng +/docs/project/technical-directions*.md @huangruiteng # Lark integration review routing. /loopx/extensions/lark/** @huangruiteng @steven-kid diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.md index e646e02ca..7382fb3d3 100644 --- a/.github/GOVERNANCE.md +++ b/.github/GOVERNANCE.md @@ -150,6 +150,35 @@ releases, and boundary decisions. - When consensus is not reached, the lead maintainer records the decision and rationale in the relevant issue or pull request. +## Technical Direction Governance + +The versioned +[Current Technical Directions](../docs/project/technical-directions.md) page is +the canonical map of active strategic programs, maturity, contribution routes, +and promotion gates. The pinned +[GitHub Discussion](https://github.com/huangruiteng/loopx/discussions/2851) is +its community-facing projection; an issue, Discussion, RFC, or integration +branch does not override merged runtime and stable reference contracts. + +Each strategic direction has one long-lived tracking issue. Trackers record +outcomes, boundaries, implementation leads, material decisions, and links to +bounded work. They are not themselves blanket implementation authorization. +A claimable change should have a separate issue or public task-board row with +an explicit smallest slice, base branch, non-goals, and validation plan. + +A material change to a direction's stage, scope, implementation lead, +integration branch, or promotion gate requires a pull request updating the +canonical map. The RFC index and contributor task board should change in the +same pull request when their routing changes. Maintainers update the pinned +Discussion after merge and should not maintain an independent roadmap body +there. + +The `direction/*` labels route discovery and review. They do not grant +authority, promise delivery, or imply that a Draft or Research item is ready +for implementation. Recognition as an implementation lead records current +public work; it is separate from repository write access, subsystem maintainer +appointment, and repository-wide maintainer authority. + ## Becoming A Maintainer Maintainers are selected from contributors who have shown sustained technical diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 4fa1778b4..d148aabda 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -12,3 +12,6 @@ contact_links: - name: Contributor task board url: https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md about: Start here for public, claimable work. + - name: Current technical directions + url: https://github.com/huangruiteng/loopx/blob/main/docs/project/technical-directions.md + about: Understand active programs, maturity, ownership boundaries, and promotion gates. diff --git a/.github/ISSUE_TEMPLATE/contributor-task.yml b/.github/ISSUE_TEMPLATE/contributor-task.yml index 6abc3da24..bebe5d957 100644 --- a/.github/ISSUE_TEMPLATE/contributor-task.yml +++ b/.github/ISSUE_TEMPLATE/contributor-task.yml @@ -13,6 +13,20 @@ body: label: Task ID or area description: Use the board ID if one exists, such as GH-C01, or a short area name. placeholder: "GH-C01 or area: docs" + - type: dropdown + id: direction + attributes: + label: Technical direction + description: Choose the closest current program. This routes discussion; it does not make a draft implementation-ready. + options: + - Core control-plane hardening + - Long-horizon benchmark evidence + - Operator surface and IM integration + - Shared Goal Authority and cross-host coordination + - Architecture and research incubator + - Unsure; maintainer triage needed + validations: + required: true - type: dropdown id: intent attributes: @@ -44,6 +58,14 @@ body: - ... validations: required: true + - type: input + id: target_base + attributes: + label: Intended base branch + description: Usually main. Name an integration branch when the direction tracker requires one. + placeholder: "main or frontend-control-plane-im-prototype-rfc" + validations: + required: true - type: textarea id: files attributes: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5dbc2a79c..7ffae7437 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -35,6 +35,19 @@ - [ ] Build, packaging, installer, or CI - [ ] Host or runtime integration +## Technical Direction + + + +- [ ] Core control-plane hardening +- [ ] Long-horizon benchmark evidence +- [ ] Operator surface and IM integration +- [ ] Shared Goal Authority and cross-host coordination +- [ ] Architecture and research incubator + +- Target base branch: +- Direction tracker or promotion unit: + ## Boundary Checklist - [ ] I did not commit `.loopx/`, `.codex/goals/`, live `ACTIVE_GOAL_STATE.md`, credentials, private benchmark traces, verifier output, raw agent sessions, internal document links, or local machine paths. diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md index dfb6ee6a4..435c3398c 100644 --- a/.github/SUPPORT.md +++ b/.github/SUPPORT.md @@ -17,7 +17,10 @@ channels. Public contributor work belongs on the [Contributor Task Board](../CONTRIBUTOR_TASKS.md) or in the contributor-task -issue form. Pull requests should follow +issue form. The +[Technical Directions map](../docs/project/technical-directions.md) explains +which programs are active and what maturity or promotion gate applies. Pull +requests should follow [`CONTRIBUTING.md`](../CONTRIBUTING.md). ## Official Publication Sources @@ -26,7 +29,9 @@ issue form. Pull requests should follow authoritative source for published versions and release notes. - [GitHub Discussions: Announcements](https://github.com/huangruiteng/loopx/discussions/categories/announcements) is the authoritative source for project announcements that are not tied to - one release. + one release. The pinned + [Current technical directions and known limitations](https://github.com/huangruiteng/loopx/discussions/2851) + post is the community-facing projection of the versioned repository map. - [GitHub Security Advisories](https://github.com/huangruiteng/loopx/security/advisories) is the authoritative source for coordinated vulnerability disclosures. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 146fefc5f..e32a6d5d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,8 +5,10 @@ contributions are small, reviewable, and tied to a public task or clear bug. ## Find Work -Start with [CONTRIBUTOR_TASKS.md](CONTRIBUTOR_TASKS.md). It lists public work -that is useful, claimable, and safe to discuss in the repository. +Start with the [current technical directions](docs/project/technical-directions.md) +to understand the active programs and their maturity, then use +[CONTRIBUTOR_TASKS.md](CONTRIBUTOR_TASKS.md) to find public work that is useful, +claimable, and safe to discuss in the repository. If you do not see a matching task: diff --git a/CONTRIBUTOR_TASKS.md b/CONTRIBUTOR_TASKS.md index 55b5a712e..42f08cab9 100644 --- a/CONTRIBUTOR_TASKS.md +++ b/CONTRIBUTOR_TASKS.md @@ -37,54 +37,37 @@ 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. -## 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, task-lease, and todo-completion settlement, and the - turn driver is the second consumer of the settlement algebra. M7 parity - fixtures, a read-only journal lens, and a shared typed settlement - receipt-chain driver are shipped. The next milestone is negative coverage - on the shared driver (receipt-chain drift, replay identity) 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. +## Current Technical Directions -## Priority Queue +The canonical [Technical Directions map](docs/project/technical-directions.md) +explains outcomes, maturity, ownership boundaries, and promotion gates. This +board lists bounded work; it does not redefine those directions. -| Priority | Slice | Issue / PR | Status | +| Direction | Current stage | Contributor entry | Boundary | | --- | --- | --- | --- | -| P0 | Wire caller-approved `validation_command` into the remaining self-report entry points | #3082 | Available | -| P0 | Typed settlement receipt-chain negatives on the shared driver; Turn fencing review still open | #3074, #3199 | Available | -| P1 | Security-boundary mutation coverage beyond the shipped negative fixtures | #3137-#3140 | Available | -| P1 | Codex CLI timeout recovery cannot resume the session observed by the failed Turn | #3228 | 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.7 | GH-C04 | Available | -| P2 | CLI ownership and hot-module extraction | GH-C06 | Available | +| Long-Horizon Benchmarks and Evidence | Active research | [#3243](https://github.com/huangruiteng/loopx/issues/3243) | Work on public-safe fixtures, treatment integrity, reducers, and docs; live cases and scoring remain maintainer-owned. | +| Operator Surface and IM Integration | Incubating on `frontend-control-plane-im-prototype-rfc` | [#3244](https://github.com/huangruiteng/loopx/issues/3244) | State the target base branch; UI remains a projection and promotion to `main` is staged. | +| Shared Goal Authority and Cross-host Coordination | Draft contract / provider qualification | [#3245](https://github.com/huangruiteng/loopx/issues/3245) | Start provider-neutral and file-backed; NoKV is an unpromoted candidate, not authority. | +| Architecture and Research Incubator | Mixed by RFC | [#3246](https://github.com/huangruiteng/loopx/issues/3246) | Read the per-exploration stage; an RFC alone does not make implementation claimable. | + +Core control-plane reliability remains the shared shipped foundation. Effect +Program hardening, verified transitions, recovery, observability, +maintainability, and contributor experience continue through the focused rows +below and the existing `control-plane` label. + +## Priority Queue + +| Priority | Direction | Slice | Issue / PR | Status | +| --- | --- | --- | --- | --- | +| P0 | Core hardening | Wire caller-approved `validation_command` into the remaining self-report entry points | #3082 | Available | +| P0 | Core hardening | Complete exact-head review of remote execution and terminal writeback fencing | #3074 | Claimed | +| P1 | Core hardening | Recover the session observed by a failed Codex CLI Turn without weakening drift checks | #3228 | Available | +| P1 | Benchmark evidence | Split one deterministic adapter-fidelity or treatment-integrity fixture | #3243 | Needs design | +| P1 | Operator surface / IM | Split one projection or session-contract characterization unit from the incubation branch | #3244 | Needs design | +| P1 | Shared coordination | Define the first provider-neutral, file-backed `claim_work` parity slice | #3245 | Needs design | +| P1 | Core hardening | One budget-aware CLI output ergonomics slice | #2881 | Needs design | +| P2 | Project docs | Release docs timeline v0.2.6 -> v0.4.7 | GH-C04 | Available | +| P2 | Maintainability | CLI ownership and hot-module extraction | GH-C06 | Available | ## Product Manager Cut diff --git a/README.md b/README.md index 37ca47ef3..179934a3b 100644 --- a/README.md +++ b/README.md @@ -482,6 +482,36 @@ loopx check \ --scan-path examples/ ``` +## Current Technical Directions + +LoopX has three active strategic programs plus an architecture and research +incubator. These are direction signals, not delivery promises; `main`, released +artifacts, and stable reference contracts remain the source of shipped truth. + +- **Long-Horizon Benchmarks and Evidence:** reproducible capability evidence + and controlled mechanism research across complementary benchmark + environments. [Direction tracker](https://github.com/huangruiteng/loopx/issues/3243) +- **Operator Surface and IM Integration:** an operator workspace, session + records, and bounded collaboration surfaces, currently incubating on a + dedicated integration branch with `@maxliux5` as implementation lead. + [Direction tracker](https://github.com/huangruiteng/loopx/issues/3244) +- **Shared Goal Authority and Cross-host Coordination:** provider-neutral + coordination for explicitly shared goals, with NoKV as an unpromoted + provider candidate rather than a new control-plane authority. + [Direction tracker](https://github.com/huangruiteng/loopx/issues/3245) +- **Architecture and Research Incubator:** Effect Program hardening, + TypeScript parity migration, hierarchical stride, research exploration, + human attention, artifact lifecycle, and memory utility work at explicitly + different maturity levels. + [Direction tracker](https://github.com/huangruiteng/loopx/issues/3246) + +Read the canonical +[Technical Directions map](docs/project/technical-directions.md) for stages, +promotion gates, contributor-safe cuts, and ownership boundaries. Use the +pinned [GitHub Discussion](https://github.com/huangruiteng/loopx/discussions/2851) +for community discussion. Core control-plane reliability continues as the +shared foundation beneath these programs. + ## Advanced Documentation Start with the path that matches your current task. Use the hosted @@ -551,6 +581,7 @@ deeper documents and versioned protocols. ### Project and Community +- [Current Technical Directions](docs/project/technical-directions.md) - [Project Governance](.github/GOVERNANCE.md) - [Contributing](CONTRIBUTING.md) and [Contributor Tasks](CONTRIBUTOR_TASKS.md) - [Authors and Contributors](AUTHORS.md) @@ -627,10 +658,10 @@ or experimental. LoopX does not grant credentials, approve destructive or production actions, publish on a user's behalf without authorization, or turn an unverified run into evidence of success. -The next milestones are simpler installation and host packaging, broader typed -runtime adapters, stronger terminal acceptance across repeated public loops, -independent adoption and outcome evidence, and a more polished management -surface. +Current investment is organized through the +[Technical Directions map](docs/project/technical-directions.md): long-horizon +benchmark evidence, operator surface and IM integration, shared-goal cross-host +coordination, and an explicitly staged architecture and research incubator. ## Star History diff --git a/README.zh-CN.md b/README.zh-CN.md index 10f9334e5..0a041061b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -433,6 +433,33 @@ loopx check \ --scan-path examples/ ``` +## 当前技术方向 + +LoopX 当前有三个活跃战略计划和一个架构与研究孵化器。这些内容用于表达方向, +不是交付承诺;`main`、已发布 artifact 和 stable reference contract 仍然定义真实 +已交付行为。 + +- **长程 Benchmark 与证据:**在互补 benchmark 环境中建立可复现的能力证据, + 并开展受控的机制研究。 + [方向 Tracker](https://github.com/huangruiteng/loopx/issues/3243) +- **Operator Surface 与 IM Integration:**建设 operator workspace、session + record 与有界协作表面;当前在专用 integration branch 孵化,由 `@maxliux5` + 作为 implementation lead。 + [方向 Tracker](https://github.com/huangruiteng/loopx/issues/3244) +- **Shared Goal Authority 与跨 Host 协作:**为显式共享 goal 提供 + provider-neutral 协调;NoKV 是尚未晋级的 provider candidate,而不是新的控制面 + 权威。 + [方向 Tracker](https://github.com/huangruiteng/loopx/issues/3245) +- **架构与研究孵化器:**以明确不同的成熟度推进 Effect Program hardening、 + TypeScript parity migration、hierarchical stride、research exploration、human + attention、artifact lifecycle 与 memory utility。 + [方向 Tracker](https://github.com/huangruiteng/loopx/issues/3246) + +完整阶段、promotion gate、贡献者安全切片和 ownership 边界见 +[当前技术方向地图](docs/project/technical-directions.zh-CN.md);社区讨论使用置顶的 +[GitHub Discussion](https://github.com/huangruiteng/loopx/discussions/2851)。核心控制面 +可靠性继续作为这些计划共同的底座。 + ## 进阶文档 按当前任务选择入口;[线上文档](https://huangruiteng.github.io/loopx/docs/) @@ -494,6 +521,7 @@ loopx check \ ### 项目与社区 +- [当前技术方向](docs/project/technical-directions.zh-CN.md) - [Project Governance](.github/GOVERNANCE.md) - [Contributing](CONTRIBUTING.md)与[Contributor Tasks](CONTRIBUTOR_TASKS.md) - [Authors and Contributors](AUTHORS.md) @@ -563,8 +591,9 @@ integration 和进阶路径仍是 optional、default-off 或 experimental。Loop 获得 credential,不会替用户批准 destructive / production action,不会在未授权时 公开发布,也不会把未经验证的 run 当成成功证据。 -下一阶段会继续改善安装与 host packaging、扩展 typed runtime adapter、加强重复公开 -Loop 的 terminal acceptance、补足独立采用与 outcome evidence,并打磨管理面。 +当前投入按[技术方向地图](docs/project/technical-directions.zh-CN.md)组织:长程 +benchmark 证据、operator surface 与 IM integration、shared-goal 跨 host 协作,以及 +明确分阶段的架构与研究孵化器。 ## Star 趋势 diff --git a/docs/README.md b/docs/README.md index 776ac9dcd..ba92797dd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,6 +15,7 @@ material available without putting all of it on one page. | Run or recover a long-lived goal | [Operations](operations/README.md) | [Integration guide](integration.md) | | Understand the control plane | [Architecture](architecture.md) | [Concepts](concepts/README.md) | | Connect an agent runtime or provider | [Integrations](integrations/README.md) | [Extensions and capabilities](reference/extensions.md) | +| See what contributors are building now | [Current technical directions](project/technical-directions.md) | [Contributor tasks](../CONTRIBUTOR_TASKS.md) | | Build or review LoopX | [Developer guide](development/README.md) | [Testing and quality](development/testing-and-quality.md) | | Inspect real outcomes | [Showcases](showcases/README.md) | [Research and evidence](research/README.md) | @@ -66,6 +67,7 @@ a longer onboarding path. ## Project And Community +- [Current technical directions](project/technical-directions.md) - [Contributing](../CONTRIBUTING.md) - [Contributor tasks](../CONTRIBUTOR_TASKS.md) - [Governance](../.github/GOVERNANCE.md) diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index b41ce6cc9..cb9d9c077 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -5,27 +5,70 @@ status, decision boundary, non-goals, smallest useful implementation slice, and validation criteria. An RFC may describe future work; current behavior is defined by the implementation and stable reference contracts. -## Active Drafts - -- [Long-Horizon Harness Benchmark and Research Program v0](long-horizon-harness-benchmark-research-program-v0.md): use ALE, LHTB, and DeepSWE as a complementary external-validity portfolio, separate capability evidence from mechanism research, and require benchmark-native outcomes, matched experiments, typed treatment integrity, and public-safe collaboration. -- [长程 Harness Benchmark 与研究计划 v0](long-horizon-harness-benchmark-research-program-v0.zh-CN.md):以 ALE、LHTB 与 DeepSWE 组成互补的外部效度组合,严格区分能力论证与机制研究,并要求 benchmark 原生结果、匹配实验、类型化 treatment 完整性和 public-safe 协作边界。 -- [Hierarchical Agent Stride Control v0](hierarchical-agent-stride-control-v0.md): treat effect feedback, bounded delivery, and authority intervention as three nested control intervals, then qualify their efficiency and failure modes before introducing adaptive stride selection. -- [长程 Agent 分层步幅控制 v0](hierarchical-agent-stride-control-v0.zh-CN.md):把 effect 反馈、有界交付与 authority 干预视为三种嵌套控制区间,在引入 adaptive stride selection 前,先验证各层效率与失败模式。 -- [Human Attention Wishlist v0](human-attention-wishlist-v0.md): let agents capture bounded, evidence-backed requests for optional human leverage as a non-blocking post-delivery sidecar, without changing user-gate authority, selected work, quota, or notification behavior. -- [Human Attention Wishlist v0(中文版)](human-attention-wishlist-v0.zh-CN.md):让 agent 把有证据、可增加价值但不阻塞当前交付的人类协作机会,作为有界的交付后 sidecar 写入;不改变 user gate 权限、选中工作、quota 或通知行为。 -- [Research Exploration Control Plane v0](research-exploration-control-plane-v0.md): evolve a typed research frontier across coverage, closure, and explicit composition experiments while keeping Explore, goal-frontier, and execution authority separate. -- [研究型探索控制面 v0](research-exploration-control-plane-v0.zh-CN.md):围绕 coverage、closure 与显式组合实验演进类型化研究前沿,同时保持 Explore、goal-frontier 与执行权限彼此分离。 -- [Agent Loop Effect Interpreter v0](agent-loop-effect-interpreter-v0.md): model LoopX as the effect interpreter around an agent loop, with canonical effect-request/interpretation/observation packet semantics. -- [Agent Loop Effect Interpreter v0(中文版)](agent-loop-effect-interpreter-v0.zh-CN.md): 把 LoopX 建模为 agent loop 外围的 effect interpreter,并给出 canonical effect-request/interpretation/observation packet 语义。 -- [Agent IM, LoopX, and OpenViking collaboration v0](agent-im-openviking-collaboration-v0.md): separate runtime delivery, durable control state, and scoped context while preserving direct agent-to-LoopX interaction. -- [Goal Channel collaboration v0](goal-channel-collaboration-v0.md): bind one external collaboration channel to one LoopX goal while preserving LoopX as the source of truth. -- [Goal Channel 协作模型 v0](goal-channel-collaboration-v0.zh-CN.md): 将一个外部协作通道绑定到一个 LoopX goal,同时保持 LoopX 作为事实源。 -- [Shared-goal online authority and pluggable coordination provider v0](shared-goal-authority-state-provider-v0.md): a claim-only contract proof for target-scoped conflicts over one canonical coordination aggregate, atomic original-receipt replay, and per-layer persistence ownership, with NoKV as an unpromoted provider candidate ([中文版](shared-goal-authority-state-provider-v0.zh-CN.md), [validation boundary](shared-goal-authority-state-provider-v0-evidence.zh-CN.md)). -- [Goal artifact lifecycle projection v0](goal-artifact-lifecycle-projection-v0.md): derived from artifact-centric business process management (ABPM / GSM milestone-guard semantics); treat a goal as a business artifact with derived milestones, blocking guards, and legal next transitions, projected read-only for operators and global views ([中文版](goal-artifact-lifecycle-projection-v0.zh-CN.md)). -- [Post-Outcome Memory Utility Attribution v0](post-outcome-memory-utility-attribution-v0.md): attribute bounded, evidence-tiered utility to recalled memory after verified outcomes, without turning retrieval, model judgment, or a global evaluator into authority. -- [结果后记忆效用归因 v0](post-outcome-memory-utility-attribution-v0.zh-CN.md):在可验证结果之后,对召回记忆做有界、分证据等级的效用归因,同时避免让召回、模型判断或全局评估器变成新的权限来源。 -- [TypeScript Control-Plane Migration v0](typescript-control-plane-migration-v0.md): contract-first, parity-gated, block-by-block migration from Python to TypeScript over the event store, parity-fixture layer, and CLI boundary; Python remains canonical during the transition. -- [TypeScript 控制面迁移 v0](typescript-control-plane-migration-v0.zh-CN.md):契约优先、parity 门禁、逐块迁移;基于事件存储、parity fixture 层与 CLI 边界从 Python 渐进迁移到 TypeScript,过渡期内 Python 保持权威实现。 +The [Current Technical Directions](../../project/technical-directions.md) page +maps these RFCs to strategic programs, contribution routes, and promotion +gates. The groups below reflect the status written in each RFC; they do not +promote a proposal beyond that status. + +## Accepted Architecture + +- [Agent Loop Effect Interpreter v0](agent-loop-effect-interpreter-v0.md) + ([中文版](agent-loop-effect-interpreter-v0.zh-CN.md)): model LoopX as the + effect interpreter around an agent loop, with canonical + effect-request/interpretation/observation packets and a shared typed Effect + Program for qualified settlement paths. Replan planning and ACK remain + domain-local until a second real plan/receipt lifecycle justifies extraction. + +## Active Research Programs + +- [Long-Horizon Harness Benchmark and Research Program v0](long-horizon-harness-benchmark-research-program-v0.md) + ([中文版](long-horizon-harness-benchmark-research-program-v0.zh-CN.md)): + use ALE, LHTB, and DeepSWE as a complementary external-validity portfolio; + separate capability evidence from mechanism research and preserve + benchmark-native outcomes. +- [Hierarchical Agent Stride Control v0](hierarchical-agent-stride-control-v0.md) + ([中文版](hierarchical-agent-stride-control-v0.zh-CN.md)): qualify effect + feedback, bounded delivery, and authority intervention as nested control + intervals before introducing adaptive stride selection. + +## Drafts Under Review + +- [Research Exploration Control Plane v0](research-exploration-control-plane-v0.md) + ([中文版](research-exploration-control-plane-v0.zh-CN.md)): evolve a typed + research frontier across coverage, closure, and explicit composition while + keeping Explore, goal-frontier, and execution authority separate. +- [Human Attention Wishlist v0](human-attention-wishlist-v0.md) + ([中文版](human-attention-wishlist-v0.zh-CN.md)): capture bounded, + evidence-backed requests for optional human leverage as a non-blocking + post-delivery sidecar without changing gates, selected work, quota, or + notification authority. +- [Shared-goal online authority and pluggable coordination provider v0](shared-goal-authority-state-provider-v0.md) + ([中文版](shared-goal-authority-state-provider-v0.zh-CN.md), + [validation boundary](shared-goal-authority-state-provider-v0-evidence.zh-CN.md)): + prove a claim-only provider-neutral contract for target-scoped conflict and + original-receipt replay, with NoKV as an unpromoted provider candidate. +- [Goal artifact lifecycle projection v0](goal-artifact-lifecycle-projection-v0.md) + ([中文版](goal-artifact-lifecycle-projection-v0.zh-CN.md)): derive + milestones, blocking guards, and legal next transitions as a read-only + operator projection. +- [Post-Outcome Memory Utility Attribution v0](post-outcome-memory-utility-attribution-v0.md) + ([中文版](post-outcome-memory-utility-attribution-v0.zh-CN.md)): attribute + bounded, evidence-tiered utility to recalled memory after verified outcomes + without making retrieval, model judgment, or a global evaluator authoritative. +- [TypeScript Control-Plane Migration v0](typescript-control-plane-migration-v0.md) + ([中文版](typescript-control-plane-migration-v0.zh-CN.md)): use a + contract-first, parity-gated, block-by-block process; Python remains + canonical during the transition. + +## Draft Integration Proposals + +- [Agent IM, LoopX, and OpenViking collaboration v0](agent-im-openviking-collaboration-v0.md): + separate runtime delivery, durable control state, and scoped context while + preserving direct agent-to-LoopX interaction. +- [Goal Channel collaboration v0](goal-channel-collaboration-v0.md) + ([中文版](goal-channel-collaboration-v0.zh-CN.md)): bind one external + collaboration channel to one LoopX goal while preserving LoopX as the source + of truth. RFCs must not contain internal conversations, private links, local filesystem paths, credentials, raw transcripts, or non-public organizational context. diff --git a/docs/development/README.md b/docs/development/README.md index 45e1e89c1..25de962bb 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -11,45 +11,50 @@ not need these documents to start LoopX. 1. Read [Contributing](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md) for repository boundaries and the pull-request checklist. -2. Follow the [Developer Book](/loopx/docs/book/) for the curated external +2. Read [Current technical directions](../project/technical-directions.md) to + choose an active program, understand its maturity, and find its tracker. +3. Follow the [Developer Book](/loopx/docs/book/) for the curated external learning path from control-plane foundations to project onboarding and developer contributions. -3. Follow the [control-plane developer course](control-plane-course/README.md) +4. Follow the [control-plane developer course](control-plane-course/README.md) for an eleven-lecture, code-led path through the real CLI, state machine, and layered quality gates. -4. Read [Testing and quality](testing-and-quality.md) before changing agent-facing +5. Read [Testing and quality](testing-and-quality.md) before changing agent-facing output, scheduler decisions, todo/gate semantics, onboarding, or release promotion. -5. Use [What counts as a good smoke](good-smokes.md) before adding, retaining, +6. Use [What counts as a good smoke](good-smokes.md) before adding, retaining, or consolidating a public smoke. -6. Use [Architecture](../architecture.md) and the +7. Use [Architecture](../architecture.md) and the [core control-plane graphs](../product/core-control-plane/README.md) to find the bounded context that owns the behavior. -7. Check [Public/private boundaries](../public-private-boundary.md) before adding +8. Check [Public/private boundaries](../public-private-boundary.md) before adding fixtures, examples, evidence, or provider-backed evaluation. -8. Follow the [documentation layout policy](documentation-layout.md) before +9. Follow the [documentation layout policy](documentation-layout.md) before adding or moving public documentation. 1. 先阅读[贡献指南](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTING.md),了解仓库边界和 PR 检查项。 -2. 按顺序阅读[开发者手册](/loopx/docs/book/),从控制面基础到项目接入和开发者贡献。 -3. 按顺序学习[控制面开发者 11 讲](control-plane-course/README.md),沿真实 CLI、 +2. 阅读[当前技术方向](../project/technical-directions.zh-CN.md),选择活跃计划、了解 + 成熟度并找到对应 tracker。 +3. 按顺序阅读[开发者手册](/loopx/docs/book/),从控制面基础到项目接入和开发者贡献。 +4. 按顺序学习[控制面开发者 11 讲](control-plane-course/README.md),沿真实 CLI、 状态机、核心函数和分层质量门禁建立代码心智模型。 -4. 修改 agent-facing 输出、调度决策、todo/gate 语义、新用户接入或发布流程前, +5. 修改 agent-facing 输出、调度决策、todo/gate 语义、新用户接入或发布流程前, 阅读[测试与质量体系](testing-and-quality.md)。 -5. 新增、保留或合并公开 smoke 前,阅读 +6. 新增、保留或合并公开 smoke 前,阅读 [什么是好的 Smoke](good-smokes.md)。 -6. 通过[架构文档](../architecture.md)和 +7. 通过[架构文档](../architecture.md)和 [控制面核心图](../product/core-control-plane/README.md)定位真正拥有该行为的 bounded context。 -7. 添加 fixture、示例、证据或模型测试前,检查 +8. 添加 fixture、示例、证据或模型测试前,检查 [公开/私有边界](../public-private-boundary.md)。 -8. 新增或移动公开文档前,遵循 +9. 新增或移动公开文档前,遵循 [文档布局规则](documentation-layout.md)。 ## Core References / 核心参考 | Area / 领域 | Reference / 文档 | | --- | --- | +| Current strategic programs / 当前战略方向 | [Technical directions](../project/technical-directions.md) · [中文](../project/technical-directions.zh-CN.md) | | Curated learning path / 开发者学习路径 | [Developer Book](/loopx/docs/book/) | | Control-plane code reading / 控制面代码领读 | [Eleven-lecture developer course](control-plane-course/README.md) | | Quality layers and commands / 质量分层与命令 | [Testing and quality](testing-and-quality.md) | diff --git a/docs/project/technical-directions.md b/docs/project/technical-directions.md new file mode 100644 index 000000000..6fed18aa3 --- /dev/null +++ b/docs/project/technical-directions.md @@ -0,0 +1,153 @@ +# Current Technical Directions + +This page is the maintainer-curated map of LoopX's current strategic programs. +It helps contributors understand where the project is investing, how mature +each direction is, and where a useful contribution can begin. It is not a +delivery promise, a release plan, or a replacement for shipped contracts. + +> Language note: the +> [Chinese version](technical-directions.zh-CN.md) and this English version are +> semantic mirrors. A material difference between them is a defect. + +## How To Read This Map + +- Code on `main`, released artifacts, and stable reference contracts define + shipped behavior. +- An RFC records a proposal or accepted architectural decision at the status + stated in that RFC. It does not make unimplemented behavior real. +- An integration branch is an implementation candidate. It is not a second + product baseline and does not change `main` contracts until promoted. +- A direction tracker records outcomes, boundaries, and material decisions. + A separate bounded issue or task-board row is required before work is + claimable. +- The pinned + [Current technical directions and known limitations](https://github.com/huangruiteng/loopx/discussions/2851) + Discussion is the community-facing projection of this page. + +Use these maturity terms consistently: + +| Stage | Meaning | +| --- | --- | +| Shipped / hardening | The behavior or architectural contract is in `main`; work improves reliability, parity, or usability. | +| Incubating / qualification | A real candidate exists, but compatibility, evidence, or promotion gates remain. | +| Active research | The program is running evidence-producing experiments; results do not automatically become defaults or product claims. | +| Draft | Design review is welcome; implementation starts only from an agreed smallest useful slice. | +| Held | The direction remains visible, but implementation should not begin until the stated gate changes. | + +## Stable Foundation: Control-Plane Reliability + +Goals, typed todos, quota, scheduler hints, evidence, Effect Program +settlement, recovery, and host parity remain the shared substrate under every +strategic program. Their reliability work continues through the +[Contributor Task Board](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) +and the `control-plane` +label. It is ongoing product hardening, not a competing source of direction. + +## Strategic Programs + +| Direction | Outcome | Stage | Start here | +| --- | --- | --- | --- | +| Long-Horizon Benchmarks and Evidence | Produce benchmark-native, reproducible evidence for long-horizon capability and use controlled tasks to study mechanisms. | Active research | [Tracker #3243](https://github.com/huangruiteng/loopx/issues/3243) · [RFC](../architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.md) | +| Operator Surface and IM Integration | Make goals, sessions, decisions, evidence, and bounded collaboration legible through a coherent operator workspace. | Incubating on an integration branch | [Tracker #3244](https://github.com/huangruiteng/loopx/issues/3244) · [integration branch](https://github.com/huangruiteng/loopx/tree/frontend-control-plane-im-prototype-rfc) | +| Shared Goal Authority and Cross-host Coordination | Coordinate explicitly shared goals across hosts without turning a provider or host session into control-plane authority. | Draft contract / provider qualification | [Tracker #3245](https://github.com/huangruiteng/loopx/issues/3245) · [RFC](../architecture/rfcs/shared-goal-authority-state-provider-v0.md) | +| Architecture and Research Incubator | Qualify architectural changes and research mechanisms before they expand production scope. | Mixed; see the portfolio below | [Tracker #3246](https://github.com/huangruiteng/loopx/issues/3246) · [RFC index](../architecture/rfcs/README.md) | + +## Long-Horizon Benchmarks And Evidence + +The benchmark program has two separate lanes: + +1. **Capability evidence** asks whether LoopX changes benchmark-native outcome, + efficiency, or recovery under matched conditions. +2. **Mechanism research** asks why a change occurred by studying stride, + evidence delivery, replan, exploration, human attention, memory utility, + and capability evolution. + +ALE, LHTB, and DeepSWE provide complementary external-validity environments. +LoopX preserves each benchmark's native result and does not publish a synthetic +aggregate score. Contributor-ready work includes deterministic adapter +fixtures, treatment-integrity checks, public-safe reducers, and analysis +contracts. Live cases, raw tasks, trajectories, verifier output, uploads, +official scoring, and unpublished comparisons remain maintainer-owned. + +## Operator Surface And IM Integration + +The current frontend and IM work is an incubation program, not shipped `main` +behavior. The primary implementation package is +[#3167](https://github.com/huangruiteng/loopx/pull/3167), led by +[`@maxliux5`](https://github.com/maxliux5), on the +[`frontend-control-plane-im-prototype-rfc`](https://github.com/huangruiteng/loopx/tree/frontend-control-plane-im-prototype-rfc) +integration branch. [#3200](https://github.com/huangruiteng/loopx/pull/3200) +is a separate event-driven proposal currently under requested changes. + +Promotion to `main` follows this ledger: + +1. characterize shared projection and session contracts; +2. isolate provider-neutral backend, delivery, and receipt boundaries; +3. promote cohesive runtime or projection slices with parity checks; +4. promote UI only after its source projections and authority boundaries are + stable, with owner preview for first-screen changes; +5. keep credentials, provider payloads, private receipts, local paths, and raw + sessions outside public fixtures and browser state. + +`@maxliux5` is the current implementation lead, not a repository-wide +maintainer appointment. Lark-specific paths follow the subsystem review route +recorded in [project governance](https://github.com/huangruiteng/loopx/blob/main/.github/GOVERNANCE.md); +cross-subsystem +and mainline promotion decisions remain with the lead maintainer. + +## Shared Goal Authority And Cross-Host Coordination + +This direction is intentionally not called a "shared metadata database." +NoKV is an unpromoted optional provider candidate behind LoopX authority, not +the authority itself. Agents do not connect directly to NoKV. Run history, +status, quota, scheduler state, host sessions, and evidence retain their +existing owners. + +The next qualifying slice is provider-neutral: extract one compact +command/precondition/receipt/outcome core, qualify a file-backed provider on +the same `claim_work` contract, and prove target-scoped conflicts plus atomic +original-receipt replay. Live NoKV qualification, renew/reclaim semantics, +distributed quota, authentication, high availability, and broader state sync +remain later explicit decisions. + +## Architecture And Research Incubator + +| Exploration | Stage | Current entry | Implementation rule | +| --- | --- | --- | --- | +| Effect Program and settlement algebra | Accepted / runtime hardening | [RFC](../architecture/rfcs/agent-loop-effect-interpreter-v0.md) | Improve the shared typed contract and negative coverage; keep scheduler ownership and domain-local ACK semantics explicit. | +| TypeScript control-plane migration | Draft / parity experiment | [#3225](https://github.com/huangruiteng/loopx/issues/3225) | Start with process-boundary parity over existing fixtures; Python remains canonical during transition. | +| Hierarchical agent stride | Active research | [#3203](https://github.com/huangruiteng/loopx/issues/3203) | Qualify read-only and shadow evidence before adaptive selection. | +| Research exploration control plane | Draft / typed frontier | [RFC](../architecture/rfcs/research-exploration-control-plane-v0.md) | Keep Explore, goal-frontier, and execution authority separate. | +| Human Attention Wishlist | Draft / non-blocking sidecar | [#3179](https://github.com/huangruiteng/loopx/issues/3179) | Do not change user gates, selected work, quota, or notification authority. | +| Goal artifact lifecycle projection | Draft / read model | [RFC](../architecture/rfcs/goal-artifact-lifecycle-projection-v0.md) | Derive milestones and legal next transitions read-only before adding writes. | +| Post-outcome memory utility | Draft / research | [#3214](https://github.com/huangruiteng/loopx/issues/3214) | Attribute utility only after verified outcomes; retrieval and model judgment remain advisory. | +| Goal Channel and Agent IM/OpenViking boundaries | Draft / integration exploration | [RFC index](../architecture/rfcs/README.md) | Keep delivery, durable control state, and scoped context under separate owners. | + +An exploration becomes implementation-ready only when it has a real caller or +compatibility contract, an agreed smallest slice, and focused qualification. +Do not add speculative modules or duplicate authority merely because an RFC +describes a possible future. + +## Contribution And Governance Loop + +1. Choose the closest direction tracker and read its current stage and + boundary. +2. Find a bounded task on the + [Contributor Task Board](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md), + or open a contributor + task issue that names the direction, intended base branch, smallest slice, + non-goals, and validation. +3. For incubation work, state whether the PR targets `main` or an integration + branch. A `main` PR must not silently depend on an unpromoted branch-only + contract. +4. Keep discussion and direction tracking in the umbrella issue; keep concrete + implementation and review in its own issue or PR. + +A material stage, owner, integration-branch, promotion-gate, or scope change +must update this page through a PR. The RFC index and task board should change +in the same PR when their routing changes. After merge, maintainers update the +pinned Discussion; the Discussion does not override merged repository truth. + +The four `direction/*` labels are routing aids, not maturity or authority +claims. Implementation-lead recognition records current public work and does +not silently grant repository permissions or maintainer status. diff --git a/docs/project/technical-directions.zh-CN.md b/docs/project/technical-directions.zh-CN.md new file mode 100644 index 000000000..d0c25e288 --- /dev/null +++ b/docs/project/technical-directions.zh-CN.md @@ -0,0 +1,134 @@ +# 当前技术方向 + +本文是由 maintainer 维护的 LoopX 当前战略方向地图,帮助贡献者理解项目正在 +投入什么、各方向成熟到什么阶段,以及一项有价值的贡献应该从哪里开始。它不是 +交付承诺、release plan,也不替代已经发布的契约。 + +> 语言说明:本文与 +> [英文版](technical-directions.md)互为语义镜像;实质差异属于缺陷。 + +## 如何阅读这张地图 + +- `main` 上的代码、已发布 artifact 和 stable reference contract 定义真实已交付行为。 +- RFC 记录提案或已经接受的架构决策,其效力以 RFC 内标注的状态为准。没有实现的 + 内容不会因为写进 RFC 就成为事实。 +- integration branch 是实现候选,不是第二条产品基线;晋级之前不会改变 `main` + 契约。 +- direction tracker 记录结果目标、边界和实质决策。只有另行拆出的有界 issue 或 + task-board 条目才可以被认领。 +- 置顶的 + [当前技术方向与已知限制](https://github.com/huangruiteng/loopx/discussions/2851) + Discussion 是本文面向社区的投影。 + +统一使用以下成熟度词汇: + +| 阶段 | 含义 | +| --- | --- | +| Shipped / hardening | 行为或架构契约已进入 `main`;后续工作改善可靠性、parity 或易用性。 | +| Incubating / qualification | 已有真实候选,但兼容性、证据或晋级 gate 尚未通过。 | +| Active research | 正在进行会产出证据的实验;结果不会自动变成默认行为或产品结论。 | +| Draft | 欢迎设计评审;只有达成一致的最小有用切片才能进入实现。 | +| Held | 保留方向可见性,但在明确 gate 改变之前不应开始实现。 | + +## 稳定基础:控制面可靠性 + +Goal、typed todo、quota、scheduler hint、evidence、Effect Program settlement、 +recovery 与 host parity 是所有战略方向共用的底座。其可靠性工作继续通过 +[Contributor Task Board](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) +和 `control-plane` label +推进;这是持续的产品 hardening,不是另一套方向事实源。 + +## 战略方向 + +| 方向 | 目标 | 阶段 | 从这里开始 | +| --- | --- | --- | --- | +| 长程 Benchmark 与证据 | 产出 benchmark-native、可复现的长程能力证据,并用受控任务研究机制。 | Active research | [Tracker #3243](https://github.com/huangruiteng/loopx/issues/3243) · [RFC](../architecture/rfcs/long-horizon-harness-benchmark-research-program-v0.zh-CN.md) | +| Operator Surface 与 IM Integration | 通过一致的 operator workspace,让 goal、session、decision、evidence 和有界协作清晰可操作。 | 在 integration branch 孵化 | [Tracker #3244](https://github.com/huangruiteng/loopx/issues/3244) · [integration branch](https://github.com/huangruiteng/loopx/tree/frontend-control-plane-im-prototype-rfc) | +| Shared Goal Authority 与跨 Host 协作 | 让多 host 围绕显式共享 goal 协作,同时避免 provider 或 host session 变成控制面权威。 | Draft contract / provider qualification | [Tracker #3245](https://github.com/huangruiteng/loopx/issues/3245) · [RFC](../architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md) | +| 架构与研究孵化器 | 在扩大生产代码范围之前验证架构演进与研究机制。 | 混合成熟度,见下表 | [Tracker #3246](https://github.com/huangruiteng/loopx/issues/3246) · [RFC 索引](../architecture/rfcs/README.md) | + +## 长程 Benchmark 与证据 + +Benchmark 计划包含两条必须分开的 lane: + +1. **能力证据**:在匹配条件下,LoopX 是否改变 benchmark 原生结果、效率或恢复 + 能力。 +2. **机制研究**:通过 stride、evidence delivery、replan、exploration、human + attention、memory utility 与 capability evolution 研究变化为什么发生。 + +ALE、LHTB 与 DeepSWE 提供互补的外部效度环境。LoopX 保留每个 benchmark 的 +原生结果,不发布合成总分。贡献者可以参与 deterministic adapter fixture、 +treatment-integrity 检查、public-safe reducer 和分析契约。真实 case、raw task、 +trajectory、verifier output、upload、官方 scoring 和未公开比较仍由 maintainer +负责。 + +## Operator Surface 与 IM Integration + +当前前端与 IM 工作是孵化计划,不是 `main` 已交付行为。主要实现包是由 +[`@maxliux5`](https://github.com/maxliux5)主导的 +[#3167](https://github.com/huangruiteng/loopx/pull/3167),基于 +[`frontend-control-plane-im-prototype-rfc`](https://github.com/huangruiteng/loopx/tree/frontend-control-plane-im-prototype-rfc) +集成分支。[#3200](https://github.com/huangruiteng/loopx/pull/3200) 是另一项仍处于 +requested changes 的 event-driven 提案。 + +进入 `main` 的 promotion ledger 为: + +1. 先用 fixture 刻画共享 projection 与 session contract; +2. 隔离 provider-neutral backend、delivery 与 receipt 边界; +3. 通过 parity check 晋级内聚的 runtime 或 projection 切片; +4. source projection 与 authority 边界稳定后再晋级 UI;首屏变化需要 owner preview; +5. credential、provider payload、private receipt、本地路径和 raw session 不得进入 + public fixture 或浏览器状态。 + +`@maxliux5` 是当前 implementation lead,不代表仓库级 maintainer 任命。Lark 专属 +路径遵循[项目治理](https://github.com/huangruiteng/loopx/blob/main/.github/GOVERNANCE.md) +记录的 subsystem review route; +跨子域和 mainline 晋级决策仍由 lead maintainer 负责。 + +## Shared Goal Authority 与跨 Host 协作 + +本方向刻意不叫“共享元信息数据库”。NoKV 是位于 LoopX authority 之后、尚未晋级 +的可选 provider candidate,而不是 authority 本身。Agent 不直接连接 NoKV。 +Run history、status、quota、scheduler state、host session 与 evidence 继续由原有 +边界负责。 + +下一项 qualification 必须先保持 provider-neutral:抽取紧凑的 +command/precondition/receipt/outcome core,让 file-backed provider 通过相同的 +`claim_work` 契约,并证明 target-scoped conflict 与 atomic original-receipt +replay。真实 NoKV qualification、renew/reclaim、distributed quota、认证、HA 与更 +广泛的状态同步都是后续显式决策,不属于隐含 scope。 + +## 架构与研究孵化器 + +| 探索 | 阶段 | 当前入口 | 实现规则 | +| --- | --- | --- | --- | +| Effect Program 与 settlement algebra | Accepted / runtime hardening | [RFC](../architecture/rfcs/agent-loop-effect-interpreter-v0.zh-CN.md) | 改善共享 typed contract 与 negative coverage;明确 scheduler ownership 和 domain-local ACK 语义。 | +| TypeScript 控制面迁移 | Draft / parity experiment | [#3225](https://github.com/huangruiteng/loopx/issues/3225) | 从基于已有 fixture 的进程边界 parity 开始;迁移期内 Python 保持 canonical。 | +| 分层 Agent stride | Active research | [#3203](https://github.com/huangruiteng/loopx/issues/3203) | 引入 adaptive selection 前先验证 read-only 与 shadow evidence。 | +| 研究型探索控制面 | Draft / typed frontier | [RFC](../architecture/rfcs/research-exploration-control-plane-v0.zh-CN.md) | 保持 Explore、goal-frontier 和 execution authority 分离。 | +| Human Attention Wishlist | Draft / non-blocking sidecar | [#3179](https://github.com/huangruiteng/loopx/issues/3179) | 不改变 user gate、selected work、quota 或 notification authority。 | +| Goal artifact lifecycle projection | Draft / read model | [RFC](../architecture/rfcs/goal-artifact-lifecycle-projection-v0.zh-CN.md) | 先以 read-only 方式推导 milestone 与合法 next transition。 | +| 结果后 memory utility | Draft / research | [#3214](https://github.com/huangruiteng/loopx/issues/3214) | 只在 verified outcome 后归因;retrieval 与 model judgment 保持 advisory。 | +| Goal Channel 与 Agent IM/OpenViking 边界 | Draft / integration exploration | [RFC 索引](../architecture/rfcs/README.md) | delivery、durable control state 与 scoped context 分属不同 owner。 | + +探索只有在具备真实 caller 或兼容契约、达成一致的最小切片和聚焦 qualification 后, +才进入 implementation-ready。不能只因 RFC 描述了未来可能性,就加入 speculative +module 或重复 authority。 + +## 贡献与治理闭环 + +1. 选择最接近的 direction tracker,阅读当前阶段与边界。 +2. 在 [Contributor Task Board](https://github.com/huangruiteng/loopx/blob/main/CONTRIBUTOR_TASKS.md) + 寻找有界任务;如果没有, + 用 contributor task 模板创建 issue,写明方向、目标 base branch、最小切片、 + non-goal 与验证方式。 +3. 孵化工作必须说明 PR 面向 `main` 还是 integration branch。面向 `main` 的 PR + 不得悄悄依赖只存在于未晋级分支的契约。 +4. Umbrella issue 用于方向讨论与决策;具体实现和 review 使用独立 issue 或 PR。 + +阶段、owner、integration branch、promotion gate 或 scope 出现实质变化时,必须通过 +PR 更新本文;如果 RFC index 或 task board 的路由也发生变化,应在同一 PR 更新。 +合并后由 maintainer 更新置顶 Discussion;Discussion 不能覆盖仓库已合并事实。 + +四个 `direction/*` label 只负责路由,不代表成熟度或 authority。对 implementation +lead 的认可记录当前公开工作,不会静默授予仓库权限或 maintainer 身份。 diff --git a/examples/docs-governance-smoke.py b/examples/docs-governance-smoke.py index c12238659..f7480c401 100644 --- a/examples/docs-governance-smoke.py +++ b/examples/docs-governance-smoke.py @@ -169,7 +169,7 @@ def assert_contributor_task_board_is_current() -> None: "`/loop-goal-summary` remains host-only and outside this contributor slice", "A shared typed Effect Program drives quota, Turn, task-lease, and todo-completion settlement", "The scheduler remains outside settlement", - "M7 parity fixtures, a read-only journal lens, and a shared typed settlement receipt-chain driver are shipped", + "M7 parity fixtures plus a read-only journal inspection/`interpret_turn_journal` lens shipped", "do not extract a shared executor until two adapters share execution ownership", ): assert required in tasks, required @@ -188,6 +188,82 @@ def assert_contributor_task_board_is_current() -> None: assert stale not in tasks, stale +def assert_technical_direction_governance_is_current() -> None: + direction = read("docs/project/technical-directions.md") + direction_zh = read("docs/project/technical-directions.zh-CN.md") + rfc_index = read("docs/architecture/rfcs/README.md") + tasks = read("CONTRIBUTOR_TASKS.md") + issue_template = read(".github/ISSUE_TEMPLATE/contributor-task.yml") + pr_template = read(".github/PULL_REQUEST_TEMPLATE.md") + governance = read(".github/GOVERNANCE.md") + + for required in ( + "Long-Horizon Benchmarks and Evidence", + "Operator Surface and IM Integration", + "Shared Goal Authority and Cross-host Coordination", + "Architecture and Research Incubator", + "Stable Foundation: Control-Plane Reliability", + "frontend-control-plane-im-prototype-rfc", + "@maxliux5", + "NoKV is an unpromoted optional provider candidate", + "#3243", + "#3244", + "#3245", + "#3246", + ): + assert required in direction, required + + for required in ( + "长程 Benchmark 与证据", + "Operator Surface 与 IM Integration", + "Shared Goal Authority 与跨 Host 协作", + "架构与研究孵化器", + "稳定基础:控制面可靠性", + "frontend-control-plane-im-prototype-rfc", + "@maxliux5", + "NoKV 是位于 LoopX authority 之后", + "#3243", + "#3244", + "#3245", + "#3246", + ): + assert required in direction_zh, required + + for required in ( + "## Accepted Architecture", + "## Active Research Programs", + "## Drafts Under Review", + "## Draft Integration Proposals", + "Current Technical Directions", + ): + assert required in rfc_index, required + assert "## Active Drafts" not in rfc_index + + for required in ( + "Long-Horizon Benchmarks and Evidence", + "Operator Surface and IM Integration", + "Shared Goal Authority and Cross-host Coordination", + "Architecture and Research Incubator", + ): + assert required in tasks, required + + for content in (issue_template, pr_template): + for required in ( + "Long-horizon benchmark evidence", + "Operator surface and IM integration", + "Shared Goal Authority and cross-host coordination", + "Architecture and research incubator", + ): + assert required in content, required + + for required in ( + "## Technical Direction Governance", + "direction/*", + "does not override merged runtime and stable reference contracts", + ): + assert required in governance, required + + def main() -> int: docs_index = read("docs/README.md") root_readme = read("README.md") @@ -240,6 +316,7 @@ def main() -> int: "reference/README.md", "showcases/README.md", "development/testing-and-quality.md", + "project/technical-directions.md", ]: assert required in docs_index, required @@ -272,6 +349,7 @@ def main() -> int: "docs/update-notes/README.md", ], "Project and Community": [ + "docs/project/technical-directions.md", ".github/GOVERNANCE.md", "CONTRIBUTING.md", "CONTRIBUTOR_TASKS.md", @@ -286,7 +364,10 @@ def main() -> int: "集成与扩展": navigation_contracts["Integrate and Extend"], "构建与评审 LoopX": navigation_contracts["Build and Review LoopX"], "查看结果与证据": navigation_contracts["Inspect Outcomes"], - "项目与社区": navigation_contracts["Project and Community"], + "项目与社区": [ + "docs/project/technical-directions.zh-CN.md", + *navigation_contracts["Project and Community"][1:], + ], } for readme, contracts in ( (root_readme, navigation_contracts), @@ -347,6 +428,8 @@ def main() -> int: "docs/research/long-horizon-agent-benchmarks/README.md", "docs/showcases/README.md", "docs/product/runtimes/codex-cli/codex-cli-tui-loop.md", + "docs/project/technical-directions.md", + "docs/project/technical-directions.zh-CN.md", ]: assert (REPO_ROOT / path).is_file(), path @@ -382,6 +465,7 @@ def main() -> int: assert_local_doc_links_resolve() assert_effect_interpreter_docs_are_canonical() assert_contributor_task_board_is_current() + assert_technical_direction_governance_is_current() collaboration_rfc = read( "docs/architecture/rfcs/agent-im-openviking-collaboration-v0.md" diff --git a/mkdocs.yaml b/mkdocs.yaml index ef5402e6d..fb944121e 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -116,6 +116,7 @@ nav: - Contracts: reference/contracts/README.md - Development: - development/README.md + - Technical Directions: project/technical-directions.md - Testing And Quality: development/testing-and-quality.md - Documentation Layout: development/documentation-layout.md - Benchmark Workflow: development/benchmark-developer-workflow.md