@sireai/optimus 0.1.43 → 0.1.44

package/task-harnesses/pm/STANDARD.md

@@ -26,11 +26,9 @@ Complete work in this order:
 3. `Plan Representation`
 - for each critical rule, choose exactly one:
   - `Represented Interactively`
-  - `Represented via Annotation`
   - `Downgraded / Simulated`
   - `Not Represented`
 - use `Represented Interactively` only when the prototype will contain direct behavioral evidence
-- use `Represented via Annotation` when the rule is review-critical but not faithfully expressible through lightweight interaction
 
 4. `Frame`
 - define the minimum screen and state set that makes the accepted scope reviewable
@@ -40,7 +38,7 @@ Complete work in this order:
 5. `Build`
 - produce one reviewable `prototype.html`
 - make the main path, major states, and key transitions inspectable
-- add anchored review annotations where interaction is insufficient
+- keep `prototype.html` focused on product interaction; move scope, exclusion, truth-status, simulation, and open-question commentary into `result.md` unless the source explicitly defines them as in-product UI
 
 6. `Review`
 - explicitly spawn one reviewer subagent after the first build
@@ -52,7 +50,6 @@ Complete work in this order:
   - representation plan
   - `prototype.html` when present
   - `result.md`
-  - `annotations.json` when present
   - previous review findings and builder revisions when this is round 2 or 3
   - current round number and maximum round count
 - reviewer must judge against the reviewer rubric defined below
@@ -61,6 +58,7 @@ Complete work in this order:
   - reviewer verdict
   - key gaps
   - recommended revisions or explicit approval
+- if reviewer subagent invocation fails, log the failure, skip the reviewer loop for this run, and continue normal artifact finalization; do not hang waiting for the reviewer path to recover
 
 7. `Revise`
 - if the reviewer finds material gaps, revise the prototype and rerun the reviewer subagent
@@ -77,7 +75,6 @@ Complete work in this order:
 
 8. `Deliver`
 - generate `result.md`
-- generate `annotations.json` whenever a prototype exists
 - generate `review-log.md` whenever the reviewer loop ran
 - declare deviations, simulations, and unresolved implementation-critical points precisely
 
@@ -101,12 +98,11 @@ If execution stops early, explain which step could not be completed and why.
   - deeper business or interaction logic is only described textually and not demonstrated clearly enough through the prototype
   - explicit source fact drift that changes review interpretation
   - simulated behavior presented as if it were faithful interaction
-  - annotation layer and `annotations.json` disagree on important meaning
   - the artifact set is too weak to guide downstream AI coding without major guessing about rules, state behavior, or implementation intent
   - UI quality is materially below design-review expectations, especially when the requirement document already contains screenshots, diagrams, or strong structural visual cues that were not meaningfully used
 - examples of `Can Ship As Partial`:
   - useful prototype exists, but some non-core states remain merged or downgraded
-  - some important but secondary rules remain annotation-only or simulated
+  - some important but secondary rules remain simulated or unresolved in direct interaction
   - the core design direction is usable, but parts of the visual system or interaction polish still fall below designer-grade expectations
 - examples of `Open Question`:
   - requirement ambiguity prevents stronger representation without invention
@@ -122,7 +118,6 @@ Each reviewer round should receive these inputs in this priority order:
 2. `Produced artifacts`
 - `prototype.html` when present
 - `result.md`
-- `annotations.json` when present
 
 3. `Builder framing`
 - requirement map
@@ -180,33 +175,34 @@ The reviewer must evaluate the prototype against these principles in order:
 - the prototype must not stop at first-layer description when the requirement meaning depends on richer interaction logic
 
 3. `Representation correctness`
-- interaction, annotation, simulation, and omission must each be used deliberately and truthfully
-- if a rule needs to be understood for review, the prototype must either demonstrate it or annotate it clearly
+- interaction, simulation, and omission must each be used deliberately and truthfully
+- if a rule cannot be demonstrated faithfully in interaction, disclose the gap clearly in `result.md`
 - avoid reviewer-driven overbuilding: do not add extra flows, fake data breadth, or decorative complexity unless they directly improve requirement understanding
 
 4. `Implementation readiness for AI coding`
-- the artifact set must give downstream AI coding enough rule context, implementation guardrails, and annotation coverage to avoid major guessing
-- `result.md` and `annotations.json` must supplement the prototype where direct interaction is insufficient
+- the artifact set must give downstream AI coding enough rule context and implementation guardrails to avoid major guessing
+- `result.md` must supplement the prototype where direct interaction is insufficient
 
 5. `UI design quality and visual fidelity`
 - the prototype should reach designer-grade quality for its intended fidelity level
 - visual style, layout cues, screenshots, diagrams, and structural hints from the requirement document should be used as first-priority guidance when present
 - avoid generic or template-looking UI when the source document provides stronger visual direction
 - every core panel must remain visibly populated and reviewable after each revision; do not accept a panel that retains only a title, labels, or empty chrome while its intended information carrier disappears
