@dailephd/my-dev-kit-lab 0.2.2 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 my-dev-kit-lab is the experiment, evidence, reporting, security-validation, and future audit companion for my-dev-kit. It runs reproducible experiments that test whether my-dev-kit's graph-guided retrieval helps coding-agent workflows, collects metrics, renders reports, generates plots, captures screenshots, builds gallery outputs, and performs automated CLI/package security validation.
 
-The current package is v0.2.2, release-prepared but not yet published to npm. Its generic experiment-plugin framework was introduced in v0.2.0. The first plugin is `context-strategy-comparison`, which preserves the existing raw-full-file vs my-dev-kit-guided workflow through the plugin runner.
+The current package version is `v0.3.0` (release-prepared; not yet published to npm, tagged, or released on GitHub). The latest published npm baseline is `v0.2.2`. Its generic experiment-plugin framework was introduced in v0.2.0. The first plugin is `context-strategy-comparison`, which preserves the existing raw-full-file vs my-dev-kit-guided workflow through the plugin runner.
 
 my-dev-kit is most useful when the repository is larger than the task. It helps coding agents work with large codebases through reusable structural indexing, graph-guided retrieval, targeted source slices, and auditable context selection. Results are scoped evidence; the project does not claim that my-dev-kit always saves tokens.
 
@@ -32,6 +32,7 @@ my-dev-kit is most useful when the repository is larger than the task. It helps
 - Target-aware experiment execution for local projects via `experiment:run -- --target <path>`
 - Plugin-aware JSON and HTML reports with plugin, target, variant, metric, artifact, warning, skip, and failure metadata
 - Security validation framework: dependency audit, package tarball inspection, CLI adversarial tests, static scans (CodeQL/Semgrep), bounded fuzz smoke, attack-scenario checks, and structured verdict/report output — runnable against any local project via `security:validate --target <path>`
+- Generic audit framework (package.json now specifies version `v0.3.0`; release-prepared but not yet published to npm, tagged, or released on GitHub): `npm run audit` runs heuristic, conservative code-rot detectors and writes text/JSON reports under `reports/audits/code-rot/` by default. Only the `code-rot` audit type is currently implemented; `quality`, `security`, `project`, and `all` audit types are planned and fail cleanly instead of running. `npm run audit` supports `--target`, `--types code-rot`, and other flags — see [docs/COMMANDS.md](docs/COMMANDS.md). Audit does not modify target files, does not auto-fix issues, does not run `security:validate`, and does not perform release-readiness determination.
 
 ---
 
@@ -202,7 +203,7 @@ See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
 
 ## Current baseline release positioning
 
-my-dev-kit-lab is at a working baseline. The raw-vs-indexed experiment pipeline is fully implemented and produces reproducible artifacts. Real-agent campaign support exists for Codex and Claude. The current package version is `v0.2.2`, which implements the automated security-validation fortification work described below and has passed pre-release readiness and cross-platform validation. `v0.2.2` has not yet been published to npm.
+my-dev-kit-lab is at a working baseline. The raw-vs-indexed experiment pipeline is fully implemented and produces reproducible artifacts. Real-agent campaign support exists for Codex and Claude. The latest published npm baseline is `v0.2.2`, which implements the automated security-validation fortification work described below and has passed pre-release readiness and cross-platform validation. package.json now specifies version `v0.3.0`, which adds the generic audit framework described below; `v0.3.0` is release-prepared but has not yet been published to npm, tagged, or released on GitHub.
 
 ---
 

