From b93216d59e5c7fb2d5e22ce225a4cfc86ba7b9c1 Mon Sep 17 00:00:00 2001 From: Davi Lopes <172943456+Lopesnextgen@users.noreply.github.com> Date: Tue, 20 Oct 2026 00:11:10 -0300 Subject: [PATCH 1/2] feat: require evidence on findings in check-kb SKILL.md already sends a finding without evidence to questions.md, but check-kb only enforced evidence on rules and barriers. A finding now needs [obs EV-###], [net EV-###] or [doc SRC-###]; inference only warns. A finding's summary row and detail heading are checked together. A rule, barrier or finding section now ends at the next heading of the same or a higher level, so the last finding no longer takes its evidence from the Strengths section below it. --- .../references/knowledge-base.md | 2 +- .../scripts/check-kb.mjs | 31 ++++++++++++++----- tests/kb-scripts.test.mjs | 29 +++++++++++++++++ 3 files changed, 54 insertions(+), 8 deletions(-) diff --git a/skills/reverse-engineering-saas/references/knowledge-base.md b/skills/reverse-engineering-saas/references/knowledge-base.md index 5f8603a..f3a62bb 100644 --- a/skills/reverse-engineering-saas/references/knowledge-base.md +++ b/skills/reverse-engineering-saas/references/knowledge-base.md @@ -146,7 +146,7 @@ Send the zip to the user in the chat. The receiver unzips it and gives the folde `node /scripts/check-kb.mjs ` reports: -- Errors: unresolved references, duplicate definitions, rules or barriers without evidence, invalid ledger rows, `fixture`, `kept`, `human` or `incident` rows without a note, missing `STATUS.md`; with `--closing`, an unfilled charter. +- Errors: unresolved references, duplicate definitions, rules, barriers or findings without evidence, invalid ledger rows, `fixture`, `kept`, `human` or `incident` rows without a note, missing `STATUS.md`; with `--closing`, an unfilled charter. - Warnings: open ledger rows, `[inf]` lines without `Q-###`, features without a coverage row, artifact files without a "Not tested" section, entity field rows without an evidence tag, evidence files missing from `evidence/index.csv`, `STATUS.md` older than the newest log, template placeholders left in place. Add `--closing` at the end of the study: `open`, `fixture` and `human` ledger rows become errors. diff --git a/skills/reverse-engineering-saas/scripts/check-kb.mjs b/skills/reverse-engineering-saas/scripts/check-kb.mjs index 4d00f7e..fad1982 100644 --- a/skills/reverse-engineering-saas/scripts/check-kb.mjs +++ b/skills/reverse-engineering-saas/scripts/check-kb.mjs @@ -167,20 +167,37 @@ function checkReferencesAndLinks(kb, files) { } } -// Rules and barriers are claims the clone depends on: each section needs evidence. +// Sections that start with a "PREFIX-###" heading and end at the next heading of the same or a higher level. +function claimSections(text, prefix) { + const sections = []; + let current = null; + for (const line of text.split('\n')) { + const heading = line.match(/^(#{1,6})\s/); + if (heading && current && heading[1].length <= current.level) current = null; + const own = line.match(new RegExp(`^(#{1,6})\\s+(${prefix}-\\d{3})\\b`)); + if (own) sections.push((current = { id: own[2], level: own[1].length, lines: [] })); + current?.lines.push(line); + } + return sections.map(({ id, lines }) => [id, lines.join('\n')]); +} + +// Rules, barriers and findings are claims the clone depends on: each needs evidence. +// A finding may have a summary row and a detail heading; they are checked together. function checkEvidenceSections(kb, files) { const targets = [ ...files.filter((name) => name.startsWith('rules/') && name.endsWith('.md')).map((file) => [file, 'R']), ...files.filter((name) => name === 'clone/barriers.md').map((file) => [file, 'BR']), + ...files.filter((name) => name === 'findings.md').map((file) => [file, 'B']), ]; for (const [file, prefix] of targets) { const text = stripIgnored(readFileSync(join(kb, file), 'utf8')); - const start = new RegExp(`^(?=#{1,6}\\s+${prefix}-\\d{3}\\b)`, 'm'); - const sections = text.split(start).filter((section) => new RegExp(`^#{1,6}\\s+${prefix}-\\d{3}`).test(section)); - for (const section of sections) { - const id = section.match(new RegExp(`${prefix}-\\d{3}`))[0]; - if (/\[(obs|net)\s+EV-\d{3}|\[doc\s+SRC-\d{3}/.test(section)) continue; - if (/\[inf\]/.test(section) && /\bQ-\d{3}\b/.test(section)) warnings.push(`${file}: ${id} rests on inference only`); + const claims = new Map(); + const add = (id, claim) => claims.set(id, `${claims.get(id) ?? ''}\n${claim}`); + for (const [id, section] of claimSections(text, prefix)) add(id, section); + if (prefix === 'B') for (const row of text.split('\n').filter((line) => /^\|\s*B-\d{3}\b/.test(line))) add(row.match(/B-\d{3}/)[0], row); + for (const [id, claim] of claims) { + if (/\[(obs|net)\s+EV-\d{3}|\[doc\s+SRC-\d{3}/.test(claim)) continue; + if (/\[inf\]/.test(claim) && /\bQ-\d{3}\b/.test(claim)) warnings.push(`${file}: ${id} rests on inference only`); else errors.push(`${file}: ${id} has no evidence tag ([obs EV-###], [net EV-###] or [doc SRC-###])`); } } diff --git a/tests/kb-scripts.test.mjs b/tests/kb-scripts.test.mjs index 3b912eb..5e33e3c 100644 --- a/tests/kb-scripts.test.mjs +++ b/tests/kb-scripts.test.mjs @@ -130,6 +130,35 @@ test('barriers need evidence and are counted as BR IDs', () => { assert.match(check('--next').stdout, /BR-002/); }); +test('findings need evidence', () => { + const header = '\n| ID | Finding | Severity | Where | Evidence |\n|---|---|---|---|---|\n'; + appendFileSync(join(kb, 'findings.md'), `${header}| B-001 | Save view is lost on reload | Medium | Board | |\n`); + let result = check(); + assert.equal(result.status, 1); + assert.match(result.stdout, /findings\.md: B-001 has no evidence tag/); + write('findings.md', `# Findings\n${header}| B-001 | Save view is lost on reload | Medium | Board | [inf] Q-001 |\n`); + appendFileSync(join(kb, 'questions.md'), '| Q-001 | Does it persist? | Matters | Reload | open |\n'); + result = check(); + assert.equal(result.status, 0, result.stdout); + assert.match(result.stdout, /findings\.md: B-001 rests on inference only/); + write('findings.md', `# Findings\n${header}| B-001 | Save view is lost on reload | Medium | Board | [obs EV-001] |\n`); + appendFileSync(join(kb, 'evidence/index.csv'), 'EV-001,2026-10-15,s01,/board,Board,yes\n'); + write('evidence/EV-001-board.md', 'Board\n'); + result = check(); + assert.equal(result.status, 0, result.stdout); + assert.doesNotMatch(result.stdout, /B-001/); +}); + +test('a finding is checked with its row and heading together, never with Strengths', () => { + write('evidence/EV-001-board.md', 'Board\n'); + appendFileSync(join(kb, 'evidence/index.csv'), 'EV-001,2026-10-15,s01,/board,Board,yes\n'); + write('findings.md', '# Findings\n\n| ID | Finding | Severity | Where | Evidence |\n|---|---|---|---|---|\n| B-001 | Lost on reload | Medium | Board | see below |\n\n### B-001 Lost on reload\n- Steps: reload the board [obs EV-001]\n\n### B-002 Escape closes the task\n- Steps: press Escape\n\n## Strengths\n\n- Undo after complete [obs EV-001]\n'); + const result = check(); + assert.equal(result.status, 1); + assert.doesNotMatch(result.stdout, /B-001 has no evidence tag/); + assert.match(result.stdout, /findings\.md: B-002 has no evidence tag/); +}); + test('entity field rows need an evidence tag', () => { write('data-model/entities/E-001-deal.md', '# E-001 Deal\n\n## Fields\n\n| Field | Type | Required | Default | Constraints or enum | Source |\n|---|---|---|---|---|---|\n| title | string | yes | | | [doc SRC-001] |\n| value | number | no | 0 | | |\n\n## Not tested\n- None.\n'); appendFileSync(join(kb, 'sources.md'), '| SRC-001 | API | https://example.com/api | api | 2026-10-15 | fields |\n'); From 334fa01f5af557fa11c38c5c9306e25b79265fc0 Mon Sep 17 00:00:00 2001 From: Davi Lopes <172943456+Lopesnextgen@users.noreply.github.com> Date: Tue, 20 Oct 2026 00:11:21 -0300 Subject: [PATCH 2/2] feat: add triage-kb, a triage report and issue drafts for the clone The KB records problems, barriers and open questions, but nothing turns them into work items for the team that builds the clone. triage-kb writes -triage-/ next to the KB: - TRIAGE.md: barriers by severity, problems with their evidence state (computed from the tags) and their decision in clone/implications.md, and the open questions. - issues/: a draft per barrier, and per problem that has a Copy, Avoid or Improve row. A problem without one gets no draft; the report lists it instead. - issues.json: title and file of each draft, for gh issue create. It runs check-kb first and stops on errors unless --force, never overwrites an existing folder, never touches the network and files nothing. --- README.md | 4 + .../references/knowledge-base.md | 14 + .../scripts/triage-kb.mjs | 357 ++++++++++++++++++ tests/kb-scripts.test.mjs | 86 ++++- 4 files changed, 459 insertions(+), 2 deletions(-) create mode 100644 skills/reverse-engineering-saas/scripts/triage-kb.mjs diff --git a/README.md b/README.md index 69f9363..9db78b9 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,10 @@ node skills/reverse-engineering-saas/scripts/check-kb.mjs re-acme-crm node skills/reverse-engineering-saas/scripts/build-report.mjs re-acme-crm ``` +```bash +node skills/reverse-engineering-saas/scripts/triage-kb.mjs re-acme-crm +``` + ```bash node skills/reverse-engineering-saas/scripts/pack-kb.mjs re-acme-crm ``` diff --git a/skills/reverse-engineering-saas/references/knowledge-base.md b/skills/reverse-engineering-saas/references/knowledge-base.md index f3a62bb..2fa613a 100644 --- a/skills/reverse-engineering-saas/references/knowledge-base.md +++ b/skills/reverse-engineering-saas/references/knowledge-base.md @@ -142,6 +142,20 @@ Initialize the KB as its own git repository (`init-kb.mjs --git`), even inside a Send the zip to the user in the chat. The receiver unzips it and gives the folder to a coding agent, starting from `BUILD.md`. +## Triage + +`node /scripts/triage-kb.mjs ` turns a finished KB into issue drafts for the clone's tracker. It writes `-triage-/` next to the KB folder: + +- `TRIAGE.md`: summary, barriers, problems with their decisions, open questions, and how to file. +- `issues/`: one draft per barrier, and one per problem that has an Avoid, Improve or Copy row in `clone/implications.md`. A problem with no decision gets no draft; the report lists it as needing one. +- `issues.json`: `id`, `title` and `file` of each draft: barriers first, then problems, each most severe first. + +It runs `check-kb` first and stops on errors (`--force` triages anyway and says so). It never overwrites: if the output folder exists it stops, so pass `--out ` for another one. It never touches the network and files nothing. Read the drafts, then file them from the triage folder, with the clone's repository as `owner/repo`: + +```bash +jq -r '.[] | [.title, .file] | @tsv' issues.json | while IFS=$'\t' read -r title file; do gh issue create -R owner/repo --title "$title" --body-file "$file"; done +``` + ## Checks `node /scripts/check-kb.mjs ` reports: diff --git a/skills/reverse-engineering-saas/scripts/triage-kb.mjs b/skills/reverse-engineering-saas/scripts/triage-kb.mjs new file mode 100644 index 0000000..489b957 --- /dev/null +++ b/skills/reverse-engineering-saas/scripts/triage-kb.mjs @@ -0,0 +1,357 @@ +#!/usr/bin/env node +// Turns a finished knowledge base into a triage report (TRIAGE.md) and issue +// drafts for the clone team's tracker: one per barrier, one per problem that +// has a decision in clone/implications.md. Never touches the network and never +// files anything. No dependencies. +import { spawnSync } from 'node:child_process'; +import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { basename, dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const USAGE = 'Usage: node triage-kb.mjs [--out ] [--force] [--help]'; +const BARRIER_SEVERITIES = ['blocks launch', 'blocks feature', 'adds lead time', 'adds cost', 'moat']; +const FINDING_SEVERITIES = ['critical', 'high', 'medium', 'low']; +const CLOSED_STATUSES = /^(answered|closed|resolved|done)\b/i; +const TITLE_LIMIT = 200; +const FILING = `Run this in this folder, with the clone's repository as \`owner/repo\`: + +\`\`\`bash +jq -r '.[] | [.title, .file] | @tsv' issues.json | while IFS=$'\\t' read -r title file; do gh issue create -R owner/repo --title "$title" --body-file "$file"; done +\`\`\``; + +// Same as stripIgnored in check-kb.mjs: blanks HTML comments and fenced code, keeping line numbers. +function stripIgnored(text) { + const blank = (match) => match.replace(/[^\n]/g, ''); + return text.replace(//g, blank).replace(/^```[\s\S]*?^```/gm, blank); +} + +// Same CSV reader as check-kb.mjs. +function parseCsv(text) { + const rows = []; + let row = []; + let field = ''; + let quoted = false; + for (let i = 0; i < text.length; i += 1) { + const char = text[i]; + if (quoted) { + if (char === '"' && text[i + 1] === '"') { + field += '"'; + i += 1; + } else if (char === '"') quoted = false; + else field += char; + } else if (char === '"') quoted = true; + else if (char === ',') { + row.push(field); + field = ''; + } else if (char === '\n' || char === '\r') { + if (char === '\r' && text[i + 1] === '\n') i += 1; + row.push(field); + if (row.some((cell) => cell !== '')) rows.push(row); + row = []; + field = ''; + } else field += char; + } + row.push(field); + if (row.some((cell) => cell !== '')) rows.push(row); + return rows; +} + +const read = (kb, file) => (existsSync(join(kb, file)) ? stripIgnored(readFileSync(join(kb, file), 'utf8').replace(/\r\n?/g, '\n')) : ''); + +// Cells are kept verbatim; only unescaped pipes split them. +const splitCells = (line) => line.replace(/^\|/, '').replace(/(? cell.trim()); + +// Table rows keyed by lower-case header name, with the "## " section they sit under. +function readRows(text) { + const rows = []; + let section = ''; + let header = null; + for (const line of text.split('\n')) { + const heading = line.match(/^##\s+(.+)/); + if (heading) section = heading[1].trim().toLowerCase(); + if (!line.startsWith('|')) { + header = null; + } else if (!header) { + header = splitCells(line).map((name) => name.toLowerCase()); + } else if (!/^\|[\s|:-]+\|$/.test(line)) { + const cells = splitCells(line); + rows.push({ section, raw: line, by: Object.fromEntries(header.map((name, i) => [name, cells[i] ?? ''])), first: cells[0] }); + } + } + return rows; +} + +// Same boundary as claimSections in check-kb.mjs: a "PREFIX-### title" heading starts a section, +// and the next heading of the same or a higher level ends it. +function readSections(text, prefix) { + const sections = []; + let current = null; + for (const line of text.split('\n')) { + const heading = line.match(/^(#{1,6})\s/); + if (heading && current && heading[1].length <= current.level) current = null; + const own = line.match(new RegExp(`^(#{1,6})\\s+(${prefix}-\\d{3})\\b\\s*(.*)`)); + if (own) { + sections.push((current = { id: own[2], title: own[3].trim(), level: own[1].length, lines: [] })); + continue; + } + current?.lines.push(line); + } + return sections.map(({ id, title, lines }) => ({ id, title, body: lines.join('\n').trim() })); +} + +// The first cell holds the ID, alone or followed by the title. +const rowId = (row, prefix) => row.first.match(new RegExp(`^(${prefix}-\\d{3})\\b\\s*(.*)`)); +const rowTitle = (row, id, column) => (row.by[column] && row.by[column] !== row.first ? row.by[column] : id[2]); + +// check-kb reports duplicate IDs as errors; with --force the first definition wins. +const skipped = []; +function keepFirst(map, id, value) { + if (map.has(id)) skipped.push(id); + else map.set(id, value); +} + +// Heading text goes into table cells, where a bare pipe would split the cell. +const cell = (text) => text.replace(/(? body.match(new RegExp(`^-\\s*${name}:\\s*(.+)$`, 'im'))?.[1].trim() ?? ''; + +function rank(value, order) { + const index = order.findIndex((name) => value.toLowerCase().startsWith(name)); + return index === -1 ? order.length : index; +} + +const bySeverity = (order) => (a, b) => rank(a.severity, order) - rank(b.severity, order); + +function readBarriers(kb) { + const barriers = new Map(); + for (const section of readSections(read(kb, 'clone/barriers.md'), 'BR')) keepFirst(barriers, section.id, { ...section, severity: field(section.body, 'Severity') }); + return [...barriers.values()].sort(bySeverity(BARRIER_SEVERITIES)); +} + +// A finding may have a summary row and a detail heading; both describe the same finding. +function readFindings(kb) { + const text = read(kb, 'findings.md'); + const findings = new Map(); + for (const row of readRows(text)) { + const id = rowId(row, 'B'); + if (id) keepFirst(findings, id[1], { id: id[1], text: rowTitle(row, id, 'finding'), severity: row.by.severity ?? '', where: row.by.where ?? '', detail: '', source: row.raw }); + } + const headed = new Map(); + for (const section of readSections(text, 'B')) keepFirst(headed, section.id, section); + for (const section of headed.values()) { + const known = findings.get(section.id); + findings.set(section.id, { + id: section.id, + text: known?.text || cell(section.title), + severity: known?.severity || field(section.body, 'Severity'), + where: known?.where || field(section.body, 'Where'), + detail: section.body.split('\n').filter((line) => !/^-\s*(Severity|Where):/i.test(line)).join('\n').trim(), + source: [known?.source, section.body].filter(Boolean).join('\n'), + }); + } + return [...findings.values()].sort(bySeverity(FINDING_SEVERITIES)); +} + +// Findings mentioned in a Copy, Avoid or Improve row get that row as a decision. +function readDecisions(kb) { + const decisions = new Map(); + for (const row of readRows(read(kb, 'clone/implications.md'))) { + const kind = ['copy', 'avoid', 'improve'].find((name) => row.section.startsWith(name)); + if (!kind) continue; + const decision = { kind, item: row.by.item ?? '', detail: row.by.why ?? row.by.how ?? '', refs: row.by.refs ?? '' }; + for (const id of new Set(row.raw.match(/\bB-\d{3}\b/g) ?? [])) decisions.set(id, [...(decisions.get(id) ?? []), decision]); + } + return decisions; +} + +function readQuestions(kb) { + const text = read(kb, 'questions.md'); + const questions = new Map(); + for (const row of readRows(text)) { + const id = rowId(row, 'Q'); + if (id) keepFirst(questions, id[1], { id: id[1], question: rowTitle(row, id, 'question'), answer: row.by['how to answer'] ?? '', status: row.by.status ?? '' }); + } + for (const section of readSections(text, 'Q')) { + if (questions.has(section.id)) continue; + questions.set(section.id, { id: section.id, question: cell(section.title), answer: cell(field(section.body, 'How to answer')), status: field(section.body, 'Status') }); + } + // An unknown status counts as open, so nothing is silently dropped. + return [...questions.values()].filter((question) => !CLOSED_STATUSES.test(question.status)); +} + +function readEvidenceDates(kb) { + const path = join(kb, 'evidence', 'index.csv'); + const dates = new Map(); + if (!existsSync(path)) return dates; + for (const [id = '', date = ''] of parseCsv(readFileSync(path, 'utf8'))) dates.set(id.trim(), date.trim()); + return dates; +} + +// Computed from the tags in the row or section, never authored. +function evidenceOf(source, dates) { + const tags = source.match(/\[(?:obs|net)\s+EV-\d{3}[^\]]*\]|\[doc\s+SRC-\d{3}[^\]]*\]/g) ?? []; + if (tags.length) { + const seen = tags.flatMap((tag) => tag.match(/EV-\d{3}/g) ?? []).map((id) => dates.get(id)).filter(Boolean).sort().at(-1); + return { state: 'confirmed', tags: tags.join(' '), seen }; + } + if (/\[inf\]/.test(source)) return { state: 'inferred', question: source.match(/\bQ-\d{3}\b/)?.[0] }; + return { state: 'none' }; +} + +function evidenceLine(evidence) { + if (evidence.state === 'confirmed') return `- Evidence: ${evidence.tags}${evidence.seen ? `, seen ${evidence.seen}` : ''}`; + if (evidence.state === 'inferred') return `- Evidence: inferred only.${evidence.question ? ` Answer ${evidence.question} before acting on it.` : ''}`; + return '- Evidence: none recorded.'; +} + +function decisionLine({ kind, item, detail, refs }) { + const label = kind === 'improve' ? 'How' : 'Why'; + const parts = [`${kind[0].toUpperCase()}${kind.slice(1)}: ${item}`, detail && `${label}: ${detail}`, refs && `Refs: ${refs}`]; + return `- ${parts.filter(Boolean).join('. ')}`; +} + +// Draft bodies carry no title: the title goes in issues.json, so a filed issue does not repeat it. +function barrierDraft(barrier, product) { + return `${barrier.body}\n\nFrom \`clone/barriers.md\` in the ${product} knowledge base.\n`; +} + +function findingDraft(finding, evidence, decisions, product) { + return [ + [`- Severity: ${finding.severity}`, `- Where: ${finding.where}`, evidenceLine(evidence)].join('\n'), + finding.detail, + `## For the clone\n\n${decisions.map(decisionLine).join('\n')}`, + `From \`findings.md\` and \`clone/implications.md\` in the ${product} knowledge base.`, + ] + .filter(Boolean) + .join('\n\n') + .concat('\n'); +} + +// GitHub caps titles at 256 characters. +function issueTitle(text) { + const title = text.replace(/\\\|/g, '|'); + if (title.length <= TITLE_LIMIT) return title; + const cut = title.slice(0, TITLE_LIMIT - 3); + return `${cut.slice(0, cut.lastIndexOf(' ') > 0 ? cut.lastIndexOf(' ') : undefined)}...`; +} + +const table = (header, rows) => [`| ${header.join(' | ')} |`, `|${header.map(() => '---').join('|')}|`, ...rows.map((row) => `| ${row.join(' | ')} |`)].join('\n'); + +function buildReport({ product, date, folder, barriers, problems, questions, undecided }) { + const launch = barriers.filter((barrier) => rank(barrier.severity, BARRIER_SEVERITIES) === 0).length; + const count = (state) => problems.filter((problem) => problem.evidence.state === state).length; + const sections = [ + `# Triage: ${product}\n\nGenerated ${date} from \`${folder}\`. The drafts in \`issues/\` are for the clone's tracker. Nothing was filed.`, + `## Summary\n\n- Barriers: ${barriers.length}. Launch blockers: ${launch}.\n- Problems: ${problems.length} (confirmed ${count('confirmed')}, inferred ${count('inferred')}). Without a decision in \`clone/implications.md\`: ${undecided.length}.\n- Open questions: ${questions.length}.`, + ]; + if (barriers.length) { + const rows = barriers.map((b) => [b.id, cell(b.title), cell(b.severity), `[${b.id}](issues/${b.id}.md)`]); + sections.push(`## Barriers\n\n${table(['ID', 'Barrier', 'Severity', 'Draft'], rows)}`); + } + if (problems.length) { + const rows = problems.map((p) => { + const kinds = [...new Set(p.decisions.map((decision) => decision.kind))].join(', ') || 'none'; + return [p.id, p.text, p.severity, p.evidence.state, kinds, p.decisions.length ? `[${p.id}](issues/${p.id}.md)` : '-']; + }); + sections.push(`## Problems\n\n${table(['ID', 'Problem', 'Severity', 'Evidence', 'Decision', 'Draft'], rows)}`); + } + if (questions.length) sections.push(`## Open questions\n\n${table(['ID', 'Question', 'How to answer'], questions.map((q) => [q.id, q.question, q.answer]))}`); + sections.push(`## Filing\n\nEach draft is an issue body; \`issues.json\` holds the title and file of every draft, in the order above. Read the drafts before filing them.\n\n${FILING}`); + return `${sections.join('\n\n')}\n`; +} + +function parseArgs(argv) { + const options = { force: false }; + for (let i = 0; i < argv.length; i += 1) { + const arg = argv[i]; + if (arg === '--out') options.out = argv[(i += 1)]; + else if (arg === '--force') options.force = true; + else if (arg === '--help' || arg === '-h') options.help = true; + else if (!arg.startsWith('--') && !options.dir) options.dir = arg; + else throw new Error(`Unknown argument: ${arg}`); + } + return options; +} + +function main() { + let options; + try { + options = parseArgs(process.argv.slice(2)); + } catch (error) { + console.error(`${error.message}\n${USAGE}`); + process.exit(2); + } + if (options.help) { + console.log(USAGE); + return; + } + if (!options.dir) { + console.error(USAGE); + process.exit(2); + } + const kb = resolve(options.dir); + if (!existsSync(join(kb, 'STATUS.md'))) { + console.error(`Not a knowledge base (no STATUS.md): ${kb}`); + process.exit(2); + } + const scripts = dirname(fileURLToPath(import.meta.url)); + + const check = spawnSync(process.execPath, [join(scripts, 'check-kb.mjs'), kb], { encoding: 'utf8' }); + if (check.status !== 0 && !options.force) { + console.error(`${check.stdout}${check.stderr}\ncheck-kb reports errors. Fix them, or pass --force to triage anyway.`); + process.exit(1); + } + + const folder = basename(kb); + const product = readFileSync(join(kb, 'STATUS.md'), 'utf8').match(/^# Status:\s*(.+)$/m)?.[1]?.trim() || folder; + const date = new Date().toLocaleDateString('en-CA'); + const out = resolve(options.out || join(dirname(kb), `${folder}-triage-${date}`)); + if (existsSync(out)) { + console.error(`Already exists: ${out}. Choose another --out.`); + process.exit(2); + } + + const dates = readEvidenceDates(kb); + const decisions = readDecisions(kb); + const barriers = readBarriers(kb); + const questions = readQuestions(kb); + const problems = readFindings(kb).map((finding) => ({ ...finding, evidence: evidenceOf(finding.source, dates), decisions: decisions.get(finding.id) ?? [] })); + const decided = problems.filter((problem) => problem.decisions.length); + const undecided = problems.filter((problem) => !problem.decisions.length); + + const drafts = [ + ...barriers.map((barrier) => ({ id: barrier.id, title: `${barrier.id} ${barrier.title}`, text: barrierDraft(barrier, product) })), + ...decided.map((problem) => ({ id: problem.id, title: `${problem.id} ${problem.text}`, text: findingDraft(problem, problem.evidence, problem.decisions, product) })), + ]; + const index = drafts.map(({ id, title }) => ({ id, title: issueTitle(title), file: `issues/${id}.md` })); + + try { + mkdirSync(out); + } catch (error) { + console.error(`Cannot create ${out}: ${error.message}`); + process.exit(2); + } + // This run created the directory, so a partial output is entirely ours to remove. + try { + mkdirSync(join(out, 'issues')); + const files = [ + ...drafts.map(({ id, text }) => [`issues/${id}.md`, text]), + ['issues.json', `${JSON.stringify(index, null, 2)}\n`], + ['TRIAGE.md', buildReport({ product, date, folder, barriers, problems, questions, undecided })], + ]; + for (const [name, text] of files) writeFileSync(join(out, name), text, { flag: 'wx' }); + } catch (error) { + rmSync(out, { recursive: true, force: true }); + throw error; + } + + console.log(`Triage: ${out}`); + console.log(`Drafts: ${drafts.length} (barriers ${barriers.length}, problems ${decided.length}).`); + console.log(`Problems without a decision: ${undecided.length}${undecided.length ? ` (${undecided.map((problem) => problem.id).join(', ')})` : ''}.`); + console.log(`Open questions: ${questions.length}.`); + if (skipped.length) console.log(`Skipped second definitions of: ${[...new Set(skipped)].join(', ')}.`); + console.log('Nothing was filed. TRIAGE.md says how to file the drafts.'); + if (check.status !== 0) console.log('Triaged with --force: check-kb reported errors.'); +} + +main(); diff --git a/tests/kb-scripts.test.mjs b/tests/kb-scripts.test.mjs index 5e33e3c..05f54ac 100644 --- a/tests/kb-scripts.test.mjs +++ b/tests/kb-scripts.test.mjs @@ -1,7 +1,7 @@ -// Tests for init-kb.mjs and check-kb.mjs. No dependencies. +// Tests for init-kb.mjs, check-kb.mjs and triage-kb.mjs. No dependencies. import assert from 'node:assert/strict'; import { spawnSync } from 'node:child_process'; -import { appendFileSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { dirname, join } from 'node:path'; import { afterEach, beforeEach, test } from 'node:test'; @@ -159,6 +159,88 @@ test('a finding is checked with its row and heading together, never with Strengt assert.match(result.stdout, /findings\.md: B-002 has no evidence tag/); }); +const triage = (...args) => run('triage-kb.mjs', kb, ...args); + +test('triage-kb writes a report and drafts for barriers and decided findings', () => { + appendFileSync(join(kb, 'clone/barriers.md'), '\n### BR-001 Gmail scopes need a yearly review\n- Severity: blocks feature\n- Evidence: [doc SRC-001]\n\n### BR-002 LGPD processor duties\n- Severity: blocks launch\n- Evidence: [doc SRC-001]\n'); + appendFileSync(join(kb, 'sources.md'), '| SRC-001 | Docs | https://example.com | docs | 2026-10-16 | terms |\n'); + write('findings.md', '# Findings\n\n| ID | Finding | Severity | Where | Evidence |\n|---|---|---|---|---|\n| B-001 | View changes are lost on reload | Medium | Board | [obs EV-001] |\n| B-002 | Escape closes the whole task | Low | Task | [inf] Q-001 |\n| B-003 | Toolbar covers the title | Low | Toolbar | [obs EV-001] |\n'); + write('questions.md', '# Open questions\n\n| ID | Question | Why it matters | How to answer | Status |\n|---|---|---|---|---|\n| Q-001 | Does Escape close the input first? | UX | Press it | open |\n| Q-002 | Old question | n/a | n/a | answered |\n'); + write('clone/implications.md', '# Implications\n\n## Avoid\n\n| Area | Item | Why | Refs |\n|---|---|---|---|\n| Board | Dropping view drafts | Lost work | B-001 |\n\n## Improve\n\n| Area | Item | How | Refs |\n|---|---|---|---|\n| Task view | Escape | Close the input first | B-002 |\n'); + appendFileSync(join(kb, 'evidence/index.csv'), 'EV-001,2026-10-15,s01,/board,Board,yes\n'); + write('evidence/EV-001-board.md', 'Board\n'); + const out = join(dir, 'triage'); + const result = triage('--out', out); + assert.equal(result.status, 0, result.stdout + result.stderr); + const index = JSON.parse(readFileSync(join(out, 'issues.json'), 'utf8')); + assert.deepEqual(index.map((item) => item.id), ['BR-002', 'BR-001', 'B-001', 'B-002']); + assert.deepEqual(index[0], { id: 'BR-002', title: 'BR-002 LGPD processor duties', file: 'issues/BR-002.md' }); + assert.ok(!existsSync(join(out, 'issues/B-003.md'))); + assert.match(readFileSync(join(out, 'issues/BR-002.md'), 'utf8'), /^- Severity: blocks launch/); + assert.match(readFileSync(join(out, 'issues/B-001.md'), 'utf8'), /^- Severity: Medium\n- Where: Board\n- Evidence: \[obs EV-001\], seen 2026-10-15\n/); + assert.match(readFileSync(join(out, 'issues/B-001.md'), 'utf8'), /- Avoid: Dropping view drafts\. Why: Lost work\. Refs: B-001/); + assert.match(readFileSync(join(out, 'issues/B-002.md'), 'utf8'), /- Evidence: inferred only\. Answer Q-001 before acting on it\./); + const report = readFileSync(join(out, 'TRIAGE.md'), 'utf8'); + assert.match(report, /\| B-003 \| Toolbar covers the title \| Low \| confirmed \| none \| - \|/); + assert.match(report, /\| Q-001 \| Does Escape close the input first\? \| Press it \|/); + assert.doesNotMatch(report, /Q-002/); + assert.match(result.stdout, /Drafts: 4 \(barriers 2, problems 2\)\.\nProblems without a decision: 1 \(B-003\)\.\nOpen questions: 1\./); + assert.match(result.stdout, /Nothing was filed/); +}); + +test('triage-kb merges a finding defined by a summary row and a detail heading', () => { + write('findings.md', '# Findings\n\n| ID | Finding | Severity | Where | Evidence |\n|---|---|---|---|---|\n| B-001 | Lost on reload | Medium | Board | [inf] Q-001 |\n\n### B-001 Lost on reload\n- Seen again after a reload [obs EV-001]\n'); + write('questions.md', '# Open questions\n\n| ID | Question | Why it matters | How to answer | Status |\n|---|---|---|---|---|\n| Q-001 | Always? | UX | Reload twice | open |\n'); + write('clone/implications.md', '# Implications\n\n## Avoid\n\n| Area | Item | Why | Refs |\n|---|---|---|---|\n| Board | Dropping drafts | Lost work | B-001 |\n'); + appendFileSync(join(kb, 'evidence/index.csv'), 'EV-001,2026-10-15,s01,/board,Board,yes\n'); + write('evidence/EV-001-board.md', 'Board\n'); + const out = join(dir, 'triage'); + const result = triage('--out', out); + assert.equal(result.status, 0, result.stdout + result.stderr); + assert.deepEqual(JSON.parse(readFileSync(join(out, 'issues.json'), 'utf8')).map((item) => item.id), ['B-001']); + assert.match(readFileSync(join(out, 'issues/B-001.md'), 'utf8'), /- Severity: Medium\n- Where: Board\n- Evidence: \[obs EV-001\], seen 2026-10-15/); +}); + +test('triage-kb reads Windows line endings, IDs with titles, heading questions and finding details', () => { + write('clone/barriers.md', '# Production barriers\r\n\r\n### BR-001 LGPD processor duties\r\n- Severity: blocks launch\r\n- Evidence: [doc SRC-001]\r\n'); + appendFileSync(join(kb, 'sources.md'), '| SRC-001 | Docs | https://example.com | docs | 2026-10-16 | terms |\n'); + write('findings.md', '# Findings\n\n| Finding | Severity | Where | Evidence |\n|---|---|---|---|\n| B-001 View changes are lost on reload | Medium | Board | [obs EV-001] |\n\n### B-002 Escape closes the task\n- Severity: Low\n- Where: Task view\n- Steps: open a task, press Escape [obs EV-001]\n\n## Strengths\n\n- None recorded yet.\n'); + write('questions.md', '# Open questions\n\n### Q-001 Does Escape close the input first?\n- How to answer: press it in an empty input\n- Status: open\n'); + write('clone/implications.md', '# Implications\n\n## Avoid\n\n| Area | Item | Why | Refs |\n|---|---|---|---|\n| Board | Dropping view drafts | Lost work | B-001 |\n| Task view | Escape closing the task | Lost context | B-002 |\n'); + appendFileSync(join(kb, 'evidence/index.csv'), 'EV-001,2026-10-15,s01,/board,Board,yes\n'); + write('evidence/EV-001-board.md', 'Board\n'); + const out = join(dir, 'triage'); + const result = triage('--out', out); + assert.equal(result.status, 0, result.stdout + result.stderr); + const index = JSON.parse(readFileSync(join(out, 'issues.json'), 'utf8')); + assert.deepEqual(index.map((item) => item.title), ['BR-001 LGPD processor duties', 'B-001 View changes are lost on reload', 'B-002 Escape closes the task']); + const draft = readFileSync(join(out, 'issues/B-002.md'), 'utf8'); + assert.match(draft, /^- Severity: Low\n- Where: Task view\n- Evidence: \[obs EV-001\], seen 2026-10-15\n\n- Steps: open a task, press Escape \[obs EV-001\]\n/); + assert.equal(draft.match(/Severity/g).length, 1); + assert.match(readFileSync(join(out, 'TRIAGE.md'), 'utf8'), /\| Q-001 \| Does Escape close the input first\? \| press it in an empty input \|/); +}); + +test('triage-kb never overwrites and refuses a KB with errors unless --force', () => { + const out = join(dir, 'taken'); + mkdirSync(out); + let result = triage('--out', out); + assert.equal(result.status, 2); + assert.deepEqual(readdirSync(out), []); + appendFileSync(join(kb, 'findings.md'), '\n| B-001 | Lost on reload | Medium | Board | |\n'); + const fresh = join(dir, 'fresh'); + result = triage('--out', fresh); + assert.equal(result.status, 1); + assert.ok(!existsSync(fresh)); + result = triage('--out', fresh, '--force'); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Triaged with --force: check-kb reported errors\./); + appendFileSync(join(kb, 'clone/barriers.md'), '\n### BR-001 First\n- Severity: moat\n\n### BR-001 Second\n- Severity: moat\n'); + result = triage('--out', join(dir, 'duplicates'), '--force'); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Skipped second definitions of: BR-001\./); + assert.match(readFileSync(join(dir, 'duplicates', 'issues', 'BR-001.md'), 'utf8'), /^- Severity: moat\n/); +}); + test('entity field rows need an evidence tag', () => { write('data-model/entities/E-001-deal.md', '# E-001 Deal\n\n## Fields\n\n| Field | Type | Required | Default | Constraints or enum | Source |\n|---|---|---|---|---|---|\n| title | string | yes | | | [doc SRC-001] |\n| value | number | no | 0 | | |\n\n## Not tested\n- None.\n'); appendFileSync(join(kb, 'sources.md'), '| SRC-001 | API | https://example.com/api | api | 2026-10-15 | fields |\n');