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

package/README.md

@@ -1,302 +1,27 @@
 # my-dev-kit-lab
 
-my-dev-kit-lab is the experiment, evidence, reporting, security-validation, and 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, performs automated CLI/package security validation, and runs the generic audit framework.
+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.
 
-The current published baseline is `v0.3.3`. `v0.3.0` introduced the generic audit framework and the first implemented code-rot detector family; `v0.3.1` added the language-aware code-rot substrate plus TypeScript/JavaScript support; `v0.3.2` added Python-aware code-rot support and a first security-validation audit adapter; `v0.3.3` adds Java/Kotlin source-facts support and JVM-aware code-rot detector integration. The 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.
+## Version state
 
-`v0.3.3` is the previously published npm baseline. Java/Kotlin support is conservative static analysis only: dependency-free scanners, static Gradle/Maven metadata detection, and no compiler, classpath, Gradle, Maven, Android, or target-test execution. `v0.3.4` is release-prepared in this repository: package metadata has been bumped to `0.3.4`, adding mixed-language stability coverage, repeated-run report hardening, cross-platform/path normalization tests, CRLF/LF stability checks, and final documentation reconciliation. `v0.3.4` is not yet published to npm, not tagged, and no GitHub release has been created — local Windows validation has passed and a latest-Node cross-platform workflow is configured for ubuntu/macos/windows, but a fresh remote multi-OS run should be verified during publication.
+`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.
 
-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.
-
-**my-dev-kit** is the repo indexing and graph-guided retrieval engine.
-**my-dev-kit-lab** is the separate lab layer that feeds it benchmark inputs and records evaluation outputs.
-
----
-
-## Current capabilities
-
-- Benchmark projects at small, medium, and large complexity levels
-- Project complexity metrics and benchmark case metadata with answer keys
-- Prompt variant generation at `short`, `medium`, `long`, and `multi-step` complexity levels
-- Fake-agent adapter for deterministic smoke and demo validation
-- Codex and Claude adapters for real-agent campaigns
-- Controlled experiment runner comparing `raw-full-file` vs `my-dev-kit-guided` strategies
-- Deterministic correctness scoring from answer keys
-- Token usage, duration, and status comparisons between matched strategy pairs
-- HTML experiment report rendering
-- Static SVG plot generation
-- Optional PNG screenshot capture
-- Gallery manifest and static gallery index output
-- Visualization demos using my-dev-kit commands against benchmark projects
-- Final demo workflow combining all pipeline stages
-- Generic experiment-plugin command surface: `experiment:list`, `experiment:describe`, and `experiment:run`
-- First experiment plugin: `context-strategy-comparison`
-- 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>`. `security:validate` remains the standalone, focused security-validation command; it is not replaced by the audit adapter below.
-- Generic audit framework, current published baseline: `npm run audit` runs heuristic, conservative code-rot detectors and writes text/JSON reports under `reports/audits/code-rot/` by default. `code-rot` and `security` are the currently implemented audit types (`--types code-rot`, `--types security`, or combined `--types code-rot,security`); `quality`, `project`, and `all` audit types are planned and fail cleanly instead of running. `npm run audit` supports `--target`, `--types`, and other flags — see [docs/COMMANDS.md](docs/COMMANDS.md). Audit does not modify target files and does not auto-fix issues.
-- Language-aware code-rot support, current published package state: normalized language/file-role inventory, a source-facts model and collector, TypeScript/JavaScript, Python, Java, and Kotlin analyzers, and conservative detector integrations for `dead-code-candidate`, `duplicate-implementation-candidate`, `test-rot`, and `docs-code-mismatch`. Python project metadata remains a top-level audit report field. Java/Kotlin support adds static JVM project metadata detection for Gradle/Maven/source-set shape and conservative source-facts evidence, but no compiler parsing, type resolution, classpath resolution, Gradle/Maven execution, Android validation, or target-project test execution. No `SourceFacts` schema change or new audit command was added for `v0.3.3`.
-- Security-validation audit adapter, current published package state: `npm run audit -- --types security` runs security validation through the shared audit/report surface by calling the same `runSecurityValidation()` internals `security:validate` uses, maps security findings into audit-issue-shaped entries, and adds a `securitySummary` field (verdict, check counts, finding counts, and links to the original `reports/security/*.txt`/`*.json` report) to audit JSON/text reports. `npm run audit -- --types code-rot,security` runs both audit types together. The original `security:validate` command and its `reports/security/` output are unchanged.
-- `v0.3.4` implementation state (release-prepared, not yet published): mixed-language fixture corpus, source-facts invariants, full-registry mixed-language detector stability tests, repeated-run audit report determinism checks, cross-platform/path normalization hardening, CRLF/LF parsing stability coverage, and final documentation reconciliation. Package metadata is bumped to `0.3.4`; it is not yet tagged or published.
-
----
-
-## Architecture overview
-
-```mermaid
-flowchart TD
-  A[scripts/experiments] --> B[Experiment plugin registry + runner]
-  B --> C[context-strategy-comparison]
-  C --> D[Controlled experiment foundations]
-  D --> E[Plugin + legacy artifacts]
-  E --> F[Plugin-aware reports]
-  E --> G[Plots / screenshots / gallery]
-  H[scripts/security] --> I[Automated security validation]
-  I --> J[Security reports + verdict]
-```
-
----
-
-## Quickstart
-
-### Install
-
-```bash
-npm install
-```
+## Android validation
 
 ```powershell
-npm install
-```
-
-`cmd.exe` users should run the same command on one line.
-
-### Build
-
-```bash
-npm run build
+npm run security:validate -- --target "<android-project-path>" --profile android
 ```
 
