@dailephd/my-dev-kit-lab 0.4.1 → 0.4.3

package/README.md

@@ -1,27 +1,210 @@
 # my-dev-kit-lab
 
-my-dev-kit-lab is the experiment, evidence, reporting, visualization, audit, and security-validation companion for my-dev-kit. It provides controlled retrieval experiments, deterministic demonstrations, reports, plots, galleries, generic audits, and local security-validation workflows.
+my-dev-kit-lab is the experiment, audit, and evidence companion for [my-dev-kit](https://www.npmjs.com/package/@dailephd/my-dev-kit). It helps users compare repository-context strategies, audit project health, validate CLI/package and Android security boundaries, and turn each run into reviewable reports and visual artifacts.
 
-## Version state
+my-dev-kit provides local repository indexing and graph-guided retrieval. my-dev-kit-lab supplies the controlled benchmarks, agent adapters, metrics, security checks, and reports needed to evaluate when that retrieval is useful. Results are evidence for a specific target and configuration; they do not guarantee token savings or security.
 
-`v0.4.1` is the published baseline, with the advanced Android implementation released. `v0.4.0` is the previous published baseline. `v0.4.2` remains future work.
+The latest published release is v0.4.3 (stage-specific bounded-context and workflow-instruction evaluation). See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md).
 
