relay-dsh-plugin-manager 0.2.6 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project are documented here.
 
+## Unreleased
+
+## [0.3.0] - 2026-09-11
+
+### Changed
+
+- Combine the bounded Registry keyword pool with semantic-directory routing,
+  while preserving exact identifiers, rejecting snapshot mismatch, and safely
+  falling back when either read-only route fails.
+- Replace fixed-count presentation guidance with a smallest-complete-answer
+  contract: cover every distinct solution role and materially different
+  approach, group alternatives, and omit unrelated or duplicate projects.
+- Add the read-only `search_roles` and `assess_solution` workflow. The Agent
+  supplies a bounded role decomposition, the manager searches each role through
+  the inspected provider path, and a short-lived draft becomes complete only
+  after reviewed selections cover every required role with no ambiguity.
+
+### Added
+
+- Add a versioned bilingual search acceptance suite that compares keyword and
+  hybrid results for required-role coverage, reviewed false positives,
+  duplicate project identities, and exact package/repository queries. Recall
+  and reciprocal-rank values remain diagnostic rather than release gates.
+- Add a versioned task-solution fixture covering required versus optional
+  roles, incomplete and ambiguous tasks, shared multi-role plugins, distinct
+  alternatives, invalid cross-role selections, and draft expiry.
+- Add an opt-in bilingual live-model role-planning acceptance command with a
+  strict output schema and deterministic checks for minimal role count,
+  semantic coverage, optionality, ambiguity, and invented near-neighbours.
+
 ## [0.2.6] - 2026-09-07
 
 ### Added
@@ -157,3 +187,4 @@ All notable changes to this project are documented here.
 [0.1.1]: https://github.com/yangbobo2021/relay-dsh-plugin-manager/compare/v0.1.0...v0.1.1
 [0.2.3]: https://github.com/yangbobo2021/relay-dsh-plugin-manager/compare/v0.2.2...v0.2.3
 [0.2.6]: https://github.com/yangbobo2021/relay-dsh-plugin-manager/compare/v0.2.5...v0.2.6
+[0.3.0]: https://github.com/yangbobo2021/relay-dsh-plugin-manager/compare/v0.2.6...v0.3.0

package/README.md

@@ -147,10 +147,27 @@ This provider sends only the task query, inferred Chinese/English locale, and
 result limit. Returned candidates are
 always inspected locally through the same npm/GitHub flow before any plan can be
 created; Registry descriptions are untrusted text and cannot authorize changes.
-Search returns one relevance-ranked page (twenty candidates by default). The
-Agent is instructed to preserve that order and show every possibly relevant
-candidate instead of silently shortening the page to a fixed top five; results
-whose plugin purpose is clearly unrelated to the request are excluded.
+Search combines a bounded keyword pool with the active semantic directory, then
+locally inspects and merges npm/GitHub aliases by project identity. The Agent
+builds the smallest complete answer from the resulting pool: every distinct
+responsibility and materially different solution approach is covered, related
+alternatives are grouped by role, and clearly unrelated or duplicate candidates
+are omitted. It neither pads the answer to twenty nor silently cuts it to an
+arbitrary top count. Exact package and repository queries remain rank one.
+
+For a task with several responsibilities, the Agent uses a two-step read-only
+workflow. It first searches a minimal set of required and optional roles, then
+reviews each role group and asks the manager to assess only the selected direct
+solutions. The manager reports `complete` only when every required role has a
+reviewed candidate and no material user choice remains unresolved. One plugin
+may cover several roles without being repeated; distinct implementations remain
+grouped as primary and alternatives. These drafts expire after ten minutes and
+never authorize installation.
+
+For monitoring that must survive a wait and continue the original conversation,
+the Agent searches source-specific state/event reading separately from durable
+waiting and Session resumption. A plugin that covers both responsibilities is
+still shown only once in the assessed solution.
 
 ## Part of Relay
 

package/README.zh.md

@@ -133,9 +133,20 @@ RELAY_PLUGIN_MANAGER_TELEMETRY_TEST=1 dsh web
 该 provider 只发送任务查询、推断出的中英文语言和结果数量。返回候选仍必须进入同一套本地 npm/GitHub
 检查流程，完成检查后才能生成计划；Registry 描述属于不可信文本，不能授权任何
 变更。
-搜索返回一页按相关性排序的结果（默认二十个）。Agent 必须保持该顺序并展示所有
-可能相关的候选，不能静默截成固定的前五个；插件用途明确与需求完全无关时必须
-省略。
+搜索会把有限的关键词候选池与当前语义目录结合，再通过本地检查按项目身份合并
+npm/GitHub 别名。Agent 从候选池中构造“最小完整答案”：覆盖任务需要的每一种职责和
+实质不同的解决思路，按角色组织可替代方案，并去掉明确无关或重复的候选。结果不会
+为了凑满二十个而填充，也不会静默截成任意固定数量；精确包名和仓库查询仍保持第一名。
+
+对于包含多项职责的任务，Agent 会执行两步只读流程：先拆成最少的必需/可选角色并
+分别搜索，再审查每个角色组，只把直接解决该职责的候选交给管理器评估。只有每个
+必需角色都有经过审查的候选、并且不存在未解决的重要用户选择时，结果才会标记为
+`complete`。同一插件可以承担多个角色而只展示一次；实质不同的实现会按主方案和
+替代方案分组。草案十分钟后过期，也不会产生任何安装授权。
+
+对于需要跨越等待并继续原对话的监控任务，Agent 会分别搜索“读取特定来源的状态/事件”
+和“持久等待并恢复 Session”两项职责。如果同一个插件同时覆盖两项职责，最终方案仍只
+展示一次，不会制造重复结果。
 
 ## 与 Relay 的关系
 

