@sireai/optimus 0.1.42 → 0.1.43

package/task-harnesses/pm/STANDARD.md

@@ -1,68 +1,275 @@
 # STANDARD
 
-Defines the mandatory execution sequence, result contract, and closure standard.
+Defines the mandatory PM execution flow, artifact contract, and delivery standard.
 
 ## Execution sequence
 Complete work in this order:
 
 1. `Read`
 - read the full source requirement document
-- extract explicit goals, users, flows, states, constraints, and missing information
-- identify review-critical rules such as thresholds, counts, ordering, gating, frequency limits, role boundaries, and content-type distinctions
+- extract goals, users, flows, states, constraints, open questions, and explicit source facts
+- identify review-critical rules such as thresholds, counts, ordering, gating, permissions, formulas, and content-type distinctions
 
 2. `Map`
 - build a requirement map before designing screens or writing HTML
-- include at minimum:
+- include:
   - product goal
   - target user
+  - bounded scope
   - entry point
   - core flow
   - key states
-  - requirement-critical rules
+  - critical rules
   - explicit non-goals
   - open questions
 
 3. `Plan Representation`
-- for each requirement-critical rule, choose exactly one:
+- for each critical rule, choose exactly one:
   - `Represented Interactively`
   - `Represented via Annotation`
   - `Downgraded / Simulated`
   - `Not Represented`
-- prefer interaction for core user behavior and decision-critical meaning
-- use annotation when meaning is review-critical but not faithfully expressible through lightweight interaction
-- use downgrade/simulation only when it still supports useful review
-- choose `Represented Interactively` only when the prototype will contain clear behavioral evidence of that rule
-- if the rule is mainly conveyed by explanation, scenario toggles, or approximation rather than direct behavior, classify it as `Represented via Annotation` or `Downgraded / Simulated`
+- 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 prototype scope that makes the core flow reviewable
-- decide covered screens, transitions, states, and review-mode needs
+- define the minimum screen and state set that makes the accepted scope reviewable
 - reduce breadth before inventing detail
-- record only the minimum assumptions needed for continuity
+- keep assumptions minimal and explicit
 
 5. `Build`
-- produce one reviewable interactive HTML prototype package
-- convert requirement meaning into UI structure, interaction, and visible states
-- add review mode when rule meaning cannot be carried clearly by interaction alone
-- use annotation content to mark `Confirmed`, `Simulated`, and `Open Question` where helpful
+- produce one reviewable `prototype.html`
+- make the main path, major states, and key transitions inspectable
+- add anchored review annotations where interaction is insufficient
 
-6. `Deliver`
+6. `Review`
+- explicitly spawn one reviewer subagent after the first build
+- reviewer input must include:
+  - source requirement document
+  - source URL when available
+  - accepted scope
+  - requirement map
+  - 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
+- record one review round log entry containing:
+  - round number
+  - reviewer verdict
+  - key gaps
+  - recommended revisions or explicit approval
+
+7. `Revise`
+- if the reviewer finds material gaps, revise the prototype and rerun the reviewer subagent
+- maximum review rounds: 3 total
+- stop early when:
+  - the reviewer approves closure, or
+  - another revise-and-review pass is unlikely to improve trustworthiness materially
+- if the final reviewer verdict still finds material gaps after the maximum rounds, downgrade closure instead of looping further
+- the builder must read the latest reviewer output before revising
+- each new review round must include:
+  - the previous reviewer findings
+  - what the builder changed
+  - what the builder intentionally did not change and why
+
+8. `Deliver`
 - generate `result.md`
-- declare outputs precisely
-- surface assumptions, open questions, uncovered areas, and representation choices explicitly
+- 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
 
 If execution stops early, explain which step could not be completed and why.
 
