From 8dae177795a8ef1306778a37239455910b897546 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 3 Jun 2026 14:15:53 +0000 Subject: [PATCH] docs: add progress log distillation guidance --- docs/reference/strategy-governance.md | 47 +++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/reference/strategy-governance.md b/docs/reference/strategy-governance.md index e61f0669..6cdb7755 100644 --- a/docs/reference/strategy-governance.md +++ b/docs/reference/strategy-governance.md @@ -94,6 +94,53 @@ 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.