qa-boot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Murat Kus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# QA Boot
+
+Bootstrap QA context for AI coding agents.
+
+QA Boot scans a repository or multi-repo workspace, collects deterministic testing/build/CI evidence, captures unknowns, and generates Claude Code-compatible QA context files.
+
+It helps QA engineers and quality leads onboard into messy projects without letting AI agents invent missing process knowledge.
+
+QA Boot is not a test generator or QA automation framework. It is the context and safety layer before AI-assisted QA work.
+
+## Core idea
+
+Most AI QA tooling focuses on generating, executing, or reviewing tests.
+
+QA Boot focuses on the missing layer before that:
+
+- What does this project know?
+- What is unknown?
+- Which facts are observed, inferred, or human-provided?
+- Which quality risks are technical versus business-critical?
+- What is Claude allowed to assume?
+- What should Claude ask before acting?
+
+## V1 product boundary
+
+V1 is a CLI-first file generator.
+
+It should:
+
+- scan repos deterministically,
+- consume evidence providers like QA Radar,
+- generate `qa-context/`,
+- generate Claude Code project skills,
+- generate unknowns and maturity summaries,
+- avoid external writes by default.
+
+V1 should not:
+
+- auto-comment on PRs,
+- auto-create Jira tickets,
+- update TestRail,
+- trigger CI,
+- approve releases,
+- access secrets,
+- act as a full autonomous QA agent.
+
+## Install & usage
+
+Requires Node 20+. Run qa-boot directly in any repo — no install step needed:
+
+```bash
+npx qa-boot init --project-name my-service
+npx qa-boot scan        # auto-runs generate
+```
+
+`scan` detects languages/tests/CI/docs/build/agent-config, writes
+`qa-context/facts.json`, and (unless `--no-generate`) renders the `qa-context/*.md`
+summaries, `unknowns.md`, `maturity.md`, `CLAUDE.qa.md`, and the `.claude/skills`.
+
+Record human-told QA knowledge (answers to open unknowns, or free-form facts):
+
+```bash
+npx qa-boot tell <unknown-id> "the answer" --by alice
+npx qa-boot tell "we release every Tuesday" --domain release --by alice
+```
+
+Prefer a permanent command? `npm install -g qa-boot` gives you `qa-boot` on your
+PATH; `npm install -D qa-boot` pins a version per-project.
+
+QA Radar is consumed live when installed:
+
+```bash
+npx qa-boot scan --with-qaradar   # spawns `qaradar analyze --json-output`
+npx qa-boot scan --skip-qaradar   # built-in scanners only
+```
+
+When `qaradar` is absent the scan still succeeds and records the gap as an
+unknown (`repo-risk.md` is only written when QA Radar ran).
+
+### Developing qa-boot itself
+
+```bash
+git clone https://github.com/MuratKus/qa-boot.git
+cd qa-boot && npm install
+npm test                 # vitest
+npm run dev -- scan      # run the CLI from source via tsx
+```
+
+Design and plan: [`docs/superpowers/specs/2026-06-02-qa-boot-v0-design.md`](./docs/superpowers/specs/2026-06-02-qa-boot-v0-design.md)
+and [`docs/superpowers/plans/2026-06-02-qa-boot-v0.md`](./docs/superpowers/plans/2026-06-02-qa-boot-v0.md).
+
+## Start here
+
+Read [`SPEC_INDEX.md`](./SPEC_INDEX.md) first.
+
+For implementation planning, start with:
+
+- [`docs/00-overview.md`](./docs/00-overview.md)
+- [`docs/02-v1-scope.md`](./docs/02-v1-scope.md)
+- [`docs/03-architecture.md`](./docs/03-architecture.md)
+
+## Tagline
+
+> Make Claude more grounded before making it more autonomous.

package/dist/cli/commands/generate.js

@@ -0,0 +1,7 @@
+import { loadConfig } from "../../config/config.js";
+import { runGenerate } from "../../generate/generate.js";
+export async function cmdGenerate(repoPath, opts) {
+    const config = loadConfig(repoPath);
+    const written = runGenerate({ repoPath, config, claude: opts.claude });
+    console.log(`Generated ${written.length} files.`);
+}

