@super-hands/connect 0.1.21 → 0.1.24

package/client.mjs

@@ -42,7 +42,7 @@ function codexConfigBlock(args) {
 }
 
 // lib/connect-skill.ts
-var CONNECT_SKILL_VERSION = 14;
+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,30 +124,72 @@ 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. As your work reaches files your opening intent never mentioned, call
+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
+   caused there \u2014 \`{ "part": "the form's validation errors",
+   "instructionChanges": [{ "key": "skill#every-view-has-its-states", "change":
+   "kept the typed values and named the failing field" }] }\`. If one caused no
+   change, say that in its line. The run's page shows the line beside that
+   Instruction as it lands, so the person watching sees what each changed
+   while you work rather than only at the end. It records and does not
+   review; a failed call costs the work nothing.
+   - In your working log, say "[part] reported" when it returns.
+   - If that tool is not available on this server, skip this step; the
+     closing report below carries the same lines.
+6. As your work reaches files your opening intent never mentioned, call
    \`superhands_possible_misses\` with the \`paths\` you are actually in. It is
    a free, instant, advisory list of checks those files usually need \u2014 not a
    review, not a gate \u2014 so call it as the work moves and once before your
    summary, passing \`handled\` for anything you already covered.
-6. When you have finished \u2014 not part-way through \u2014 send the files you wrote or
-   changed with \`superhands_report_completed_build\`, naming the \`route\` if
-   you know it, and \`instructionChanges\`: for each Instruction you were
-   handed up front or picked up during the work, its key exactly as it was
-   handed to you and one line on the concrete change it caused in what you
-   built \u2014 \`{ "key": "skill#every-view-has-its-states", "change": "added
-   loading, empty and error states to the orders table" }\`. If one caused no
-   change, say that in its line rather than leaving it out. The team looks at
-   what their agents build there and reads those lines as your words; it
+7. When you have finished \u2014 not part-way through \u2014 say so with
+   \`superhands_report_completed_build\`, naming the \`route\` if you know it,
+   and \`instructionChanges\`: for each Instruction you were handed up front
+   or picked up during the work, its key exactly as it was handed to you and
+   one line on the concrete change it caused in what you built \u2014 \`{ "key":
+   "skill#every-view-has-its-states", "change": "added loading, empty and
+   error states to the orders table" }\`. Do not send your code: there is no
+   field for files, and the report is your account of the build rather than a
+   copy of it. Repeat the lines you reported per part where they still hold,
+   and add one for anything you were handed and never reported. If one caused
+   no change, say that in its line rather than leaving it out. The team sees
+   there that the work is done and reads those lines as your words; it
    records and does not review, so a failed report costs the work nothing. A
-   successful response ends with the run's Instructions receipt; include it
-   once in your final response so the person can see what was handed over up
-   front, picked up during the work, or only named for later, and what you
-   reported each changed. It is context provenance, not proof that anything
-   was applied.
-7. In that final response, state the same concrete output change each
+   successful response ends with
+   the run's Instructions receipt; include it once in your final response so
+   the person can see what was handed over up front, picked up during the
+   work, or only named for later, and what you reported each changed. It is
+   context provenance, not proof that anything was applied.
+8. In that final response, state the same concrete output change each
    picked-up Instruction caused, in your own words. This is your account of the
    work, not a Superhands review or verification.
-8. When you finish, say you followed the team's Instructions \u2014 never that your
+9. When you finish, say you followed the team's Instructions \u2014 never that your
    work was checked. Reading Instructions is not a check, reporting a build is
    not a review, and nothing has looked at what you built.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.21",
+  "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"