yadflow 3.3.1 → 3.4.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [3.3.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.3.0...v3.3.1) (2026-07-01)
+# [3.4.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.3.1...v3.4.0) (2026-07-01)
 
 
-### Bug Fixes
+### Features
 
-* restore npm ci in github checks template ([c3079c2](https://github.com/abdelrahmannasr/yadflow/commit/c3079c246692188b5256550a74c6fa14d214c7a7)), closes [#92](https://github.com/abdelrahmannasr/yadflow/issues/92)
+* **report:** add self issue reporter with auto-scrubbed diagnostics ([cd70965](https://github.com/abdelrahmannasr/yadflow/commit/cd7096568995d52501a2e9b57a7ac091a22620f1))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/bin/yad.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // `yad` — setup/maintenance + the PR-driven review gate + build helpers for the SDLC module.
 import { VERSION } from '../cli/manifest.mjs';
-import { c, log, closePrompts } from '../cli/lib.mjs';
+import { c, log, closePrompts, askYesNo } from '../cli/lib.mjs';
 import { runSetup } from '../cli/setup.mjs';
 import { reconcile } from '../cli/reconcile.mjs';
 import { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer, gateWalkthrough } from '../cli/gate.mjs';
@@ -17,6 +17,7 @@ import { runDoctor } from '../cli/doctor.mjs';
 import { runNext } from '../cli/next.mjs';
 import { syncStatuses } from '../cli/artifact-status.mjs';
 import { runThread, runReconcile } from '../cli/thread.mjs';
+import { runReport } from '../cli/report.mjs';
 
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
 
@@ -33,6 +34,9 @@ ${c.bold('Setup & maintenance')}
                        repo paths, epic ledgers (exit 1 on any failure)
   yad sync-status [epic]   Update artifact frontmatter status (draft/in-review/approved)
                        from .sdlc/state.json — all epics if omitted (--dry-run to preview)
+  yad report [-m <text>]   File a bug in the yadflow repo with auto-scrubbed diagnostics
+                       (no paths/hosts/repo names/logins/flag values). Also offered
+                       automatically after an unexpected failure. YAD_NO_REPORT=1 disables.
 
 ${c.bold('Reviewer roster')}
   yad roster list                      Show every member + their roles per scope (hub + each repo)
@@ -181,6 +185,9 @@ async function main() {
     case 'doctor':
       await runDoctor(o.dir, { json: o.json });
       break;
+    case 'report':
+      await runReport(o.dir, { message: o.message });
+      break;
     case 'sync-status': {
       const [, epic] = o._;
       if (epic && !isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
@@ -279,11 +286,24 @@ async function main() {
 }
 
 main()
-  .catch((err) => {
+  .catch(async (err) => {
     const code = err?.code && /^YAD-/.test(err.code) ? ` [${err.code}]` : '';
     log(c.red(`\nyad failed${code}: ${err?.message || err}`));
     if (err?.hint) log(c.yellow(`  → ${err.hint}`));
     if (code) log(c.dim('  (see README "Troubleshooting" for this code, or run `yad doctor`)'));
     process.exitCode = 1;
+    // Offer to report the failure — but only interactively (never in CI), and opt-out via
+    // YAD_NO_REPORT. `report` failing on its own would land here, so never re-offer for it.
+    // Require a TTY on BOTH ends: stdout for the message, stdin so the y/N prompt can be answered
+    // (a TTY stdout with piped/closed stdin would otherwise hang on readline).
+    const offerReport = process.stdin.isTTY && process.stdout.isTTY && !process.env.SDLC_NONINTERACTIVE
+      && !process.env.YAD_NO_REPORT && process.argv[2] !== 'report';
+    if (offerReport) {
+      try {
+        if (await askYesNo('\nReport this failure to the yadflow team?', false)) {
+          await runReport(process.cwd(), { error: err });
+        }
+      } catch { /* reporting is best-effort — never mask the original failure */ }
+    }
   })
   .finally(closePrompts);

package/cli/doctor.mjs

@@ -304,12 +304,21 @@ export function threadChecks(checks, root) {
   }
 }
 
-export async function runDoctor(root, { json = false } = {}) {
+// Run every check section and return the diagnostic object without printing. This is the shared
+// core of `runDoctor` — the reporter (cli/report.mjs) consumes it to derive a *scrubbed* safe
+// subset (never the raw checks, which carry names + paths). Same shape `--json` prints.
+export function collectDoctor(root) {
   const checks = [];
   envChecks(checks);
   projectChecks(checks, root);
   epicChecks(checks, root);
   threadChecks(checks, root);
+  const failed = checks.filter((x) => x.status === 'fail');
+  return { version: VERSION, ok: failed.length === 0, checks };
+}
+
+export async function runDoctor(root, { json = false } = {}) {
+  const { checks } = collectDoctor(root);
 
   const failed = checks.filter((x) => x.status === 'fail');
   const warned = checks.filter((x) => x.status === 'warn');

package/cli/manifest.mjs

@@ -7,8 +7,15 @@ import { readFileSync } from 'node:fs';
 // tracks the semantic-release-managed version — never a hardcoded constant
 // that would drift after a release. package.json ships in the npm tarball and
 // sits at the package root, one level up from this cli/ dir.
-const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-export const VERSION = version;
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const VERSION = pkg.version;
+
+// The upstream yadflow repo, as `owner/name` — where `yad report` files issues. Derived from
+// package.json `bugs.url` (the single source of truth) so it tracks a fork/rename automatically;
+// falls back to the canonical slug if the field is ever malformed.
+export const UPSTREAM_REPO =
+  (pkg.bugs?.url || '').match(/github\.com\/([^/]+\/[^/]+?)(?:\/issues)?\/?$/i)?.[1]
+  || 'abdelrahmannasr/yadflow';
 
 // The hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
 export const SKILLS = [
@@ -44,6 +51,7 @@ export const SKILLS = [
   'yad-review-companion',
   'yad-pair-review',
   'yad-status',
+  'yad-report',
   'yad-change',
   'yad-timeline',
   'yad-defects',

package/cli/platform.mjs

@@ -2,6 +2,7 @@
 // skills/yad-hub-bridge/references/bridge.md. Everything runs as the local user (gh/glab own auth);
 // no tokens are stored. Pure mapping fns (resolveLogin/mapApprovers) are exported for unit tests;
 // readPr is injectable so the gate can be tested with a fake.
+import { URLSearchParams } from 'node:url';
 import { run, has } from './lib.mjs';
 import { parseEngagement } from './companion.mjs';
 
@@ -424,3 +425,71 @@ export function createPr(platform, opts = {}) {
   }
   return { ok: true, url, reviewers: reviewers.slice(0, 1), mentioned, dropped };
 }
+
+// ---- issues (for `yad report`) ------------------------------------------------------------------
+// Filing a bug against the upstream yadflow repo. Same local-user auth as everything else: the call
+// inherits the user's own gh/glab session, no tokens handled. `repo` is an `owner/name` slug; the
+// upstream lives on GitHub, so the github path is the primary one (glab kept for symmetry).
+// `runner` is injectable so cli/report.mjs — and its tests — never shell out.
+
+// Is the platform CLI present AND authenticated? A best-effort probe (mirrors doctor's auth check).
+// Used to decide direct-file vs the URL fallback; a false here is not an error, just "use the URL".
+export function platformAuthed(platform, { runner = run } = {}) {
+  const cli = cliFor(platform);
+  if (!cli || !has(cli)) return false;
+  return runner(cli, ['auth', 'status']).ok;
+}
+
+// Open issues whose title/body match `query`. Returns { ok, matches: [{number, title, url}] }.
+// A failed/absent CLI returns ok:false so the caller can skip dedup rather than block filing.
+export function searchIssues(platform, repo, query, { runner = run, limit = 5 } = {}) {
+  if (platform === 'gitlab') {
+    const r = runner('glab', ['issue', 'list', '--repo', repo, '--search', query, '-P', String(limit), '-F', 'json']);
+    if (!r.ok) return { ok: false, matches: [] };
+    try {
+      const rows = JSON.parse(r.stdout || '[]');
+      return { ok: true, matches: rows.map((i) => ({ number: i.iid, title: i.title, url: i.web_url })) };
+    } catch { return { ok: false, matches: [] }; }
+  }
+  const r = runner('gh', ['issue', 'list', '--repo', repo, '--search', query, '--state', 'open', '--limit', String(limit), '--json', 'number,title,url']);
+  if (!r.ok) return { ok: false, matches: [] };
+  try {
+    return { ok: true, matches: JSON.parse(r.stdout || '[]') };
+  } catch { return { ok: false, matches: [] }; }
+}
+
+// The issue URL from a create command's stdout: the last line that looks like one (tolerates any
+// trailing notice the CLI may print after it), falling back to the last non-empty line.
+const urlFromStdout = (stdout = '') => {
+  const lines = stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+  return [...lines].reverse().find((l) => /^https?:\/\//.test(l)) || lines.pop() || '';
+};
+
+// Create an issue. Returns { ok, url } or { ok:false, reason }. Mirrors createPr's shape.
+export function createIssue(platform, repo, { title, body, labels = [] } = {}, { runner = run } = {}) {
+  if (platform === 'gitlab') {
+    const args = ['issue', 'create', '--repo', repo, '--title', title, '--description', body];
+    for (const l of labels) args.push('--label', l);
+    const r = runner('glab', args);
+    if (!r.ok) return { ok: false, reason: r.stderr };
+    return { ok: true, url: urlFromStdout(r.stdout) };
+  }
+  const args = ['issue', 'create', '--repo', repo, '--title', title, '--body', body];
+  for (const l of labels) args.push('--label', l);
+  const r = runner('gh', args);
+  if (!r.ok) return { ok: false, reason: r.stderr };
+  return { ok: true, url: urlFromStdout(r.stdout) };
+}
+
+// The prefilled `issues/new` URL — the always-works fallback when the CLI is missing/unauthenticated.
+// GitHub honours ?title=&body= (and &labels=); GitLab uses issue[title]/issue[description].
+export function issueUrl(platform, repo, { title = '', body = '', labels = [] } = {}) {
+  if (platform === 'gitlab') {
+    const q = new URLSearchParams({ 'issue[title]': title, 'issue[description]': body });
+    if (labels.length) q.set('issue[label_names][]', labels.join(','));
+    return `https://gitlab.com/${repo}/-/issues/new?${q.toString()}`;
+  }
+  const q = new URLSearchParams({ title, body });
+  if (labels.length) q.set('labels', labels.join(','));
+  return `https://github.com/${repo}/issues/new?${q.toString()}`;
+}

package/cli/report.mjs

@@ -0,0 +1,227 @@
+// `yad report` — the self issue reporter. When a flow breaks, help the user file a well-formed bug
+// in the upstream yadflow repo with diagnostics attached, so recurring issues surface to maintainers.
+//
+// PRIVACY IS THE POINT: the issue posts to a PUBLIC repo, so this module is allowlist-first. It
+// assembles ONLY a known-safe set of fields (version, node/os, tool booleans, platform enum, error
+// code/hint, a path-scrubbed message, and command + flag NAMES) and actively strips everything else —
+// no absolute paths, hostnames, git URLs, repo names, roster logins/emails, epic/story IDs, branch
+// names, or flag values ever leave the machine. The user sees the exact payload and confirms before
+// anything is posted. See memory: no-private-data-in-reports.
+import path from 'node:path';
+import { c, log, info, ok, warn, note, ask, askYesNo, has, readJSON, run } from './lib.mjs';
+import { VERSION, UPSTREAM_REPO, PROJECT_FILES } from './manifest.mjs';
+import { createIssue, searchIssues, issueUrl, platformAuthed } from './platform.mjs';
+
+// The upstream lives on GitHub — file there regardless of the user's own hub platform.
+const UPSTREAM_PLATFORM = 'github';
+const PLACEHOLDER = '‹redacted›';
+
+// ---- scrubbing ----------------------------------------------------------------------------------
+
+// Strip anything that could carry private context from a free-text string. Ordered so broader
+// structures (URLs, hosts) go first. Over-redaction is the safe direction — a redacted timestamp or
+// filename beats a leaked home directory, internal hostname, or branch name. Covers: URLs of any
+// scheme, scp-style ssh remotes, emails, IPv4/IPv6 (+port), multi-label hostnames, Windows UNC and
+// drive paths, unix/home paths, epic/story IDs, and remaining `a/b`-style refs (branch names).
+export function scrub(s = '') {
+  return String(s)
+    .replace(/\b[a-z][\w+.-]*:\/\/\S+/gi, '‹url›')          // scheme://... (http, https, ssh, git, ftp, file)
+    .replace(/\b[\w.+-]+@[\w.-]+:[^\s'"]+/g, '‹url›')       // scp-style ssh remote: user@host:path
+    .replace(/\b[\w.+-]+@[\w.-]+\.\w+/g, PLACEHOLDER)       // email
+    .replace(/\b\d{1,3}(?:\.\d{1,3}){3}(?::\d+)?\b/g, '‹ip›') // IPv4 (+ optional :port)
+    .replace(/\b(?:[0-9a-f]{1,4}:){3,}[0-9a-f]{0,4}\b/gi, '‹ip›') // IPv6 (>=3 hextet groups)
+    .replace(/\b(?:[\w-]+\.){2,}[a-z]{2,}\b/gi, '‹host›')   // FQDN (>=3 labels — spares 2-label filenames)
+    .replace(/\\\\[\w.-]+(?:\\[\w.$-]+)+/g, '‹path›')       // Windows UNC \\host\share\...
+    .replace(/\b[A-Za-z]:\\[\w.\\-]+/g, '‹path›')           // Windows drive path C:\...
+    .replace(/(?:~)?\/[\w.-]+(?:\/[\w.-]+)*/g, '‹path›')    // unix/home path (>=1 segment)
+    .replace(/\bEP-[a-z0-9-]+\b/gi, '‹id›')                 // epic / story IDs (standalone)
+    .replace(/\b[\w.-]+\/[\w.-]+(?:\/[\w.-]+)*\b/g, '‹ref›'); // remaining a/b refs (branch names, origin/x)
+}
+
+// The verbs `yad` understands (top-level commands + their sub-actions). Anything NOT in this set —
+// roster logins, repo names, roles, epic IDs, filenames, and every flag VALUE — is dropped, so the
+// reported command carries only structure, never data.
+const SAFE_VERBS = new Set([
+  'setup', 'check', 'update', 'doctor', 'report', 'sync-status', 'next', 'gate', 'review', 'commit',
+  'open-pr', 'ship', 'repo', 'roster', 'docs', 'thread', 'reconcile',
+  'open', 'sync', 'comments', 'status', 'walkthrough', 'trailer', 'ci', 'context', 'chat', 'cards',
+  'nudge', 'list', 'add', 'grant', 'revoke', 'remove', 'build', 'deploy', 'refresh', 'wire',
+]);
+
+// Reduce an argv to a safe command line: the leading verb chain (at most `command subcommand`, and
+// only tokens in SAFE_VERBS) plus flag NAMES only. Every positional that isn't a known verb — epic
+// IDs (`EP-foo`), logins, repo names, roles, filenames — and every flag VALUE is dropped, so both
+// `yad gate sync EP-x --dir /p -m "secret"` and `yad roster add joesmith` reduce to structure only.
+export function sanitizeArgv(argv = []) {
+  const out = [];
+  let i = 0;
+  for (; i < argv.length && out.length < 2; i++) {
+    const t = argv[i];
+    if (t.startsWith('-') || !SAFE_VERBS.has(t)) break; // stop at the first flag or non-verb token
+    out.push(t);
+  }
+  for (; i < argv.length; i++) {
+    const t = argv[i];
+    if (t.startsWith('-')) out.push(t.split('=')[0]); // flag names only — values and positionals are never kept
+  }
+  return out.join(' ');
+}
+
+// ---- context (allowlist) ------------------------------------------------------------------------
+
+// Build the safe, postable context — the ONLY data that can reach the issue. Reads doctor for tool
+// state but keeps just the booleans, never the raw checks (which carry names + paths).
+export function sanitizeContext(dir, { error = null, argv = process.argv.slice(2) } = {}) {
+  const hub = readJSON(path.join(dir, PROJECT_FILES.hubConfig), null);
+  const platform = hub && ['github', 'gitlab'].includes(hub.platform) ? hub.platform : 'file-only';
+  // Derive tool auth from doctor's checks without keeping any check text.
+  const toolState = (cli, p) => (has(cli) ? (platformAuthed(p) ? 'present + authenticated' : 'present, not authenticated') : 'not installed');
+  const ctx = {
+    version: VERSION,
+    node: process.versions.node,
+    os: process.platform,
+    git: has('git') ? 'present' : 'not found',
+    gh: toolState('gh', 'github'),
+    // The hub CLI's auth is a useful diagnostic for a GitLab user (issues still file to GitHub upstream).
+    ...(platform === 'gitlab' ? { glab: toolState('glab', 'gitlab') } : {}),
+    platform,
+    command: sanitizeArgv(argv) || '(none)',
+  };
+  if (error) {
+    ctx.error = {
+      code: /^YAD-/.test(error.code || '') ? error.code : null,
+      message: scrub(error.message || String(error)),
+      hint: error.hint ? scrub(error.hint) : null,
+    };
+  }
+  return ctx;
+}
+
+// ---- body assembly ------------------------------------------------------------------------------
+
+// Title: prefer the error code + command; fall back to the (scrubbed) summary.
+export function buildTitle(ctx, summary) {
+  const code = ctx.error?.code ? ` [${ctx.error.code}]` : '';
+  const cmd = ctx.command && ctx.command !== '(none)' ? `\`yad ${ctx.command}\`` : 'yad';
+  if (ctx.error) return `[report] ${cmd} failed${code}`;
+  return `[report] ${summary ? summary.slice(0, 72) : 'yad issue'}`;
+}
+
+// Body mirrors the fields of .github/ISSUE_TEMPLATE/bug_report.yml — but only the safe subset.
+export function buildBody(ctx, summary) {
+  const lines = [];
+  lines.push('### What happened?', '', summary || '_(no summary provided)_', '');
+  lines.push(`Command: \`yad ${ctx.command}\``, '');
+  lines.push('### Environment');
+  lines.push(`- yadflow: \`${ctx.version}\``);
+  lines.push(`- node: \`${ctx.node}\``);
+  lines.push(`- os: \`${ctx.os}\``);
+  lines.push(`- git: ${ctx.git}`);
+  lines.push(`- gh: ${ctx.gh}`);
+  if (ctx.glab) lines.push(`- glab: ${ctx.glab}`);
+  lines.push(`- platform: ${ctx.platform}`);
+  lines.push('');
+  if (ctx.error) {
+    lines.push('### Error');
+    if (ctx.error.code) lines.push(`- code: \`${ctx.error.code}\``);
+    lines.push(`- message: ${ctx.error.message}`);
+    if (ctx.error.hint) lines.push(`- hint: ${ctx.error.hint}`);
+    lines.push('');
+  }
+  lines.push('---', '_Filed via `yad report`. Diagnostics are auto-scrubbed — no paths, hostnames, repo names, logins, or flag values._');
+  return lines.join('\n');
+}
+
+// ---- open a URL (best-effort) -------------------------------------------------------------------
+function openUrl(url, { runner = run } = {}) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  if (has(cmd)) runner(cmd, [url]);
+}
+
+// ---- the flow -----------------------------------------------------------------------------------
+
+// Never throws — a failure while reporting must not crash the CLI (and, from the top-level catch,
+// must not re-trigger a report). Returns { filed, url } for tests/callers.
+export async function runReport(dir, opts = {}) {
+  const {
+    error = null,
+    message = null,
+    // injectable seams (tests never shell out or prompt)
+    filer = createIssue,
+    searcher = searchIssues,
+    prompter = askYesNo,
+    asker = ask,
+    opener = openUrl,
+    authed = () => platformAuthed(UPSTREAM_PLATFORM),
+    argv = process.argv.slice(2),
+    interactive = !process.env.SDLC_NONINTERACTIVE,
+  } = opts;
+
+  try {
+    const ctx = sanitizeContext(dir, { error, argv });
+
+    // Summary — the user's own description (scrubbed for stray paths/urls). Ask if interactive.
+    let summary = message ? scrub(message) : '';
+    if (!summary && interactive) {
+      const a = await asker('One line — what went wrong?', '');
+      summary = a ? scrub(a) : '';
+    }
+
+    const title = buildTitle(ctx, summary);
+    const body = buildBody(ctx, summary);
+    const labels = ['bug'];
+
+    // Dedup — search open issues by the error code (or the first summary word). Advisory: a failed
+    // search just skips this step, it never blocks filing.
+    const query = ctx.error?.code || (summary.split(/\s+/)[0] || '').replace(/[^\w-]/g, '');
+    if (query) {
+      const { ok: searchedOk, matches } = searcher(UPSTREAM_PLATFORM, UPSTREAM_REPO, `${query} in:title`);
+      if (searchedOk && matches.length) {
+        log(c.bold(`\nFound ${matches.length} possibly-related open issue(s):`));
+        for (const m of matches) info(`#${m.number} — ${m.title}  ${c.dim(m.url)}`);
+        if (interactive && await prompter('Open an existing issue instead of filing a new one?', true)) {
+          opener(matches[0].url);
+          log(`\n  → ${c.cyan(matches[0].url)}`);
+          return { filed: false, url: matches[0].url, deduped: true };
+        }
+      }
+    }
+
+    // Preview — show EXACTLY what will be posted to the public repo before anything leaves.
+    log(c.bold(`\nThis will be posted to ${c.cyan(UPSTREAM_REPO)} (a public repo):\n`));
+    log(c.bold(title));
+    log(c.dim('─'.repeat(60)));
+    log(body);
+    log(c.dim('─'.repeat(60)));
+
+    // Posting to a public repo is always a deliberate act — require an explicit yes. Non-interactive
+    // runs never auto-post; they hand back the prefilled URL instead.
+    const confirmed = interactive ? await prompter('Post this now?', false) : false;
+    if (!confirmed) {
+      const url = issueUrl(UPSTREAM_PLATFORM, UPSTREAM_REPO, { title, body, labels });
+      note(interactive ? 'Not posted. You can file it yourself here (prefilled):' : 'Non-interactive — not posted. File it here (prefilled):');
+      log(`  → ${c.cyan(url)}`);
+      return { filed: false, url };
+    }
+
+    // File directly when the CLI is authenticated; otherwise fall back to the prefilled URL.
+    if (authed()) {
+      const r = filer(UPSTREAM_PLATFORM, UPSTREAM_REPO, { title, body, labels });
+      if (r.ok) {
+        ok(`Issue filed: ${c.cyan(r.url)}`);
+        return { filed: true, url: r.url };
+      }
+      warn(`Could not file automatically: ${r.reason || 'unknown error'}`);
+    } else {
+      note('gh is not authenticated — opening a prefilled issue in your browser instead.');
+    }
+    const url = issueUrl(UPSTREAM_PLATFORM, UPSTREAM_REPO, { title, body, labels });
+    opener(url);
+    log(`  → ${c.cyan(url)}`);
+    return { filed: false, url };
+  } catch (e) {
+    // Reporting itself must never crash the CLI.
+    note(`could not complete the report (${e?.message || e}) — please file manually at https://github.com/${UPSTREAM_REPO}/issues`);
+    return { filed: false, url: null, failed: true };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). A BMAD module + 34 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/install.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT"
 
-SKILLS=(yad-discovery yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-sync-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-review-companion yad-pair-review yad-status yad-change yad-timeline yad-defects yad-reconcile)
+SKILLS=(yad-discovery yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-sync-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-review-companion yad-pair-review yad-status yad-report yad-change yad-timeline yad-defects yad-reconcile)
 
 # Skills removed in a later release: this installer only refreshes names still in SKILLS, so a
 # rerun would otherwise leave a dropped skill sitting in the IDE dirs. Purge any lingering copy

package/skills/sdlc/module-help.csv

@@ -27,6 +27,7 @@ SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build-half Step E:
 SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build-half Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh
 SDLC Workflow,yad-run,Run (Automation),RN,"Phase 4 orchestrator: drive a story's back-half loop (spec→tasks→implement→checks) in one code repo, reading each step's automation dial from build-state — on machine_advance it advances on its own, on human_approve it stops for a human. Records every run in the trust log. Realizes Step B (a clean checks pass auto-advances to the engineer review when earned; any FAIL / scope overrun / contract touch HALTS). set-dial earns/reverts a step's automation (machine_advance gated by the trust threshold; front states and engineer-review refused); kill/unkill toggles the system-wide kill switch. Front states and the human merge gate never auto-advance.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <repo>} {action: run|set-dial|kill|unkill} {step: <back-step>} {to: human_approve|machine_advance},4-automate,yad-spec,yad-engineer-review,false,epics/EP-<slug>/.sdlc/,build-state/<story-id>.json trust-log.json
 SDLC Workflow,yad-status,SDLC Status,SS,"Read-only: print the full front-state chain, per-step dials, contract lock, story repo tags, and pending approvals at the active gate. For stories in the build half, also print each back-half step's automation dial and status, the trust record (runs / % approved-unchanged / earned vs gathering evidence), and the system-wide kill-switch state.",,{epic: EP-<slug>},1-front,,,false,,
+SDLC Workflow,yad-report,Report Issue,RP,"Self issue reporter: when a yad flow breaks, file a well-formed bug in the upstream yadflow repo with AUTO-SCRUBBED diagnostics (yadflow/node/os version, tool present+authenticated booleans, hub platform enum, the YadError code/hint, a path-scrubbed message, and the failing command + flag NAMES only) — never absolute paths, hostnames, git URLs, repo names, roster logins/emails, epic/story IDs, branch names, or flag values. Searches open issues first to avoid duplicates, previews the exact payload, and asks before posting to the public repo; files via an authenticated gh/glab or a prefilled issues/new URL fallback. Also offered automatically after an unexpected failure (interactive only; YAD_NO_REPORT=1 disables). Never a gate, never touches epic state.",,{message: one-line summary},,,,false,,
 SDLC Workflow,yad-connect-docs,Connect Docs Target,DX,"Setup/maintenance: connect a docs/Pages publishing target so the interactive-docs steps can deploy the generated site (not just commit its source). Auto-detects the platform from .sdlc/hub.json (github->github-pages, gitlab->gitlab-pages, null->build-only), resolves the Vite base path, and records the target in .sdlc/docs.json (local-user auth, no stored tokens). Degrades to build-only when gh/glab is absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {target: github-pages|gitlab-pages|none} {scope: hub|<repo>|dedicated} {base_path: <override>},0-setup,,yad-docs,false,.sdlc/,docs.json
 SDLC Workflow,yad-docs,Author Docs Site,DS,"Generate the per-epic interactive documentation SPA (animated flow canvas + role-based stakeholder doc pages) from the epic's approved artifacts (epic, architecture, locked contract, ui-design, stories, code-context, test-cases), themed by the connected design system, into epics/EP-<slug>/docs-site/. Copies the vendored React/Vite/Tailwind shell verbatim and generates src/data/*.ts deterministically; drives the yad docs build/deploy CLI to publish to Pages (or build-only). An OUTPUT ENRICHMENT — never a gate; never mutates state.json, approvals, or the contract lock.",,{epic: EP-<slug>} {action: generate|refresh|deploy} {login_gate: true|false},,yad-review-gate,,false,epics/EP-<slug>/docs-site/,docs-site/ docs-build.json
 SDLC Workflow,yad-docs-overview,Docs Overview Site,DO,"Generate the project SDLC-overview interactive site (docs/sdlc-site/) — every stage from setup to ship modeled as flow paths, system components, and stakeholder roles — reusing the same vendored shell, themed with yadflow's brand palette. Reads config.yaml + module-help.csv + the overview diagram as the pipeline source. Folds the hand-maintained docs/index.html report into the site as report.html (linked from the nav). Not a gate — a project-level enrichment that regenerates whenever the skill set / pipeline changes.",,{action: generate|deploy},,,,false,docs/sdlc-site/,sdlc-site/ .docs-build.json

package/skills/yad-report/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: yad-report
+description: 'Self issue reporter for the yad CLI. When a yadflow flow breaks, file a well-formed bug in the upstream yadflow repo (abdelrahmannasr/yadflow) with auto-scrubbed diagnostics attached, so recurring issues surface to the maintainers. Drives the `yad report` command: it captures ONLY a privacy-safe allowlist (yadflow/node/os version, tool present+authenticated booleans, hub platform enum, the YadError code/hint, a path-scrubbed error message, and the failing command + flag NAMES) — never absolute paths, hostnames, git URLs, repo names, roster logins/emails, epic/story IDs, branch names, or flag values. It searches open issues first to avoid duplicates, shows the exact payload, and asks before posting anything to the public repo. Files directly via an authenticated gh/glab, or falls back to a prefilled issues/new URL. Also offered automatically after an unexpected failure (interactive only; YAD_NO_REPORT=1 or SDLC_NONINTERACTIVE disables it). Use when the user says "yad report", "report this bug", "file an issue", or "something broke in the flow".'
+---
+
+# yad — Self Issue Reporter
+
+**Goal:** turn a broken flow into a fixable, well-formed bug report in the upstream yadflow repo —
+without leaking any private data. This skill drives the `yad report` CLI command; it does not
+hand-craft issues.
+
+## When it runs
+- **Manually:** the user runs `yad report` (optionally `yad report -m "one-line summary"`).
+- **Automatically:** after an unexpected failure, the CLI's top-level handler offers
+  *"Report this failure to the yadflow team?"*. This is **interactive only** — it never fires in CI
+  (`SDLC_NONINTERACTIVE`) and is disabled by `YAD_NO_REPORT=1`.
+
+## Privacy is the contract
+Issues post to a **public** repo, so the reporter is **allowlist-first**. It sends ONLY:
+- `yadflow` version, Node version, OS platform;
+- tool state as booleans (`git` present; `gh` present + authenticated);
+- the hub **platform enum** (`github` / `gitlab` / `file-only`) — never the URL, host, or roster;
+- the `YadError` **code** + **hint**, and a **path-scrubbed** error message;
+- the failing **command name and flag names only** — never flag values.
+
+It **never** sends absolute paths, cwd, hostnames, git remote URLs, repo names/paths, roster logins
+or emails, epic/story IDs or titles, branch names, `-m` free text, or the raw `yad doctor --json`
+check list. Free-text fields (the summary, the error message) are scrubbed of paths / URLs / emails.
+
+## On activation
+1. **Assemble the safe context** (`sanitizeContext`) and, if interactive and no `-m` was given, ask
+   the user for a one-line summary.
+2. **Deduplicate:** search open issues in `abdelrahmannasr/yadflow` by the error code (or the first
+   summary word). If matches exist, list them and offer to open an existing one instead of filing a
+   duplicate.
+3. **Preview + consent:** print the exact title + body that will be posted to the public repo, then
+   ask *"Post this now?"*. Nothing leaves the machine without this confirmation.
+4. **File:** with an authenticated `gh`/`glab`, create the issue directly (label `bug`) and print the
+   URL. Otherwise, fall back to a **prefilled `issues/new` URL** (printed and, on a TTY, opened in the
+   browser) so the user can complete it manually.
+
+## Hard rules
+- Reuse the `yad report` command — do not craft issues by hand or shell out to `gh` directly.
+- Reporting is best-effort: it must never crash the CLI or mask the original failure.
+- Respect `SDLC_NONINTERACTIVE` and `YAD_NO_REPORT` — no prompts, no auto-offer when they are set.
+- Diagnostics are the maintainers' input to fix bugs; keep the payload safe and truthful.