+## Review loop standard
+- the reviewer subagent must be explicitly requested; do not assume it will appear automatically
+- the reviewer must not rewrite the prototype directly; it judges and recommends
+- the builder applies revisions and owns the updated artifacts
+- provide the reviewer with facts first, not builder conclusions first
+- the reviewer should treat the source requirement and produced artifacts as primary evidence; builder framing is supporting context only
+- reviewer findings do not justify unlimited scope growth, denser chrome, or extra speculative screens by default
+- each review round should classify every material finding as one of:
+  - `Must Fix Before Complete`
+  - `Can Ship As Partial`
+  - `Open Question`
+- examples of `Must Fix Before Complete`:
+  - missing core flow coverage
+  - important requirement content is omitted, misunderstood, or inconsistent with the source document
+  - missing or materially wrong key rule representation
+  - 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
+  - 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
+
+## Reviewer input contract
+Each reviewer round should receive these inputs in this priority order:
+
+1. `Source facts`
+- requirement document
+- source URL when available
+- explicit accepted scope
+
+2. `Produced artifacts`
+- `prototype.html` when present
+- `result.md`
+- `annotations.json` when present
+
+3. `Builder framing`
+- requirement map
+- representation plan
+- declared deviations, simulations, and unresolved points
+
+4. `Round context`
+- current round number
+- maximum rounds: `3`
+- previous reviewer findings and builder revisions for rounds 2 and 3
+
+## Reviewer output contract
+Each reviewer round must produce a compact review record that the builder can consume directly.
+
+Minimum fields:
+- `Round`
+- `Reviewer Verdict`
+- `Coverage Assessment`
+- `Logic Demonstrability Assessment`
+- `AI Coding Readiness Assessment`
+- `UI Fidelity Assessment`
+- `Core Panel Visibility Check`
+- `New Regression Since Previous Round`
+- `Must Fix Before Complete`
+- `Can Ship As Partial`
+- `Open Questions`
+- `Suggested Revisions`
+
+Allowed `Reviewer Verdict` values:
+- `Must Fix Before Complete`
+- `Can Ship As Partial`
+- `Approved for Prototype Complete`
+
+## Builder handoff contract
+After each review round, the builder must:
+- read the full reviewer output
+- revise the prototype and companion artifacts when `Must Fix Before Complete` findings exist
+- preserve unresolved but non-blocking findings inside `result.md` when closure remains partial
+- run a full core-panel self-check before requesting the next review, not only a point fix for the previous `Must Fix`
+- prefer downgrade over another revise round when the next change would require speculative product invention, materially larger scope, or a noisier prototype that reduces reviewability
+- write a concise round handoff into `review-log.md` containing:
+  - what was changed
+  - what was intentionally left unchanged
+  - why the next review should or should not still expect a gap
+
+## Reviewer rubric
+The reviewer must evaluate the prototype against these principles in order:
+
+1. `Requirement completeness and correctness`
+- the interactive prototype must reflect the requirement document fully enough for the accepted scope
+- important requirement content must not be missing, misunderstood, or inconsistent
+
+2. `Logic demonstrability`
+- deeper logic chains, dependencies, and cause-effect behavior must be demonstrated clearly
+- 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
+- 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
+
+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
+- 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
+- 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
+
+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
+  - 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
+
+## Closure policy
+- decide closure only after the final review round
+- `Prototype Complete` requires:
+  - reviewer approval with no unresolved `Must Fix Before Complete` findings
+  - accepted scope, core path, major states, and key rules are reviewable
+  - source fact drift is absent or explicitly declared and immaterial
+  - deeper logic chains are demonstrated clearly enough for review
+  - the artifact set can guide downstream AI coding without major rule ambiguity
+  - UI quality is credible for design review and meaningfully uses source visual guidance when present
+- `Prototype Partial` requires:
+  - a meaningful prototype exists
+  - reviewer found remaining material gaps, but the output is still useful for review
+  - remaining weakness is declared clearly in `result.md`
+- prefer `Prototype Partial` over a larger but less truthful or less readable prototype assembled only to satisfy late review suggestions
+- `Analysis Only` requires:
+  - no trustworthy interactive prototype was produced, or
+  - trustworthy completion would require heavy invention, or
+  - repeated review still shows the prototype is too weak to present as a meaningful interactive artifact
+- do not use review-round exhaustion as a reason to mark `Prototype Complete`
+- if closure is `Prototype Partial` or `Analysis Only`, state the strongest blocker or downgrade reason explicitly
+
 ## Prototype standard
-- the primary artifact is an interactive `prototype.html`
+- `prototype.html` is the main review artifact
 - the prototype must make the main user flow inspectable
-- the prototype should support meaningful review actions such as navigation, state changes, or key transitions
-- prioritize depth on the core path over shallow breadth
-- when major requirement meaning cannot be expressed clearly by interaction alone, include review annotations
-- review annotations should be anchored to concrete UI targets, states, or transitions whenever possible
-- the prototype must remain understandable when annotations are hidden or minimized
+- 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
 
-## Result contract
+## 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`
 - return `failed` only for true runtime exceptions