-### 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 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
-```
-
-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` |
-| 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` |
-
----
-
-## 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 baseline does not prove token savings are guaranteed; 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
-
----
-
-## 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 previously published npm baseline is `v0.3.3`, which added Java/Kotlin analyzers, JVM metadata detection, Java/Kotlin detector support, and Java/Kotlin/Gradle/Maven docs-code-mismatch checks on top of the published `v0.3.2` baseline.
-
-`v0.3.4` is release-prepared in this repository: package metadata has been bumped to `0.3.4`. It hardens the existing language-aware audit path with mixed-language fixture coverage, detector and report determinism checks, cross-platform/path normalization coverage, CRLF/LF stability coverage, and documentation reconciliation. It does not add a new command. It is not yet published, not tagged, and no GitHub release has been created.
-
-Planned roadmap direction after the previously published baseline:
-
-- `v0.3.3`: Java/Kotlin code-rot support (published)
-- `v0.3.4`: cross-language stability for the language-aware code-rot track (release-prepared in this checkout; not yet published)
-- `v0.4.0` through `v0.4.2`: Android automated security validation, including an Android-specific extension of the security audit adapter
-- manual pentest: post-v1 / version TBD
-
----
-
-## Security validation
-
-my-dev-kit-lab owns a release-security validation track for **my-dev-kit**. This work is separate from the experiment pipeline and does not replace the generic experiment-plugin roadmap. Its purpose is to generate release-validation evidence for the local CLI/package before release preparation.
-
-`security:validate` remains the standalone, focused command for this validation and is unaffected by the current checked-out state. `npm run audit -- --types security` additionally adapts the same `security:validate` internals into the shared audit/report surface (mapped issues, a `securitySummary` field, and links to the original `reports/security/` output) — it does not replace or duplicate `security:validate`'s own checks or reports.
-
-This is not a web application pentest framework. **my-dev-kit** is a local CLI/package, so the validation model is CLI/package adversarial testing focused on whether it remains:
-
-- local-first
-- deterministic
-- read-only with respect to user source files
-- network-free during normal CLI operation
-- LLM-free
-- database-free
-- safe to run on local repositories
-
-The automated validation gate is implemented. It combines static scans, dependency/package checks, adversarial CLI tests, bounded fuzz smoke tests, and attack-scenario checks with structured text/JSON reports and a four-category verdict.
-
-### Security commands
-
-| Command | Description |
-|---|---|
-| `npm run security:deps` | npm audit, OSV-Scanner (if available), outdated packages |
-| `npm run security:package` | npm pack --dry-run, forbidden content detection |
-| `npm run security:codeql` | CodeQL CLI availability check; skipped gracefully when absent |
-| `npm run security:semgrep` | Semgrep scan via local binary or npx; skipped gracefully when both absent |
-| `npm run test:security` | Automated security and adversarial CLI tests (path traversal, read-only boundaries, malformed artifacts, JSON safety, and related checks) |
-| `npm run test:fuzz:smoke` | 9 bounded fuzz targets, seeded PRNG, completes in under 1 second |
-| `npm run security:validate` | Runs selected security checks, applies profile-aware defaults when requested, and writes text/JSON reports according to `--format` |
-
-CodeQL, Semgrep, and OSV-Scanner are optional. When unavailable locally, they are recorded as `skipped` in the report, not as passed. That can lead to `ready except optional manual checks`; it does not silently turn missing tooling into a clean pass.
-
-Each security command can validate my-dev-kit-lab itself or another local project via `--target <path>`. When `--target` is omitted, the framework performs self-validation. Target projects are inspected in place: their source files are not modified by default, generated artifacts stay under `reports/security/` unless `--out` is used, and external-target reports identify the tool root, target root, target package metadata, target git metadata, command cwd, exit code, and stdout/stderr summaries.
-
-`security:validate` supports `--checks`, `--profile`, `--format`, `--fail-on`, `--out`, and `--report-prefix`. The no-flag path remains backward compatible and still runs the classic implemented check groups: `deps`, `package`, `static`, `cli-adversarial`, and `fuzz`. Supplying `--profile` without `--checks` swaps in that profile's default checks; supplying explicit `--checks` always wins over profile defaults.
-
-The current attack-scenario checks cover boundary, subprocess, secrets, and network assumptions. They are automated adversarial checks, not a manual pentest. Manual pentest is deferred until after `v1.0.0`. `verdictImpact` metadata from each registered scenario drives blocker categorization in report reasoning, and narrowed `--checks` runs are labeled as scoped rather than described as a full release gate.
-
-JSON report poisoning/config-injection checks use a baseline-diff schema guard so legitimate additive JSON fields do not fail the guard while payload-created trusted top-level fields still do. Text reports are sanitized to strip ANSI/control-byte payloads before rendering.
-
-Known limits remain intentionally explicit: secret scanning is bounded rather than exhaustive, the network/local-first check is a bounded static assumption check rather than proof of runtime isolation, package-boundary severity is still result-level rather than per-evidence-item, and profile-specific scenario behavior is limited to profile-based scenario selection/default checks.
-
-For external-target validation, `security:validate` reads the target `package.json`, detects `scripts.test:security`, and runs `npm run test:security` in the target project root when that script exists. This behavior is validated both from the source checkout and from an installed packed tarball because published-package execution differs from local source execution.
-
-Generated security reports under `reports/security/` are excluded from git by default. They are produced locally or in CI as release-gate evidence and are not committed to the repository.
-
-See [docs/COMMANDS.md](docs/COMMANDS.md) for full command options and [docs/security-validation-framework.md](docs/security-validation-framework.md) for the security model, implemented modules, and release verdicts.
-
----
-
-## 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.
+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.
 
-If this project helps your workflow, you can support continued development through GitHub Sponsors or PayPal:
+`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.
 
