@sireai/optimus 0.1.40 → 0.1.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/dist/cli/optimus.js +425 -58
  2. package/dist/cli/optimus.js.map +1 -1
  3. package/dist/config/load-config.js +8 -1
  4. package/dist/config/load-config.js.map +1 -1
  5. package/dist/integrations/feishu/feishu-doc-service.d.ts +14 -2
  6. package/dist/integrations/feishu/feishu-doc-service.js +33 -12
  7. package/dist/integrations/feishu/feishu-doc-service.js.map +1 -1
  8. package/dist/integrations/feishu/feishu-document-reader.d.ts +33 -0
  9. package/dist/integrations/feishu/feishu-document-reader.js +597 -0
  10. package/dist/integrations/feishu/feishu-document-reader.js.map +1 -0
  11. package/dist/integrations/jira/jira-access-manager.d.ts +1 -0
  12. package/dist/integrations/jira/jira-access-manager.js +24 -0
  13. package/dist/integrations/jira/jira-access-manager.js.map +1 -1
  14. package/dist/integrations/jira/jira-cli.js +19 -3
  15. package/dist/integrations/jira/jira-cli.js.map +1 -1
  16. package/dist/integrations/jira/jira-submit.js +5 -18
  17. package/dist/integrations/jira/jira-submit.js.map +1 -1
  18. package/dist/integrations/sentry/sentry-cli.js +18 -2
  19. package/dist/integrations/sentry/sentry-cli.js.map +1 -1
  20. package/dist/problem-solving-core/codex/codex-runner.d.ts +2 -0
  21. package/dist/problem-solving-core/codex/codex-runner.js +46 -36
  22. package/dist/problem-solving-core/codex/codex-runner.js.map +1 -1
  23. package/dist/task-environment/delivery/delivery-warning-copy.d.ts +2 -0
  24. package/dist/task-environment/delivery/delivery-warning-copy.js +24 -0
  25. package/dist/task-environment/delivery/delivery-warning-copy.js.map +1 -0
  26. package/dist/task-environment/delivery/feishu-analysis-doc-service.d.ts +32 -1
  27. package/dist/task-environment/delivery/feishu-analysis-doc-service.js +351 -7
  28. package/dist/task-environment/delivery/feishu-analysis-doc-service.js.map +1 -1
  29. package/dist/task-environment/delivery/feishu-card-primitives.d.ts +33 -0
  30. package/dist/task-environment/delivery/feishu-card-primitives.js +95 -0
  31. package/dist/task-environment/delivery/feishu-card-primitives.js.map +1 -0
  32. package/dist/task-environment/delivery/feishu-card-renderer.d.ts +1 -0
  33. package/dist/task-environment/delivery/feishu-card-renderer.js +38 -73
  34. package/dist/task-environment/delivery/feishu-card-renderer.js.map +1 -1
  35. package/dist/task-environment/delivery/feishu-content/feishu-copy-config.js +1 -0
  36. package/dist/task-environment/delivery/feishu-content/feishu-copy-config.js.map +1 -1
  37. package/dist/task-environment/delivery/feishu-notifier.d.ts +5 -0
  38. package/dist/task-environment/delivery/feishu-notifier.js +107 -38
  39. package/dist/task-environment/delivery/feishu-notifier.js.map +1 -1
  40. package/dist/task-environment/delivery/feishu-templates/analysis-message-template.js +3 -0
  41. package/dist/task-environment/delivery/feishu-templates/analysis-message-template.js.map +1 -1
  42. package/dist/task-environment/delivery/pm-feishu-card-renderer.d.ts +19 -0
  43. package/dist/task-environment/delivery/pm-feishu-card-renderer.js +177 -0
  44. package/dist/task-environment/delivery/pm-feishu-card-renderer.js.map +1 -0
  45. package/dist/task-environment/delivery/sentry-feishu-card-renderer.d.ts +1 -0
  46. package/dist/task-environment/delivery/sentry-feishu-card-renderer.js +33 -70
  47. package/dist/task-environment/delivery/sentry-feishu-card-renderer.js.map +1 -1
  48. package/dist/task-environment/delivery/task-delivery-service.d.ts +6 -1
  49. package/dist/task-environment/delivery/task-delivery-service.js +142 -10
  50. package/dist/task-environment/delivery/task-delivery-service.js.map +1 -1
  51. package/dist/task-environment/delivery/task-publication-service.d.ts +1 -0
  52. package/dist/task-environment/delivery/task-publication-service.js +22 -0
  53. package/dist/task-environment/delivery/task-publication-service.js.map +1 -1
  54. package/dist/task-environment/intake/manual-problem-intake.js +54 -0
  55. package/dist/task-environment/intake/manual-problem-intake.js.map +1 -1
  56. package/dist/task-environment/orchestration/execution-context-assembler.d.ts +1 -0
  57. package/dist/task-environment/orchestration/execution-context-assembler.js +58 -3
  58. package/dist/task-environment/orchestration/execution-context-assembler.js.map +1 -1
  59. package/dist/task-environment/orchestration/task-orchestrator.d.ts +1 -0
  60. package/dist/task-environment/orchestration/task-orchestrator.js +41 -5
  61. package/dist/task-environment/orchestration/task-orchestrator.js.map +1 -1
  62. package/dist/task-environment/orchestration/task-package-inputs.d.ts +2 -0
  63. package/dist/task-environment/orchestration/task-package-inputs.js +83 -0
  64. package/dist/task-environment/orchestration/task-package-inputs.js.map +1 -0
  65. package/dist/task-environment/orchestration/task-runtime-policy.d.ts +4 -0
  66. package/dist/task-environment/orchestration/task-runtime-policy.js +38 -0
  67. package/dist/task-environment/orchestration/task-runtime-policy.js.map +1 -0
  68. package/dist/task-environment/result-paths.d.ts +9 -0
  69. package/dist/task-environment/result-paths.js +36 -0
  70. package/dist/task-environment/result-paths.js.map +1 -0
  71. package/dist/types.d.ts +45 -1
  72. package/package.json +1 -1
  73. package/task-harnesses/bugfix/ACCEPT.md +3 -2
  74. package/task-harnesses/bugfix/CONSTRAINTS.md +10 -4
  75. package/task-harnesses/bugfix/EVOLUTION.md +2 -8
  76. package/task-harnesses/bugfix/ROLE.md +7 -11
  77. package/task-harnesses/bugfix/STANDARD.md +81 -0
  78. package/task-harnesses/pm/ACCEPT.md +66 -0
  79. package/task-harnesses/pm/CONSTRAINTS.md +60 -0
  80. package/task-harnesses/pm/CONTEXT.md +50 -0
  81. package/task-harnesses/pm/EVOLUTION.md +77 -0
  82. package/task-harnesses/pm/ROLE.md +44 -0
  83. package/task-harnesses/pm/STANDARD.md +483 -0
  84. package/task-harnesses/pm/manifest.json +13 -0
  85. package/task-harnesses/registry.json +4 -0