@@ -77,110 +284,200 @@ If execution stops early, explain which step could not be completed and why.
 }
 ```
 
-## Result artifacts
+## 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
-- any task-private files must be declared inside `result.md`
-
-## Result content
-At minimum, `result.md` must include:
-
-### Delivery Summary
-- `Closure`
-- `Document Basis`
-- `Prototype Scope`
-- `Core Flow`
-- `Platform`
-- `Coverage`
-- `Uncovered Areas`
-- `Assumptions`
-- `Open Questions`
-- `Next Action`
-
-### Outputs
-- `Main Review Artifact`
-- `Additional Files`
-- `Output Notes`
-
-### Requirement Mapping
-- `Requirement-Critical Rules`
-- `Represented Interactively`
-- `Represented via Annotation`
-- `Downgraded / Simulated`
-- `Not Represented`
-- `Representation Notes`
-
-### Detail
-- `Product Goal`
-- `Target User`
-- `Requirement Summary`
-- `Covered Screens / Sections`
-- `Key Interactions`
-- `States Included`
-- `Confirmed Requirements Used`
-- `Inferred Structure`
-- `Interaction Fidelity Notes`
-- `Review Annotation Notes`
-- `Assumptions`
-- `Open Questions`
-- `Recommended Next Step`
-
-## Result rules
-- separate confirmed requirement content from inferred structure
-- prefer explicit gaps over fake completeness
-- if annotation-assisted explanation is used, state what was annotated and why interaction was insufficient
-- do not claim a requirement was fully represented when it was only approximated or annotated
-- ensure representation fields reflect the actual prototype, not the intended prototype
-- if a key rule was merged or flattened for simplicity, record that downgrade explicitly
-- `Represented Interactively` requires clear behavioral evidence in the prototype itself, not only surrounding explanation
-- if a rule depends mainly on annotation, scenario controls, review notes, or narrative explanation, do not classify it as fully interactive
-
-## Closure standard
-- `Prototype Complete`: accepted scope, core path, major states, and key rules are reviewable through faithful interaction or clear anchored annotation
-- `Prototype Partial`: a meaningful prototype exists, but important parts remain uncovered, over-merged, or materially downgraded
-- `Analysis Only`: no trustworthy interactive prototype was produced; explain blockers and minimum missing input
-
-## Result template
+- task-private files are optional and must support review directly
+
+## Feishu delivery document
+- default language is Chinese unless the task explicitly requires another language
+- 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. `需求文档`
+- provide the direct jump link to the source requirement
+
+2. `产物`
+- provide the downloadable artifact set
+- 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.
+
+### Must include
+1. `规则补充`
+- implementation-critical product rules
+- key business logic or calculation rules
+- important state, permission, ordering, threshold, or edge-case notes
+
+2. `原型未完全表达的点`
+- rules or branches not fully captured by direct interaction
+- simulations, merges, or approximations that must not be mistaken as final behavior
+- open points that materially affect implementation understanding
+
+3. `闭环判定`
+- final closure level: `Prototype Complete` / `Prototype Partial` / `Analysis Only`
+- the strongest reviewer-backed reason for that closure
+- if closure is not `Prototype Complete`, the top remaining blocker or downgrade reason
+
+### Must not do
+- do not use `result.md` as a delivery index
+- do not carry `需求文档` or artifact listing here
+- do not add sections such as `产物文件`, `Artifacts`, `Artifact Files`, `需求文档`, or `产物`
+- do not rewrite the PRD
+- do not let prototype sample data appear indistinguishable from source fact
+- do not dump full per-round review logs into `result.md`; keep detailed round logs in `review-log.md`
+
+### Template
+```md
+# 规则补充
+- Load Rate 的 All 口径必须使用 total power / total capacity，不能使用平均值。
+- 历史范围下 KPI `Power` 的精确定义仍待确认，当前原型仅保留交互与展示位置。
+- 权限不足时仅展示空状态说明，不在原型中模拟真实鉴权流程。
+
+# 原型未完全表达的点
+- Live 数据刷新为轻量模拟，不能视为真实刷新策略。
+- Last 90 Days 的聚合粒度仍需产品确认后才能进入研发实现。
+
+# 闭环判定
+- Closure Level：Prototype Partial
+- 判定依据：核心路径可评审，但历史场景下 Power 统计口径仍未明确，且部分规则仍以 annotation 承载。
+- 主要剩余问题：历史 Power KPI 的精确定义仍是 Open Question。
+```
+
+## `review-log.md` contract
+- purpose: preserve the reviewer subagent loop as an audit trail
+- language may be concise Chinese with stable English verdict tokens
+- one round entry per review pass
+- minimum fields per round:
+  - `Round`
+  - `Reviewer Verdict`
+  - `Must Fix`
+  - `Can Ship As Partial`
+  - `Open Questions`
+  - `Builder Action`
+- if the first review approves the prototype directly, still record that approval round
+
+### Template
 ```md
