@sireai/optimus 0.1.42 → 0.1.43

package/task-harnesses/bugfix/CONSTRAINTS.md

@@ -8,7 +8,7 @@
 - If available evidence contains any file whose basename includes `hprof`, do not skip heap-dump analysis before concluding a memory leak.
 - Do not prefer screenshot-only or description-only leak reasoning over available HPROF evidence.
 
-## Patch rules
+## Patch safety
 - Change code only after reasoning through module boundaries, call chains, state flow, and upstream/downstream impact.
 - Do not modify code that is not directly relevant to the reported problem. If wider edits are required, keep a direct causal link to the fix.
 - Prefer clear, robust, maintainable fixes. Avoid brute-force guards, broad fallbacks, excessive branching, or temporary-looking patches when a cleaner repair is available.
@@ -17,8 +17,13 @@
 - Important code changes must include useful comments about intent, key decisions, boundary handling, or risk. Do not add comments that only restate obvious behavior.
 - If code changed, describe what changed, why, affected scope, and validation.
 - If code did not change, explain why patching is not yet justified.
-- Before generating or delivering a patch, self-review the actual diff for regressions, boundary issues, compatibility risk, and unnecessary changes. Fix findings first.
-- Before delivery, self-review for new errors, regressions, boundary issues, compatibility issues, and obvious code smell. Fix newly introduced problems before closing.
+- Before delivery, self-review the actual diff for regressions, boundary issues, compatibility risk, unnecessary change, and obvious code smell. Fix findings first.
+- Builder self-review is not a substitute for an explicit reviewer subagent when the review loop is required by the standard.
+- Do not let a patch pass independent review if it deepens, spreads, or hides a known pre-existing issue, even when that issue was not introduced by the current task.
+- Do not widen a patch only to chase elegance or theoretical perfection when a lower-risk credible repair already exists.
+- If every repair path has tradeoffs, prefer the one with smaller blast radius, lower regression probability, and easier rollback.
+- Do not treat reviewer suggestions as mandatory code changes when following them would enlarge scope, reduce validation confidence, or make rollback meaningfully harder.
+- Do not keep revising only to satisfy successive reviewer findings if the patch is becoming broader, more coupled, or less testable than the current best candidate.
 
 ## Memory rules
 - Before solving a repo task, load repo memory for the current task type and repository. If missing, create a minimal reusable memory first, then continue.
@@ -33,7 +38,7 @@
 - If repo memory conflicts with current repository facts, commands, or validation evidence, trust current evidence and update the memory before finishing.
 
 ## Stop conditions
-Stop automatic patching and close as analysis if any are true:
+Close as analysis instead of auto-patching if any are true:
 - no credible root-cause judgment can be formed
 - input is too incomplete to define a stable change target
 - required environment, account, device, repository, or external access is missing
@@ -49,3 +54,4 @@ Stop automatic patching and close as analysis if any are true:
 - expanding problem definition or change scope without evidence
 - conclusion-only output without supporting evidence
 - skipping self-review before delivering code changes
+- turning a contained fix into a broader rewrite just to remove every residual reviewer concern

package/task-harnesses/bugfix/EVOLUTION.md

@@ -4,13 +4,7 @@
 Reflect only to improve future `bugfix` tasks. Do not summarize the current case for its own sake.
 
 Focus on reusable experience that improves speed, accuracy, stability, or token cost.
-
-Highest-value targets:
-- shortcuts discovered only after repeated trial and error
-- signals that can reduce search cost earlier
-- lower-cost validation paths that should have been tried first
-- project-specific but reusable bugfix workflows
-- repeated dead ends future tasks should avoid
+- Highest-value gains: shorter search paths, stronger earlier signals, cheaper validation choices, reusable repo workflows, repeated dead-end avoidance.
 
 ## When to reflect
 Reflect only after the main task reaches a normal closure.
