yadflow 3.18.1 → 4.0.0-next.1

package/cli/usage.mjs

@@ -1,6 +1,6 @@
 // `yad usage` — the team-member adoption & behavior report.
 //
-// DERIVED, READ-ONLY, NO NEW SOURCE OF TRUTH. This command reconstructs each roster member's audit
+// DERIVED, READ-ONLY, NO NEW SOURCE OF TRUTH. This command reconstructs each contributor's audit
 // trail entirely from data ALREADY in git — the approval/comment/ship ledgers + git authorship — and
 // renders it as a portable report (HTML by default) to a location the caller chooses. It writes no
 // tracked state, hooks no commands, and stores nothing that cannot be rebuilt from the repos. This
@@ -11,26 +11,43 @@
 // explainable hygiene flags. It NEVER emits emails, commit messages, or free-text comment bodies. It is
 // a workflow-hygiene / adoption view for an EM, not a judgmental scorecard (see memory:
 // no-private-data-in-reports).
+//
+// PEOPLE COME FROM ACTIVITY, NOT FROM A LIST (E62). Before the roster was removed this report seeded every
+// member from it — so someone with no activity showed as `dormant` — and used it to join a person's
+// ledger name, git name and login into one row. With no stored list, a person is whoever did something:
+// the name a ledger records (the platform login since E62; the roster's name in older records) or the
+// git author. One join survives because it is evidence rather than a claim: a GitHub or GitLab noreply
+// commit address carries the login, so those commits land on the same row as that login's approvals.
+// A person whose git name and login differ may appear on more than one row, and the report says so
+// rather than guessing.
+//
+// An older record (one still carrying the `role` the roster gave it) names the person by their ROSTER
+// name, which can be ANOTHER person's login — `al` was bob's roster name and alice's login. Read raw,
+// the two landed on one row once alice's records were re-synced under her login. So an older record is
+// read through the roster's name → login table (`legacyLogins`), the same one `yad gate sync` uses, and
+// only when the roster still holds that name for exactly one login; an `unverified` record already names
+// a login.
 import fs from 'node:fs';
 import path from 'node:path';
-import { c, log, ok, note, readJSON, run } from './lib.mjs';
-import { PROJECT_FILES, epicFiles } from './manifest.mjs';
+import { c, log, ok, note, readJSON, run, emitJSON, collectWarning } from './lib.mjs';
+import { PROJECT_FILES, epicFiles, productConfigPath } from './manifest.mjs';
 import { readShips } from './ledger.mjs';
-import { rolesForScope } from './platform.mjs';
+import { epicRoot, ledgerPersonLogin, FOUNDATION_DIR, FOUNDATION_EPIC, FOUNDATION_FILES } from './epic-state.mjs';
+import { legacyLogins } from './gate.mjs';
 
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
 // Ledger read for the report. A MISSING file is normal (the epic hasn't reached that gate) and yields
 // `def` silently; a file that EXISTS but fails to parse is surfaced to stderr and skipped — NOT thrown,
 // since one corrupt ledger must not abort the whole derived view, but a silent under-count must never
