@brunosps00/dev-workflow 1.1.2 → 1.2.0

package/scaffold/scripts/lib/resolve-browser.mjs

@@ -3,26 +3,23 @@
 // Resolves which browser to drive for dev-workflow's browser-automation flows
 // (dw-qa, dw-functional-doc, dw-redesign-ui), with WSL resilience.
 //
-// Resolution order: env BROWSER_TEST -> .dw/config.json (browserTest) -> auto-detect.
-// On WSL with no explicit config, auto-detects a Windows browser (Edge first, then
-// Chrome) and launches it in remote-debugging mode so flows connect over CDP instead
-// of opening WSLg / losing layout fidelity in the bundled Linux Chromium.
+// Resolution order: Playwright Chromium primary -> optional CDP fallback from env
+// BROWSER_TEST or .dw/config.json (browserTest).
 //
 // Returns one of:
-//   { mode: "cdp",    endpoint, source, cleanup }   // connect over CDP (browser ready)
-//   { mode: "launch", launchOptions, source }        // let Playwright launch the browser
+//   { mode: "launch", launchOptions, source, fallback?, openFallback? } // let Playwright launch first
+//   { mode: "cdp",    endpoint, source, cleanup }                       // resolved fallback descriptor
 //
-// DEFAULT (no BROWSER_TEST): the full Playwright Chromium in headless via
-// channel:"chromium", which uses the new headless mode (desktop-faithful rendering,
-// not the lighter headless-shell) and never opens WSLg. This is the robust default on
-// WSL. Set BROWSER_TEST to opt into a Windows browser.
+// DEFAULT: full Playwright Chromium in headless via channel:"chromium", which uses the
+// new headless mode (desktop-faithful rendering, not the lighter headless-shell) and
+// never opens WSLg. BROWSER_TEST can provide a CDP/Windows-browser fallback when the
+// primary Playwright launch fails.
 //
 // NOTE on WSL networking: the Chromium debug port binds Windows loopback only. In mirrored
 // networking mode WSL shares that loopback, so 127.0.0.1 connects directly. In NAT mode the
-// helper starts the prebuilt cdp-relay.exe on Windows (0.0.0.0:<fixed port> -> 127.0.0.1:debug)
-// and connects via the Windows host gateway. That needs the one-time setup performed by
-// `npx @brunosps00/dev-workflow setup-wsl-browser` (installs the prebuilt relay + adds the Hyper-V firewall
-// rule). Without it, the helper falls back to the local headless Chromium.
+// helper starts the prebuilt cdp-relay.exe on Windows in reverse mode: the Windows process
+// connects outbound to a WSL broker, and Playwright connects to a local WSL proxy. The one-time
+// setup only installs the relay in the Windows user profile; no admin/firewall rule is needed.
 
 import fs from "node:fs";
 import net from "node:net";