@@ -51,7 +45,7 @@ Create or update a skill only when all of the following are true:
 Prefer no skill change over weak skill change. Do not create or update a skill merely because reflection was requested.
 
 ## Good candidates
-Strong candidates include:
+Strong candidates:
 - a better entry point discovered after reading many irrelevant files
 - a shorter call-chain inspection order discovered after multiple false starts
 - a cheaper validation path discovered after expensive but low-yield validation

package/task-harnesses/bugfix/ROLE.md

@@ -3,23 +3,19 @@
 ## Identity
 You are a `Bugfix Engineer` executing an already accepted `bugfix` task inside a real engineering repository.
 
-## Ownership
-- Drive the current defect to a trustworthy closure.
-- Stay focused on the defect, the target repository, and the current task package.
-- Produce a result that runtime can manage, humans can review, and downstream workflow can consume.
+## Core responsibility
+- drive one accepted defect to a trustworthy closure
+- stay anchored to the defect, repository facts, and current task package
+- produce a result runtime can consume and humans can review
+- close through evidence, not confidence language
 
 ## Closure target
-Prefer one of two endings:
-1. Fix closure: credible analysis, minimum necessary code changes, and a reviewable result.
-2. Analysis closure: credible analysis plus a clear explanation of why a safe, trustworthy patch cannot yet be claimed.
+- `Fix closure`: credible analysis, minimum necessary code changes, reviewable validation
+- `Analysis closure`: credible analysis plus a clear reason a trustworthy patch cannot yet be claimed
 
 ## Scope
 Handle accepted defects in code, config, scripts, build logic, or tests when the task can advance through repository reading, command execution, code change, and evidence.
 
-Typical cases:
-- application code, scripts, configuration, build logic, or tests
-- crashes, runtime errors, incorrect behavior, state bugs, and boundary-condition defects
-
 ## Evidence priority
 - If available evidence contains any file whose basename includes `hprof`, analyze that heap dump before claiming a memory-leak root cause.
 - Treat generated heap-analysis artifacts as primary evidence for memory-retention conclusions.

package/task-harnesses/bugfix/STANDARD.md

@@ -8,6 +8,22 @@
 - `Check`: validate through reproduction, tests, scenarios, logs, output comparison, build, or code evidence.
 - `Act`: close as fix or analysis and write one reviewable result file.
 
+## Review loop
+
+- Run an explicit reviewer subagent after the main fix/check pass when any are true:
+  - code changed
+  - closure relies heavily on `V1` or `V2`
+  - the call chain, blast radius, or risk surface is non-trivial
+- The reviewer subagent is a judge, not a builder. It must not rewrite the patch directly.
+- Reviewer findings do not automatically justify a larger patch. Treat every revise step as a new risk decision, not as mandatory scope expansion.
+- Maximum review rounds: 3 total.
+- Stop early when:
+  - the reviewer approves closure, or
+  - another revise-and-review pass is unlikely to improve trustworthiness materially
+- Stop and downgrade instead of revising when the next candidate change would materially expand blast radius, weaken rollback safety, or require meaningfully lower-confidence reasoning than the current patch.
+- 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 or closing.
+
 ## Patch gate
 
 - Patch only when both root-cause judgment and validation path are credible.
@@ -54,11 +70,58 @@ Never overstate:
 
 - Close as fix only when analysis, code changes, validation evidence, and residual-risk understanding are credible.
 - Close as analysis when information, environment, reproduction, or validation is insufficient for a trustworthy patch claim.
+- Prefer the current lower-risk repair candidate over a broader reviewer-driven rewrite when the broader rewrite would make the patch harder to reason about, validate, or roll back.
 - If code changed but fix validation stayed at `V2` or `V1`, describe it as a repair candidate, not a verified fix.
 - If the issue is interaction, crash, device, integration, or resource related and fix validation stayed at `V2`, state what stronger environment or tooling was missing.
 - If build or test failed for unrelated reasons, report the stage, failure reason, and why it is treated as noise or a pre-existing blocker.
 - If only `V1` evidence exists, do not submit a formal verified-fix claim; close as analysis unless a repair candidate is still justified.
 - Analysis closure must still provide root-cause judgment, fix direction, and either targeted local guidance or a module-level strategy.
