@yugoo-design/companion 0.1.0-beta.10 → 0.1.0-beta.12

package/README.md

@@ -1,6 +1,6 @@
 # Yugoo Design Companion — beta
 
-Package: `@yugoo-design/companion@0.1.0-beta.10`.
+Package: `@yugoo-design/companion@0.1.0-beta.12`.
 
 Yugoo Design (语构设计系统) is an interactive design plugin for native Agent Hosts.
 It combines domain methods, Design Projects, versioned Design Files and shared
@@ -21,7 +21,7 @@ selected beta to the exact version and integrity before acquisition; keep the
 previous installed version available during updates. Do not substitute `latest`.
 
 ```sh
-ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --ignore-scripts=false --save-exact @yugoo-design/companion@0.1.0-beta.10 --registry=https://registry.npmjs.org
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --ignore-scripts=false --save-exact @yugoo-design/companion@0.1.0-beta.12 --registry=https://registry.npmjs.org
 npx --no-install design-system --help
 ```
 
@@ -38,7 +38,7 @@ allowBuilds:
 ```
 
 ```sh
-ONNXRUNTIME_NODE_INSTALL_CUDA=skip pnpm add --save-exact @yugoo-design/companion@0.1.0-beta.10 --registry=https://registry.npmjs.org
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip pnpm add --save-exact @yugoo-design/companion@0.1.0-beta.12 --registry=https://registry.npmjs.org
 pnpm exec design-system --help
 ```
 
@@ -86,7 +86,7 @@ process value:
 $previousOrtCuda = [Environment]::GetEnvironmentVariable('ONNXRUNTIME_NODE_INSTALL_CUDA', 'Process')
 try {
   $env:ONNXRUNTIME_NODE_INSTALL_CUDA = 'skip'
-  npm install --ignore-scripts=false --save-exact @yugoo-design/companion@0.1.0-beta.10 --registry=https://registry.npmjs.org
+  npm install --ignore-scripts=false --save-exact @yugoo-design/companion@0.1.0-beta.12 --registry=https://registry.npmjs.org
 } finally {
   [Environment]::SetEnvironmentVariable('ONNXRUNTIME_NODE_INSTALL_CUDA', $previousOrtCuda, 'Process')
 }
@@ -108,8 +108,8 @@ to an already published package. Users do not install DSH and Companion separate
 | WorkBuddy | `install --host workbuddy`: prepare the stable marketplace and plugin; import or update and enable through the host. |
 | DSH | `install --host dsh`: run the existing plan/apply transaction with the bound aggregate, official CLI/Loader and an explicitly selected existing profile. |
 
-For a fresh WorkBuddy installation, use native suite `0.3.23` with
-`--suite-version 0.3.23`, the verified Node executable and a persistent external
+For a fresh WorkBuddy installation, use native suite `0.3.25` with
+`--suite-version 0.3.25`, the verified Node executable and a persistent external
 preparation destination. Import the returned `nativeImport.market` directory and
 enable its `yugoo-design` plugin. The fresh market is also named `yugoo-design`;
 no previous test market or preparation receipt is required. An owned update with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yugoo-design/companion",
-  "version": "0.1.0-beta.10",
+  "version": "0.1.0-beta.12",
   "description": "Yugoo Design Companion beta: interactive Design Projects and Panels in supported native Agent Hosts.",
   "license": "Apache-2.0",
   "type": "module",

package/payload/desktop-preparation/hosts/workbuddy/design-SKILL.md

@@ -5,6 +5,9 @@ description: Open and use Yugoo Design in this WorkBuddy conversation with a bro
 
 Use this Skill for an authorized Design task in the current WorkBuddy conversation.
 The user starts WorkBuddy normally; never create a host launcher or another model client.
+For the main U/S/T and conditional background review protocols, read the installed
+[native execution reference](native-execution.md). The WorkBuddy placement limits
+below still apply: foreground Producers remain serial and Workers are unsupported.
 
 1. Obtain this conversation's exact `sessionId`, `nativeCwd` and `transcriptPath` from its current
    `YUGOO_WORKBUDDY_IDENTITY_PROBE` Hook context. This is routing evidence, not task
@@ -80,15 +83,32 @@ The user starts WorkBuddy normally; never create a host launcher or another mode
    never guess names or conclude that all Bundles require a Producer from an
    unknown-name error. The catalog declares execution policy, not verified host
    capabilities; preparation still checks the requested placement.
+   Read the complete returned `method`, starting with its shared native execution
+   contract, and pass it unchanged to the selected executor together with its
+   `executionContract`, resource and Design Files paths. That contract maps
+   Bundle operation names to the current Host; references do not override it
+   with DSH-only tool spellings. Do not conclude that native file generation is
+   unavailable merely because MCP has no `write`, `edit`, `design_validate` or
+   `design_publish`. Native filesystem tools author the owned files;
+   `design_finish_run` / `design_finish_main_bundle` validate and publish them.
    - For `execution.mode: main`, read the entire returned Bundle method/output
      contract, then use `design_begin_main_bundle` and `design_finish_main_bundle`
      with its exact invocation ID. Publish unanswered questions with
      `scope: state`, `outcome: pause`; never invent answers.
    - For `execution.mode: subagent`, use one foreground native general-purpose
      `Agent`. Its first bootstrap task only returns READY and performs no writes.
+     Do not choose a read-only research Agent or supply a tool filter that removes
+     the native file/command tools required for the subsequent generation task.
+     If the child reports missing capability, inspect its actual native tool names
+     and the Agent type/permissions/filter once; a list of MCP tools alone cannot
+     establish that native Write/Edit/command tools are absent. Report a real
+     denial without changing permissions or borrowing another executor.
      Obtain the actual Agent ID from the native result, then call
      `design_register_run` with the exact connection, `runId`, current session as
      `parentRunId`, `role: producer`, the prepared `skill`, and stable `artifactId`.
+     Use the returned real `agent-...` ID, not a task name. WorkBuddy does not use
+     Codex `launchCallId` / `agentPath` or QwenWork `taskPath`; its child transcript
+     is derived from the already bound original conversation.
      The server cross-checks the parent native receipt and child transcript; a
      filename, assistant assertion or pasted Agent ID cannot grant authority.
      After successful binding, `resume` that same Agent in foreground. Give it
@@ -102,20 +122,54 @@ The user starts WorkBuddy normally; never create a host launcher or another mode
      validation still needs repair after return, resume the same Agent; do not
      repair its files in main or call its work complete based on a text response.
      Never use background mode for a foreground Producer.
-   Workers/nested delegation and GRA are unavailable in this preview. Execute the
-   Producer serially; never change a subagent Bundle to main mode or substitute
+   Workers/nested delegation remain unavailable. Background GRA requires the
+   current-service readiness proof described below; it does not enable Workers.
+   Execute the Producer serially; never change a subagent Bundle to main mode or substitute
    another model/CLI. Failed binding or absent native Agent/resume support is a
    real error, not permission to bypass the guard.
 5. The shared Panel validates and saves before notification. After a user-authorized
    save notice, read `design_status` once using its exact connection and read the
    canonical saved state. Confirm the actual answers; never reapply saved edits.
+   In the actual main continuation turn, call `design_main_context` for the current
+   exact U/S/T input and shared rubric. Reuse a current assessment; otherwise
+   assess the saved facts in main and call `report_design_clarity` with that exact
+   input before the final reply or next Design recommendation. Report at most once
+   per real user turn; a new save, Kit or user interjection requires fresh context,
+   not relabeling old scores. A background review cannot substitute for this main
+   report. Missing verified native history means unavailable, not a made-up score.
    If the widget is closed or the original conversation changes, notification may
    fail while files remain saved. Explain this and preserve the existing project;
    do not blindly repeat a send or create another project.
 
 KAG uses the shared local implementation and exposes actual status; report failures
-honestly. Serial native Producer bootstrap/resume and publication have a separate
-acceptance boundary from Workers and background GRA, which remain disabled. An interface
+honestly. Successful saves already admit indexing. Use `design_knowledge_context`
+and `design_query_knowledge` only when useful, retaining exact project/checkpoint/
+revision pins and checking source facts; indexing never blocks save acknowledgement.
+
+For GRA, immediately read `design_status.hostCapabilities` before any real review.
+Only `backgroundReviewReadiness: ready` and `backgroundReviews: true` permit
+dispatch. WorkBuddy 5.8.3's public `Agent(run_in_background=true)` can fall back
+to synchronous execution when native background capability is disabled. Do not
+probe it with a real review prompt. Unverified readiness keeps requests pending;
+use the returned content-free `backgroundReviewProtocol.bootstrap` only as an
+explicit readiness check, then read status again. Do not change Host settings or
+repeat an uncertain probe. Proof must be newer than this exact Companion connection
+opening; a historical descriptor from the same session is insufficient.
+
+When ready, honor the project GRA policy (`off` forbids automatic review) and reuse
+the exact `dispatch:true` prepared IDs. Follow the installed native execution
+reference: launch independent read-only native background reviewers, bind actual
+structured task IDs with `design_bind_reviews`, and let each child read its own
+`design_read_review` prompt/schema and submit through `design_submit_review`.
+Review only the request's committed snapshot through `design_git_read`; keep its
+checkpoint on every page, and do not edit Design Files or execute advice. Producer
+write/command instructions above are not reviewer permissions. A synchronous
+`lastId` result, teammate name or assistant assertion is not a background handle.
+The server checks the descriptor against the actual parent Agent call; native
+`TaskOutput(task_id, block=false)` structured receipts establish terminal state.
+Unknown/externalized status stays unknown. Do not poll, wait for reviews, or block
+the user's task. Serial Producer, conditional background GRA and unsupported
+Workers retain separate acceptance boundaries. An interface
 receipt is not proof that the agent consumed a message; actual readback is required.
 
 Conversation history uses the exact Hook transcript path, verified session and cwd.

package/payload/desktop-preparation/materials.json

@@ -5,7 +5,8 @@
     "LICENSE": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30",
     "NOTICE": "6b4eec391144fcbd96ec7b45a28764ab1932722a96325248377c3e28aac2c62d",
     "THIRD_PARTY_NOTICES.md": "bfcab921c6c15ccc47f9b1a6cc5941675c95962de5ea5b0edc50fbfa2aef136a",
-    "hosts/workbuddy/design-SKILL.md": "2452f5eab1ba7c87699c44df7254ea8fdbe2d2c018da921e5b4cdabf76fe3a78",
+    "hosts/workbuddy/design-SKILL.md": "5cc44054186fccb6bba66e237367cec3774ea59f64ae93ea4acf5648355f22b0",
+    "plugin/design-system/skills/design-panel/native-execution.md": "7a2ab8b2aff916115a8c767c3c1e8156dc71a58c154366a0e8ba5c80256aeda3",
     "qwenwork-package.mjs": "ae340c245feb2beab0de9e02c09b37d9924fa0d6fe9f3dd1c329242e4a350c11",
     "qwenwork-template/.claude-plugin/plugin.json": "7beaf01908b62b4ad6c0a371f09b45cb3236f622910c3769f8b3393e4cacb354",
     "qwenwork-template/.mcp.json": "931fdcd8efa8e0cfe1dbdda225c523d62dbc4bacb5a33d01eebe84933b712353",
@@ -22,7 +23,7 @@
     "qwenwork-template/scripts/windows-private-storage.mjs": "27c3eb052278f0cb2850326e1d0864cfd2f3f6d2b1975ec7c24535ef6251ac94",
     "qwenwork-template/skills/design-component/SKILL.md": "85a1f2a016174787226eaa9e9e6675e86057212d322a65014edd71f3e4861b34",
     "qwenwork-template/skills/yugoo/SKILL.md": "3aedb6739f204c9931cf1d406e5a71d59fc3424875746ee5737e68e5a58236bc",
-    "qwenwork-template/skills/yugoo/native-execution.md": "c23d1840c2557a4bdc9442edb3e6b488e1acb4dfb564b966e123c105710ec849",
+    "qwenwork-template/skills/yugoo/native-execution.md": "9d300490b3493ff9f4826414cfa832244acc29b2205b825d3ccaff8665049ddd",
     "src/browser-access.mjs": "4b64284b9bfaaa32c8502ab00febdda4f8a972f4b41e822d4e708b27e7e3efdf",
     "src/native-hook-transport.mjs": "a5878335c40bc930d28d34e079de09f7628dc0cbcc828a1309826c1829640a83",
     "src/qwenwork-connection.mjs": "850b95ea4f57ccf4e1cb6463f98625b941d74f4df76bc24f05dbdf15b8597b3a",
@@ -30,12 +31,12 @@
     "src/windows-native-platform.mjs": "57ac50c9a8cc0371597d6d40e3efe4cbe2a470e98f75f0229721c7d5a48e7e98",
     "src/windows-private-storage.mjs": "27c3eb052278f0cb2850326e1d0864cfd2f3f6d2b1975ec7c24535ef6251ac94",
     "src/workbuddy-context-probe.mjs": "1553e01ab95d7d9f2099806a7af5dd76cab856bd5fe8483b29c4cd8f7d30bff8",
-    "src/workbuddy-mcp-relay.mjs": "5a9fc1d8ef5acb90c471e9405c53591b9e94c8fb7b60d6e43a45f6ce48567d46",
+    "src/workbuddy-mcp-relay.mjs": "92a30918792f5d4543a7c94e2d86446e7df4069f8ce26fe20b9439dad7b30286",
     "src/workbuddy-message-probe.mjs": "9366d0ebc8c4133c8d3c4acb793c0319b9f6bb4a123381bd2d83f6ecb6275101",
     "src/workbuddy-panel-mcp.mjs": "55accb55244f86e86d9f36e445e450fedba47e7bce80cacd2ceb6327a14b99ef",
-    "src/workbuddy-relay-probe.mjs": "ea20a6f03a9fe661990c10da0bf5b2431f784f3724a9827a250c84f480159e69",
+    "src/workbuddy-relay-probe.mjs": "c5ea46abadbf9dfe265eb40eb81ed08a4f6596dd5f673fd248843e7775160cc4",
     "src/workbuddy-relay-service.mjs": "44d60d6956250417507fb76c71c3030a01bc38e565e4572a761b46f255f8e669",
     "src/workbuddy-ui-probes.mjs": "a91d4651248125769254755bdf66a44bbc9e5a793dad0a137c35acbb10a89a88",
-    "workbuddy-package.mjs": "25bb0db84c5d11fdad27b25cc796c8c43cf32a52a864ee786a8108a2f426f36b"
+    "workbuddy-package.mjs": "cc3ca0be5cc120f107119bf82897a83d555f71338347c7908568dba562111ec9"
   }
 }

package/payload/desktop-preparation/plugin/design-system/skills/design-panel/native-execution.md

@@ -0,0 +1,413 @@
+# Native Design execution
+
+The native Host owns spawning, concurrency, messages, cancellation and permissions. The
+companion owns Design Files, Panels and the existing validation/Git/journal path.
+Do not invoke a second `codex exec`, `resume`, or app-server to simulate children.
+If native delegation is unavailable, report the limitation rather than claim
+fanout succeeded. The Producer may perform the scoped artifact work itself.
+
+## Common bridge
+
+`serve` prints a private `connection` file path. Keep it inside the local task
+context; do not print its contents or include its token in a shared artifact.
+Prefer the plugin's MCP tools. Pass `connection` as that exact file path on each
+call; no temporary request file or shell process is needed. Do not infer the
+calling child's identity from the connection, which belongs to the main session.
+
+| Existing operation | MCP tool |
+| --- | --- |
+
+| `prepareBundle` | `design_prepare_bundle` |
+| `registerNativeRun` | `design_register_run` |
+| `finishNativeRun` | `design_finish_run` |
+| `focusArtifact` | `design_focus_artifact` |
+| `prepareReview`, `bindReviewRun`, `submitReview` | `design_prepare_review`, `design_bind_review`, `design_submit_review` |
+| `prepareReviews`, `readReview`, `bindReviewRuns` | `design_prepare_reviews`, `design_read_review`, `design_bind_reviews` |
+| `claimReviewAction`, `settleReviewAction` | `design_claim_action`, `design_settle_action` |
+| `mainContext`, `reportMainClarity` | `design_main_context`, `report_design_clarity` |
+
+### Main U/S/T after saved output
+
+At a meaningful saved Design output boundary, including the actual continuation
+turn after Panel Save and continue, call `design_main_context`. It returns the
+latest exact `input`, shared assessment method, current score and KAG status.
+Use a current score; otherwise assess the saved facts against the agreed user
+scope in this main conversation and call `report_design_clarity` with that exact
+input before a final reply or next Design recommendation. The service verifies
+the real native main call and records at most one new report per actual user
+turn. An identical retry retains the original audit provenance. A newer save,
+Kit change or user interjection invalidates old inputs: read context again,
+never relabel old reasoning. If the current turn already reported, await a real
+new user boundary before creating a different report. Missing verified native
+history means unavailable assessment, not a fabricated turn or score.
+
+This main report uses the existing Journal and clarity authority. It neither
+runs a second evaluator nor waits for background GRA. U/S/T identifies useful
+evidence gaps; it does not override explicit user work or impose mandatory
+stages. KAG is derived discovery: successful saves already admit maintenance,
+and pending indexing never gates the save acknowledgement or ordinary design.
+
+### Serial artifact focus
+
+Before the main Agent or an existing native Producer begins work on one
+artifact, call `design_focus_artifact` with the exact connection and either
+`invocationId` from `design_begin_main_bundle` or the Producer's registered
+`runId`. Supply `artifact_kind`, `artifact_id` and `artifact_file` together.
+Keep the stable ID/path/kind identical when returning to the same target. For
+example, after starting a Research main invocation:
+
+```json
+{
+  "connection": "/exact/private/connection.json",
+  "invocationId": "<invocationId returned by design_begin_main_bundle>",
+  "artifact_kind": "direction",
+  "artifact_id": "R-001/D-001",
+  "artifact_file": "research/R-001/D-001.md"
+}
+```
+
+Replace the illustrative connection and invocation values with actual returned
+values. For Producer execution, replace `invocationId` with its actual `runId`;
+never register the main Agent as a Producer. The generic Companion CLI `call`
+operation exposes the same bridge method `focusArtifact` with camel-case
+`artifactKind`, `artifactId`, `artifactFile`. This only associates observed native
+activity; it creates no artifact, attempt, agent or acceptance receipt. Canonical
+Bundle JSON, other Bundle paths, settled invocations and Worker owners are rejected.
+
+Workspace `artifactActivities` carries the actual native executor and a
+`logTarget`. Pass its `artifactId` and optional main `invocationId` with the
+actual `runId` to `readExecutionLog`. Only rows after focus and before the next
+target switch or Bundle settlement are returned. Returning to a target aggregates
+its separate segments. Earlier main conversation history is not artifact work.
+Rows already evicted by the bounded native observer are marked truncated;
+unavailable or invalid native logs produce unavailable activity, never completion.
+Native status and published artifact availability remain independent facts.
+
+
+Parameters below are unchanged apart from the additional `connection` path.
+Use `design_status` for a compact execution/clarity/handoff read when needed,
+not as a polling loop. Keep large artifacts in files with native filesystem tools.
+
+If MCP tools are unavailable in this host/session, report that limitation and
+use the existing CLI fallback: write a small request JSON outside `design_files`, then call:
+
+```sh
+node /absolute/plugin-root/scripts/design.mjs call \
+  --connection /absolute/connection.json --request /absolute/request.json
+```
+
+Requests have `{ "method": "operation", "params": { ... } }` shape. This local
+bridge does not dispatch agents. Use native spawning tools for that operation.
+The common operations below are available only while this companion is running.
+
+## Producer
+
+`prepareBundle` also returns shared `cooperationMethod`, `workerMethod` and
+`knowledgeMethod` guidance. Apply cooperationMethod and knowledgeMethod in the
+Bundle executor, whether main or Producer. Forward workerMethod and
+knowledgeMethod along with a bounded task/evidence brief to native Workers.
+Source locators and relevant excerpts avoid blanket rereads; exact assets and
+validator inputs remain file-backed. Query KAG only when useful to the task,
+passing actual returned pins to children; missing capability/pins fall back to
+source files without blocking. These fields do not change native permissions.
+
+Execution placement comes from `prepareBundle.execution.mode`: `subagent`
+(also the default for older manifests) creates a native Producer; `main` runs
+the same Bundle method in this conversation. Worker fanout is a separate Bundle
+decision, not a consequence of this mode. Do not silently substitute a mode when
+the host cannot support it.
+
+For `main`, call `beginMainBundle` (`design_begin_main_bundle`) with the skill.
+Keep its exact `invocationId`; this is a Bundle invocation, **not** a native run
+ID. Read the returned method/resources yourself, maintain canonical JSON and
+perform the same validation. Call `finishMainBundle`
+(`design_finish_main_bundle`) with that invocation ID and the same scope/outcome
+described below. Correct validation failures here before retrying settlement.
+Cancel/wait for any Workers before settling; a new main Bundle cannot start until
+the current one is settled. Never register the main Agent as a Producer child.
+Completing the Bundle does not end the main conversation. A focused main artifact
+uses its actual conversation observer and bounded target segments; no Producer
+rolling log or attempt is fabricated. Real Workers retain ordinary status and logs.
+
+The following child-registration steps apply to `subagent` mode:
+
+1. Request `prepareBundle` with `{ "skill": "page_design" }` (the selected
+   Bundle name, not a fixed Page default). Read the returned Bundle method,
+   referenced artifact contract and the applicable Mindset. Pass a bounded user
+   task, exact returned resource paths and the same project context to a native
+   Producer child. The parent owns registration; the child does not scan sessions
+   or rediscover the installed Bundle. A not-yet-created output directory is normal.
+2. Register that child using `registerNativeRun`: `role: "producer"`, `skill`,
+   `artifactId` (Bundle name for its root), and exact native `runId`. For `host=codex` only,
+   an exact `launchCallId` or uniquely recorded `agentPath` from native spawn can
+   be supplied instead. The adapter resolves paths inside the bound host session
+   storage; do not search or print session metadata. Parent defaults to the main
+   conversation; a Worker of a Producer must supply its real Producer parent ID.
+   Explicit `transcriptPath` (and Qoder `taskPath`) remain supported. Native
+   metadata must prove the parent/child relationship and the native cwd supplied
+   to `serve --host-cwd` (not necessarily the Design Project root). Never
+   select a newest log or fabricate IDs. If metadata is not yet written,
+   register after it becomes available; don't respawn a duplicate child.
+3. The Producer maintains canonical JSON, preserves user edits and coordinates
+   artifacts. Workers can write distinct artifacts; only the Producer edits
+   the shared JSON. Producer takeover remains available. A missing reference
+   means planned, not completed; do not insert execution statuses into JSON.
+4. On child completion or an intentional user handoff, call `finishNativeRun`
+   with its `runId` and `scope: "completion"` or `scope: "state"` respectively.
+   This reads files directly, runs shared validation, and uses the existing
+   Bundle Git publication path. Fix actionable diagnostics in the generator.
+   On failure/cancellation call it with `outcome: "failed"`/`"cancelled"` to
+   audit existing facts; Git cadence does not depend on design success.
+
+Native terminal events, not this bridge call, drive execution indicators. Panel
+content is read from files even before settlement. If the Producer forgot the
+settlement call, the parent performs it once; don't rerun generation just to
+obtain a publication tool call.
+
+## Worker
+
+For independent artifacts, follow the Bundle's delegation method. The native
+parent is the Producer in `subagent` mode or the main Agent in `main` mode.
+Give each Worker the artifact contract, its concrete task, existing shared
+design inputs and exact `artifact_id`, `artifact_kind`, `artifact_file` from
+the Bundle. No additional task schema is required in `skill.yaml`.
+
+Register each actual child with `registerNativeRun`, `role: "worker"`, its
+native `runId`, Producer `parentRunId`, exact native `transcriptPath`, `skill`,
+`artifactId`, `artifactKind`, `artifactFile`. This maps native events/logs to the
+correct entity and round. Do not reuse one child's identity for several files.
+When the parent is the main Agent, supply its actual `parentRunId` and the exact
+`invocationId` returned by `beginMainBundle` as well. Do not invent an intermediate
+Producer. The main Agent then performs the same JSON integration duties below.
+
+Workers write artifacts directly in `design_files`, use Bundle file-oriented
+scripts for required layout/validation and repair diagnostics before returning.
+Return only the path and compact validation result, not the complete HTML/XML.
+The optional `finishNativeRun` call returns a compact file receipt. The Producer
+updates canonical references as each Worker finishes, without waiting for the
+remaining Workers. All workers must finish or be cancelled before the Producer
+settles its Bundle. Do not hide failure by substituting another file.
+
+## Mapping existing Bundle tool terminology
+
+| Bundle operation | Native Codex operation |
+| --- | --- |
+| `design_delegate` | Native child spawn, followed by exact run/target registration |
+| `read_skill_resource` | Read the referenced file under returned Bundle resources |
+| `list`, `read`, `write`, `edit` and worker artifact tools | Native filesystem tools on the same Design Files project |
+| `run_skill_script` | Native shell, run the actual Bundle script with its documented file-path arguments; use Design Files as cwd |
+| `design_validate` | Packaged `validate --project … --skill … --scope …` |
+| `design_publish`, `design_finish` | `finishNativeRun` for a Producer, `finishMainBundle` for main execution; state scope preserves the same handoff |
+
+These mappings adapt execution, not the Bundle's schema, generation method or
+validation criteria. Native permissions remain authoritative. Never disable
+approvals or install dependencies silently to make a task pass.
+
+## Background GRA and U/S/T
+
+### Shared Design KAG
+
+All Bundles can use the same stored graph; it is not a required preliminary
+workflow. When a task needs cross-file evidence, `design_knowledge_context`
+returns availability, a bounded starting context and the shared reading method.
+Use `design_query_knowledge` for more: preserve its exact `project`, `checkpoint`
+and `revision` pins, select source files or original entity IDs, then traverse
+one-hop `incidentTo` neighborhoods with `direction` and optional `relationTypes`.
+Pagination must retain the same filters. Read the referenced files to verify
+facts; similarity is a candidate, and isolation or partial search is not proof
+of a missing design. If pins become stale, restart the bounded investigation
+from a new context rather than mixing versions. Unavailable graph access does
+not block normal source-file work or authorize repeated retries.
+
+The packaged local embedding runtime uses cached model weights by default. If
+weights are missing, file projection still works and semantic coverage reports
+an error, not completion. With the user's agreement to download model weights,
+start Companion with `--allow-embedding-download`; text remains local. Use
+`--disable-embedding` for structural-only operation. Do not silently change to
+a cloud embedding endpoint. Packages include native inference dependencies for
+their recorded build platform/architecture, not every operating system.
+
+GRA's existing result may include evidence-backed relationships or justified
+retractions of its own prior relationships; it does not edit Design Files.
+Use exact IDs and the supplied output schema. Empty results do not clear graph
+state. A negative search conclusion belongs to that review's checked scope and
+file revision, not an enduring “missing” fact; reassess after source changes.
+Clarity reads evidence but does not maintain relationships. Service-managed
+reviewers receive a fixed read replica and read-only query helper when available;
+they must not contact the main session or use its MCP connection.
+
+First honor the current host's execution capability: if `design_status` reports
+`hostCapabilities.backgroundReviews: false` or `reviewDispatchOwner: "unavailable"`,
+do not prepare, spawn, bind or recheck reviews. Keep the existing requests/results
+and explain the capability gap without changing the user's review policy. A Hook
+notification and a synchronous Agent call do not establish background execution.
+Clarity is a separate assessment capability; unavailable evaluation must not be
+reported as a current score or as successful GRA. Continue the authorized
+foreground task. The launch instructions below require available native
+background execution as well as an exact `dispatch:true` reference.
+
+For WorkBuddy, read `design_status.hostCapabilities` immediately before any real
+review dispatch. Its `backgroundReviewReadiness` must be `ready`; the public
+`backgroundReviewProtocol` alone does not prove capability. WorkBuddy 5.8.3 can
+silently execute `Agent(run_in_background=true)` synchronously when background
+capability is disabled. Never use a real review prompt to test this. With
+unverified readiness, keep reviews pending and explain the normal Host capability
+gap. The protocol includes a content-free readiness bootstrap that may be run
+explicitly; it returns immediately without reading files, using tools or
+assessing Design. Read status again afterwards. Do not change private Host
+settings or automatically repeat the probe. Only a native descriptor created
+after this exact Companion connection opened proves readiness; an old descriptor
+in the same session is insufficient after restart.
+
+Once ready and given an exact prepared review reference, use the ordinary native
+`Agent` tool with `run_in_background=true`. Bind its structured `subAgent.sessionId`
+task ID and exact background descriptor to that review; never use a teammate name,
+assistant text, synchronous `lastId` result or a guessed log. The adapter verifies
+the actual parent call, session, cwd and child path. Spawn RPC completion proves
+only launch, not review completion. WorkBuddy's `TaskOutput(task_id, block=false)`
+structured `agent-output` receipt supplies native status. Externalized/missing
+status or newer unbound child activity remains unknown. Do not follow paths in
+tool text, busy-poll, wait for review completion or block the main user task.
+
+When `design_status` reports `reviewDispatchOwner: "companion"`, or preparation
+returns `dispatchOwner: "companion"`, the service owns background review execution.
+Do not prepare, spawn, bind, follow up, or wait for reviewer children. Continue the
+user's design work; review results appear in the existing background area,
+advisory queue and clarity score. The native-child instructions below apply only
+when the main Agent owns dispatch. Enabling `serve --background-reviews` is an
+explicit account-quota decision, not something to enable silently during setup.
+
+Successful Panel saves and Bundle publications automatically admit KAG maintenance;
+graph reads and Worker drafts do not trigger it. `design_status` also exposes the
+project `reviewPolicy`: auto combines Agent initiative with a publication rule
+after a configurable quiet window (default 30 seconds), continuous checks the
+latest published checkpoint every configured N minutes even without file changes,
+and off forbids autonomous GRA but still permits an
+explicit human `design_recheck_reviews` request. Never change this user policy
+yourself. Clarity is independent. In native-dispatch mode the rule queues a notice
+with exact prepared review IDs; it does not itself spawn native children. Queue
+acceptance is not execution, and uncertain delivery must not be blindly replayed.
+
+Save/finish responses and `design_status` expose the same derived `reviews`
+summary. It is a read-only reminder. `due` means evidence or
+observed editing scope needs review; `prepared` means a request exists but is not
+bound. Inspect/reuse it rather than blindly spawning a duplicate. `running` is
+not a result; `unsubmitted`, `failed`, `interrupted` and `unavailable` require
+inspection, not a claim that review passed or an automatic retry loop. Do not
+poll in the main conversation or wait for reviews before continuing user work.
+
+For useful Agent initiative in auto mode, use one
+`prepareReviews` call, normally omitting `profiles`; it bypasses the rule's wait
+and reuses current work. Do not mechanically call it after every save. In off
+mode use `design_recheck_reviews` only for an explicit human request, with one
+stable requestId across retries, without changing the policy. The service
+considers all three GRA profiles and initial/stale
+clarity, reusing current requests without dispatching duplicates. A paraphrased
+context does not create a new default review. Explicit `profiles` remain for a
+user-requested scoped reassessment or diagnostics, not arbitrary omission and
+later catch-up rounds. These remain independent reviews, not one merged review.
+Only entries with `dispatch:true` authorize a new launch in this batch. Reused
+prepared requests require inspection of any prior launch before recovery; do not
+spawn duplicates after an uncertain response. A batch shares preparation context,
+not an immutable file snapshot: `revisionChanged:true` means do not dispatch it.
+An explicit publication-rule notice is different: its exact requests deliberately
+pin immutable historical Git commits. Read only that checkpoint, not live files;
+historical results cannot become current advice, Clarity, or KAG observations.
+WorkBuddy requests also pin committed evidence for Agent-initiated preparation;
+follow each exact request's checkpoint and `design_git_read` pagination contract.
+Pass `userContext` with the current user request, relevant requests to simplify
+or defer, and concrete work still being edited. Do not invent user preferences.
+Observed running targets are not exclusions: an Agent can still be alive after
+settlement or resume after a pause. Review saved evidence and avoid judging
+in-progress output as complete. Report any coverage limitation separately to the
+parent; when that editing scope clears, check for a follow-up review even if the
+file revision did not change.
+The response supplies short request references. Reviewers use `readReview` with
+their exact `reviewId` and `connection` to obtain the full prompt and schema;
+the parent need not read or rewrite them. Do not dump Design Files into the parent.
+
+Spawn independent native **background** review children from the main Agent.
+Give each only its review ID, connection path and instructions to read its request
+and submit its own structured result. Launch independent children together when
+the host supports it. Use one `bindReviewRuns` call with
+`{bindings:[{reviewId,nativeRun},...]}` for the exact native launch results;
+`nativeRun` can contain just the actual `runId` (or, for `host=codex` only, an exact launch reference
+as above); the service fills paths and verifies native evidence. Do not send
+reviewers to scan logs for their identity. Inspect per-entry errors: partial
+success is possible, and successful bindings must not be relaunched. Never guess
+the latest log path. The child reads the registered binding from `readReview`
+before submission, eliminating a separate parent message carrying that binding.
+It may read evidence while binding is pending. If still unbound when ready to
+submit, report the pending binding and yield; do not poll or claim success.
+If that same child has already yielded for binding (or ended without submitting),
+after successful binding use one native follow-up/resume to tell it to read its
+registered request and submit. Reuse the same child, not a new spawn. This is
+recovery for an early finish, not a mandatory message for every running reviewer.
+If the request is superseded or its revision changed, report that limitation;
+do not present the old assessment as current. A reviewer
+may handle another bounded profile or later revision with its own review ID and
+schema; this does not reuse the previous result or grant editing authority.
+Submit with `submitReview` params `{reviewId, nativeRun, result}`. The child may
+read evidence while registration completes, but cannot publish before binding.
+The single-review prepare/bind tools remain compatibility paths, not the default
+multi-profile orchestration. Do not use them to reproduce four preparation rounds.
+If a user save or message arrives during preparation, handle the user's work
+first. Reconcile the existing requests at the next settled checkpoint, without
+automatically completing the old batch or restarting it in the foreground.
+Do not synchronously wait for GRA or treat review completion as a prerequisite
+for foreground generation, user interaction, or a successful Bundle result.
+Use native notifications for completion; no busy-loop polling or unbounded
+self-respawning. A subsequent settled change can start the next bounded review.
+
+The reviewers have no authority to edit Design Files or automatically accept
+advice. Use `submitReview` for structured result publication, preserving the
+exact review ID/native child binding. Errors return diagnostics for correction.
+Do not force stale results onto newer project evidence. UI reads and polling
+must never launch reviews. Native permission/cancellation remains in Codex.
+
+GRA and U/S/T are distinct: U/S/T updates assessment; GRA contributes suggestions
+to the shared advisory inbox. Only a real user acceptance dispatches a scoped
+foreground action with the original exact action receipt. Queue acceptance is
+not proof that the action started or completed.
+
+For an accepted action in `main` mode, begin the exact target main Bundle and
+claim it with `{receiptId, invocationId}` before editing. After file settlement,
+use that same pair to settle the action; the main session need not end. A failed
+claim grants no permission to execute the advisory.
+
+For an accepted action in `subagent` mode, spawn the exact target Producer initially instructed to
+wait before editing. Register its actual native identity, then call
+`claimReviewAction` with `{receiptId, runId}`. Only after a successful claim send
+the native Producer permission to begin this scoped action. After file settlement
+via `finishNativeRun` and the native terminal event, call `settleReviewAction`
+with `{receiptId, runId}`; the bridge derives the outcome, not the caller.
+If claiming fails, cancel the waiting child and report the diagnostic. This is
+workflow coordination, not a replacement for native host permissions.
+
+## Return control to the user
+
+After the foreground Bundle settles, honor any already requested next task.
+Otherwise briefly explain the result and, when a user choice is needed, offer
+the most relevant next steps through the host's native question tool if it is
+available in the current mode. Do not wait for GRA; use available evidence and
+report unavailable clarity honestly. Ask about consequential choices, not routine
+bookkeeping, and retain the option to adjust or stop.
+
+If the native question tool is unavailable in this session/mode, do not omit the
+next-step choice: ask one concise question in the main conversation with concrete
+options and a short recommendation, including adjusting or stopping where useful.
+A recommendation sentence alone is not a choice handoff: finish with an actual
+question the user can answer, such as “继续梳理核心流程，还是先调整这些功能？”.
+Do not invent a native question event from that prose, enable experimental host
+features, or change collaboration mode to force a question tool to appear.
+Use the tools actually exposed by the current host; a tool name in this document
+does not make it callable. Do not switch modes or launch another host to manufacture a question
+tool. The companion's message queue is not a native-question answer channel;
+never present a queued message as an answer to a pending native question.
+
+## Development handoff and existing specs
+
+When the user requests implementation or a development brief from a Design Project, use the selected project and the specified coding workspace; this is not a request to run another design Bundle. Confirm the actual project root, Kit pin and published design checkpoint with available host readers. Keep unpublished differences separate. Read only the records and artifacts relevant to the authorized task; KAG is a discovery aid, not a substitute for those originals, and unavailable or partial knowledge does not prevent reading the files.
+Inspect the target repository's instructions and existing specs before proposing an output location. Recognize GitHub Spec Kit's specs/<feature>/spec.md, plan.md and tasks.md; OpenSpec's openspec/specs/<domain>/spec.md and openspec/changes/<change>/ proposal, spec deltas, design and tasks; and Kiro's .kiro/specs/<feature>/requirements.md, design.md and tasks.md. Preserve the actual repository's structure and responsibilities, including its current-spec versus proposed-change distinction. These paths are discovery hints, not permission to create every file or assume a framework is active. If several conventions coexist, follow the one governing this task; if none exists, propose an existing convention or an ordinary Markdown brief and resolve the location before writing. Do not install a framework or invent a Yugoo spec schema.
+For the task-scoped brief, use ordinary Markdown links to the actual design source paths, relevant artifact paths and precise record IDs or JSON pointers, with the project, Kit pin and verified published checkpoint beside the links. Use relative links where the target workspace can resolve them; disclose external project paths instead of claiming they are portable. Do not invent a remote URL, copy all design artifacts, or treat a prototype, inference, score or unanswered field as a confirmed requirement. Organize the affected user behavior and scope, important exceptions and constraints, implementation tasks and observable acceptance criteria in the repository's existing requirement/design/task sections; keep design decisions, implementation proposals and unresolved product decisions distinct.
+Produce the brief before coding when scope needs agreement. Existing user authorization carries forward; ask only about consequential unresolved scope or product decisions. Updating target specs or code requires that workspace's authorization, and this guidance grants none. Implement only the agreed slice and report checks actually run. For a design change, return the discrepancy to its owning Bundle's ordinary validation and publication route; after publication, update only affected spec links, tasks and acceptance criteria against the new checkpoint. Development specs and code do not write back to Design Files or silently become design authority. No second requirements store, automatic bidirectional synchronization or required full-project rewrite is introduced.