yadflow 2.6.0 → 2.8.0

package/cli/roster.mjs

@@ -0,0 +1,164 @@
+// `yad roster` — manage the reviewer roster (.sdlc/hub.json) and per-repo roles at any time.
+// The roster maps a platform login -> SDLC name + a per-scope roles map; it is the only thing that lets
+// the review gate attribute approvals and route per-repo domain-owner reviewers. This is the standalone
+// counterpart of the `yad setup` roster step and the `yad-connect-repos action: roster` skill action.
+// Repo-driven: `add`/`edit` walks the connected repos from repos.json so roles are assigned against what
+// is actually connected, not against repo names the user has to remember. Granting/revoking a
+// `domain-owner` keeps repos.json `domain_owners` in sync so the gate never drifts from the roster.
+import path from 'node:path';
+import { c, log, ok, info, warn, hand, fail, ask, askYesNo, readJSON, writeJSON } from './lib.mjs';
+import { PROJECT_FILES } from './manifest.mjs';
+import { rolesForScope } from './platform.mjs';
+import { parseRolesSpec, upsertRosterEntry, addRepoRoles, removeRepoRole, setRepoDomainOwners, reconcileRepoRoles } from './setup.mjs';
+
+const ROLES = ['owner', 'reviewer', 'domain-owner'];
+
+const loadHub = (root) => readJSON(path.join(root, PROJECT_FILES.hubConfig), null);
+const loadRepos = (root) => readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] }).repos || [];
+const ownersOf = (repo) => (Array.isArray(repo.domain_owners) ? repo.domain_owners : (repo.domain_owner ? [repo.domain_owner] : []));
+
+// `list` — every member with their per-scope roles, plus a drift check between hub.json roles and
+// repos.json domain_owners (the two should agree; the sync on grant/revoke keeps them aligned).
+function rosterList(root) {
+  const hub = loadHub(root);
+  if (!hub || !Array.isArray(hub.roster) || !hub.roster.length) {
+    warn('no roster yet (.sdlc/hub.json) — add one with `yad roster add <login>` or `yad setup`');
+    return { members: 0 };
+  }
+  const repos = loadRepos(root);
+  log(c.bold('\nreviewer roster'));
+  for (const e of hub.roster) {
+    const flag = e.unverified ? c.yellow(' (unverified)') : '';
+    log(`  ${c.bold(e.name || e.login)} ${c.dim(`@${e.login}`)}${e.email ? c.dim(` <${e.email}>`) : ''}${flag}`);
+    const hubRoles = rolesForScope(e, 'hub');
+    log(`    hub: ${hubRoles.length ? hubRoles.join(', ') : c.dim('—')}`);
+    for (const r of repos) {
+      const rr = rolesForScope(e, r.name);
+      if (rr.length) log(`    ${r.name}: ${rr.join(', ')}`);
+    }
+  }
+  const drift = [];
+  for (const r of repos) {
+    const owners = ownersOf(r);
+    for (const nm of owners) {
+      const e = hub.roster.find((x) => x.name === nm);
+      if (!e || !rolesForScope(e, r.name).includes('domain-owner')) {
+        drift.push(`${nm} owns ${r.name} in repos.json but has no domain-owner role in hub.json`);
+      }
+    }
+    for (const e of hub.roster) {
+      if (rolesForScope(e, r.name).includes('domain-owner') && !owners.includes(e.name)) {
+        drift.push(`${e.name} has domain-owner for ${r.name} in hub.json but is missing from repos.json domain_owners`);
+      }
+    }
+  }
+  if (drift.length) { log(''); for (const d of drift) warn(d); }
+  return { members: hub.roster.length, repos: repos.length, drift: drift.length };
+}
+
+// The repo-driven walk: for each connected repo show the member's current role and offer to set it.
+async function repoWalk(root, entry) {
+  const repos = loadRepos(root);
+  if (!repos.length) { info('no connected repos to assign roles for (.sdlc/repos.json) — connect one with `yad setup`'); return; }
+  for (const r of repos) {
+    const cur = rolesForScope(entry, r.name);
+    if (!(await askYesNo(`  set ${entry.name}'s role on ${r.name}? (current: ${cur.length ? cur.join(', ') : 'none'})`, false))) continue;
+    const input = await ask('    roles (domain-owner/reviewer/owner, space-separated; blank = clear)', cur.join(' '));
+    const want = input.split(/\s+/).map((x) => x.trim()).filter(Boolean);
+    const invalid = want.filter((x) => !ROLES.includes(x));
+    if (invalid.length) warn(`ignoring unknown role(s): ${invalid.join(', ')} (allowed: ${ROLES.join(', ')})`);
+    reconcileRepoRoles(root, entry.name, r.name, cur, want.filter((x) => ROLES.includes(x)));
+  }
+}
+
+// Mirror any domain-owner scopes from a non-interactive `--roles` upsert into repos.json.
+function syncDomainOwners(root, entry) {
+  for (const [scope, list] of Object.entries(entry.roles || {})) {
+    if (scope !== 'hub' && Array.isArray(list) && list.includes('domain-owner')) setRepoDomainOwners(root, scope, entry.name, { add: true });
+  }
+}
+
+// `add`/`edit <login>` — upsert by login (from flags or interactive prompts), then either apply a
+// `--roles` spec directly (scriptable) or run the repo-driven walk (interactive default).
+async function rosterAdd(root, login, { name, email, roles } = {}) {
+  if (!login) { fail('usage: yad roster add <login> [--name N] [--email E] [--roles "hub=owner,reviewer backend=domain-owner"]'); process.exitCode = 1; return {}; }
+  const hub = loadHub(root);
+  const platform = hub ? hub.platform : null;
+  const existing = hub && Array.isArray(hub.roster) ? hub.roster.find((e) => e.login === login) : null;
+  const scripted = !!roles;
+  let nm = name;
+  let em = email;
+  let rolesMap;
+  if (scripted) {
+    rolesMap = parseRolesSpec(roles);
+  } else {
+    nm = nm || await ask('  yad name', (existing && existing.name) || login);
+    em = em || await ask('  commit email (blank to skip)', (existing && existing.email) || '');
+    const def = rolesForScope(existing, 'hub').join(' ') || 'reviewer';
+    const hubRoles = (await ask('  hub roles (owner/reviewer, space-separated)', def)).split(/\s+/).filter(Boolean);
+    rolesMap = hubRoles.length ? { hub: hubRoles } : {};
+  }
+  const { entry, created } = upsertRosterEntry(root, { login, name: nm, email: em || undefined, roles: rolesMap, platform });
+  if (!entry) return {};
+  ok(`${created ? 'added' : 'updated'} ${entry.name} (@${login})`);
+  if (scripted) syncDomainOwners(root, entry);
+  else await repoWalk(root, entry);
+  return { entry: entry.name, created };
+}
+
+// `grant <name> <repo> <role...>` — scriptable per-repo grant (member must already be in the roster).
+function rosterGrant(root, [name, repo, ...roles]) {
+  if (!name || !repo || !roles.length) { fail('usage: yad roster grant <name> <repo> <role...>'); process.exitCode = 1; return {}; }
+  const invalid = roles.filter((r) => !ROLES.includes(r));
+  if (invalid.length) { fail(`unknown role(s): ${invalid.join(', ')} (allowed: ${ROLES.join(', ')})`); process.exitCode = 1; return {}; }
+  const hub = loadHub(root);
+  if (!hub || !Array.isArray(hub.roster) || !hub.roster.some((e) => e.name === name)) {
+    fail(`'${name}' is not in the roster — add them first with \`yad roster add <login>\``); process.exitCode = 1; return {};
+  }
+  if (!loadRepos(root).some((r) => r.name === repo)) warn(`repo '${repo}' is not registered — the role is recorded and applies once it is connected`);
+  addRepoRoles(root, repo, Object.fromEntries(roles.map((r) => [r, [name]])));
+  if (roles.includes('domain-owner')) setRepoDomainOwners(root, repo, name, { add: true });
+  ok(`granted ${name} ${roles.join(', ')} on ${repo}`);
+  return { name, repo, roles };
+}
+
+// `revoke <name> <repo> <role...>` — scriptable per-repo revoke.
+function rosterRevoke(root, [name, repo, ...roles]) {
+  if (!name || !repo || !roles.length) { fail('usage: yad roster revoke <name> <repo> <role...>'); process.exitCode = 1; return {}; }
+  removeRepoRole(root, name, repo, roles);
+  if (roles.includes('domain-owner')) setRepoDomainOwners(root, repo, name, { add: false });
+  ok(`revoked ${name} ${roles.join(', ')} on ${repo}`);
+  return { name, repo, roles };
+}
+
+// `remove <login>` — delete a member; warn (do not cascade) if still a domain owner in repos.json.
+function rosterRemove(root, login) {
+  if (!login) { fail('usage: yad roster remove <login>'); process.exitCode = 1; return {}; }
+  const hubPath = path.join(root, PROJECT_FILES.hubConfig);
+  const hub = readJSON(hubPath, null);
+  if (!hub || !Array.isArray(hub.roster)) { warn('no roster to remove from (.sdlc/hub.json)'); return { removed: 0 }; }
+  const idx = hub.roster.findIndex((e) => e.login === login);
+  if (idx < 0) { warn(`no roster member with login '${login}'`); return { removed: 0 }; }
+  const [removed] = hub.roster.splice(idx, 1);
+  writeJSON(hubPath, hub);
+  ok(`removed ${removed.name} (@${login})`);
+  const refs = loadRepos(root).filter((r) => ownersOf(r).includes(removed.name)).map((r) => r.name);
+  if (refs.length) hand(`'${removed.name}' is still a domain owner in repos.json for: ${refs.join(', ')} — revoke with \`yad roster revoke ${removed.name} <repo> domain-owner\``);
+  return { removed: 1 };
+}
+
+export async function runRoster(root, { action = 'list', args = [], name, email, roles } = {}) {
+  switch (action) {
+    case 'list': return rosterList(root);
+    case 'add':
+    case 'edit': return rosterAdd(root, args[0], { name, email, roles });
+    case 'grant': return rosterGrant(root, args);
+    case 'revoke': return rosterRevoke(root, args);
+    case 'remove':
+    case 'rm': return rosterRemove(root, args[0]);
+    default:
+      fail(`unknown roster action: ${action} (list | add | edit | grant | revoke | remove)`);
+      process.exitCode = 1;
+      return {};
+  }
+}

