@praneeth_54/agentdoctor 2.1.0 → 3.0.1

package/dist/product/requirements/trace.js

@@ -0,0 +1,166 @@
+import path from "node:path";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
+import { readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { isLikelyRequirementsDoc, isMarkdownDoc } from "../evidence-scan.js";
+const REQ_HEADING = /^(#{1,4})\s+(?:REQ[-\s]?(\d+)[:\s]+|Requirement\s+(\d+)[:\s]+|US[-\s]?(\d+)[:\s]+|User\s+Story\s+(\d+)[:\s]+)?(.+)$/i;
+const AC_LINE = /^\s*[-*]\s*(?:AC|Acceptance Criteria)[:\s]+(.+)$/i;
+const AC_SECTION = /^#{1,4}\s+Acceptance Criteria\s*$/i;
+function slugId(sourcePath, line, title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40);
+    return `${sourcePath.replace(/[^\w./-]/g, "_")}:${line}:${slug || "req"}`;
+}
+function testFileMightCover(title, testPaths) {
+    const tokens = title
+        .toLowerCase()
+        .split(/\W+/)
+        .filter((t) => t.length > 3);
+    if (!tokens.length)
+        return false;
+    for (const tp of testPaths) {
+        const lower = tp.toLowerCase();
+        if (tokens.some((t) => lower.includes(t)))
+            return true;
+    }
+    return false;
+}
+function isTestPath(relativePath) {
+    const p = relativePath.toLowerCase();
+    return (p.includes(".test.") ||
+        p.includes(".spec.") ||
+        p.startsWith("tests/") ||
+        p.startsWith("test/") ||
+        p.includes("__tests__/"));
+}
+function docEligible(relativePath, content) {
+    if (!isMarkdownDoc(relativePath))
+        return false;
+    if (isLikelyRequirementsDoc(relativePath))
+        return true;
+    if (/acceptance criteria/i.test(content))
+        return true;
+    if (/^#{1,4}\s+(?:REQ|Requirement|User Story)/im.test(content))
+        return true;
+    return false;
+}
+function parseRequirementsFromDoc(relativePath, content, testPaths) {
+    const lines = content.split(/\r?\n/);
+    const out = [];
+    let inAcSection = false;
+    let current = null;
+    const flush = () => {
+        if (!current)
+            return;
+        if (current.acceptanceCriteria.length === 0) {
+            current.truth = "PARTIAL";
+        }
+        current.missingTestHeuristic = !testFileMightCover(current.title, testPaths);
+        if (current.missingTestHeuristic) {
+            current.missingTestNote =
+                "No test file path matched requirement title tokens (heuristic only).";
+        }
+        out.push(current);
+        current = null;
+        inAcSection = false;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const lineNo = i + 1;
+        if (AC_SECTION.test(line.trim())) {
+            inAcSection = true;
+            continue;
+        }
+        const heading = REQ_HEADING.exec(line.trim());
+        if (heading) {
+            flush();
+            const reqNum = heading[2] ?? heading[3] ?? heading[4] ?? heading[5];
+            const titlePart = (heading[6] ?? "").trim();
+            const base = relativePath.split("/").pop()?.toLowerCase() ?? "";
+            const explicitCatalog = base === "requirements.md" || base === "user-stories.md";
+            if (!reqNum && !explicitCatalog)
+                continue;
+            const title = reqNum ? titlePart : titlePart || line.replace(/^#{1,4}\s+/, "").trim();
+            if (!title || title.length < 3)
+                continue;
+            const displayTitle = reqNum ? `REQ-${reqNum}: ${title}` : title;
+            current = {
+                id: slugId(relativePath, lineNo, displayTitle),
+                title: displayTitle,
+                sourcePath: relativePath,
+                sourceLine: lineNo,
+                acceptanceCriteria: [],
+                truth: "VERIFIED",
+                evidence: [{ path: relativePath, line: lineNo, excerpt: line.trim().slice(0, 120) }],
+                missingTestHeuristic: false,
+            };
+            inAcSection = false;
+            continue;
+        }
+        if (!current)
+            continue;
+        const acInline = AC_LINE.exec(line);
+        if (acInline?.[1]) {
+            current.acceptanceCriteria.push(acInline[1].trim());
+            current.evidence.push({
+                path: relativePath,
+                line: lineNo,
+                excerpt: line.trim().slice(0, 120),
+            });
+            continue;
+        }
+        if (inAcSection && /^\s*[-*]\s+/.test(line)) {
+            const item = line.replace(/^\s*[-*]\s+/, "").trim();
+            if (item) {
+                current.acceptanceCriteria.push(item);
+                current.evidence.push({
+                    path: relativePath,
+                    line: lineNo,
+                    excerpt: item.slice(0, 120),
+                });
+            }
+        }
+        else if (inAcSection && line.trim() === "") {
+            continue;
+        }
+        else if (inAcSection && /^#{1,4}\s/.test(line)) {
+            inAcSection = false;
+        }
+    }
+    flush();
+    return out;
+}
+/**
+ * Scan repository docs for requirements / user stories with file evidence only.
+ */
+export async function traceRequirements(rootInput, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE_BYTES) {
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const limitations = [
+        "Requirements are extracted only from markdown headings and acceptance-criteria sections present in files.",
+        "Missing-test detection is a filename/token heuristic, not coverage analysis.",
+    ];
+    if (detection.diagnostics.length) {
+        limitations.push(...detection.diagnostics.slice(0, 3));
+    }
+    const testPaths = detection.discovery.files.map((f) => f.relativePath).filter(isTestPath);
+    const requirements = [];
+    for (const entry of detection.discovery.files) {
+        const rel = entry.relativePath.replace(/\\/g, "/");
+        const abs = path.join(root, rel);
+        const text = await readTextFile(abs, maxFileSizeBytes);
+        if (text === null)
+            continue;
+        if (!docEligible(rel, text))
+            continue;
+        requirements.push(...parseRequirementsFromDoc(rel, text, testPaths));
+    }
+    requirements.sort((a, b) => a.sourcePath === b.sourcePath
+        ? a.sourceLine - b.sourceLine
+        : a.sourcePath.localeCompare(b.sourcePath));
+    return { root, requirements, limitations };
+}

package/dist/product/search/index.d.ts

@@ -0,0 +1,29 @@
+export interface IndexDocument {
+    id: string;
+    path: string;
+    text: string;
+}
+export interface TfidfIndex {
+    documents: IndexDocument[];
+    idf: Map<string, number>;
+    docVectors: Map<string, Map<string, number>>;
+    limitations: string[];
+}
+export declare function buildIndex(documents: IndexDocument[]): TfidfIndex;
+export declare function searchIndex(index: TfidfIndex, query: string, maxHits?: number): Array<{
+    document: IndexDocument;
+    score: number;
+}>;
+export declare function documentId(path: string, content: string): string;
+export declare function searchHybrid(index: TfidfIndex, query: string, substringHits: Array<{
+    path: string;
+    line?: number;
+    excerpt: string;
+    score: number;
+}>, maxHits?: number): Array<{
+    path: string;
+    line?: number;
+    excerpt: string;
+    score: number;
+    kind: "tfidf" | "keyword";
+}>;

package/dist/product/search/index.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+const TOKEN_RE = /[a-zA-Z][a-zA-Z0-9_]{1,48}|[0-9]+/g;
+function tokenize(text) {
+    const lower = text.toLowerCase();
+    const matches = lower.match(TOKEN_RE);
+    return matches ?? [];
+}
+function termFrequency(tokens) {
+    const tf = new Map();
+    for (const t of tokens) {
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    }
+    const max = Math.max(1, ...tf.values());
+    for (const [k, v] of tf) {
+        tf.set(k, v / max);
+    }
+    return tf;
+}
+export function buildIndex(documents) {
+    const limitations = [
+        "Local index uses keyword TF-IDF — not neural embeddings or semantic similarity.",
+    ];
+    const docTokens = new Map();
+    const df = new Map();
+    for (const doc of documents) {
+        const tokens = tokenize(doc.text);
+        docTokens.set(doc.id, tokens);
+        const unique = new Set(tokens);
+        for (const t of unique) {
+            df.set(t, (df.get(t) ?? 0) + 1);
+        }
+    }
+    const n = Math.max(1, documents.length);
+    const idf = new Map();
+    for (const [term, count] of df) {
+        idf.set(term, Math.log((1 + n) / (1 + count)) + 1);
+    }
+    const docVectors = new Map();
+    for (const doc of documents) {
+        const tf = termFrequency(docTokens.get(doc.id) ?? []);
+        const vec = new Map();
+        for (const [term, weight] of tf) {
+            const idfVal = idf.get(term) ?? 1;
+            vec.set(term, weight * idfVal);
+        }
+        docVectors.set(doc.id, vec);
+    }
+    return { documents, idf, docVectors, limitations };
+}
+function vectorNorm(vec) {
+    let sum = 0;
+    for (const v of vec.values())
+        sum += v * v;
+    return Math.sqrt(sum) || 1;
+}
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    const smaller = a.size <= b.size ? a : b;
+    const other = a.size <= b.size ? b : a;
+    for (const [term, weight] of smaller) {
+        const ow = other.get(term);
+        if (ow !== undefined)
+            dot += weight * ow;
+    }
+    return dot / (vectorNorm(a) * vectorNorm(b));
+}
+export function searchIndex(index, query, maxHits = 40) {
+    const qTokens = tokenize(query);
+    if (!qTokens.length)
+        return [];
+    const qTf = termFrequency(qTokens);
+    const qVec = new Map();
+    for (const [term, weight] of qTf) {
+        qVec.set(term, weight * (index.idf.get(term) ?? 1));
+    }
+    const hits = [];
+    for (const doc of index.documents) {
+        const dVec = index.docVectors.get(doc.id);
+        if (!dVec)
+            continue;
+        const score = cosineSimilarity(qVec, dVec);
+        if (score > 0)
+            hits.push({ document: doc, score });
+    }
+    hits.sort((a, b) => b.score - a.score || a.document.path.localeCompare(b.document.path));
+    return hits.slice(0, maxHits);
+}
+export function documentId(path, content) {
+    return createHash("sha1").update(`${path}\0${content.length}`).digest("hex").slice(0, 16);
+}
+export function searchHybrid(index, query, substringHits, maxHits = 40) {
+    const tfidf = searchIndex(index, query, maxHits);
+    const merged = new Map();
+    for (const h of tfidf) {
+        const key = h.document.path;
+        merged.set(key, {
+            path: h.document.path,
+            excerpt: h.document.text.slice(0, 140),
+            score: h.score + 0.05,
+            kind: "tfidf",
+        });
+    }
+    for (const h of substringHits) {
+        const key = `${h.path}:${h.line ?? 0}`;
+        const prev = merged.get(key);
+        if (!prev || h.score > prev.score) {
+            merged.set(key, { ...h, kind: "keyword" });
+        }
+        else if (prev) {
+            merged.set(key, { ...prev, score: prev.score + h.score * 0.5 });
+        }
+    }
+    return [...merged.values()]
+        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+        .slice(0, maxHits);
+}

package/dist/product/search/software-search.d.ts

@@ -0,0 +1,19 @@
+import type { TruthLabel } from "../truth.js";
+export interface SoftwareSearchHit {
+    kind: "filename" | "content" | "brain" | "tfidf";
+    path: string;
+    line?: number;
+    excerpt: string;
+    score: number;
+    truth: TruthLabel;
+}
+export interface SoftwareSearchReport {
+    root: string;
+    query: string;
+    hits: SoftwareSearchHit[];
+    limitations: string[];
+}
+export declare function searchSymbolsAndConcepts(rootInput: string, query: string, options?: {
+    maxHits?: number;
+    maxFiles?: number;
+}): Promise<SoftwareSearchReport>;

package/dist/product/search/software-search.js

@@ -0,0 +1,105 @@
+import path from "node:path";
+import { loadLatestBrain, searchBrain } from "../../core/brain-cli/service.js";
+import { detectProject } from "../../detectors/project.js";
+import { readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { buildIndex, documentId, searchHybrid } from "./index.js";
+export async function searchSymbolsAndConcepts(rootInput, query, options) {
+    const root = resolveRepoRoot(rootInput);
+    const q = query.trim();
+    const maxHits = options?.maxHits ?? 40;
+    const maxFiles = options?.maxFiles ?? 300;
+    const limitations = [
+        "Search combines TF-IDF keyword index + brain claims + bounded filename/content scan.",
+        "TF-IDF is lexical — not neural embeddings or semantic code search.",
+        "Content substring hits are INFERRED.",
+    ];
+    if (!q) {
+        return { root, query: q, hits: [], limitations: [...limitations, "Empty query"] };
+    }
+    const hits = [];
+    const qLower = q.toLowerCase();
+    const brain = await loadLatestBrain(root);
+    if (brain) {
+        for (const bh of searchBrain(brain, q)) {
+            if (bh.text.includes(".private/") ||
+                bh.text.includes("AgentDoctorOS/") ||
+                bh.text.includes("oss-validation/")) {
+                continue;
+            }
+            hits.push({
+                kind: "brain",
+                path: ".agentdoctor/project-brain",
+                excerpt: bh.text,
+                score: bh.score + 0.2,
+                truth: "INFERRED",
+            });
+        }
+    }
+    else {
+        limitations.push("No project brain snapshot; brain search skipped.");
+    }
+    const detection = await detectProject(root);
+    let filesScanned = 0;
+    const indexDocs = [];
+    const substringHits = [];
+    for (const entry of detection.discovery.files) {
+        if (filesScanned >= maxFiles)
+            break;
+        const rel = entry.relativePath.replace(/\\/g, "/");
+        filesScanned += 1;
+        const base = path.basename(rel).toLowerCase();
+        if (base.includes(qLower)) {
+            hits.push({
+                kind: "filename",
+                path: rel,
+                excerpt: rel,
+                score: 1.1,
+                truth: "VERIFIED",
+            });
+        }
+        const text = await readTextFile(path.join(root, rel), 256 * 1024);
+        if (text === null)
+            continue;
+        indexDocs.push({
+            id: documentId(rel, text),
+            path: rel,
+            text: `${rel}\n${text.slice(0, 8_000)}`,
+        });
+        const idx = text.toLowerCase().indexOf(qLower);
+        if (idx >= 0) {
+            const line = text.slice(0, idx).split("\n").length;
+            const lineText = text.split(/\r?\n/)[line - 1]?.trim() ?? "";
+            substringHits.push({
+                path: rel,
+                line,
+                excerpt: lineText.slice(0, 140),
+                score: 1,
+            });
+        }
+    }
+    if (filesScanned >= maxFiles) {
+        limitations.push(`Content scan capped at ${maxFiles} files`);
+    }
+    if (indexDocs.length) {
+        const index = buildIndex(indexDocs);
+        limitations.push(...index.limitations);
+        for (const h of searchHybrid(index, q, substringHits, maxHits)) {
+            hits.push({
+                kind: h.kind === "tfidf" ? "tfidf" : "content",
+                path: h.path,
+                ...(h.line !== undefined ? { line: h.line } : {}),
+                excerpt: h.excerpt,
+                score: h.score,
+                truth: h.kind === "tfidf" ? "INFERRED" : "INFERRED",
+            });
+        }
+    }
+    hits.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+    return {
+        root,
+        query: q,
+        hits: hits.slice(0, maxHits),
+        limitations,
+    };
+}

package/dist/product/security/doctor.d.ts

@@ -0,0 +1,23 @@
+import { type SecretFinding } from "../../core/secrets/scan.js";
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface SecurityPatternFinding {
+    id: string;
+    title: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface SecurityDoctorReport {
+    root: string;
+    /** Local heuristic rules only — not enterprise SAST. */
+    staticAnalysisLabel: "TECHNICAL_STATIC_ANALYSIS_SUPPORTED";
+    secretScan: {
+        enabled: boolean;
+        filesScanned: number;
+        findings: SecretFinding[];
+        limitations: string[];
+    };
+    authMarkers: SecurityPatternFinding[];
+    dangerousPatterns: SecurityPatternFinding[];
+    limitations: string[];
+}
+export declare function analyzeSecuritySurface(rootInput: string): Promise<SecurityDoctorReport>;

package/dist/product/security/doctor.js

@@ -0,0 +1,124 @@
+import { scanSecrets } from "../../core/secrets/scan.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { lineNumberAt, loadProjectSourceFiles } from "../evidence-scan.js";
+const AUTH_MARKERS = [
+    {
+        id: "middleware-auth",
+        title: "Auth middleware marker",
+        re: /\b(?:auth|authenticate|authorize)\s*\(/i,
+    },
+    { id: "laravel-gate", title: "Laravel Gate/Policy marker", re: /\bGate::|\bPolicy\b|\b@can\b/i },
+    { id: "nestjs-guard", title: "NestJS guard/decorator marker", re: /@UseGuards\b|AuthGuard\b/i },
+    {
+        id: "rbac-role",
+        title: "RBAC role/permission marker",
+        re: /\b(?:hasPermission|hasRole|@PreAuthorize|@Roles)\b/i,
+    },
+];
+const DANGEROUS_PATTERNS = [
+    { id: "eval-call", title: "Dynamic eval() (CWE-95)", re: /\beval\s*\(/g },
+    {
+        id: "child-process-exec-string",
+        title: "child_process exec with string literal (CWE-78)",
+        re: /\b(?:exec|execSync)\s*\(\s*['"`]/g,
+    },
+    {
+        id: "child-process-exec-concat",
+        title: "child_process exec with string concatenation (CWE-78)",
+        re: /\b(?:exec|execSync)\s*\(\s*[^)]*\+/g,
+    },
+    {
+        id: "innerhtml-assign",
+        title: "DOM innerHTML assignment (CWE-79)",
+        re: /\.innerHTML\s*=/g,
+    },
+    {
+        id: "path-join-user-input",
+        title: "Path join with request/user input pattern (CWE-22)",
+        re: /\bpath\.(?:join|resolve)\s*\([^)]*(?:req\.|request\.|params\.|query\.|user[A-Z_a-z]*|input)/g,
+    },
+    { id: "shell-exec", title: "Shell invocation helper", re: /\bshell\s*:\s*true\b/g },
+];
+function redactExcerpt(line) {
+    return line
+        .trim()
+        .slice(0, 120)
+        .replace(/['"][^'"]{8,}['"]/g, "'[REDACTED]'");
+}
+export async function analyzeSecuritySurface(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const limitations = [
+        "TECHNICAL STATIC ANALYSIS SUPPORTED locally (regex/heuristic rules with file evidence — not full SAST).",
+        "Security doctor uses heuristic pattern scans — not a substitute for SAST/DAST or manual review.",
+        "Secret values are never included; only redacted snippets and rule ids.",
+    ];
+    const secretScan = await scanSecrets({ root, enabled: true, maxFiles: 400 });
+    const { files } = await loadProjectSourceFiles(root, (rel) => /\.(ts|tsx|js|jsx|mjs|cjs|py|php|go)$/i.test(rel));
+    const authMarkers = [];
+    const dangerousPatterns = [];
+    for (const file of files) {
+        for (const marker of AUTH_MARKERS) {
+            marker.re.lastIndex = 0;
+            if (marker.re.test(file.content)) {
+                const idx = file.content.search(marker.re);
+                authMarkers.push({
+                    id: marker.id,
+                    title: marker.title,
+                    truth: "INFERRED",
+                    evidence: [
+                        {
+                            path: file.relativePath,
+                            ...(idx >= 0 ? { line: lineNumberAt(file.content, idx) } : {}),
+                            excerpt: redactExcerpt(file.content.split(/\r?\n/)[Math.max(0, lineNumberAt(file.content, Math.max(idx, 0)) - 1)] ?? ""),
+                        },
+                    ],
+                });
+                break;
+            }
+        }
+        for (const pattern of DANGEROUS_PATTERNS) {
+            pattern.re.lastIndex = 0;
+            let match;
+            while ((match = pattern.re.exec(file.content)) !== null) {
+                const line = lineNumberAt(file.content, match.index);
+                const lineText = file.content.split(/\r?\n/)[line - 1] ?? "";
+                dangerousPatterns.push({
+                    id: pattern.id,
+                    title: pattern.title,
+                    truth: "INFERRED",
+                    evidence: [
+                        {
+                            path: file.relativePath,
+                            line,
+                            excerpt: redactExcerpt(lineText),
+                        },
+                    ],
+                });
+                if (dangerousPatterns.length >= 80)
+                    break;
+            }
+            if (dangerousPatterns.length >= 80)
+                break;
+        }
+        if (dangerousPatterns.length >= 80) {
+            limitations.push("Dangerous pattern finding cap reached (80)");
+            break;
+        }
+    }
+    if (authMarkers.length === 0) {
+        limitations.push("No auth/permission file markers matched heuristics (absence is not proof).");
+    }
+    return {
+        root,
+        staticAnalysisLabel: "TECHNICAL_STATIC_ANALYSIS_SUPPORTED",
+        secretScan: {
+            enabled: secretScan.enabled,
+            filesScanned: secretScan.filesScanned,
+            findings: secretScan.findings,
+            limitations: secretScan.limitations,
+        },
+        authMarkers: authMarkers.slice(0, 40),
+        dangerousPatterns,
+        limitations,
+    };
+}

package/dist/product/self/diagnose.d.ts

@@ -0,0 +1,15 @@
+import type { TruthLabel } from "../truth.js";
+export interface SelfDiagnoseFinding {
+    id: string;
+    label: string;
+    ok: boolean;
+    truth: TruthLabel;
+    evidence: string;
+}
+export interface SelfDiagnoseReport {
+    root: string;
+    ok: boolean;
+    findings: SelfDiagnoseFinding[];
+    limitations: string[];
+}
+export declare function diagnoseAgentDoctorSelf(rootInput?: string): Promise<SelfDiagnoseReport>;

package/dist/product/self/diagnose.js

@@ -0,0 +1,82 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { detectProject } from "../../detectors/project.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { pathExists } from "../../utils/fs.js";
+const REQUIRED_MODULES = [
+    "src/security/paths.ts",
+    "src/enforcement/runner.ts",
+    "src/assurance/change.ts",
+    "src/intelligence/graph/build.ts",
+];
+export async function diagnoseAgentDoctorSelf(rootInput) {
+    const root = resolveRepoRoot(rootInput ?? process.cwd());
+    const limitations = [
+        "Self-check reports VERIFIED findings only when files/signals are present on disk.",
+        "Does not validate npm publish or CI status.",
+    ];
+    const findings = [];
+    try {
+        const detection = await detectProject(root);
+        const langs = detection.repository.languages ?? [];
+        findings.push({
+            id: "detect-project",
+            label: "detectProject completes",
+            ok: true,
+            truth: "VERIFIED",
+            evidence: `languages=${langs.join(",") || "none"}`,
+        });
+    }
+    catch (error) {
+        findings.push({
+            id: "detect-project",
+            label: "detectProject completes",
+            ok: false,
+            truth: "VERIFIED",
+            evidence: error instanceof Error ? error.message : String(error),
+        });
+    }
+    const testsDir = path.join(root, "tests");
+    const testsExists = await pathExists(testsDir);
+    findings.push({
+        id: "tests-dir",
+        label: "tests/ directory exists",
+        ok: testsExists,
+        truth: testsExists ? "VERIFIED" : "VERIFIED",
+        evidence: testsExists ? "tests/" : "missing tests/",
+    });
+    const pkgPath = path.join(root, "package.json");
+    let scriptsOk = false;
+    let scriptEvidence = "no package.json";
+    if (await pathExists(pkgPath)) {
+        try {
+            const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+            const scripts = pkg.scripts ?? {};
+            scriptsOk = typeof scripts.test === "string";
+            scriptEvidence = scriptsOk ? `test script present` : "test script missing";
+        }
+        catch {
+            scriptEvidence = "package.json unreadable";
+        }
+    }
+    findings.push({
+        id: "package-test-script",
+        label: "package.json defines test script",
+        ok: scriptsOk,
+        truth: "VERIFIED",
+        evidence: scriptEvidence,
+    });
+    for (const rel of REQUIRED_MODULES) {
+        const abs = path.join(root, rel);
+        const ok = await pathExists(abs);
+        findings.push({
+            id: `module-${rel.replace(/[^\w]/g, "-")}`,
+            label: `Required module ${rel}`,
+            ok,
+            truth: "VERIFIED",
+            evidence: ok ? "present" : "missing",
+        });
+    }
+    const ok = findings.every((f) => f.ok);
+    return { root, ok, findings, limitations };
+}