@super-hands/connect 0.1.23 → 0.1.24

package/client.mjs

@@ -42,7 +42,7 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 16;
+var CONNECT_SKILL_VERSION = 17;
 var CONNECT_SKILL_DIR = MCP_SERVER_KEY;
 var CONNECT_SKILL_FILENAME = "SKILL.md";
 var VERSION_MARKER = `[//]: # (superhands-skill-version: ${CONNECT_SKILL_VERSION})`;
@@ -63,6 +63,15 @@ describe how agents should build in this product. Source labels tell you where
 an instruction came from and how to read it; they are not a choice about which
 half to follow.
 
+Design traces connect guidance to reported changes, evidence and designer review.
+For this task, create a stable task reference once (for example a UUID), and send
+it as \`trace.taskId\` on the first Instructions read. Reuse it if that read
+needs retrying. Save the returned \`trace.runId\` and \`trace.decisionId\`;
+send \`trace.runId\` on every later read and report. Do not use a transport
+session or a shared credential as a task identity. Send \`trace.target\` for
+known screens/parts, \`trace.phase\` (before or during), and \`trace.trigger\`
+when an observation prompted guidance. Unknown scope stays unknown.
+
 Before you build, change, or restyle any UI:
 
 1. Call the \`superhands_get_instructions\` MCP tool with \`intent\` set to what
@@ -115,7 +124,32 @@ Before you build, change, or restyle any UI:
    entries pull in different directions, prefer the more specific instruction,
    preserve explicit exceptions, and call out any conflict you cannot honestly
    resolve.
-5. When you finish a part, call \`superhands_report_part\` with \`part\` \u2014 the
+5. Keep each design decision explicit. Use \`superhands_report_trace\` with the
+   runId, a stable eventId and occurredAt timestamp (reuse both on retries).
+   Send a \`decision\` event with the returned delivery IDs when one context
+   response supports several decisions; use \`replaces\` to refine a provisional
+   group without counting both. Title it \u201CSuggested \u2026\u201D until output inspection
+   establishes reuse. Keep conflicting sources and any explicit resolution.
+   Register each identifiable output with an \`output\` event: revision,
+   identity (commit:<sha>[:dirty-digest], deployment:<build-id>, or
+   artifact:<digest>), label and target. A preview URL is only a locator.
+   Later revisions name the preceding revision in \`supersedes\`.
+   Send \`response\` events with decisionId, revision, description and
+   \`reported_applied\`, \`reported_adapted\`, or \`reported_rejected\`.
+   Include a concise explicit reason when useful; never provide private reasoning.
+   Agent reports and agent-run checks are labelled **Agent reported**, not
+   independent verification. A screenshot is an artifact, not a passed check.
+   Use \`superhands_add_trace_artifact\` for available images or evidence links,
+   with their route, viewport and UI state. Missing capture capability is a gap;
+   it must not stop coding. Never invent a before image or an unguided baseline.
+   Read \`superhands_get_trace\` before responding to designer feedback. Feedback
+   belongs to its reviewed revision. After addressing it, register the new output
+   and send a \`ready\` event naming feedbackId; only the designer may approve.
+   Report interrupted/failed/resumed lifecycle explicitly; to resume a terminal
+   run, read and supersede its lifecycleId. Later outputs do not inherit approval.
+   If trace recording fails, report that gap and continue the coding task.
+
+6. When you finish a part, call \`superhands_report_part\` with \`part\` \u2014 the
    part you just finished, in the words you fetched it under \u2014 and
    \`instructionChanges\`: for each Instruction you built that part to, its key
    exactly as it was handed to you and one line on the concrete change it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Connect the coding agents on this machine to your team's Superhands MCP server — with `start`, from a machine that has no Superhands account at all. Refresh it later with `update` (no token needed), and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
   "bin": {
     "superhands-connect": "client.mjs"