crewly 1.20.435 → 1.20.437

package/config/skills/agent/core/reproduce-ui/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: Reproduce UI
-description: Open a Crewly dashboard feature by its feature-map entry in a headless browser and save evidence (screenshot, console errors, failed requests, timings) before you reproduce or fix a UI bug report.
-version: 1.0.0
+description: Turn a UI bug report (a screenshot and a sentence) into evidence - match it to a feature-map entry, open that feature in a headless browser and save screenshot, console errors, failed requests and timings, plus one line for the ticket - before you reproduce or fix it.
+version: 1.1.0
 category: development
 skillType: claude-skill
 assignableRoles:
@@ -17,6 +17,7 @@ triggers:
   - reproduce
   - screenshot bug
   - UI bug
+  - bug report
   - feature map
 tags:
   - frontend
@@ -39,6 +40,10 @@ for every route how a user reaches it, what it should do and which
 `data-testid` anchors it has; this skill turns one map entry into a run.
 
 ```bash
+# From the bug report: the owner's sentence plus the words you read on the
+# screenshot (headings, tab names, button labels). Picks the feature, runs it.
+bash execute.sh --report "runs tab is blank — Tickets, Board · Requests · Runs"
+
 # By route (tabs go in the query string, as the map shows them)
 bash execute.sh --route "/tickets?tab=runs"
 
@@ -55,20 +60,37 @@ bash execute.sh --feature Usage --dry-run
 What you get back is one JSON line with `dir`: the evidence folder under
 `$CREWLY_HOME/evidence/<utc stamp>-<route>/` holding `screenshot.png`,
 `console.json` (console errors, warnings and page errors), `requests.json`
-(failed requests and responses ≥ 400), `report.md` and `summary.json`.
-Exit 0 means the key element appeared; exit 2 means it did not (the
-evidence is still there — that is the bug, or the wrong selector); exit 1 is
-a usage or browser problem.
+(failed requests and responses ≥ 400), `report.md` and `summary.json`; its
+`ticketLine` is the one line to put in the ticket ("Reproduced `/x`: key
+element NOT found; 1 console error; 2 failed requests (first: POST /api/b →
+500); evidence: <dir>"). Exit 0 means the key element appeared; exit 2 means
+it did not (the evidence is still there — that is the bug, or the wrong
+selector); exit 1 is a usage or browser problem; exit 3 means the report
+matched no single feature (the candidates are on stderr — pass `--route`).
+
+How `--report` matches: every word of the report is looked up in each
+feature's title and **Expected** line (2 points), its route, **Reach** and
+**Elements** (1 point), and its tab names (4 points, and the tab becomes
+`?tab=`). A feature wins with two or more matching words, 3+ points and half
+again as much as the runner-up. The words on the screenshot are what make
+it unambiguous: a report of "blank page" alone matches nothing; "blank page,
+Tickets, Runs" opens `/tickets?tab=runs`. Read the screenshot first and put
+what you see into the report text.
 
 How to use it on a report:
 
-1. Find the feature in the map (the words on the screenshot are usually in
-   a page's **Expected** or **Elements** line). Note its route and `?tab=`.
-2. Run this skill on that route. Compare `screenshot.png` with the owner's
-   screenshot; read `console.json` and `requests.json` first — a failed
-   `/api/...` call explains most blank or stale pages.
-3. Put the `report.md` path (or its key lines) in the ticket, then fix. After
-   the fix, run it again and attach the second folder as proof.
+1. Write the report text: the owner's sentence, then the headings, tab
+   names and labels you can read on the screenshot. Run `--report` with it
+   (or `--report-file`). If it exits 3, pick the route from the candidates it
+   printed and run `--route`.
+2. Compare `screenshot.png` with the owner's screenshot; read `console.json`
+   and `requests.json` first — a failed `/api/...` call explains most blank
+   or stale pages. `report.md` quotes the report and says which words chose
+   the feature, so a wrong match is visible at a glance.
+3. Put `ticketLine` in the ticket (the evidence folder stays on this
+   machine; quote the folder path and the key lines, not the files), then
+   fix. After the fix, run it again and put the second line under the first
+   as proof.
 
 Notes:
 

package/config/skills/agent/core/reproduce-ui/execute.sh

@@ -21,11 +21,15 @@ print_usage() {
 Usage:
   bash execute.sh --route /tickets?tab=runs                 Open a route, wait for its key element, save evidence
   bash execute.sh --feature "Run detail" --param id=<uuid>   Resolve the route from the feature map
+  bash execute.sh --report "runs tab is blank, Tickets"      Match a bug report to a feature, then run it
   bash execute.sh --route /wiki --wait '[data-testid="wiki-recent-list"]' --full-page
 
 Options:
   --route      Path to open (with ?tab= when the page has tabs)
   --feature    A route or a word from a Routes row of FEATURE_MAP.md (needs the map)
+  --report     A bug report: the owner's sentence plus the words you read on the
+               screenshot; scored against the map's Features (needs the map)
+  --report-file  The same, read from a file
   --param k=v  Value for a :param in the route (repeatable)
   --wait       CSS selector to wait for (default: the feature's first data-testid, else body)
   --map        FEATURE_MAP.md path (default: <project>/frontend/FEATURE_MAP.md when present)
@@ -38,17 +42,20 @@ Options:
   --help | -h  Show this help
 
 Output: one JSON line with the evidence folder (screenshot.png, console.json,
-requests.json, report.md, summary.json). Exit 0 when the element appeared, 2
-when it did not (evidence still saved), 1 on a usage or browser error.
+requests.json, report.md, summary.json; summary.ticketLine is the line to put
+in the ticket). Exit 0 when the element appeared, 2 when it did not (evidence
+still saved), 1 on a usage or browser error, 3 when the report matches no
+single feature (candidates on stderr; pass --route).
 EOF_USAGE
 }
 
-ROUTE=""; FEATURE=""; WAIT=""; MAP=""; BASE_URL=""; OUT=""; TIMEOUT=""; FULL_PAGE=""; BROWSER=""; DRY_RUN=""
+ROUTE=""; FEATURE=""; REPORT=""; WAIT=""; MAP=""; BASE_URL=""; OUT=""; TIMEOUT=""; FULL_PAGE=""; BROWSER=""; DRY_RUN=""
 PARAMS=()
 
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
   ROUTE=$(printf '%s' "$1" | jq -r '.route // empty')
   FEATURE=$(printf '%s' "$1" | jq -r '.feature // empty')
+  REPORT=$(printf '%s' "$1" | jq -r '.report // empty')
   WAIT=$(printf '%s' "$1" | jq -r '.wait // empty')
   MAP=$(printf '%s' "$1" | jq -r '.map // empty')
   BASE_URL=$(printf '%s' "$1" | jq -r '.baseUrl // empty')
@@ -64,6 +71,8 @@ while [[ $# -gt 0 ]]; do
   case "$1" in
     --route)     [ $# -ge 2 ] || error_exit "--route requires a value";    ROUTE="$2";    shift 2 ;;
     --feature)   [ $# -ge 2 ] || error_exit "--feature requires a value";  FEATURE="$2";  shift 2 ;;
+    --report)    [ $# -ge 2 ] || error_exit "--report requires text";      REPORT="$2";   shift 2 ;;
+    --report-file) [ $# -ge 2 ] || error_exit "--report-file requires a path"; [ -f "$2" ] || error_exit "--report-file not found: $2"; REPORT="$(cat "$2")"; shift 2 ;;
     --param)     [ $# -ge 2 ] || error_exit "--param requires k=v";        PARAMS+=("$2"); shift 2 ;;
     --wait)      [ $# -ge 2 ] || error_exit "--wait requires a selector";  WAIT="$2";     shift 2 ;;
     --map)       [ $# -ge 2 ] || error_exit "--map requires a path";       MAP="$2";      shift 2 ;;
@@ -78,7 +87,7 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-[ -n "$ROUTE" ] || [ -n "$FEATURE" ] || error_exit "one of --route or --feature is required (--help for usage)"
+[ -n "$ROUTE" ] || [ -n "$FEATURE" ] || [ -n "$REPORT" ] || error_exit "one of --route, --feature or --report is required (--help for usage)"
 command -v node >/dev/null 2>&1 || error_exit "node is required"
 
 # The map: explicit, else the project's checkout, else the package's own copy (a repo install).
@@ -95,6 +104,6 @@ for kv in "${PARAMS[@]+"${PARAMS[@]}"}"; do
   export "RU_PARAM_${key}=${val}"
 done
 
-RU_MAIN=1 RU_ROUTE="$ROUTE" RU_FEATURE="$FEATURE" RU_WAIT="$WAIT" RU_MAP="$MAP" RU_BASE_URL="$BASE_URL" \
+RU_MAIN=1 RU_ROUTE="$ROUTE" RU_FEATURE="$FEATURE" RU_REPORT="$REPORT" RU_WAIT="$WAIT" RU_MAP="$MAP" RU_BASE_URL="$BASE_URL" \
 RU_OUT="$OUT" RU_TIMEOUT_MS="$TIMEOUT" RU_FULL_PAGE="$FULL_PAGE" RU_BROWSER="$BROWSER" RU_DRY_RUN="$DRY_RUN" \
 RU_PKG_ROOT="$PKG_ROOT" node "${SCRIPT_DIR}/reproduce.mjs"

package/config/skills/agent/core/reproduce-ui/execute.test.sh

@@ -34,19 +34,22 @@ cat > "$MAP" <<'EOF_MAP'
 
 ### Dashboard (`/`)
 
+- **Expected**: "Waiting on you" first, then "Crew now" with the health bar.
 - **Elements**: `dashboard`, `crew-now`.
 
 ### Tickets hub (`/tickets`, tabs `board` · `runs`)
 
+- **Expected**: Board = kanban columns; Runs = one row per work item.
 - **Elements**: `tickets-panel-${tab}`, `tickets-page`, `tickets-board`.
 
 ### Run detail (`/tickets/runs/:id`)
 
+- **Expected**: the work item's header, metrics and timeline.
 - **Elements**: `workitem-detail-loading|error|not-found`, `workitem-detail`.
 
 ### Usage (`/usage`)
 
-- **Expected**: one headline.
+- **Expected**: one headline with tokens by team.
 EOF_MAP
 export CREWLY_API_URL="http://127.0.0.1:18799"
 export CREWLY_HOME="$T/home"
@@ -60,7 +63,7 @@ check "help names --feature" "$(printf '%s' "$OUT" | grep -c -- '--feature')" "$
 # ---- no route / feature ----
 ERR=$(bash "$EXEC" --dry-run 2>&1 >/dev/null); RC=$?
 check "no route: exit 1" "$RC" "1"
-check "no route: error says so" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'route or --feature')" "1"
+check "no route: error says so" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'route, --feature or --report')" "1"
 
 # ---- route + map: wait selector from the Elements line; ${} and a|b skipped ----
 OUT=$(bash "$EXEC" --route "/tickets?tab=runs" --map "$MAP" --dry-run)
@@ -113,6 +116,73 @@ OUT=$(bash "$EXEC" '{"route":"/usage","map":"'"$MAP"'","dryRun":true,"params":{"
 check "json input: route" "$(printf '%s' "$OUT" | jq -r .path)" "/usage"
 check "json input: fullPage" "$(printf '%s' "$OUT" | jq -r .fullPage)" "true"
 
+# ---- --report: a bug report matched to a feature (slice 3) ----
+OUT=$(bash "$EXEC" --report "the runs tab under tickets is blank" --map "$MAP" --dry-run)
+check "report: tab word picks the hub with ?tab=" "$(printf '%s' "$OUT" | jq -r .route)" "/tickets?tab=runs"
+check "report: wait = that tab's panel" "$(printf '%s' "$OUT" | jq -r .waitFor)" '[data-testid="tickets-panel-runs"]'
+check "report: match title" "$(printf '%s' "$OUT" | jq -r .match.title)" "Tickets hub"
+check "report: matched words (plural dropped)" "$(printf '%s' "$OUT" | jq -c .match.matched)" '["run","ticket"]'
+check "report: runner-up listed" "$(printf '%s' "$OUT" | jq -r '.match.candidates[0].route')" "/tickets/runs/:id"
+check "report: text kept in the plan" "$(printf '%s' "$OUT" | jq -r .report)" "the runs tab under tickets is blank"
+
+OUT=$(bash "$EXEC" --report "Tokens by team headline missing on the usage page" --map "$MAP" --dry-run)
+check "report: Expected words pick Usage" "$(printf '%s' "$OUT" | jq -r .route)" "/usage"
+
+OUT=$(bash "$EXEC" --report "Waiting on you never loads, Crew now spins" --map "$MAP" --dry-run)
+check "report: Dashboard by its Expected words" "$(printf '%s' "$OUT" | jq -r .route)" "/"
+
+ERR=$(bash "$EXEC" --report "nothing happens at all" --map "$MAP" --dry-run 2>&1 >/dev/null); RC=$?
+check "report with no match: exit 3" "$RC" "3"
+check "report with no match: says so" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'matches no feature')" "1"
+
+ERR=$(bash "$EXEC" --report "tickets" --map "$MAP" --dry-run 2>&1 >/dev/null); RC=$?
+check "one-word report: exit 3" "$RC" "3"
+check "one-word report: asks for more words" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'too weakly')" "1"
+check "one-word report: best candidate first" "$(printf '%s' "$ERR" | jq -r '.candidates[0].route')" "/tickets"
+
+ERR=$(bash "$EXEC" --report "the work item is wrong" --map "$MAP" --dry-run 2>&1 >/dev/null); RC=$?
+check "even report: exit 3" "$RC" "3"
+check "even report: says equally" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'about equally')" "1"
+check "even report: lists candidates" "$(printf '%s' "$ERR" | jq -r '.candidates | length' )" "2"
+
+printf 'runs tab under\ntickets is blank\n' > "$T/report.txt"
+OUT=$(bash "$EXEC" --report-file "$T/report.txt" --map "$MAP" --dry-run)
+check "report-file: same match" "$(printf '%s' "$OUT" | jq -r .route)" "/tickets?tab=runs"
+ERR=$(bash "$EXEC" --report-file "$T/nope.txt" --map "$MAP" --dry-run 2>&1 >/dev/null); RC=$?
+check "report-file missing: exit 1" "$RC" "1"
+
+OUT=$(bash "$EXEC" '{"report":"runs tab under tickets","map":"'"$MAP"'","dryRun":true}')
+check "json input: report" "$(printf '%s' "$OUT" | jq -r .route)" "/tickets?tab=runs"
+
+OUT=$(bash "$EXEC" --route /usage --report "runs tab under tickets" --map "$MAP" --dry-run)
+check "route beats report" "$(printf '%s' "$OUT" | jq -r .route)" "/usage"
+check "route beats report: no match block" "$(printf '%s' "$OUT" | jq -r .match)" "null"
+
+ERR=$(bash "$EXEC" --report "runs tab" --map "$T/missing.md" --dry-run 2>&1 >/dev/null); RC=$?
+check "report without map: exit 1" "$RC" "1"
+check "report without map: explains" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'needs the feature map')" "1"
+
+# ---- ticketLine / report sections (pure functions, no browser) ----
+OUT=$(cd "$HERE" && node --input-type=module -e '
+import { ticketLine, renderReport } from "./reproduce.mjs";
+const reqs = [{ url: "http://x/api/a", method: "GET", status: 404 }, { url: "http://x/api/b", method: "POST", status: 500 }];
+const s = { route: "/tickets?tab=runs", url: "http://x/tickets?tab=runs", finalUrl: "", title: "T", waitFor: "[data-testid=\"p\"]", waitSource: "map",
+  found: false, error: "Timeout 60000ms", timings: { navigationMs: 1, elementMs: null, totalMs: 2 }, consoleErrors: 1, failedRequests: 2, dir: "/e/1",
+  screenshot: null, feature: null, report: "runs tab blank\nsecond line", match: { title: "Tickets hub", score: 6, matched: ["run", "ticket"] } };
+s.ticketLine = ticketLine(s, reqs);
+console.log(s.ticketLine);
+console.log(renderReport(s, [{ type: "error", text: "boom" }], reqs));
+')
+check "ticketLine: not found + 5xx first" "$(printf '%s' "$OUT" | sed -n 1p)" 'Reproduced `/tickets?tab=runs`: key element `[data-testid="p"]` NOT found (Timeout 60000ms); 1 console error; 2 failed requests (first: POST http://x/api/b → 500); evidence: /e/1'
+check "report.md: match line" "$(printf '%s' "$OUT" | grep -c 'Matched from the report: Tickets hub (score 6, words: run, ticket)')" "1"
+check "report.md: ticket section" "$(printf '%s' "$OUT" | grep -c '^## For the ticket')" "1"
+check "report.md: report quoted" "$(printf '%s' "$OUT" | grep -c '^> second line')" "1"
+OUT=$(cd "$HERE" && node --input-type=module -e '
+import { ticketLine } from "./reproduce.mjs";
+console.log(ticketLine({ route: "/", found: true, consoleErrors: 0, failedRequests: 0, dir: "/e/2" }, []));
+')
+check "ticketLine: rendered, nothing failed" "$OUT" 'Reproduced `/`: rendered; 0 console errors; 0 failed requests; evidence: /e/2'
+
 ERR=$(bash "$EXEC" --route relative --dry-run 2>&1 >/dev/null); RC=$?
 check "route must start with /" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'must start with /')" "1"
 

package/config/skills/agent/core/reproduce-ui/reproduce.mjs

@@ -1,10 +1,12 @@
 /**
  * reproduce-ui — open a dashboard feature by its feature-map entry and save
- * evidence (#811 slice 2, specs/2026-10-26-feature-map.md).
+ * evidence (#811 slices 2–3, specs/2026-10-26-feature-map.md).
  *
  * Driven by execute.sh through environment variables:
  *   RU_ROUTE      route to open, e.g. `/tickets?tab=runs` (or RU_FEATURE)
  *   RU_FEATURE    a word of a Routes row of the map, resolved to its route
+ *   RU_REPORT     a bug report (the owner's sentence plus the words read off
+ *                 the screenshot); matched to one Features section of the map
  *   RU_WAIT       CSS selector to wait for; default = the first data-testid
  *                 of the feature's Elements line in the map, else `body`
  *   RU_MAP        path of FEATURE_MAP.md (optional; lookups need it)
@@ -18,7 +20,8 @@
  *
  * Output: one JSON line on stdout — the plan (dry run) or the summary with the
  * evidence folder. Exit 0 when the element appeared, 2 when it did not (the
- * evidence is still written), 1 on a usage or launch error.
+ * evidence is still written), 1 on a usage or launch error, 3 when a report
+ * matches no single feature (the candidates are on stderr).
  */
 
 import { createRequire } from 'node:module';
@@ -131,6 +134,128 @@ export function defaultWaitSelector(markdown, route, tab) {
 	return null;
 }
 
+/**
+ * Words that say nothing about which feature a report is about.
+ */
+const REPORT_STOPWORDS = new Set([
+	'the', 'and', 'for', 'with', 'this', 'that', 'there', 'then', 'than', 'when', 'what', 'where', 'which', 'who',
+	'why', 'how', 'but', 'not', 'nothing', 'none', 'all', 'any', 'some', 'are', 'was', 'were', 'has', 'have',
+	'had', 'does', 'did', 'can', 'cannot', 'could', 'should', 'would', 'will', 'just', 'still', 'again', 'also',
+	'only', 'very', 'too', 'from', 'into', 'onto', 'out', 'over', 'under', 'after', 'before', 'about', 'here',
+	'see', 'sees', 'seen', 'shows', 'show', 'shown', 'showing', 'looks', 'look', 'like', 'seems', 'says', 'said',
+	'page', 'pages', 'screen', 'screenshot', 'tab', 'tabs', 'click', 'clicked', 'clicking', 'open', 'opens',
+	'opened', 'opening', 'get', 'gets', 'got', 'its', 'you', 'your', 'our', 'they', 'them', 'their', 'one', 'two',
+	'bug', 'broken', 'wrong', 'blank', 'empty', 'missing', 'error', 'errors', 'fails', 'failed', 'failing',
+	'loading', 'loads', 'load', 'stuck', 'forever', 'instead', 'please', 'fix', 'crewly', 'dashboard',
+	'something', 'anything', 'everything', 'thing', 'things', 'off', 'yet', 'now',
+]);
+
+/**
+ * The comparable words of a text: lower-case, letters and digits only,
+ * three characters or more, no stopwords, a trailing plural `s` dropped so
+ * that "runs" meets "run".
+ *
+ * @param {string} text - Any text
+ * @returns {Set<string>}
+ */
+export function reportTokens(text) {
+	const out = new Set();
+	for (const raw of (text || '').toLowerCase().split(/[^a-z0-9]+/)) {
+		if (raw.length < 3 || REPORT_STOPWORDS.has(raw)) continue;
+		out.add(raw.length > 3 && raw.endsWith('s') && !raw.endsWith('ss') ? raw.slice(0, -1) : raw);
+	}
+	return out;
+}
+
+/**
+ * One Features section of the map, broken into the word sets a report is
+ * scored against.
+ *
+ * @typedef {object} FeatureBlock
+ * @property {string} title - The heading without the parenthesis
+ * @property {string} route - The first route in the heading
+ * @property {string[]} tabs - Tab names from `tabs \`a\` · \`b\``
+ * @property {Set<string>} strong - Title and Expected words (weight 2)
+ * @property {Set<string>} weak - Route segments, Reach, Elements words (weight 1)
+ */
+
+/**
+ * The Features sections of the map.
+ *
+ * @param {string} markdown - FEATURE_MAP.md
+ * @returns {FeatureBlock[]}
+ */
+export function featureBlocks(markdown) {
+	const blocks = [];
+	for (const block of markdownSection(markdown, '## Features').split(/\n(?=### )/)) {
+		const lines = block.split('\n');
+		const heading = lines[0] ?? '';
+		if (!heading.startsWith('### ')) continue;
+		const route = /`(\/[^`]*)`/.exec(heading)?.[1];
+		if (!route) continue;
+		const title = heading.slice(4).replace(/\s*\(.*$/, '').trim();
+		const tabsText = /tabs\s+((?:`[^`]+`\s*(?:·\s*)?)+)/.exec(heading)?.[1] ?? '';
+		const tabs = [...tabsText.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+		const lineOf = (label) => lines.find((l) => l.includes(`**${label}**`)) ?? '';
+		const strong = reportTokens(`${title} ${lineOf('Expected')}`);
+		const weak = reportTokens(`${route.replace(/:[A-Za-z_]+/g, ' ')} ${lineOf('Reach')} ${lineOf('Elements').replace(/[-_$]/g, ' ')}`);
+		blocks.push({ title, route, tabs, strong, weak });
+	}
+	return blocks;
+}
+
+/**
+ * Score every feature against a bug report: a report word found in the
+ * feature's title or Expected line counts 2, in its route, Reach or
+ * Elements 1, and a word that is one of the feature's tab names 4 (the tab
+ * also becomes the `?tab=` of the route). The best feature wins when at
+ * least two words matched, it scores 3 or more, and half again as much as
+ * the runner-up; otherwise the caller gets the candidates and asks for
+ * `--route`. One word is never enough: "Usage" alone is a `--feature`.
+ *
+ * @param {string} markdown - FEATURE_MAP.md
+ * @param {string} report - The owner's sentence plus words read off the screenshot
+ * @returns {{chosen: object|null, candidates: object[], tokens: string[]}}
+ *   candidates: `{route, title, score, matched}` sorted best first (score > 0 only)
+ */
+export function matchReport(markdown, report) {
+	const tokens = [...reportTokens(report)];
+	const scored = [];
+	for (const b of featureBlocks(markdown)) {
+		let score = 0;
+		const matched = [];
+		let tab = null;
+		for (const t of tokens) {
+			const tabHit = b.tabs.find((name) => reportTokens(name).has(t));
+			const w = tabHit ? 4 : b.strong.has(t) ? 2 : b.weak.has(t) ? 1 : 0;
+			if (!w) continue;
+			score += w;
+			matched.push(t);
+			if (tabHit && !tab) tab = tabHit;
+		}
+		if (score > 0) scored.push({ route: tab ? `${b.route}?tab=${tab}` : b.route, title: b.title, score, matched });
+	}
+	scored.sort((a, c) => c.score - a.score || a.route.localeCompare(c.route));
+	const [best, second] = scored;
+	const confident = best && best.matched.length >= 2 && best.score >= 3 && (!second || best.score >= second.score * 1.5);
+	return { chosen: confident ? best : null, candidates: scored.slice(0, 5), tokens };
+}
+
+/**
+ * Why a report could not be matched, for the error line.
+ *
+ * @param {{candidates: object[]}} m - From {@link matchReport}
+ * @returns {string}
+ */
+export function matchFailure(m) {
+	if (!m.candidates.length) return 'the report matches no feature in the map; add the words you see on the screenshot, or pass --route';
+	const best = m.candidates.map((c) => `${c.route} [${c.score}]`).join(', ');
+	if (m.candidates.length === 1 || m.candidates[0].score >= m.candidates[1].score * 1.5) {
+		return `the report matches a feature too weakly (one word only, or under 3 points); add the words you see on the screenshot, or pass --route (best: ${best})`;
+	}
+	return `the report matches several features about equally; pass --route (best: ${best})`;
+}
+
 /**
  * The Routes row whose pattern matches an opened path (`/tickets/runs/abc`
  * → `/tickets/runs/:id`); an exact match wins, the query string is ignored.
@@ -191,6 +316,25 @@ export function buildPlan() {
 	const map = mapPath ? readFileSync(mapPath, 'utf8') : null;
 	let route = env.RU_ROUTE || '';
 	let row = null;
+	let match = null;
+	if (!route && !env.RU_FEATURE && env.RU_REPORT) {
+		if (!map) fail(`--report needs the feature map; pass --map or --route (looked for ${env.RU_MAP || 'FEATURE_MAP.md'})`);
+		const m = matchReport(map, env.RU_REPORT);
+		if (!m.chosen) {
+			process.stderr.write(
+				`${JSON.stringify({
+					ok: false,
+					error: matchFailure(m),
+					candidates: m.candidates,
+					tokens: m.tokens,
+				})}\n`,
+			);
+			process.exit(3);
+		}
+		route = m.chosen.route;
+		match = { ...m.chosen, candidates: m.candidates.slice(1) };
+		row = matchRouteRow(routeRows(map), route);
+	}
 	if (!route && env.RU_FEATURE) {
 		if (!map) fail(`--feature needs the feature map; pass --map or --route (looked for ${env.RU_MAP || 'FEATURE_MAP.md'})`);
 		const r = resolveFeature(map, env.RU_FEATURE);
@@ -200,7 +344,7 @@ export function buildPlan() {
 	} else if (route && map) {
 		row = matchRouteRow(routeRows(map), route);
 	}
-	if (!route) fail('one of --route or --feature is required');
+	if (!route) fail('one of --route, --feature or --report is required');
 	if (!route.startsWith('/')) fail('--route must start with /');
 	const params = {};
 	for (const [k, v] of Object.entries(env)) if (k.startsWith('RU_PARAM_') && v) params[k.slice('RU_PARAM_'.length)] = v;
@@ -221,10 +365,30 @@ export function buildPlan() {
 		fullPage: env.RU_FULL_PAGE === '1',
 		map: mapPath,
 		feature: row ? { page: row.page, reach: row.reach, job: row.job } : null,
+		report: env.RU_REPORT || null,
+		match,
 		outRoot,
 	};
 }
 
+/**
+ * One line for the ticket: what was opened, whether it rendered, and what
+ * the console and network said, with the evidence folder.
+ *
+ * @param {object} s - Summary
+ * @param {Array<object>} requests - Failed requests
+ * @returns {string}
+ */
+export function ticketLine(s, requests) {
+	const worst = requests.find((r) => r.status >= 500) ?? requests.find((r) => r.failure) ?? requests[0];
+	const parts = [
+		`Reproduced \`${s.route}\`: ${s.found ? 'rendered' : `key element \`${s.waitFor}\` NOT found${s.error ? ` (${s.error})` : ''}`}`,
+		`${s.consoleErrors} console error${s.consoleErrors === 1 ? '' : 's'}`,
+		`${s.failedRequests} failed request${s.failedRequests === 1 ? '' : 's'}${worst ? ` (first: ${worst.method} ${worst.url} → ${worst.status ?? worst.failure})` : ''}`,
+	];
+	return `${parts.join('; ')}; evidence: ${s.dir}`;
+}
+
 /**
  * Load playwright-core from the Crewly package.
  *
@@ -320,7 +484,10 @@ async function run(plan) {
 		dir,
 		screenshot: existsSync(screenshot) ? screenshot : null,
 		feature: plan.feature,
+		report: plan.report,
+		match: plan.match,
 	};
+	summary.ticketLine = ticketLine(summary, requests);
 	writeFileSync(join(dir, 'console.json'), `${JSON.stringify(console_, null, 2)}\n`);
 	writeFileSync(join(dir, 'requests.json'), `${JSON.stringify(requests, null, 2)}\n`);
 	writeFileSync(join(dir, 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
@@ -348,6 +515,9 @@ export function renderReport(s, console_, requests) {
 		`- Screenshot: ${s.screenshot ? 'screenshot.png' : '(none)'}`,
 	];
 	if (s.feature) lines.push(`- Feature: ${s.feature.job} — reached from ${s.feature.reach}; page \`${s.feature.page}\``);