+- default prototype surface should read as product UI, not as a delivery brief or review console
 - for `Represented Interactively` modules, visible content must remain materially present:
   - charts must still show visible bars, lines, points, or equivalent graphical carriers rather than only captions or axes
-  - explanatory panels such as scope / exclusion / guardrail areas must retain enough information density to communicate their product meaning, not collapse into thin placeholder copy
+  - product-facing explanatory content that is actually part of the requirement UI must retain enough information density to communicate its meaning, not collapse into thin placeholder copy
 - if a revision fixes one issue but causes another panel to become visually blank, materially thinner, or harder to interpret, treat it as a new blocking regression
 
 6. `Artifact consistency`
-- `prototype.html`, `result.md`, and `annotations.json` must agree on key rules, limitations, and truth status
+- `prototype.html` and `result.md` must agree on key rules, limitations, and truth status
 
 7. `Regression control after revision`
 - every later review round must re-check the whole accepted prototype surface, not only the previous `Must Fix` list
 - the reviewer must explicitly check for:
   - newly blank or near-blank core panels
   - graph containers whose DOM exists but whose intended visual content is no longer meaningfully visible
-  - explanatory regions whose copy became materially thinner or lost review-critical meaning
+  - product-facing explanatory regions required by the source UI whose copy became materially thinner or lost review-critical meaning
   - regressions where a previously acceptable panel becomes weaker after a later fix
 - if such regressions appear, record them under `New Regression Since Previous Round` and classify them as `Must Fix Before Complete` when they reduce reviewability materially
 - if a proposed follow-up revision would mainly add complexity, speculative branches, or visual clutter without improving requirement truth, prefer `Prototype Partial` over further churn
@@ -234,41 +230,14 @@ The reviewer must evaluate the prototype against these principles in order:
 
 ## Prototype standard
 - `prototype.html` is the main review artifact
+- `prototype.html` is not the place for delivery portal content or truth-status summaries
 - the prototype must make the main user flow inspectable
 - prefer depth on the core path over shallow breadth
 - support meaningful review actions such as navigation, state changes, or key transitions
-- keep the prototype understandable when annotations are hidden or minimized
 - keep core panels visibly reviewable across revisions
 - do not count a panel as interactively represented when its main carrier is visually missing, nearly invisible, or replaced by bare labels only
 - if the accepted scope includes charted data, preserve visible graphical expression rather than text-only scaffolding
 
-## Annotation standard
-- use a dedicated review mode when annotation density would otherwise disrupt normal reading
-- keep review-only controls secondary, collapsible, or minimized
-- assign stable target ids
-- recommended target attribute: `data-pm-target="<id>"`
-- recommended annotation attribute: `data-pm-annotation="<id>"`
-- each annotation should have one primary target whenever possible
-- clicking an annotation should focus its target; clicking a target affordance should reveal the linked annotation
-- use stronger linkage such as numbered mapping or connector lines only when it improves readability
-
-### Truth semantics
-- `Confirmed`: faithful to the source requirement
-- `Simulated`: represented approximately for review
-- `Open Question`: unresolved and review-relevant
-
-### Good annotation targets
-- server-side rules that materially affect UX
-- formulas, thresholds, ordering, permissions, and gating
-- approximations that could be mistaken as final behavior
-- unresolved behavior reviewers must notice
-
-### Bad annotation targets
-- long PRD excerpts without interpretation
-- screen facts already obvious from the UI
-- visual design commentary with no product impact
-- missing core flows that should have been prototyped directly
-
 ## Runtime result contract
 - return exactly one runtime JSON object
 - normal completion and analysis-only closure both return `completed`
@@ -287,10 +256,10 @@ The reviewer must evaluate the prototype against these principles in order:
 ## Artifact contract
 - always generate `result.md` on normal completion
 - generate `prototype.html` for `Prototype Complete` and `Prototype Partial`
-- generate `annotations.json` whenever `prototype.html` is generated
 - generate `review-log.md` when the PM review loop ran
 - use repository-independent artifact paths
 - `result.md` is the only framework-required result artifact
+- put scope boundaries, exclusions, simulations, assumptions, truth-status notes, and open questions in `result.md`, not in the default prototype page
 - task-private files are optional and must support review directly
 
 ## Feishu delivery document
@@ -298,7 +267,6 @@ The reviewer must evaluate the prototype against these principles in order:
 - treat the Feishu delivery document as a delivery portal, not as a second PRD
 - detailed interaction belongs in `prototype.html`
 - rule supplements belong in `result.md`