-# Delivery Summary
-- Closure: Prototype Complete
-- Document Basis: source requirement document provided with the task
-- Prototype Scope: First-run onboarding only
-- Core Flow: Open invite -> fill profile -> complete setup
-- Platform: responsive
-- Coverage: invite landing, profile form, completion state
-- Uncovered Areas: admin approval flow, edge-case recovery paths
-- Assumptions: invite is valid for one user session
-- Open Questions: SSO is optional or required?
-- Next Action: review flow coverage and copy gaps
-
-# Outputs
-- Main Review Artifact: `prototype.html`
-- Additional Files: none
-- Output Notes: private outputs live under `artifactDir`
-
-# Requirement Mapping
-- Requirement-Critical Rules: invite entry, profile setup, completion confirmation
-- Represented Interactively: invite landing, profile form, submit, validation, success transition
-- Represented via Annotation: backend invite validation timing and account-provisioning dependency
-- Downgraded / Simulated: loading and approval check are simulated only
-- Not Represented: admin exception handling path
-- Representation Notes: approval timing is review-critical but backend-owned, so it is explained through anchored annotation instead of fake workflow logic
-
-# Detail
-- Product Goal: Reduce first-day confusion
-- Target User: New employee
-- Requirement Summary: Requirement input asks for a reviewable onboarding prototype
-- Covered Screens / Sections: invite landing, profile setup, confirmation
-- Key Interactions: start onboarding, form validation, submit, success transition
-- States Included: empty, validation error, loading, success
-- Confirmed Requirements Used: invite entry, profile setup, completion confirmation
-- Inferred Structure: lightweight validation and loading states to preserve flow continuity
-- Interaction Fidelity Notes: validation and submit flow are interactive; backend approval timing is annotation-assisted
-- Review Annotation Notes: approval dependency is attached to submit and success states in review mode
-- Assumptions: backend behavior is simulated only
-- Open Questions: whether manager approval is required before activation
-- Recommended Next Step: confirm approval rule and add branch state if needed
+# Review Log
+
+## Round 1
+- Reviewer Verdict: Must Fix Before Complete
+- Must Fix:
+  - `All Load Rate` 计算口径未在原型或 annotation 中明确。
+- Can Ship As Partial:
+  - 历史 Power KPI 口径仍可暂时保留为开放问题。
+- Open Questions:
+  - `Last 90 Days` 聚合粒度是否按月展示仍待确认。
+- Builder Action:
+  - 新增 `All Load Rate` 计算口径 annotation，并调整结果说明。
 ```
+
+## Final self-check
+- review loop ran and did not exceed 3 rounds
+- reviewer was explicitly requested as a subagent, not implied
+- 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

package/task-harnesses/pm/ANNOTATION_PATTERN.md

@@ -1,58 +0,0 @@
-# PM Review Annotation Pattern
-
-Reusable implementation convention for review-mode annotations in PM prototypes.
-
-## Goal
-- keep the prototype itself reviewable
-- attach rule meaning to the exact UI it explains
-- avoid replacing interaction with detached explanation blocks
-
-## Structure
-1. `Review mode`
-- provide a dedicated toggle
-- keep annotation chrome hidden or minimized outside review mode
-
-2. `Target anchors`
-- assign stable target ids
-- recommended attribute: `data-pm-target="<id>"`
-
-3. `Annotation records`
-- bind each annotation to one primary target
-- recommended attribute: `data-pm-annotation="<id>"`
-- recommended fields:
-  - `targetId`
-  - `type`: `confirmed` | `simulated` | `open-question`
-  - `title`
-  - `body`
-  - optional `secondaryTargets`
-
-4. `Focused guidance`
-- selecting an annotation should highlight the bound target
-- optional connector lines may be used when they improve readability
-- prefer one focused annotation at a time
-
-## Recommended behavior
-- click annotation item -> scroll target into view -> highlight target -> optionally show connector
-- click target badge -> open linked annotation detail
-- switching annotation should clear the previous focus state
-
-## Visual semantics
-- `Confirmed`: neutral or positive emphasis
-- `Simulated`: caution emphasis
-- `Open Question`: unresolved emphasis
-- use color as reinforcement, not as the only signal
-
-## Good annotation content
-- server-side rules that materially affect UX
-- thresholds, limits, gating, ordering, and role boundaries
-- prototype approximations that could otherwise be mistaken as final behavior
-- unresolved details reviewers must notice
-
-## Bad annotation content
-- long PRD excerpts with no interpretation
-- generic summary already obvious from the screen
-- visual design commentary that does not affect product understanding
-- missing core flows that should have been prototyped directly
-
-## Rule of thumb
-If UI alone would cause requirement misunderstanding, add an anchored annotation. If direct interaction explains the requirement better, build the interaction instead.