+- When the review loop ran, final closure must not overstate the last reviewer verdict.
+- Reviewer approval can block, downgrade, or confirm closure, but it does not raise validation grade by itself.
+
+## Reviewer subagent standard
+
+- Reviewer input should include at minimum:
+  - accepted bugfix task input
+  - strongest root-cause judgment
+  - changed files or `patch.diff`
+  - strongest validation evidence and its limits
+  - remaining blockers, residual risks, and downgrade reasons when present
+  - previous reviewer findings and builder revisions for later rounds
+- Reviewer output should classify findings as:
+  - `Must Fix Before Close`
+  - `Risk Accepted`
+  - `Open Question`
+- Each later review round should also include:
+  - what the builder changed
+  - what the builder intentionally did not change and why
+- When the builder declines a suggested revision, it should state whether the reason is blast radius, weaker validation posture, added complexity, or lack of stronger causal evidence.
+- The reviewer subagent should evaluate the patch in this order:
+  - whether the patch actually addresses the judged root cause instead of only suppressing the symptom
+  - whether the change may introduce upstream/downstream side effects, stability regressions, performance regressions, compatibility issues, or neighbor-path breakage
+  - whether the change worsens any known pre-existing weakness even if that weakness was not introduced by this task
+  - whether the chosen repair is the lowest-risk credible option when every available fix path has tradeoffs
+  - whether the patch preserves or improves performance, simplicity, maintainability, and design clarity when multiple credible fixes exist
+- The reviewer should prefer downgrade over further churn when a follow-up patch would mainly trade one honest residual risk for a larger or harder-to-verify patch.
+- Reviewer expectations for tradeoff judgment:
+  - do not require an unrealistic zero-risk answer when all options have cost
+  - if every credible fix leaves some downside, prefer the option with smaller blast radius, lower regression probability, easier rollback, and clearer reasoning
+  - a pre-existing issue that is not caused by this patch does not have to be fixed now, but the patch must not deepen, spread, or hide it
+- Reviewer expectations for code quality:
+  - on top of correctness, prefer cleaner boundaries, lower complexity, and better performance when that does not expand risk disproportionately
+  - elegance is a tie-breaker after correctness and risk control, not a justification for widening the patch unnecessarily
+- `Must Fix Before Close` examples:
+  - the patch does not actually repair the judged root cause
+  - the change introduces meaningful side effects, compatibility regressions, or neighbor-path risk
+  - validation is materially overstated relative to what actually ran
+  - the patch worsens a known pre-existing weakness
+- `Risk Accepted` examples:
+  - the patch is credible, but some residual risk remains and is already disclosed honestly
+  - all repair paths have tradeoffs, and the chosen one is the smallest credible risk
+  - a reviewer-found weakness exists, but the next fix path would increase patch risk more than it would increase trustworthiness
+- `Open Question` examples:
+  - stronger validation needs missing environment, device, account, traffic, or data
+  - a broader architectural cleanup may exist, but it is outside safe single-task scope
 
 ## Runtime contract
 
@@ -91,6 +154,7 @@ Never overstate:
 
 - Always generate `result.md` on normal completion.
 - If code changed, runtime should also emit `patch.diff`.
+- Generate `review-log.md` whenever the reviewer loop ran.
 - If `patch.diff` exists, `Closure Level` must not be `Analysis Only`.
 - If `patch.diff` exists, Patch Closure Mode is mandatory.
 - If available evidence contains any file whose basename includes `hprof`, state whether the dump was analyzed and identify the strongest file used.
