yadflow 4.8.0 → 4.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/CHANGELOG.md +114 -0
  2. package/README.md +4 -3
  3. package/bin/commands.mjs +7 -0
  4. package/bin/yad.mjs +123 -8
  5. package/cli/agent-guard.mjs +793 -65
  6. package/cli/agent-rules.mjs +40 -5
  7. package/cli/argv-flags.mjs +1 -1
  8. package/cli/build.mjs +1 -1
  9. package/cli/ci-check.mjs +45 -1
  10. package/cli/codeowners-command.mjs +72 -6
  11. package/cli/commit.mjs +17 -3
  12. package/cli/docs.mjs +2 -0
  13. package/cli/doctor.mjs +176 -12
  14. package/cli/epic-state.mjs +94 -4
  15. package/cli/epic.mjs +11 -7
  16. package/cli/fold.mjs +31 -6
  17. package/cli/guide.mjs +3 -1
  18. package/cli/hook.mjs +50 -7
  19. package/cli/issue-links.mjs +61 -0
  20. package/cli/issues-act.mjs +327 -0
  21. package/cli/issues-write.mjs +428 -0
  22. package/cli/issues.mjs +474 -0
  23. package/cli/lifecycle.mjs +7 -0
  24. package/cli/machine.mjs +141 -0
  25. package/cli/manifest.mjs +9 -3
  26. package/cli/openpr.mjs +69 -9
  27. package/cli/plan.mjs +2 -0
  28. package/cli/platform.mjs +157 -2
  29. package/cli/preview.mjs +253 -0
  30. package/cli/protection.mjs +21 -3
  31. package/cli/reconcile.mjs +1 -1
  32. package/cli/repo.mjs +64 -3
  33. package/cli/review.mjs +4 -0
  34. package/cli/run-checks.mjs +10 -2
  35. package/cli/scan.mjs +314 -0
  36. package/cli/setup.mjs +12 -3
  37. package/cli/standup.mjs +33 -7
  38. package/cli/story-frames.mjs +307 -0
  39. package/cli/test-agents-file.mjs +378 -11
  40. package/cli/test-build.mjs +25 -0
  41. package/cli/test-ci-check.mjs +469 -10
  42. package/cli/test-guide.mjs +7 -0
  43. package/cli/test-machine.mjs +140 -0
  44. package/cli/test-node.mjs +15 -0
  45. package/cli/test-preview.mjs +511 -0
  46. package/cli/test-run-checks.mjs +17 -0
  47. package/cli/test-setup-agent.mjs +14 -0
  48. package/cli/test-story-frames.mjs +409 -0
  49. package/cli/toolbox-connect.mjs +244 -0
  50. package/cli/toolbox.mjs +159 -5
  51. package/package.json +7 -3
  52. package/skills/sdlc/config.yaml +1 -1
  53. package/skills/sdlc/module-help.csv +3 -1
  54. package/skills/yad-analysis/SKILL.md +4 -0
  55. package/skills/yad-backfill/SKILL.md +4 -0
  56. package/skills/yad-change/SKILL.md +4 -0
  57. package/skills/yad-checks/SKILL.md +13 -7
  58. package/skills/yad-checks/references/check-gates.md +62 -30
  59. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  60. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  61. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  62. package/skills/yad-checks/templates/github/yad-checks.yml +357 -69
  63. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  64. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  65. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  66. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  67. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  68. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +79 -20
  69. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  70. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  71. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  72. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  73. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  74. package/skills/yad-commit/SKILL.md +3 -1
  75. package/skills/yad-connect-design/SKILL.md +48 -13
  76. package/skills/yad-connect-design/references/design-context.md +56 -3
  77. package/skills/yad-connect-design/references/design-registry.md +4 -4
  78. package/skills/yad-connect-learning/SKILL.md +12 -2
  79. package/skills/yad-connect-repos/SKILL.md +12 -0
  80. package/skills/yad-connect-testing/SKILL.md +22 -5
  81. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  82. package/skills/yad-engineer-review/SKILL.md +13 -0
  83. package/skills/yad-epic/SKILL.md +4 -0
  84. package/skills/yad-epic/references/state-schema.md +21 -0
  85. package/skills/yad-guide/SKILL.md +8 -4
  86. package/skills/yad-implement/SKILL.md +69 -3
  87. package/skills/yad-implement/references/implement-conventions.md +2 -1
  88. package/skills/yad-issues/SKILL.md +53 -0
  89. package/skills/yad-learn/SKILL.md +4 -0
  90. package/skills/yad-open-pr/SKILL.md +10 -1
  91. package/skills/yad-pair-review/SKILL.md +5 -0
  92. package/skills/yad-pr-template/SKILL.md +2 -1
  93. package/skills/yad-pr-template/templates/checks/pr-title.sh +34 -2
  94. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
  95. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
  96. package/skills/yad-product-bridge/references/bridge.md +28 -0
  97. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  98. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  99. package/skills/yad-review-companion/SKILL.md +4 -1
  100. package/skills/yad-run/SKILL.md +5 -0
  101. package/skills/yad-scan/SKILL.md +51 -0
  102. package/skills/yad-spec/SKILL.md +32 -0
  103. package/skills/yad-stories/SKILL.md +22 -0
  104. package/skills/yad-stories/references/story-schema.md +1 -0
  105. package/skills/yad-test-cases/SKILL.md +18 -2
  106. package/skills/yad-ui/SKILL.md +48 -8
  107. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