+	if (s.match) lines.push(`- Matched from the report: ${s.match.title} (score ${s.match.score}, words: ${s.match.matched.join(', ')})`);
+	if (s.ticketLine) lines.push('', '## For the ticket', '', s.ticketLine);
+	if (s.report) lines.push('', '## Report', '', ...s.report.split('\n').map((l) => `> ${l}`));
 	lines.push('', `## Console errors (${console_.length})`, '');
 	lines.push(...(console_.length ? console_.map((c) => `- [${c.type}] ${c.text}`) : ['- none']));
 	lines.push('', `## Failed requests (${requests.length})`, '');

package/config/sops/developer/debugging.md

@@ -39,7 +39,7 @@ Name **one command** you have already run at least once that shows the user's ex
 
 ## 2. Reproduce and minimise
 
-For a dashboard (UI) report, run the `reproduce-ui` skill on the feature first: `bash config/skills/agent/core/reproduce-ui/execute.sh --route "/tickets?tab=runs"` (route and `?tab=` from `frontend/FEATURE_MAP.md`; `--feature <word>` resolves it from the map). Read its `console.json` and `requests.json` before the screenshot — a failed `/api/...` call explains most blank or stale pages — and put the evidence folder in the ticket.
+For a dashboard (UI) report, run the `reproduce-ui` skill on the feature first. A screenshot and a sentence is enough: read the screenshot, then `bash config/skills/agent/core/reproduce-ui/execute.sh --report "<the sentence> <headings, tab names and labels you see>"` matches it to a `frontend/FEATURE_MAP.md` entry and opens it (exit 3 = ambiguous: it lists the candidate routes, run again with `--route`; `--feature <word>` and `--route "/tickets?tab=runs"` work when you already know the page). Read its `console.json` and `requests.json` before the screenshot — a failed `/api/...` call explains most blank or stale pages. Put its `ticketLine` (from the JSON it prints, also in `report.md`) in the ticket; after the fix run it again and add the second line as proof.
 
 Cut inputs one at a time. Done when every remaining element is load-bearing.
 