package/SPEC.md

@@ -50,8 +50,13 @@ service.
 | PM-023 | `plugin_manage confirm` owns its DSH question: it validates the token, expiry, and exact Session before asking; supplies a stable plan-specific id, visible plan detail, exact approve/decline options, and `plan-review` intent; and executes in that same tool call only for the exact single approve answer. Declines, malformed or unrelated answers, provider failure/cancellation, and cross-session attempts do not execute or consume a still-valid plan. Generic model-authored question results are never mutation authority. |
 | PM-024 | GitHub owner discovery recognizes `owner:<name>`, owner-only GitHub identities, `<name> DSH plugins`, and conservative bare identifiers containing digits. It sends a typed owner intent to providers, uses GitHub's exact owner qualifier, case-insensitively verifies returned ownership, and ranks verified owner matches first. Owner-only `inspect` fails with an actionable error directing callers to search. Every emitted repository identity is accepted by `inspect`; every recommended immutable source is accepted by `plan`. |
 | PM-025 | Register a read-only DSH Registry provider against `https://dsh-plugins.tech` by default, with an explicit `registryUrl: false` opt-out and HTTPS-only configuration override. Send only the task query, inferred Chinese/English locale and result limit; accept only source-level untrusted DiscoveryEntry records, convert their npm/GitHub descriptors into core-owned source types, and submit them to the same mandatory local inspection used by all providers. Registry responses cannot supply exact versions, approval, plans, installers, or profile state, and provider failure remains isolated. |
-| PM-026 | Return search candidates as one explicit, one-based relevance-ranked result page with a default and maximum size of 20. The model-facing contract requires the Agent to preserve rank order, surface every possibly relevant returned candidate, exclude candidates whose purpose is clearly unrelated, and MUST NOT silently reduce the remaining page to a fixed top-N. Ranking remains distinct from compatibility, security, or installation approval. |
+| PM-026 | Return search candidates as one explicit, one-based relevance-ranked pool with a default and maximum size of 20. The model-facing contract requires the Agent to produce the smallest complete answer: cover every distinct responsibility and materially different solution approach, group alternatives by role, exclude clearly unrelated candidates, merge npm/GitHub aliases of one project, and neither pad nor silently cut the answer to a fixed count. Ranking remains distinct from compatibility, security, or installation approval. |
 | PM-027 | Send default-on anonymous operational telemetry only to the Registry's canonical first-party HTTPS endpoint under schema `1.1.0`, with explicit `RELAY_PLUGIN_MANAGER_TELEMETRY=0` or `telemetry.enabled: false` opt-out. Events are limited to manager discovery/planning type and manager-executed install start/success/failure, including per-plugin batch outcomes. An operator-only `RELAY_PLUGIN_MANAGER_TELEMETRY_TEST=1` or `telemetry.test: true` mode adds only `is_test: true`; ordinary events omit the marker. Never send raw search text, conversation content, Profile state, installed inventory, paths, credentials, command output, error text, account identity, PostHog configuration, or client timestamps. Store only a stable random anonymous ID locally, create it lazily, and never let storage, validation, network, Registry, or analytics failure affect plugin management. |
+| PM-028 | Use the Registry keyword index as a bounded recall baseline and the active semantic directory as reranking evidence, with exact-identifier dominance, named-technology disambiguation, snapshot-consistency checks, and safe single-source fallback. A versioned bilingual scenario suite evaluates the post-inspection, deduplicated result pool for required-role coverage, forbidden near-neighbours, exact identifiers, and duplicate identities. Release comparison may not hide an individual hard-check regression behind aggregate improvement. |
+| PM-029 | For a task with multiple responsibilities, the Agent authors the smallest mutually distinct role plan. Every role has a stable id, user-facing label, focused search query, and required/optional status; material unresolved user choices are explicit ambiguities rather than guessed defaults. The manager validates bounds, text, uniqueness, and structure before searching. |
+| PM-030 | `search_roles` searches all validated roles concurrently through the normal inspected and identity-deduplicated provider path, preserves candidates in separate role groups, and creates a bounded, short-lived read-only draft. Candidate presence alone is `needs_review`, never proof of relevance or completeness. A required role with no candidate is already `incomplete`; any unresolved ambiguity is `ambiguous`. |
+| PM-031 | `assess_solution` accepts only candidate identities previously returned for their declared role. The first reviewed identity is the primary and additional identities are materially different alternatives selected by the Agent. One candidate selected for multiple roles appears once in the solution set with all role ids. The result is `complete` only when every required role has a reviewed selection and no ambiguity remains; missing optional roles do not block completeness. |
+| PM-032 | Treat cross-time observation as two coverage responsibilities: source-specific state/event reading and durable waiting/scheduling that resumes the original Session. The Agent keeps them as separate search roles even when one plugin may cover both, while the assessed solution still emits that shared plugin only once. An opt-in bilingual live-model suite must also preserve explicit optionality, surface material channel ambiguity, avoid invented near-neighbour roles, and produce the exact minimal role count for every reviewed case. |
 
 ## Command Grammar
 
@@ -69,15 +74,25 @@ behavior drift between direct commands and conversation.
 
 ### `plugin_discover`
 