-## Android validation
+## Current capabilities
+
+- **Run context-strategy experiments:** compare `raw-full-file` with `my-dev-kit-guided` using deterministic fixtures or locally configured Codex and Claude CLIs.
+- **Audit repository health:** run conservative code-rot detectors for TypeScript/JavaScript, Python, Java, and Kotlin, or adapt security findings into the common audit report.
+- **Validate CLI/package security:** inspect dependencies, package contents, path and subprocess boundaries, malformed inputs, optional static scanners, and bounded fuzz targets.
+- **Validate Android projects:** run nineteen static checks by default, with Gradle operations, external tools, and network access available only through explicit opt-in flags.
+- **Review evidence:** generate JSON and HTML reports, SVG plots, optional screenshots, visualization demos, and a static gallery.
+- **Evaluate stage-context strategies:** compare the two legacy strategies against six additional bounded stage-context strategies — `architecture-context-only`, `architecture-plus-implementation-refresh`, `architecture-plus-implementation-and-test-refresh`, `full-workflow-library`, `bounded-workflow-instruction-packet`, and `combined-bounded-stage-context` — selected through programmatic configuration, not CLI flags. Each strategy's evidence is reported through bounded `report.json`, `report.html`, and `report.txt` output with an explicit `available`/`unavailable`/`not-applicable` metric-availability model and no composite score, grade, ranking, or winning strategy.
+
+## Quickstart
+
+### Install
+
+```bash
+npm install
+```
+
+The same command works in PowerShell and `cmd.exe`.
+
+### Build
+
+```bash
+npm run build
+```
+
+### Verify the installation
+
+```bash
+npm run verify
+```
+
+### Run the fake-agent final demo (deterministic, no external CLIs required)
+
+```bash
+npm run run-final-demo -- \
+  --cases examples/token-savings-cases.json \
+  --out lab-output/final-demo \
+  --kit-command "node tests/fixtures/fake-my-dev-kit-cli.js" \
+  --agents fake-agent \
+  --complexities short \
+  --no-screenshot
+```
+
+```powershell
+npm run run-final-demo -- `
+  --cases examples/token-savings-cases.json `
+  --out lab-output/final-demo `
+  --kit-command "node tests/fixtures/fake-my-dev-kit-cli.js" `
+  --agents fake-agent `
+  --complexities short `
+  --no-screenshot
+```
+
+```bat
+npm run run-final-demo -- --cases examples/token-savings-cases.json --out lab-output/final-demo --kit-command "node tests/fixtures/fake-my-dev-kit-cli.js" --agents fake-agent --complexities short --no-screenshot
+```
+
+The lab resolves Windows `.cmd` and `.ps1` CLI shims, supports command paths with spaces, and keeps generated artifacts inside the requested output directory.
+
+This runs a full pipeline: controlled experiment → report → plots → visualization demos → gallery.
+
+### Run a real-agent campaign (requires Codex or Claude CLI)
+
+```bash
+npm run run-controlled-experiment -- \
+  --cases examples/real-agent-campaign-cases.json \
+  --agents codex,claude \
+  --strategies raw-full-file,my-dev-kit-guided \
+  --complexities medium,multi-step \
+  --out lab-output/real-agent-campaign \
+  --include-real-agents \
+  --continue-on-failure \
+  --timeout-ms 240000
+```
+
+Real-agent runs require local Codex or Claude CLI setup and available usage capacity. Runs that time out, produce invalid output, or hit session limits are recorded as structured outcomes rather than failures.
+
+### List, describe, and run experiment plugins
+
+```bash
+npm run experiment:list
+npm run experiment:describe -- --experiment context-strategy-comparison
+npm run experiment:run -- \
+  --experiment context-strategy-comparison \
+  --target /path/to/local/project \
+  --agents fake-agent \
+  --complexities short \
+  --no-screenshot
+```
 
 ```powershell
-npm run security:validate -- --target "<android-project-path>" --profile android
+npm run experiment:list
+npm run experiment:describe -- --experiment context-strategy-comparison
+npm run experiment:run -- `
+  --experiment context-strategy-comparison `
+  --target "Z:\Users\newuser\Projects\my-dev-kit-v1" `
+  --agents fake-agent `
+  --complexities short `
+  --no-screenshot
 ```
 
-The default Android profile runs nineteen checks: the original eight checks plus eleven advanced internal checks for Network Security Config, backup/data extraction, release configuration, secret candidates, signing configuration, WebView, FileProvider, sensitive storage, sensitive logging, clipboard, and Firebase/Google services. It runs zero Gradle operations, zero external tools, and zero network operations by default.
+When `--target` is omitted, the experiment runs in self mode against my-dev-kit-lab. When `--target <path>` is provided, the lab remains the tool root and the target project is inspected separately. Generated experiment outputs stay under lab-controlled output directories by default, not inside the target project.
+
+---
+
+## Where to find outputs
+
+| Artifact | Location |
+|---|---|
+| Experiment summary | `lab-output/<experiment>/experiment-summary.json` |
+| All runs | `lab-output/<experiment>/experiment-runs.json` |
+| Strategy comparisons | `lab-output/<experiment>/experiment-comparisons.json` |
+| HTML report | `lab-output/<report>/experiment-report.html` |
+| Report JSON | `lab-output/<report>/experiment-report.json` |
+| Report screenshot | `lab-output/<report>/experiment-report.png` |
+| Plugin experiment report JSON | `lab-output/experiments/<plugin>/<target>/<run>/report.json` |
+| Plugin experiment report HTML | `lab-output/experiments/<plugin>/<target>/<run>/report.html` |
+| Plugin experiment report text | `lab-output/experiments/<plugin>/<target>/<run>/report.txt` |
+| Plot data | `lab-output/<plots>/plot-data.json` |
+| SVG charts | `lab-output/<plots>/charts/*.svg` |
+| Gallery manifest | `lab-output/<gallery>/gallery-manifest.json` |
+| Gallery index | `lab-output/<gallery>/gallery-index.html` |
+| Audit reports | `reports/audits/<type>/code-rot-audit.txt` and `.json` |
+| Security reports | `reports/security/<prefix>-security-validation.txt` and `.json` |
+
+---
+
+## How to read the main report
+
+Open `experiment-report.html` in a browser. The report shows:
+
+- **Project profile** — benchmark project name, language mix, complexity score, and file tree
+- **Benchmark tasks** — task descriptions and answer keys
+- **Strategy comparisons** — paired `raw-full-file` vs `my-dev-kit-guided` runs per case
+- **Correctness scores** — deterministic answer-key scoring (not semantic LLM judging)
+- **Token usage** — estimated or reported token totals per run
+- **Token savings** — positive means my-dev-kit used fewer tokens; negative means it used more
+- **Duration** — wall-clock time per run
+- **Status** — completed, timeout, invalid-output, or limit-reached
+- **Warnings and limitations** — notes on missing token totals or partial results
+
+See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
+
+---
+
+## Current limitations
+
+- Token savings shown in fake-agent runs are based on estimated character counts, not provider billing telemetry
+- Claude does not expose token totals; token savings comparisons are unavailable for Claude runs
+- Codex may expose token totals but can produce timeouts or invalid-output runs
+- Small projects may make raw-full-file cheaper than my-dev-kit-guided; larger localized tasks are where my-dev-kit is expected to become more useful
+- The generic experiment-plugin framework currently ships one plugin, `context-strategy-comparison`; future plugins such as warm-index reuse, incremental-change, and context-window scaling are not implemented yet
+- The current release does not guarantee token savings; it produces auditable evidence for specific cases, targets, agents, and strategies
+- Provider telemetry dashboards, semantic LLM judging, and cloud API billing integration are not yet implemented
+- The six new stage-context strategies have no CLI flags yet, are configured programmatically, and do not yet include plots, screenshots, or gallery integration
+- The published upstream artifacts the stage-context strategies read do not expose considered-but-unselected reads or unnecessary-read evidence; those metrics report `unavailable` rather than zero
+
+---
+
+## Security validation
+
+`npm run security:validate` is the standalone security-validation command. It checks local CLI/package boundaries and can inspect another local project with `--target <path>`. The generic audit command can reuse those results through `--types security`, but it does not replace the standalone validator or its reports.
+
+Android validation uses `--profile android`. Its default path is static and non-destructive: it starts zero Gradle processes, zero external tools, and zero network operations. Only confirmed `SecurityFinding` records can become audit issues; Android `CandidateEvidence` remains review-only evidence.
+
+Optional scanners are reported as `skipped` when unavailable, never as passed. The framework does not provide runtime isolation proof, device or APK/AAB analysis, signing verification, Play Console validation, automatic fixes, or manual pentesting. Manual pentest remains deferred until post-v1/version TBD.
+
+See [COMMANDS.md](docs/COMMANDS.md) for exact syntax and [Security Validation Framework](docs/security-validation-framework.md) for checks, evidence semantics, verdicts, and limitations.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for the full text.
+
+---
+
+## Support
+
+my-dev-kit-lab is an independent project by dailephd LLC, developed and maintained by Dai Le.
 
-`SecurityFinding` records confirmed conservative evidence. `CandidateEvidence` remains separate review or unresolved evidence and is not a confirmed vulnerability. Text and JSON reports under `reports/security/` include advanced-security checks, external-tool results, candidate-evidence summaries, artifacts, mutation evidence, verdict reasons, and limitations.
+If this project helps your workflow, you can support continued development through GitHub Sponsors or PayPal:
 
-Optional Gradle operations use `--android-gradle-operations` and only accept `wrapper-version`, `tasks`, `assemble-debug`, `unit-test-debug`, and `lint-debug`. They are environment-dependent, record mutations, and never perform cleanup or arbitrary tasks.
+- [Sponsor on GitHub](https://github.com/sponsors/dailephd)
+- [Support via PayPal](https://paypal.me/daile88)
 
-Optional external tools use `--android-external-tools semgrep,osv,android-lint,dependency-check`. Network defaults to `--android-external-network deny`; `allow-requested` authorizes only requested supported network-capable tools. Semgrep uses package-owned local rules, Android Lint reuses the closed offline Gradle path, Dependency-Check disables updates, and OSV requires explicit network authorization. Tools are never installed automatically; unavailable requested tools are skipped or inconclusive, not clean passes.
+Support is optional and does not affect access to the project.
 
-Verdicts are `not-ready-security-blocker-remains`, `inconclusive-audit-environment-incomplete`, `ready-except-optional-manual-checks`, and `ready-for-release-preparation`. They are evidence states, not runtime, Play, publication, or pentest guarantees.
+---
 
-Selected local references such as supported `@xml` resources are resolved conservatively. Manifests are not merged, full overlay precedence and Gradle evaluation are not implemented, whole-program flow is not performed, and APK/AAB, signing, emulator/device, remote Firebase, live Play policy, and manual pentest validation remain outside scope.
+## Documentation
 
-See [Project overview](docs/PROJECT_OVERVIEW.md), [Commands](docs/COMMANDS.md), [Workflows](docs/WORKFLOWS.md), [Architecture](docs/ARCHITECTURE.md), and [Roadmap](docs/ROADMAP.md).
+- [docs/PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md) — product purpose and target users
+- [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) — implemented, planned, validated, blocked, and next state
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — current components, ownership, flows, and invariants
+- [docs/WORKFLOWS.md](docs/WORKFLOWS.md) — step-by-step workflows with diagrams
+- [docs/COMMANDS.md](docs/COMMANDS.md) — all commands with options and examples
+- [docs/TUTORIAL.md](docs/TUTORIAL.md) — first-run walkthrough
+- [docs/METRICS.md](docs/METRICS.md) — metric definitions and interpretation
+- [docs/ROADMAP.md](docs/ROADMAP.md) — versioned plans, dependencies, exclusions, and acceptance criteria
+- [docs/GALLERY.md](docs/GALLERY.md) — gallery output explained
+- [docs/security-validation-framework.md](docs/security-validation-framework.md) — security evidence, verdicts, and safety boundaries

package/benchmarks/contracts/todo-behavior.md

@@ -66,5 +66,5 @@ Answer key requirements:
 - `answerKey.expectedFiles` lists files a correct answer may need to cite
 - `answerKey.expectedSymbols` lists relevant symbols
 - `answerKey.expectedFacts` lists weighted facts with unique `id`, `text`, `weight`, and `required`
-- `answerKey.minimumCorrectFacts` defines the future scoring threshold, but scoring is not implemented in this prompt
+- `answerKey.minimumCorrectFacts` defines the required-fact threshold used by deterministic correctness scoring
 - optional `forbiddenWrongClaims` records claims that should be penalized by a later correctness scorer

package/benchmarks/projects/task-analytics-large-mixed/README.md

@@ -1 +1,3 @@
+# task-analytics-large-mixed
+
 Mixed TypeScript and Python benchmark project for deterministic task analytics, quality labeling, and report generation.

package/benchmarks/projects/task-workflow-medium-ts/README.md

@@ -1 +1,3 @@
-Task workflow benchmark project with multiple services, validation rules, filtering, summarization, and deterministic imports.
+# task-workflow-medium-ts
+
+TypeScript task-workflow benchmark with multiple services, validation rules, filtering, summarization, and deterministic imports.

package/dist/scripts/audits/runAudit.js

@@ -20,9 +20,29 @@ import { writeAuditReports } from "../../src/audits/report/writeAuditReports.js"
 // ---------------------------------------------------------------------------
 const USAGE = "Usage: npm run audit -- [--target <path>] [--types code-rot,security] " +
     "[--include docs,tests,package,architecture,cli] [--format text,json] " +
-    "[--fail-on blocker|high|medium|low|none] [--out <path>]";
+    "[--fail-on blocker|high|medium|low|none] [--out <path>] [--android]\n" +
+    "\n" +
+    "  --android opts into Batch 2's programmatic Android security integration.\n" +
+    "  Requires --types to include \"security\" (e.g. --types security or --types\n" +
+    "  code-rot,security). Runs the same static, read-only, nineteen-check\n" +
+    "  Android validation security:validate --profile android performs --\n" +
+    "  detection, manifest parsing, and internal advanced security checks --\n" +
+    "  through the existing security adapter, never a subprocess. Confirmed\n" +
+    "  findings are mapped into the normal issue collection; CandidateEvidence\n" +
+    "  remains a separate, bounded summary and is never treated as a confirmed\n" +
+    "  issue. Starts zero Gradle operations, zero external tools, and zero\n" +
+    "  network operations by default; --android does not expose any of those.\n" +
+    "  Example: npm run audit -- --target \"<android-project-path>\" --types security --android --format text,json --fail-on none";
 const rawArgs = process.argv.slice(2);
 const toolRoot = resolveToolRoot(import.meta.url);
+// Help deliberately wins over every other argument, mirroring
+// scripts/security/validate.ts -- no config normalization, target
+// resolution, audit execution, or report write.
+if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    console.log(USAGE);
+    process.exitCode = 0;
+    process.exit(0);
+}
 let config;
 try {
     const args = parseAuditArgs(rawArgs);
@@ -89,6 +109,13 @@ if (model.securitySummary.ran) {
         console.log(`  Full report: ${model.securitySummary.reportPaths.text}`);
     }
 }
+if (model.androidSecurity.summary.requested) {
+    const android = model.androidSecurity.summary;
+    console.log(`\nAndroid security validation: status=${android.status} applicable=${android.applicable ?? "n/a"} verdict=${android.verdict ?? "(unknown)"} checks=${android.totalChecks} confirmed=${android.confirmedFindingCount} mappedIssues=${android.mappedIssueCount} candidates=${android.candidateSummary.totalCount}`);
+    if (android.reportPaths.text) {
+        console.log(`  Full report: ${android.reportPaths.text}`);
+    }
+}
 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}`);

package/dist/src/audits/core/auditConfig.js

@@ -8,10 +8,19 @@ const FLAGS_WITH_VALUE = {
     "--fail-on": "failOn",
     "--out": "out",
 };
+// v0.4.2 Batch 3 -- presence-only flags (no following value consumed).
+const BOOLEAN_FLAGS = {
+    "--android": "android",
+};
 export function parseAuditArgs(argv) {
     const result = {};
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        const booleanKey = BOOLEAN_FLAGS[arg];
+        if (booleanKey) {
+            result[booleanKey] = true;
+            continue;
+        }
         const key = FLAGS_WITH_VALUE[arg];
         if (!key)
             continue;
@@ -28,6 +37,10 @@ export function normalizeAuditConfig(raw, toolRoot) {
     const formats = parseFormatOption(raw.format);
     const failOn = parseFailOnOption(raw.failOn);
     const out = raw.out !== undefined ? resolveOutDir(raw.out) : defaultOutDir(toolRoot, types.value);
+    const android = raw.android === true;
+    if (android && !types.value.includes("security")) {
+        throw new Error(`Invalid combination: --android requires --types to include "security" (e.g. --types security or --types code-rot,security).`);
+    }
     return {
         targetPathArg: raw.target,
         targetMode: raw.target === undefined ? "self" : "external",
@@ -46,7 +59,9 @@ export function normalizeAuditConfig(raw, toolRoot) {
             raw.include === undefined &&
             raw.format === undefined &&
             raw.failOn === undefined &&
-            raw.out === undefined,
+            raw.out === undefined &&
+            raw.android === undefined,
+        android,
     };
 }
 function splitAndNormalizeList(raw, flagName) {

package/dist/src/audits/core/auditRunner.js

@@ -6,7 +6,7 @@ import { collectSourceOfTruth } from "./sourceOfTruth.js";
 import { collectSourceFacts } from "./collectSourceFacts.js";
 import { collectPythonProjectMetadata } from "./pythonProjectMetadata.js";
 import { runSecurityAuditAdapter } from "../security/securityAuditAdapter.js";
-import { SECURITY_AUDIT_NOT_RUN_SUMMARY } from "../security/securityAuditTypes.js";
+import { ANDROID_AUDIT_NOT_REQUESTED_SUMMARY, SECURITY_AUDIT_NOT_RUN_SUMMARY, } from "../security/securityAuditTypes.js";
 export async function runAudit(options) {
     const { config, toolRoot } = options;
     const registry = options.registry ?? DEFAULT_AUDIT_REGISTRY;
@@ -49,10 +49,12 @@ export async function runAudit(options) {
     // code-rot detector issues (registry order) first, then security findings
     // (security-validation check-execution order).
     let securitySummary = SECURITY_AUDIT_NOT_RUN_SUMMARY;
+    let androidSummary = ANDROID_AUDIT_NOT_REQUESTED_SUMMARY;
     if (config.types.includes("security")) {
-        const securityAudit = await runSecurityAuditAdapter({ toolRoot, config });
+        const securityAudit = await runSecurityAuditAdapter({ toolRoot, config, android: config.android ? { enabled: true } : undefined }, options.securityDependencies);
         issues.push(...securityAudit.issues);
         securitySummary = securityAudit.summary;
+        androidSummary = securityAudit.android;
     }
     const issueCounts = countIssuesBySeverity(issues);
     const { exitCode, reason } = calculateAuditExitCode(issues, config.failOn);
@@ -64,6 +66,7 @@ export async function runAudit(options) {
             failOn: config.failOn,
             out: config.out,
             isDefaultRun: config.isDefaultRun,
+            android: config.android,
         },
         targetSummary: {
             rootPath: target.rootPath,
@@ -81,6 +84,7 @@ export async function runAudit(options) {
         sourceFacts,
         pythonProjectMetadata,
         securitySummary,
+        androidSummary,
         noDetectorsRegistered: selected.length === 0,
     };
 }

package/dist/src/audits/report/auditReportModel.js

@@ -166,6 +166,7 @@ export function buildAuditReportModel(result, opts) {
             failOn: result.configSummary.failOn,
             out: result.configSummary.out,
             isDefaultRun: result.configSummary.isDefaultRun,
+            android: result.configSummary.android,
         },
         summary: {
             totalIssues: issues.length,
@@ -191,6 +192,10 @@ export function buildAuditReportModel(result, opts) {
         sourceFacts: summarizeSourceFacts(result.sourceFacts),
         pythonProjectMetadata: result.pythonProjectMetadata,
         securitySummary: result.securitySummary,
+        androidSecurity: {
+            summary: result.androidSummary,
+            candidates: result.androidSummary.candidateSummary,
+        },
         detectors,
         issues,
         skippedDetectors: result.skippedDetectors,
@@ -252,5 +257,7 @@ function reconstructCommand(result) {
         parts.push("--format", cfg.formats.join(","));
     parts.push("--fail-on", cfg.failOn);
     parts.push("--out", cfg.out);
+    if (cfg.android)
+        parts.push("--android");
     return parts.join(" ");
 }

package/dist/src/audits/report/renderAuditJsonReport.js

@@ -21,6 +21,7 @@ export function renderAuditJsonReport(model) {
         sourceFacts: model.sourceFacts,
         pythonProjectMetadata: model.pythonProjectMetadata,
         securitySummary: model.securitySummary,
+        androidSecurity: model.androidSecurity,
         detectors: model.detectors,
         issues: model.issues,
         skippedDetectors: model.skippedDetectors,

package/dist/src/audits/report/renderAuditTextReport.js

@@ -133,6 +133,43 @@ export function renderAuditTextReport(model) {
         }
     }
     lines.push("");
+    // v0.4.2 Batch 3 -- bounded summary only, mirroring the "Security
+    // validation summary" section above exactly. Confirmed mapped Android
+    // findings are NOT re-listed here -- they already appear in the "Issues"
+    // section below like any other AuditIssue (see spec section 12: "the
+    // existing generic issues section remains the detailed presentation for
+    // confirmed mapped Android findings"). CandidateEvidence bodies never
+    // appear here either -- only counts, with a pointer to the full Android
+    // report for detail.
+    lines.push("Android security validation summary");
+    lines.push(divider("-"));
+    if (!model.androidSecurity.summary.requested) {
+        lines.push("  (not requested -- add --android alongside --types security to include it)");
+    }
+    else {
+        const android = model.androidSecurity.summary;
+        const candidates = model.androidSecurity.candidates;
+        const applicabilityNote = android.applicable === false ? " (target is not an Android project)" : "";
+        lines.push(`  Status: ${android.status}${applicabilityNote}`);
+        lines.push(`  Verdict: ${android.verdict ?? "(unknown)"}`);
+        lines.push(`  Checks: total=${android.totalChecks} passed=${android.passedChecks} withFindings=${android.checksWithFindings} candidateOnly=${android.candidateOnlyChecks} skipped=${android.skippedChecks} inconclusive=${android.inconclusiveChecks} failed=${android.failedChecks}`);
+        lines.push(`  Findings: confirmed=${android.confirmedFindingCount} mappedIssues=${android.mappedIssueCount}`);
+        lines.push(`  Candidates (review evidence, not confirmed vulnerabilities): total=${candidates.totalCount} checksWithCandidates=${candidates.checksWithCandidates}`);
+        if (android.warnings.length > 0) {
+            lines.push(`  Warnings: ${android.warnings.length}`);
+        }
+        if (android.errors.length > 0) {
+            lines.push(`  Errors: ${android.errors.length}`);
+            for (const e of android.errors.slice(0, 5)) {
+                lines.push(`    ${sanitizeLine(e)}`);
+            }
+        }
+        if (android.reportPaths.text || android.reportPaths.json) {
+            lines.push(`  Full report: ${android.reportPaths.text ?? "(none)"} / ${android.reportPaths.json ?? "(none)"}`);
+        }
+        lines.push("  Static analysis only -- does not prove runtime behavior, APK/AAB validity, Play compliance, or pentest results.");
+    }
+    lines.push("");
     lines.push("Issue summary");
     lines.push(divider("-"));
     lines.push(`  Total issues: ${model.summary.totalIssues}`);

package/dist/src/audits/security/androidAuditIntegration.js

@@ -0,0 +1,145 @@
+import path from "node:path";
+import { validateAndroidTarget } from "../../mobile/android/validate/validateAndroidTarget.js";
+import { toAndroidReportModel } from "../../mobile/android/report/model.js";
+import { writeAndroidReportFiles } from "../../mobile/android/report/writeAndroidReportFiles.js";
+import { reportFilenamePrefix } from "../../securityValidation/validate/resolveTarget.js";
+import { mapAndroidSecurityFindingToAuditIssue } from "./mapAndroidSecurityFindingToAuditIssue.js";
+import { ANDROID_AUDIT_NOT_REQUESTED_SUMMARY, EMPTY_ANDROID_AUDIT_CANDIDATE_SUMMARY, } from "./securityAuditTypes.js";
+const ANDROID_REPORT_SUBDIR = "android";
+// Bounded, redacted — never the thrown value's stack, never raw child-process
+// output (there is none at this boundary; validateAndroidTarget itself never
+// spawns a process unless Gradle/external-tool options are requested, which
+// Batch 2 never supplies).
+const MAX_ANDROID_ERROR_MESSAGE_LENGTH = 500;
+function boundErrorMessage(message) {
+    return message.length <= MAX_ANDROID_ERROR_MESSAGE_LENGTH
+        ? message
+        : `${message.slice(0, MAX_ANDROID_ERROR_MESSAGE_LENGTH)}... [truncated, ${message.length} chars total]`;
+}
+function failedSummary(errorMessage) {
+    return {
+        ...ANDROID_AUDIT_NOT_REQUESTED_SUMMARY,
+        requested: true,
+        applicable: null,
+        status: "failed",
+        errors: [boundErrorMessage(errorMessage)],
+    };
+}
+// Exact-duplicate dedupe by AuditIssue id only, first occurrence wins —
+// mirrors validateAndroidTarget's own findingsById convention. Iterates
+// checks in their own fixed order (never re-sorted) and each check's own
+// findings in their own order — never the top-level, already-flattened
+// result.findings, which has lost per-check identity this mapper needs as
+// context. Exported standalone so aggregation correctness (ordering,
+// dedup, provenance) can be tested against small literal AndroidCheckResult
+// fixtures without needing a full AndroidValidationResult.
+export function aggregateAndroidIssues(checks, reportReference) {
+    const issuesById = new Map();
+    for (const check of checks) {
+        for (const finding of check.findings) {
+            const issue = mapAndroidSecurityFindingToAuditIssue(finding, {
+                checkId: check.id,
+                checkCategory: check.category,
+                checkConfidence: check.confidence,
+                reportReference,
+            });
+            if (!issuesById.has(issue.id)) {
+                issuesById.set(issue.id, issue);
+            }
+        }
+    }
+    return [...issuesById.values()];
+}
+export function buildCandidateSummary(checks) {
+    const byConfidence = { ...EMPTY_ANDROID_AUDIT_CANDIDATE_SUMMARY.byConfidence };
+    const byResolutionState = { ...EMPTY_ANDROID_AUDIT_CANDIDATE_SUMMARY.byResolutionState };
+    const byCategory = {};
+    let totalCount = 0;
+    let checksWithCandidates = 0;
+    for (const check of checks) {
+        const candidates = check.candidateEvidence ?? [];
+        if (candidates.length === 0)
+            continue;
+        checksWithCandidates += 1;
+        for (const candidate of candidates) {
+            totalCount += 1;
+            byConfidence[candidate.confidence] += 1;
+            byResolutionState[candidate.resolutionState] += 1;
+            byCategory[candidate.category] = (byCategory[candidate.category] ?? 0) + 1;
+        }
+    }
+    // Deterministic key order regardless of check/candidate traversal order.
+    const sortedByCategory = Object.fromEntries(Object.entries(byCategory).sort(([a], [b]) => a.localeCompare(b)));
+    return { totalCount, checksWithCandidates, byConfidence, byResolutionState, byCategory: sortedByCategory };
+}
+export async function runAndroidAuditIntegration(options) {
+    const runAndroidValidation = options.runAndroidValidation ?? validateAndroidTarget;
+    let result;
+    try {
+        result = await runAndroidValidation({
+            toolRoot: options.toolRoot,
+            targetPath: options.targetPathArg,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { issues: [], summary: failedSummary(`Android validation failed to run: ${message}`) };
+    }
+    const isApplicable = result.detection.projectKind !== "non-android";
+    const reportModel = toAndroidReportModel(result, { profile: "android" });
+    const reportDir = path.join(options.toolRoot, "reports", "security", ANDROID_REPORT_SUBDIR);
+    const prefix = reportFilenamePrefix({
+        isSelf: result.target.local.isSelf,
+        packageName: result.target.local.packageName,
+        packageVersion: result.target.local.packageVersion,
+        targetRoot: result.target.local.targetRoot,
+    });
+    let reportPaths;
+    let writeErrors = [];
+    try {
+        const written = writeAndroidReportFiles({ outDir: reportDir, prefix, report: reportModel, formats: ["text", "json"] });
+        reportPaths = { text: written.textPath, json: written.jsonPath };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        reportPaths = { text: null, json: null };
+        writeErrors = [boundErrorMessage(`Failed to write Android report files: ${message}`)];
+    }
+    const issues = aggregateAndroidIssues(result.checks, reportPaths);
+    const passedChecks = result.checks.filter((c) => c.status === "passed").length;
+    const skippedChecks = result.checks.filter((c) => c.status === "skipped").length;
+    const inconclusiveChecks = result.checks.filter((c) => c.status === "inconclusive").length;
+    const failedChecks = result.checks.filter((c) => c.status === "failed" || c.status === "error").length;
+    const checksWithFindings = result.checks.filter((c) => c.findings.length > 0).length;
+    const candidateOnlyChecks = result.checks.filter((c) => c.findings.length === 0 && (c.candidateEvidence?.length ?? 0) > 0).length;
+    const candidateEvidenceCount = result.checks.reduce((sum, c) => sum + (c.candidateEvidence?.length ?? 0), 0);
+    const summary = {
+        requested: true,
+        applicable: isApplicable,
+        status: "completed",
+        verdict: result.verdict,
+        totalChecks: result.checks.length,
+        passedChecks,
+        checksWithFindings,
+        candidateOnlyChecks,
+        skippedChecks,
+        inconclusiveChecks,
+        failedChecks,
+        confirmedFindingCount: result.findings.length,
+        mappedIssueCount: issues.length,
+        candidateEvidenceCount,
+        // No Gradle/external-tool programmatic passthrough exists yet in Batch 2
+        // (see securityAuditTypes.ts's AndroidAuditSummary comment) — the default
+        // request always executes zero of either.
+        requestedGradleOperationCount: 0,
+        executedGradleOperationCount: 0,
+        requestedExternalToolCount: 0,
+        executedExternalToolCount: 0,
+        skippedExternalToolCount: 0,
+        reportPaths,
+        warnings: result.warnings,
+        errors: [...result.errors, ...writeErrors],
+        candidateSummary: buildCandidateSummary(result.checks),
+    };
+    return { issues, summary };
+}