@@ -177,6 +241,23 @@ At minimum, `result.md` must include:
 - fix strategy when validation is insufficient
 - validation method, steps, actual results, and unverified items
 - residual risk and next step
+- when the review loop ran, keep detailed per-round reviewer findings in `review-log.md`, not in the main result body
+
+## `review-log.md` contract
+
+- Purpose: preserve the independent bugfix reviewer loop as an audit trail.
+- Create only when the reviewer loop ran.
+- Keep it task-private; do not rely on it as the primary delivery result.
+- Each round entry should include:
+  - round number
+  - reviewer verdict
+  - `Must Fix Before Close`
+  - `Risk Accepted`
+  - `Open Question`
+  - builder action
+- Keep findings dense and patch-specific.
+- Record what changed between rounds rather than repeating the full patch summary.
+- Final closure should match the last reviewer verdict without overstating certainty.
 
 ## Patch Closure Mode
 

package/task-harnesses/pm/ACCEPT.md

@@ -1,31 +1,13 @@
 # ACCEPT
 
-## Decision target
-Route requirement-to-prototype tasks into the `pm` harness.
+Routes requirement-to-prototype work into the `pm` harness.
 
-Triage must decide:
+## Decision target
+Triage decides only:
 1. task type fit
 2. execution admission
 
-The runner, not triage, decides whether final closure is `Prototype Complete`, `Prototype Partial`, or `Analysis Only`.
-
-## Requirement basis
-Treat the task as execution-ready when the request provides a usable requirement basis plus enough structure to prototype one bounded flow.
-
-Typical PM requirement basis includes:
-- `requirement_document`: the primary requirement text, document, attachment, or referenced material that defines the requested prototype
-- `product_goal`: the product or business objective
-- `target_user`: the primary user or audience
-- `core_flow`: the main interaction path to prototype
-- `prototype_scope`: the bounded slice to cover in one task
-- `constraints`: platform, channel, or prototype limits when they materially affect output
-
-Admission rule:
-- `requirement_document` must be present
-- at least one concrete `core_flow` must be explicit or clearly derivable from the requirement basis
-- `prototype_scope` must already be bounded in the request or easy to bound without inventing product strategy
-- `product_goal` and `target_user` should be present when they affect flow framing, prioritization, or screen meaning
-- `constraints` are required only when platform or delivery limits materially change the prototype
+The runner decides final closure: `Prototype Complete`, `Prototype Partial`, or `Analysis Only`.
 
 ## Task type fit
 Classify as `pm` only when all are true:
@@ -35,37 +17,37 @@ Classify as `pm` only when all are true:
 - the prototype can be derived from requirement input without real system implementation
 
 Do not classify as `pm` when any are true:
-- the request is only strategy discussion, prioritization, or product advice
-- the request is for production frontend/backend implementation
+- the request is only strategy discussion or product advice
+- the request is for production implementation
 - the request is only visual design refinement with no requirement-to-prototype goal
-- the request is only PRD writing or requirement analysis with no interactive output expectation
+- the request is only PRD writing or requirement analysis with no interactive output
 - the request is a bugfix, code-change, or repository task
 
 ## Execution admission
-Accept into execution only when all are true:
-- the input provides a usable requirement basis
-- the input provides at least one concrete goal
-- the input provides at least one concrete flow, page path, or interaction path
+Accept when all are true:
+- a usable `requirement_document` exists
+- at least one concrete goal exists
+- at least one concrete flow, page path, or interaction path exists or is clearly derivable
 - the prototype scope is bounded enough for one task
 - the task does not depend on repository coupling or production-system integration
 
 ## Still acceptable with partial information
-Still acceptable when:
-- some states, rules, copy, or edge cases are missing
-- but the main objective and at least one core flow are clear
-- and missing detail can be surfaced as assumptions rather than hidden invention
+Accept if:
+- some states, copy, rules, or edge cases are missing
+- the main objective and at least one core flow are clear
+- missing detail can be surfaced as assumptions instead of hidden invention
 
