pikasTech-unidesk/docs/reference/strategy-governance.md

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. The long-term governance follow-up for the default user path versus diagnostics/status boundary is DC-DCSN-P0-2026-004.

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.

Minimal Requirement Shaping

Before writing a long-term reference, implementation plan, issue, prompt, or task breakdown for a broad requirement, first compress the requirement to the smallest domain model that satisfies the current external need.

Use an explicit simplification pass:

1. List the rich or default architecture that first comes to mind.
2. Remove roles, groups, projects, capabilities, services, middleware, gates, and audit surfaces that are not needed for the first useful workflow.
3. Produce a before/after table showing what was removed or merged.
4. Ask whether the remaining model can be implemented with an existing service, database, and control path before introducing a new microservice or middleware.
5. Record postponed components as trigger-based follow-ups, not as phase-one dependencies.

For example, a multi-user hardware-lab requirement should first check whether admin/user, session ownership, and a single grant table are enough before adding group/project RBAC, capability matrices, OpenFGA, Keycloak, service mesh, or Kubernetes tenant abstractions. A middleware is justified only when a concrete trigger appears, such as external identity integration, inherited permissions, tenant self-service namespaces, or admission-policy enforcement that cannot be handled by the existing service boundary.

Reference And Plan Split

When the simplified requirement needs documentation, split the output:

• docs/reference/*.md owns stable design goals, authority boundaries, table or API contracts, request paths, service ownership, and acceptance criteria.
• docs/plan/*.md, GitHub issues, or project-specific planning docs own current state, source observations, implementation order, migration steps, incompatible changes, and open work.

The reference must not become a process log. It should explain the target shape as if a future implementer has not seen the chat. The plan should explain how the current source differs from that target and what must change.

For product or platform designs that touch multiple services, the plan should name each affected service and classify the change:

• data/schema change;
• API or request-chain change;
• frontend behavior change;
• worker/runtime behavior change;
• deployment or namespace/data-plane change;
• incompatible behavior that deliberately removes an old route, default, or fallback.

Do not preserve legacy compatibility just because it existed before. If the user has accepted a simplified target, old assertions, public routes, feature flags, fallbacks, or dual paths that conflict with the target should be removed in the same plan, with the user-facing breakage and migration handling stated clearly.

Progress Log Distillation

Use this rule when turning issue/PR activity, daily work logs, or project management updates into an OA/project SPEC, GitHub summary, or other planning document. The output document may contain dates and current status; this reference records only the reusable method.

Start from the active objective, not from the commit list. Read the current SPEC, epic, board, or target issue first, then read the relevant issue and PR activity. For UniDesk/HWLAB/AgentRun GitHub data, use the UniDesk gh CLI entry rather than native gh or ad hoc API scripts. When the request says "today", state the timezone and use an exact time window in the working notes or planning document.

Summaries must be semantic, not chronological. Group activity by capability domain such as user workflow, cloud collaboration, device access, observability, runtime stability, delivery infrastructure, or governance. PR numbers, issue numbers, commits, traces, and commands are evidence, not the subject of the main text.

Every progress update must include a goal-alignment pass:

• direct alignment: work that implements or proves a stated target capability;
• enabling alignment: platform, visibility, or tooling work required before the target capability can be delivered;
• partial alignment: work that touches the target area but leaves a named acceptance gap;
• no observed alignment: target areas with no current evidence.

Do not overclaim based on activity volume. A closed issue, merged PR, successful source check, or improved trace is not enough to claim the product goal is met unless the target acceptance artifact or live/runtime evidence exists. Missing SPECs, boundary drafts, runtime proofs, hardware evidence, or user-entry validation must be named explicitly as remaining gaps.

Next-stage goals must be derived from those gaps, not from generic roadmap phrases. Prefer a short list of concrete deliverables such as a SPEC issue, boundary document, runtime validation path, stable interface contract, or targeted migration. The next-stage section should explain why each item is the next step toward the active objective.

Project-specific planning documents may keep dated progress sections and source references. Long-term reference documents must not copy those dated logs; they should only capture the stable summarization method, authority boundaries, and acceptance criteria. For daily commander brief style, also follow docs/reference/code-queue-supervision.md.

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.

Default Path Boundary

When a product surface has both a primary user workflow and an internal diagnostics or acceptance surface, the primary workflow must remain the default discoverable entry. Diagnostics and status pages may exist for verification, recovery, or observability, but they do not become the product's headline or default route unless a decision record explicitly says so.

For the current HWLAB case, DC-DCSN-P0-2026-003 freezes the short-term product direction, and DC-DCSN-P0-2026-004 records the longer-term governance rule for keeping the default path distinct from diagnostics/status surfaces.

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.