-// masquerade as "no activity" (an active reviewer wrongly shown dormant). Mirrors the `readJSONStrict`
+// masquerade as "no activity" (an active reviewer wrongly left off the report). Mirrors the `readJSONStrict`
 // hazard note in lib.mjs, softened to warn-and-continue for this read-only aggregation.
 function readLedger(p, def) {
   if (!fs.existsSync(p)) return def;
   try {
     return JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch (e) {
-    note(c.yellow(`skipped unreadable ledger ${path.basename(path.dirname(path.dirname(p)))}/${path.basename(p)}: ${e.message}`));
+    { const w = `skipped unreadable ledger ${path.basename(path.dirname(path.dirname(p)))}/${path.basename(p)}: ${e.message}`; collectWarning(w); note(c.yellow(w)); }
     return def;
   }
 }
@@ -44,77 +61,62 @@ const ARTIFACT_FILES = new Set([
   'epic.md', 'analysis.md', 'architecture.md', 'contract.md', 'ui-design.md', 'DESIGN.md', 'test-cases.md',
 ]);
 
-// ---- roster / attribution ----------------------------------------------------------------------
+// ---- attribution -------------------------------------------------------------------------------
 
-function loadRoster(root) {
-  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), null);
-  return hub && Array.isArray(hub.roster) ? hub.roster : [];
-}
-
-// A member's hub-scope role label (supports both the per-scope `roles` map and the legacy flat `role`).
-function rosterRole(m) {
-  const scoped = rolesForScope(m, 'hub');
-  if (scoped.length) return scoped.join(', ');
-  return m.role || '';
-}
-
-// Resolve a display name / login / git-author identity to a canonical roster member (or null when the
-// person is not in the roster — we still attribute the event to the raw name so nothing is dropped).
-function makeResolver(roster) {
-  const byEmail = new Map();
-  const byName = new Map();
-  const byLogin = new Map();
-  for (const m of roster) {
-    if (m.email) byEmail.set(m.email.toLowerCase(), m);
-    if (m.name) byName.set(m.name, m);
-    if (m.login) byLogin.set(m.login, m);
-  }
-  return {
-    // Ledgers store the roster `name` (approver/commenter) — map back to the full entry when possible.
-    byNameOrLogin: (s) => (s == null ? null : byName.get(s) || byLogin.get(s) || null),
-    // git authorship maps by commit email first (the reliable key), then by author name == roster name.
-    byGitAuthor: (name, email) =>
-      byEmail.get((email || '').toLowerCase()) || byName.get(name) || byLogin.get(name) || null,
-  };
-}
+// The login a noreply commit address carries. It LIVES in cli/riskmap.mjs now, because E67's bash twin
+// has to derive the same login and the rule is compared between the two; this export stays (rule 3 —
+// add the new name beside the old) and is the one every older reader here still calls.
+import { loginFromEmail } from './riskmap.mjs';
+export { loginFromEmail };
 
 // ---- epic enumeration --------------------------------------------------------------------------
 
+// The Foundation (E75) is appended when its ledger folder exists: approving or commenting on it is
+// contribution like any other gate, and a report that left it out would under-count exactly the
+// people who framed the product. The case-insensitive match on `epics/` is this report's own, older
+// rule and is kept as it was.
 function listEpics(root) {
   const dir = path.join(root, 'epics');
-  if (!fs.existsSync(dir)) return [];
-  return fs
-    .readdirSync(dir, { withFileTypes: true })
-    .filter((e) => e.isDirectory() && /^EP-[a-z0-9-]+$/i.test(e.name))
-    .map((e) => e.name)
-    .sort();
+  const ids = fs.existsSync(dir)
+    ? fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && /^EP-[a-z0-9-]+$/i.test(e.name) && e.name !== FOUNDATION_EPIC)
+      .map((e) => e.name)
+    : [];
+  if (fs.existsSync(path.join(root, FOUNDATION_DIR, '.sdlc'))) ids.push(FOUNDATION_EPIC);
+  return ids.sort();
 }
 
 const inWindow = (date, since, until) => !!date && (!since || date >= since) && (!until || date <= until);
 
 // ---- event derivation --------------------------------------------------------------------------
 
