yadflow 4.3.0 → 4.5.0

package/cli/toolbox.mjs

@@ -46,33 +46,75 @@ const TIER_TITLES = { core: 'Core — offered at setup', recommended: 'Recommend
 
 const CHECKED = '2026-10-01';
 
+// ---- vetting (E88) --------------------------------------------------------------------------------
+//
+// EVERY ENTRY IS VETTED BEFORE IT SHIPS, and the vetting is redone before it goes stale. `checked` above
+// is when an entry's INSTALL routes were read; `vetted` is the proof that the tool is what it claims:
+//
+//   on           the day the vetting was done. Per entry: they all start on VETTED_ON, and re-vetting ONE
+//                tool gives that entry its own date literal rather than moving the shared one
+//   licenceFrom  where the licence was read — the repository's LICENSE file, or, for a closed tool, the
+//                vendor's own terms page. `licence` on the entry is the answer; this is the proof
+//   source       the official home the tool comes from (its owner's repository or docs)
+//   release      the source's latest release tag on that day, or null where none is published. A tag is
+//                provenance, not a version: tags read `v1.18.1`, `skill-v4.5.0`, `cli-2.11.0`
+//   packages     each registry package an install route names, confirmed to point back to `source`
+//                (npm `repository`, or the source's own README naming it), with the version on that day
+//   note         anything a reader of the record has to know — a missing LICENSE, a rebrand
+//
+// Licence and source only, as decided with the row: no maintenance score, no security scan, and no
+// tested version range — `versions` stays null. A team's own tools (`yad toolbox add --custom`) are the
+// team's to vet; yad vets only the list it ships.
+//
+// TWO GATES. The unit suite holds every record complete (`vettingProblems`); the release check refuses
+// to publish while any record is older than VET_MAX_AGE_DAYS (`staleVettings`, `scripts/vet-check.mjs`).
+// The age is checked only at release, never in the unit suite, so `main` does not turn red by itself.
+const VETTED_ON = '2026-10-02';
+export const VET_MAX_AGE_DAYS = 180;
+const VET_REGISTRIES = Object.freeze(['npm', 'pypi']);
+
 // The list itself, checked against each tool's own repository and docs on CHECKED. `install` keeps only
 // the routes the roadmap's four types describe (plugin, npm, python, script); a tool's other routes
 // (Docker, Homebrew, a VS Code extension) are in its own README, which `source` links. `versions` is null
-// everywhere for now: no bound has been tested yet — E88 vets each default and is where a known-good
-// range is earned. `records` is the exact line a skill writes when the tool is absent, so E87 can point
-// the skill at this entry without renaming anything.
+// everywhere: no bound has been tested, and E88 vets licence and source, not a version range. `records`
+// is the exact line a skill writes when the tool is absent. Each skill in
+// `usedBy` quotes `fallback` and `records` word for word in its "When a tool is missing" section (E87):
+// change the words here, then rewrite the sections with `skillFallbackSection`.
 export const TOOLBOX = Object.freeze([
   // ---- core: offered at setup --------------------------------------------------------------------
   {
     id: 'repomix', name: 'Repomix', tier: 'core', role: 'packs each code repo into one file the Shape steps read',
     licence: 'MIT', source: 'https://github.com/yamadashy/repomix', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://github.com/yamadashy/repomix/blob/main/LICENSE',
+      source: 'https://github.com/yamadashy/repomix', release: 'v1.18.1',
+      packages: [{ registry: 'npm', name: 'repomix', version: '1.18.1' }],
+      note: null,
+    },
     install: [
-      { type: 'npm', command: 'npx repomix@latest' },
-      { type: 'npm', command: 'npm install -g repomix' },
+      { type: 'npm', command: 'npx repomix@1.18.1' },
+      { type: 'npm', command: 'npm install -g repomix@1.18.1' },
       { type: 'plugin', command: '/plugin marketplace add yamadashy/repomix, then /plugin install repomix-mcp@repomix' },
     ],
     manual: null,
-    // yad runs it through `npx repomix@latest` (setup, `yad repo refresh`), so `npx` alone makes it usable.
+    // yad runs it through npx, at the vetted version (setup, `yad repo refresh`; REPOMIX_VERSION below),
+    // so `npx` alone makes it usable.
     detect: { npx: true, bins: ['repomix'], plugins: ['repomix-mcp', 'repomix-commands', 'repomix-explorer'], mcp: ['repomix'], skills: ['repomix-explorer'] },
     versions: null,
-    fallback: 'no code pack: repos are not packed, and the Shape steps read the code map alone',
-    records: null, note: null,
-    usedBy: ['yad setup', 'yad repo refresh', 'yad-connect-repos'],
+    fallback: 'no Repomix pack. yad-connect-repos and yad-backfill put the same context together by hand, from the source tree and the recent git log, and the Shape steps read the code map',
+    records: 'source: repomix-unavailable',
+    note: 'yad setup and yad repo refresh skip the pack only when npx is missing. They do not follow a team skip.',
+    usedBy: ['yad setup', 'yad repo refresh', 'yad-connect-repos', 'yad-backfill'],
   },
   {
     id: 'spec-kit', name: 'Spec Kit', tier: 'core', role: 'runs the spec ceremony (specify → plan → tasks) in a code repo',
     licence: 'MIT', source: 'https://github.com/github/spec-kit', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://github.com/github/spec-kit/blob/main/LICENSE',
+      source: 'https://github.com/github/spec-kit', release: 'v1.0.13',
+      packages: [{ registry: 'pypi', name: 'specify-cli', version: '1.0.13' }],
+      note: "PyPI's specify-cli lists no project links and no provenance; Spec Kit's own README names `uv tool install specify-cli`, which is the link to the source.",
+    },
     install: [
       { type: 'python', command: 'uv tool install specify-cli, then specify init <project> --integration claude' },
       { type: 'python', command: 'pipx install specify-cli' },
@@ -89,6 +131,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'impeccable', name: 'Impeccable', tier: 'core', role: 'drives the UI design step (document, extract, craft)',
     licence: 'Apache-2.0', source: 'https://github.com/pbakaus/impeccable', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://github.com/pbakaus/impeccable/blob/main/LICENSE',
+      source: 'https://github.com/pbakaus/impeccable', release: 'skill-v4.5.0',
+      packages: [{ registry: 'npm', name: 'impeccable', version: '4.1.0' }],
+      note: "The skill and the npm installer are versioned separately: the release tag is the skill, the npm version is the installer.",
+    },
     install: [
       { type: 'npm', command: 'npx impeccable install' },
       { type: 'plugin', command: '/plugin marketplace add pbakaus/impeccable, then /plugin install impeccable@impeccable' },
@@ -96,7 +144,7 @@ export const TOOLBOX = Object.freeze([
     manual: null,
     detect: { skills: ['impeccable'], plugins: ['impeccable'] },
     versions: null,
-    fallback: 'Markdown-only UI design: yad-ui writes ui-design.md and DESIGN.md directly',
+    fallback: 'markdown-only UI design: yad-ui writes ui-design.md and DESIGN.md directly',
     records: 'impeccable: not-installed', note: null,
     usedBy: ['yad-ui'],
   },
@@ -106,6 +154,12 @@ export const TOOLBOX = Object.freeze([
     id: 'bmad-method', name: 'BMAD-METHOD', tier: 'recommended', role: 'a pool of planning and building skills',
     // The LICENSE file is MIT text with attribution added (GitHub reads it as NOASSERTION); "BMad" is a trademark.
     licence: 'MIT', source: 'https://github.com/bmad-code-org/BMAD-METHOD', checked: CHECKED,
+    vetted: {
+      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 an attribution clause added; npm declares MIT.",
+    },
     install: [
       { type: 'npm', command: 'npx bmad-method install' },
       { type: 'plugin', command: '/plugin marketplace add bmad-code-org/bmad-plugins, then install bmad-method from /plugin' },
@@ -121,6 +175,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'ecc', name: 'ECC (Everything Claude Code)', tier: 'recommended', role: 'a large pool of skills, agents and hooks',
     licence: 'MIT', source: 'https://github.com/affaan-m/ECC', checked: CHECKED,
+    vetted: {
+      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: null,
+    },
     install: [
       { type: 'npm', command: 'npx ecc-universal install --guided' },
       { type: 'plugin', command: '/plugin marketplace add https://github.com/affaan-m/ECC, then /plugin install ecc@ecc' },
@@ -137,6 +197,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'mattpocock-skills', name: 'mattpocock/skills', tier: 'recommended', role: 'a small pool of engineering skills',
     licence: 'MIT', source: 'https://github.com/mattpocock/skills', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://github.com/mattpocock/skills/blob/main/LICENSE',
+      source: 'https://github.com/mattpocock/skills', release: 'v1.2.3',
+      packages: [],
+      note: null,
+    },
     install: [{ type: 'plugin', command: 'claude plugins install mattpocock-skills' }],
     manual: null,
     // Generic names (`tdd`, `code-review`) collide with other packs; this one is its own.
@@ -151,6 +217,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'figma', name: 'Figma', tier: 'connector', role: 'design tool: yad-ui generates and links screens in it',
     licence: 'proprietary', source: 'https://developers.figma.com/docs/figma-mcp-server/', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://www.figma.com/legal/tos/',
+      source: 'https://github.com/figma/mcp-server-guide', release: null,
+      packages: [],
+      note: "The plugin comes from Anthropic's official marketplace, which points at figma/mcp-server-guide; that repository has no LICENSE file, so the proof of terms is Figma's own.",
+    },
     install: [{ type: 'plugin', command: 'claude plugin install figma@claude-plugins-official' }],
     manual: 'https://developers.figma.com/docs/figma-mcp-server/',
     detect: { plugins: ['figma'], mcp: ['figma', 'figma-desktop', 'html-to-design'] },
@@ -162,6 +234,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'pencil', name: 'Pencil (pen.dev)', tier: 'connector', role: 'design tool: yad-ui writes .pen web and mobile screens',
     licence: 'proprietary', source: 'https://docs.pencil.dev/getting-started/installation', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://www.pen.dev/terms-of-use',
+      source: 'https://docs.pencil.dev/getting-started/installation', release: null,
+      packages: [],
+      note: "Pencil now publishes as pen.dev; its terms live there and the old docs address still answers.",
+    },
     install: [],
     manual: 'https://docs.pencil.dev/getting-started/installation',
     detect: { mcp: ['pencil'] },
@@ -173,6 +251,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'playwright', name: 'Playwright MCP', tier: 'connector', role: 'testing tool: generates and runs browser and API tests',
     licence: 'Apache-2.0', source: 'https://github.com/microsoft/playwright-mcp', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://github.com/microsoft/playwright-mcp/blob/main/LICENSE',
+      source: 'https://github.com/microsoft/playwright-mcp', release: 'v0.0.83',
+      packages: [{ registry: 'npm', name: '@playwright/mcp', version: '0.0.83' }],
+      note: null,
+    },
     install: [{ type: 'npm', command: 'claude mcp add playwright npx @playwright/mcp@latest' }],
     manual: null,
     detect: { mcp: ['playwright'], plugins: ['playwright'] },
@@ -185,6 +269,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'cypress', name: 'Cypress', tier: 'connector', role: 'testing tool: Cypress specs',
     licence: 'proprietary', source: 'https://docs.cypress.io/cloud/integrations/cloud-mcp', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://www.cypress.io/terms-of-use',
+      source: 'https://docs.cypress.io/cloud/integrations/cloud-mcp', release: null,
+      packages: [],
+      note: null,
+    },
     install: [],
     manual: 'https://docs.cypress.io/cloud/integrations/cloud-mcp',
     detect: { mcp: ['cypress', 'cypress-cloud'] },
@@ -197,6 +287,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'pytest', name: 'pytest', tier: 'connector', role: 'testing tool: service-layer tests',
     licence: 'MIT', source: 'https://github.com/pytest-dev/pytest', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://github.com/pytest-dev/pytest/blob/main/LICENSE',
+      source: 'https://github.com/pytest-dev/pytest', release: '9.1.1',
+      packages: [],
+      note: null,
+    },
     install: [],
     manual: 'https://docs.pytest.org/',
     detect: { mcp: ['pytest'] },
@@ -209,6 +305,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'maestro', name: 'Maestro', tier: 'connector', role: 'testing tool: mobile UI flows',
     licence: 'Apache-2.0', source: 'https://github.com/mobile-dev-inc/Maestro', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://github.com/mobile-dev-inc/Maestro/blob/main/LICENSE',
+      source: 'https://github.com/mobile-dev-inc/Maestro', release: 'cli-2.11.0',
+      packages: [],
+      note: null,
+    },
     install: [{ type: 'script', command: 'curl -fsSL "https://get.maestro.mobile.dev" | bash, then claude mcp add maestro -- maestro mcp' }],
     manual: 'https://docs.maestro.dev/get-started/maestro-mcp',
     detect: { bins: ['maestro'], mcp: ['maestro'] },
@@ -220,6 +322,12 @@ export const TOOLBOX = Object.freeze([
   {
     id: 'deeptutor', name: 'DeepTutor', tier: 'connector', role: 'learning tool: tutors a team member on what is being built',
     licence: 'Apache-2.0', source: 'https://github.com/HKUDS/DeepTutor', checked: CHECKED,
+    vetted: {
+      on: VETTED_ON, licenceFrom: 'https://github.com/HKUDS/DeepTutor/blob/main/LICENSE',
+      source: 'https://github.com/HKUDS/DeepTutor', release: 'v1.6.12',
+      packages: [{ registry: 'pypi', name: 'deeptutor', version: '1.6.12' }],
+      note: "PyPI's deeptutor lists no project links; DeepTutor's own README names `pip install -U deeptutor`, which is the link to the source.",
+    },
     install: [{ type: 'python', command: 'pip install -U deeptutor, then deeptutor init' }],
     manual: null,
     detect: { bins: ['deeptutor'] },
@@ -263,13 +371,89 @@ export function toolProblems(t) {
   }
   need(t?.versions === null || (typeof t?.versions === 'string' && parseRange(t.versions) !== null), 'versions is null or a range this reader understands');
   need(typeof t?.fallback === 'string' && t.fallback.length > 0, 'fallback says what yadflow does without it');
+  // A skill's section adds the full stop (E87), so a fallback ending in one would print two.
+  need(typeof t?.fallback !== 'string' || !/[.\s]$/.test(t.fallback), 'fallback ends without a full stop or a space');
   need(t?.records === null || (typeof t?.records === 'string' && t.records.length > 0), 'records is null or the line a skill writes');
   need(t?.note === null || (typeof t?.note === 'string' && t.note.length > 0), 'note is null or a sentence');
   need(t?.manual === null || (typeof t?.manual === 'string' && /^https:\/\//.test(t.manual)), 'manual is null or an https URL');
   need(isStringList(t?.usedBy), 'usedBy lists the skills or commands that use it');
+  need(t?.tier !== 'connector' || !isStringList(t?.usedBy) || connectorFile(t) !== null, 'a connector names the yad-connect-* skill that connects it');
+  return out;
+}
+
+// Every way a SHIPPED entry's vetting record is incomplete, as sentences (E88). [] means vetted. Kept out of
+// `toolProblems` because a team's own tool is well formed without one: yad vets only what it ships.
+export function vettingProblems(t) {
+  const out = [];
+  const need = (ok, what) => { if (!ok) out.push(what); };
+  const v = t?.vetted;
+  need(v && typeof v === 'object' && !Array.isArray(v), 'vetted is set — a tool ships only once its licence and source are vetted');
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return out;
+  need(isCalendarDay(v.on), 'vetted.on is a real YYYY-MM-DD date');
+  need(typeof v.licenceFrom === 'string' && HTTPS_URL.test(v.licenceFrom), 'vetted.licenceFrom is the https URL the licence was read from');
+  need(typeof v.source === 'string' && HTTPS_URL.test(v.source), 'vetted.source is the https URL of the official home');
+  need(v.release === null || (typeof v.release === 'string' && v.release.length > 0), 'vetted.release is null or the release tag on that day');
+  need(Array.isArray(v.packages), 'vetted.packages is a list');
+  for (const p of Array.isArray(v.packages) ? v.packages : []) {
+    need(VET_REGISTRIES.includes(p?.registry), `a vetted package's registry is one of ${VET_REGISTRIES.join(', ')}`);
+    need(typeof p?.name === 'string' && p.name.length > 0, 'a vetted package has its name');
+    need(parseVersion(p?.version)?.full === true, 'a vetted package has the full version that was vetted (1.2.3)');
+  }
+  need(v.note === null || (typeof v.note === 'string' && v.note.length > 0), 'vetted.note is null or a sentence');
+  // A closed tool has no LICENSE file to read, so its proof must be the vendor's terms, not a repo file.
+  need(t.licence !== 'proprietary' || !isRepoLicenceFile(v.licenceFrom), 'a proprietary tool\'s licence proof is its terms page');
   return out;
 }
 
+// An https URL with a host, not just the scheme.
+const HTTPS_URL = /^https:\/\/[^/\s]+\.[^/\s]+/;
+// Is this URL a licence FILE in a code repository (LICENSE, license, LICENSE-MIT, License.md, COPYING)?
+// Decided by WHERE the URL points, not by its letter case (review 4): a repository file is shown under a
+// `/blob/` or `/raw/` path (GitHub, GitLab's `/-/blob/`, Bitbucket, Codeberg, most self-hosted forges) or
+// served from raw.githubusercontent.com. A repository's front page (`github.com/org/license-tool`) is not
+// a file, and a vendor's terms page at `/license` or `/license-agreement` is the right proof for a closed
+// tool. The query and fragment are not the file; a percent-encoded name is read decoded. `new URL`
+// already lowercases the host.
+const RAW_HOSTS = new Set(['raw.githubusercontent.com']);
+export function isRepoLicenceFile(url) {
+  let u;
+  try { u = new URL(String(url)); } catch { return false; }
+  let pathname = u.pathname;
+  try { pathname = decodeURIComponent(pathname); } catch { /* a stray % — read it as written */ }
+  const inRepo = RAW_HOSTS.has(u.hostname) || /\/(blob|raw|src)\//.test(pathname);
+  const file = pathname.split('/').filter(Boolean).at(-1) || '';
+  return inRepo && /^(licen[cs]e|copying)([-_.].*)?$/i.test(file);
+}
+
+// A YYYY-MM-DD string that names a real day. `Date.parse` rolls an impossible day forward (2026-02-30
+// becomes 2 March) instead of refusing it, so the day has to come back out unchanged.
+export const isCalendarDay = (s) => {
+  if (typeof s !== 'string' || !DATE.test(s)) return false;
+  const t = Date.parse(`${s}T00:00:00Z`);
+  return !Number.isNaN(t) && new Date(t).toISOString().slice(0, 10) === s;
+};
+
+// How many whole days old a vetting record is on `today` (a Date). A parameter, never `new Date()` here,
+// so a test can pass any day and the unit suite never ages by itself.
+export const vettingAge = (t, today) =>
+  Math.floor((Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate()) - Date.parse(`${t.vetted.on}T00:00:00Z`)) / 86400000);
+
+// The shipped entries whose vetting cannot be trusted on `today`: `[{ id, name, on, age, why }]`, where
+// `why` is 'stale' (older than VET_MAX_AGE_DAYS) or 'future' (a date after today — a typo like 2027 for
+// 2026 would otherwise keep a tool out of the gate for a year). The release check refuses to publish
+// while this is not empty (`scripts/vet-check.mjs`).
+export const staleVettings = (today, list = TOOLBOX) => list
+  .filter((t) => vettingProblems(t).length === 0)
+  .map((t) => ({ id: t.id, name: t.name, on: t.vetted.on, age: vettingAge(t, today) }))
+  .filter((s) => s.age > VET_MAX_AGE_DAYS || s.age < 0)
+  .map((s) => ({ ...s, why: s.age < 0 ? 'future' : 'stale' }));
+
+// The ONE Repomix version yad runs (E88): the npm package version its vetting confirmed. `yad setup`,
+// `yad repo refresh` and the install line use it; the skills write it out as text, and a test holds every
+// npx Repomix command in cli/ and skills/ to this value. Moving up is a re-vet and a yadflow release.
+export const REPOMIX_VERSION = TOOLBOX.find((t) => t.id === 'repomix').vetted.packages
+  .find((p) => p.registry === 'npm' && p.name === 'repomix').version;
+
 // ---- versions ---------------------------------------------------------------------------------------
 
 // `1.2.3`, `v1.2`, `3` → [1,2,3] / [1,2,0] / [3,0,0]; a pre-release (`1.2.3-beta`) is below its release.
@@ -471,6 +655,8 @@ export function customProblems(t) {
 const customRow = (t) => ({
   id: t.id, name: t.name || t.id, tier: 'project', role: t.role,
   licence: null, source: t.source ?? null, checked: null,
+  // A team's own tool is the team's to vet (E88): yad vets only the list it ships.
+  vetted: null,
   install: t.install ?? [], manual: null,
   detect: Object.fromEntries(Object.values(DETECT_KINDS).filter((k) => t.detect[k]?.length).map((k) => [k, t.detect[k]])),
   versions: null, fallback: t.fallback, records: null, note: null, usedBy: [],
@@ -533,6 +719,240 @@ export function toolUse(tool, { shipped, connected }) {
   return { used: false, because: null };
 }
 
+// ---- what a skill does when its tool is missing (E87) ------------------------------------------------
+//
+// Every skill a shipped tool's `usedBy` names carries one section, built here, so its words are the
+// toolbox's words and a test can hold the two together. A skill decides from yad's own answer — one rule
+// for every skill, which already sees a plugin turned off in Claude Code — not from its own guess:
+//   core       used when `yad toolbox list --json` says `used: true` and the state is `installed` or
+//              `available`. A team's `skip` (`yad toolbox remove <id>`) means the fallback, even when the
+//              tool is installed.
+//   connector  used when the Product's design, testing or learning file connects it. The connect skill
+//              writes that file and the step skill follows it, as before E87.
+// Recommended tools are bound with `yad skill bind`, so no skill names one.
+export const SKILL_FALLBACK_HEADING = '## When a tool is missing';
+// The section's last line. The section is exactly the lines from its heading to this marker, so a
+// rewrite never has to guess from the Markdown where the section ends (rounds 5 to 9 of the E87 review
+// each found one more way such a guess could cut part of a skill).
+export const SKILL_FALLBACK_END = '<!-- end: When a tool is missing -->';
+const CONNECT_FILES = { 'yad-connect-design': 'designConfig', 'yad-connect-testing': 'testingConfig', 'yad-connect-learning': 'learningConfig' };
+
+// The Product file that connects a connector: the one its `yad-connect-*` skill writes.
+export function connectorFile(tool) {
+  const skill = tool.usedBy.find((u) => CONNECT_FILES[u]);
+  return skill ? PROJECT_FILES[CONNECT_FILES[skill]] : null;
+}
+
+// The skills (folders under skills/, not `yad <command>`s) that use a tool.
+export const skillsUsing = (tool) => tool.usedBy.filter((u) => !u.startsWith('yad '));
+
+export function skillFallbackSection(skill, tools = TOOLBOX) {
+  const mine = tools.filter((t) => t.tier !== 'recommended' && skillsUsing(t).includes(skill));
+  if (!mine.length) return null;
+  const core = mine.filter((t) => t.tier !== 'connector');
+  const connectors = mine.filter((t) => t.tier === 'connector');
+  const lines = [
+    SKILL_FALLBACK_HEADING,
+    '',
+    '<!-- Written from yadflow\'s cli/toolbox.mjs (E87). Change the words there: a test holds this section to it. -->',
+    '',
+    'No tool below is required. When one is missing, this skill still finishes, using the fallback written',
+    'beside it.',
+    '',
+  ];
+  // Only a skill with a core tool asks yad: a connector is decided by its Product file, and an answer the
+  // skill must then ignore would only confuse it.
+  if (core.length) {
+    lines.push(
+      // Name the tools: "the one without a connector" means nothing in a skill that has no connector.
+      `For ${core.map((t) => t.name).join(' and ')}${connectors.length ? ` (${core.length === 1 ? 'the one tool here that is not a connector' : 'the tools here that are not connectors'})` : ''}, decide from yad's answer, not from a guess:`,
+      'run `yad toolbox list --json` and read, in its `tools` list, the entry with the tool\'s `id`. Run it',
+      'where the tool will run: for work inside a code repo, add `--dir <that repo>`, so the tools installed',
+      'there are found.',
+      '',
+      '- **The team\'s choices.** They come from the Product. If the answer\'s `product` is null, yad found no',
+      '  Product, so a tool the team chose not to use still shows `used: true`. Tell the person that.',
+      '- **When yad cannot see the tool.** yad does not read every way a tool can be set up (an older install',
+      '  may be missed). If the entry says `missing` but the check in the steps below finds the tool, use',
+      '  it — but never when the entry says `used: false`.',
+      '- **When yad cannot answer** (yad is not installed here, or the command fails), use the check in the',
+      '  steps below.',
+      '',
+    );
+  }
+  lines.push('Tell the person which tools you used and which fallbacks, and why.', '');
+  for (const t of core) {
+    lines.push(`- **${t.name}** (\`${t.id}\`). Use it when its entry has \`used: true\` and \`status.state\` is \`installed\` or \`available\`. Otherwise — not found, its plugin turned off in Claude Code, or the team chose not to use it (\`yad toolbox remove ${t.id}\`) — use the fallback.`);
+    lines.push(`  - Fallback — ${t.fallback}.`);
+    if (t.records) lines.push(`  - Record \`${t.records}\`. It means the tool was not used, whatever the reason.`);
+  }
+  for (const t of connectors) {
+    const file = connectorFile(t);
+    const connect = t.usedBy.find((u) => CONNECT_FILES[u]);
+    // The connect skill is the one that decides and writes the file; every other skill follows it.
+    lines.push(CONNECT_FILES[skill]
+      ? `- **${t.name}** (\`${t.id}\`, a connector). This skill connects it, by writing \`${file}\` as the steps below say. The other skills follow that file, not yad's toolbox answer.`
+      : `- **${t.name}** (\`${t.id}\`, a connector). Used when \`${file}\` connects it. ${connect} writes that file; follow it, not yad's toolbox answer.`);
+    lines.push(`  - Fallback — ${t.fallback}.`);
+    if (t.records) lines.push(`  - Record \`${t.records}\`. It means the tool was not used, whatever the reason.`);
+  }
+  lines.push('', SKILL_FALLBACK_END);
+  return lines.join('\n');
+}
+
+// Where the section is in a skill's text: from its heading down to its end marker, both included. A
+// line inside a fenced code block is never either, so an example that quotes them is skipped. A fence
+// closes only with the same character, at least as many times, and nothing after it (CommonMark).
+// A heading may be indented up to three spaces and end in spaces or closing `#`s, as CommonMark allows.
+// `first`, where a new section goes, is the first `##` heading: a skill's `#` title is above it.
+// `[^]*`, not `.*`: `.` stops at a lone \r or a Unicode line break, and `$` then forces a slow retry.
+const HEADING = /^ {0,3}(#{1,2})(?:[ \t]+([^]*))?$/;
+// Only spaces and tabs are trimmed, as CommonMark does — by hand, since /[ \t]+$/ backtracks.
+const trimSpaces = (s) => { let k = s.length; while (k > 0 && (s[k - 1] === ' ' || s[k - 1] === '\t')) k--; return s.slice(0, k); };
+const headingOf = (line) => {
+  const h = HEADING.exec(line);
+  if (!h) return null;
+  // Cut a closing run of `#`s only when a space or tab comes before it (`## C#` keeps its `#`).
+  // Walked back by hand: a pattern for the run of `#`s restarts at each one, which is slow on a long run.
+  let text = trimSpaces(h[2] ?? '');
+  let j = text.length;
+  while (j > 0 && text[j - 1] === '#') j--;
+  if (j < text.length && (j === 0 || text[j - 1] === ' ' || text[j - 1] === '\t')) text = trimSpaces(text.slice(0, j));
+  return { level: h[1].length, text };
+};
+
+// Is this line the section's heading, in any spelling the finder accepts (indent, case, trailing spaces
+// or `#`s)? One rule, so the finder and the test that counts copies cannot disagree.
+export function isFallbackHeading(line) {
+  const h = headingOf(line.replace(/\r$/, ''));
+  return h?.level === 2 && h.text.toLowerCase() === SKILL_FALLBACK_HEADING.slice(3).toLowerCase();
+}
+
+const isFallbackEnd = (line) => trimSpaces(line.replace(/\r$/, '')) === SKILL_FALLBACK_END;
+
+function sectionBounds(lines) {
+  let fence = null;
+  const headings = [];
+  const ends = [];
+  // A YAML frontmatter block at the top (`---` … `---`, after any byte-order mark) is the skill's
+  // metadata, never Markdown: a heading-like line there (a `## comment`, a quoted heading in a YAML
+  // value) is neither our heading nor where a new section goes, and a fence there is not one. Only our
+  // exact end marker is looked for in it: a section that seems to sit inside (a file opening with a
+  // `---` divider) then shows as a marker with no heading, and is refused rather than hidden — so a
+  // write never runs a section across the block's closing `---`. A copy without a marker inside such a
+  // block reads as metadata, as a YAML loader would read it, and is left alone. The block closes at `---`
+  // or `...`, trailing spaces allowed, as common frontmatter readers accept.
+  let skip = 0;
+  // Only when the next line is a YAML key, quoted or not (every SKILL.md opens `name:`): a `---` divider
+  // above a title is Markdown, and treating it as frontmatter could hide a section. A YAML comment is not
+  // enough: `# T` is a title too.
+  if (trimSpaces(lines[0]?.replace(/^\uFEFF/, '') ?? '') === '---' && /^([A-Za-z_][\w-]*[ \t]*:|["'][^"']+["'][ \t]*:)/.test(lines[1] ?? '')) {
+    const close = lines.findIndex((l, i) => i > 0 && (trimSpaces(l) === '---' || trimSpaces(l) === '...'));
+    if (close > 0) skip = close + 1;
+  }
+  let fenceAt = -1;
+  lines.forEach((l, i) => {
+    if (i < skip) {
+      if (isFallbackEnd(l)) ends.push(i);
+      return;
+    }
+    const f = /^ {0,3}(`{3,}|~{3,})([^]*)$/.exec(l);
+    if (fence) {
+      if (f && f[1][0] === fence[0] && f[1].length >= fence.length && f[2].trim() === '') fence = null;
+    } else if (f && !(f[1][0] === '`' && f[2].includes('`'))) { fence = f[1]; fenceAt = i; }
+    else if (isFallbackEnd(l)) ends.push(i);
+    else {
+      const h = headingOf(l);
+      if (h) headings.push({ i, level: h.level, ours: isFallbackHeading(l) });
+    }
+  });
+  const ours = headings.filter((h) => h.ours).map((h) => h.i);
+  const at = ours[0];
+  const end = at === undefined ? undefined : ends.find((i) => i > at);
+  // Why a section cannot be rewritten safely, and what to do, or null. Without its marker, where the
+  // section ends is a guess; behind a fence that never closes, nothing after it can be seen at all.
+  const problem = fence !== null ? `a code fence is never closed (it opens on line ${fenceAt + 1}), so yad cannot see past it — close it`
+    : ours.length > 1 ? 'the section\'s heading is there more than once — delete one of the copies (one without an end marker, if there is one), from its heading down to the end of its text'
+      : ends.length > 1 ? 'the section\'s end marker is there more than once — delete the extra marker line'
+        : at === undefined ? (ends.length ? 'the end marker is there without the section\'s heading — delete that marker line' : null)
+          : end === undefined ? 'the section has no end marker (a copy made by hand, or older than the marker) — delete it, from its heading down to the end of its text' : null;
+  return { at, end, problem, first: headings.find((h) => h.level === 2)?.i };
+}
+
+// Why yad will not rewrite this skill's section and what to do about it, or null when it can (or there
+// is none).
+export function skillSectionProblem(text) {
+  return sectionBounds(text.replace(/\r\n/g, '\n').split('\n')).problem;
+}
+
+// Bring every skill under `skillsDir` in line with the toolbox: the section where a tool names the
+// skill, none where no tool does. `check` changes nothing. Returns the skill folder names it found
+// stale and wrote, and `refused: [{ skill, reason }]` — a section it will not touch, and why.
+export function syncSkillFallbacks(skillsDir, { check = false, tools = TOOLBOX } = {}) {
+  const out = { stale: [], wrote: [], refused: [] };
+  const skills = fs.readdirSync(skillsDir).filter((s) => fs.existsSync(path.join(skillsDir, s, 'SKILL.md'))).sort();
+  for (const skill of skills) {
+    const file = path.join(skillsDir, skill, 'SKILL.md');
+    const text = fs.readFileSync(file, 'utf8');
+    const want = skillFallbackSection(skill, tools); // null: no tool names this skill, so no section
+    const reason = skillSectionProblem(text);
+    // Compared as text, not bytes, so a CRLF checkout (Windows) is not stale for its line endings alone.
+    if (!reason && skillSectionOf(text) === want) continue;
+    out.stale.push(skill);
+    const next = reason ? null : withSkillSection(text, want);
+    // A last check that ignores fences, frontmatter and indent: after a write the file holds exactly one
+    // `##` line that is the heading and one marker line (none after a removal), counted at any indent,
+    // fenced or not. So a copy the finder skipped (fenced, indented in a list) cannot be doubled. It does
+    // not catch a copy in another heading form — in a `>` quote, underlined with `---`, or as `<h2>`.
+    const seen = next === null ? [] : next.split(/\r?\n/).map((l) => l.replace(/^[ \t]+/, ''));
+    const expect = want === null ? 0 : 1;
+    const doubled = next !== null && (seen.filter(isFallbackHeading).length !== expect || seen.filter(isFallbackEnd).length !== expect);
+    const why = reason || (doubled ? 'after the write the file would hold another line that looks like the section\'s heading or end marker (in a code block, say) — delete or reword it' : null);
+    // One answer for both modes: `check` names what a write would refuse.
+    if (why) out.refused.push({ skill, reason: why });
+    if (check || why) continue;
+    fs.writeFileSync(file, next);
+    out.wrote.push(skill);
+  }
+  return out;
+}
+
+// By hand: /\n+$/ restarts at every newline of a long blank run in the middle of the text.
+const dropTrailingNewlines = (s) => { let k = s.length; while (k > 0 && s[k - 1] === '\n') k--; return s.slice(0, k); };
+
+// The section as the skill holds it (LF), heading to end marker, or null when it has none. With a
+// problem (no marker, two copies), null too: there is no section yad can read whole.
+export function skillSectionOf(text) {
+  const lines = text.replace(/\r\n/g, '\n').split('\n');
+  const { at, end, problem } = sectionBounds(lines);
+  return at === undefined || problem ? null : lines.slice(at, end + 1).join('\n');
+}
+
+// The skill's text with `section` in place of its old one, or, when it has none, just before its first
+// `## ` heading, so the agent reads it early. `null` removes it, with the blank line it was written
+// with. A section with a problem is left as it is. The file keeps its own line ending.
+export function withSkillSection(text, section) {
+  // A file keeps the ending most of its lines have (a Windows checkout is all CRLF).
+  const crlf = (text.match(/\r\n/g) || []).length;
+  const eol = crlf > (text.match(/\n/g) || []).length - crlf ? '\r\n' : '\n';
+  const lines = text.replace(/\r\n/g, '\n').split('\n');
+  const { at, end, first, problem } = sectionBounds(lines);
+  if (problem) return text;
+  let out;
+  if (at !== undefined) {
+    // A removal also takes the blank line yad wrote below it — when a blank line sits above too, or a
+    // heading comes next (yad inserts just above one), so the text on either side never closes up.
+    let after = end + 1;
+    if (section === null && lines[after] === '' && (at === 0 || lines[at - 1] === '' || headingOf(lines[after + 1] ?? '') !== null)) after++;
+    out = [...lines.slice(0, at), ...(section === null ? [] : section.split('\n')), ...lines.slice(after)];
+  } else if (section === null) out = lines;
+  else if (first === undefined) {
+    const body = dropTrailingNewlines(lines.join('\n'));
+    out = body ? [...body.split('\n'), '', ...section.split('\n'), ''] : [...section.split('\n'), ''];
+  } else out = [...lines.slice(0, first), ...section.split('\n'), '', ...lines.slice(first)];
+  return out.join('\n').replace(/\n/g, eol);
+}
+
 // Every row — shipped, then the team's own — with what is found here and whether it is in use. Finding
 // reads `detectRoot` (the folder yad runs in: a code repo's own skills count); the choices come from the
 // Product, which may be another folder.
@@ -569,6 +989,8 @@ export function toolboxLines(rows) {
       if (s.inRange === false) lines.push(`      ${c.yellow('!')} version ${version} is outside the known-good range ${r.versions} — still used; if it misbehaves, install a version in range`);
       if (s.state === 'missing' || s.state === 'disabled') lines.push(`      ${c.dim(`without it: ${clean(r.fallback)}`)}`);
       if (r.note) lines.push(`      ${c.dim(r.note)}`);
+      // E88: what was vetted and when — the licence, and the day its proof was read.
+      if (r.vetted) lines.push(`      ${c.dim(`licence ${clean(r.licence)}, vetted ${r.vetted.on}`)}`);
     }
   }
   return lines;
@@ -582,7 +1004,7 @@ export function runToolboxList(root, { json = false, productRoot = null, tools =
   info(productRoot
     ? '[used here] = in use in this Product; change it with `yad toolbox add <id>` / `yad toolbox remove <id>`'
     : 'no Product here, so this shows the defaults: the core tools are the ones in use');
-  info('`yad toolbox list --json` adds each tool\'s licence, source, install commands and where it was found');
+  info('`yad toolbox list --json` adds each tool\'s licence and its vetting record, source, install commands and where it was found');
   return undefined;
 }