-- [Sponsor on GitHub](https://github.com/sponsors/dailephd)
-- [Support via PayPal](https://paypal.me/daile88)
+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.
 
-Support is optional and does not affect access to the project.
+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.
 
----
+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.
 
-## Documentation
+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.
 
-- [docs/PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md) — product purpose and target users
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — current and future architecture
-- [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) — current baseline and future phases
-- [docs/GALLERY.md](docs/GALLERY.md) — gallery output explained
+See [Project overview](docs/PROJECT_OVERVIEW.md), [Commands](docs/COMMANDS.md), [Workflows](docs/WORKFLOWS.md), [Architecture](docs/ARCHITECTURE.md), and [Roadmap](docs/ROADMAP.md).

package/dist/scripts/security/validate.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import path from "node:path";
 import { runSecurityValidation } from "../../src/securityValidation/validate/runSecurityValidation.js";
 import { resolveValidationTarget, reportFilenamePrefix } from "../../src/securityValidation/validate/resolveTarget.js";
 import { buildSecurityReportFromSummary } from "../../src/securityValidation/report/buildSecurityReport.js";
@@ -8,12 +9,53 @@ import { parseSecurityValidateArgs, normalizeSecurityValidateConfig, applyProfil
 import { resolveAttackProfile } from "../../src/securityValidation/attackScenarios/attackProfile.js";
 import { findingsBreachFailOnThreshold } from "../../src/securityValidation/validate/verdict.js";
 import { resolveToolRoot } from "./resolveToolRoot.js";
+import { validateAndroidTarget } from "../../src/mobile/android/validate/validateAndroidTarget.js";
+import { toAndroidReportModel } from "../../src/mobile/android/report/model.js";
+import { renderAndroidTextReport } from "../../src/mobile/android/report/renderAndroidReport.js";
+import { writeAndroidReportFiles } from "../../src/mobile/android/report/writeAndroidReportFiles.js";
 const USAGE = "Usage: npm run security:validate -- [--target <path>] [--out <dir>] [--report-prefix <name>] " +
     "[--checks deps,package,static,cli-adversarial,fuzz,boundary,subprocess,secrets,network] " +
-    "[--profile node-cli-package|local-tool|npm-package] [--format text,json] [--fail-on blocker|high|medium|low]";
+    "[--profile node-cli-package|local-tool|npm-package|android] [--format text,json] [--fail-on blocker|high|medium|low] " +
+    "[--android-gradle-operations wrapper-version,tasks,assemble-debug,unit-test-debug,lint-debug] " +
+    "[--android-external-tools semgrep,osv,android-lint,dependency-check] " +
+    "[--android-external-network deny|allow-requested]\n" +
+    "\n" +
+    "Android profile:\n" +
+    "  --profile android performs static, read-only Android project detection, manifest parsing,\n" +
+    "  permission/exported-component/intent-filter/deep-link audits, static Gradle metadata\n" +
+    "  extraction, and (as of v0.4.1 Batch 8) eleven internal advanced security checks (network\n" +
+    "  security config, backup/release configuration, hardcoded secrets, signing configuration,\n" +
+    "  WebView, FileProvider, sensitive storage/logging, clipboard, and Firebase/Google services).\n" +
+    "  Gradle and external tools are never executed by default.\n" +
+    "  --android-gradle-operations explicitly opts into running ONLY the listed allowlisted Gradle\n" +
+    "  operations (wrapper-version, tasks, assemble-debug, unit-test-debug, lint-debug) via the\n" +
+    "  project's own Gradle wrapper. Arbitrary Gradle tasks cannot be passed. This option is only\n" +
+    "  valid together with --profile android.\n" +
+    "  --android-external-tools explicitly opts into running ONLY the listed allowlisted optional\n" +
+    "  external security tools (semgrep, osv, android-lint, dependency-check). No arbitrary tool\n" +
+    "  names, commands, or arguments can be passed. This option is only valid together with\n" +
+    "  --profile android.\n" +
+    "  --android-external-network controls whether a requested tool may use network access.\n" +
+    "  Defaults to deny (osv is skipped unless supported offline data is available; semgrep,\n" +
+    "  android-lint, and dependency-check always run offline/no-update regardless of this flag).\n" +
+    "  allow-requested authorizes network only for an explicitly requested tool whose Batch 7\n" +
+    "  contract supports it (currently only osv). This option is only valid together with\n" +
+    "  --profile android.\n" +
+    "  Example: npm run security:validate -- --target \"<android-project-path>\" --profile android\n" +
+    "  Example: npm run security:validate -- --target \"<android-project-path>\" --profile android --android-gradle-operations wrapper-version,tasks\n" +
+    "  Example: npm run security:validate -- --target \"<android-project-path>\" --profile android --android-external-tools semgrep,android-lint\n" +
+    "  Example: npm run security:validate -- --target \"<android-project-path>\" --profile android --android-external-tools osv --android-external-network allow-requested";
 // Parse CLI arguments from process.argv (after the node/tsx and script path).
 const rawArgs = process.argv.slice(2);
 const toolRoot = resolveToolRoot(import.meta.url);
+// Help deliberately wins over every other argument. It must remain a
+// no-work path: no target/default resolution, option normalization, report
+// directory creation, validation orchestration, or subprocess execution.
+if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    console.log(USAGE);
+    process.exitCode = 0;
+    process.exit(0);
+}
 let args;
 let config;
 try {
@@ -22,15 +64,18 @@ try {
     // v0.2.2 Batch 5: --profile with no --checks uses that profile's declared
     // default checks. No-op unless the user passed --profile without --checks
     // (see applyProfileDefaultChecksIfApplicable's guard) — the true no-flag
-    // case and any explicit --checks case are always unaffected.
-    config = applyProfileDefaultChecksIfApplicable(config, resolveAttackProfile(config.profile).defaultCheckIds);
+    // case and any explicit --checks case are always unaffected. Skipped for
+    // "android": that profile does not use the classic --checks pipeline.
+    if (config.profile !== "android") {
+        config = applyProfileDefaultChecksIfApplicable(config, resolveAttackProfile(config.profile).defaultCheckIds);
+    }
 }
 catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`\nERROR: ${msg}`);
     console.error(USAGE);
-    process.exitCode = 1;
-    process.exit(1);
+    process.exitCode = 2;
+    process.exit(2);
 }
 // Resolve and validate target early so we can fail fast with a clean error.
 let target;
@@ -56,71 +101,166 @@ if (!target.isSelf) {
 else {
     console.log(`Mode       : self-validation`);
 }
-if (!config.checksWereDefault) {
-    console.log(`Checks     : ${config.checks.join(", ")}`);
-}
-if (config.plannedChecksRequested.length > 0) {
-    console.log(`Note       : ${config.plannedChecksRequested.join(", ")} are routed through the attack-scenario framework rather than the classic check-group runners. Review the attack-scenario section in the report for their concrete results.`);
-}
-console.log("");
-const summary = await runSecurityValidation({
-    cwd: toolRoot,
-    targetPath: args.target,
-    fuzzIterations: parseInt(process.env["FUZZ_ITERATIONS"] ?? "50", 10),
-    fuzzSeed: parseInt(process.env["FUZZ_SEED"] ?? "0xDEADBEEF", 16),
-    // Full selection (implemented + planned/attack-scenario ids) — the runner
-    // gates both implemented check groups and attack-scenario checks off the
-    // same selectedChecks set.
-    selectedChecks: config.checks,
-    profile: config.profile,
-});
-// v0.2.2 Batch 5: --fail-on breach is additive to (never a substitute for)
-// the existing verdict-based exit decision below — it can only escalate
-// exit 0 to exit 1 (e.g. --fail-on medium/low catching minor/informational
-// findings the verdict policy doesn't already treat as blocking), never
-// downgrade an existing blocker.
-const failOnBreached = findingsBreachFailOnThreshold(summary.findings, config.failOnThreshold);
-// Build report object
-const report = buildSecurityReportFromSummary(summary, {
-    profile: config.profile,
-    selectedChecks: config.checks,
-    failOnThreshold: config.failOnThreshold,
-    formats: config.formats,
-    failOnBreached,
-});
-const textReport = renderTextReport(report);
-// Determine output directory
-const reportsDir = config.out;
-// Determine report filename prefix
-const prefix = args.reportPrefix ?? reportFilenamePrefix(target);
-const { textPath: txtPath, jsonPath, writtenPaths } = writeSecurityReportFiles({
-    outDir: reportsDir,
-    prefix,
-    report,
-    formats: config.formats,
-});
-// Print report to stdout
-console.log(textReport);
-console.log(`\nReports written:`);
-for (const p of writtenPaths) {
-    console.log(`  ${p}`);
-}
-// Exit code based on verdict, escalated (never downgraded) by --fail-on.
-const blockerExists = summary.verdict === "not-ready-security-blocker-remains";
-const inconclusive = summary.verdict === "inconclusive-audit-environment-incomplete";
-if (blockerExists) {
-    console.error("\nExit 1 — security blocker remains.");
-    process.exitCode = 1;
-}
-else if (inconclusive) {
-    console.warn("\nExit 2 — audit environment incomplete.");
-    process.exitCode = 2;
-}
-else if (failOnBreached) {
-    console.error(`\nExit 1 — --fail-on ${config.failOnThreshold} threshold breached.`);
-    process.exitCode = 1;
+console.log(`Profile    : ${config.profile}`);
+// ---------------------------------------------------------------------------
+// v0.4.0 Batch 5 — Android profile path.
+//
+// A separate orchestrator (not the classic check-group/attack-scenario
+// pipeline below) because the Android check/finding/status vocabulary
+// established in Batches 1-4 does not fit SecurityCheckId/SecurityCheckResult.
+// Same command, same --profile flag, same reports/security/ output root.
+// ---------------------------------------------------------------------------
+if (config.profile === "android") {
+    if (config.androidGradleOperationIds.length > 0) {
+        console.log(`Gradle ops : ${config.androidGradleOperationIds.join(", ")} (explicitly requested — will execute via the target's Gradle wrapper)`);
+    }
+    else {
+        console.log(`Gradle ops : (none requested — static-only validation, zero Gradle process execution)`);
+    }
+    // v0.4.1 Batch 8 — external tools remain explicit opt-in, mirroring Gradle
+    // operations exactly. "allow-requested" (the CLI-facing value) maps to the
+    // Batch 7 dispatcher's "allow-for-requested-tool" network policy value.
+    const externalNetworkPolicy = config.androidExternalNetworkPolicy === "allow-requested" ? "allow-for-requested-tool" : "deny";
+    if (config.androidExternalToolIds.length > 0) {
+        console.log(`External   : ${config.androidExternalToolIds.join(", ")} (explicitly requested — network policy: ${config.androidExternalNetworkPolicy})`);
+    }
+    else {
+        console.log(`External   : (none requested — zero external-tool process execution)`);
+    }
+    console.log("");
+    const reportsDir = config.out;
+    let result;
+    try {
+        result = await validateAndroidTarget({
+            toolRoot,
+            targetPath: args.target,
+            requestedGradleOperationIds: config.androidGradleOperationIds,
+            requestedExternalToolIds: config.androidExternalToolIds,
+            externalNetworkPolicy: externalNetworkPolicy,
+            externalToolArtifactRoot: path.join(reportsDir, "external-tools"),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nERROR: Android validation failed to run: ${msg}`);
+        process.exitCode = 3;
+        process.exit(3);
+    }
+    const reportModel = toAndroidReportModel(result, {
+        profile: config.profile,
+        requestedGradleOperations: config.androidGradleOperationIds,
+        requestedExternalTools: config.androidExternalToolIds,
+        externalNetworkPolicy: config.androidExternalNetworkPolicy,
+    });
+    const textReport = renderAndroidTextReport(reportModel);
+    const prefix = args.reportPrefix ??
+        reportFilenamePrefix({
+            isSelf: result.target.local.isSelf,
+            packageName: result.target.local.packageName,
+            packageVersion: result.target.local.packageVersion,
+            targetRoot: result.target.local.targetRoot,
+        });
+    let writtenPaths;
+    try {
+        ({ writtenPaths } = writeAndroidReportFiles({ outDir: reportsDir, prefix, report: reportModel, formats: config.formats }));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nERROR: Failed to write Android report files: ${msg}`);
+        console.error("Validation completed but the report could not be written. The in-memory result was not persisted.");
+        process.exitCode = 4;
+        process.exit(4);
+    }
+    console.log(textReport);
+    console.log(`\nReports written:`);
+    for (const p of writtenPaths) {
+        console.log(`  ${p}`);
+    }
+    const blockerExists = result.verdict === "not-ready-security-blocker-remains";
+    const inconclusive = result.verdict === "inconclusive-audit-environment-incomplete";
+    if (blockerExists) {
+        console.error("\nExit 1 — security blocker remains.");
+        process.exitCode = 1;
+    }
+    else if (inconclusive) {
+        console.warn("\nExit 2 — android environment incomplete.");
+        process.exitCode = 2;
+    }
+    else {
+        console.log("\nExit 0 — validation completed.");
+        process.exitCode = 0;
+    }
 }
 else {
-    console.log("\nExit 0 — validation completed.");
-    process.exitCode = 0;
+    // ---------------------------------------------------------------------------
+    // Classic check-group/attack-scenario pipeline (unchanged from prior versions).
+    // ---------------------------------------------------------------------------
+    if (!config.checksWereDefault) {
+        console.log(`Checks     : ${config.checks.join(", ")}`);
+    }
+    if (config.plannedChecksRequested.length > 0) {
+        console.log(`Note       : ${config.plannedChecksRequested.join(", ")} are routed through the attack-scenario framework rather than the classic check-group runners. Review the attack-scenario section in the report for their concrete results.`);
+    }
+    console.log("");
+    const summary = await runSecurityValidation({
+        cwd: toolRoot,
+        targetPath: args.target,
+        fuzzIterations: parseInt(process.env["FUZZ_ITERATIONS"] ?? "50", 10),
+        fuzzSeed: parseInt(process.env["FUZZ_SEED"] ?? "0xDEADBEEF", 16),
+        // Full selection (implemented + planned/attack-scenario ids) — the runner
+        // gates both implemented check groups and attack-scenario checks off the
+        // same selectedChecks set.
+        selectedChecks: config.checks,
+        profile: config.profile,
+    });
+    // v0.2.2 Batch 5: --fail-on breach is additive to (never a substitute for)
+    // the existing verdict-based exit decision below — it can only escalate
+    // exit 0 to exit 1 (e.g. --fail-on medium/low catching minor/informational
+    // findings the verdict policy doesn't already treat as blocking), never
+    // downgrade an existing blocker.
+    const failOnBreached = findingsBreachFailOnThreshold(summary.findings, config.failOnThreshold);
+    // Build report object
+    const report = buildSecurityReportFromSummary(summary, {
+        profile: config.profile,
+        selectedChecks: config.checks,
+        failOnThreshold: config.failOnThreshold,
+        formats: config.formats,
+        failOnBreached,
+    });
+    const textReport = renderTextReport(report);
+    // Determine output directory
+    const reportsDir = config.out;
+    // Determine report filename prefix
+    const prefix = args.reportPrefix ?? reportFilenamePrefix(target);
+    const { writtenPaths } = writeSecurityReportFiles({
+        outDir: reportsDir,
+        prefix,
+        report,
+        formats: config.formats,
+    });
+    // Print report to stdout
+    console.log(textReport);
+    console.log(`\nReports written:`);
+    for (const p of writtenPaths) {
+        console.log(`  ${p}`);
+    }
+    // Exit code based on verdict, escalated (never downgraded) by --fail-on.
+    const blockerExists = summary.verdict === "not-ready-security-blocker-remains";
+    const inconclusive = summary.verdict === "inconclusive-audit-environment-incomplete";
+    if (blockerExists) {
+        console.error("\nExit 1 — security blocker remains.");
+        process.exitCode = 1;
+    }
+    else if (inconclusive) {
+        console.warn("\nExit 2 — audit environment incomplete.");
+        process.exitCode = 2;
+    }
+    else if (failOnBreached) {
+        console.error(`\nExit 1 — --fail-on ${config.failOnThreshold} threshold breached.`);
+        process.exitCode = 1;
+    }
+    else {
+        console.log("\nExit 0 — validation completed.");
+        process.exitCode = 0;
+    }
 }