package/dist/scripts/audits/runAudit.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { parseAuditArgs, normalizeAuditConfig } from "../../src/audits/core/auditConfig.js";
+import { resolveAuditTarget } from "../../src/audits/core/auditTarget.js";
+import { runAudit } from "../../src/audits/core/auditRunner.js";
+import { AUDIT_EXIT_CODES } from "../../src/audits/core/auditExitCode.js";
+import { resolveToolRoot } from "../security/resolveToolRoot.js";
+import { buildAuditReportModel } from "../../src/audits/report/auditReportModel.js";
+import { writeAuditReports } from "../../src/audits/report/writeAuditReports.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 5 -- npm run audit entrypoint.
+//
+// Thin wiring only: parse args -> normalize config -> resolve target ->
+// runAudit() -> buildAuditReportModel() -> writeAuditReports() -> print a
+// concise console summary -> set process.exitCode. All report-shaping logic
+// (the former inline buildJsonReport()/renderMinimalTextSummary()/
+// summarizeInventory()/summarizeSourceOfTruth() functions from Batch 1/2)
+// now lives in src/audits/report/ -- see auditReportModel.ts,
+// renderAuditJsonReport.ts, renderAuditTextReport.ts, writeAuditReports.ts.
+// Mirrors the structure of scripts/security/validate.ts.
+// ---------------------------------------------------------------------------
+const USAGE = "Usage: npm run audit -- [--target <path>] [--types code-rot] " +
+    "[--include docs,tests,package,architecture,cli] [--format text,json] " +
+    "[--fail-on blocker|high|medium|low|none] [--out <path>]";
+const rawArgs = process.argv.slice(2);
+const toolRoot = resolveToolRoot(import.meta.url);
+let config;
+try {
+    const args = parseAuditArgs(rawArgs);
+    config = normalizeAuditConfig(args, toolRoot);
+}
+catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\nERROR: ${msg}`);
+    console.error(USAGE);
+    process.exitCode = AUDIT_EXIT_CODES.FATAL_ERROR;
+    process.exit(AUDIT_EXIT_CODES.FATAL_ERROR);
+}
+let target;
+try {
+    target = resolveAuditTarget(config.targetPathArg, toolRoot);
+}
+catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\nERROR: ${msg}`);
+    console.error(USAGE);
+    process.exitCode = AUDIT_EXIT_CODES.FATAL_ERROR;
+    process.exit(AUDIT_EXIT_CODES.FATAL_ERROR);
+}
+console.log("=".repeat(60));
+console.log("my-dev-kit-lab audit");
+console.log("=".repeat(60));
+console.log(`Tool root  : ${toolRoot}`);
+if (!target.isSelf) {
+    console.log(`Target     : ${target.rootPath}`);
+}
+else {
+    console.log(`Mode       : self-audit`);
+}
+console.log(`Types      : ${config.types.join(", ")}`);
+console.log(`Include    : ${config.include.join(", ")}`);
+console.log("");
+let result;
+try {
+    result = await runAudit({ config, toolRoot, target });
+}
+catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\nERROR: audit runtime failure: ${msg}`);
+    process.exitCode = AUDIT_EXIT_CODES.FATAL_ERROR;
+    process.exit(AUDIT_EXIT_CODES.FATAL_ERROR);
+}
+const model = buildAuditReportModel(result, { target });
+const { writtenPaths } = writeAuditReports({ model, config, outDir: config.out });
+console.log(`Issues found        : ${model.summary.totalIssues}`);
+console.log(`  blocker=${model.summary.issuesBySeverity.blocker} high=${model.summary.issuesBySeverity.high} medium=${model.summary.issuesBySeverity.medium} low=${model.summary.issuesBySeverity.low} info=${model.summary.issuesBySeverity.info}`);
+console.log(`Skipped detectors    : ${model.summary.skippedDetectorCount}`);
+if (model.summary.detectorErrorCount > 0) {
+    console.log(`Detector errors      : ${model.summary.detectorErrorCount}`);
+    for (const e of model.detectorErrors) {
+        console.log(`  [${e.id}] ${e.message}`);
+    }
+}
+if (model.summary.noDetectorsRegistered) {
+    console.log(`Note: no code-rot detectors are registered for this run's --types/--include selection -- this run collected inventory/source-of-truth data only.`);
+}
+console.log(`\nInventory: ${model.inventory.totalScannedFileCount} file(s) scanned, ${model.inventory.skippedFileCount} skipped`);
+console.log(`  source=${model.inventory.filesByCategory.source} tests=${model.inventory.filesByCategory.tests} docs=${model.inventory.filesByCategory.docs} package=${model.inventory.filesByCategory.package} config=${model.inventory.filesByCategory.config} scripts=${model.inventory.filesByCategory.scripts} ci=${model.inventory.filesByCategory.ci}`);
+console.log(`Source of truth: package=${model.sourceOfTruth.packageName ?? "(none)"}@${model.sourceOfTruth.packageVersion ?? "?"} readme=${model.sourceOfTruth.hasReadme} changelog=${model.sourceOfTruth.hasChangelog} ciWorkflows=${model.sourceOfTruth.ciWorkflowCount}`);
+if (writtenPaths.length > 0) {
+    console.log(`\nReports written:`);
+    for (const p of writtenPaths) {
+        console.log(`  ${p}`);
+    }
+}
+console.log(`\nHighest severity: ${model.summary.highestSeverity ?? "(none)"}`);
+console.log(`Verdict: ${model.summary.finalVerdictLabel}`);
+console.log(`Exit reason: ${model.exit.reason}`);
+console.log(model.exit.code === AUDIT_EXIT_CODES.SUCCESS
+    ? `Exit 0 -- audit completed.`
+    : `Exit 1 -- fail-on threshold breached.`);
+process.exitCode = model.exit.code;