-Read-only actions: `list`, `search`, `inspect`, `status`.
+Read-only actions: `list`, `search`, `search_roles`, `assess_solution`, `inspect`, `status`.
 
 `search` accepts capability text or GitHub owner forms such as
 `owner:yangbobo2021`. `inspect` accepts npm sources and all three GitHub
 repository forms from PM-007. An owner without a repository belongs to
 `search`, not `inspect`. Search defaults to a twenty-candidate ranked page. Each
-candidate carries its explicit display rank; the Agent presents all possibly
-relevant returned candidates in that order instead of silently selecting an
-arbitrary top five.
+candidate carries its explicit display rank and semantic-directory evidence
+when available. The Agent builds a minimal complete answer grouped by required
+role and materially different approach. It does not repeat source aliases, pad
+the answer, or silently impose an arbitrary top count.
+
+For a multi-responsibility task, `search_roles` receives an Agent-authored role
+plan and returns a short-lived grouped candidate draft. The Agent reviews each
+group and calls `assess_solution` with only direct solutions. Assessment rejects
+unknown roles and cross-role or duplicate selections, groups primary and
+alternative implementations, merges one plugin used by multiple roles, and
+reports explicit required-role coverage. If a material choice remains unknown,
+the draft and assessment remain `ambiguous` until the user resolves it and the
+Agent creates a new plan.
 
 ### `plugin_manage`
 
@@ -97,7 +112,10 @@ The manager owns inspection, immutable resolution, deduplication, ranking,
 confirmation, installation, rollback, activation, and restart.
 
 Provider scores are not globally comparable. The manager uses them only within
-one provider before deterministic cross-provider ordering.
+one provider before deterministic cross-provider ordering. Inside the Registry
+provider, bounded reciprocal-rank fusion combines keyword order with the active
+semantic-directory route; the keyword pool limits semantic drift and one
+additional challenger permits a directory-supported boundary correction.
 
 The `dsh-registry` provider defaults to `https://dsh-plugins.tech`. Plugin
 configuration `registryUrl` or environment variable `DSH_PLUGIN_REGISTRY_URL`

package/docs/acceptance/live-dsh-task-solution-2026-09-11.md

@@ -0,0 +1,61 @@
+# Live DSH Task-Solution Acceptance — 2026-09-11
+
+This record captures A-038: the task-solution workflow running through a real
+DSH Web Session, rather than a direct manager or model-only harness.
+
+## Frozen inputs
+
+- Candidate: `relay-dsh-plugin-manager@0.2.6`, packed and installed into a
+  disposable DSH Profile.
+- DSH upstream commit: `76fda729799fe9b3848dbe2c211d4b231032b81e`.
+- Agent backend: `gpt-5.6-luna`, high reasoning effort, through
+  `relay-dsh-plugin-codex`.
+- Registry export:
+  `discovery.composite.2026-09-06.v1-0-5.b92b985e31df`, 14,829 records.
+- Semantic directory: `plugin-directory-semantic-v3-18`.
+- Export file digest:
+  `sha256:d03f7dbe79a0a9cda3129a5945b08e5b97aebe6dd346736d3232c2a94bbe6e4a`.
+- Reconstructed DiscoverySnapshot canonical-entry digest:
+  `sha256:62f266eaab41de08419c854d7953952c1ca2983f8ef63d9719904c3d1c0997e6`.
+
+The two digests intentionally cover different byte representations. The first
+is the frozen JSONL export; the second is the Registry contract's canonical
+JSON-array digest. Snapshot id and entry count are checked before DSH starts,
+and the semantic directory must reference that exact snapshot id.
+
+## Scenario and result
+
+The user task was: keep watching a local program and send its result to Lark
+when it exits. The live Agent had to keep process-state reading, durable
+monitoring/session resumption, and Lark delivery as three distinct required
+responsibilities.
+
+The passing session made exactly two read-only calls:
+
+1. one `search_roles` call with three focused role queries and eight candidates
+   per role;
+2. one `assess_solution` call selecting one primary candidate per role.
+
+The assessed solution was complete, with three covered required roles, no
+missing roles, no alternatives, and three globally unique plugins:
+
+- `relay-dsh-plugin-monitor-process@0.1.1` for process-state reading;
+- `relay-dsh-plugin-monitors@0.3.1` for durable repeated checks and resumption;
+- `dsh-lark-channel@0.0.7` for Lark delivery.
+
+There were no failed discovery workflow calls, redundant `inspect` calls, or
+`plugin_manage` calls. Four candidates in the reviewed pools carried semantic
+directory evidence. Directory evidence is recorded as a metric rather than a
+per-selected-plugin gate: a correct resolved candidate may be supplied by the
+keyword side of hybrid retrieval when the broader directory path does not
+match a highly specific role query. Aggregate directory contribution and
+retrieval regression remain gated separately by A-035.
+
+Run the acceptance with:
+
+```sh
+npm run acceptance:live:dsh-task-solution
+```
+
+The command is read-only outside temporary files. It does not install into the
+source Profile and does not access or mutate the production Registry database.

package/docs/acceptance/search-scenarios-2026-09-11.md

