diff --git a/AGENTS.md b/AGENTS.md index c32cd88f..607450f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,6 +67,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `docs/reference/arch.md`：UniDesk 分布式工作平台的长期架构约束。 - `docs/reference/repo-tree.md`：仓库结构目标与组件边界。 +- `docs/reference/strategy-governance.md`：UniDesk 外部收益约束、短长期收益划分和需求审视准则；战略分析记录见 GitHub issue #7。 - `docs/reference/observability.md`：服务日志、任务活性、通用性能指标 API 和性能面板的可观测性规则。 - `docs/reference/microservices.md`：用户服务（兼容命名 `microservice`）的配置、代理、安全边界、unidesk-direct/k3sctl-managed 部署模式、Todo Note/Baidu Netdisk on main-server、k3s Control/Code Queue/MDTODO/Decision Center/FindJob/Pipeline/MET Nonlinear on D601 和验证规则。 - `docs/reference/windows-passthrough.md`：WSL provider 通过 SSH 透传调用 Windows cmd/PowerShell、Keil、COM 串口和 Windows 侧 skill 的长期规则。 diff --git a/docs/reference/release-governance.md b/docs/reference/release-governance.md index 56d2e109..670a461c 100644 --- a/docs/reference/release-governance.md +++ b/docs/reference/release-governance.md @@ -2,6 +2,8 @@ This document owns UniDesk release-line, runtime-version, CI/CD control-plane and feature-flag governance. The decision record is [GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6). +For the strategic filter that decides whether a proposal should exist at all, and whether it is a short-term or long-term investment, see `docs/reference/strategy-governance.md`. + ## Decision Scope The governance decision covers four boundaries: diff --git a/docs/reference/strategy-governance.md b/docs/reference/strategy-governance.md new file mode 100644 index 00000000..7750e7bd --- /dev/null +++ b/docs/reference/strategy-governance.md @@ -0,0 +1,108 @@ +# Strategy Governance + +This document owns the strategic filter for UniDesk requirements: external-benefit traceability, short-term versus long-term investment, and anti-loop guardrails for architecture proposals. The analysis record for the current strategy framing is [GitHub issue #7](https://github.com/pikasTech/unidesk/issues/7). + +## Scope + +Use this document when deciding whether a proposal should exist at all, how urgently it should be pursued, and whether it belongs to the short-term stabilization lane or the long-term base-layer lane. + +This document does not replace `docs/reference/release-governance.md`, `docs/reference/deploy.md`, `docs/reference/ci.md`, or `docs/reference/dev-environment.md`. Those documents own the execution rules. This document owns the demand filter before execution begins. + +## Strategic Principle + +UniDesk should be driven by verifiable external demand, not by infinite internal derivation or architecture taste. + +External demand includes: + +- user workflow value; +- operator recovery and incident reduction; +- deployment speed and reliability; +- delivery throughput; +- availability and observability; +- cost reduction that can be observed in practice; +- adoption or retention of a real platform capability. + +Internal work is acceptable only when it can be traced to one of those outcomes or when it is a bounded investment that clearly compounds future external value. + +If a proposal only improves internal elegance, symmetry, or conceptual purity, it is not sufficient by itself. + +## Requirement Test + +Before accepting a requirement, answer these questions: + +1. Who outside the implementation layer benefits? +2. What external metric improves? +3. How can the improvement be observed or verified? +4. Is the benefit short-term or long-term? +5. What user, operator, or delivery pain does it remove? +6. What is the removal condition if the proposal is only a temporary bridge? + +If the answers are weak, the requirement should be dropped, narrowed, or rewritten. + +## Short-Term Work + +Short-term work is the work that improves the current usable system quickly. + +It is valid when it: + +- stabilizes `release/v1`; +- protects production availability; +- makes CI/CD more reliable; +- reduces manual recovery effort; +- fixes user-visible defects; +- removes a blocking infrastructure defect that slows delivery; +- reduces the cost of shipping the next verified change. + +Short-term work should be chosen when the main problem is today’s delivery or today’s operational fragility. + +## Long-Term Work + +Long-term work is justified only when it creates reusable base capability with a measurable future payoff. + +It is valid when it: + +- raises the ceiling of future delivery speed; +- reduces the cost of every later change; +- improves the quality of the stable base for future releases; +- removes a recurring class of operational pain; +- creates a platform primitive that several real workflows will use. + +Long-term work must still have: + +- a named beneficiary; +- a measurable hypothesis; +- a bounded budget; +- an explicit exit condition; +- a reason it cannot wait forever. + +If it does not have those properties, it is just internal expansion. + +## Anti-Patterns + +Do not accept requirements that are only: + +- architecture experimentation without a user or operator payoff; +- feature-flag proliferation without a clear removal path; +- hidden dual paths that are hard to test or observe; +- abstractions added only because they feel cleaner; +- infrastructure work that cannot be tied to delivery, availability, recovery, or cost; +- refactors that move complexity around without reducing external pain. + +## Review Rule + +When a new idea is proposed, classify it immediately: + +- `short-term` if it helps the current stable base ship, recover, or stay alive; +- `long-term` if it compounds future capability and has a clear payoff path; +- `reject` if it cannot be tied to external benefit. + +The default bias should be toward the simplest path that satisfies the external need. Complexity is only justified when it pays for itself in visible external value. + +## Relationship to Other Governance Docs + +- `docs/reference/release-governance.md` owns release lines, stabilization windows, runtime pinning, and feature-flag governance. +- `docs/reference/deploy.md` owns desired-state reconciliation and rollout semantics. +- `docs/reference/ci.md` owns CI execution on D601. +- `docs/reference/dev-environment.md` owns the persistent dev lane. + +This document sits above those execution rules. It decides whether a proposed change is worth doing and whether it belongs to the short-term lane or the long-term lane.