@@ -35,6 +32,8 @@ const BUNDLED_LAUNCH = { channel: "chromium" };
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const dedupe = (items) => [...new Set(items.filter(Boolean))];
+const REVERSE_RELAY_POOL = 8;
+const CLIENT_WAIT_TIMEOUT_MS = 5000;
 
 export function detectWsl() {
   if (process.env.WSL_DISTRO_NAME) {
@@ -96,6 +95,42 @@ function getFreePort() {
   });
 }
 
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve(server.address().port);
+    };
+    server.once("error", onError);
+    server.listen(port, host, onListening);
+  });
+}
+
+function removeItem(items, item) {
+  const index = items.indexOf(item);
+  if (index >= 0) items.splice(index, 1);
+}
+
+function destroyQuietly(item) {
+  try {
+    item.destroy();
+  } catch {
+    // ignore
+  }
+}
+
+function closeServerQuietly(server) {
+  try {
+    server.close();
+  } catch {
+    // ignore
+  }
+}
+
 function windowsHostIp() {
   // In WSL2 NAT mode the Windows host is the default-route gateway (the vEthernet
   // adapter), NOT the /etc/resolv.conf nameserver (which can be a DNS-tunneling proxy
@@ -120,6 +155,27 @@ function windowsHostIp() {
   return null;
 }
 
+function wslBrokerHosts() {
+  const hosts = ["127.0.0.1"];
+  try {
+    const out = spawnSync("ip", ["-4", "-o", "addr", "show", "dev", "eth0", "scope", "global"], { encoding: "utf8" }).stdout ?? "";
+    const match = out.match(/\binet\s+([0-9.]+)\//);
+    if (match) hosts.push(match[1]);
+  } catch {
+    // ignore
+  }
+  if (hosts.length === 1) {
+    try {
+      const out = spawnSync("hostname", ["-I"], { encoding: "utf8" }).stdout ?? "";
+      const fallback = out.split(/\s+/).find((ip) => /^[0-9.]+$/.test(ip) && !ip.startsWith("127."));
+      if (fallback) hosts.push(fallback);
+    } catch {
+      // ignore
+    }
+  }
+  return dedupe(hosts);
+}
+
 function httpGetJson(url, timeoutMs = 1000) {
   return new Promise((resolve) => {
     const request = http.get(url, { timeout: timeoutMs }, (response) => {
@@ -190,21 +246,19 @@ function windowsTempDir() {
   return wslPath ? { winPath, wslPath } : null;
 }
 
-// Fixed port the Windows-side relay listens on, so a single Hyper-V firewall rule covers it.
-const DEFAULT_RELAY_PORT = 39222;
-
 function relayPort(projectRoot) {
   const fromEnv = Number(process.env.DW_RELAY_PORT);
-  if (fromEnv) return fromEnv;
+  if (Number.isInteger(fromEnv) && fromEnv > 0 && fromEnv < 65536) return fromEnv;
   if (projectRoot) {
     try {
       const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, ".dw", "config.json"), "utf8"));
-      if (Number(cfg?.relayPort)) return Number(cfg.relayPort);
+      const fromConfig = Number(cfg?.relayPort);
+      if (Number.isInteger(fromConfig) && fromConfig > 0 && fromConfig < 65536) return fromConfig;
     } catch {
       // ignore
     }
   }
-  return DEFAULT_RELAY_PORT;
+  return 0;
 }
 
 // The prebuilt Windows relay (cdp-relay.exe), installed by `setup-wsl-browser`. Order:
@@ -237,13 +291,183 @@ function findRelayExe(projectRoot) {
   return null;
 }
 
+async function startReverseRelayBroker({ relay, debugPort, projectRoot }) {
+  const idleRelays = [];
+  const pendingClients = [];
+  const relaySockets = [];
+  const localSockets = [];
+  const relayChildren = [];
+  const relayWaiters = [];
+  let closed = false;
+
+  const notifyRelayReady = () => {
+    while (idleRelays.length > 0 && relayWaiters.length > 0) {
+      const waiter = relayWaiters.shift();
+      clearTimeout(waiter.timer);
+      waiter.resolve(true);
+    }
+  };
+
+  const waitForRelayReady = (timeoutMs) => {
+    if (idleRelays.length > 0) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const waiter = { resolve, timer: null };
+      waiter.timer = setTimeout(() => {
+        removeItem(relayWaiters, waiter);
+        resolve(false);
+      }, timeoutMs);
+      relayWaiters.push(waiter);
+    });
+  };
+
+  const removePendingClient = (pending) => {
+    clearTimeout(pending.timer);
+    removeItem(pendingClients, pending);
+  };
+
+  const pairSockets = (client, relaySocket) => {
+    const closePair = () => {
+      destroyQuietly(client);
+      destroyQuietly(relaySocket);
+    };
+    client.on("error", closePair);
+    relaySocket.on("error", closePair);
+    client.on("close", () => destroyQuietly(relaySocket));
+    relaySocket.on("close", () => destroyQuietly(client));
+    relaySocket.write("GO\n", (error) => {
+      if (error) closePair();
+    });
+    client.pipe(relaySocket);
+    relaySocket.pipe(client);
+  };
+
+  const drainPending = () => {
+    while (pendingClients.length > 0 && idleRelays.length > 0) {
+      const pending = pendingClients.shift();
+      clearTimeout(pending.timer);
+      const relaySocket = idleRelays.shift();
+      if (pending.client.destroyed || relaySocket.destroyed) {
+        destroyQuietly(pending.client);
+        destroyQuietly(relaySocket);
+        continue;
+      }
+      pairSockets(pending.client, relaySocket);
+    }
+  };
+
+  const brokerServer = net.createServer((socket) => {
+    if (closed) {
+      socket.destroy();
+      return;
+    }
+    socket.setNoDelay(true);
+    relaySockets.push(socket);
+    idleRelays.push(socket);
+    socket.on("error", () => destroyQuietly(socket));
+    socket.on("close", () => {
+      removeItem(relaySockets, socket);
+      removeItem(idleRelays, socket);
+    });
+    notifyRelayReady();
+    drainPending();
+  });
+
+  const localServer = net.createServer((client) => {
+    if (closed) {
+      client.destroy();
+      return;
+    }
+    client.setNoDelay(true);
+    localSockets.push(client);
+    client.on("close", () => removeItem(localSockets, client));
+    client.on("error", () => destroyQuietly(client));
+    const pending = {
+      client,
+      timer: setTimeout(() => {
+        removePendingClient(pending);
+        destroyQuietly(client);
+      }, CLIENT_WAIT_TIMEOUT_MS),
+    };
+    client.on("close", () => removePendingClient(pending));
+    pendingClients.push(pending);
+    drainPending();
+  });
+
+  const cleanup = async () => {
+    closed = true;
+    for (const waiter of relayWaiters.splice(0)) {
+      clearTimeout(waiter.timer);
+      waiter.resolve(false);
+    }
+    for (const pending of pendingClients.splice(0)) {
+      clearTimeout(pending.timer);
+      destroyQuietly(pending.client);
+    }
+    for (const socket of [...localSockets, ...relaySockets]) destroyQuietly(socket);
+    for (const child of relayChildren) {
+      try {
+        child.kill();
+      } catch {
+        // ignore
+      }
+    }
+    closeServerQuietly(localServer);
+    closeServerQuietly(brokerServer);
+  };
+
+  let localPort;
+  let brokerPort;
+  try {
+    localPort = await listen(localServer, relayPort(projectRoot), "127.0.0.1");
+    brokerPort = await listen(brokerServer, 0, "0.0.0.0");
+  } catch (error) {
+    await cleanup();
+    throw new Error(`Could not start the WSL reverse relay broker: ${error.message}`);
+  }
+
+  let selectedHost = null;
+  for (const brokerHost of wslBrokerHosts()) {
+    const child = spawn(
+      relay.wslPath,
+      ["--reverse", brokerHost, String(brokerPort), String(debugPort), String(REVERSE_RELAY_POOL)],
+      { detached: true, stdio: "ignore" },
+    );
+    relayChildren.push(child);
+    child.unref();
+
+    if (await waitForRelayReady(brokerHost === "127.0.0.1" ? 1800 : 3000)) {
+      selectedHost = brokerHost;
+      break;
+    }
+
+    try {
+      child.kill();
+    } catch {
+      // ignore
+    }
+  }
+
+  if (!selectedHost) {
+    await cleanup();
+    throw new Error(
+      "WSL is in NAT mode, but the Windows relay could not connect back to the WSL broker. " +
+        "Run `npx @brunosps00/dev-workflow setup-wsl-browser` to reinstall the relay, or enable mirrored networking.",
+    );
+  }
+
+  return {
+    hosts: ["127.0.0.1", "localhost"],
+    port: localPort,
+    relayHost: selectedHost,
+    cleanup,
+  };
+}
+
 // Launches the Windows browser in remote-debugging mode and returns a CDP descriptor.
 // - mirrored networking: WSL shares the Windows loopback (Hyper-V LoopbackEnabled), connect 127.0.0.1.
-// - NAT networking: the prebuilt cdp-relay.exe bridges 0.0.0.0:<relayPort> -> 127.0.0.1:<debug> on the
-//   Windows side, and WSL connects via the Windows host gateway. This needs a one-time Hyper-V firewall
-//   inbound rule for <relayPort> (added by `setup-wsl-browser`), because WSL's Hyper-V firewall defaults
-//   inbound to Block. The browser echoes the request Host into webSocketDebuggerUrl, so the ws stays
-//   reachable through the relay.
+// - NAT networking: the prebuilt cdp-relay.exe runs on Windows in reverse mode. It connects outbound
+//   to a WSL broker, which exposes a local proxy for Playwright. The browser echoes the request Host
+//   into webSocketDebuggerUrl, so the ws stays reachable through the local proxy.
 // --remote-allow-origins=* is required or Chromium drops the DevTools ws (anti-DNS-rebinding).
 async function launchWindowsBrowser(exePath, { headless, projectRoot }) {
   const mirrored = isMirroredNetworking();
@@ -282,58 +506,85 @@ async function launchWindowsBrowser(exePath, { headless, projectRoot }) {
     }
   };
 
-  let hosts;
-  let port;
-  if (mirrored) {
-    hosts = ["127.0.0.1", "localhost"];
-    port = debugPort;
-  } else {
-    const relay = findRelayExe(projectRoot);
-    if (!relay) {
-      await cleanup();
+  try {
+    let hosts;
+    let port;
+    let sourceSuffix = "";
+    if (mirrored) {
+      hosts = ["127.0.0.1", "localhost"];
+      port = debugPort;
+    } else {
+      const relay = findRelayExe(projectRoot);
+      if (!relay) {
+        throw new Error(
+          "WSL is in NAT mode; reaching the Windows browser needs cdp-relay.exe. Run " +
+            "`npx @brunosps00/dev-workflow setup-wsl-browser` to install the prebuilt relay in your Windows user profile. " +
+            "Alternatively enable mirrored networking or set BROWSER_TEST to a CDP URL.",
+        );
+      }
+      const reverseRelay = await startReverseRelayBroker({ relay, debugPort, projectRoot });
+      cleanups.unshift(reverseRelay.cleanup);
+      hosts = reverseRelay.hosts;
+      port = reverseRelay.port;
+      sourceSuffix = "+reverse-relay";
+    }
+
+    const found = await waitForCdp(hosts, port);
+    if (!found) {
       throw new Error(
-        "WSL is in NAT mode; reaching the Windows browser needs cdp-relay.exe. Run " +
-          "`npx @brunosps00/dev-workflow setup-wsl-browser` (installs the prebuilt relay and adds the " +
-          "Hyper-V firewall rule). Alternatively enable mirrored networking or set BROWSER_TEST to a CDP URL.",
+        `Launched ${path.basename(exePath)} but its CDP endpoint was not reachable (${hosts.join("/")}:${port}). ` +
+          "Run `npx @brunosps00/dev-workflow setup-wsl-browser` to reinstall the user-level relay, or enable mirrored networking.",
       );
     }
-    const rport = relayPort(projectRoot);
-    const relayChild = spawn(relay.wslPath, [String(rport), String(debugPort)], { detached: true, stdio: "ignore" });
-    relayChild.unref();
-    cleanups.unshift(() => relayChild.kill());
-    hosts = [windowsHostIp(), "127.0.0.1"].filter(Boolean);
-    port = rport;
-  }
 
-  const found = await waitForCdp(hosts, port);
-  if (!found) {
+    return { mode: "cdp", endpoint: found.base, source: `launched:${path.basename(exePath)}${sourceSuffix}`, cleanup };
+  } catch (error) {
     await cleanup();
-    throw new Error(
-      `Launched ${path.basename(exePath)} but its CDP endpoint was not reachable (${hosts.join("/")}:${port}). ` +
-        "The Hyper-V firewall rule may be missing — run `npx @brunosps00/dev-workflow setup-wsl-browser`.",
-    );
+    throw error;
   }
-
-  return { mode: "cdp", endpoint: found.base, source: `launched:${path.basename(exePath)}${mirrored ? "" : "+relay"}`, cleanup };
 }
 
 const noopCleanup = async () => {};
 
-function bundledDescriptor(headless, source = "bundled") {
+function bundledDescriptor(headless, source = "playwright-default") {
   return { mode: "launch", launchOptions: { ...BUNDLED_LAUNCH, headless }, source };
 }
 
-// When an explicit BROWSER_TEST cannot be honored, degrade to the headless default
-// (resilient) unless allowFallback is false (then throw, e.g. for diagnostics).
-function degradeOrThrow(message, { headless, allowFallback }) {
-  if (allowFallback) {
-    process.stderr.write(`resolve-browser: ${message} Falling back to headless Chromium.\n`);
-    return bundledDescriptor(headless, "fallback");
+function cdpFallbackInfo({ kind, source, value }) {
+  return { mode: "cdp", kind, source, value };
+}
+
+async function resolveCdpFallback({ kind, value, source, projectRoot, headless }) {
+  if (kind === "cdp") {
+    const url = new URL(value.replace(/^cdp:\/\//i, "http://"));
+    const port = Number(url.port) || 9222;
+    const found = await findReachableCdp(port, [url.hostname]);
+    if (!found) {
+      throw new Error(`CDP fallback '${value}' is not reachable (start the browser with --remote-debugging-port=${port}).`);
+    }
+    return { mode: "cdp", endpoint: found.base, source: `fallback:${source}`, cleanup: noopCleanup };
+  }
+
+  if (kind === "exe") {
+    if (!fs.existsSync(value)) {
+      throw new Error(`CDP fallback points to '${value}', but that file does not exist.`);
+    }
+    const descriptor = await launchWindowsBrowser(value, { headless, projectRoot });
+    return { ...descriptor, source: `fallback:${descriptor.source}` };
   }
-  throw new Error(message);
+
+  throw new Error(`Unsupported CDP fallback kind '${kind}'.`);
+}
+
+function withCdpFallback(primary, fallbackArgs) {
+  return {
+    ...primary,
+    fallback: cdpFallbackInfo(fallbackArgs),
+    openFallback: () => resolveCdpFallback(fallbackArgs),
+  };
 }
 
-export async function resolveBrowser({ projectRoot, headless = true, allowFallback = true } = {}) {
+export async function resolveBrowser({ projectRoot, headless = true } = {}) {
   const { value, source } = readConfigValue(projectRoot);
 
   if (!value) {
@@ -343,30 +594,11 @@ export async function resolveBrowser({ projectRoot, headless = true, allowFallba
   const kind = classifyValue(value);
 
   if (kind === "cdp") {
-    const url = new URL(value.replace(/^cdp:\/\//i, "http://"));
-    const port = Number(url.port) || 9222;
-    const found = await findReachableCdp(port, [url.hostname]);
-    if (!found) {
-      return degradeOrThrow(
-        `BROWSER_TEST endpoint '${value}' is not reachable (start the browser with --remote-debugging-port=${port}).`,
-        { headless, allowFallback },
-      );
-    }
-    return { mode: "cdp", endpoint: found.base, source, cleanup: noopCleanup };
+    return withCdpFallback(bundledDescriptor(headless), { kind, value, source, projectRoot, headless });
   }
 
   if (kind === "exe") {
-    if (!fs.existsSync(value)) {
-      return degradeOrThrow(`BROWSER_TEST points to '${value}', but that file does not exist.`, {
-        headless,
-        allowFallback,
-      });
-    }
-    try {
-      return await launchWindowsBrowser(value, { headless, projectRoot });
-    } catch (error) {
-      return degradeOrThrow(error.message, { headless, allowFallback });
-    }
+    return withCdpFallback(bundledDescriptor(headless), { kind, value, source, projectRoot, headless });
   }
 
   // channel: chrome | msedge | chromium

package/scaffold/skill-registry.json

@@ -240,7 +240,7 @@
       "trigger": "Security review, sensitive code, OWASP checks, auth/payment/input surfaces",
       "expected_output": "High-confidence security findings or explicit pass.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 14000,
       "bundled": true
     },
     {

package/scaffold/skills/api-testing-recipes/SKILL.md

@@ -102,3 +102,15 @@ Per-recipe details in `references/auth-patterns.md`.
 ## Inspired by
 
 Hand-curated by dev-workflow. `.http` syntax follows the JetBrains HTTP Client / VSCode REST Client conventions. Per-stack recipes adapt patterns from each ecosystem's official testing docs (FastAPI testing tutorial, NestJS testing recipes, Microsoft.AspNetCore.Mvc.Testing docs, Axum testing examples).
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when a recipe and evidence path are selected, `FINDINGS` when API test gaps remain, `BLOCKED` when the stack or auth flow is unknown, `NOT_APPLICABLE` when no HTTP/API surface is in scope.
+- **Scope:** API surface, requirement/RF, auth mode, and selected recipe.
+- **Evidence:** route/schema/source files read and request/response logs or planned log path.
+- **Artifacts:** `.http` file, test file, matrix, or log path to create/update.
+- **Decisions:** why this recipe fits the stack and why alternatives were rejected.
+- **Risks:** credentials, environment dependencies, flaky external calls, or uncovered negative cases.
+- **Next Step:** exact command or file edit needed to execute the recipe.

package/scaffold/skills/docker-compose-recipes/SKILL.md

@@ -82,3 +82,15 @@ Each row points to `services/<name>.yml`.
 ## Inspired by
 
 Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `redis`, `mailhog/mailhog`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when service recipes and compose guidance are selected, `FINDINGS` when compose gaps remain, `BLOCKED` when required ports/secrets/envs are unknown, `NOT_APPLICABLE` when no local infrastructure service is in scope.
+- **Scope:** services, project mode (`dev`/`prod`), ports, volumes, and env files touched.
+- **Evidence:** existing compose files, service references, healthcheck needs, and conflicting ports.
+- **Artifacts:** compose snippets/files, `.env` keys, healthchecks, and follow-up reference files.
+- **Decisions:** selected service recipe, image tag policy, and any prod/dev transform.
+- **Risks:** secret leakage, readiness ambiguity, data persistence, mail routing, or destructive defaults.
+- **Next Step:** exact compose edit and validation command.

package/scaffold/skills/dw-codebase-intel/SKILL.md

@@ -11,7 +11,7 @@ allowed-tools:
 
 # dw-codebase-intel
 
-Bundled skill that gives dev-workflow native **codebase intelligence** — a queryable knowledge base of the project's stack, file graph, API surface, dependencies, and architecture. Other commands (`/dw-plan prd`, `/dw-plan techspec`, `/dw-review --code-only`, `/dw-brainstorm --refactor`, `/dw-brainstorm`, etc.) read from this index instead of re-exploring the codebase on every invocation.
+Bundled skill that gives dev-workflow native **codebase intelligence** — a queryable knowledge base of the project's stack, file graph, API surface, dependencies, and architecture. Other commands (`/dw-plan prd`, `/dw-plan techspec`, `/dw-review --code-only`, `/dw-opportunities`, `/dw-refactor`, `/dw-brainstorm`, etc.) read from this index instead of re-exploring the codebase on every invocation.
 
 ## Why a skill (not inline)
 
@@ -111,3 +111,15 @@ If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded
 Adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`gsd-intel-updater`) by gsd-build (MIT license). Core schemas (`files.json`, `apis.json`, `deps.json`, `stack.json`, `arch.md`) and incremental update protocol preserved. Path conventions changed from `.planning/intel/` to `.dw/intel/`. CLI tooling (`gsd-sdk query intel.*`) replaced by agent-driven inline operations (no separate runtime). The companion `gsd-codebase-mapper` agent (human-readable analysis docs) was NOT ported — its scope overlaps with the existing `/dw-analyze-project` command which writes to `.dw/rules/`.
 
 The `bugfixes.json` index and the `bugfix-history` / `risk-area` query shapes (see `references/query-patterns.md`) were added in v1.0.2 to enable cross-skill awareness of `.dw/bugfixes/` — adapted from the operational-memory pattern in [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). The original skill maintains a single `STATE.md`; dev-workflow splits this into project-level `.dw/STATE.md` (session continuity) and a queryable `bugfixes.json` (historical fixes), which compose with the existing per-PRD `MEMORY.md`.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when indexes are updated or the query answer is cited, `FINDINGS` when intel is stale/incomplete, `BLOCKED` when required project files cannot be read, `NOT_APPLICABLE` when the task does not need codebase intel.
+- **Scope:** index files, query type, module, and paths inspected.
+- **Evidence:** cited `.dw/intel/*` entries, source files, timestamps, or stale-index indicators.
+- **Artifacts:** updated index files, query answer, codemap, or bugfix index path.
+- **Decisions:** whether to rebuild, incrementally update, or answer from existing intel.
+- **Risks:** stale docs, missing generated files, broad reads, or uncited conclusions.
+- **Next Step:** exact index update, query refinement, or source read required.

package/scaffold/skills/dw-context-budget/SKILL.md

@@ -43,3 +43,15 @@ Return:
 5. What must remain loaded because commands depend on it.
 
 Inspired by ECC's `context-budget` and `strategic-compact` patterns; adapted for dev-workflow's `.dw/` scaffold and cross-platform wrappers.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when the budget is acceptable, `FINDINGS` when concrete savings exist, `BLOCKED` when files cannot be measured, `NOT_APPLICABLE` when context budget is not relevant.
+- **Scope:** commands, skills, agents, MCPs, and instruction files measured.
+- **Evidence:** largest files, duplicate content, loaded references, and approximate byte/token cost.
+- **Artifacts:** report path or inline budget table.
+- **Decisions:** what stays loaded, what moves behind lazy references, and what can merge/remove.
+- **Risks:** losing trigger clarity, hiding required instructions, or creating stale references.
+- **Next Step:** top compaction action with expected savings.

package/scaffold/skills/dw-council/SKILL.md

@@ -180,3 +180,15 @@ Adaptations for dev-workflow:
 - Integration points map to dev-workflow commands (`dw-brainstorm`, `dw-create-techspec`) instead of Compozy's idea-factory pipeline
 
 Credit: Compozy project (https://github.com/compozy/compozy).
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when advisor positions and a recommendation are complete, `FINDINGS` when unresolved tensions remain, `BLOCKED` when inputs or constraints are missing, `NOT_APPLICABLE` when no high-impact tradeoff exists.
+- **Scope:** decision, constraints, advisors consulted, and artifact path.
+- **Evidence:** each advisor's cited position and the facts they used.
+- **Artifacts:** council report, debate notes, or decision summary path.
+- **Decisions:** recommended path, rejected alternatives, and what would change the call.
+- **Risks:** unresolved disagreement, missing stakeholder data, or unvalidated assumptions.
+- **Next Step:** concrete follow-up: accept, run experiment, gather data, or escalate.

package/scaffold/skills/dw-debug-protocol/SKILL.md

@@ -106,3 +106,15 @@ After 60 minutes stuck at step 2 (localize) or step 4 (root cause), surface the
 - Don't silently spin. Fresh eyes find what stuck eyes miss.
 
 This is not failure — it's protocol. Stuck > 1 hour is a signal, not a flaw.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when the bug is reproduced, root-caused, guarded, and verified, `FINDINGS` when a confirmed defect remains, `BLOCKED` when reproduction/localization is impossible, `NOT_APPLICABLE` when the task is not bug-shaped.
+- **Scope:** symptom, affected surface, environment, and triage step reached.
+- **Evidence:** reproduction command, failing output, localized files, and root-cause proof.
+- **Artifacts:** bugfix task/report, regression test, logs, or verification output.
+- **Decisions:** chosen fix path and rejected hypotheses.
+- **Risks:** non-reproducibility, partial guard coverage, rollback gaps, or hidden adjacent defects.
+- **Next Step:** next triage step or verification command.

package/scaffold/skills/dw-execute-phase/SKILL.md

@@ -131,3 +131,15 @@ If the executor exhausts its context budget mid-phase OR the user signals stop:
 ## Inspired by
 
 Adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`gsd-executor`, `gsd-plan-checker`) by gsd-build (MIT license). Core protocols (goal-backward verification, atomic commits, deviation handling, checkpoint resume) preserved. Path conventions changed from `.planning/<phase>/` to `.dw/spec/prd-<slug>/`. SDK CLI calls (`gsd-sdk query init.execute-phase`) replaced by inline operations. The companion `gsd-debugger` agent (1452 lines) was NOT ported — its scope overlaps with the existing `/dw-bugfix` and `/dw-qa --fix` commands.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when plan-check and execution wave complete, `FINDINGS` when deviations or failed tasks remain, `BLOCKED` when plan-check returns `REVISE`/`BLOCK`, `NOT_APPLICABLE` when no task execution is in scope.
+- **Scope:** PRD/spec slug, wave, tasks, dependencies, and agent roles.
+- **Evidence:** plan-check verdict, task files read, command outputs, and deviation notes.
+- **Artifacts:** changed files, task memory, checkpoint, deviations report, or commits.
+- **Decisions:** wave ordering, task split, and accepted deviations.
+- **Risks:** dependency drift, uncommitted work, skipped verification, or partial checkpoint.
+- **Next Step:** next task, commit, checkpoint, or revision needed.

package/scaffold/skills/dw-git-discipline/SKILL.md

@@ -121,3 +121,15 @@ Real-world software can't always be perfect:
 - [ ] No `--no-verify`
 - [ ] No amend of pushed commit
 - [ ] Branch name follows convention
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when the commit/PR plan is atomic and verified, `FINDINGS` when git hygiene gaps remain, `BLOCKED` when repository state is ambiguous, `NOT_APPLICABLE` when no git action is in scope.
+- **Scope:** branch, staged/unstaged files, intended commit/PR, and remote state.
+- **Evidence:** `git status`, diff summary, verification commands, and branch checks.
+- **Artifacts:** commit plan, commit hash, PR body, or branch hygiene report.
+- **Decisions:** commit split, message type/scope, and files intentionally excluded.
+- **Risks:** unrelated dirty files, skipped checks, pushed-history rewrite, or mixed intent.
+- **Next Step:** exact stage/commit/push/PR command or cleanup action.

package/scaffold/skills/dw-incident-response/SKILL.md

@@ -166,3 +166,15 @@ Files are committed to the repo alongside code — incidents are part of the pro
 ## Why this skill exists
 
 dev-workflow's existing surface is "build feature → ship." Nothing covered "production broke, what now?" Teams improvised postmortems, action items got lost, and the same bug recurred. This skill closes that loop: structured response in the moment, blameless reflection after, and cross-incident learning that feeds back into the project's constitution.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when incident triage, resolution, comms, and follow-up are complete, `FINDINGS` when incident work remains, `BLOCKED` when severity/ownership/evidence is missing, `NOT_APPLICABLE` when no incident workflow is in scope.
+- **Scope:** incident id, severity, service, timeline window, and owner.
+- **Evidence:** symptoms, customer impact, logs/metrics, mitigation, and verification.
+- **Artifacts:** incident files, communication draft, action items, or postmortem path.
+- **Decisions:** severity, mitigation path, rollback/fix choice, and communication cadence.
+- **Risks:** recurring cause, incomplete customer notice, weak action items, or missing monitoring.
+- **Next Step:** next incident phase or postmortem/action-item owner.