package/cli/setup.mjs

@@ -11,13 +11,29 @@ import {
   moduleActions, repoActions, hubActions, authorsActions,
   legacyModuleActions, legacyRepoActions, legacyHubActions,
 } from './plan.mjs';
-import { validateLogin } from './platform.mjs';
+import { validateLogin, rolesForScope } from './platform.mjs';
 
 // Parse a comma/space separated list into a clean, deduped array of trimmed tokens.
-function parseList(s) {
+export function parseList(s) {
   return [...new Set((s || '').split(/[,\s]+/).map((x) => x.trim()).filter(Boolean))];
 }
 
+// Parse a per-scope roles spec — `"hub=owner,reviewer backend=domain-owner"` — into the roster's
+// per-scope map `{ hub: ['owner','reviewer'], backend: ['domain-owner'] }`. Tokens are whitespace
+// separated; each is `scope=role[,role...]`. Malformed tokens (no `=`, empty scope/roles) are skipped.
+export function parseRolesSpec(s) {
+  const out = {};
+  for (const tok of (s || '').split(/\s+/).map((x) => x.trim()).filter(Boolean)) {
+    const eq = tok.indexOf('=');
+    if (eq < 0) continue;
+    const scope = tok.slice(0, eq).trim();
+    const roles = parseList(tok.slice(eq + 1));
+    if (!scope || !roles.length) continue;
+    out[scope] = [...new Set([...(out[scope] || []), ...roles])];
+  }
+  return out;
+}
+
 const ALL_IDES = [...IDE_FOLDER_TARGETS, '.opencode'];
 
 export function detectPlatform(remoteUrl = '') {
@@ -68,6 +84,98 @@ export function addRepoRoles(root, repo, grants = {}) {
   if (touched) writeJSON(hubPath, hub);
 }
 
+// Normalize a roster entry's roles in place to the per-scope map, migrating the two legacy shapes
+// (a flat array, or a single `role` string) into `roles.hub` so nothing is lost. Mirrors the
+// migration addRepoRoles does; pulled out so upsert/remove share it.
+function normalizeRoles(entry) {
+  if (!entry.roles || typeof entry.roles !== 'object' || Array.isArray(entry.roles)) {
+    const hub = Array.isArray(entry.roles) ? entry.roles : (entry.role ? [entry.role] : []);
+    entry.roles = hub.length ? { hub } : {};
+    delete entry.role;
+  }
+  return entry.roles;
+}
+
+// Upsert one roster member into hub.json, keyed by `login`. Deep-merges the per-scope `roles` map so
+// scopes the caller did not name are preserved; sets `name`/`email` when given; validates the login
+// against the hub (warn-only — a miss flags `unverified`, `checked:false` skips silently). Creates the
+// hub.json shell if absent. Returns { entry, created }.
+export function upsertRosterEntry(root, { login, name, email, roles = {}, platform } = {}) {
+  if (!login) { warn('roster upsert needs a login — skipped'); return { entry: null, created: false }; }
+  const hubPath = path.join(root, PROJECT_FILES.hubConfig);
+  const hub = readJSON(hubPath, null) || { platform: platform && platform !== 'none' ? platform : null, bridge_enabled: false, bridge: false, default_branch: 'main', roster: [] };
+  if (!Array.isArray(hub.roster)) hub.roster = [];
+  let entry = hub.roster.find((e) => e.login === login);
+  const created = !entry;
+  if (!entry) { entry = { login, name: name || login, roles: {} }; hub.roster.push(entry); }
+  if (name) entry.name = name;
+  if (email) entry.email = email;
+  normalizeRoles(entry);
+  for (const [scope, list] of Object.entries(roles || {})) {
+    const cur = Array.isArray(entry.roles[scope]) ? entry.roles[scope] : [];
+    entry.roles[scope] = [...new Set([...cur, ...list])];
+  }
+  if (email && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) warn(`'${email}' does not look like an email address`);
+  const plat = platform || hub.platform;
+  if (plat && plat !== 'none') {
+    const v = validateLogin(plat, login);
+    if (v.checked && !v.exists) { warn(`'${login}' not found on ${plat} — saved as unverified`); entry.unverified = true; }
+    else if (v.checked && v.exists) { ok(`verified ${login} on ${plat}`); delete entry.unverified; }
+  }
+  writeJSON(hubPath, hub);
+  return { entry, created };
+}
+
+// Inverse of addRepoRoles: drop the named role(s) from a member's `roles[<repo>]` scope, removing the
+// scope key when it empties. Member is found by yad `name` (matching addRepoRoles). Idempotent.
+export function removeRepoRole(root, name, repo, roles = []) {
+  const hubPath = path.join(root, PROJECT_FILES.hubConfig);
+  const hub = readJSON(hubPath, null);
+  if (!hub || !Array.isArray(hub.roster)) return;
+  const entry = hub.roster.find((e) => e.name === name);
+  if (!entry) { warn(`'${name}' is not in the roster — nothing to revoke for ${repo}`); return; }
+  normalizeRoles(entry);
+  const cur = Array.isArray(entry.roles[repo]) ? entry.roles[repo] : [];
+  const next = cur.filter((r) => !roles.includes(r));
+  if (next.length === cur.length) return; // nothing removed
+  if (next.length) entry.roles[repo] = next; else delete entry.roles[repo];
+  writeJSON(hubPath, hub);
+}
+
+// Keep repos.json `domain_owners` in sync when a domain-owner role is granted/revoked via the roster,
+// so the gate's per-repo reviewer-routing and the derivation fallback never drift from hub.json. Adds
+// or removes the yad `name` and mirrors `domain_owner = domain_owners[0]`. No-op + warn if the repo is
+// not registered. Returns true when the registry was written.
+export function setRepoDomainOwners(root, repo, name, { add = true } = {}) {
+  const regPath = path.join(root, PROJECT_FILES.reposRegistry);
+  const registry = readJSON(regPath, { repos: [] });
+  const entry = (registry.repos || []).find((r) => r.name === repo);
+  if (!entry) { warn(`repo '${repo}' is not registered (.sdlc/repos.json) — domain_owners not synced`); return false; }
+  const owners = Array.isArray(entry.domain_owners) ? [...entry.domain_owners] : (entry.domain_owner ? [entry.domain_owner] : []);
+  const has = owners.includes(name);
+  let next;
+  if (add) { if (has) return false; next = [...owners, name]; }
+  else { if (!has) return false; next = owners.filter((o) => o !== name); }
+  entry.domain_owners = next;
+  entry.domain_owner = next[0] || '';
+  writeJSON(regPath, registry);
+  return true;
+}
+
+// Reconcile one repo's roles for a member to exactly `want`: grant what is new, revoke what is gone,
+// and mirror domain-owner changes into repos.json. `current` is the member's existing roles for the
+// repo. Shared by the `yad roster` walk and the `yad setup` per-repo role step. Idempotent.
+export function reconcileRepoRoles(root, name, repo, current = [], want = []) {
+  const toAdd = want.filter((r) => !current.includes(r));
+  const toRemove = current.filter((r) => !want.includes(r));
+  if (!toAdd.length && !toRemove.length) { info(`    ${repo}: unchanged`); return; }
+  if (toAdd.length) addRepoRoles(root, repo, Object.fromEntries(toAdd.map((r) => [r, [name]])));
+  if (toRemove.length) removeRepoRole(root, name, repo, toRemove);
+  if (toAdd.includes('domain-owner')) setRepoDomainOwners(root, repo, name, { add: true });
+  if (toRemove.includes('domain-owner')) setRepoDomainOwners(root, repo, name, { add: false });
+  ok(`    ${repo}: ${want.length ? want.join(', ') : 'cleared'}`);
+}
+
 export function registerRepo(root, registry, { name, rpath, platform, domain_owner = '', domain_owners = null, default_branch = 'main', today = null }) {
   if (!insideRoot(root, rpath)) {
     warn(`${rpath} resolves outside the project root — skipped`);
@@ -370,6 +478,24 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
+  // 7b. Assign/update roles for ALREADY-connected repos. The connect loop above only prompts for the
+  // repos you add now; this closes the gap so a member's domain-owner/reviewer/owner role on a repo
+  // connected in an earlier run can be set without reconnecting. Mirrors `yad roster` (repo-driven).
+  const hub7 = readJSON(hubPath, null);
+  if (registry.repos.length && hub7 && Array.isArray(hub7.roster) && hub7.roster.length
+      && await askYesNo('Assign/update roles for connected repos?', false)) {
+    for (const member of hub7.roster) {
+      if (!(await askYesNo(`  edit ${member.name}'s repo roles?`, false))) continue;
+      for (const repo of registry.repos) {
+        const cur = rolesForScope(member, repo.name);
+        if (!(await askYesNo(`    set ${member.name}'s role on ${repo.name}? (current: ${cur.length ? cur.join(', ') : 'none'})`, false))) continue;
+        const input = await ask('      roles (domain-owner/reviewer/owner, space-separated; blank = clear)', cur.join(' '));
+        const want = parseList(input).filter((x) => ['owner', 'reviewer', 'domain-owner'].includes(x));
+        reconcileRepoRoles(root, member.name, repo.name, cur, want);
+      }
+    }
+  }
+
   // 8. Wire each connected repo + the hub itself
   step(8, total, 'Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
   if (registry.repos.length === 0) info('no repos to wire');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "2.6.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). A BMAD module + 25 yad-* skills.",
+  "version": "2.8.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). A BMAD module + 29 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
   "license": "MIT",
@@ -22,7 +22,6 @@
     "!cli/test.mjs",
     "!cli/test-checks.mjs",
     "skills/",
-    "docs/index.html",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -55,7 +54,7 @@
     "deeptutor"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.39.4",
+    "@eslint/js": "^10.0.1",
     "@semantic-release/changelog": "^6.0.3",
     "eslint": "^9.39.4",
     "semantic-release": "^25.0.3"

package/skills/sdlc/config.yaml

@@ -176,6 +176,25 @@ learning:
   # tokens in the registry (kb name + sources are plain references, never credentials). Opt-in, never a gate.
   auth: user
 
+# Interactive documentation (yad-connect-docs / yad-docs / yad-docs-overview / yad-docs-sync) — the
+# generated React+Vite+Tailwind doc SITES. yad-docs builds a per-epic site (epics/EP-<slug>/docs-site/)
+# from the authored artifacts, themed by the connected design system; yad-docs-overview builds the
+# project SDLC-overview site (docs/sdlc-site/) from the pipeline definition, superseding docs/index.html.
+# The deploy TARGET is a Pages host, auto-detected from hub.platform (github->github-pages,
+# gitlab->gitlab-pages, null->build-only). The yad CLI does the npm build + Pages wiring + staleness;
+# the content generation is the AI step. Docs are an OUTPUT ENRICHMENT — never a gate, never touch state.
+docs:
+  registry: "{project-root}/.sdlc/docs.json"         # project-wide docs/Pages connection (NOT per-epic)
+  targets: [github-pages, gitlab-pages]               # supported Pages hosts; auto-detected from hub.platform
+  scope: hub                                          # publish from: hub (default) | <repo-name> | dedicated
+  degrade: build-only                                 # no Pages host / no gh|glab => build the dist, publish via CI
+  login_gate: false                                   # public docs by default (the client-side gate is presentational only)
+  manifest: "{project-root}/epics/EP-<slug>/.sdlc/docs-build.json"   # per-epic staleness baseline (yad-docs)
+  overview: "{project-root}/docs/sdlc-site/"          # the project SDLC-overview site (yad-docs-overview)
+  # Auth: `yad-connect-docs` records only how to reach the Pages host (platform + base path); it stores NO
+  # tokens — publishing runs as the LOCAL user's own gh/glab or the platform CI. Idempotent, refreshable.
+  auth: user
+
 # Hub platform + front-half review bridge (yad-connect-repos `detect-hub`; yad-review-gate + yad-hub-bridge).
 # The product hub is itself a git repo on a platform. With the bridge enabled, the front-half review/
 # comment/approval cycle runs through a real PR/MR on the hub: a review PR is opened per artifact, reviewers

package/skills/sdlc/install.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT"
 
-SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-connect-design yad-connect-testing yad-connect-learning yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-status)
+SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-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-review-comments yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-status)
 
 echo "Installing sdlc module from $ROOT/skills ..."
 

package/skills/sdlc/module-help.csv

@@ -24,3 +24,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-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
+SDLC Workflow,yad-docs-sync,Docs Sync,DY,"Maintenance/CI: keep the generated doc sites fresh. Detect staleness (a content hash of the approved artifacts + the connected repos' HEAD shas + the doc-shell version vs each site's build manifest), report which sites drifted and why, regenerate + redeploy the stale ones, and wire a CI job that rebuilds on push (carrying [skip ci] + a concurrency group to prevent deploy loops). Generalizes the rule that feature work must hand-update docs/index.html + diagrams + skill counts. Refresh is always a human/CI decision; never a gate.",,{action: check|refresh|wire} {epic: EP-<slug>},,,,false,epics/EP-<slug>/.sdlc/,docs-build.json yad-docs.yml

package/skills/yad-connect-docs/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: yad-connect-docs
+description: 'Connects a docs/Pages publishing target to the product hub so the interactive-docs steps can build and deploy the generated SPA — not just commit its source. Registers the target into the project-wide .sdlc/docs.json (GitHub Pages / GitLab Pages / build-only), auto-detecting the platform from .sdlc/hub.json and resolving the Vite base path, with local-user auth and no stored tokens. Detects whether gh/glab is present and degrades to build-only when absent. Run at setup or any time the publish target changes. Reusable, idempotent, refreshable. Use when the user says "connect docs", "connect Pages", "refresh the docs connection", or "list the docs connection".'
+---
+
+# SDLC — Connect a Docs/Pages Target (make the docs steps publishable)
+
+**Goal:** Let the interactive-docs steps (`yad-docs` per epic, `yad-docs-overview` project-wide)
+**build and deploy** the generated React/Vite SPA to a real URL — a GitHub Pages or GitLab Pages site —
+instead of only committing its source. This skill **connects** a publishing target to the product hub
+and records *how* to reach it (the platform, the publish scope, the base path) — never a credential.
+
+This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+epic's approvals. It only writes the project-wide docs registry. `yad-docs` / `yad-docs-overview`
+consume it: when a target is connected, they theme + generate the site and drive `yad docs deploy`;
+when nothing is connected (`target: "none"`), they still generate and **npm-build** the site but stop
+at a local `dist/` — build-only, no publish, exactly as before.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- The target is **GitHub-Pages-first but pluggable** — a *publish adapter*, mirroring the GitHub/GitLab
+  platform adapter the hub already uses. `github-pages` and `gitlab-pages` are the providers; `none` →
+  build-only (deliberate, no error).
+- The platform CLI (`gh` / `glab`) is a **subprocess**, used read/deploy-only via the user's own auth —
+  never installed by this skill, never given a token. Absent ⇒ degrade to build-only (`source:
+  "unavailable"`).
+- Registry: `{project-root}/.sdlc/docs.json` (project-wide, shared across all epics + the overview —
+  NOT per-epic), the sibling of `.sdlc/hub.json`, `.sdlc/repos.json`, and `.sdlc/design.json`.
+- Per-epic / overview build manifests (`docs-build.json`) are written later by `yad-docs` /
+  `yad-docs-overview`, not here. This skill describes the *connection*; it does not build.
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
+- `target` — `github-pages` | `gitlab-pages` | `none`. Default **auto-detected** from `.sdlc/hub.json`
+  `platform` (github → `github-pages`, gitlab → `gitlab-pages`, null/no hub → `none`).
+- `scope` — `hub` (default) | `<repo-name>` | `dedicated`. Where the Pages site is published from (the
+  hub repo, one connected code repo, or a dedicated docs repo).
+- `public` — `true` (default) | `false`. Whether the published site is public.
+- `base_path` — optional explicit override of the Vite `base` (otherwise resolved, Step 2).
+
+## On Activation
+
+### Step 1 — Resolve the target + detect the platform (the publish adapter)
+Determine the `target`. If not given, read `{project-root}/.sdlc/hub.json` `platform` and map it the same
+way the hub bridge maps repos: `github` → `github-pages`, `gitlab` → `gitlab-pages`, `null`/no hub →
+`none` (deliberate build-only). Reject a `target` value outside the three providers (fall back to the
+detected default with a warning, the way `registerRepo` falls back on an unknown platform).
+
+Then **probe the platform CLI** in the user's own session — `gh --version` / `gh auth status` for
+GitHub, `glab --version` / `glab auth status` for GitLab. Record `source`:
+- CLI present + authenticated → `source: "gh"` | `"glab"` (deploy can publish via the platform).
+- CLI absent or unauthenticated → `source: "unavailable"` — record it and report that `yad-docs` will
+  **build-only** (npm build to a local `dist/`, no publish) until the CLI is available. No error — the
+  publish is purely additive, exactly like the `gh`/`glab` review bridge degrading.
+
+**Auth is the local user's own** (`gh`/`glab`/git already on this device). The skill **stores no
+tokens**; everything in the registry is a plain reference. Do **not** install a CLI as part of this step.
+
+### Step 2 — Decide the publish scope + resolve the base path
+Resolve `scope` → `publishRepo`:
+- `hub` (default) → publish from the hub repo (read its name from `hub.json` `git_url`).
+- `<repo-name>` → publish from that connected code repo (must exist in `.sdlc/repos.json`).
+- `dedicated` → a dedicated docs repo the user names (recorded as `publishRepo`).
+
+Resolve `basePath` (the Vite `base`) per the table in `references/docs-registry.md`:
+- **GitHub *project* Pages** (a repo that is not `<user>.github.io`) serve under `/<repo>/` → `basePath =
+  "/<repo>/"`. Per-epic sites nest under `/<repo>/epics/EP-<slug>/`; the overview under `/<repo>/`.
+- **GitHub user/org Pages** (`<user>.github.io`) and **GitLab Pages** serve at the domain root → `basePath
+  = "/"`.
+- An explicit `base_path` input always wins (recorded verbatim, normalized to a leading + trailing `/`).
+
+### Step 3 — Record the connection in the registry (idempotent)
+Upsert into `{project-root}/.sdlc/docs.json` (create the file + parent `.sdlc/` if absent):
+
+```json
+{
+  "target": "github-pages",
+  "scope": "hub",
+  "publishRepo": "<repo or hub name>",
+  "basePath": "/<repo>/",
+  "public": true,
+  "auth": "user",
+  "connectedAt": "<YYYY-MM-DD>",
+  "lastSyncedAt": "<YYYY-MM-DD>",
+  "source": "gh"
+}
+```
+
+- `target: "none"` records a deliberate build-only project: `{ "target": "none", "scope": "hub",
+  "publishRepo": null, "basePath": "/", "source": "unavailable", ... }`.
+- `connect` is **idempotent** — re-running it overwrites the single connection in place (a project has
+  one docs target at a time; switching targets is just another `connect`).
+
+### Step 4 — Report (never auto-advance)
+Report the connected `target`, its `scope`/`publishRepo`, the resolved `basePath`, whether the platform
+CLI is available (or that the docs steps will degrade to **build-only**), and that **`yad-docs` /
+`yad-docs-overview` will now build + deploy here**. Nothing auto-advances; this is setup. **Do not build
+the site here — `yad-docs` builds.**
+
+## Other actions
+
+- **`refresh`** — re-detect the platform CLI and re-resolve the base path (after the user authenticates a
+  session, renames the publish repo, or switches `scope`), updating `lastSyncedAt`. Same machinery as
+  `connect`. Re-detection may flip `source` between `gh`/`glab` and `unavailable` — report the change.
+- **`list`** — print the current connection: `target`, `scope`/`publishRepo`, `basePath`, `public`, and a
+  **available/unavailable** flag for the platform CLI (best-effort, the user's own session). No target
+  connected ⇒ "build-only".
+- **`disconnect`** — remove the registry file (or set `target: "none"`). The platform's own Pages site is
+  **never touched** — only the hub's record of it.
+
+## Hard rules
+
+- **Local-user auth only; store no tokens.** Connect through the user's own `gh`/`glab`/git; never embed a
+  PAT or any credential in the registry. Everything recorded is a plain reference.
+- **Degrade gracefully.** No target / no platform CLI → the docs steps **build-only** (local `dist/`) with
+  no error. Publishing is additive, never a blocker — the same discipline as the `gh`/`glab` review bridge.
+- **Setup, not a gate.** Never touch `.sdlc/state.json`, approvals, or the contract lock from here.
+- **Idempotent + refreshable.** `connect`/`refresh` are safe to re-run; a project carries one docs
+  connection at a time.
+- **Describe the connection; do not build here.** This skill records *how to reach* the target.
+  `yad-docs` / `yad-docs-overview` generate, build, and deploy the site.
+
+## Reference
+- Registry schema, the base-path resolution table, and the freshness/degrade rules:
+  `references/docs-registry.md`.
+- The connect pattern this mirrors (design tool): `../yad-connect-design/SKILL.md`.
+- The connect pattern this mirrors (code repos + hub detection): `../yad-connect-repos/SKILL.md`.
+- The consumers — how `yad-docs` / `yad-docs-overview` build + deploy: `../yad-docs/SKILL.md`,
+  `../yad-docs-overview/SKILL.md`.

package/skills/yad-connect-docs/references/docs-registry.md

@@ -0,0 +1,74 @@
+# `.sdlc/docs.json` — the docs/Pages registry
+
+Project-wide, shared across every epic's docs site **and** the project overview site (NOT per-epic).
+The sibling of `.sdlc/hub.json`, `.sdlc/repos.json`, and `.sdlc/design.json`. Written by
+`yad-connect-docs`; read by `yad-docs`, `yad-docs-overview`, `yad-docs-sync`, and the `yad docs` CLI.
+Holds **no credentials** — every field is a plain reference. Auth is always the local user's own
+`gh`/`glab`/git session.
+
+## Schema
+
+```json
+{
+  "target": "github-pages | gitlab-pages | none",
+  "scope": "hub | <repo-name> | dedicated",
+  "publishRepo": "<repo or hub name>",
+  "basePath": "/<repo>/",
+  "public": true,
+  "auth": "user",
+  "connectedAt": "<YYYY-MM-DD>",
+  "lastSyncedAt": "<YYYY-MM-DD>",
+  "source": "gh | glab | unavailable"
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `target` | The publish adapter. `none` = deliberate build-only (no publish, no error). |
+| `scope` | Where the Pages site publishes from: the `hub` repo, one connected `<repo-name>`, or a `dedicated` docs repo. |
+| `publishRepo` | The concrete repo name resolved from `scope`. `null` when `target: "none"`. |
+| `basePath` | The Vite `base` substituted into each generated site (resolution table below). Normalized to a leading + trailing `/`. |
+| `public` | Whether the published site is public. |
+| `auth` | Always `"user"` — local-user / platform-CLI session. No token is ever stored. |
+| `connectedAt` / `lastSyncedAt` | ISO dates the connection was first written / last re-detected. |
+| `source` | `gh`/`glab` when the platform CLI is present + authenticated (publish works); `unavailable` when absent (build-only). |
+
+`target: "none"` records `{ "target": "none", "publishRepo": null, "basePath": "/", "source":
+"unavailable", ... }`.
+
+## Platform auto-detection (from `.sdlc/hub.json`)
+
+When `target` is not given, map the hub's `platform` the same way `yad-connect-repos` maps a repo host:
+
+| `hub.json` `platform` | default `target` |
+|-----------------------|------------------|
+| `github` | `github-pages` |
+| `gitlab` | `gitlab-pages` |
+| `null` / no hub.json | `none` (build-only) |
+
+## Base-path resolution table
+
+GitHub serves *project* Pages under a `/<repo>/` prefix, so Vite's `base` must match or every asset 404s.
+User/org Pages and GitLab Pages serve at the domain root.
+
+| Target + repo kind | `basePath` | Per-epic site URL | Overview site URL |
+|--------------------|------------|-------------------|-------------------|
+| GitHub **project** Pages (repo ≠ `<user>.github.io`) | `/<repo>/` | `/<repo>/epics/EP-<slug>/` | `/<repo>/` |
+| GitHub **user/org** Pages (`<user>.github.io`) | `/` | `/epics/EP-<slug>/` | `/` |
+| GitLab Pages | `/` | `/epics/EP-<slug>/` | `/` |
+| explicit `base_path` input | as given (normalized) | nests `epics/EP-<slug>/` under it | the given base |
+
+An explicit `base_path` input always wins. `yad-docs` substitutes `basePath` into the shell's Vite
+config; per-epic sites append `epics/EP-<slug>/` so they nest under the overview without colliding.
+
+## Freshness + degrade rules
+
+- **Freshness** here is connection-level, not content-level: `lastSyncedAt` reflects the last `refresh`.
+  *Site* staleness (artifacts/repos moved, shell upgraded) is tracked separately in each site's
+  `docs-build.json` and reconciled by `yad-docs-sync` — not here.
+- **`list`** flags the platform CLI **available/unavailable** by probing `gh auth status` / `glab auth
+  status` in the user's own session (best-effort). A flip to `unavailable` means the docs steps
+  degrade to build-only until the CLI is back.
+- **Degrade is silent + non-blocking.** No target / no CLI ⇒ `yad-docs` still generates + npm-builds the
+  site to a local `dist/`; only the publish step is skipped. The same discipline as the design-tool MCP
+  and the `gh`/`glab` review bridge being absent.

package/skills/yad-connect-repos/SKILL.md

@@ -133,6 +133,10 @@ write only `{project-root}/.sdlc/hub.json` (`config.yaml` `hub.config`) — neve
   `roles[<repo>]` (and still **derived** as a fallback when a roster `name` equals a repo's
   `domain_owner`/`domain_owners` in `repos.json` — see `references/hub-config.md`). An unmapped login
   degrades to a plain `reviewer`, never auto-promoted to owner/domain-owner.
+  **The deterministic half is the `yad roster` CLI command** — runnable any time, not just at setup:
+  `yad roster list`; `yad roster add <login>` (upsert, then a repo-driven walk that asks for each
+  connected repo's role); `yad roster grant|revoke <name> <repo> <role>`; `yad roster remove <login>`.
+  A `domain-owner` grant/revoke keeps `repos.json` `domain_owners` in sync so the gate never drifts.
 
 If the hub has no remote (`platform: null`) or the bridge is disabled, the front-half gate runs
 file-only with no error — the bridge is purely additive.

package/skills/yad-connect-repos/references/hub-config.md

@@ -33,7 +33,9 @@ login to an SDLC name + role. It is a single object for the hub itself — the s
 
 The roster is how a platform identity (a GitHub/GitLab **login**) becomes an SDLC **name + role(s)** in
 the file ledger (`approvals.json` / `comments.json`). Roles are the same three the gate uses:
-`owner | reviewer | domain-owner`.
+`owner | reviewer | domain-owner`. Populate and edit it any time with the **`yad roster`** CLI command
+(`list` / `add` / `grant` / `revoke` / `remove`) — `add` walks the connected repos asking for each
+one's role, and a `domain-owner` grant keeps `repos.json` `domain_owners` in sync.
 
 - **`login`** — the platform username whose PR review / approval is being mapped.
 - **`name`** — the SDLC name written into the ledger (the same names used across `approvals.json`,