yadflow 4.3.0 → 4.5.0

package/cli/next.mjs

@@ -15,7 +15,7 @@ import { c, log, ok, info, warn, hand, fail, readJSON, exists, emitJSON } from '
 import { PROJECT_FILES, isVerifiedLedger, productConfigPath, stepAdvance } from './manifest.mjs';
 import { printTeamHint, soloTeamHint } from './people.mjs';
 import { OWNER_STEPS, liveOwner, readState as loadLedgerState } from './owners.mjs';
-import { dedupeConsecutive, epicIds, isGateStep, killSwitchOn, loadAutomation, epicRel, epicRoot, loadLedger, loadSkillBindings, stepSkills, nextAction, preconditionsMet, isValidEpicId, epicLineage, typeNoun, phaseOf, stepPhase, profileSteps, lifecycleProfile, PHASES, PRODUCT_DONE, PRODUCT_EPICS, STEPS } from './epic-state.mjs';
+import { bindingsForEpic, bindingsForProfile, dedupeConsecutive, epicIds, isGateStep, killSwitchOn, loadAutomation, epicRel, epicRoot, loadLedger, loadSkillBindings, stepSkills, nextAction, preconditionsMet, isValidEpicId, epicLineage, typeNoun, phaseOf, stepPhase, profileSteps, lifecycleProfile, PHASES, PRODUCT_DONE, PRODUCT_EPICS, STEPS } from './epic-state.mjs';
 
 // Is solo mode on? Persisted in hub.json by setup (Phase C/D); default false. Read defensively so a
 // missing/old hub.json never breaks the driver.