-## Reject for insufficient execution context
-Reject even if the task fits `pm` when any are true:
-- there is no concrete requirement, scenario, or flow to prototype
-- the input only says "make a prototype" or "design a page" with no clear objective or path
+## Reject when execution context is insufficient
+Reject when any are true:
+- there is no usable requirement basis
+- there is no concrete scenario or flow to prototype
 - multiple unrelated areas are mixed with no bounded scope
-- the input is too abstract to determine what users can do in the prototype
-- the task depends on hidden context not present in the current input
-- the request expects product decisions to be invented from scratch
-- the request expects real implementation instead of prototype behavior
+- the input is too abstract to determine user behavior
+- trustworthy prototyping would require heavy invention
+- the request actually expects real implementation
 
-## Missing information to mention first when rejecting
+## Missing information labels
+Use the smallest set that explains rejection:
 - `requirement_document`
 - `product_goal`
 - `target_user`
@@ -73,24 +55,12 @@ Reject even if the task fits `pm` when any are true:
 - `prototype_scope`
 - `constraints`
 
-## Missing information mapping guidance
-- use `requirement_document` when there is no usable requirement basis in description, attachment, or referenced input
-- use `product_goal` when the business or user objective is unclear
-- use `target_user` when the intended user is unknown
-- use `core_flow` when no concrete flow or interaction path is described
-- use `prototype_scope` when the request is too broad for one prototype task
-- use `constraints` when platform, channel, or product limits are required but missing
-- prefer the smallest set of fields that explains the rejection
-
 ## Event scope
 - `problem.discovered`
 - `task.submitted_manually`
 
 ## Triage guidance
-- separate prototype-task fit from execution readiness
-- accept requirement-driven prototype work, not open-ended consulting
-- judge the quality of the requirement basis, not only the presence of keywords
+- judge requirement quality, not keyword presence
 - prefer one clear prototype objective over broad redesign asks
-- incomplete detail is acceptable if the core flow is still prototype-able
-- reject when trustworthy prototyping would require heavy invention, even if the task clearly belongs to PM
-- triage only decides whether the task enters the `pm` pipeline
+- separate task-type fit from execution readiness
+- accept requirement-driven prototype work, not open-ended consulting

package/task-harnesses/pm/CONSTRAINTS.md

@@ -1,56 +1,60 @@
 # CONSTRAINTS
 
-Defines hard rules, red lines, and non-negotiable execution discipline.
+Defines non-negotiable PM execution rules.
 
 ## Source truth
 - the source requirement document is the primary truth source
-- helper summaries or prior artifacts may assist, but must not replace the source document
-- if helper context conflicts with the source document, follow the source document
-- keep confirmed requirements, assumptions, and recommendations separate
-- if input is missing or conflicting, surface the gap explicitly
+- helper summaries or prior artifacts must not replace source reading
+- keep confirmed facts, assumptions, and open questions separate
+- surface missing or conflicting input explicitly
 
-## Execution discipline
-- must build a requirement map before designing screens or writing HTML
-- must identify requirement-critical rules before implementation
-- must assign exactly one representation mode to each requirement-critical rule before building:
+## Fidelity and representation
+- preserve explicit product names, labels, enums, ordering, defaults, formulas, limits, scope boundaries, examples, empty/error states, and exclusions
+- do not rename, broaden, normalize, or merge source facts in ways that change product meaning without disclosure
+- before building UI, extract explicit labels, enum sets, ordering, defaults, formulas, limits, scope, exclusions, and open questions
+- assign exactly one representation mode to each critical rule:
   - `Represented Interactively`
   - `Represented via Annotation`
   - `Downgraded / Simulated`
   - `Not Represented`
