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](https://github.com/pikasTech/unidesk/issues/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.