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 5f8603a..2fa613a 100644 --- a/skills/reverse-engineering-saas/references/knowledge-base.md +++ b/skills/reverse-engineering-saas/references/knowledge-base.md @@ -142,11 +142,25 @@ 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: -- 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/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 3b912eb..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'; @@ -130,6 +130,117 @@ 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/); +}); + +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');