@@ -0,0 +1,32 @@
+# Search Scenario Acceptance — 2026-09-11
+
+This record captures A-035 against the local production-sized Registry snapshot
+and semantic directory. It compares the former keyword strategy with the new
+hybrid candidate strategy after simulated identity inspection and project
+deduplication.
+
+- Registry origin: local read-only server at `127.0.0.1:4199`
+- Discovery entries: 14,829
+- Snapshot: `discovery.composite.2026-09-06.v1-0-5.b92b985e31df`
+- Directory: `plugin-directory-semantic-v3-18`
+- Suite: `plugin-manager-search.2026-09-11.v1`
+- Evaluations: 16 scenarios in Chinese and English, plus 3 exact queries
+
+| Gate | Keyword baseline | Hybrid candidate |
+| --- | ---: | ---: |
+| Scenario evaluations passed | 30 / 32 | 32 / 32 |
+| Required solution roles covered | 35 / 36 | 36 / 36 |
+| Reviewed forbidden neighbours suppressed | 7 / 8 | 8 / 8 |
+| Duplicate project identities | 0 | 0 |
+| Exact identifiers at required rank | 3 / 3 | 3 / 3 |
+| Individual hard-check regressions | — | 0 |
+
+The hybrid strategy passed every hard gate. Its recall at rank 10 was lower
+(`0.888889` versus `0.944444`) because some required roles moved to ranks 11–20,
+but no required role was lost from the bounded result pool. This rank metric is
+therefore retained for diagnosis and is not allowed to override complete role
+coverage or non-redundancy.
+
+The run used Registry identity simulation for the large scenario comparison;
+immutable npm/GitHub resolution is covered separately by unit, integration, and
+live Registry smoke acceptance. No production state was changed.

package/docs/acceptance/task-role-model-2026-09-11.md

@@ -0,0 +1,45 @@
+# Live Task-Role Model Acceptance — 2026-09-11
+
+This record captures A-037 for Agent-authored semantic role plans. It is
+separate from the deterministic A-036 runtime workflow: passing JSON validation
+or finding candidates is not accepted as proof that the plan is complete.
+
+The checked-in suite is
+`fixtures/evaluation/task-role-model-scenarios.v1.json`. Six tasks are evaluated
+in Chinese and English, for twelve independent plans. The model receives only
+the task text and role-planning rules; expected concepts and forbidden phrases
+remain evaluator-only.
+
+The hard checks require:
+
+1. The exact reviewed minimal role count.
+2. A distinct observed role for every expected semantic responsibility.
+3. Correct required versus explicitly optional status.
+4. No invented terminal or shell role for workspace file browsing.
+5. The exact ambiguity count and recognition of an unspecified notification
+   channel.
+6. Separate state/event-reading and durable Session-resumption coverage for
+   cross-time monitoring, even when one plugin can later satisfy both roles.
+
+Negative unit cases prove that merged/missing roles, wrong optionality, missing
+ambiguity, forbidden roles, and missing/duplicate/unexpected plans fail. The
+semantic matcher uses one-to-one maximum matching, so one observed role cannot
+claim two expected responsibilities.
+
+An opt-in run with `gpt-5.6-luna` at high reasoning effort produced these final
+results:
+
+| Check | Result |
+| --- | ---: |
+| Plans | 12 / 12 |
+| Exact role counts | 12 / 12 |
+| Distinct role concepts | 26 / 26 |
+| Required/optional flags | 26 / 26 |
+| Forbidden-role checks | 6 / 6 |
+| Exact ambiguity counts | 12 / 12 |
+| Ambiguity concepts | 2 / 2 |
+
+Run it with `npm run acceptance:live:task-roles`. The command uses an ephemeral,
+read-only Codex execution, writes no credentials, performs no plugin search or
+mutation, and only writes a full report when
+`DSH_TASK_ROLE_ACCEPTANCE_OUTPUT` is explicitly set.

package/docs/acceptance/task-solutions-2026-09-11.md

@@ -0,0 +1,42 @@
+# Task Solution Acceptance — 2026-09-11
+
+This record captures A-036 for the role-decomposition, grouped-search, and
+completeness-assessment workflow.
+
+The checked-in suite is
+`fixtures/evaluation/task-solution-scenarios.v1.json`. It fixes six reviewed
+examples:
+
+1. A three-role process-monitoring and Lark-delivery task is complete only after
+   all three required roles have a selected direct solution.
+2. Missing Lark delivery leaves the same task incomplete.
+3. Missing an explicitly optional dashboard does not block completeness; one
+   combined monitor may cover the state-reader and durable-resumption roles.
+4. One selected plugin can cover two roles while appearing once globally.
+5. Two materially different Lark implementations remain grouped as primary and
+   alternative, while an adjacent document plugin is not selected.
+6. An unresolved notification-channel choice keeps an otherwise covered task
+   ambiguous, while the same monitoring coverage boundary is preserved.
+
+Negative tests reject duplicate role plans, duplicate labels or focused
+queries, ambiguity ids that collide with role ids, candidates selected for the
+wrong role, repeated candidate selection, and expired drafts.
+
+The runtime guarantees are exercised at three layers:
+
+- pure `TaskSolutionStore` scenario tests;
+- `PluginManager` integration with independent per-role provider queries and
+  inspected candidates;
+- the real DSH `ToolRuntime` schema and execution path for `search_roles`
+  followed by `assess_solution`.
+
+The semantic role plan is intentionally Agent-authored: the manager does not
+pretend that candidate presence proves relevance. It validates the structure,
+preserves candidate boundaries, and computes completeness only from the
+Agent-reviewed selections. Model-specific role-decomposition quality is
+evaluated separately by A-037 so this deterministic runtime fixture remains a
+release gate.
+
+The full verification passed with 120 automated tests, package build, and local
+DSH package installation against upstream commit
+`76fda729799fe9b3848dbe2c211d4b231032b81e`. No production state was changed.