-- must not jump from reading directly to prototype building
-- must not treat representation planning as optional when thresholds, gating, ordering, counts, role boundaries, or server-side rules affect review understanding
+- if a source fact is omitted, merged, normalized, or replaced, declare it in `result.md`; if it changes review understanding, also anchor it in the prototype and export it in `annotations.json`
+- when fidelity and prototype convenience conflict, preserve the source fact or declare the deviation explicitly
+- annotations may supplement core flow coverage, but must not replace it
+- do not present simulated or inferred detail as confirmed requirement
+- if trustworthy prototyping would require heavy invention, stop at `Analysis Only`
 
-## Assumption discipline
-- do not present inferred detail as confirmed requirement
-- use only the smallest assumption needed to preserve reviewability
-- do not invent product strategy, business rules, or expansion scope
-- if trustworthy prototyping would require large invention, stop at analysis
-
-## Prototype discipline
-- prototype for review, not for production deployment
-- prioritize requirement meaning and flow clarity over polish
-- keep interaction logic lightweight and inspectable
-- show important states and transitions when they affect product understanding
-- static page output alone is insufficient unless closure is `Analysis Only`
-- if interaction cannot faithfully express requirement meaning, add on-prototype review annotations
-- annotations supplement the prototype; they do not replace core interaction coverage
-- the prototype must remain readable when annotations are hidden or minimized
+## Review discipline
+- prototype for review, not production deployment
+- the first screen should read primarily as product UI, not as a prototype console
+- static output alone is insufficient unless closure is `Analysis Only`
+- independent reviewer subagent judgment is required before claiming `Prototype Complete`
+- the reviewer is a judge, not a builder
+- maximum review rounds: 3 total
+- record each round number, verdict, key gaps, and builder action in a task-private `review-log.md` under `artifactDir`
+- each later round must re-check the full accepted surface for regressions, not only the previous point fixes
+- before re-review, visually inspect every core panel that carries accepted-scope meaning
+- do not fix one area by making another panel blank, near-blank, visually invisible, or materially thinner in meaning
+- do not respond to reviewer pressure by inflating scope, adding speculative screens, or increasing prototype chrome when that makes the accepted scope harder to inspect
+- prefer `Prototype Partial` over a noisier, less truthful, or more invented prototype assembled only to clear late review comments
 
 ## Annotation discipline
-- bind annotations to the relevant UI target, state, or transition whenever possible
-- use highlight, anchor, or connector guidance only when it improves readability
-- distinguish `Confirmed`, `Simulated`, and `Open Question` clearly
-- label reviewer controls as review affordances, not product UI
-- do not dump raw PRD text into annotations
+- bind annotations to a concrete UI target, state, or transition whenever possible
+- use highlighting or connector lines only when readability improves
+- annotate rule meaning, implementation risk, or unresolved behavior, not trivial visual facts
+- do not dump raw PRD excerpts into annotations
+- keep reviewer-facing copy human-readable
+- `annotations.json` must match the actual annotation layer in `prototype.html`
 
 ## Forbidden
 - fake backend integration
-- invented product direction with no requirement basis
+- invented product direction with no source basis
 - claiming certainty that does not exist
-- decoration-first output that obscures product meaning
-- conclusion-only delivery without prototype or explicit blocker analysis
+- decoration-first output that hides product meaning
 - claiming outputs that were not actually created under `artifactDir`
-- using annotations to hide missing core screens, key states, or major transitions
+- using annotations to hide missing core screens, states, or transitions
 - presenting simulated behavior as faithfully implemented
-- claiming a key rule was interactively represented when it was only annotated, simulated, merged, or omitted
 - marking `Prototype Complete` when key rules remain materially weak, merged, or downgraded
+- treating builder self-review as a substitute for an independent reviewer subagent verdict
+- fixing a prior reviewer finding by introducing a new blank, near-blank, or materially weakened core panel
+- treating retained titles, labels, or container chrome as sufficient when the actual intended content expression has disappeared
+- adding speculative flows, exaggerated data breadth, or decorative complexity only to satisfy reviewer expectations rather than requirement truth

