docs(strategy): add external-benefit governance

This commit is contained in:
Codex
2026-05-19 08:07:56 +00:00
parent 517c8d75a8
commit ac73b05154
3 changed files with 111 additions and 0 deletions
+1
View File
@@ -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 的长期规则。
+2
View File
@@ -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:
+108
View File
@@ -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 todays delivery or todays 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.