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

package/README.md

@@ -1,302 +1,78 @@
 # 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, and security-validation companion for my-dev-kit. It provides controlled raw-full-file versus graph-guided retrieval experiments, deterministic fake-agent demonstrations, reports, plots, gallery artifacts, 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.
-
-`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.
-
-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.
-
----
+The current published baseline is `v0.3.4`. The v0.4.0 Android validation implementation is release-prepared on `release/v0.4.0`; publication is pending. It is not published, and the npm registry latest version remains `0.3.4`.
 
 ## 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]
-```
-
----
+- Controlled experiment plugins, reports, plots, screenshots, and gallery artifacts.
+- Generic code-rot and general security audit types through `npm run audit`.
+- Standalone CLI/package security validation through `npm run security:validate`.
+- Android security validation through the canonical `android` profile on the v0.4.0 feature branch.
 
-## Quickstart
+## Android validation
 
-### Install
-
-```bash
-npm install
-```
+Run static Android validation with:
 
 ```powershell
-npm install
+npm run security:validate -- --target "<android-project-path>" --profile android
 ```
 
-`cmd.exe` users should run the same command on one line.
-
-### Build
+This default path executes **no Gradle commands**. It detects/classifies Android projects and UI evidence, parses discovered manifests independently, audits permissions/exported components/intent filters/deep links, extracts static Gradle metadata, assembles release metadata and Play-readiness placeholders, calculates an Android verdict, and writes bounded text and JSON reports.
 
-```bash
-npm run build
-```
-
-### Verify the installation
-
-```bash
-npm run verify
-```
+Reports use the existing `reports/security/` root unless `--out` is supplied. Android report files use the `<prefix>-android-security-validation.txt` and `.json` convention.
 
-### 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
-```
+Optional Gradle validation is explicit:
 
 ```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
+npm run security:validate -- --target "<android-project-path>" --profile android --android-gradle-operations wrapper-version,tasks
 ```
 
-```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 only allowed operation IDs are:
 
-The lab resolves Windows `.cmd` and `.ps1` CLI shims, supports command paths with spaces, and keeps generated artifacts inside the requested output directory.
+- `wrapper-version`
+- `tasks`
+- `assemble-debug`
+- `unit-test-debug`
+- `lint-debug`
 
-This runs a full pipeline: controlled experiment → report → plots → visualization demos → gallery.
+Unknown or empty lists, arbitrary tasks, and use with a non-Android profile are rejected. Optional operations can require Java, Android SDK components, wrapper distributions, and cached dependencies; environment gaps can produce skipped or inconclusive evidence.
 
-### Run a real-agent campaign (requires Codex or Claude CLI)
+### Verdicts
 
-```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
-```
+- `not-ready-security-blocker-remains`: a blocker remains.
+- `inconclusive-audit-environment-incomplete`: required evidence/environment is incomplete.
+- `ready-except-optional-manual-checks`: advisory or manual follow-up remains.
+- `ready-for-release-preparation`: required static evidence passed.
 
-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.
+These are validation-evidence states, not claims that an app is published, Play-ready, Play-compliant, runtime-secure, or signing-valid.
 
-### List, describe, and run experiment plugins
+### Important Android limitations
 
-```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
-```
+- Static analysis does not prove runtime behavior.
+- Manifests are not merged; placeholders and resource references are not resolved.
+- Gradle scripts are not evaluated; dynamic metadata can stay unresolved; same-file duplicate assignment extraction uses the first match.
+- Optional Gradle execution is disabled by default and environment-dependent.
+- APK/AAB contents, signing, emulator/device behavior, Digital Asset Links, domain ownership, and live Google Play policy are not validated.
+- Play Console items such as privacy policy, Data Safety, permissions declarations, store listing, release notes, content rating, and policy review remain manual placeholders.
+
+## Development
 
 ```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
+npm run typecheck
+npm run build
+npm run test
+npm run verify
 ```
 
-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.
-
-If this project helps your workflow, you can support continued development through GitHub Sponsors or PayPal:
-
-- [Sponsor on GitHub](https://github.com/sponsors/dailephd)
-- [Support via PayPal](https://paypal.me/daile88)
-
-Support is optional and does not affect access to the project.
+Use `npm run security:validate -- --help` for command usage. Help does not run validation or write reports.
 
----
+## Roadmap status
 
-## Documentation
+- `v0.4.0`: Android validation MVP — release-prepared; publication pending.
+- `v0.4.1`: planned advanced Android security checks.
+- `v0.4.2`: planned Android extension of the existing security audit adapter; it will not replace `security:validate`.
+- Manual pentest: deferred post-v1 / version TBD; not part of v0.4.x.
 
-- [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 [docs/PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md), [docs/COMMANDS.md](docs/COMMANDS.md), [docs/WORKFLOWS.md](docs/WORKFLOWS.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), and [docs/ROADMAP.md](docs/ROADMAP.md).

package/dist/scripts/security/validate.js

@@ -8,12 +8,36 @@ 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]\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, and static Gradle metadata\n" +
+    "  extraction. Gradle is 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" +
+    "  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";
 // 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 +46,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 +83,151 @@ 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)`);
+    }
+    console.log("");
+    let result;
+    try {
+        result = await validateAndroidTarget({
+            toolRoot,
+            targetPath: args.target,
+            requestedGradleOperationIds: config.androidGradleOperationIds,
+        });
+    }
+    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,
+    });
+    const textReport = renderAndroidTextReport(reportModel);
+    const reportsDir = config.out;
+    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;
+    }
 }