-// Ledger-sourced events for one epic: approvals, comments, and ship engineer-reviews. Each carries the
-// roster `name` already, so attribution is direct.
-function ledgerEvents(root, epic, resolver) {
-  const f = epicFiles(path.join(root, 'epics', epic));
+// Ledger-sourced events for one epic: approvals, comments, and ship engineer-reviews, attributed to the
+// name the ledger records — as recorded, with nothing to translate it through.
+function ledgerEvents(root, epic, aliases = new Map()) {
+  const f = epicFiles(epicRoot(root, epic));
   const events = [];
-  const emit = (rawName, action, date, extra = {}) => {
+  const emit = (rec, rawName, action, date, extra = {}) => {
     if (!rawName || !date) return;
-    const m = resolver.byNameOrLogin(rawName);
-    events.push({ ts: date, actor: m ? m.name || m.login : rawName, login: m ? m.login || null : null, rostered: !!m, action, epic, ...extra });
+    // A record whose login a gate write recorded from the roster (E64, `rosterName`) names that login, just
+    // as the name table said before the stamp — so the row stays one known by login. The rule LIVES in
+    // cli/epic-state.mjs since E71, because the active-people count has to place a record on exactly the
+    // person this report does — two readers that disagreed would split or fold a person between them.
+    const login = ledgerPersonLogin(rec, rawName, aliases);
+    events.push({ ts: date, actor: login || rawName, login, action, epic, ...extra });
   };
-  for (const a of readLedger(f.approvals, []) || []) emit(a.approver, 'approved', a.date, { artifact: a.artifact, role: a.role });
-  for (const cm of readLedger(f.comments, []) || []) emit(cm.commenter, 'commented', cm.date, { artifact: cm.artifact, role: cm.role });
-  for (const s of readShips(path.join(root, 'epics', epic))) {
-    for (const er of s.engineer_review || []) emit(er.approver, 'shipped', s.shippedAt, { story: s.story, task: s.task, repo: s.repo, risk: s.risk });
+  for (const a of readLedger(f.approvals, []) || []) emit(a, a.approver, 'approved', a.date, { artifact: a.artifact });
+  for (const cm of readLedger(f.comments, []) || []) emit(cm, cm.commenter, 'commented', cm.date, { artifact: cm.artifact });
+  for (const s of readShips(epicRoot(root, epic))) {
+    for (const er of s.engineer_review || []) emit(er, er.approver, 'shipped', s.shippedAt, { story: s.story, task: s.task, repo: s.repo, risk: s.risk });
   }
   return events;
 }
 
-// True for `epics/<EP>/<artifact>.md` or `epics/<EP>/stories/<file>.md`.
-function isArtifactPath(rel) {
+// True for `epics/<EP>/<artifact>.md`, `epics/<EP>/stories/<file>.md`, or a Foundation section
+// `foundation/<section>.md` (E75).
+export function isArtifactPath(rel) {
   const parts = rel.split('/');
+  if (parts[0] === FOUNDATION_DIR) return parts.length === 2 && FOUNDATION_FILES.includes(parts[1]);
   if (parts[0] !== 'epics' || parts.length < 3) return false;
   if (parts[2] === 'stories') return parts.length >= 4 && parts[3].endsWith('.md');
   return parts.length === 3 && ARTIFACT_FILES.has(parts[2]);
@@ -139,27 +141,29 @@ function parseGitLog(stdout) {
 
 const GIT_PRETTY = '--pretty=format:\x01%an%x00%ae%x00%ad';
 
-// git-sourced "authored" events: who committed which epic artifact, when. Degrades to [] when the hub
+// git-sourced "authored" events: who committed which epic artifact, when. Degrades to [] when the Product
 // is not a git repo (e.g. a test fixture dir), so the command never depends on git being present.
-function gitAuthoredEvents(root, resolver) {
-  const r = run('git', ['-C', root, 'log', '--no-merges', '--date=short', GIT_PRETTY, '--name-only', '--', 'epics']);
+function gitAuthoredEvents(root) {
+  const r = run('git', ['-C', root, 'log', '--no-merges', '--date=short', GIT_PRETTY, '--name-only', '--', 'epics', FOUNDATION_DIR]);
   if (!r.ok || !r.stdout) return [];
   const events = [];
   for (const cm of parseGitLog(r.stdout)) {
-    const m = resolver.byGitAuthor(cm.an, cm.ae);
+    const login = loginFromEmail(cm.ae);
     for (const rel of cm.files) {
       if (!isArtifactPath(rel)) continue;
       events.push({
-        ts: cm.ad, actor: m ? m.name || m.login : cm.an, login: m ? m.login || null : null, rostered: !!m,
-        action: 'authored', epic: rel.split('/')[1], artifact: rel.split('/').pop().replace(/\.md$/, ''),
+        ts: cm.ad, actor: login || cm.an, login,
+        action: 'authored', epic: rel.startsWith(`${FOUNDATION_DIR}/`) ? FOUNDATION_EPIC : rel.split('/')[1],
+        artifact: rel.split('/').pop().replace(/\.md$/, ''),
       });
     }
   }
   return events;
 }
 
-// Optional (`--repos`): code commits in each connected code repo, attributed by author → roster.
-function repoCommitEvents(root, resolver) {
+// Optional (`--repos`): code commits in each connected code repo, attributed to the git author (or the
+// login a noreply address carries).
+function repoCommitEvents(root) {
   const reg = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
   const events = [];
   for (const repo of reg?.repos || []) {
@@ -168,18 +172,20 @@ function repoCommitEvents(root, resolver) {
     const r = run('git', ['-C', abs, 'log', '--no-merges', '--date=short', GIT_PRETTY]);
     if (!r.ok || !r.stdout) continue;
     for (const cm of parseGitLog(r.stdout)) {
-      const m = resolver.byGitAuthor(cm.an, cm.ae);
-      events.push({ ts: cm.ad, actor: m ? m.name || m.login : cm.an, login: m ? m.login || null : null, rostered: !!m, action: 'committed', repo: repo.name });
+      const login = loginFromEmail(cm.ae);
+      events.push({ ts: cm.ad, actor: login || cm.an, login, action: 'committed', repo: repo.name });
     }
   }
   return events;
 }
 
 // The full, window-filtered event stream. Deterministic: sorted by (date, action, epic/repo, actor).
-export function deriveEvents(root, resolver, { since, until, repos = false } = {}) {
-  const events = [...gitAuthoredEvents(root, resolver)];
-  for (const epic of listEpics(root)) events.push(...ledgerEvents(root, epic, resolver));
-  if (repos) events.push(...repoCommitEvents(root, resolver));
+export function deriveEvents(root, { since, until, repos = false } = {}) {
+  const events = [...gitAuthoredEvents(root)];
+  let aliases = new Map();
+  try { aliases = legacyLogins(readJSON(productConfigPath(root), null)); } catch { /* no Product — nothing to translate */ }
+  for (const epic of listEpics(root)) events.push(...ledgerEvents(root, epic, aliases));
+  if (repos) events.push(...repoCommitEvents(root));
   return events
     .filter((e) => inWindow(e.ts, since, until))
     .sort((a, b) =>
@@ -192,18 +198,21 @@ export function deriveEvents(root, resolver, { since, until, repos = false } = {
 const zeroCounts = () => Object.fromEntries(ACTIONS.map((a) => [a, 0]));
 
 // Per-member rollup + explainable hygiene flags + team totals. `window` echoes the requested range.
-export function analyze(events, roster, window = { since: null, until: null }) {
+// Everyone here did something in range: there is no stored list to seed an inactive person from (E62).
+export function analyze(events, window = { since: null, until: null }) {
   const members = new Map();
-  const seed = (key, name, login, role, rostered, isReviewer = false) => {
+  const seed = (key, name, login) => {
     if (!members.has(key)) {
-      members.set(key, { key, name, login: login || null, role: role || '', rostered, isReviewer, counts: zeroCounts(), total: 0, firstActive: null, lastActive: null, epics: new Set(), timeline: [] });
+      members.set(key, { key, name, login: login || null, counts: zeroCounts(), total: 0, firstActive: null, lastActive: null, epics: new Set(), timeline: [] });
     }
-    return members.get(key);
+    const m = members.get(key);
+    if (login && !m.login) m.login = login;
+    return m;
   };
-  // Seed every roster member first so dormant members appear at zero, not missing.
-  for (const m of roster) seed(m.login || m.name, m.name || m.login, m.login || null, rosterRole(m), true, isReviewerAnywhere(m));
   for (const e of events) {
-    const m = seed(e.login || e.actor, e.actor, e.login, '', e.rostered);
+    // Keyed case-insensitively: GitHub and GitLab logins are, so `OctoCat` on an approval and `octocat`
+    // in a noreply address are one person.
+    const m = seed(String(e.login || e.actor).toLowerCase(), e.actor, e.login);
     m.counts[e.action] = (m.counts[e.action] || 0) + 1;
     m.total += 1;
     if (e.epic) m.epics.add(e.epic);
@@ -212,7 +221,7 @@ export function analyze(events, roster, window = { since: null, until: null }) {
     m.timeline.push({ ts: e.ts, action: e.action, epic: e.epic || null, repo: e.repo || null, artifact: e.artifact || null });
   }
   const list = [...members.values()].map((m) => ({
-    name: m.name, login: m.login, role: m.role, rostered: m.rostered,
+    name: m.name, login: m.login,
     counts: m.counts, total: m.total, firstActive: m.firstActive, lastActive: m.lastActive,
     epics: [...m.epics].sort(), flags: memberFlags(m), timeline: m.timeline,
   }));
@@ -222,22 +231,15 @@ export function analyze(events, roster, window = { since: null, until: null }) {
   return { window, generatedFrom: 'derived', members: list, totals };
 }
 
-// Is this roster entry a reviewer in ANY scope? Reviewer roles are usually repo-scoped
-// (`roles: { backend: ['reviewer'] }`), not hub-scoped, so a hub-only check would miss most of them.
-export function isReviewerAnywhere(entry) {
-  if (!entry) return false;
-  if ((entry.role || '') === 'reviewer') return true;                            // legacy flat role
-  if (Array.isArray(entry.roles)) return entry.roles.includes('reviewer');       // legacy hub-scope array (rolesForScope shape)
-  return Object.values(entry.roles || {}).some((list) => Array.isArray(list) && list.includes('reviewer'));
-}
-
-// Factual, per-member flags — each is a plain derivation, never a score.
+// Factual, per-member flags — each is a plain derivation, never a score. The two that needed a stored
+// list went with the roster (E62): `dormant` (listed, no activity) and `reviewer-not-reviewing` (holds a
+// reviewer role, never reviews).
 function memberFlags(m) {
   const flags = [];
-  if (m.rostered && m.total === 0) flags.push('dormant');                       // in the roster, no activity in range
   const reviews = m.counts.commented + m.counts.approved;
-  if (m.total > 0 && m.counts.authored > 0 && reviews === 0) flags.push('no-review-participation'); // authors but never reviews
-  if (m.total > 0 && m.isReviewer && reviews === 0) flags.push('reviewer-not-reviewing');            // a reviewer (any scope) who never reviews
+  // Only on a row whose person is known by LOGIN. A row built from a bare git name cannot see that
+  // person's approvals, which are recorded under their login, so "never reviews" would be a false claim.
+  if (m.login && m.total > 0 && m.counts.authored > 0 && reviews === 0) flags.push('no-review-participation'); // authors but never reviews
   return flags;
 }
 
@@ -251,7 +253,7 @@ function memberFlags(m) {
 export function shipHygiene(root, { since, until } = {}) {
   const items = [];
   for (const epic of listEpics(root)) {
-    for (const s of readShips(path.join(root, 'epics', epic))) {
+    for (const s of readShips(epicRoot(root, epic))) {
       if (!inWindow(s.shippedAt, since, until)) continue;
       if (s.retroactive) continue;
       if (!Array.isArray(s.engineer_review) || s.engineer_review.length === 0) {
@@ -279,7 +281,7 @@ export function renderHtml(model, today = '') {
   const memberCard = (m) => `
     <section class="member${m.total === 0 ? ' idle' : ''}">
       <header>
-        <h3>${esc(m.name)} ${m.login ? `<span class="login">@${esc(m.login)}</span>` : ''} ${m.role ? `<span class="role">${esc(m.role)}</span>` : ''}${m.rostered ? '' : ' <span class="role">off-roster</span>'}</h3>
+        <h3>${esc(m.name)} ${m.login && m.login !== m.name ? `<span class="login">@${esc(m.login)}</span>` : ''}</h3>
         <div class="flags">${m.flags.map(flagChip).join(' ')}</div>
       </header>
       ${bar(m)}
@@ -306,12 +308,10 @@ h1{font-size:22px;margin:0 0 4px}.sub{color:var(--dim);margin:0 0 24px}
 .member{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:16px;margin:0 0 14px}
 .member.idle{opacity:.6}.member header{display:flex;justify-content:space-between;align-items:center;gap:8px;flex-wrap:wrap}
 h3{margin:0;font-size:15px}.login{color:var(--dim);font-weight:400;font-size:13px}
-.role{color:var(--accent);font-size:11px;border:1px solid var(--line);border-radius:6px;padding:1px 6px;margin-left:4px}
 .bar{height:6px;background:var(--line);border-radius:4px;margin:10px 0;overflow:hidden}.bar span{display:block;height:100%;background:var(--accent)}
 table.counts{border-collapse:collapse;font-size:12px;margin:6px 0}table.counts th{color:var(--dim);text-align:left;font-weight:500;padding:2px 14px 2px 0}table.counts td{padding:2px 14px 2px 0}
 .meta{color:var(--dim);font-size:12px;margin:6px 0 0}
 .flags{display:flex;gap:6px;flex-wrap:wrap}.flag{font-size:11px;border-radius:6px;padding:1px 8px;background:#3a2a12;color:#ffcf7a;border:1px solid #5a3f14}
-.flag-dormant{background:#2a2f3a;color:#9aa7bd;border-color:#39414f}
 details{margin-top:10px}summary{cursor:pointer;color:var(--dim);font-size:12px}
 ul.timeline{list-style:none;padding:8px 0 0;margin:0;font-size:12px}ul.timeline li{padding:2px 0;border-top:1px solid var(--line)}
 time{color:var(--dim);font-variant-numeric:tabular-nums;margin-right:6px}
@@ -323,18 +323,18 @@ footer{color:var(--dim);font-size:12px;margin-top:28px;border-top:1px solid var(
 <div class="totals">${ACTIONS.map((a) => `<div>${a}<b>${model.totals[a]}</b></div>`).join('')}</div>
 ${model.members.map(memberCard).join('')}
 ${hygiene}
-<footer>Derived, read-only view — reconstructed from git history and the SDLC ledgers. Regenerate any time with <code>yad usage</code>. No emails, commit messages, or comment bodies are included.</footer>
+<footer>Derived, read-only view — reconstructed from git history and the SDLC ledgers. Regenerate any time with <code>yad usage</code>. No emails, commit messages, or comment bodies are included. People are listed as the ledgers and git name them: someone whose git name differs from their platform login may appear twice.</footer>
 </div></body></html>\n`;
 }
 
 // A compact Markdown variant for quick reads / pasting into a PR. Dynamic values are sanitized so a
-// name/role/repo containing `|` or a newline can't corrupt the table or list structure.
+// name/repo containing `|` or a newline can't corrupt the table or list structure.
 export function renderMarkdown(model, today = '') {
   const mdCell = (s) => String(s ?? '').replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
   const mdText = (s) => String(s ?? '').replace(/\r?\n/g, ' ');
-  const L = [`# Team usage & behavior report`, ``, `- Range: **${rangeLabel(model.window)}**${today ? ` · generated ${today}` : ''}`, `- Members: ${model.members.length}`, `- Totals: ${ACTIONS.map((a) => `${a} ${model.totals[a]}`).join(' · ')}`, ``, `| member | role | ${ACTIONS.join(' | ')} | total | flags |`, `|---|---|${ACTIONS.map(() => '--:').join('|')}|--:|---|`];
+  const L = [`# Team usage & behavior report`, ``, `- Range: **${rangeLabel(model.window)}**${today ? ` · generated ${today}` : ''}`, `- Members: ${model.members.length}`, `- Totals: ${ACTIONS.map((a) => `${a} ${model.totals[a]}`).join(' · ')}`, ``, `| member | ${ACTIONS.join(' | ')} | total | flags |`, `|---|${ACTIONS.map(() => '--:').join('|')}|--:|---|`];
   for (const m of model.members) {
-    L.push(`| ${mdCell(`${m.name}${m.login ? ` (@${m.login})` : ''}`)} | ${mdCell(m.role || '—')} | ${ACTIONS.map((a) => m.counts[a]).join(' | ')} | ${m.total} | ${mdCell(m.flags.join(', ') || '—')} |`);
+    L.push(`| ${mdCell(`${m.name}${m.login && m.login !== m.name ? ` (@${m.login})` : ''}`)} | ${ACTIONS.map((a) => m.counts[a]).join(' | ')} | ${m.total} | ${mdCell(m.flags.join(', ') || '—')} |`);
   }
   L.push('', '## Workflow hygiene');
   if (model.hygiene?.length) {
@@ -343,17 +343,15 @@ export function renderMarkdown(model, today = '') {
   } else {
     L.push('No ship-without-review gaps in range. ✓');
   }
-  L.push('', '_Derived, read-only — reconstructed from git + the SDLC ledgers; no emails/comment bodies._', '');
+  L.push('', '_Derived, read-only — reconstructed from git + the SDLC ledgers; no emails/comment bodies. People are listed as the ledgers and git name them, so one person may appear twice._', '');
   return L.join('\n');
 }
 
 // ---- CLI entry ---------------------------------------------------------------------------------
 
 export function buildModel(root, { since, until, repos = false, member } = {}) {
-  const roster = loadRoster(root);
-  const resolver = makeResolver(roster);
-  const events = deriveEvents(root, resolver, { since, until, repos });
-  const model = analyze(events, roster, { since: since || null, until: until || null });
+  const events = deriveEvents(root, { since, until, repos });
+  const model = analyze(events, { since: since || null, until: until || null });
   model.hygiene = shipHygiene(root, { since, until });
   if (member) {
     model.members = model.members.filter((m) => m.name === member || m.login === member);
@@ -371,16 +369,24 @@ function writeReport(dest, content) {
   fs.writeFileSync(dest, content);
 }
 
-export function runUsage(root, { out, since, until, all, member, format = 'html', repos = false, json = false, today = '' } = {}) {
+export function runUsage(root, { out, since, until, all, member, format, repos = false, json = false, today = '' } = {}) {
   if (all) { since = undefined; until = undefined; }
   // Dates compare lexically as strings, so an unpadded value (2026-6-1) silently mis-windows — warn.
   for (const [flag, val] of [['--since', since], ['--until', until]]) {
-    if (val && !DATE_RE.test(val)) note(c.yellow(`${flag} ${val} is not YYYY-MM-DD — dates compare lexically, so a non-padded value may filter incorrectly`));
+    if (val && !DATE_RE.test(val)) { const w = `${flag} ${val} is not YYYY-MM-DD — dates compare lexically, so a non-padded value may filter incorrectly`; collectWarning(w); note(c.yellow(w)); }
   }
-  let fmt = json ? 'json' : format;
-  if (!['html', 'json', 'md'].includes(fmt)) { note(c.yellow(`unknown --format ${fmt} (html|json|md) — using html`)); fmt = 'html'; }
+  // `--json` is the command's answer in E1's envelope; `--format json` is a REPORT format — the bare model,
+  // written to --out or printed — and stays that. With both, the report is written and the answer says where.
+  // With --json and no --format, a report written to --out is the JSON model, as it was before E1.
+  let fmt = json && format === undefined ? 'json' : (format ?? 'html');
+  if (!['html', 'json', 'md'].includes(fmt)) { const w = `unknown --format ${fmt} (html|json|md) — using html`; collectWarning(w); note(c.yellow(w)); fmt = 'html'; }
   const model = buildModel(root, { since, until, repos, member });
 
+  if (json) {
+    if (out) { writeReport(out, fmt === 'json' ? `${JSON.stringify(model, null, 2)}\n` : fmt === 'md' ? renderMarkdown(model, today) : renderHtml(model, today)); note(`wrote ${fmt.toUpperCase()} report → ${out}`); }
+    emitJSON({ ...model, out: out || null });
+    return model;
+  }
   if (fmt === 'json') {
     const s = JSON.stringify(model, null, 2);
     if (out) { writeReport(out, s + '\n'); note(`wrote JSON → ${out}`); } else { log(s); } // stdout stays pure JSON

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "3.18.1",
-  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). A BMAD module + 38 yad-* skills.",
+  "version": "4.0.0-next.1",
+  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). Plus 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
   "license": "MIT",
@@ -49,9 +49,9 @@
   },
   "keywords": [
     "sdlc",
+    "adlc",
     "yad",
     "yadflow",
-    "bmad",
     "workflow",
     "cli",
     "spec-driven-development",