package/dist/backend/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "39a294088c0e4369cd70b33b4fbdc9e619c41292",
-  "builtAt": "2026-10-26T09:42:06.990Z"
+  "commit": "0325d3b3ba4216522326cbe59359c72df5760c4f",
+  "builtAt": "2026-10-26T10:49:46.811Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewly",
-  "version": "1.20.435",
+  "version": "1.20.437",
   "type": "module",
   "description": "Multi-agent orchestration platform for AI coding teams — coordinates Claude Code, Gemini CLI, and Codex agents with a real-time web dashboard",
   "workspaces": [

package/packages/crewly-agent/src/runtime/agent-runner.service.test.ts

@@ -253,6 +253,65 @@ describe('AgentRunnerService', () => {
     });
   });
 
+  describe('sub-agents (#1317)', () => {
+    const okResult = {
+      text: 'done',
+      steps: [{ toolCalls: [], toolResults: [] }],
+      usage: { inputTokens: 10, outputTokens: 5 },
+      finishReason: 'stop',
+    };
+
+    it('gives a normal agent spawn_subagent on top of the full tool set', async () => {
+      await runner.initialize();
+      mockGenerateText.mockResolvedValueOnce(okResult);
+      await runner.run('hi');
+      const tools = mockGenerateText.mock.calls[0][0].tools as Record<string, unknown>;
+      expect(tools.spawn_subagent).toBeDefined();
+      expect(tools.report_to_parent).toBeUndefined();
+      expect(tools.send_message).toBeDefined();
+      expect(tools.read_file).toBeDefined();
+    });
+
+    it('gives a sub-agent only the confined file/search/shell tools plus report_to_parent', async () => {
+      const child = new AgentRunnerService(
+        {
+          ...baseConfig,
+          sessionName: 'test-session/sub-1',
+          projectPath: '/tmp/proj',
+          subagent: { cwd: '/tmp/proj', readOnly: false, depth: 1, parentSession: 'test-session' },
+        },
+        mockModelManager,
+        mockApiClient,
+      );
+      child._generateTextFn = mockGenerateText;
+      await child.initialize();
+      mockGenerateText.mockResolvedValueOnce(okResult);
+      await child.run('task');
+      const tools = mockGenerateText.mock.calls[0][0].tools as Record<string, unknown>;
+      expect(tools.report_to_parent).toBeDefined();
+      expect(tools.read_file).toBeDefined();
+      expect(tools.bash_exec).toBeDefined();
+      expect(tools.spawn_subagent).toBeUndefined();
+      expect(tools.send_message).toBeUndefined();
+      expect(tools.delegate_task).toBeUndefined();
+      expect(tools.remember).toBeUndefined();
+      expect(child.getSubagentReport()).toBeNull();
+    });
+
+    it('folds a child\'s tokens into the parent\'s next run result and totals, once', async () => {
+      await runner.initialize();
+      runner.recordChildUsage({ input: 1000, output: 200, cachedInput: 50 });
+      mockGenerateText.mockResolvedValueOnce(okResult);
+      const first = await runner.run('one');
+      expect(first.usage).toEqual({ input: 1010, output: 205, cachedInput: 50 });
+      expect(runner.getState().totalTokens).toEqual({ input: 1010, output: 205 });
+
+      mockGenerateText.mockResolvedValueOnce(okResult);
+      const second = await runner.run('two');
+      expect(second.usage).toEqual({ input: 10, output: 5, cachedInput: 0 });
+    });
+  });
+
   describe('serial queue', () => {
     beforeEach(async () => {
       await runner.initialize();