package/cli/scan.mjs ADDED
@@ -0,0 +1,314 @@
1
+ // E172 — the findings of a scan, filed on the repo's own GitHub issues or GitLab work items. The CLI never starts an
2
+ // AI: the yad-scan skill does the judging and hands a findings file to `yad scan file`, which does everything that
3
+ // must be exact: checking the file, finding duplicates, routing security findings, labels, milestones and filing.
4
+ //
5
+ // A finding's text came from a model that read possibly hostile code, so it is untrusted. Secrets are redacted, and
6
+ // it is escaped so it cannot notify a person, link anywhere, or forge a fingerprint.
7
+ // The platform is the record of what was filed: a fingerprint in each body, so there is no file here to keep.
8
+ import fs from 'node:fs';
9
+ import { createHash } from 'node:crypto';
10
+ import { run, readJSON, forTerminal, c, log, fail, hand, info, warn, emitJSON } from './lib.mjs';
11
+ import { productConfigPath } from './manifest.mjs';
12
+ import { productIdentity } from './members.mjs';
13
+ import { prTarget } from './pr-list.mjs';
14
+ import { repoSources } from './standup.mjs';
15
+ import { api, httpStatus, shown, whyFailed } from './protection.mjs';
16
+ import { createFinding, createDraftAdvisory, createMilestone } from './platform.mjs';
17
+ import { createLabel, labelRules, mdEscape, PRIORITIES, readLabels } from './issues.mjs';
18
+
19
+ export const CATEGORIES = ['security', 'tech-debt', 'suggestion'];
20
+ export const MAX_FILED = 20;
21
+ const MAX_IN_FILE = 200;
22
+ const PAGE = 100;
23
+ const MAX_PAGES = 10;
24
+ export const FINDING_LABEL = 'yad: finding';
25
+ export const DEFAULT_MILESTONES = { security: 'yad: Security', 'tech-debt': 'yad: Technical debt', suggestion: 'yad: Suggestions' };
26
+ const CATEGORY_NAME = { security: 'Security', 'tech-debt': 'Technical debt', suggestion: 'Suggestion' };
27
+ const SEVERITY = { P0: 'critical', P1: 'high', P2: 'medium', P3: 'low' };
28
+ const MARKER = /<!-- yad-finding: ([0-9a-f]{64}) -->/g;
29
+
30
+ // ---- checking the file -------------------------------------------------------------------------------
31
+
32
+ export function badPath(p) {
33
+ if (typeof p !== 'string' || !p || p.length > 300) return true;
34
+ if (/^[/\\]|^[a-zA-Z]:|\\/.test(p) || [...p].some((ch) => ch.charCodeAt(0) < 32)) return true;
35
+ return p.split('/').some((seg) => seg === '..' || seg === '.' || seg === '');
36
+ }
37
+
38
+ const text = (v, max) => typeof v === 'string' && v.trim() !== '' && v.length <= max;
39
+
40
+ // Why one finding is refused, or null.
41
+ function problemWith(f) {
42
+ if (!f || typeof f !== 'object' || Array.isArray(f)) return 'it is not an object';
43
+ if (!CATEGORIES.includes(f.category)) return `category must be one of ${CATEGORIES.join(', ')}`;
44
+ if (!PRIORITIES.includes(f.priority)) return `priority must be one of ${PRIORITIES.join(', ')}`;
45
+ if (f.category === 'security' ? !/^CWE-\d{1,6}$/.test(f.rule ?? '') : !/^[a-z0-9][a-z0-9-]{0,63}$/.test(f.rule ?? '')) return f.category === 'security' ? 'a security rule must be a CWE number, such as CWE-79' : 'rule must be a short lower-case slug';
46
+ if (typeof f.symbol !== 'string' || f.symbol.length > 200) return 'symbol must be a string (it may be empty)';
47
+ if (badPath(f.file)) return 'file must be a path relative to the repo';
48
+ if (!Number.isInteger(f.line) || f.line < 1) return 'line must be a positive whole number';
49
+ if (!text(f.title, 200)) return 'title must be text of at most 200 characters';
50
+ if (!text(f.why, 4000)) return 'why must be text of at most 4000 characters';
51
+ if (!text(f.fix, 4000)) return 'fix must be text of at most 4000 characters';
52
+ return null;
53
+ }
54
+
55
+ // `{ findings }` or `{ error }`. One bad finding refuses the whole file: the skill wrote it, and should fix it.
56
+ export function parseFindings(raw) {
57
+ let doc;
58
+ try { doc = JSON.parse(raw); } catch { return { error: 'the findings file is not JSON' }; }
59
+ const list = Array.isArray(doc) ? doc : doc?.findings;
60
+ if (!Array.isArray(list)) return { error: 'the findings file needs a "findings" list' };
61
+ if (list.length > MAX_IN_FILE) return { error: `the findings file has more than ${MAX_IN_FILE} findings` };
62
+ const problems = list.flatMap((f, i) => { const p = problemWith(f); return p ? [`finding ${i + 1}: ${p}`] : []; });
63
+ return problems.length ? { error: problems.slice(0, 10).join('; ') } : { findings: list };
64
+ }
65
+
66
+ // Not the line: it moves. Not the title: two runs word it differently.
67
+ export const fingerprint = (f) => createHash('sha256').update(JSON.stringify([f.category, f.file, f.rule, f.symbol])).digest('hex');
68
+
69
+ // ---- making text safe to post ------------------------------------------------------------------------
70
+
71
+ const SECRET = /(gh[pousr]_[A-Za-z0-9]{10,}|github_pat_[A-Za-z0-9_]{10,}|glpat-[A-Za-z0-9_-]{10,}|AKIA[0-9A-Z]{12,}|xox[abprs]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9_-]{16,}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}(?:\.[A-Za-z0-9_-]+)?|-----BEGIN[^-]*-----|[A-Za-z0-9+_=-]{40,})/g;
72
+ // Text a person wrote keeps its commit hashes and long names: only tokens with a known prefix are redacted.
73
+ const PREFIXED = /(gh[pousr]_[A-Za-z0-9]{10,}|github_pat_[A-Za-z0-9_]{10,}|glpat-[A-Za-z0-9_-]{10,}|AKIA[0-9A-Z]{12,}|xox[abprs]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9_-]{16,}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}(?:\.[A-Za-z0-9_-]+)?|-----BEGIN[^-]*-----)/g;
74
+ export const redactTokens = (s) => String(s ?? '').replace(PREFIXED, '[redacted]');
75
+ export const redact = (s) => String(s ?? '').replace(SECRET, '[redacted]');
76
+ const plain = (s, max) => { const t = forTerminal(redact(s)).replace(/\s+/g, ' ').trim(); return t.length > max ? `${t.slice(0, max - 1)}…` : t; };
77
+ // An invisible space after each trigger stops a mention or a reference. GitHub reads backslashes and HTML entities as
78
+ // the real character before it looks for one, so neither of those is enough (checked against its renderer).
79
+ const ZWSP = '\u200b';
80
+ const breakRefs = (t) => t.replace(/GH-(?=\d)/gi, (m) => `${m}${ZWSP}`).replace(/[%$](?=[\w"])/g, (m) => `${m}${ZWSP}`);
81
+ // A title is not Markdown, but a mention in one can still notify.
82
+ export const safeTitle = (s) => breakRefs(plain(s, 200).replace(/[@#!~&](?=\S)/g, (m) => `${m}${ZWSP}`));
83
+ // `mdEscape` stops links, images, tags and code.
84
+ // A leading `/` is broken too: at the start of a line GitLab runs it as a quick action, such as `/assign`.
85
+ export const safeMd = (s, max = 2000) => breakRefs(mdEscape(plain(s, max)).replace(/\\([@#!~&])/g, `$1${ZWSP}`)).replace(/^\//, `${ZWSP}/`);
86
+
87
+ export function findingBody(f, fp, { task = null, labelled = true } = {}) {
88
+ return [
89
+ `**Category:** ${CATEGORY_NAME[f.category]} · **Priority:** ${f.priority}${labelled ? '' : ` · **Rule:** ${safeMd(f.rule, 80)}`}`,
90
+ `**Where:** ${safeMd(f.file, 300)}, line ${f.line}${f.symbol ? ` (${safeMd(f.symbol, 200)})` : ''}`,
91
+ '', '### Why it matters', safeMd(f.why, 4000),
92
+ '', '### What to do', safeMd(f.fix, 4000),
93
+ '', `_Found by the yadflow scan${task ? ` of task ${safeMd(task, 80)}` : ''}. Check it before acting on it._`,
94
+ `<!-- yad-finding: ${fp} -->`,
95
+ ].join('\n');
96
+ }
97
+
98
+ // ---- reading what is already there -------------------------------------------------------------------
99
+
100
+ // Every fingerprint on items labelled as findings, open and closed. Null if any page failed or the limit was reached.
101
+ function filedFingerprints(t, runner) {
102
+ const gh = t.platform === 'github';
103
+ const label = encodeURIComponent(FINDING_LABEL);
104
+ const at = gh ? `repos/${t.repo}/issues?labels=${label}&state=all&per_page=${PAGE}` : `projects/${encodeURIComponent(t.repo)}/issues?labels=${label}&scope=all&per_page=${PAGE}`;
105
+ const seen = new Set();
106
+ for (let page = 1; page <= MAX_PAGES; page++) {
107
+ const res = api(runner, t.cli, t.host, `${at}&page=${page}`);
108
+ if (!res.ok || !Array.isArray(res.body)) return { why: whyFailed(res.ok ? { unreadable: true } : res, { platform: t.platform, host: t.host, what: `the findings already filed on ${shown(t.repo)}`, plural: true }) };
109
+ for (const it of res.body) for (const m of String((gh ? it?.body : it?.description) ?? '').matchAll(MARKER)) seen.add(m[1]);
110
+ if (res.body.length < PAGE) return { seen };
111
+ }
112
+ return { why: `${shown(t.repo)} has more filed findings than yad reads` };
113
+ }
114
+
115
+ // Paging here is by cursor, so a full page is treated as not fully read.
116
+ function draftAdvisories(t, runner) {
117
+ // Every state: a draft a person closed or published must not come back.
118
+ const res = api(runner, t.cli, t.host, `repos/${t.repo}/security-advisories?per_page=${PAGE}`);
119
+ if (!res.ok || !Array.isArray(res.body)) return { why: res.ok ? 'the advisories could not be understood' : `the advisories could not be read${res.status ? ` (HTTP ${res.status})` : ''}: an administrator or security manager must run this` };
120
+ if (res.body.length >= PAGE) return { why: 'there are too many advisories to read them all' };
121
+ const seen = new Set();
122
+ for (const a of res.body) for (const m of String(a?.description ?? '').matchAll(MARKER)) seen.add(m[1]);
123
+ return { seen };
124
+ }
125
+
126
+ // `vis` is public, private, internal, or null. `noPush` is true only when GitHub says so: it silently drops the labels
127
+ // and milestone of an item made without push access, and the next run could not recognise that item.
128
+ export function repoFacts(t, runner) {
129
+ const res = api(runner, t.cli, t.host, `repos/${t.repo}`);
130
+ if (!res.ok || !res.body || typeof res.body !== 'object') return { vis: null, noPush: false };
131
+ const b = res.body;
132
+ const vis = ['public', 'private', 'internal'].includes(b.visibility) ? b.visibility : (b.private === true ? 'private' : null);
133
+ return { vis, noPush: b.permissions?.push === false };
134
+ }
135
+
136
+ // What the platform really did with an item: why it is not what was asked, or null.
137
+ function droppedFrom(stdout, confidential) {
138
+ let b;
139
+ try { b = JSON.parse(stdout); } catch { return 'the answer could not be read'; }
140
+ const names = (Array.isArray(b?.labels) ? b.labels : []).map((l) => String(typeof l === 'string' ? l : l?.name).toLowerCase());
141
+ if (confidential && b?.confidential !== true) return 'it was NOT made confidential: restrict it now';
142
+ if (!names.includes(FINDING_LABEL)) return 'the platform dropped its label, so a later scan would file it again';
143
+ return null;
144
+ }
145
+
146
+ // Map(title → id), across open and closed. Null if unread. GitHub assigns by number, GitLab by id.
147
+ function readMilestones(t, runner) {
148
+ const gh = t.platform === 'github';
149
+ const at = gh ? `repos/${t.repo}/milestones?state=all&per_page=${PAGE}` : `projects/${encodeURIComponent(t.repo)}/milestones?per_page=${PAGE}`;
150
+ const map = new Map();
151
+ for (let page = 1; page <= MAX_PAGES; page++) {
152
+ const res = api(runner, t.cli, t.host, `${at}&page=${page}`);
153
+ if (!res.ok || !Array.isArray(res.body)) return null;
154
+ for (const m of res.body) { const id = gh ? m?.number : m?.id; if (typeof m?.title === 'string' && Number.isInteger(id)) map.set(m.title, id); }
155
+ if (res.body.length < PAGE) return map;
156
+ }
157
+ return null;
158
+ }
159
+
160
+ // ---- routing ------------------------------------------------------------------------------------------
161
+
162
+ // Where one finding goes: 'issue', 'confidential', 'advisory', or 'none'. Only a repo known to be private gets a
163
+ // normal issue for a security finding on GitHub: an unknown one is treated as public.
164
+ export function routeFor(category, platform, vis) {
165
+ if (category !== 'security') return 'issue';
166
+ if (platform === 'gitlab') return 'confidential';
167
+ if (vis === 'private') return 'issue';
168
+ return vis === 'public' ? 'advisory' : 'none';
169
+ }
170
+ const ROUTE_WHY = 'this repo\'s visibility could not be confirmed as private or public, so it was kept off the tracker';
171
+
172
+ function scanSettings(productConfig) {
173
+ const set = productConfig?.issues?.scan;
174
+ const titles = { ...DEFAULT_MILESTONES };
175
+ for (const k of CATEGORIES) if (typeof set?.milestones?.[k] === 'string' && set.milestones[k].trim()) titles[k] = set.milestones[k].trim();
176
+ return { enabled: set?.enabled !== false, titles };
177
+ }
178
+
179
+ function targetFor(root, productConfig, repo, { env, runner }) {
180
+ const identity = productIdentity(root, { productConfig, runner });
181
+ const notRead = [];
182
+ // The first source is the Product itself. Findings belong to a registered code repo, even one named `Product`.
183
+ const s = repoSources(root, identity, productConfig, notRead, env, { localPaths: false }).slice(1).find((x) => x.label === repo);
184
+ if (!s) return { why: notRead.length ? 'the repo list could not be read' : `no registered repo is called ${forTerminal(repo)}` };
185
+ const t = prTarget({ platform: s.platform, gitUrl: s.gitUrl }, { env, runner });
186
+ return t.ok ? { t } : { why: t.why };
187
+ }
188
+
189
+ const NO_PUSH = 'your login cannot push to this repo, so the platform would drop its labels';
190
+ const rank = (p) => PRIORITIES.indexOf(p);
191
+
192
+ // ---- the command --------------------------------------------------------------------------------------
193
+
194
+ export async function runScanFile(root, { file, repo, task = null, dryRun = false, json = false, env = process.env, runner = run } = {}) {
195
+ const refuse = (message, hint) => {
196
+ process.exitCode = 1;
197
+ if (json) return emitJSON({ ok: false, error: message, hint: hint ?? null });
198
+ fail(message); if (hint) hand(hint);
199
+ return undefined;
200
+ };
201
+ if (!fs.existsSync(productConfigPath(root))) return refuse('not a Product (no .sdlc/product.json here)', 'run it from the Product, or pass --dir');
202
+ if (!file || !repo) return refuse('usage: yad scan file <findings.json> --repo <name> [--task <id>] [--dry-run] [--json]');
203
+ if (task !== null && !/^[A-Za-z0-9._-]{1,64}$/.test(task)) return refuse('--task must be a plain task id');
204
+ let raw;
205
+ try { raw = fs.readFileSync(file, 'utf8'); } catch { return refuse('the findings file could not be read'); }
206
+ const parsed = parseFindings(raw);
207
+ if (parsed.error) return refuse(`findings refused: ${forTerminal(parsed.error)}`, 'fix the file and run it again. Nothing was filed');
208
+ const productConfig = readJSON(productConfigPath(root), null);
209
+ const settings = scanSettings(productConfig);
210
+ const skip = (why) => { if (json) return emitJSON({ ok: true, skipped: why, filed: [], duplicates: 0, notFiled: [], failed: [], notes: [], overCap: 0, dryRun }); info(`scan not filed: ${why}`); return undefined; };
211
+ if (!settings.enabled) return skip('issues.scan.enabled is false in .sdlc/product.json');
212
+ if (env.YAD_PLATFORM_READ === '0') return skip('platform reads are turned off (YAD_PLATFORM_READ=0)');
213
+ const where = targetFor(root, productConfig, repo, { env, runner });
214
+ if (!where.t) return refuse(`${forTerminal(repo)}: ${where.why}`, 'nothing was filed. The findings file can be run again');
215
+ const { t } = where;
216
+ // A read that failed is unknown, not "nothing filed yet": filing now could post every finding a second time.
217
+ const filed = filedFingerprints(t, runner);
218
+ if (!filed.seen) return refuse(`nothing was filed: ${filed.why}`, 'the findings file can be run again');
219
+
220
+ const unique = [...new Map(parsed.findings.map((f) => [fingerprint(f), f])).entries()];
221
+ const fresh = unique.filter(([fp]) => !filed.seen.has(fp));
222
+ let duplicates = unique.length - fresh.length;
223
+ const { vis, noPush } = t.platform === 'github' && fresh.length ? repoFacts(t, runner) : { vis: null, noPush: false };
224
+ const notFiled = [];
225
+ const ordered = [];
226
+ let drafts = null;
227
+ for (const [fp, f] of fresh) {
228
+ const route = routeFor(f.category, t.platform, vis);
229
+ if (route === 'none') { notFiled.push({ fingerprint: fp, category: f.category, priority: f.priority, title: plain(f.title, 200), file: f.file, line: f.line, why: ROUTE_WHY }); continue; }
230
+ if (route === 'advisory') {
231
+ drafts ??= draftAdvisories(t, runner);
232
+ if (!drafts.seen) { notFiled.push({ fingerprint: fp, category: f.category, priority: f.priority, title: plain(f.title, 200), file: f.file, line: f.line, why: drafts.why }); continue; }
233
+ if (drafts.seen.has(fp)) { duplicates++; continue; }
234
+ }
235
+ ordered.push({ fp, f, route });
236
+ }
237
+ ordered.sort((a, b) => rank(a.f.priority) - rank(b.f.priority));
238
+ const chosen = ordered.slice(0, MAX_FILED);
239
+ const overCap = ordered.length - chosen.length;
240
+ const rules = labelRules(productConfig);
241
+ const result = { ok: true, skipped: null, dryRun, filed: [], duplicates, notFiled, failed: [], notes: [], overCap };
242
+ const labelsOf = (f) => [FINDING_LABEL, rules.priority[f.priority][0], rules.type[f.category][0]];
243
+
244
+ const wantsTracker = chosen.filter((x) => x.route !== 'advisory');
245
+ if (dryRun) {
246
+ for (const { fp, f, route } of chosen) {
247
+ const row = { fingerprint: fp, category: f.category, priority: f.priority, title: plain(f.title, 200) };
248
+ if (noPush && route !== 'advisory') result.failed.push({ ...row, why: NO_PUSH });
249
+ else result.filed.push({ ...row, to: route, url: null, wouldFile: true });
250
+ }
251
+ } else {
252
+ // A finding without its label could not be recognised next time, and would be filed again: labels come first.
253
+ let labelsReady = !noPush;
254
+ if (wantsTracker.length && labelsReady) {
255
+ const have = readLabels(t, runner);
256
+ if (!have.ok) labelsReady = false;
257
+ else for (const name of new Set(wantsTracker.flatMap(({ f }) => labelsOf(f)))) {
258
+ if (have.names.has(name.toLowerCase())) continue;
259
+ if (!createLabel(t, name, name === FINDING_LABEL ? '5319e7' : '1d76db', runner).ok) labelsReady = false;
260
+ }
261
+ }
262
+ const milestones = new Map();
263
+ const existing = wantsTracker.length && labelsReady ? readMilestones(t, runner) : null;
264
+ if (wantsTracker.length && labelsReady && !existing) result.notes.push('the milestones could not be read, so these findings have none');
265
+ const milestoneFor = (category) => {
266
+ if (!existing) return null;
267
+ if (milestones.has(category)) return milestones.get(category);
268
+ const title = settings.titles[category];
269
+ let id = existing.get(title) ?? null;
270
+ if (id === null) {
271
+ const r = createMilestone(t, title, { runner });
272
+ try { id = r.ok ? (t.platform === 'github' ? JSON.parse(r.stdout).number : JSON.parse(r.stdout).id) ?? null : null; } catch { id = null; }
273
+ if (id === null) result.notes.push(`the milestone ${forTerminal(title)} could not be created`);
274
+ }
275
+ milestones.set(category, id);
276
+ return id;
277
+ };
278
+ // Once the platform has dropped something, the next item would lose the same thing.
279
+ let halted = false;
280
+ for (const { fp, f, route } of chosen) {
281
+ const title = safeTitle(f.title);
282
+ const row = { fingerprint: fp, category: f.category, priority: f.priority, title };
283
+ if (route === 'advisory') {
284
+ const r = createDraftAdvisory(t, { summary: title, description: findingBody(f, fp, { task, labelled: false }), severity: SEVERITY[f.priority], cwe: f.rule }, { runner });
285
+ if (r.ok) { let url = null; try { url = JSON.parse(r.stdout).html_url ?? null; } catch { /* filed, with no address */ } result.filed.push({ ...row, to: 'advisory', url }); }
286
+ else notFiled.push({ ...row, file: f.file, line: f.line, why: [403, 404].includes(httpStatus(r)) ? `the draft advisory was refused (HTTP ${httpStatus(r)}): an administrator or security manager must run this` : `GitHub did not accept the draft advisory${httpStatus(r) ? ` (HTTP ${httpStatus(r)})` : ''}` });
287
+ continue;
288
+ }
289
+ if (halted) { result.failed.push({ ...row, why: 'not sent: an earlier finding in this run did not come back as asked. Fix that first; running the scan again would send one more' }); continue; }
290
+ if (!labelsReady) { result.failed.push({ ...row, why: noPush ? NO_PUSH : 'the labels could not be read or created, so it would not be recognised next time' }); continue; }
291
+ const r = createFinding(t, { title, body: findingBody(f, fp, { task }), labels: labelsOf(f), milestone: milestoneFor(f.category), confidential: route === 'confidential' }, { runner });
292
+ if (r.ok) {
293
+ let url = null;
294
+ try { const b = JSON.parse(r.stdout); url = b.html_url ?? b.web_url ?? null; } catch { /* the check below says so */ }
295
+ const dropped = droppedFrom(r.stdout, route === 'confidential');
296
+ if (dropped) { halted = true; result.failed.push({ ...row, url, why: dropped }); } else result.filed.push({ ...row, to: route, url });
297
+ }
298
+ else result.failed.push({ ...row, why: httpStatus(r) ? `${t.host} answered HTTP ${httpStatus(r)}` : 'the platform refused it' });
299
+ }
300
+ }
301
+ if (result.failed.length) { process.exitCode = 1; result.ok = false; }
302
+ // The answer of a --json run: the command runner prints what is returned, once.
303
+ if (json) return result;
304
+ for (const x of result.filed) {
305
+ const line = `${x.priority} ${x.category}: ${forTerminal(x.title)} ${c.dim(`→ ${dryRun ? 'would file as ' : ''}${x.to}`)}${x.url ? ` ${x.url}` : ''}`;
306
+ if (x.priority === 'P0') warn(line); else log(` ${line}`);
307
+ }
308
+ for (const x of notFiled) warn(`NOT FILED ${x.priority} ${x.category}: ${forTerminal(x.title)} (${forTerminal(x.file)}:${x.line}): ${forTerminal(x.why)}`);
309
+ for (const x of result.failed) warn(`failed ${x.priority} ${x.category}: ${forTerminal(x.title)}: ${forTerminal(x.why)}${x.url ? ` ${x.url}` : ''}`);
310
+ for (const n of result.notes) info(n);
311
+ if (overCap) info(`${overCap} more finding(s) were left out: at most ${MAX_FILED} are filed per run, most urgent first. Run the scan again to file them`);
312
+ info(`${result.filed.length} ${dryRun ? 'would be filed' : 'filed'}, ${duplicates} already filed, ${notFiled.length} not filed`);
313
+ return undefined;
314
+ }
package/cli/setup.mjs CHANGED
@@ -19,6 +19,7 @@ import { recordActor } from './skip.mjs';
19
19
  import { loadSkillBindings, stepSkills } from './epic-state.mjs';
20
20
  import { offerToolbox, REPOMIX_VERSION } from './toolbox.mjs';
21
21
  import { readAllowList } from './agent-rules.mjs';
22
+ import { PREAPPROVED } from './agent-guard.mjs';
22
23
 
23
24
  // Parse a comma/space separated list into a clean, deduped array of trimmed tokens.
24
25
  export function parseList(s) {
@@ -645,9 +646,9 @@ export async function runSetup(root, opts = {}) {
645
646
  const learningPath = path.join(root, PROJECT_FILES.learningConfig);
646
647
  if (configureTools) {
647
648
  // Connect a design tool (Figma-first, pluggable; the UI step materializes the design here)
648
- S('Connect a design tool (Figma / pencil / none)');
649
+ S(`Connect a design tool (${[...DESIGN_TOOLS, 'none'].join(' / ')})`);
649
650
  guide([
650
- 'Where yad-ui materializes real screens. figma (confirm the MCP later) or none for markdown-only.',
651
+ 'Where yad-ui materializes real screens: figma, pencil or openpencil (confirm its MCP or CLI later), or none for markdown-only.',
651
652
  'Skipping is safe — the UI step degrades to ui-design.md.',
652
653
  ]);
653
654
  if (exists(designPath) && !(opts.reconfigure ?? await askYesNo('design.json exists — reconfigure?', false))) {
@@ -659,7 +660,7 @@ export async function runSetup(root, opts = {}) {
659
660
  tool = DESIGN_PRIMARY;
660
661
  }
661
662
  // A tool named by flag takes its URL by flag too (blank when not given): no prompt.
662
- const project_url = tool === 'none' ? null : (has_(opts.design) ? opts.designUrl : await ask(' project/file URL (blank to set later)', '')) || null;
663
+ const project_url = tool === 'none' ? null : (has_(opts.design) ? opts.designUrl : await ask(tool === 'openpencil' ? ' project URL (blank: each epic keeps its design file in its own design/ folder)' : ' project/file URL (blank to set later)', '')) || null;
663
664
  registerDesign(root, { tool, project_url, today: opts.today ?? null });
664
665
  ok(tool === 'none'
665
666
  ? `wrote ${PROJECT_FILES.designConfig} (markdown-only)`
@@ -806,6 +807,10 @@ export async function runSetup(root, opts = {}) {
806
807
  log(` ${c.bold(who)} ${c.dim('(read-only yad commands Claude Code runs without asking, in .claude/settings.json)')}`);
807
808
  if (allowListShown) { log(` ${c.dim('the same list as above')}`); return; }
808
809
  for (const e of readAllowList()) log(` ${c.dim(e)}`);
810
+ // E167 (#353): what the agent guard also lets run without asking, read word by word (cli/agent-guard.mjs).
811
+ log(` ${c.dim('and, judged by the agent guard each time (YAD_NO_PREAPPROVE=1 turns this off):')}`);
812
+ for (const [k, text] of Object.entries(PREAPPROVED)) if (k !== 'never') log(` ${c.dim(`- ${text}`)}`);
813
+ log(` ${c.dim(`never: ${PREAPPROVED.never}`)}`);
809
814
  allowListShown = true;
810
815
  };
811
816
  for (const repo of registry.repos) {
@@ -934,6 +939,10 @@ export async function runSetup(root, opts = {}) {
934
939
  if (learning && learning.tool && learning.tool !== 'none') {
935
940
  hand(`confirm the learning tool: run \`yad-connect-learning\` to detect the ${learning.tool} CLI (or it degrades to harness-native)`);
936
941
  }
942
+ // E165: each tool in use that is not ready here, offered under the connect-tool rule — one yes per tool.
943
+ for (const f of toolbox?.findings ?? []) {
944
+ if (f.connect) hand(`offer to connect ${f.name}: \`${f.connect}\` (the connect-tool rule: ask once, run only its agent steps)`);
945
+ }
937
946
  log('');
938
947
  log(c.dim('Re-run anytime: `yad check` (report) / `yad check --fix` (reconcile).'));
939
948
  // The --json answer (E1). A --json setup never prompts: every answer comes from a flag, or the run was
package/cli/standup.mjs CHANGED
@@ -3,7 +3,7 @@
3
3
  //
4
4
  // READ-ONLY, DERIVED LIVE, FACTS ONLY. Nothing here is stored; every line is rebuilt from git, the Product
5
5
  // ledgers, the capture branches and the platform each time. No score, no ranking and no judging flag
6
- // (`yad usage`'s rule), and never an email, a commit message, a PR title or a comment body. The one write
6
+ // (`yad usage`'s rule), and never an email, a commit message, a PR title or a comment body. Issue and work item titles are the one exception (E171). The one write
7
7
  // is E131's access cache in git's own folder (`memberStatuses`), never a Product file.
8
8
  //
9
9
  // WHO. The team list is E131's member files. Each member is one block, joined through every identity the
@@ -41,6 +41,7 @@ import { readClaims, fetchCaptures } from './claims.mjs';
41
41
  import { gitIn, wipName, WIP_PREFIX } from './capture.mjs';
42
42
  import { gitAuthors, personKey } from './people.mjs';
43
43
  import { isBot } from './riskmap.mjs';
44
+ import { accountId, buildIssues, mdEscape, mdUrl } from './issues.mjs';
44
45
  import { readMembers, memberStatuses, memberMatches, productIdentity, ttlDays, accountLabel, accessCheck } from './members.mjs';
45
46
  import { ledgerEvents, esc, mdText, writeReport } from './usage.mjs';
46
47
  import { readRegistry, judgeRepo, runnable } from './workspace.mjs';
@@ -168,7 +169,7 @@ function wipSaves(root, env, startMs) {
168
169
 
169
170
  // The repos to read: the Product and every registered repo. `dir` is set only when git may run there
170
171
  // (judged first, E81); `gitUrl` is what the platform is asked about.
171
- export function repoSources(root, identity, productConfig, notRead, env) {
172
+ export function repoSources(root, identity, productConfig, notRead, env, { localPaths = true } = {}) {
172
173
  const productUrl = typeof productConfig?.git_url === 'string' && productConfig.git_url ? productConfig.git_url
173
174
  : (gitIn(root, env)(['remote', 'get-url', 'origin']).out.trim() || '');
174
175
  const out = [{ label: 'Product', dir: root, gitUrl: productUrl, platform: identity.platform }];
@@ -178,7 +179,7 @@ export function repoSources(root, identity, productConfig, notRead, env) {
178
179
  if (!r || typeof r.name !== 'string' || !r.name) continue;
179
180
  const label = forTerminal(r.name);
180
181
  let dir = null;
181
- if (typeof r.path === 'string' && r.path) {
182
+ if (!localPaths) { /* a platform-only read (`yad issues`) needs no checkout */ } else if (typeof r.path === 'string' && r.path) {
182
183
  const j = judgeRepo(root, r);
183
184
  if (runnable(j)) dir = path.resolve(root, r.path);
184
185
  else notRead.push(`${label}: ${j.state === 'missing' ? 'not cloned on this machine' : j.linked ? "reached through a link inside a repo's tree" : safe(j.reason)} — its commits are not read`);
@@ -209,7 +210,7 @@ function whoseWip(members, w) {
209
210
  // and the same login on GitLab can be two people, so the platform and host must match too; an account two
210
211
  // files claim (`matchLogins` leaves it out) matches nobody.
211
212
  const keyOf = (a) => `${a.platform}\0${String(a.host).toLowerCase()}\0${String(a.login).toLowerCase()}`; // members.mjs's accountKey
212
- function whoseAccount(members, { platform, host, login }, disputed = new Set()) {
213
+ export function whoseAccount(members, { platform, host, login }, disputed = new Set()) {
213
214
  const want = keyOf({ platform, host: host || '', login: login || '' });
214
215
  // An account two files claim is matched by nobody — unless it is a member's own primary (E131's rule).
215
216
  const hit = members.filter((m) => m.accounts.some((a) => keyOf(a) === want && (keyOf(a) === keyOf(m.primary) || !disputed.has(want))));
@@ -504,9 +505,21 @@ export function buildStandup(root, { now = Date.now(), tz = 'UTC', since = null,
504
505
  const shape = (m) => ({
505
506
  login: m.primary.login, logins: m.accounts.map((a) => a.login), account: accountLabel(m.primary), accounts: m.accounts.map(accountLabel), status: m.status, lastActive: isDay(m.lastActive) ? m.lastActive : null, ...blocks.get(m),
506
507
  });
507
- const team = members.filter((m) => m.status !== 'left').map(shape);
508
+ // E171. Each member's items: open ones, and those closed in this window. Titles are shown on purpose: a list of
509
+ // numbers is no use in a standup. A repo not read is "not read", through `gapLines`, never "no items".
510
+ const active = members.filter((m) => m.status !== 'left');
511
+ const backlog = active.length ? buildIssues(root, { now, closedSinceMs: win.startMs, env, authCache, ...(runner ? { runner } : {}) }) : { items: [], repos: [], notes: [], registryUnread: false };
512
+ const platformGone = new Set(prMissing.map((p) => p.label));
513
+ // Each repo's failure is said once, with its PR read's line if that failed too. The flag does not depend on that.
514
+ const issuesNotRead = backlog.repos.filter((r) => !r.read && !platformGone.has(r.label)).map((r) => `${r.label}: items not read — ${r.why}`);
515
+ notes.push(...backlog.notes.filter((n) => !notes.includes(n)));
516
+ const issuesUnknown = backlog.registryUnread || backlog.repos.some((r) => !r.read || r.partial) || backlog.items.some((i) => i.assignees.some((a) => a.ambiguous));
517
+ const itemsFor = (m) => backlog.items.filter((i) => i.assignees.some((a) => a.memberKey === accountId(m.primary))).map((i) => ({ ref: i.ref, url: i.url, title: i.title, priority: i.priority, status: i.status, epic: i.epic?.id ?? null, flags: i.flags }));
518
+ const team = active.map((m) => ({ ...shape(m), issues: itemsFor(m) }));
508
519
  const left = members.filter((m) => m.status === 'left').map(shape);
509
520
  return {
521
+ issuesNotRead,
522
+ issuesUnknown,
510
523
  window: { start: new Date(win.startMs).toISOString(), end: new Date(now).toISOString(), tz, basis: win.basis, ledgerFrom: win.startUtcDay },
511
524
  fetched,
512
525
  ttlDays: ttl,
@@ -534,7 +547,7 @@ export function onlyMember(model, login) {
534
547
  // ---- rendering -----------------------------------------------------------------------------------
535
548
 
536
549
  const SECTIONS = [['done', 'Done'], ['working', 'Working on'], ['waiting', 'Waiting']];
537
- const FOOTER = 'Derived, read-only — rebuilt from git, the Product ledgers, the capture branches and the platform each time it runs. Facts only: no score, no ranking, and no emails, commit messages, PR titles or comment bodies.';
550
+ const FOOTER = 'Derived, read-only — rebuilt from git, the Product ledgers, the capture branches and the platform each time it runs. Facts only: no score, no ranking, and no emails, commit messages, PR titles or comment bodies. Issue and work item titles are shown: check before sharing outside the team.';
538
551
 
539
552
  const LOCAL_ONLY = 'no remote named origin — only your own capture branches are read';
540
553
 
@@ -544,6 +557,7 @@ export function gapLines(model) {
544
557
  ...(model.fetched === 'failed' ? ['could not fetch the capture branches — claims and drafts are as last fetched'] : []),
545
558
  ...model.platform.filter((p) => !p.read).map((p) => `${p.repo}: platform not read — ${p.why}`),
546
559
  ...model.notRead,
560
+ ...(model.issuesNotRead ?? []),
547
561
  ...model.notes,
548
562
  ...(model.fetched === 'local' ? [LOCAL_ONLY] : []),
549
563
  ...model.memberErrors,
@@ -577,6 +591,9 @@ const emptyLine = (model) => {
577
591
  return gaps.length ? `nothing recorded here — but ${gaps.join(', and ')}, so something may be missing (see the end)` : 'nothing';
578
592
  };
579
593
 
594
+ const itemMeta = (i) => [i.priority ?? 'no priority', i.status, i.epic ?? 'no epic', ...(i.flags ?? [])].join(' · ');
595
+ const noItems = (model) => (model.issuesUnknown ? 'none found — but some items could not be read or matched to a member (see the end)' : 'none');
596
+
580
597
  function blockText(model, b, title) {
581
598
  log(`\n ${c.bold(title)}`);
582
599
  for (const [k, label] of SECTIONS) {
@@ -584,6 +601,10 @@ function blockText(model, b, title) {
584
601
  if (!b[k].length) log(` ${c.dim(emptyLine(model))}`);
585
602
  for (const it of b[k]) log(` • ${it.text}`);
586
603
  }
604
+ if (!b.issues) return;
605
+ log(` ${c.dim('Assigned items')}`);
606
+ if (!b.issues.length) log(` ${c.dim(noItems(model))}`);
607
+ for (const i of b.issues) log(` • ${forTerminal(i.ref)} ${i.title} ${c.dim(`[${itemMeta(i)}]`)}${i.url ? ` ${i.url}` : ''}`);
587
608
  }
588
609
 
589
610
  const memberTitle = (m) => `${forTerminal(m.login)} ${c.dim(`— ${m.status}${m.lastActive ? `, last active ${m.lastActive}` : ''}${m.accounts.length > 1 ? ` · ${m.accounts.join(', ')}` : ''}`)}`;
@@ -623,6 +644,11 @@ export function renderMarkdown(model) {
623
644
  for (const it of b[k]) L.push(`- ${mdText(it.text)}`);
624
645
  L.push('');
625
646
  }
647
+ if (!b.issues) return;
648
+ L.push('**Assigned items**', '');
649
+ if (!b.issues.length) L.push(`- _${noItems(model)}_`);
650
+ for (const i of b.issues) L.push(`- ${i.url ? `[${mdEscape(i.ref)}](${mdUrl(i.url)})` : mdEscape(i.ref)} ${mdEscape(i.title)} (${mdEscape(itemMeta(i))})`);
651
+ L.push('');
626
652
  };
627
653
  const none = noTeamLine(model);
628
654
  if (none) L.push(`_${mdText(none)}_`, '');
@@ -641,7 +667,7 @@ export function renderMarkdown(model) {
641
667
 
642
668
  export function renderHtml(model) {
643
669
  const list = (items, empty) => (items.length ? `<ul>${items.map((it) => `<li>${esc(it.text)}</li>`).join('')}</ul>` : `<p class="none">${esc(empty)}</p>`);
644
- const block = (b, title, sub = '') => `<section class="member"><h2>${esc(title)}${sub ? ` <span>${esc(sub)}</span>` : ''}</h2>${SECTIONS.map(([k, label]) => `<h3>${label}</h3>${list(b[k], emptyLine(model))}`).join('')}</section>`;
670
+ const block = (b, title, sub = '') => `<section class="member"><h2>${esc(title)}${sub ? ` <span>${esc(sub)}</span>` : ''}</h2>${SECTIONS.map(([k, label]) => `<h3>${label}</h3>${list(b[k], emptyLine(model))}`).join('')}${b.issues ? `<h3>Assigned items</h3>${b.issues.length ? `<ul>${b.issues.map((it) => `<li>${it.url ? `<a href="${esc(it.url)}">${esc(it.ref)}</a>` : esc(it.ref)} ${esc(it.title)} <span class="none">(${esc(itemMeta(it))})</span></li>`).join('')}</ul>` : `<p class="none">${esc(noItems(model))}</p>`}` : ''}</section>`;
645
671
  const missing = gapLines(model);
646
672
  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
647
673
  <title>yadflow — standup</title><style>