package/dist/src/audits/codeRot/codeRotDetectors.js

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 3 — code-rot detector aggregator.
+//
+// Single import surface for src/audits/core/auditRegistry.ts's
+// DEFAULT_AUDIT_REGISTRY. Keeps the registry file from needing to know each
+// detector's individual file path.
+// ---------------------------------------------------------------------------
+export { STALE_COMMAND_REFERENCE_DETECTOR } from "./detectors/staleCommandReferenceDetector.js";
+export { DOCS_CODE_MISMATCH_DETECTOR } from "./detectors/docsCodeMismatchDetector.js";
+export { PACKAGE_RELEASE_ROT_DETECTOR } from "./detectors/packageReleaseRotDetector.js";
+export { DUPLICATE_IMPLEMENTATION_DETECTOR } from "./detectors/duplicateImplementationDetector.js";
+export { DEAD_CODE_CANDIDATE_DETECTOR } from "./detectors/deadCodeCandidateDetector.js";
+export { TEST_ROT_DETECTOR } from "./detectors/testRotDetector.js";
+export { ARCHITECTURE_DRIFT_DETECTOR } from "./detectors/architectureDriftDetector.js";
+export { DEPENDENCY_ENVIRONMENT_ROT_DETECTOR } from "./detectors/dependencyEnvironmentRotDetector.js";
+export { CROSS_PLATFORM_ROT_DETECTOR } from "./detectors/crossPlatformRotDetector.js";
+export { SECURITY_VALIDATION_ASSUMPTION_ROT_DETECTOR } from "./detectors/securityValidationAssumptionRotDetector.js";