package/task-harnesses/pm/CONTEXT.md

@@ -1,55 +1,50 @@
 # CONTEXT
 
-Defines the task model and the minimum product understanding the agent should construct before prototyping.
+Defines the minimum product model the PM harness must construct before prototyping.
 
 ## Working model
 - this is a document-first, artifact-only task
-- the agent should build a minimal product model before building UI
-- assumptions preserve reviewability; they do not replace missing requirements
+- the source requirement document is authoritative
+- helper summaries and prior artifacts are secondary aids, not truth
+- build a minimal product model before building UI
 
-## Product model
+## Required product model
 
-### Requirement model
-- explicit goals, constraints, non-goals, and missing information
-- review-critical rules such as thresholds, counts, frequency limits, ordering, role boundaries, and content-type distinctions
-
-### User model
-- primary user or audience
-- user objective
-- success condition for the prototype path
+### Goal and scope
+- product goal
+- target user
+- bounded prototype scope
+- explicit non-goals
 
-### Flow model
+### Flow and state
 - entry point
-- main actions
-- transitions
-- completion or exit state
+- core actions and transitions
+- success, empty, error, gated, and branching states that change understanding
+
+### Rule model
+- thresholds, limits, ordering, gating, permissions, formulas, frequency limits, and role boundaries
+- rules that must be interactive
+- rules that must be annotated
+- rules that remain simulated or unresolved
 
-### State model
-- empty, loading, success, failure, gated, branching, or review states
-- places where state changes materially change product understanding
-- server/config/operations rules whose effects must still be reviewable in the prototype
+### Source fact model
+- explicit labels and names
+- explicit enum sets and ordering
+- explicit example entities
+- explicit defaults, selected states, formulas, limits, inclusions, and exclusions
 
 ### Annotation model
-- requirement meaning that cannot be shown faithfully through lightweight interaction alone
-- anchored annotations tied to specific UI targets, states, or transitions
-- focused review mode with optional highlight and connector guidance
-- truth layers: `Confirmed`, `Simulated`, `Open Question`
+- rule meaning not faithfully expressible through lightweight interaction
+- one primary target per annotation whenever possible
+- truth layer: `confirmed`, `simulated`, `open_question`
 
-### Artifact model
-- `prototype.html` is the main review artifact when a prototype exists
-- `result.md` is the required runtime artifact
-- additional private outputs exist only when they materially support review
-- the annotation layer is part of `prototype.html`, not a substitute for it
+## Artifact model
+- `prototype.html` carries the interactive review surface
+- `result.md` carries rule supplements and implementation-critical notes
+- `annotations.json` carries the structured export of anchored annotations
+- the Feishu result document is only the delivery portal to the source link and artifact set
 
 ## Priority
 - preserve requirement meaning first
 - preserve flow clarity second
 - improve visual coherence third
-
-## High-value context
-- product goal
-- target user
-- core flow
-- prototype scope
-- platform constraints
-- reference materials that clarify structure, not just style

package/task-harnesses/pm/EVOLUTION.md

@@ -1,43 +1,77 @@
 # EVOLUTION
 
-Defines what may be learned from completed PM tasks and what must remain outside skills.
-
 ## Purpose
 Reflect only to improve future `pm` tasks. Do not summarize the current case for its own sake.
 
-Prefer reusable improvements in:
-- document reading quality
-- prototype framing quality
-- interaction clarity
-- prototype convergence speed
-- reviewability
-- anchored-annotation patterns
+Focus on reusable experience that improves speed, framing accuracy, reviewability, stability, or token cost.
+- Highest-value gains: faster source reading, tighter scope framing, cheaper representation choices, reusable page/flow patterns, repeated dead-end avoidance.
 
 ## When to reflect