-- structured annotation handoff belongs in `annotations.json`
 
 ### Required structure
 1. `需求文档`
@@ -309,95 +277,6 @@ The reviewer must evaluate the prototype against these principles in order:
 - keep artifact purpose attached to the artifact itself
 - do not duplicate artifact content in the delivery document
 
-## `annotations.json` contract
-- purpose: machine-readable export of anchored review annotations
-- paired artifact: normally `prototype.html`
-- top-level fields:
-  - `version`
-  - `artifact`
-  - `annotations`
-- `annotations` may be empty, but must exist when the file is generated
-
-### Each annotation record must include
-- `id`
-- `target`
-- `type`
-- `status`
-- `priority`
-- `title`
-- `content`
-
-### `target` must include
-- `elementId`
-- optional `page`
-- optional `anchor`: `top` | `right` | `bottom` | `left` | `inline` | `state`
-
-### Recommended enums
-- `type`:
-  - `interaction`
-  - `state`
-  - `calculation`
-  - `data_rule`
-  - `edge_case`
-  - `empty_state`
-  - `error_state`
-  - `permission`
-  - `out_of_scope`
-  - `open_question`
-- `status`:
-  - `confirmed`
-  - `assumption`
-  - `simulated`
-  - `open_question`
-- `priority`:
-  - `high`
-  - `medium`
-  - `low`
-
-### Optional fields
-- `secondaryTargets`
-- `structured`
-- `sourceRefs`
-- `implementationImpact`
-- `reviewerNote`
-
-### Generation rules
-- create one record per review-meaningful annotation, not per DOM node
-- if a rule is represented via annotation in the requirement map, it must appear here
-- keep truth status aligned with the prototype
-- use `structured` when formulas, state keys, limits, or forbidden interpretations matter
-
-### Example
-```json
-{
-  "version": "1.0",
-  "artifact": "prototype.html",
-  "annotations": [
-    {
-      "id": "ann-load-rate-all-rule",
-      "target": {
-        "page": "power-dashboard",
-        "elementId": "load-rate-trend-chart",
-        "anchor": "right"
-      },
-      "type": "calculation",
-      "status": "confirmed",
-      "priority": "high",
-      "title": "All Load Rate calculation rule",
-      "content": "All Load Rate must be calculated as total power divided by total capacity. Average-based calculation is not allowed.",
-      "structured": {
-        "formula": "sum(room.power) / sum(room.capacity) * 100%",
-        "forbiddenFormula": "avg(room.loadRate)"
-      },
-      "implementationImpact": "Affects trend aggregation logic, KPI cards, and chart tooltip consistency.",
-      "sourceRefs": [
-        "Load Rate Trend > All view"
-      ]
-    }
-  ]
-}
-```
-
 ## `result.md` contract
 Keep `result.md` dense, implementation-oriented, and in Chinese unless the task explicitly requires another language.
 
@@ -438,7 +317,7 @@ Keep `result.md` dense, implementation-oriented, and in Chinese unless the task
 
 # 闭环判定
 - Closure Level：Prototype Partial
-- 判定依据：核心路径可评审，但历史场景下 Power 统计口径仍未明确，且部分规则仍以 annotation 承载。
+- 判定依据：核心路径可评审，但历史场景下 Power 统计口径仍未明确，且部分规则仍未能通过交互完全表达。
 - 主要剩余问题：历史 Power KPI 的精确定义仍是 Open Question。
 ```
 
@@ -462,13 +341,13 @@ Keep `result.md` dense, implementation-oriented, and in Chinese unless the task
 ## Round 1
 - Reviewer Verdict: Must Fix Before Complete
 - Must Fix:
-  - `All Load Rate` 计算口径未在原型或 annotation 中明确。
+  - `All Load Rate` 计算口径未在原型或 `result.md` 中明确。
 - Can Ship As Partial:
   - 历史 Power KPI 口径仍可暂时保留为开放问题。
 - Open Questions:
   - `Last 90 Days` 聚合粒度是否按月展示仍待确认。
 - Builder Action:
-  - 新增 `All Load Rate` 计算口径 annotation，并调整结果说明。
+  - 补强原型交互表达，并在 `result.md` 中补充规则说明。
 ```
 
 ## Final self-check
@@ -477,7 +356,6 @@ Keep `result.md` dense, implementation-oriented, and in Chinese unless the task
 - final closure matches the last reviewer verdict
 - every material key rule has a declared representation mode
 - any remaining downgraded or missing behavior is disclosed in `result.md`
-- `annotations.json` matches the actual annotation layer in `prototype.html`
 - `result.md` contains no delivery-index or artifact-list sections
 - source facts are preserved or deviations are explicitly declared
 - sample data is not presented as source truth