package/dist/src/audits/codeRot/detectors/architectureDriftDetector.js

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import path from "node:path";
+import { currentClaimPatternFor } from "../utils/docClaimPatterns.js";
+import { readBoundedFileText } from "../utils/boundedRead.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — architecture drift detector.
+//
+// Deterministic path/claim checks only -- no semantic judgment. Two of the
+// checks below (stale/missing backtick path mentions, and the hardcoded
+// "audit framework described as planned while implemented" check) are
+// deliberately scoped to docs/ARCHITECTURE.md and docs/CURRENT_STATE.md
+// only, not every doc file. Both files' own headers state their purpose is
+// describing CURRENT implemented state ("This file is the concise source of
+// truth for the checked-in implementation" / "Current implemented
+// architecture"). docs/ROADMAP.md, by contrast, is full of legitimate
+// backtick-quoted "Suggested architecture" paths for genuinely
+// not-yet-built future work items -- scanning it with the same "does this
+// path exist" check would produce many false positives against accurate,
+// correctly-labeled-as-future roadmap content. Restricting scope keeps this
+// detector's signal high-confidence.
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "architecture-drift";
+const MAX_READ_BYTES = 200_000;
+const CURRENT_STATE_DOC_BASENAMES = new Set(["architecture.md", "current_state.md"]);
+const BACKTICK_SRC_PATH_PATTERN = /`(src\/[\w./-]+|scripts\/[\w./-]+)`/g;
+const HISTORICAL_FRAMING_PATTERN = /\b(historical|previously|used to|no longer|removed|deprecated)\b/i;
+const PLANNED_FRAMING_PATTERN = /\b(planned|future|roadmap|not (?:yet )?implemented)\b/i;
+const AUDIT_FRAMEWORK_SUBJECT_PATTERN = /\baudit (?:framework|contracts)\b|\bcode rot detector\b/i;
+const MIN_SOURCE_FILES_FOR_MAJOR_DIR = 3;
+export const ARCHITECTURE_DRIFT_DETECTOR = {
+    id: DETECTOR_ID,
+    auditType: "code-rot",
+    title: "Architecture drift",
+    description: "Detects deterministic drift between documentation and actual source layout: doc-claimed paths that don't exist, the audit framework described as planned while implemented, major source directories missing from ARCHITECTURE.md, and unhedged manual-pentest/Android implementation claims.",
+    supportedIncludeAreas: ["architecture", "docs", "package", "cli"],
+    shouldSkip: (ctx) => {
+        if (!ctx.config.include.includes("docs") && !ctx.config.include.includes("architecture")) {
+            return { skip: true, reason: "--include selects neither docs nor architecture; this detector's checks are docs-based." };
+        }
+        return { skip: false };
+    },
+    run: (ctx) => {
+        const issues = [];
+        const currentStateDocs = ctx.inventory.docsFiles.filter((f) => CURRENT_STATE_DOC_BASENAMES.has(path.basename(f.relativePath).toLowerCase()));
+        for (const docFile of currentStateDocs) {
+            const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+            if (content === null)
+                continue;
+            issues.push(...findStaleOrMissingBacktickPaths(ctx, docFile.relativePath, content));
+        }
+        issues.push(...findAuditFrameworkDescribedAsPlanned(ctx, currentStateDocs));
+        const architectureDoc = ctx.inventory.docsFiles.find((f) => path.basename(f.relativePath).toLowerCase() === "architecture.md");
+        if (architectureDoc) {
+            const content = readBoundedFileText(ctx.target.rootPath, architectureDoc.relativePath, architectureDoc.sizeBytes, MAX_READ_BYTES);
+            if (content !== null) {
+                issues.push(...findMajorDirsAbsentFromArchitectureDoc(ctx, architectureDoc.relativePath, content));
+            }
+        }
+        for (const docFile of ctx.inventory.docsFiles) {
+            const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+            if (content === null)
+                continue;
+            issues.push(...findUnsupportedCurrentClaims(docFile.relativePath, content));
+        }
+        return deduplicateIssuesById(issues);
+    },
+};
+function pathExistsInInventoryOrDisk(ctx, claimedPath) {
+    const trimmed = claimedPath.replace(/\/$/, "");
+    const inventoryHit = ctx.inventory.files.some((f) => f.relativePath === trimmed || f.relativePath.startsWith(`${trimmed}/`));
+    if (inventoryHit)
+        return true;
+    try {
+        return fs.existsSync(path.join(ctx.target.rootPath, trimmed));
+    }
+    catch {
+        return false;
+    }
+}
+function findStaleOrMissingBacktickPaths(ctx, docRelativePath, content) {
+    const issues = [];
+    const seen = new Set();
+    BACKTICK_SRC_PATH_PATTERN.lastIndex = 0;
+    for (const match of content.matchAll(BACKTICK_SRC_PATH_PATTERN)) {
+        const claimedPath = match[1];
+        if (seen.has(claimedPath))
+            continue;
+        seen.add(claimedPath);
+        if (pathExistsInInventoryOrDisk(ctx, claimedPath))
+            continue;
+        const matchIndex = match.index ?? 0;
+        const windowStart = Math.max(0, matchIndex - 200);
+        const windowEnd = Math.min(content.length, matchIndex + claimedPath.length + 200);
+        const window = content.slice(windowStart, windowEnd);
+        const isHistorical = HISTORICAL_FRAMING_PATTERN.test(window);
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [docRelativePath, isHistorical ? "stale-path-mention" : "claimed-path-missing", claimedPath],
+            title: isHistorical
+                ? `${docRelativePath} mentions a stale (historically-framed) path: "${claimedPath}"`
+                : `${docRelativePath} claims path "${claimedPath}" exists, but it does not`,
+            description: isHistorical
+                ? `${docRelativePath} mentions "${claimedPath}" with historical framing, and the path no longer exists on disk. Low-severity because it is explicitly framed as historical.`
+                : `${docRelativePath} references "${claimedPath}" as a current path (backtick code span), but no such file or directory exists in the project.`,
+            severity: isHistorical ? "low" : "medium",
+            confidence: isHistorical ? "medium" : "medium",
+            falsePositiveRisk: "medium",
+            category: "architecture-drift",
+            recommendedAction: isHistorical
+                ? `Confirm whether the historical reference to "${claimedPath}" is still useful context.`
+                : `Update ${docRelativePath} to reference an existing path, or restore/implement "${claimedPath}".`,
+            suggestedFixStrategy: `Correct or remove the "${claimedPath}" reference in ${docRelativePath}.`,
+            validationCommands: ["npm run audit -- --types code-rot --include architecture,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: "Backtick-quoted path does not exist on disk.",
+                    filePath: docRelativePath,
+                    excerpt: claimedPath,
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [docRelativePath],
+        }));
+    }
+    return issues;
+}
+function findAuditFrameworkDescribedAsPlanned(ctx, currentStateDocs) {
+    const auditImplemented = fs.existsSync(path.join(ctx.target.rootPath, "src", "audits")) && "audit" in (ctx.sourceOfTruth.package?.scripts ?? {});
+    if (!auditImplemented)
+        return [];
+    const issues = [];
+    for (const docFile of currentStateDocs) {
+        const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+        if (content === null)
+            continue;
+        AUDIT_FRAMEWORK_SUBJECT_PATTERN.lastIndex = 0;
+        const subjectMatch = AUDIT_FRAMEWORK_SUBJECT_PATTERN.exec(content);
+        if (!subjectMatch)
+            continue;
+        const matchIndex = subjectMatch.index;
+        const windowStart = Math.max(0, matchIndex - 400);
+        const windowEnd = Math.min(content.length, matchIndex + subjectMatch[0].length + 400);
+        const window = content.slice(windowStart, windowEnd);
+        if (!PLANNED_FRAMING_PATTERN.test(window))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [docFile.relativePath, "audit-framework-planned-but-implemented"],
+            title: `${docFile.relativePath} describes the audit framework as planned/future, but it is already implemented`,
+            description: `${docFile.relativePath} mentions "${subjectMatch[0]}" near planned/future/not-implemented wording, but src/audits exists and package.json defines an "audit" script -- the audit framework is already implemented, not merely planned.`,
+            severity: "high",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "architecture-drift",
+            recommendedAction: `Update ${docFile.relativePath} to describe the audit framework's actual current implementation status.`,
+            suggestedFixStrategy: `Move the audit-framework description in ${docFile.relativePath} out of the planned/future section.`,
+            validationCommands: ["npm run audit -- --types code-rot --include architecture,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: "Doc describes the audit framework as planned/future near this mention, but src/audits exists and an \"audit\" npm script is defined.",
+                    filePath: docFile.relativePath,
+                    excerpt: subjectMatch[0],
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [docFile.relativePath],
+        }));
+    }
+    return issues;
+}
+function findMajorDirsAbsentFromArchitectureDoc(ctx, docRelativePath, content) {
+    const countsByDir = new Map();
+    for (const file of ctx.inventory.sourceFiles) {
+        const parts = file.relativePath.split("/");
+        if (parts[0] !== "src" || parts.length < 3)
+            continue;
+        const dirName = parts[1];
+        countsByDir.set(dirName, (countsByDir.get(dirName) ?? 0) + 1);
+    }
+    const issues = [];
+    const sortedDirs = [...countsByDir.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [dirName, count] of sortedDirs) {
+        if (count < MIN_SOURCE_FILES_FOR_MAJOR_DIR)
+            continue;
+        if (content.includes(dirName))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [docRelativePath, "major-dir-absent-from-architecture-doc", dirName],
+            title: `Major implemented directory "src/${dirName}" is not mentioned in ${docRelativePath}`,
+            description: `"src/${dirName}" contains ${count} source files but is never mentioned in ${docRelativePath}.`,
+            severity: "medium",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "architecture-drift",
+            recommendedAction: `Add "src/${dirName}" to ${docRelativePath}'s module map.`,
+            suggestedFixStrategy: `Document the responsibility of "src/${dirName}" in ${docRelativePath}.`,
+            validationCommands: ["npm run audit -- --types code-rot --include architecture,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "observation",
+                    message: `"src/${dirName}" has ${count} source files and is not mentioned anywhere in ${docRelativePath}.`,
+                    filePath: docRelativePath,
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [docRelativePath],
+        }));
+    }
+    return issues;
+}
+function findUnsupportedCurrentClaims(docRelativePath, content) {
+    const issues = [];
+    const subjects = [
+        { id: "manual-pentest", label: "manual pentest", pattern: "manual pentest" },
+        { id: "android-validation", label: "Android/mobile validation", pattern: "(?:android (?:validation|support))" },
+    ];
+    for (const subject of subjects) {
+        const pattern = currentClaimPatternFor(subject.pattern);
+        const match = pattern.exec(content);
+        if (!match)
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [docRelativePath, "unsupported-current-claim", subject.id],
+            title: `${docRelativePath} claims "${subject.label}" is implemented/current`,
+            description: `${docRelativePath} contains an unhedged "${subject.label} is implemented/current" claim, but there is no corresponding source signal for this repo.`,
+            severity: "high",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "architecture-drift",
+            recommendedAction: `Confirm whether "${subject.label}" is actually implemented; if not, correct ${docRelativePath}.`,
+            suggestedFixStrategy: `Rephrase the "${subject.label}" claim in ${docRelativePath} to accurately reflect its planned status.`,
+            validationCommands: ["npm run audit -- --types code-rot --include architecture,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: `Matched an unhedged "${subject.label} is implemented/current" claim pattern.`,
+                    filePath: docRelativePath,
+                    excerpt: match[0].slice(0, 200),
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [docRelativePath],
+        }));
+    }
+    return issues;
+}