package/docs/acceptance.md

@@ -38,8 +38,12 @@ This matrix is the release contract. Tests name the relevant `PM-*` ids.
 | A-030 owner-only inspect forms return actionable search guidance while malformed, unsafe, and non-GitHub inputs remain rejected without weakening source validation | PM-018, PM-024 | source/manager negative unit |
 | A-031 search results feed one immutable multi-install plan through the real DSH tool and user-question registries; no mutation starts before one exact UI approval, then child installs execute serially and approval replay is rejected | PM-002, PM-005, PM-009, PM-010, PM-015, PM-023, PM-024 | combined host/tool/search/question/manager integration |
 | A-032 The default formal Registry searches at least 3,000 source records for Chinese task text, English task text, exact plugin names and an honest empty result; every returned source is locally inspected to an immutable npm version or GitHub commit, while Registry authority remains source-only, untrusted, non-recommending and non-approving | PM-005, PM-006, PM-025 | provider/unit/host integration tests plus `npm run acceptance:live:registry` |
-| A-033 Search defaults to a complete twenty-candidate result page, assigns stable one-based display ranks after merge and deduplication, and tells the Agent to exclude clearly unrelated purposes while surfacing every remaining possibly relevant candidate without silent fixed-count truncation | PM-005, PM-026 | search orchestration and conversation-tool contract unit tests plus Agent answer acceptance |
+| A-033 Search defaults to a bounded twenty-candidate pool, assigns stable one-based display ranks after merge and deduplication, and tells the Agent to produce the smallest complete answer: cover each distinct responsibility and materially different approach, group alternatives by role, exclude clearly unrelated or duplicate solutions, and neither pad nor silently truncate to a fixed count | PM-005, PM-026 | search orchestration and conversation-tool contract unit tests plus Agent answer acceptance |
 | A-034 Default manager actions send only schema-valid anonymous envelopes to the first-party Registry endpoint, reuse a lazily created random ID, record each attempted batch install outcome, and continue normally through storage or delivery failure; explicit opt-out creates no ID and makes no telemetry request | PM-027 | telemetry unit tests + manager integration event assertions + Registry endpoint contract and end-to-end PostHog verification |
+| A-035 A versioned bilingual scenario suite covers named-backend and adjacent-capability confusion, compositions, third-party npm and GitHub-only plugins, exact identifiers, and post-inspection alias deduplication. The hybrid Registry candidate pool must cover every required role, suppress reviewed forbidden neighbours, preserve exact rank one, contain no duplicate project identity, and report every individual regression against the keyword baseline | PM-005, PM-006, PM-025, PM-026, PM-028 | scenario schema/evaluator unit tests plus `npm run acceptance:live:registry` against one frozen Registry snapshot and directory version |
+| A-036 A versioned task-solution suite covers a complete three-role composition, missing required and optional roles, one plugin covering multiple roles, distinct alternatives, and unresolved ambiguity. Tool integration must search each role, preserve role groups, reject duplicate/cross-role/expired selection, globally deduplicate selected solutions, and report complete only after reviewed coverage of every required role | PM-005, PM-026, PM-029, PM-030, PM-031 | checked-in task-solution fixture, store unit tests, conversation schema test, and manager integration test |
+| A-037 A separate bilingual live-model suite gives the model only user tasks, then deterministically checks exact minimal role count, distinct semantic coverage, required/optional flags, forbidden invented roles, and unresolved ambiguity. Cross-time monitoring must retain separate state-reader and durable-resumption coverage even when one selected plugin can satisfy both | PM-029, PM-031, PM-032 | checked-in task-role fixture and output schema, positive/negative evaluator tests, plus opt-in `npm run acceptance:live:task-roles` |
+| A-038 A real disposable DSH Web conversation uses the packed release candidate and a snapshot-aligned local Registry to perform one `search_roles` and one `assess_solution` for a three-capability task. The gate requires exact role coverage, one reviewed gold solution per role, global non-duplication, no workflow-call errors, no redundant inspection, and no mutation; directory contribution remains an observed metric because final relevance can validly come from keyword evidence | PM-005, PM-025, PM-026, PM-029-PM-032 | pure evaluator tests plus opt-in `npm run acceptance:live:dsh-task-solution` against frozen Registry export `discovery.composite.2026-09-06.v1-0-5.b92b985e31df` and directory `plugin-directory-semantic-v3-18` |
 
 ## Test Layers
 

package/docs/technical-design.md

@@ -22,10 +22,10 @@ natural language --------------------------+
                                             v
                                     PluginManager core
                           +-----------------+------------------+
-                          |                                    |
-                   PluginSearchRuntime                  Operation runtime
-                          |                                    |
-                built-in / external providers         official DSH CLI
+                          |                 |                  |
+                   PluginSearchRuntime  TaskSolutionStore  Operation runtime
+                          |                 |                  |
+                built-in / external providers          official DSH CLI
                                                                |
                                           postcondition -> hot activation
                                                                |
@@ -115,6 +115,59 @@ directly into `inspect`; `recommendedSource` is immutable and can flow directly
 into `plan`. Owner-only identities fail inspection with guidance to use owner
 search instead of falling through to npm validation.
 