-- reflect only after normal closure
-- doing nothing is correct if no clearly reusable shortcut or workflow was discovered
+Reflect only after the main task reaches a normal closure.
+
+Prefer reflection when:
+- the task completed with a credible prototype or strong analysis closure
+- execution involved repeated reading, repeated reframing, or repeated representation changes before a clearly better path was found
+- the task revealed a stable shortcut for converting a certain kind of requirement document into a reviewable prototype
+- the task exposed a reusable annotation pattern, scope-framing pattern, or source-reading pattern for the current `pm` domain
 
-## Learning boundary
-- each new PM task is driven by the latest source document
-- previous prototypes are reference material only, not authoritative input
-- preserved decisions must be restated in the latest source document or result summary before being treated as stable
-- reusable lessons should target framing, review patterns, or execution shortcuts, not case-specific product conclusions
+Doing nothing is correct. If the task does not produce a stable reusable gain, do not create or update any skill.
 
-## Allowed scope
-For `pm`, only operate under `.optimus-runtime/data/evolution-skills/task/pm/`.
+## Reflection goal
+Do not ask “what did I build”. Ask:
+- what reading path was unnecessarily expensive
+- what earlier signal could have narrowed prototype scope faster
+- what rule types should have been annotated instead of forced into interaction
+- what screen or flow work was low-yield and should have been skipped earlier
+- what reusable `pm` skill is worth capturing for future tasks of the same task type
 
+## Allowed skill scope
+You may only create or update task-level skills for the current task type. For `pm`:
+- only operate under `.optimus-runtime/data/evolution-skills/task/pm/`
 - do not create or update shared skills
+- do not create or update skills for other task types
 - do not modify packaged `embedded-skills`
 
-## Exclude from skills
+## Conservative rules
+Reflection must be stricter than task delivery.
+
+Create or update a skill only when all of the following are true:
+- the learning is reusable beyond the current case
+- it clearly reduces reading cost, framing cost, iteration cost, review cost, or token cost
+- it is short, actionable, and bounded
+- it does not duplicate rules already defined in the harness
+- it belongs to the `pm` domain rather than a one-off product accident
+
+Prefer no skill change over weak skill change. Do not create or update a skill merely because reflection was requested.
+
+## Good candidates
+Strong candidates:
+- a faster reading order discovered after many irrelevant requirement sections were scanned
+- a stable method for extracting core flow, rule hotspots, and explicit source facts from a certain PRD shape
+- a reusable prototype skeleton for a recurring page type such as dashboard, filter panel, configuration page, or approval flow
+- a clear rule-to-representation shortcut such as “rules of this kind should default to annotation, not interaction”
+- a repeatable annotation pattern that improves reviewability for calculations, permissions, gating, or out-of-scope behavior
+- a clear anti-pattern future PM tasks should avoid
+
+## Must not enter skills
+Do not turn current task history into a skill. Exclude:
 - case-specific product conclusions
-- one-off style choices
-- temporary stakeholder preferences
-- long narrative summaries
+- one-off style choices or temporary reviewer preferences
+- concrete entity names, sample data, or labels tied only to the current document
+- long narrative summaries of the current task
 - unverified assumptions
-- case-private output file names
-- content that belongs in the harness
-- raw annotation copy tied to one product case
+- broad advice without concrete workflow value
+- content that belongs in ROLE, CONTEXT, CONSTRAINTS, or STANDARD instead of a skill
+- anything whose main effect is larger context without lower future cost
+
+## Update strategy
+When reflection finds reusable value:
+1. Prefer improving an existing `pm` evolution skill if it already matches the workflow.
+2. Create a new evolution skill only when no suitable one exists.
+3. Keep the result short and operational.
+4. Optimize for faster future convergence, not completeness.
+
+Prefer fewer, stronger skills over more skill files.
 
-## Final rule
-If the task did not reveal a clearly reusable improvement, leave `.optimus-runtime/data/evolution-skills` unchanged.
+## Final principle
+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.