package/dist/cli/commands/init.js

@@ -0,0 +1,24 @@
+import { writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { defaultConfig } from "../../config/config.js";
+const README = `# QA Context
+
+This directory is generated and owned by \`qa-boot\`. Do not hand-edit these files —
+they are regenerated from \`facts.json\` on every \`qa-boot generate\`.
+
+- \`facts.json\` — the source of truth (written by \`qa-boot scan\`).
+- \`unknowns.md\` — what QA Boot could not determine, with questions to ask a human.
+- other \`*.md\` — per-domain summaries.
+`;
+export async function cmdInit(repoPath, opts) {
+    const configPath = join(repoPath, "qa-boot.config.json");
+    if (existsSync(configPath) && !opts.force) {
+        throw new Error("qa-boot.config.json already exists. Pass --force to overwrite.");
+    }
+    const config = defaultConfig(opts.projectName);
+    config.claude.enabled = opts.claude;
+    config.evidence_providers.qaradar.enabled = opts.qaradar;
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+    mkdirSync(join(repoPath, "qa-context"), { recursive: true });
+    writeFileSync(join(repoPath, "qa-context", "README.md"), README, "utf8");
+}

package/dist/cli/commands/scan.js

@@ -0,0 +1,30 @@
+import { join } from "node:path";
+import { loadConfig } from "../../config/config.js";
+import { buildScanContext } from "../../core/scan-context.js";
+import { FactStore } from "../../core/fact-store.js";
+import { todayISO } from "../../core/fact.js";
+import { runScanDetailed } from "../../pipeline/run-scan.js";
+import { cmdGenerate } from "./generate.js";
+export async function cmdScan(repoPath, opts) {
+    const config = loadConfig(repoPath);
+    if (opts.skipQaradar)
+        config.evidence_providers.qaradar.enabled = "false";
+    if (opts.withQaradar)
+        config.evidence_providers.qaradar.enabled = "true";
+    const ctx = buildScanContext(repoPath, config);
+    const today = todayISO();
+    const factsPath = join(repoPath, "qa-context", "facts.json");
+    const store = FactStore.load(factsPath);
+    store.markTimeStaleness(today);
+    const priorTold = store.all().filter((f) => f.provenance === "told" && !f.stale);
+    const { facts, qaradarRan } = await runScanDetailed(ctx, today, (m) => console.log(m), priorTold);
+    if (qaradarRan)
+        console.log("QA Radar: included its analysis.");
+    store.upsert(facts);
+    store.markTimeStaleness(today);
+    store.save(factsPath);
+    console.log(`Wrote ${store.all().length} facts to qa-context/facts.json`);
+    if (opts.generate) {
+        await cmdGenerate(repoPath, { claude: opts.claude });
+    }
+}

package/dist/cli/commands/tell.js

@@ -0,0 +1,27 @@
+import { join } from "node:path";
+import { FactStore } from "../../core/fact-store.js";
+import { todayISO } from "../../core/fact.js";
+import { applyTell } from "../../tell/tell.js";
+import { appendInterviewLog } from "../../tell/interview-log.js";
+export async function cmdTell(repoPath, unknownId, statement, opts) {
+    const factsPath = join(repoPath, "qa-context", "facts.json");
+    const store = FactStore.load(factsPath);
+    const today = todayISO();
+    store.markTimeStaleness(today);
+    const result = applyTell(store, { unknownId, domain: opts.domain, statement, by: opts.by ?? "", source: opts.source, idSlug: opts.id }, today);
+    store.save(factsPath);
+    appendInterviewLog(repoPath, {
+        date: today,
+        by: result.fact.told_by ?? "",
+        unknownId: result.fact.answers_unknown,
+        question: result.question,
+        domain: result.fact.domain,
+        statement: result.fact.statement,
+        factId: result.fact.id,
+        scope: result.fact.scope ?? "repo",
+    });
+    console.log(`Recorded told fact ${result.fact.id} (scope: ${result.fact.scope ?? "repo"}).`);
+    if (result.fact.answers_unknown)
+        console.log(`Resolved unknown ${result.fact.answers_unknown}.`);
+    console.log(`${result.remainingUnknowns} unknowns remain open. Run \`qa-boot scan\` to refresh context files and maturity.`);
+}

package/dist/cli/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { cmdInit } from "./commands/init.js";
+import { cmdScan } from "./commands/scan.js";
+import { cmdGenerate } from "./commands/generate.js";
+import { cmdTell } from "./commands/tell.js";
+import { cliVersion } from "./version.js";
+import { basename } from "node:path";
+const program = new Command();
+program.name("qa-boot").description("Bootstrap QA context for AI coding agents.").version(cliVersion());
+program
+    .command("init")
+    .description("Initialize qa-boot config in the current repo")
+    .option("--project-name <name>", "project name")
+    .option("--no-claude", "disable Claude output")
+    .option("--qaradar <mode>", "auto|true|false", "auto")
+    .option("--force", "overwrite existing config")
+    .action(async (o) => {
+    await cmdInit(process.cwd(), {
+        projectName: o.projectName ?? basename(process.cwd()),
+        claude: o.claude,
+        qaradar: o.qaradar,
+        force: o.force,
+    });
+});
+program
+    .command("scan")
+    .description("Scan the repo, write facts.json, and generate context")
+    .option("--no-generate", "write facts.json only")
+    .option("--no-claude", "skip Claude output during generate")
+    .option("--with-qaradar", "force-enable QA Radar")
+    .option("--skip-qaradar", "disable QA Radar")
+    .action(async (o) => {
+    await cmdScan(process.cwd(), {
+        generate: o.generate,
+        claude: o.claude,
+        withQaradar: Boolean(o.withQaradar),
+        skipQaradar: Boolean(o.skipQaradar),
+    });
+});
+program
+    .command("generate")
+    .description("Generate context files from qa-context/facts.json")
+    .option("--no-claude", "skip Claude output")
+    .action(async (o) => {
+    await cmdGenerate(process.cwd(), { claude: o.claude });
+});
+program
+    .command("tell <idOrStatement> [statement]")
+    .description("Record human-told QA knowledge (answer an unknown by id, or add --domain knowledge)")
+    .option("--domain <domain>", "domain for free-form knowledge")
+    .option("--by <who>", "who provided this knowledge (required)")
+    .option("--source <url>", "optional source link")
+    .option("--id <slug>", "explicit id slug for free-form mode")
+    .action(async (idOrStatement, statement, o) => {
+    const isAnswer = statement !== undefined;
+    await cmdTell(process.cwd(), isAnswer ? idOrStatement : undefined, isAnswer ? statement : idOrStatement, {
+        domain: o.domain,
+        by: o.by,
+        source: o.source,
+        id: o.id,
+    });
+});
+program.parseAsync().catch((err) => {
+    console.error(String(err instanceof Error ? err.message : err));
+    process.exitCode = 1;
+});

package/dist/cli/version.js

@@ -0,0 +1,5 @@
+import { createRequire } from "node:module";
+export function cliVersion() {
+    const pkg = createRequire(import.meta.url)("../../package.json");
+    return pkg.version;
+}

package/dist/config/config.js

@@ -0,0 +1,34 @@
+import { readJson } from "../core/fs-utils.js";
+export function defaultConfig(projectName) {
+    return {
+        project_name: projectName,
+        mode: "single-repo",
+        claude: { enabled: true, generate_skills: true },
+        evidence_providers: { qaradar: { enabled: "auto", days: 90, top: 20 } },
+        refresh: { default_days: 30 },
+    };
+}
+export function normalizeConfig(partial) {
+    const base = defaultConfig(partial.project_name ?? "project");
+    return {
+        project_name: partial.project_name ?? base.project_name,
+        mode: "single-repo",
+        claude: { ...base.claude, ...partial.claude },
+        evidence_providers: {
+            qaradar: { ...base.evidence_providers.qaradar, ...partial.evidence_providers?.qaradar },
+        },
+        refresh: { ...base.refresh, ...partial.refresh },
+    };
+}
+export function loadConfig(repoPath) {
+    const raw = readJson(repoPath, "qa-boot.config.json");
+    return normalizeConfig(raw ?? { project_name: "project" });
+}
+export function qaradarEnabled(c) {
+    const v = c.evidence_providers.qaradar.enabled;
+    if (v === true)
+        return "true";
+    if (v === false)
+        return "false";
+    return v;
+}

package/dist/core/fact-store.js

@@ -0,0 +1,50 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { todayISO } from "./fact.js";
+function daysBetween(a, b) {
+    const ms = Date.parse(b) - Date.parse(a);
+    return Math.floor(ms / 86_400_000);
+}
+export class FactStore {
+    facts = new Map();
+    constructor(initial = []) {
+        for (const f of initial)
+            this.facts.set(f.id, f);
+    }
+    static load(path) {
+        if (!existsSync(path))
+            return new FactStore([]);
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return new FactStore(raw.facts ?? []);
+    }
+    save(path) {
+        mkdirSync(dirname(path), { recursive: true });
+        const out = { facts: this.all() };
+        writeFileSync(path, JSON.stringify(out, null, 2) + "\n", "utf8");
+    }
+    upsert(incoming) {
+        for (const f of incoming) {
+            const next = { ...f };
+            delete next.stale;
+            delete next.stale_reason;
+            this.facts.set(f.id, next);
+        }
+    }
+    markTimeStaleness(today = todayISO()) {
+        for (const f of this.facts.values()) {
+            if (daysBetween(f.last_verified, today) > f.expires_after_days) {
+                f.stale = true;
+                f.stale_reason = "expired";
+            }
+        }
+    }
+    remove(id) {
+        return this.facts.delete(id);
+    }
+    byId(id) {
+        return this.facts.get(id);
+    }
+    all() {
+        return [...this.facts.values()].sort((a, b) => a.id.localeCompare(b.id));
+    }
+}

package/dist/core/fact.js

@@ -0,0 +1,30 @@
+export function todayISO(d = new Date()) {
+    return d.toISOString().slice(0, 10);
+}
+export function makeFact(input, today = todayISO()) {
+    const f = {
+        id: input.id,
+        domain: input.domain,
+        statement: input.statement,
+        value: input.value ?? null,
+        provenance: input.provenance,
+        confidence: input.confidence,
+        evidence_provider: input.evidence_provider,
+        evidence_command: input.evidence_command ?? "qa-boot scan",
+        evidence: input.evidence ?? [],
+        limitations: input.limitations ?? [],
+        risk_if_wrong: input.risk_if_wrong ?? "",
+        needs_human_confirmation: input.needs_human_confirmation ?? false,
+        last_verified: today,
+        expires_after_days: input.expires_after_days ?? 30,
+    };
+    if (input.told_by !== undefined)
+        f.told_by = input.told_by;
+    if (input.scope !== undefined)
+        f.scope = input.scope;
+    if (input.source !== undefined)
+        f.source = input.source;
+    if (input.answers_unknown !== undefined)
+        f.answers_unknown = input.answers_unknown;
+    return f;
+}

package/dist/core/fs-utils.js

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import fg from "fast-glob";
+import { minimatch } from "minimatch";
+const IGNORE = ["**/node_modules/**", "**/.git/**", "**/dist/**"];
+export function listFiles(root) {
+    return fg.sync("**/*", {
+        cwd: root,
+        dot: true,
+        ignore: IGNORE,
+        onlyFiles: false,
+        markDirectories: true,
+    });
+}
+export function exists(files, pattern) {
+    return files.some((f) => minimatch(f, pattern, { dot: true }));
+}
+export function matches(files, pattern) {
+    return files.filter((f) => minimatch(f, pattern, { dot: true }));
+}
+export function readText(root, rel) {
+    try {
+        return readFileSync(join(root, rel), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function readJson(root, rel) {
+    const text = readText(root, rel);
+    if (text === null)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/scan-context.js

@@ -0,0 +1,13 @@
+import { listFiles, exists, matches, readText, readJson } from "./fs-utils.js";
+export function buildScanContext(repoPath, config) {
+    const files = listFiles(repoPath);
+    return {
+        repoPath,
+        config,
+        files,
+        has: (p) => exists(files, p),
+        match: (p) => matches(files, p),
+        read: (rel) => readText(repoPath, rel),
+        readJson: (rel) => readJson(repoPath, rel),
+    };
+}

package/dist/core/slug.js

@@ -0,0 +1,8 @@
+export function slug(name, maxLen = 60) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, maxLen)
+        .replace(/-+$/g, "");
+}

package/dist/domains/agent-facts.js

@@ -0,0 +1,31 @@
+import { makeFact } from "../core/fact.js";
+import { slug } from "../core/slug.js";
+const PROVIDER = "agent-config-scanner";
+export function agentFacts(ev, today) {
+    const facts = [];
+    for (const e of ev.filter((x) => x.kind === "agent-config")) {
+        const name = String(e.detail?.name);
+        facts.push(makeFact({
+            id: `agent_permissions.config.${slug(name)}`,
+            domain: "agent_permissions",
+            statement: `Agent config ${name} is present.`,
+            provenance: "observed",
+            confidence: 0.8,
+            evidence_provider: PROVIDER,
+            evidence: e.path ? [e.path] : [],
+            limitations: ["Presence does not define what the agent is permitted to do."],
+        }, today));
+    }
+    if (ev.some((e) => e.kind === "agent-skills")) {
+        facts.push(makeFact({
+            id: "agent_permissions.skills",
+            domain: "agent_permissions",
+            statement: "Existing Claude skills were detected.",
+            provenance: "observed",
+            confidence: 0.8,
+            evidence_provider: PROVIDER,
+            evidence: [".claude/skills"],
+        }, today));
+    }
+    return facts;
+}

package/dist/domains/build-facts.js

@@ -0,0 +1,31 @@
+import { makeFact } from "../core/fact.js";
+const PROVIDER = "build-scanner";
+export function buildFacts(ev, today) {
+    const facts = [];
+    for (const e of ev.filter((x) => x.kind === "build-command")) {
+        const name = String(e.detail?.name);
+        facts.push(makeFact({
+            id: `build.command.${name}`,
+            domain: "build",
+            statement: `A "${name}" command is defined.`,
+            provenance: "observed",
+            confidence: 0.8,
+            evidence_provider: PROVIDER,
+            evidence: e.path ? [e.path] : [],
+            value: { command: String(e.detail?.cmd) },
+        }, today));
+    }
+    for (const e of ev.filter((x) => x.kind === "build-file")) {
+        const name = String(e.detail?.name);
+        facts.push(makeFact({
+            id: `build.tool.${name}`,
+            domain: "build",
+            statement: `Build tooling detected: ${name}.`,
+            provenance: "observed",
+            confidence: 0.8,
+            evidence_provider: PROVIDER,
+            evidence: e.path ? [e.path] : [],
+        }, today));
+    }
+    return facts;
+}

package/dist/domains/ci-facts.js

@@ -0,0 +1,43 @@
+import { makeFact } from "../core/fact.js";
+const PROVIDER = "ci-scanner";
+export function ciFacts(ev, today) {
+    const facts = [];
+    for (const e of ev.filter((x) => x.kind === "ci-system")) {
+        const name = String(e.detail?.name);
+        facts.push(makeFact({
+            id: `ci.system.${name}`,
+            domain: "ci",
+            statement: `CI system ${name} detected.`,
+            provenance: "observed",
+            confidence: 0.8,
+            evidence_provider: PROVIDER,
+            evidence: e.path ? [e.path] : [],
+        }, today));
+    }
+    const jobs = ev.filter((x) => x.kind === "ci-job");
+    const hasKind = (k) => jobs.some((j) => j.detail?.kind === k);
+    if (hasKind("test")) {
+        facts.push(makeFact({
+            id: "ci.runs-tests",
+            domain: "ci",
+            statement: "CI appears to run tests.",
+            provenance: "inferred",
+            confidence: 0.5,
+            evidence_provider: PROVIDER,
+            evidence: jobs.filter((j) => j.detail?.kind === "test").map((j) => j.path).filter(Boolean),
+            limitations: ["Job name suggests tests; not confirmed to block merges."],
+        }, today));
+    }
+    if (hasKind("deploy")) {
+        facts.push(makeFact({
+            id: "ci.has-deploy-job",
+            domain: "release",
+            statement: "A deploy/release job is present in CI.",
+            provenance: "inferred",
+            confidence: 0.5,
+            evidence_provider: PROVIDER,
+            evidence: jobs.filter((j) => j.detail?.kind === "deploy").map((j) => j.path).filter(Boolean),
+        }, today));
+    }
+    return facts;
+}

package/dist/domains/docs-facts.js

@@ -0,0 +1,28 @@
+import { makeFact } from "../core/fact.js";
+const PROVIDER = "docs-scanner";
+const LABEL = {
+    readme: "README documentation",
+    contributing: "Contributing guide",
+    "docs-dir": "A docs/ directory",
+    codeowners: "CODEOWNERS file",
+    "pr-template": "Pull request template",
+    "issue-template": "Issue template",
+    changelog: "Changelog",
+    adr: "Architecture decision records",
+};
+export function docsFacts(ev, today) {
+    return ev
+        .filter((e) => e.kind === "doc")
+        .map((e) => {
+        const kind = String(e.detail?.kind);
+        return makeFact({
+            id: `knowledge_sources.${kind}`,
+            domain: "knowledge_sources",
+            statement: `${LABEL[kind] ?? kind} is present.`,
+            provenance: "observed",
+            confidence: 0.8,
+            evidence_provider: PROVIDER,
+            evidence: e.path ? [e.path] : [],
+        }, today);
+    });
+}

package/dist/domains/repo-facts.js

@@ -0,0 +1,52 @@
+import { makeFact } from "../core/fact.js";
+const PROVIDER = "repo-scanner";
+export function repoFacts(ev, today) {
+    const facts = [];
+    for (const e of ev.filter((x) => x.kind === "language")) {
+        const name = String(e.detail?.name);
+        facts.push(makeFact({
+            id: `repo.language.${name}`,
+            domain: "repo",
+            statement: `Repository uses ${name}.`,
+            provenance: "observed",
+            confidence: 0.8,
+            evidence_provider: PROVIDER,
+            evidence: e.path ? [e.path] : [],
+        }, today));
+    }
+    for (const e of ev.filter((x) => x.kind === "package-manager")) {
+        const name = String(e.detail?.name);
+        facts.push(makeFact({
+            id: `repo.package-manager.${name}`,
+            domain: "repo",
+            statement: `Package manager ${name} detected.`,
+            provenance: "observed",
+            confidence: 0.8,
+            evidence_provider: PROVIDER,
+            evidence: e.path ? [e.path] : [],
+        }, today));
+    }
+    if (ev.some((e) => e.kind === "readme")) {
+        facts.push(makeFact({
+            id: "repo.readme",
+            domain: "repo",
+            statement: "A README is present.",
+            provenance: "observed",
+            confidence: 0.8,
+            evidence_provider: PROVIDER,
+            evidence: ev.filter((e) => e.kind === "readme").map((e) => e.path).filter(Boolean),
+        }, today));
+    }
+    if (ev.some((e) => e.kind === "monorepo")) {
+        facts.push(makeFact({
+            id: "repo.monorepo",
+            domain: "repo",
+            statement: "Monorepo workspace markers detected.",
+            provenance: "inferred",
+            confidence: 0.5,
+            evidence_provider: PROVIDER,
+            evidence: ev.filter((e) => e.kind === "monorepo").map((e) => e.path).filter(Boolean),
+        }, today));
+    }
+    return facts;
+}