package/dist/src/audits/codeRot/detectors/crossPlatformRotDetector.js

@@ -0,0 +1,214 @@
+import { readBoundedFileText } from "../utils/boundedRead.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — cross-platform rot detector.
+//
+// Read-only with respect to the target project throughout -- never
+// modifies scripts or source. Bounded (per-file MAX_READ_BYTES skip).
+//
+// Simplification made after self-testing against this repo's own source:
+// the spec's ".split(\"/\")" raw-path-splitting sub-check was DROPPED. This
+// repo's own project inventory (src/audits/core/projectInventory.ts)
+// guarantees relativePath values are always forward-slash normalized, so
+// splitting an already-normalized relativePath on "/" (as several of this
+// batch's own new detector files legitimately do, e.g.
+// filePatternUtils.ts's firstTwoPathSegments()) is the correct, intentional
+// pattern here, not a cross-platform bug -- a bare regex cannot distinguish
+// that from a genuinely unsafe raw OS path split without semantic analysis.
+// The much narrower, high-signal ".split(\"\\\\\")" (raw double-backslash
+// Windows-style split) sub-check is kept, since that pattern has near-zero
+// legitimate use in this codebase.
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "cross-platform-rot";
+const MAX_READ_BYTES = 200_000;
+const WINDOWS_MENTION_PATTERN = /\bWindows\b/;
+const POSIX_ONLY_BINARY_PATTERN = /(^|&&)\s*(rm -rf|cp -r|mv |grep |sed |cat |find \.)/;
+const SPLIT_NEWLINE_LITERAL_PATTERN = /\.split\(\s*["']\\n["']\s*\)/g;
+const RAW_BACKSLASH_SPLIT_PATTERN = /\.split\(\s*["']\\\\["']\s*\)/g;
+const SHELL_TRUE_PATTERN = /shell:\s*true/;
+const EXEC_SPAWN_CALL_PATTERN = /\b(exec|spawn|execFile\w*|spawnSync|execSync|execFileSync)\s*\(/;
+export const CROSS_PLATFORM_ROT_DETECTOR = {
+    id: DETECTOR_ID,
+    auditType: "code-rot",
+    title: "Cross-platform rot",
+    description: "Detects POSIX-only shell syntax in npm scripts when Windows support is claimed, raw .split(\"\\n\") usage outside the canonical splitLines() helper, raw backslash path splitting, and exec/spawn calls with shell: true.",
+    supportedIncludeAreas: ["cli", "package", "docs", "tests"],
+    shouldSkip: (ctx) => {
+        if (!ctx.config.include.includes("cli") && !ctx.config.include.includes("package")) {
+            return { skip: true, reason: "--include selects neither cli nor package; this detector's checks are script/source-based." };
+        }
+        return { skip: false };
+    },
+    run: (ctx) => {
+        const issues = [];
+        const pkg = ctx.sourceOfTruth.package;
+        let docsClaimWindowsSupport = false;
+        if (ctx.config.include.includes("docs")) {
+            docsClaimWindowsSupport = docsClaimWindows(ctx);
+        }
+        if (ctx.config.include.includes("package") && pkg) {
+            issues.push(...findPosixOnlyScriptSyntax(pkg.scripts, docsClaimWindowsSupport));
+        }
+        if (ctx.config.include.includes("cli")) {
+            issues.push(...scanSourceFiles(ctx));
+        }
+        return deduplicateIssuesById(issues);
+    },
+};
+function docsClaimWindows(ctx) {
+    for (const docFile of ctx.inventory.docsFiles) {
+        const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+        if (content !== null && WINDOWS_MENTION_PATTERN.test(content))
+            return true;
+    }
+    return false;
+}
+function findPosixOnlyScriptSyntax(scripts, docsClaimWindowsSupport) {
+    const issues = [];
+    for (const [scriptName, command] of Object.entries(scripts)) {
+        const segments = command.split("&&").map((s) => s.trim());
+        for (const segment of segments) {
+            if (!POSIX_ONLY_BINARY_PATTERN.test(segment))
+                continue;
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: ["posix-only-script-syntax", scriptName],
+                title: `Script "${scriptName}" appears to use POSIX-only shell syntax`,
+                description: `package.json script "${scriptName}" contains a segment that looks like a bare POSIX shell command ("${segment.slice(0, 60)}"), which is not guaranteed to work on Windows without a POSIX shell shim.${docsClaimWindowsSupport ? " Docs explicitly claim Windows support." : ""}`,
+                severity: docsClaimWindowsSupport ? "high" : "medium",
+                confidence: "medium",
+                falsePositiveRisk: "medium",
+                category: "cross-platform-rot",
+                recommendedAction: "Replace the POSIX-only command with a cross-platform Node script or a guarded/portable equivalent.",
+                suggestedFixStrategy: `Rewrite the "${scriptName}" script segment to avoid relying on a POSIX-only shell binary.`,
+                validationCommands: [`npm run ${scriptName}`],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "reference",
+                        message: "Script command segment matches a bare POSIX-only shell binary pattern.",
+                        filePath: "package.json",
+                        excerpt: segment.slice(0, 200),
+                        source: DETECTOR_ID,
+                        confidence: "medium",
+                    },
+                ],
+                affectedFiles: ["package.json"],
+            }));
+        }
+    }
+    return issues;
+}
+function scanSourceFiles(ctx) {
+    const issues = [];
+    const auditSourceFiles = ctx.inventory.sourceFiles.filter((f) => f.relativePath.startsWith("src/audits/"));
+    for (const file of auditSourceFiles) {
+        if (path_basename(file.relativePath) === "textLines.ts")
+            continue; // canonical implementation, allowed
+        const content = readBoundedFileText(ctx.target.rootPath, file.relativePath, file.sizeBytes, MAX_READ_BYTES);
+        if (content === null)
+            continue;
+        SPLIT_NEWLINE_LITERAL_PATTERN.lastIndex = 0;
+        if (SPLIT_NEWLINE_LITERAL_PATTERN.test(content)) {
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [file.relativePath, "raw-split-newline"],
+                title: `"${file.relativePath}" uses raw .split("\\n") instead of the canonical splitLines() helper`,
+                description: `"${file.relativePath}" contains a raw ".split(\\"\\n\\")"/".split('\\n')" call. This project's own convention (see src/audits/codeRot/utils/textLines.ts) requires splitLines() for all doc/text line-splitting, because a bare split leaves a trailing "\\r" on every line for CRLF-authored files.`,
+                severity: "medium",
+                confidence: "high",
+                falsePositiveRisk: "low",
+                category: "cross-platform-rot",
+                recommendedAction: `Replace the raw .split("\\n") in "${file.relativePath}" with splitLines() from ../utils/textLines.js.`,
+                suggestedFixStrategy: `Import and use splitLines() in "${file.relativePath}".`,
+                validationCommands: ["npm run audit -- --types code-rot --include cli"],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: "Raw .split(\"\\n\") usage found outside the canonical splitLines() implementation.",
+                        filePath: file.relativePath,
+                        source: DETECTOR_ID,
+                        confidence: "high",
+                    },
+                ],
+                affectedFiles: [file.relativePath],
+            }));
+        }
+        RAW_BACKSLASH_SPLIT_PATTERN.lastIndex = 0;
+        if (RAW_BACKSLASH_SPLIT_PATTERN.test(content)) {
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [file.relativePath, "raw-backslash-split"],
+                title: `"${file.relativePath}" raw-splits a path on a literal backslash`,
+                description: `"${file.relativePath}" contains a raw backslash .split() call, which assumes Windows-style backslash separators and will silently fail to split forward-slash paths (e.g. on POSIX or already-normalized relative paths).`,
+                severity: "medium",
+                confidence: "medium",
+                falsePositiveRisk: "medium",
+                category: "cross-platform-rot",
+                recommendedAction: `Use path.sep/path.normalize or a forward-slash-normalized path representation instead of a raw backslash split in "${file.relativePath}".`,
+                suggestedFixStrategy: `Replace the raw backslash split in "${file.relativePath}" with a portable path-handling helper.`,
+                validationCommands: ["npm run audit -- --types code-rot --include cli"],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: "Raw backslash-splitting pattern found in source.",
+                        filePath: file.relativePath,
+                        source: DETECTOR_ID,
+                        confidence: "medium",
+                    },
+                ],
+                affectedFiles: [file.relativePath],
+            }));
+        }
+        SHELL_TRUE_PATTERN.lastIndex = 0;
+        const shellTrueMatch = SHELL_TRUE_PATTERN.exec(content);
+        if (shellTrueMatch && EXEC_SPAWN_CALL_PATTERN.test(nearbyWindow(content, shellTrueMatch.index))) {
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [file.relativePath, "shell-true-usage"],
+                title: `"${file.relativePath}" appears to invoke a subprocess with shell: true`,
+                description: `"${file.relativePath}" contains a "shell: true" option near an exec/spawn call. This is a known risk pattern (shell metacharacter injection via unsanitized arguments).`,
+                severity: "high",
+                confidence: "medium",
+                falsePositiveRisk: "medium",
+                category: "cross-platform-rot",
+                recommendedAction: `Remove "shell: true" and pass arguments as an array instead, in "${file.relativePath}".`,
+                suggestedFixStrategy: `Refactor the subprocess call in "${file.relativePath}" to avoid shell: true.`,
+                validationCommands: ["npm run audit -- --types code-rot --include cli"],
+                releaseBlocking: true,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: "shell: true found near an exec/spawn-family call.",
+                        filePath: file.relativePath,
+                        source: DETECTOR_ID,
+                        confidence: "medium",
+                    },
+                ],
+                affectedFiles: [file.relativePath],
+            }));
+        }
+    }
+    return issues;
+}
+function nearbyWindow(content, index, radius = 150) {
+    return content.slice(Math.max(0, index - radius), Math.min(content.length, index + radius));
+}
+function path_basename(relativePath) {
+    const idx = relativePath.lastIndexOf("/");
+    return idx === -1 ? relativePath : relativePath.slice(idx + 1);
+}