+The built-in Registry provider requests a bounded keyword challenger pool and
+the active semantic-directory route concurrently. It validates both responses
+as source-only, non-authorizing discovery data and refuses to combine different
+snapshot ids. Reciprocal-rank fusion lets directory evidence rerank the bounded
+keyword candidates; directory-only candidates are used only when keyword search
+fails, which limits semantic sibling flooding. Exact identifiers and explicit
+technology terms receive deterministic priority. If one route fails, the other
+remains usable; if both fail, the provider reports an isolated provider error.
+
+The final model-facing pool carries canonical path and matched-capability
+evidence. The Agent contract asks for the smallest complete answer rather than a
+fixed top-N: cover every required role and materially different approach, group
+alternatives by role, exclude unrelated rows, and never repeat aliases of one
+project. A checked-in bilingual scenario suite tests role coverage, reviewed
+near-neighbour exclusions, duplicate project identities, and exact identifiers
+against the keyword baseline. Rank metrics remain diagnostics and cannot mask
+either a missed role or a hard-check regression.
+
+## Task Solution Workflow
+
+Complex task discovery is deliberately a two-step read-only protocol. The DSH
+Agent provides semantic judgment while the manager owns structural enforcement:
+
+1. The Agent decomposes the user task into the smallest mutually distinct set
+   of required and explicitly optional responsibilities. It supplies a focused
+   query per role and records any material unresolved choice as an ambiguity.
+   A cross-time observation keeps source-specific state/event reading separate
+   from durable waiting/scheduling and Session resumption. This is a coverage
+   boundary rather than a plugin-count assumption: one plugin may later satisfy
+   both roles.
+2. `search_roles` validates the plan and searches every role concurrently via
+   the same provider, inspection, and alias-deduplication path as ordinary
+   search. It stores at most 32 drafts for ten minutes and returns grouped
+   candidate summaries without claiming that presence proves relevance.
+3. The Agent reviews the groups, excludes adjacent or unrelated rows, retains
+   materially different alternatives, and calls `assess_solution` with the
+   selected candidate identities for each role.
+4. Assessment rejects identities that were not returned for that role and
+   duplicate selection rows. It emits one global solution record per identity,
+   annotates a shared solution with every role it covers, and computes required
+   and optional coverage. Missing required roles produce `incomplete`; any
+   unresolved ambiguity produces `ambiguous`; only reviewed full required-role
+   coverage with no ambiguity produces `complete`.
+
+Draft ids confer no mutation authority. Installation still requires the normal
+immutable inspection, plan, and separate confirmation path.
+
+Role-plan semantics have a separate opt-in live-model gate. The model sees only
+the bilingual tasks and a JSON output contract; a deterministic evaluator then
+checks reviewed semantic concepts using distinct matching, exact role and
+ambiguity counts, required/optional flags, and forbidden invented roles. The
+live gate never searches, installs, or changes a Profile.
+
 No provider callback participates after discovery.
 
 ## Confirmation Plans