@@ -46,10 +46,16 @@ function listEpics(root) {
 // `bindings` is passed in for the same reason `lin` is: every loop below renders many epics, and the
 // project's skill bindings are ONE file for all of them. The default keeps the single-epic callers a
 // one-liner; a loop reads the file once and hands the same object to every row.
-const actionFor = (root, id, lin = epicLineage(root, id), bindings = loadSkillBindings(root)) => {
+//
+// E51: the bindings are narrowed to THIS epic's route here, once, and `rowFor` hands that same view to
+// the printed line. `nextAction` would narrow them itself, but `actionLine` names skills the action
+// never carried (the Build fallback, the hand-off to the next epic) — a view built in two places is two
+// answers for one step.
+function epicAction(root, id, lin = epicLineage(root, id), bindings = loadSkillBindings(root)) {
   const ledger = loadLedger(epicRoot(root, id));
-  return {
-    ...nextAction(ledger, { epic: id, bindings }),
+  const view = bindingsForEpic(bindings, ledger?.state);
+  const action = {
+    ...nextAction(ledger, { epic: id, bindings: view }),
     lineageKind: lin.type,
     // Which ROUTE this epic RECORDED, carried so `phaseLine` can mark a phase that route never enters
     // (E40). The recorded key ONLY — never matched from the chain, which is the one place in this file
@@ -64,13 +70,19 @@ const actionFor = (root, id, lin = epicLineage(root, id), bindings = loadSkillBi
     // which route it is on simply gets the line it got before the short lanes existed.
     route: lifecycleProfile(ledger?.state?.profile) ? ledger.state.profile : null,
   };
-};
+  return { action, view };
+}
+
+const actionFor = (root, id, lin, bindings) => epicAction(root, id, lin, bindings).action;
 
 // One `epic.md` read, both things that come out of it: the action to print and the tag to print
 // beside it. Every printed path in this file goes through here.
+// `bindings` on the row is the epic's own view, and every printer spreads the row AFTER its own
+// `bindings`, so the row's wins.
 const rowFor = (root, id, bindings = loadSkillBindings(root)) => {
   const lin = epicLineage(root, id);
-  return { action: actionFor(root, id, lin, bindings), theme: lin.theme, owners: liveOwners(root, id) };
+  const { action, view } = epicAction(root, id, lin, bindings);
+  return { action, theme: lin.theme, owners: liveOwners(root, id), bindings: view };
 };
 
 // The live step owners of one epic (E47), by step. Beside the action, never in it: `yad next --json`'s
@@ -388,7 +400,7 @@ function generalNext(root, { all, headCount = null } = {}) {
     if (brownfield) hand(`capture what already exists first: invoke the ${c.bold('yad-backfill')} skill`);
     // Both name a STEP's skill, so both ask the project. `yad-backfill` above does not: waking a
     // brownfield anchor is the engine's own promote verb, not a step on any chain.
-    if (!productId) hand(`frame the whole product first (purpose, scope, MVP, roadmap, stack): run ${c.bold('yad foundation new')}, then invoke the ${c.bold(stepSkills('foundation', bindings)[0] || 'yad-discovery')} skill ${c.dim('(optional)')}`);
+    if (!productId) hand(`frame the whole product first (purpose, scope, MVP, roadmap, stack): run ${c.bold('yad foundation new')}, then invoke the ${c.bold(stepSkills('foundation', bindingsForProfile(bindings, 'foundation'))[0] || 'yad-discovery')} skill ${c.dim('(optional)')}`);
     hand(`start your first epic: invoke the ${c.bold(stepSkills('epic', bindings)[0] || 'yad-epic')} skill${productId ? c.dim(' (it reads the approved roadmap.md)') : ''}`);
     return;
   }
@@ -412,12 +424,12 @@ function generalNext(root, { all, headCount = null } = {}) {
   // The grouping theme rides this list too. This is the ONE `yad next` view that shows several epics
   // side by side, so it is where seeing which of them belong together is worth most — and leaving it
   // off would have meant bare `yad next`, the command people run by default, never showed the tag.
-  for (const { action: a, theme: tag } of rows) {
+  for (const { action: a, theme: tag, bindings: view } of rows) {
     const theme = tag ? ` ${c.dim(`#${tag}`)}` : '';
     // Debt is reminded here too (E41): the roll-up is the view people run most, and a reminder that only
     // appears once you already look at the one epic is not a reminder.
     const owed = a.debt?.length ? `  ${c.yellow(`· ${a.debt.length} owed as debt`)}` : '';
-    log(`    ${c.cyan(`${typeNoun(a.lineageKind)} ${a.epicId}`)}${theme}  ${actionLine(a, { solo, verified })}${owed}`);
+    log(`    ${c.cyan(`${typeNoun(a.lineageKind)} ${a.epicId}`)}${theme}  ${actionLine(a, { solo, bindings: view, verified })}${owed}`);
   }
   // Painted per segment, not dim-wrapping a bold: `paint` closes with a full reset, so the nested
   // form loses the dim from the first bold word to the end of the line.

package/cli/people.mjs

@@ -40,6 +40,7 @@ import { PROJECT_FILES, epicFiles } from './manifest.mjs';
 import { epicIds, epicRoot, unlistedLedgerDirs, FOUNDATION_EPIC, FOUNDATION_DIR, ledgerPersonLogin, legacyLogins, capLimit, capSeat, smallestTeam } from './epic-state.mjs';
 import { corruptShards, readShips } from './ledger.mjs';
 import { isBot, loginFromEmail } from './riskmap.mjs';
+import { gateMemberMap, hashEmail } from './members.mjs';
 
 // yadflow's OWN gate bot on GitLab. The GitHub workflow commits as `yad-gate-sync[bot]`, which `isBot`
 // already skips; the GitLab one commits as `yad-gate-sync` <yad-gate-sync@noreply.<host>> (the wired
@@ -313,7 +314,9 @@ export function gitHas(repoRoot, sha) {
   return r.status === 0;
 }
 
-function gitAuthors(dir, since) {
+// Exported for `yad standup` (E132), which reads the same authors over its own window: `at` is the commit's
+// exact time in epoch seconds, beside the UTC day in `ts` the count reads.
+export function gitAuthors(dir, since) {
   const git = (args) => spawnSync('git', args, { cwd: dir, encoding: 'utf8', maxBuffer: 1 << 30 });
   // Every reason below is printed: the folder is built from the shared registry (E81 review 15).
   const repoRoot = forTerminal(dir);
@@ -354,7 +357,8 @@ function gitAuthors(dir, since) {
     const secs = Number(ct);
     const ts = Number.isFinite(secs) && ct !== '' ? dayString(Math.floor(secs / 86400)) : null;
     if (ts === null) return { unknown: `${repoRoot}: a commit carries a date git cannot express as a calendar day` };
-    out.push({ ts, name: String(name || '').trim(), login: loginFromEmail(email), how: 'committed' });
+    // The email itself is never kept — only its hash, which a member file (E131) can match.
+    out.push({ ts, at: Math.floor(secs), name: String(name || '').trim(), login: loginFromEmail(email), emailHash: hashEmail(email), how: 'committed' });
   }
   return { events: out };
 }
@@ -393,7 +397,11 @@ function connectedRepos(root) {
 }
 
 // Every piece of evidence, from every source, with one list of the reasons any of it is missing.
-export function peopleEvidence(root, { today = todayString(), aliases = new Map(), sinceDays = CAPACITY_MAX_DAYS * WALK_PAD } = {}) {
+// E131: a commit whose author email a member file pairs with a login is that login's — one person, not a
+// name and a login counted twice. `members` is that pairing (`gateMemberMap`): only proven pairs on a GitHub
+// Product, never one two files share. It can only JOIN two keys, so it never removes anyone from the count;
+// a member file that cannot be read adds no pairing, and the count stays as it was (over, not under).
+export function peopleEvidence(root, { today = todayString(), aliases = new Map(), sinceDays = CAPACITY_MAX_DAYS * WALK_PAD, members = null } = {}) {
   const led = ledgerEvidence(root, aliases);
   const events = [...led.events];
   const unknown = [...led.unknown];
@@ -426,6 +434,8 @@ export function peopleEvidence(root, { today = todayString(), aliases = new Map(
       else events.push(...got.events);
     }
   }
+  const pairs = members || gateMemberMap(root);
+  if (pairs.size) for (const e of events) if (!e.login && e.emailHash && pairs.has(e.emailHash)) e.login = pairs.get(e.emailHash);
   return { events, merges: led.merges, unknown };
 }
 

package/cli/platform.mjs

@@ -67,7 +67,7 @@ export function platformReady(platform) {
 // both github.com and a GitHub Enterprise server would be recorded under the wrong account. `host` is the
 // caller's (the Product's `git_url`), else the directory's origin remote. `glab api` already resolves the
 // host from the repo.
-const LOGIN_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]*(\[bot\])?$/; // GitLab allows a leading underscore
+export const LOGIN_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]*(\[bot\])?$/; // GitLab allows a leading underscore
 const loginCache = new Map();
 export function platformLogin(cwd, platform, { runner = run, env = process.env, host } = {}) {
   if (env.YAD_PLATFORM_LOGIN === '0') return null;

package/cli/pr-list.mjs

@@ -0,0 +1,125 @@
+// E132 — the open and recently merged PRs/MRs of one repo, for `yad standup`. A READ, and E70's rule holds
+// here word for word: an empty list is an answer only when the platform answered it. Anything else — no
+// platform, reads turned off, no `gh`/`glab`, not logged in, offline, a 403 — is `{ ok: false, why }`, which
+// the standup prints as "platform not read — <why>", never as "no PRs".
+//
+// One call per list, never one per PR: GitHub's GraphQL answers the open PRs with their review decision
+// and check state, and the merged ones, in one query; GitLab's MR list carries `detailed_merge_status`.
+// A page is 100. A FULL page proves nothing about what is past it, so it is said ("more than 100 …, not
+// all read"), never read as the whole list.
+//
+// Facts only: the number, the author's login, draft or not, the check state and the review state the
+// platform gives. Never a title, a body, a branch name or a comment (no free text — `yad usage`'s rule).
+// `runner` is injectable so every answer is testable without a network (`YAD_PLATFORM_READ=0` in tests).
+import { run } from './lib.mjs';
+import { cliFor, detectPlatform, hostFromGitUrl, plainHost } from './platform.mjs';
+import { api, httpStatus, loggedIn, repoPathFromGitUrl, shown, whyFailed, PAGE, TIMEOUT } from './protection.mjs';
+
+// The check state, one word: GitHub's rollup, or what GitLab's merge status says about the pipeline.
+const GH_CHECKS = { SUCCESS: 'passing', FAILURE: 'failing', ERROR: 'failing', PENDING: 'running', EXPECTED: 'running' };
+
+const GH_QUERY = `query($owner:String!,$name:String!){repository(owner:$owner,name:$name){
+open:pullRequests(states:OPEN,first:${PAGE},orderBy:{field:CREATED_AT,direction:DESC}){totalCount nodes{number isDraft author{__typename login} reviewDecision reviews{totalCount} latestOpinionatedReviews(first:100){nodes{state}} commits(last:1){nodes{commit{statusCheckRollup{state}}}}}}
+merged:pullRequests(states:MERGED,first:${PAGE},orderBy:{field:UPDATED_AT,direction:DESC}){nodes{number mergedAt updatedAt author{__typename login}}}}}`;
+
+// GitHub's review state, in the words the standup prints. `none` = no review of any kind yet.
+// `reviewDecision` is null on a repo with no required-review rule — even on an approved PR — so the latest
+// opinionated review of each reviewer decides when it is null: a change request wins, then an approval.
+function ghReview(n) {
+  if (n.reviewDecision === 'CHANGES_REQUESTED') return 'changes-requested';
+  if (n.reviewDecision === 'APPROVED') return 'approved';
+  const states = (n.latestOpinionatedReviews?.nodes || []).map((r) => r?.state);
+  if (n.reviewDecision == null && states.includes('CHANGES_REQUESTED')) return 'changes-requested';
+  if (n.reviewDecision == null && states.includes('APPROVED')) return 'approved';
+  return (n.reviews?.totalCount || 0) > 0 ? 'reviewed' : 'none';
+}
+
+// GitLab's `detailed_merge_status`. Only the two pipeline words are turned into a check state; every other
+// status is printed as GitLab wrote it, because reading more into it would say what GitLab did not —
+// `mergeable` on a project with no approval rule was approved by nobody. `waits` lists the statuses where
+// the MR cannot merge until something happens: those put it under "waiting".
+const GL_CHECKS = { ci_must_pass: 'failing', ci_still_running: 'running' };
+export const GL_WAITS = ['ci_must_pass', 'ci_still_running', 'not_approved', 'requested_changes', 'discussions_not_resolved', 'need_rebase', 'conflict'];
+
+const author = (a) => (a && typeof a.login === 'string' && a.__typename !== 'Bot' && !/\[bot\]$/i.test(a.login) ? a.login : null);
+
+// Where to ask, or why yad cannot: the same preamble E70's `readProtection` runs, in the same order.
+export function prTarget({ platform = null, gitUrl = '' } = {}, { runner = run, env = process.env, authCache = new Map() } = {}) {
+  const rawHost = hostFromGitUrl(gitUrl || '');
+  const host = plainHost(rawHost);
+  const repo = repoPathFromGitUrl(gitUrl || '');
+  const plat = platform || detectPlatform(gitUrl || '') || null;
+  const base = { platform: plat, host, repo };
+  const no = (kind, why) => ({ ...base, ok: false, kind, why });
+  const cli = cliFor(plat);
+  if (!cli) return no('no-platform', plat ? `yad does not know the platform ${JSON.stringify(shown(plat))} (it reads GitHub and GitLab)` : 'no platform (GitHub or GitLab) is known for it');
+  if (env.YAD_PLATFORM_READ === '0') return no('off', 'platform reads are turned off (YAD_PLATFORM_READ=0)');
+  if (rawHost && !host) return no('no-url', 'its git URL names a host that is not a plain host name, so yad does not ask about it');
+  if (!host || !repo) return no('no-url', 'no git URL yad can read, so it cannot tell which repo to ask about');
+  if (!runner(process.platform === 'win32' ? 'where' : 'which', [cli], {}).ok) return no('no-cli', `${cli} is not installed`);
+  if (!loggedIn(runner, cli, host, authCache)) return no('no-login', `${cli} is not logged in for ${host} (or ${host} did not answer)`);
+  return { ...base, ok: true, cli };
+}
+
+// The PRs/MRs of one repo: `{ ok: true, open: [...], merged: [...], openPartial, mergedPartial }` or
+// `{ ok: false, kind, why }`. `sinceMs` bounds the merged list (epoch milliseconds).
+//   open:   { number, author, draft, checks: passing|failing|running|none|null, review: none|reviewed|approved|changes-requested|null,
+//             status? (GitLab's own word), waits? (GitLab: a status that holds the merge) }
+//   merged: { number, author, mergedAt (ISO) }
+export function listPrs(target, { sinceMs, runner = run, env = process.env, authCache = new Map() } = {}) {
+  const t = target?.cli ? target : prTarget(target, { runner, env, authCache });
+  if (!t.ok) return t;
+  return t.platform === 'github' ? listGitHub(t, sinceMs, runner) : listGitLab(t, sinceMs, runner);
+}
+
+function listGitHub(t, sinceMs, runner) {
+  const parts = t.repo.split('/');
+  const fail = (res) => ({ ...t, ok: false, kind: 'other', why: whyFailed(res, { platform: 'github', host: t.host, what: `the pull requests of ${shown(t.repo)}`, plural: true }) });
+  if (parts.length !== 2) return { ...t, ok: false, kind: 'no-url', why: `${shown(t.repo)} is not an owner/name GitHub repo path` };
+  const r = runner('gh', ['api', '--hostname', t.host, 'graphql', '-f', `query=${GH_QUERY}`, '-f', `owner=${parts[0]}`, '-f', `name=${parts[1]}`], { timeout: TIMEOUT });
+  // gh exits non-zero when the answer carries GraphQL `errors`: a partial answer is not an answer. Such an
+  // error comes with no HTTP status (`GraphQL: Could not resolve to a Repository …`), and is not "offline".
+  if (!r.ok && httpStatus(r) == null && /\bGraphQL:/.test(`${r.stderr || ''}${r.stdout || ''}`)) {
+    return { ...t, ok: false, kind: 'other', why: `GitHub answered the pull-request query for ${shown(t.repo)} with an error (the repo may not exist, or your login may not see it)` };
+  }
+  if (!r.ok) return fail({ ok: false, status: httpStatus(r) });
+  let body;
+  try { body = JSON.parse(r.stdout); } catch { return fail({ unreadable: true }); }
+  const repo = body?.data?.repository;
+  if (!repo || !Array.isArray(repo.open?.nodes) || !Array.isArray(repo.merged?.nodes)) return fail({ unreadable: true });
+  const open = repo.open.nodes.map((n) => ({
+    number: n.number, author: author(n.author), draft: n.isDraft === true,
+    checks: GH_CHECKS[n.commits?.nodes?.[0]?.commit?.statusCheckRollup?.state] || (n.commits?.nodes?.[0]?.commit?.statusCheckRollup ? null : 'none'),
+    review: ghReview(n),
+  }));
+  const nodes = repo.merged.nodes;
+  const merged = nodes.filter((n) => Date.parse(n.mergedAt) >= sinceMs).map((n) => ({ number: n.number, author: author(n.author), mergedAt: n.mergedAt }));
+  // Sorted by last update, newest first: the list is whole for the window once its oldest entry is older.
+  const last = nodes[nodes.length - 1];
+  return {
+    ...t, ok: true, open, merged,
+    openPartial: (repo.open.totalCount ?? 0) > open.length,
+    mergedPartial: nodes.length >= PAGE && !(Date.parse(last?.updatedAt) < sinceMs),
+  };
+}
+
+function listGitLab(t, sinceMs, runner) {
+  const at = `projects/${encodeURIComponent(t.repo)}/merge_requests`;
+  const what = `the merge requests of ${shown(t.repo)}`;
+  const fail = (res) => ({ ...t, ok: false, kind: 'other', why: whyFailed(res, { platform: 'gitlab', host: t.host, what, plural: true }) });
+  const o = api(runner, 'glab', t.host, `${at}?state=opened&per_page=${PAGE}`);
+  if (!o.ok) return fail(o);
+  const since = new Date(sinceMs).toISOString();
+  const m = api(runner, 'glab', t.host, `${at}?state=merged&order_by=updated_at&sort=desc&updated_after=${encodeURIComponent(since)}&per_page=${PAGE}`);
+  if (!m.ok) return fail(m);
+  if (!Array.isArray(o.body) || !Array.isArray(m.body)) return fail({ unreadable: true });
+  const who = (a) => (a && typeof a.username === 'string' && a.bot !== true && !/\[bot\]$/i.test(a.username) ? a.username : null);
+  const open = o.body.map((x) => {
+    const st = typeof x.detailed_merge_status === 'string' ? x.detailed_merge_status : null;
+    const checks = st && Object.hasOwn(GL_CHECKS, st) ? GL_CHECKS[st] : null;
+    return { number: x.iid, author: who(x.author), draft: x.draft === true, checks, review: null, ...(st && !checks ? { status: st } : {}), waits: !!st && GL_WAITS.includes(st) };
+  });
+  const merged = m.body.filter((x) => Date.parse(x.merged_at) >= sinceMs).map((x) => ({ number: x.iid, author: who(x.author), mergedAt: x.merged_at }));
+  return { ...t, ok: true, open, merged, openPartial: o.body.length >= PAGE, mergedPartial: m.body.length >= PAGE };
+}
+

package/cli/protection.mjs

@@ -28,7 +28,7 @@ import { SETTINGS_EDIT_HINT } from './manifest.mjs';
 import { cliFor, hostFromGitUrl, detectPlatform, plainHost } from './platform.mjs';
 
 export const PLATFORM_NAME = { github: 'GitHub', gitlab: 'GitLab' };
-const TIMEOUT = 10_000;
+export const TIMEOUT = 10_000;
 
 // A word with an `@` after its first character may be an e-mail address, and no address is ever printed
 // (E67). A branch or a repo path is printed as written otherwise.
@@ -67,7 +67,7 @@ export function httpStatus(r) {
 // A failed call keeps its body too (E109): both CLIs print the platform's answer on stdout, so a caller
 // can read WHY it failed. A body that is not JSON is null, never an error. Only the GitLab branch read
 // looks at it today — see `gitlabBranchCause`.
-function api(runner, cli, host, pathname) {
+export function api(runner, cli, host, pathname) {
   const r = runner(cli, ['api', '--hostname', host, pathname], { timeout: TIMEOUT });
   if (r.ok) {
     try { return { ok: true, body: JSON.parse(r.stdout) }; } catch { return { ok: false, status: null, unreadable: true }; }
@@ -96,7 +96,7 @@ const gitlabBranchCause = (res) => (res.status === 404 && typeof res.body?.messa
 export const PAGE = 100;
 
 // Why a call gave no answer, as a clause that finishes "not known — ".
-function whyFailed(res, { platform, host, what, plural = false }) {
+export function whyFailed(res, { platform, host, what, plural = false }) {
   const name = PLATFORM_NAME[platform];
   if (res.unreadable) return `${name} answered ${what} with something yad could not read`;
   if (res.status == null) return `yad could not reach ${host} to read ${what} (offline, or the host did not answer)`;
@@ -134,7 +134,7 @@ const count = (v) => (typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v
 // `gh auth status` is asked once per CLI and host per doctor run (`authCache`, which the caller makes
 // fresh for each run): on a network that drops packets each ask can take the full timeout, and a Product
 // with many repos on one host would pay it once per repo. Never kept longer — a login can change.
-function loggedIn(runner, cli, host, authCache) {
+export function loggedIn(runner, cli, host, authCache) {
   const key = `${cli}\0${host}`;
   if (!authCache.has(key)) authCache.set(key, runner(cli, ['auth', 'status', '--hostname', host], { timeout: TIMEOUT }).ok);
   return authCache.get(key);

package/cli/recommend.mjs

@@ -0,0 +1,301 @@
+// The recommendation catalogue — a short, hand-picked list of skills worth binding to each step (E52).
+//
+//   yad skill recommend [<step>] [--profile <p> | --epic <id>] [--json]
+//
+// WHAT IT IS FOR. The toolbox lists three skill pools (BMAD-METHOD, ECC, mattpocock/skills) as
+// "recommended — listed, never pushed". A pool holds dozens of skills, and an agent with three pools
+// installed chooses between hundreds of descriptions. This list narrows that to a few named skills per
+// step, each with the reason it fits. It recommends only: `yad skill bind` stays the one writer, and
+// nothing is ever bound for you (E84: listed, never pushed; E51: a step's line is always a team's choice).
+//
+// A CHAIN, NEVER A REPLACEMENT. yadflow's own skill for a step does work no pool skill knows about — it
+// writes the artifact where the gate looks, locks the contract, seeds the ledger. So every suggestion is
+// the pool skill FIRST and yadflow's skill LAST: `yad skill bind architecture <pool-skill> yad-architecture`.
+// A chain hands each skill what the one before it produced, and the last output is the artifact (closed
+// decision 7), so the pool skill shapes the thinking and yadflow's skill files the result.
+//
+// VERSIONED SEPARATELY (decided with the row). The list carries its own `version` and `checked` day, apart
+// from yadflow's package version, and every command that shows it prints its age. It still ships inside
+// yadflow and moves with a release: no network, no cache, no project file, so no shape change. A test
+// holds each version to one content: changing an entry without moving `version` fails.
+//
+// EVERY ENTRY IS VETTED, THE E88 WAY. Each one carries the same `vetted` record as a toolbox tool —
+// where the licence was read, the official source, the release tag on that day — plus `file`, the exact
+// SKILL.md at that tag, so the name was read from the real repository and never guessed from a pool's
+// naming habit. The release check refuses to publish while any record is older than VET_MAX_AGE_DAYS
+// (`scripts/vet-check.mjs`), exactly as for the toolbox.
+//
+// NOT THE ORCHESTRATOR. Part 7's separate package (E92–E102) ranks skills from measured evidence. This is
+// the hand-made list that comes first: a person read each skill and wrote down why it fits.
+import { createHash } from 'node:crypto';
+import { c, emitJSON, fail, hand, info, log, warn } from './lib.mjs';
+import { bindingsForProfile, loadSkillBindings, stepDef, stepSkills, STEPS } from './epic-state.mjs';
+import { TOOLBOX, isCalendarDay, vettingProblems } from './toolbox.mjs';
+
+// The list's own version and the day it was last read through as a whole. Move `version` whenever an
+// entry is added, removed or changed — the test names the new digest to record beside it.
+export const CATALOGUE = Object.freeze({ version: 1, checked: '2026-10-03' });
+
+const VETTED_ON = '2026-10-03';
+
+// ---- the list --------------------------------------------------------------------------------------
+//
+//   step     the step id it fits (a step a skill runs — never a review gate)
+//   skill    the name to bind, as an agent calls it once the pool is installed
+//   pool     the toolbox id of the pool it comes from (its install routes are the pool's)
+//   reason   one sentence: what it adds before yadflow's own skill runs
+//   caveat   null, or one sentence a team must know before binding it (an install profile, a file it writes)
+//   file     the skill's SKILL.md in the pool's repository, at `vetted.release`
+//   licence  + vetted: the E88 record, read for this entry
+// The vetting record each pool's skills share, read on VETTED_ON at the pool's release tag: the licence
+// from its LICENSE file, the source, and the npm package its installer is. Every SKILL.md below was
+// fetched at that tag and its `name` read; none sets `disable-model-invocation`, so an agent can run each
+// one as a step of a chain. Deprecated BMAD names that only forward to a newer skill (`bmad-create-prd`,
+// `bmad-create-architecture`, `bmad-dev-story` — removed in BMAD v7) are left out on purpose.
+const BMAD = Object.freeze({
+  on: VETTED_ON, licenceFrom: 'https://github.com/bmad-code-org/BMAD-METHOD/blob/main/LICENSE',
+  source: 'https://github.com/bmad-code-org/BMAD-METHOD', release: 'v6.12.0',
+  packages: [{ registry: 'npm', name: 'bmad-method', version: '6.12.0' }],
+  note: "GitHub reads the LICENSE as NOASSERTION: it is MIT text with a trademark notice added. Named as `npx bmad-method install` copies it (a plugin install calls it <plugin>:<name>).",
+});
+const ECC = Object.freeze({
+  on: VETTED_ON, licenceFrom: 'https://github.com/affaan-m/ECC/blob/main/LICENSE',
+  source: 'https://github.com/affaan-m/ECC', release: 'v2.2.3',
+  packages: [{ registry: 'npm', name: 'ecc-universal', version: '2.2.3' }],
+  note: 'Named as `npx ecc-universal install` copies it; the `ecc@ecc` plugin calls it ecc:<name>.',
+});
+const MATT = Object.freeze({
+  on: VETTED_ON, licenceFrom: 'https://github.com/mattpocock/skills/blob/main/LICENSE',
+  source: 'https://github.com/mattpocock/skills', release: 'v1.2.3',
+  packages: [],
+  note: 'Named as the mattpocock-skills plugin calls it (<plugin>:<name>): a plugin is the one install route the toolbox lists for this pool.',
+});
+const B = 'https://github.com/bmad-code-org/BMAD-METHOD/blob/v6.12.0/src';
+const E = 'https://github.com/affaan-m/ECC/blob/v2.2.3/skills';
+const M = 'https://github.com/mattpocock/skills/blob/v1.2.3/skills';
+const ECC_PROFILE = (p) => `Not in ECC's smaller install profiles: install with --profile ${p}, or use the ecc@ecc plugin.`;
+
+export const RECOMMENDATIONS = Object.freeze([
+  // ---- foundation: the product's purpose, scope and principles ----
+  { step: 'foundation', skill: 'bmad-prfaq', pool: 'bmad-method', licence: 'MIT', file: `${B}/bmm-skills/plan/bmad-prfaq/SKILL.md`, vetted: BMAD, caveat: null,
+    reason: 'Works backwards from a press release and its hard questions, a sharp test of the product\'s purpose before the Foundation fixes it.' },
+  { step: 'foundation', skill: 'bmad-brainstorming', pool: 'bmad-method', licence: 'MIT', file: `${B}/core-skills/bmad-brainstorming/SKILL.md`, vetted: BMAD, caveat: null,
+    reason: 'Guided ideation with several techniques, so the options are wide before the principles are narrowed.' },
+  { step: 'foundation', skill: 'council', pool: 'ecc', licence: 'MIT', file: `${E}/council/SKILL.md`, vetted: ECC, caveat: null,
+    reason: 'A four-voice structured disagreement for the go/no-go and trade-off calls a Foundation records.' },
+
+  // ---- analysis: pressure-test the idea ----
+  { step: 'analysis', skill: 'bmad-forge-idea', pool: 'bmad-method', licence: 'MIT', file: `${B}/core-skills/bmad-forge-idea/SKILL.md`, vetted: BMAD, caveat: null,
+    reason: 'Several personas attack a half-formed idea, so the analysis starts from one that has already been tested.' },
+  { step: 'analysis', skill: 'bmad-product-brief', pool: 'bmad-method', licence: 'MIT', file: `${B}/bmm-skills/plan/bmad-product-brief/SKILL.md`, vetted: BMAD, caveat: null,
+    reason: 'A structured product-brief template and validation pass to feed the discovery brief.' },
+
+  // ---- epic ----
+  { step: 'epic', skill: 'bmad-prd', pool: 'bmad-method', licence: 'MIT', file: `${B}/bmm-skills/plan/bmad-prd/SKILL.md`, vetted: BMAD, caveat: null,
+    reason: 'BMAD\'s product-manager workflow for writing and validating a PRD, the closest counterpart of the epic.' },
+  { step: 'epic', skill: 'mattpocock-skills:grilling', pool: 'mattpocock-skills', licence: 'MIT', file: `${M}/productivity/grilling/SKILL.md`, vetted: MATT, caveat: null,
+    reason: 'Questions the plan hard before the product manager writes it down.' },
+
+  // ---- architecture: the design and the locked contract ----
+  { step: 'architecture', skill: 'bmad-architecture', pool: 'bmad-method', licence: 'MIT', file: `${B}/bmm-skills/plan/bmad-architecture/SKILL.md`, vetted: BMAD, caveat: null,
+    reason: 'Records the decisions that keep separately built parts consistent, which is this step\'s cross-repo concern.' },
+  { step: 'architecture', skill: 'contract-first', pool: 'ecc', licence: 'MIT', file: `${E}/contract-first/SKILL.md`, vetted: ECC, caveat: ECC_PROFILE('developer'),
+    reason: 'Puts the contract in a machine-checkable form (OpenAPI, AsyncAPI, Protobuf or JSON Schema) before it is locked.' },
+  { step: 'architecture', skill: 'architecture-decision-records', pool: 'ecc', licence: 'MIT', file: `${E}/architecture-decision-records/SKILL.md`, vetted: ECC,
+    caveat: 'It writes numbered records under docs/adr/ as well.',
+    reason: 'Captures each architecture choice as a numbered decision record with the alternatives weighed.' },
+
+  // ---- ui-design ----
+  { step: 'ui-design', skill: 'bmad-ux', pool: 'bmad-method', licence: 'MIT', file: `${B}/bmm-skills/plan/bmad-ux/SKILL.md`, vetted: BMAD,
+    caveat: 'It writes its own DESIGN.md, the file yad-ui writes last, so review that yad-ui kept what you want.',
+    reason: 'BMAD\'s UX designer: how the product looks and how it behaves, the direct counterpart of this step.' },
+  { step: 'ui-design', skill: 'accessibility', pool: 'ecc', licence: 'MIT', file: `${E}/accessibility/SKILL.md`, vetted: ECC, caveat: ECC_PROFILE('developer'),
+    reason: 'Adds a WCAG 2.2 AA pass for web, iOS and Android to the design.' },
+
+  // ---- stories ----
+  { step: 'stories', skill: 'bmad-create-epics-and-stories', pool: 'bmad-method', licence: 'MIT', file: `${B}/bmm-skills/plan/bmad-create-epics-and-stories/SKILL.md`, vetted: BMAD, caveat: null,
+    reason: 'BMAD\'s own breakdown of requirements into stories, as a first draft for yad-stories to file and tag by repo.' },
+
+  // ---- test-cases ----
+  { step: 'test-cases', skill: 'intent-driven-development', pool: 'ecc', licence: 'MIT', file: `${E}/intent-driven-development/SKILL.md`, vetted: ECC, caveat: null,
+    reason: 'Turns stories into scoped, checkable acceptance criteria with a way to verify each, the raw material of test cases.' },
+
+  // ---- implement: one small task ----
+  { step: 'implement', skill: 'mattpocock-skills:tdd', pool: 'mattpocock-skills', licence: 'MIT', file: `${M}/engineering/tdd/SKILL.md`, vetted: MATT, caveat: null,
+    reason: 'Red-green-refactor discipline inside the task\'s small diff.' },
+  { step: 'implement', skill: 'tdd-workflow', pool: 'ecc', licence: 'MIT', file: `${E}/tdd-workflow/SKILL.md`, vetted: ECC, caveat: null,
+    reason: 'Test-first work with a coverage target, for teams that want the number enforced as they go.' },
+  { step: 'implement', skill: 'bmad-build', pool: 'bmad-method', licence: 'MIT', file: `${B}/bmm-skills/ship/bmad-build/SKILL.md`, vetted: BMAD,
+    caveat: 'It aims to finish a whole story, so it can push past yad-implement\'s one task and three files; yad-implement still stops it there.',
+    reason: 'BMAD\'s official implementation method, with its own review and verification steps.' },
+
+  // ---- checks ----
+  { step: 'checks', skill: 'verification-loop', pool: 'ecc', licence: 'MIT', file: `${E}/verification-loop/SKILL.md`, vetted: ECC, caveat: null,
+    reason: 'Runs build, type check, lint, tests, a security search and a diff review locally, with a pass/fail report, before the CI gates run.' },
+
+  // ---- engineer-review: a first pass before the human review is recorded ----
+  { step: 'engineer-review', skill: 'bmad-code-review', pool: 'bmad-method', licence: 'MIT', file: `${B}/bmm-skills/ship/bmad-code-review/SKILL.md`, vetted: BMAD, caveat: null,
+    reason: 'Several independent reviewers in parallel, then sorted findings, as a first pass before a person reviews.' },
+  { step: 'engineer-review', skill: 'bmad-walkthrough', pool: 'bmad-method', licence: 'MIT', file: `${B}/bmm-skills/ship/bmad-walkthrough/SKILL.md`, vetted: BMAD, caveat: null,
+    reason: 'Walks the human reviewer through what the change is for, what to look at, and how to test it.' },
+]);
+
+// ---- checking an entry ------------------------------------------------------------------------------
+
+const POOLS = () => TOOLBOX.filter((t) => t.tier === 'recommended').map((t) => t.id);
+const bindable = (step) => !!stepDef(step)?.skill && STEPS.some((s) => s.id === step);
+
+// Every way an entry is malformed, as sentences; [] means it is well formed. The vetting record is
+// checked by the toolbox's own `vettingProblems`, so one rule holds both lists.
+export function recommendationProblems(r) {
+  const out = [];
+  const need = (ok, what) => { if (!ok) out.push(what); };
+  need(typeof r?.step === 'string' && bindable(r.step), 'step is a step a skill runs (not a review gate)');
+  need(typeof r?.skill === 'string' && /^[a-z0-9][a-z0-9:_-]*$/i.test(r.skill), 'skill is a skill name');
+  need(POOLS().includes(r?.pool), `pool is one of the toolbox's recommended pools (${POOLS().join(', ')})`);
+  need(typeof r?.reason === 'string' && r.reason.length > 0 && /\.$/.test(r.reason), 'reason is one sentence ending in a full stop');
+  need(typeof r?.file === 'string' && /^https:\/\/[^/\s]+\/.+\/SKILL\.md$/.test(r.file), 'file is the https URL of the skill\'s SKILL.md');
+  need(typeof r?.licence === 'string' && r.licence.length > 0, 'licence is set');
+  need(r?.caveat === null || (typeof r?.caveat === 'string' && /\.$/.test(r.caveat)), 'caveat is null or one sentence ending in a full stop');
+  for (const p of vettingProblems(r)) out.push(p);
+  // The file must be read at the release the record names, so the name was checked at that tag.
+  if (r?.vetted?.release && typeof r?.file === 'string') need(r.file.includes(`/${r.vetted.release}/`), 'file is read at vetted.release');
+  return out;
+}
+
+// An entry seen through the toolbox's vetting helpers, which name a record by `id` and `name`.
+export const asVetted = (r) => ({ ...r, id: `${r.step}:${r.skill}`, name: `${r.skill} for ${r.step}` });
+
+// A digest of the list's content, so a test can hold each version to exactly one list.
+export const catalogueDigest = (list = RECOMMENDATIONS) =>
+  createHash('sha256').update(JSON.stringify(list)).digest('hex').slice(0, 16);
+
+// How many whole days old the list is on `today` (a Date), counted in UTC like every record date.
+export function catalogueAge(today = new Date(), checked = CATALOGUE.checked) {
+  if (!isCalendarDay(checked)) return null;
+  const day = Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate());
+  return Math.floor((day - Date.parse(`${checked}T00:00:00Z`)) / 86400000);
+}
+
+// "version 1, checked 2026-10-03 (12 days ago)" — said wherever the list is shown.
+export function catalogueLabel(today = new Date()) {
+  const age = catalogueAge(today);
+  const ago = age === null ? '' : age <= 0 ? ' (today)' : age === 1 ? ' (1 day ago)' : ` (${age} days ago)`;
+  return `recommendation catalogue version ${CATALOGUE.version}, checked ${CATALOGUE.checked}${ago}`;
+}
+
+// The recommendations for one step, in the list's order.
+export const recommendationsFor = (step, list = RECOMMENDATIONS) => list.filter((r) => r.step === step);
+
+// The chain a suggestion binds: the pool skill first, yadflow's own skill last (see the header).
+export function suggestedChain(r) {
+  const own = stepDef(r.step)?.skill;
+  return own && own !== r.skill ? [r.skill, own] : [r.skill];
+}
+
+export function bindCommand(r, profile = null) {
+  return `yad skill bind ${r.step} ${suggestedChain(r).join(' ')}${profile ? ` --profile ${profile}` : ''}`;
+}
+
+// ---- yad skill recommend -----------------------------------------------------------------------------
+
+const poolName = (id) => TOOLBOX.find((t) => t.id === id)?.name ?? id;
+
+// Is the BOUND name this catalogue pick? A team that installed a pool as a plugin binds
+// `ecc:contract-first`, and that is the catalogue's bare `contract-first`. Only that direction: a pick the
+// catalogue names WITH its plugin (`mattpocock-skills:tdd`) is matched exactly, because a bare `tdd` is
+// just as likely a team's own skill (review 2) — matching it would hide the bind command from a team that
+// never ran the pool's skill. These are the plugin spellings `installedSkillNames` also accepts — including
+// `<plugin>@<marketplace>:<skill>`, whose marketplace part is dropped before the exact comparison.
+const bareName = (s) => String(s).split(':').at(-1);
+const withoutMarketplace = (s) => String(s).replace(/^([^:@]+)@[^:]+:/, '$1:');
+export const sameSkill = (bound, pick) => withoutMarketplace(bound) === pick || (!pick.includes(':') && bareName(bound) === pick);
+
+// One row per recommendation: what it is, whether the step already runs it, whether it is installed here.
+// `bindings` is the view for the route shown; `names` is `installedSkillNames`' answer (null: unknown).
+// `onRoute(step)` is false for a step the route never walks — `yad skill bind --profile` refuses those, so
+// a command for one would be a command that fails.
+export function recommendRows({ step = null, bindings, names, list = RECOMMENDATIONS, profile = null, onRoute = () => true }) {
+  return list.filter((r) => (!step || r.step === step) && onRoute(r.step)).map((r) => {
+    const running = stepSkills(r.step, bindings);
+    const own = stepDef(r.step)?.skill;
+    return {
+      step: r.step, skill: r.skill, pool: r.pool, reason: r.reason, caveat: r.caveat, file: r.file, licence: r.licence,
+      bound: running.some((s) => sameSkill(s, r.skill)),
+      // Bound so that yadflow's own skill does not run LAST — in its place, or before it. Allowed (the
+      // file wins), never quiet: the last output of a chain is the artifact (closed decision 7), so the
+      // pool skill's output is then filed and yadflow's skill does not write it where the gate looks.
+      // yadflow's own skill is compared exactly: yadflow ships no plugin, so it has no `<plugin>:` spelling.
+      ownSkillDropped: running.some((s) => sameSkill(s, r.skill)) && !!own && running.at(-1) !== own,
+      installed: names ? names.has(r.skill) : null,
+      bind: suggestedChain(r),
+      command: bindCommand(r, profile),
+      vetted: r.vetted,
+    };
+  });
+}
+
+// The printer and --json answer of `yad skill recommend`. `yad skill` (cli/skill.mjs) works out the route
+// and asks `yad detect` what is installed, then calls this.
+export function showRecommendations(root, { step = null, json = false, route = { profile: null }, names = null, today = new Date(), onRoute = () => true } = {}) {
+  if (step !== null && step !== undefined && !stepDef(step)?.skill) {
+    // A review gate is a step, but no skill runs it, so nothing could be recommended for it — the same
+    // reason `yad skill bind` refuses one.
+    fail(stepDef(step) ? `\`${step}\` is a review gate — no skill runs it` : `\`${step}\` is not a step this yadflow runs`);
+    hand(`steps with a recommendation: ${[...new Set(RECOMMENDATIONS.map((r) => r.step))].join(' · ') || '(none yet)'}`);
+    process.exitCode = 1;
+    return undefined;
+  }
+  if (step && !onRoute(step)) {
+    fail(`route \`${route.profile}\` has no \`${step}\` step — nothing would ever run a binding there`);
+    hand(`see \`yad skill recommend --profile ${route.profile}\` for the steps it walks`);
+    process.exitCode = 1;
+    return undefined;
+  }
+  const bindings = bindingsForProfile(loadSkillBindings(root), route.profile);
+  const rows = recommendRows({ step, bindings, names, profile: route.profile, onRoute });
+  const catalogue = { version: CATALOGUE.version, checked: CATALOGUE.checked, age: catalogueAge(today) };
+
+  if (json) {
+    return emitJSON({
+      ok: true, catalogue, step: step ?? null, profile: route.profile, ...(route.epic ? { epic: route.epic } : {}),
+      installedChecked: !!names, recommendations: rows,
+    });
+  }
+
+  info(catalogueLabel(today));
+  if (route.profile) info(`route ${c.bold(route.profile)}${route.epic ? ` (${route.epic})` : ''} — the bind commands apply to it only`);
+  if (!rows.length) {
+    info(step ? `no recommendation for ${c.bold(step)} — yadflow's own skill (${stepDef(step)?.skill ?? 'none'}) is the one to run`
+      : route.profile ? `no recommendation for a step route ${route.profile} walks` : 'the catalogue is empty');
+    return { rows };
+  }
+  let last = null;
+  for (const r of rows) {
+    if (r.step !== last) {
+      log(`\n  ${c.bold(r.step)} ${c.dim(`— runs ${stepSkills(r.step, bindings).join(' → ') || '(none)'} now`)}`);
+      last = r.step;
+    }
+    const mark = r.bound ? c.green('✓') : r.installed === false ? c.yellow('?') : '•';
+    log(`  ${mark} ${c.bold(r.skill)} ${c.dim(`(${poolName(r.pool)}, ${r.licence})`)}`);
+    log(`      ${r.reason}`);
+    if (r.caveat) log(`      ${c.yellow('note:')} ${r.caveat}`);
+    log(`      ${r.bound ? c.dim('already bound to this step') : c.cyan(r.command)}`);
+    if (r.ownSkillDropped) {
+      warn(`${r.step} runs ${r.skill} without ${stepDef(r.step).skill} last — the last skill's output is the artifact, so yadflow's skill does not file it where the gate looks (\`${r.command}\` chains them)`);
+    }
+  }
+  log('');
+  info('each one runs BEFORE yadflow\'s own skill, which still writes the artifact — every extra skill is another model run');
+  if (rows.some((r) => r.bound)) info(`${c.green('✓')} = this step already runs it`);
+  if (!names) warn('could not check which skills are installed here — `yad detect` could not read this folder or the home folder');
+  else if (rows.some((r) => r.installed === false && !r.bound)) {
+    info(`${c.yellow('?')} = not installed here — install its pool first (\`yad toolbox list\` shows how)`);
+  }
+  hand(`nothing is bound for you: run a command above to choose one, and \`yad skill unbind <step>${route.profile ? ` --profile ${route.profile}` : ''}\` to undo it`);
+  return { rows };
+}
+
+// Exported for `yad skill list`: the skills the catalogue recommends for a step (names only). Empty for a
+// step the route never walks — `recommend` hides those too, and a bind for one is refused.
+export const recommendedSkills = (step, onRoute = () => true) => (onRoute(step) ? recommendationsFor(step).map((r) => r.skill) : []);

package/cli/setup.mjs

@@ -16,7 +16,7 @@ import {
 import { modeFields, modeOf } from './mode.mjs';
 import { recordActor } from './skip.mjs';
 import { loadSkillBindings, stepSkills } from './epic-state.mjs';
-import { offerToolbox } from './toolbox.mjs';
+import { offerToolbox, REPOMIX_VERSION } from './toolbox.mjs';
 
 // Parse a comma/space separated list into a clean, deduped array of trimmed tokens.
 export function parseList(s) {
@@ -769,7 +769,8 @@ export function packRepo(root, repo) {
   fs.mkdirSync(path.dirname(out), { recursive: true });
   ensurePackIgnored(root); // keep the pack out of git before it is (re)written — see repo-publish.mjs invariant 1
   info(`${nm}: packing with repomix …`);
-  const r = runLauncher('npx', ['repomix@latest', '--compress', '--include-logs', '--style', 'markdown', '-o', out], { cwd: repoRoot });
+  // The vetted version, never `@latest` (E88): a new Repomix release reaches users only once it is vetted.
+  const r = runLauncher('npx', [`repomix@${REPOMIX_VERSION}`, '--compress', '--include-logs', '--style', 'markdown', '-o', out], { cwd: repoRoot });
   if (r.ok) { ok(`${nm}: cached ${forTerminal(repo.contextPack)}`); hand(`${nm}: generate the code-map in your AI agent (yad-connect-repos)`); return true; }
   fail(`${nm}: repomix failed — ${forTerminal(r.stderr.split('\n')[0]) || 'unknown error'}`);
   return false;