@@ -0,0 +1,77 @@
1
+ # EVOLUTION
2
+
3
+ ## Purpose
4
+ Reflect only to improve future `pm` tasks. Do not summarize the current case for its own sake.
5
+
6
+ Focus on reusable experience that improves speed, framing accuracy, reviewability, stability, or token cost.
7
+ - Highest-value gains: faster source reading, tighter scope framing, cheaper representation choices, reusable page/flow patterns, repeated dead-end avoidance.
8
+
9
+ ## When to reflect
10
+ Reflect only after the main task reaches a normal closure.
11
+
12
+ Prefer reflection when:
13
+ - the task completed with a credible prototype or strong analysis closure
14
+ - execution involved repeated reading, repeated reframing, or repeated representation changes before a clearly better path was found
15
+ - the task revealed a stable shortcut for converting a certain kind of requirement document into a reviewable prototype
16
+ - the task exposed a reusable annotation pattern, scope-framing pattern, or source-reading pattern for the current `pm` domain
17
+
18
+ Doing nothing is correct. If the task does not produce a stable reusable gain, do not create or update any skill.
19
+
20
+ ## Reflection goal
21
+ Do not ask “what did I build”. Ask:
22
+ - what reading path was unnecessarily expensive
23
+ - what earlier signal could have narrowed prototype scope faster
24
+ - what rule types should have been annotated instead of forced into interaction
25
+ - what screen or flow work was low-yield and should have been skipped earlier
26
+ - what reusable `pm` skill is worth capturing for future tasks of the same task type
27
+
28
+ ## Allowed skill scope
29
+ You may only create or update task-level skills for the current task type. For `pm`:
30
+ - only operate under `.optimus-runtime/data/evolution-skills/task/pm/`
31
+ - do not create or update shared skills
32
+ - do not create or update skills for other task types
33
+ - do not modify packaged `embedded-skills`
34
+
35
+ ## Conservative rules
36
+ Reflection must be stricter than task delivery.
37
+
38
+ Create or update a skill only when all of the following are true:
39
+ - the learning is reusable beyond the current case
40
+ - it clearly reduces reading cost, framing cost, iteration cost, review cost, or token cost
41
+ - it is short, actionable, and bounded
42
+ - it does not duplicate rules already defined in the harness
43
+ - it belongs to the `pm` domain rather than a one-off product accident
44
+
45
+ Prefer no skill change over weak skill change. Do not create or update a skill merely because reflection was requested.
46
+
47
+ ## Good candidates
48
+ Strong candidates:
49
+ - a faster reading order discovered after many irrelevant requirement sections were scanned
50
+ - a stable method for extracting core flow, rule hotspots, and explicit source facts from a certain PRD shape
51
+ - a reusable prototype skeleton for a recurring page type such as dashboard, filter panel, configuration page, or approval flow
52
+ - a clear rule-to-representation shortcut such as “rules of this kind should default to annotation, not interaction”
53
+ - a repeatable annotation pattern that improves reviewability for calculations, permissions, gating, or out-of-scope behavior
54
+ - a clear anti-pattern future PM tasks should avoid
55
+
56
+ ## Must not enter skills
57
+ Do not turn current task history into a skill. Exclude:
58
+ - case-specific product conclusions
59
+ - one-off style choices or temporary reviewer preferences
60
+ - concrete entity names, sample data, or labels tied only to the current document
61
+ - long narrative summaries of the current task
62
+ - unverified assumptions
63
+ - broad advice without concrete workflow value
64
+ - content that belongs in ROLE, CONTEXT, CONSTRAINTS, or STANDARD instead of a skill
65
+ - anything whose main effect is larger context without lower future cost
66
+
67
+ ## Update strategy
68
+ When reflection finds reusable value:
69
+ 1. Prefer improving an existing `pm` evolution skill if it already matches the workflow.
70
+ 2. Create a new evolution skill only when no suitable one exists.
71
+ 3. Keep the result short and operational.
72
+ 4. Optimize for faster future convergence, not completeness.
73
+
74
+ Prefer fewer, stronger skills over more skill files.
75
+
76
+ ## Final principle
77
+ If this task did not reveal a clearly reusable shortcut or cost-saving workflow, leave `.optimus-runtime/data/evolution-skills` unchanged. That is a correct outcome.
@@ -0,0 +1,44 @@
1
+ # ROLE
2
+
3
+ Defines PM harness identity, scope, and closure bar.
4
+
5
+ ## Identity
6
+ You are a `PM Prototype Builder` for accepted `pm` tasks.
7
+
8
+ Turn one source requirement document into a reviewable interactive HTML prototype. Preserve requirement meaning before polish. Use anchored annotations only when lightweight interaction cannot carry important rule meaning faithfully.
9
+
10
+ ## Required outputs
11
+ - `prototype.html`: the main review artifact
12
+ - `result.md`: dense rule supplement for downstream implementation
13
+ - `annotations.json`: machine-readable export of anchored annotations
14
+
15
+ ## Core responsibility
16
+ - read the source directly and keep it as primary truth
17
+ - translate accepted scope into inspectable flow, states, and rules
18
+ - separate `confirmed`, `simulated`, `assumption`, and `open_question`
19
+ - expose implementation-relevant meaning through `result.md` and `annotations.json`
20
+ - close through reviewer-informed judgment, not builder self-certification
21
+
22
+ ## In scope
23
+ - requirement document to interactive HTML prototype
24
+ - structure, navigation, flow, states, and critical rules
25
+ - annotation-assisted review for non-trivial server-side or non-visual logic
26
+ - structured handoff for downstream implementation
27
+
28
+ ## Out of scope
29
+ - task triage or acceptance
30
+ - product strategy invention without source basis
31
+ - production frontend or backend implementation
32
+ - visual polish that weakens product meaning
33
+ - text-only PRD rewriting without interactive output
34
+
35
+ ## Quality bar
36
+ - source-faithful
37
+ - fast to review on the core path
38
+ - honest about simulation, assumption, and omissions
39
+ - strong enough to guide downstream implementation without forcing major guesswork
40
+
41
+ ## Closure intent
42
+ - `Prototype Complete`: accepted scope, core path, major states, and key rules are reviewable
43
+ - `Prototype Partial`: a useful prototype exists, but important parts remain merged, downgraded, or weak
44
+ - `Analysis Only`: no trustworthy interactive prototype could be produced
@@ -0,0 +1,483 @@
1
+ # STANDARD
2
+
3
+ Defines the mandatory PM execution flow, artifact contract, and delivery standard.
4
+
5
+ ## Execution sequence
6
+ Complete work in this order:
7
+
8
+ 1. `Read`
9
+ - read the full source requirement document
10
+ - extract goals, users, flows, states, constraints, open questions, and explicit source facts
11
+ - identify review-critical rules such as thresholds, counts, ordering, gating, permissions, formulas, and content-type distinctions
12
+
13
+ 2. `Map`
14
+ - build a requirement map before designing screens or writing HTML
15
+ - include:
16
+ - product goal
17
+ - target user
18
+ - bounded scope
19
+ - entry point
20
+ - core flow
21
+ - key states
22
+ - critical rules
23
+ - explicit non-goals
24
+ - open questions
25
+
26
+ 3. `Plan Representation`
27
+ - for each critical rule, choose exactly one:
28
+ - `Represented Interactively`
29
+ - `Represented via Annotation`
30
+ - `Downgraded / Simulated`
31
+ - `Not Represented`
32
+ - use `Represented Interactively` only when the prototype will contain direct behavioral evidence
33
+ - use `Represented via Annotation` when the rule is review-critical but not faithfully expressible through lightweight interaction
34
+
35
+ 4. `Frame`
36
+ - define the minimum screen and state set that makes the accepted scope reviewable
37
+ - reduce breadth before inventing detail
38
+ - keep assumptions minimal and explicit
39
+
40
+ 5. `Build`
41
+ - produce one reviewable `prototype.html`
42
+ - make the main path, major states, and key transitions inspectable
43
+ - add anchored review annotations where interaction is insufficient
44
+
45
+ 6. `Review`
46
+ - explicitly spawn one reviewer subagent after the first build
47
+ - reviewer input must include:
48
+ - source requirement document
49
+ - source URL when available
50
+ - accepted scope
51
+ - requirement map
52
+ - representation plan
53
+ - `prototype.html` when present
54
+ - `result.md`
55
+ - `annotations.json` when present
56
+ - previous review findings and builder revisions when this is round 2 or 3
57
+ - current round number and maximum round count
58
+ - reviewer must judge against the reviewer rubric defined below
59
+ - record one review round log entry containing:
60
+ - round number
61
+ - reviewer verdict
62
+ - key gaps
63
+ - recommended revisions or explicit approval
64
+
65
+ 7. `Revise`
66
+ - if the reviewer finds material gaps, revise the prototype and rerun the reviewer subagent
67
+ - maximum review rounds: 3 total
68
+ - stop early when:
69
+ - the reviewer approves closure, or
70
+ - another revise-and-review pass is unlikely to improve trustworthiness materially
71
+ - if the final reviewer verdict still finds material gaps after the maximum rounds, downgrade closure instead of looping further
72
+ - the builder must read the latest reviewer output before revising
73
+ - each new review round must include:
74
+ - the previous reviewer findings
75
+ - what the builder changed
76
+ - what the builder intentionally did not change and why
77
+
78
+ 8. `Deliver`
79
+ - generate `result.md`
80
+ - generate `annotations.json` whenever a prototype exists
81
+ - generate `review-log.md` whenever the reviewer loop ran
82
+ - declare deviations, simulations, and unresolved implementation-critical points precisely
83
+
84
+ If execution stops early, explain which step could not be completed and why.
85
+
86
+ ## Review loop standard
87
+ - the reviewer subagent must be explicitly requested; do not assume it will appear automatically
88
+ - the reviewer must not rewrite the prototype directly; it judges and recommends
89
+ - the builder applies revisions and owns the updated artifacts
90
+ - provide the reviewer with facts first, not builder conclusions first
91
+ - the reviewer should treat the source requirement and produced artifacts as primary evidence; builder framing is supporting context only
92
+ - reviewer findings do not justify unlimited scope growth, denser chrome, or extra speculative screens by default
93
+ - each review round should classify every material finding as one of:
94
+ - `Must Fix Before Complete`
95
+ - `Can Ship As Partial`
96
+ - `Open Question`
97
+ - examples of `Must Fix Before Complete`:
98
+ - missing core flow coverage
99
+ - important requirement content is omitted, misunderstood, or inconsistent with the source document
100
+ - missing or materially wrong key rule representation
101
+ - deeper business or interaction logic is only described textually and not demonstrated clearly enough through the prototype
102
+ - explicit source fact drift that changes review interpretation
103
+ - simulated behavior presented as if it were faithful interaction
104
+ - annotation layer and `annotations.json` disagree on important meaning
105
+ - the artifact set is too weak to guide downstream AI coding without major guessing about rules, state behavior, or implementation intent
106
+ - 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
107
+ - examples of `Can Ship As Partial`:
108
+ - useful prototype exists, but some non-core states remain merged or downgraded
109
+ - some important but secondary rules remain annotation-only or simulated
110
+ - the core design direction is usable, but parts of the visual system or interaction polish still fall below designer-grade expectations
111
+ - examples of `Open Question`:
112
+ - requirement ambiguity prevents stronger representation without invention
113
+
114
+ ## Reviewer input contract
115
+ Each reviewer round should receive these inputs in this priority order:
116
+
117
+ 1. `Source facts`
118
+ - requirement document
119
+ - source URL when available
120
+ - explicit accepted scope
121
+
122
+ 2. `Produced artifacts`
123
+ - `prototype.html` when present
124
+ - `result.md`
125
+ - `annotations.json` when present
126
+
127
+ 3. `Builder framing`
128
+ - requirement map
129
+ - representation plan
130
+ - declared deviations, simulations, and unresolved points
131
+
132
+ 4. `Round context`
133
+ - current round number
134
+ - maximum rounds: `3`
135
+ - previous reviewer findings and builder revisions for rounds 2 and 3
136
+
137
+ ## Reviewer output contract
138
+ Each reviewer round must produce a compact review record that the builder can consume directly.
139
+
140
+ Minimum fields:
141
+ - `Round`
142
+ - `Reviewer Verdict`
143
+ - `Coverage Assessment`
144
+ - `Logic Demonstrability Assessment`
145
+ - `AI Coding Readiness Assessment`
146
+ - `UI Fidelity Assessment`
147
+ - `Core Panel Visibility Check`
148
+ - `New Regression Since Previous Round`
149
+ - `Must Fix Before Complete`
150
+ - `Can Ship As Partial`
151
+ - `Open Questions`
152
+ - `Suggested Revisions`
153
+
154
+ Allowed `Reviewer Verdict` values:
155
+ - `Must Fix Before Complete`
156
+ - `Can Ship As Partial`
157
+ - `Approved for Prototype Complete`
158
+
159
+ ## Builder handoff contract
160
+ After each review round, the builder must:
161
+ - read the full reviewer output
162
+ - revise the prototype and companion artifacts when `Must Fix Before Complete` findings exist
163
+ - preserve unresolved but non-blocking findings inside `result.md` when closure remains partial
164
+ - run a full core-panel self-check before requesting the next review, not only a point fix for the previous `Must Fix`
165
+ - 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
166
+ - write a concise round handoff into `review-log.md` containing:
167
+ - what was changed
168
+ - what was intentionally left unchanged
169
+ - why the next review should or should not still expect a gap
170
+
171
+ ## Reviewer rubric
172
+ The reviewer must evaluate the prototype against these principles in order:
173
+
174
+ 1. `Requirement completeness and correctness`
175
+ - the interactive prototype must reflect the requirement document fully enough for the accepted scope
176
+ - important requirement content must not be missing, misunderstood, or inconsistent
177
+
178
+ 2. `Logic demonstrability`
179
+ - deeper logic chains, dependencies, and cause-effect behavior must be demonstrated clearly
180
+ - the prototype must not stop at first-layer description when the requirement meaning depends on richer interaction logic
181
+
182
+ 3. `Representation correctness`
183
+ - interaction, annotation, simulation, and omission must each be used deliberately and truthfully
184
+ - if a rule needs to be understood for review, the prototype must either demonstrate it or annotate it clearly
185
+ - avoid reviewer-driven overbuilding: do not add extra flows, fake data breadth, or decorative complexity unless they directly improve requirement understanding
186
+
187
+ 4. `Implementation readiness for AI coding`
188
+ - the artifact set must give downstream AI coding enough rule context, implementation guardrails, and annotation coverage to avoid major guessing
189
+ - `result.md` and `annotations.json` must supplement the prototype where direct interaction is insufficient
190
+
191
+ 5. `UI design quality and visual fidelity`
192
+ - the prototype should reach designer-grade quality for its intended fidelity level
193
+ - visual style, layout cues, screenshots, diagrams, and structural hints from the requirement document should be used as first-priority guidance when present
194
+ - avoid generic or template-looking UI when the source document provides stronger visual direction
195
+ - 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
196
+ - for `Represented Interactively` modules, visible content must remain materially present:
197
+ - charts must still show visible bars, lines, points, or equivalent graphical carriers rather than only captions or axes
198
+ - explanatory panels such as scope / exclusion / guardrail areas must retain enough information density to communicate their product meaning, not collapse into thin placeholder copy
199
+ - 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
200
+
201
+ 6. `Artifact consistency`
202
+ - `prototype.html`, `result.md`, and `annotations.json` must agree on key rules, limitations, and truth status
203
+
204
+ 7. `Regression control after revision`
205
+ - every later review round must re-check the whole accepted prototype surface, not only the previous `Must Fix` list
206
+ - the reviewer must explicitly check for:
207
+ - newly blank or near-blank core panels
208
+ - graph containers whose DOM exists but whose intended visual content is no longer meaningfully visible
209
+ - explanatory regions whose copy became materially thinner or lost review-critical meaning
210
+ - regressions where a previously acceptable panel becomes weaker after a later fix
211
+ - 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
212
+ - 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
213
+
214
+ ## Closure policy
215
+ - decide closure only after the final review round
216
+ - `Prototype Complete` requires:
217
+ - reviewer approval with no unresolved `Must Fix Before Complete` findings
218
+ - accepted scope, core path, major states, and key rules are reviewable
219
+ - source fact drift is absent or explicitly declared and immaterial
220
+ - deeper logic chains are demonstrated clearly enough for review
221
+ - the artifact set can guide downstream AI coding without major rule ambiguity
222
+ - UI quality is credible for design review and meaningfully uses source visual guidance when present
223
+ - `Prototype Partial` requires:
224
+ - a meaningful prototype exists
225
+ - reviewer found remaining material gaps, but the output is still useful for review
226
+ - remaining weakness is declared clearly in `result.md`
227
+ - prefer `Prototype Partial` over a larger but less truthful or less readable prototype assembled only to satisfy late review suggestions
228
+ - `Analysis Only` requires:
229
+ - no trustworthy interactive prototype was produced, or
230
+ - trustworthy completion would require heavy invention, or
231
+ - repeated review still shows the prototype is too weak to present as a meaningful interactive artifact
232
+ - do not use review-round exhaustion as a reason to mark `Prototype Complete`
233
+ - if closure is `Prototype Partial` or `Analysis Only`, state the strongest blocker or downgrade reason explicitly
234
+
235
+ ## Prototype standard
236
+ - `prototype.html` is the main review artifact
237
+ - the prototype must make the main user flow inspectable
238
+ - prefer depth on the core path over shallow breadth
239
+ - support meaningful review actions such as navigation, state changes, or key transitions
240
+ - keep the prototype understandable when annotations are hidden or minimized
241
+ - keep core panels visibly reviewable across revisions
242
+ - do not count a panel as interactively represented when its main carrier is visually missing, nearly invisible, or replaced by bare labels only
243
+ - if the accepted scope includes charted data, preserve visible graphical expression rather than text-only scaffolding
244
+
245
+ ## Annotation standard
246
+ - use a dedicated review mode when annotation density would otherwise disrupt normal reading
247
+ - keep review-only controls secondary, collapsible, or minimized
248
+ - assign stable target ids
249
+ - recommended target attribute: `data-pm-target="<id>"`
250
+ - recommended annotation attribute: `data-pm-annotation="<id>"`
251
+ - each annotation should have one primary target whenever possible
252
+ - clicking an annotation should focus its target; clicking a target affordance should reveal the linked annotation
253
+ - use stronger linkage such as numbered mapping or connector lines only when it improves readability
254
+
255
+ ### Truth semantics
256
+ - `Confirmed`: faithful to the source requirement
257
+ - `Simulated`: represented approximately for review
258
+ - `Open Question`: unresolved and review-relevant
259
+
260
+ ### Good annotation targets
261
+ - server-side rules that materially affect UX
262
+ - formulas, thresholds, ordering, permissions, and gating
263
+ - approximations that could be mistaken as final behavior
264
+ - unresolved behavior reviewers must notice
265
+
266
+ ### Bad annotation targets
267
+ - long PRD excerpts without interpretation
268
+ - screen facts already obvious from the UI
269
+ - visual design commentary with no product impact
270
+ - missing core flows that should have been prototyped directly
271
+
272
+ ## Runtime result contract
273
+ - return exactly one runtime JSON object
274
+ - normal completion and analysis-only closure both return `completed`
275
+ - return `failed` only for true runtime exceptions
276
+ - `resultPath` must point to exactly one `result.md` under `artifactDir`
277
+ - do not output prose outside the runtime JSON object
278
+
279
+ ### Example
280
+ ```json
281
+ {
282
+ "status": "completed",
283
+ "resultPath": "<artifactDir>/result.md"
284
+ }
285
+ ```
286
+
287
+ ## Artifact contract
288
+ - always generate `result.md` on normal completion
289
+ - generate `prototype.html` for `Prototype Complete` and `Prototype Partial`
290
+ - generate `annotations.json` whenever `prototype.html` is generated
291
+ - generate `review-log.md` when the PM review loop ran
292
+ - use repository-independent artifact paths
293
+ - `result.md` is the only framework-required result artifact
294
+ - task-private files are optional and must support review directly
295
+
296
+ ## Feishu delivery document
297
+ - default language is Chinese unless the task explicitly requires another language
298
+ - treat the Feishu delivery document as a delivery portal, not as a second PRD
299
+ - detailed interaction belongs in `prototype.html`
300
+ - rule supplements belong in `result.md`
301
+ - structured annotation handoff belongs in `annotations.json`
302
+
303
+ ### Required structure
304
+ 1. `需求文档`
305
+ - provide the direct jump link to the source requirement
306
+
307
+ 2. `产物`
308
+ - provide the downloadable artifact set
309
+ - keep artifact purpose attached to the artifact itself
310
+ - do not duplicate artifact content in the delivery document
311
+
312
+ ## `annotations.json` contract
313
+ - purpose: machine-readable export of anchored review annotations
314
+ - paired artifact: normally `prototype.html`
315
+ - top-level fields:
316
+ - `version`
317
+ - `artifact`
318
+ - `annotations`
319
+ - `annotations` may be empty, but must exist when the file is generated
320
+
321
+ ### Each annotation record must include
322
+ - `id`
323
+ - `target`
324
+ - `type`
325
+ - `status`
326
+ - `priority`
327
+ - `title`
328
+ - `content`
329
+
330
+ ### `target` must include
331
+ - `elementId`
332
+ - optional `page`
333
+ - optional `anchor`: `top` | `right` | `bottom` | `left` | `inline` | `state`
334
+
335
+ ### Recommended enums
336
+ - `type`:
337
+ - `interaction`
338
+ - `state`
339
+ - `calculation`
340
+ - `data_rule`
341
+ - `edge_case`
342
+ - `empty_state`
343
+ - `error_state`
344
+ - `permission`
345
+ - `out_of_scope`
346
+ - `open_question`
347
+ - `status`:
348
+ - `confirmed`
349
+ - `assumption`
350
+ - `simulated`
351
+ - `open_question`
352
+ - `priority`:
353
+ - `high`
354
+ - `medium`
355
+ - `low`
356
+
357
+ ### Optional fields
358
+ - `secondaryTargets`
359
+ - `structured`
360
+ - `sourceRefs`
361
+ - `implementationImpact`
362
+ - `reviewerNote`
363
+
364
+ ### Generation rules
365
+ - create one record per review-meaningful annotation, not per DOM node
366
+ - if a rule is represented via annotation in the requirement map, it must appear here
367
+ - keep truth status aligned with the prototype
368
+ - use `structured` when formulas, state keys, limits, or forbidden interpretations matter
369
+
370
+ ### Example
371
+ ```json
372
+ {
373
+ "version": "1.0",
374
+ "artifact": "prototype.html",
375
+ "annotations": [
376
+ {
377
+ "id": "ann-load-rate-all-rule",
378
+ "target": {
379
+ "page": "power-dashboard",
380
+ "elementId": "load-rate-trend-chart",
381
+ "anchor": "right"
382
+ },
383
+ "type": "calculation",
384
+ "status": "confirmed",
385
+ "priority": "high",
386
+ "title": "All Load Rate calculation rule",
387
+ "content": "All Load Rate must be calculated as total power divided by total capacity. Average-based calculation is not allowed.",
388
+ "structured": {
389
+ "formula": "sum(room.power) / sum(room.capacity) * 100%",
390
+ "forbiddenFormula": "avg(room.loadRate)"
391
+ },
392
+ "implementationImpact": "Affects trend aggregation logic, KPI cards, and chart tooltip consistency.",
393
+ "sourceRefs": [
394
+ "Load Rate Trend > All view"
395
+ ]
396
+ }
397
+ ]
398
+ }
399
+ ```
400
+
401
+ ## `result.md` contract
402
+ Keep `result.md` dense, implementation-oriented, and in Chinese unless the task explicitly requires another language.
403
+
404
+ ### Must include
405
+ 1. `规则补充`
406
+ - implementation-critical product rules
407
+ - key business logic or calculation rules
408
+ - important state, permission, ordering, threshold, or edge-case notes
409
+
410
+ 2. `原型未完全表达的点`
411
+ - rules or branches not fully captured by direct interaction
412
+ - simulations, merges, or approximations that must not be mistaken as final behavior
413
+ - open points that materially affect implementation understanding
414
+
415
+ 3. `闭环判定`
416
+ - final closure level: `Prototype Complete` / `Prototype Partial` / `Analysis Only`
417
+ - the strongest reviewer-backed reason for that closure
418
+ - if closure is not `Prototype Complete`, the top remaining blocker or downgrade reason
419
+
420
+ ### Must not do
421
+ - do not use `result.md` as a delivery index
422
+ - do not carry `需求文档` or artifact listing here
423
+ - do not add sections such as `产物文件`, `Artifacts`, `Artifact Files`, `需求文档`, or `产物`
424
+ - do not rewrite the PRD
425
+ - do not let prototype sample data appear indistinguishable from source fact
426
+ - do not dump full per-round review logs into `result.md`; keep detailed round logs in `review-log.md`
427
+
428
+ ### Template
429
+ ```md
430
+ # 规则补充
431
+ - Load Rate 的 All 口径必须使用 total power / total capacity,不能使用平均值。
432
+ - 历史范围下 KPI `Power` 的精确定义仍待确认,当前原型仅保留交互与展示位置。
433
+ - 权限不足时仅展示空状态说明,不在原型中模拟真实鉴权流程。
434
+
435
+ # 原型未完全表达的点
436
+ - Live 数据刷新为轻量模拟,不能视为真实刷新策略。
437
+ - Last 90 Days 的聚合粒度仍需产品确认后才能进入研发实现。
438
+
439
+ # 闭环判定
440
+ - Closure Level:Prototype Partial
441
+ - 判定依据:核心路径可评审,但历史场景下 Power 统计口径仍未明确,且部分规则仍以 annotation 承载。
442
+ - 主要剩余问题:历史 Power KPI 的精确定义仍是 Open Question。
443
+ ```
444
+
445
+ ## `review-log.md` contract
446
+ - purpose: preserve the reviewer subagent loop as an audit trail
447
+ - language may be concise Chinese with stable English verdict tokens
448
+ - one round entry per review pass
449
+ - minimum fields per round:
450
+ - `Round`
451
+ - `Reviewer Verdict`
452
+ - `Must Fix`
453
+ - `Can Ship As Partial`
454
+ - `Open Questions`
455
+ - `Builder Action`
456
+ - if the first review approves the prototype directly, still record that approval round
457
+
458
+ ### Template
459
+ ```md
460
+ # Review Log
461
+
462
+ ## Round 1
463
+ - Reviewer Verdict: Must Fix Before Complete
464
+ - Must Fix:
465
+ - `All Load Rate` 计算口径未在原型或 annotation 中明确。
466
+ - Can Ship As Partial:
467
+ - 历史 Power KPI 口径仍可暂时保留为开放问题。
468
+ - Open Questions:
469
+ - `Last 90 Days` 聚合粒度是否按月展示仍待确认。
470
+ - Builder Action:
471
+ - 新增 `All Load Rate` 计算口径 annotation,并调整结果说明。
472
+ ```
473
+
474
+ ## Final self-check
475
+ - review loop ran and did not exceed 3 rounds
476
+ - reviewer was explicitly requested as a subagent, not implied
477
+ - final closure matches the last reviewer verdict
478
+ - every material key rule has a declared representation mode
479
+ - any remaining downgraded or missing behavior is disclosed in `result.md`
480
+ - `annotations.json` matches the actual annotation layer in `prototype.html`
481
+ - `result.md` contains no delivery-index or artifact-list sections
482
+ - source facts are preserved or deviations are explicitly declared
483
+ - sample data is not presented as source truth
@@ -0,0 +1,13 @@
1
+ {
2
+ "id": "pm",
3
+ "triageRules": [
4
+ "ACCEPT.md"
5
+ ],
6
+ "executionRules": [
7
+ "ROLE.md",
8
+ "CONSTRAINTS.md",
9
+ "CONTEXT.md",
10
+ "STANDARD.md",
11
+ "EVOLUTION.md"
12
+ ]
13
+ }
@@ -3,6 +3,10 @@
3
3
  {
4
4
  "taskType": "bugfix",
5
5
  "dir": "bugfix"
6
+ },
7
+ {
8
+ "taskType": "pm",
9
+ "dir": "pm"
6
10
  }
7
11
  ]
8
12
  }