package/lib/errors-BGx4K2uq.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors-BGx4K2uq.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["export type PluginManagerErrorCode =\n  | 'INVALID_SOURCE'\n  | 'INVALID_NPM_SPEC'\n  | 'INVALID_NPM_VERSION'\n  | 'INVALID_GITHUB_SPEC'\n  | 'INVALID_GITHUB_REF'\n  | 'GITHUB_OWNER_REQUIRES_SEARCH'\n  | 'IMMUTABLE_SOURCE_REQUIRED'\n  | 'NETWORK_ERROR'\n  | 'SOURCE_HTTP_ERROR'\n  | 'INVALID_SOURCE_METADATA'\n  | 'INVALID_PLUGIN_MANIFEST'\n  | 'NOT_DSH_PLUGIN'\n  | 'PACKAGE_NAME_MISMATCH'\n  | 'NPM_INTEGRITY_MISSING'\n  | 'INVALID_SEARCH_QUERY'\n  | 'INVALID_ACTION'\n  | 'INVALID_BATCH'\n  | 'DUPLICATE_SEARCH_PROVIDER'\n  | 'PROFILE_READ_FAILED'\n  | 'PROFILE_WRITE_FAILED'\n  | 'PLUGIN_NOT_INSTALLED'\n  | 'PLUGIN_ALREADY_INSTALLED'\n  | 'ENABLEMENT_UNSUPPORTED'\n  | 'ENABLEMENT_CONFLICT'\n  | 'PROTECTED_PLUGIN'\n  | 'CONFIRMATION_REQUIRED'\n  | 'CONFIRMATION_INVALID'\n  | 'CONFIRMATION_EXPIRED'\n  | 'CONFIRMATION_REPLAYED'\n  | 'PLAN_STALE'\n  | 'OPERATION_NOT_FOUND'\n  | 'DSH_COMMAND_FAILED'\n  | 'BATCH_INSTALL_FAILED'\n  | 'POSTCONDITION_FAILED'\n  | 'RESTART_UNAVAILABLE'\n\nexport class PluginManagerError extends Error {\n  readonly code: PluginManagerErrorCode\n  readonly details?: Record<string, unknown>\n\n  constructor(code: PluginManagerErrorCode, message: string, details?: Record<string, unknown>) {\n    super(message)\n    this.name = 'PluginManagerError'\n    this.code = code\n    this.details = details\n  }\n}\n\nexport function fail(\n  code: PluginManagerErrorCode,\n  message: string,\n  details?: Record<string, unknown>,\n): never {\n  throw new PluginManagerError(code, message, details)\n}\n"],"mappings":";AAqCA,IAAa,qBAAb,cAAwC,MAAM;CAC5C;CACA;CAEA,YAAY,MAA8B,SAAiB,SAAmC;EAC5F,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,UAAU;CACjB;AACF;AAEA,SAAgB,KACd,MACA,SACA,SACO;CACP,MAAM,IAAI,mBAAmB,MAAM,SAAS,OAAO;AACrD"}
+{"version":3,"file":"errors-BGx4K2uq.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["export type PluginManagerErrorCode =\n  | 'INVALID_SOURCE'\n  | 'INVALID_NPM_SPEC'\n  | 'INVALID_NPM_VERSION'\n  | 'INVALID_GITHUB_SPEC'\n  | 'INVALID_GITHUB_REF'\n  | 'GITHUB_OWNER_REQUIRES_SEARCH'\n  | 'IMMUTABLE_SOURCE_REQUIRED'\n  | 'NETWORK_ERROR'\n  | 'SOURCE_HTTP_ERROR'\n  | 'INVALID_SOURCE_METADATA'\n  | 'INVALID_PLUGIN_MANIFEST'\n  | 'NOT_DSH_PLUGIN'\n  | 'PACKAGE_NAME_MISMATCH'\n  | 'NPM_INTEGRITY_MISSING'\n  | 'INVALID_SEARCH_QUERY'\n  | 'INVALID_ACTION'\n  | 'INVALID_BATCH'\n  | 'DUPLICATE_SEARCH_PROVIDER'\n  | 'PROFILE_READ_FAILED'\n  | 'PROFILE_WRITE_FAILED'\n  | 'PLUGIN_NOT_INSTALLED'\n  | 'PLUGIN_ALREADY_INSTALLED'\n  | 'ENABLEMENT_UNSUPPORTED'\n  | 'ENABLEMENT_CONFLICT'\n  | 'PROTECTED_PLUGIN'\n  | 'CONFIRMATION_REQUIRED'\n  | 'CONFIRMATION_INVALID'\n  | 'CONFIRMATION_EXPIRED'\n  | 'CONFIRMATION_REPLAYED'\n  | 'PLAN_STALE'\n  | 'OPERATION_NOT_FOUND'\n  | 'DSH_COMMAND_FAILED'\n  | 'BATCH_INSTALL_FAILED'\n  | 'POSTCONDITION_FAILED'\n  | 'RESTART_UNAVAILABLE'\n  | 'INVALID_TASK_SOLUTION'\n  | 'TASK_SOLUTION_NOT_FOUND'\n  | 'TASK_SOLUTION_EXPIRED'\n\nexport class PluginManagerError extends Error {\n  readonly code: PluginManagerErrorCode\n  readonly details?: Record<string, unknown>\n\n  constructor(code: PluginManagerErrorCode, message: string, details?: Record<string, unknown>) {\n    super(message)\n    this.name = 'PluginManagerError'\n    this.code = code\n    this.details = details\n  }\n}\n\nexport function fail(\n  code: PluginManagerErrorCode,\n  message: string,\n  details?: Record<string, unknown>,\n): never {\n  throw new PluginManagerError(code, message, details)\n}\n"],"mappings":";AAwCA,IAAa,qBAAb,cAAwC,MAAM;CAC5C;CACA;CAEA,YAAY,MAA8B,SAAiB,SAAmC;EAC5F,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,UAAU;CACjB;AACF;AAEA,SAAgB,KACd,MACA,SACA,SACO;CACP,MAAM,IAAI,mBAAmB,MAAM,SAAS,OAAO;AACrD"}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { a as PluginSearchRuntime, c as PluginSource, i as PluginSearchRequest, l as inspectPluginSource, n as PluginSearchMatch, o as FetchOptions, r as PluginSearchProvider, s as PluginInspection, t as PluginSearchCandidate } from "./search-runtime-DsmnI673.js";
+import { a as PluginSearchRuntime, c as PluginSource, i as PluginSearchRequest, l as inspectPluginSource, n as PluginSearchMatch, o as FetchOptions, r as PluginSearchProvider, s as PluginInspection, t as PluginSearchCandidate } from "./search-runtime-gzUZ5Yb3.js";
 import { spawn } from "node:child_process";
 import { Context } from "@deepseek-ai/cordis";
 
@@ -16,6 +16,50 @@ interface TelemetryConfig {
   test?: boolean;
 }
 //#endregion
+//#region src/search.d.ts
+interface SearchResultSource {
+  inspection: PluginInspection;
+  providers: string[];
+  evidence: string[];
+}
+interface SearchResult {
+  query: string;
+  candidates: Array<{
+    rank: number;
+    identity: string;
+    packageName: string;
+    description: string | null;
+    repository: string | null;
+    repositoryOwner: string | null;
+    providers: string[];
+    matchReasons: string[];
+    semanticMatches: Array<{
+      directoryVersion: string | null;
+      canonicalPathKey: string | null;
+      canonicalPath: string[];
+      matchedCapabilities: string[];
+      retrievalSources: string[];
+    }>;
+    sources: SearchResultSource[];
+    recommendedSource: string;
+  }>;
+  presentation: {
+    order: 'rank_ascending';
+    returnedCandidates: number;
+    requestedMaximum: number;
+    includeEveryDistinctRelevantSolution: true;
+    excludeClearlyIrrelevant: true;
+    deduplicateEquivalentSources: true;
+    padToRequestedMaximum: false;
+    silentTopNTruncation: false;
+  };
+  providerErrors: Array<{
+    provider: string;
+    error: string;
+  }>;
+  rejectedCandidates: number;
+}
+//#endregion
 //#region src/profile.d.ts
 interface PackageSurface {
   packageName: string;
@@ -225,6 +269,88 @@ declare class DshRestarter {
   };
 }
 //#endregion
+//#region src/task-solutions.d.ts
+interface TaskRoleInput {
+  id: string;
+  label: string;
+  query: string;
+  required?: boolean;
+}
+interface TaskRole {
+  id: string;
+  label: string;
+  query: string;
+  required: boolean;
+}
+interface TaskAmbiguityInput {
+  id: string;
+  question: string;
+  options: string[];
+}
+type TaskSolutionCandidate = Omit<SearchResult['candidates'][number], 'sources'>;
+interface TaskRoleSearchGroup extends TaskRole {
+  candidates: TaskSolutionCandidate[];
+  providerErrors: SearchResult['providerErrors'];
+  rejectedCandidates: number;
+}
+interface TaskSolutionDraft {
+  schemaVersion: '1.0.0';
+  solutionId: string;
+  task: string;
+  status: 'needs_review' | 'incomplete' | 'ambiguous';
+  createdAt: number;
+  expiresAt: number;
+  roles: TaskRoleSearchGroup[];
+  ambiguities: TaskAmbiguityInput[];
+}
+interface TaskRoleSelection {
+  roleId: string;
+  candidateIdentities: string[];
+}
+interface AssessedTaskRole extends TaskRole {
+  status: 'covered' | 'missing_required' | 'missing_optional';
+  primaryCandidateIdentity: string | null;
+  alternativeCandidateIdentities: string[];
+}
+interface TaskSolutionAssessment {
+  schemaVersion: '1.0.0';
+  solutionId: string;
+  task: string;
+  status: 'complete' | 'incomplete' | 'ambiguous';
+  roles: AssessedTaskRole[];
+  ambiguities: TaskAmbiguityInput[];
+  solutions: Array<TaskSolutionCandidate & {
+    roleIds: string[];
+  }>;
+  coverage: {
+    requiredRoles: number;
+    coveredRequiredRoles: number;
+    optionalRoles: number;
+    coveredOptionalRoles: number;
+    missingRequiredRoleIds: string[];
+    complete: boolean;
+  };
+}
+interface TaskSolutionStoreOptions {
+  now?: () => number;
+  id?: () => string;
+  ttlMs?: number;
+}
+declare class TaskSolutionStore {
+  private readonly now;
+  private readonly id;
+  private readonly ttlMs;
+  private readonly drafts;
+  constructor(options?: TaskSolutionStoreOptions);
+  create(input: {
+    task: string;
+    roles: TaskRoleInput[];
+    ambiguities?: TaskAmbiguityInput[];
+    searches: Record<string, SearchResult>;
+  }): TaskSolutionDraft;
+  assess(solutionIdValue: string, selectionValues: TaskRoleSelection[]): TaskSolutionAssessment;
+}
+//#endregion
 //#region src/manager.d.ts
 interface LoaderEntryLike {
   id?: string;
@@ -253,13 +379,19 @@ interface PluginManagerDependencies {
   fetchOptions?: Omit<FetchOptions, 'signal'>;
   hmrTimeoutMs?: number;
   telemetry?: Telemetry;
+  taskSolutions?: TaskSolutionStore;
 }
 interface DiscoverRequest {
-  action: 'list' | 'search' | 'inspect' | 'status';
+  action: 'list' | 'search' | 'search_roles' | 'assess_solution' | 'inspect' | 'status';
   query?: string;
   target?: string;
   operationId?: string;
   maxResults?: number;
+  maxResultsPerRole?: number;
+  roles?: TaskRoleInput[];
+  ambiguities?: TaskAmbiguityInput[];
+  solutionId?: string;
+  selections?: TaskRoleSelection[];
 }
 interface PlanRequest {
   operation: PlanAction;
@@ -317,6 +449,7 @@ declare class PluginManager {
   private readonly fetchOptions;
   private readonly hmrTimeoutMs;
   private readonly telemetry;
+  private readonly taskSolutions;
   constructor(dependencies: PluginManagerDependencies);
   private capture;
   private loaderEntries;
@@ -352,5 +485,5 @@ interface Config {
 }
 declare function apply(ctx: Context, config?: Config): void;
 //#endregion
-export { Config, DEFAULT_REGISTRY_ORIGIN, type DiscoverRequest, type InstallManyItemResult, type InstallManyItemStatus, type InstallManyResult, type MutationResult, type PlanRequest, type PluginInspection, PluginManager, type PluginSearchCandidate, type PluginSearchMatch, type PluginSearchProvider, type PluginSearchRequest, type PluginSource, type TelemetryConfig, apply, inject, name };
+export { Config, DEFAULT_REGISTRY_ORIGIN, type DiscoverRequest, type InstallManyItemResult, type InstallManyItemStatus, type InstallManyResult, type MutationResult, type PlanRequest, type PluginInspection, PluginManager, type PluginSearchCandidate, type PluginSearchMatch, type PluginSearchProvider, type PluginSearchRequest, type PluginSource, type TaskAmbiguityInput, type TaskRoleInput, type TaskRoleSelection, type TaskSolutionAssessment, type TaskSolutionDraft, type TelemetryConfig, apply, inject, name };
 //# sourceMappingURL=index.d.ts.map