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

package/dist/src/mobile/android/report/renderAndroidReport.js

@@ -0,0 +1,286 @@
+import { stripUnsafeControlChars } from "../../../securityValidation/attackScenarios/exploitEvidence.js";
+// ---------------------------------------------------------------------------
+// v0.4.0 Batch 5 — Android text report rendering (agents.txt Batch 5 section
+// 15.4). Mirrors the section structure and defensive text-sanitization
+// convention of src/securityValidation/report/renderSecurityReport.ts
+// (stripUnsafeControlChars guards against ANSI/control-byte report
+// poisoning from scanned manifest/Gradle content).
+// ---------------------------------------------------------------------------
+function divider(char = "-", width = 72) {
+    return char.repeat(width);
+}
+function sanitize(raw) {
+    return stripUnsafeControlChars(raw);
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+// v0.4.1 Batch 8 — shared per-check rendering for the new ADVANCED SECURITY
+// CHECKS and EXTERNAL TOOL RESULTS sections. Bounded: prints counts and
+// identifiers, never raw stdout/stderr/environment/complete source (that
+// bound is already enforced by each check builder before evidence reaches
+// this report — this function does not itself receive raw tool output).
+function renderCheckSummaryLines(lines, c) {
+    lines.push(`  ${c.id} [${c.status}] — ${sanitize(c.title)}`);
+    lines.push(`    category: ${c.category}  findings: ${c.findings.length}  candidates: ${c.candidateEvidence?.length ?? 0}`);
+    if (c.evidence.length > 0)
+        lines.push(`    evidence: ${c.evidence.map(sanitize).join(" | ")}`);
+    if (c.durationMs !== undefined)
+        lines.push(`    duration: ${formatDuration(c.durationMs)}`);
+    if (c.skipInfo)
+        lines.push(`    skip reason: ${sanitize(c.skipInfo.reason)}`);
+    for (const w of c.warnings)
+        lines.push(`    warning: ${sanitize(w)}`);
+    for (const e of c.errors)
+        lines.push(`    error: ${sanitize(e)}`);
+    if (c.environmentRequirements.length > 0)
+        lines.push(`    limitations: ${c.environmentRequirements.map(sanitize).join(" | ")}`);
+}
+export function renderAndroidTextReport(model) {
+    const lines = [];
+    // 1. Summary
+    lines.push(divider("="));
+    lines.push("ANDROID SECURITY-VALIDATION SUMMARY");
+    lines.push(divider("="));
+    lines.push(sanitize(model.executiveSummary));
+    lines.push(`Profile        : ${model.metadata.profile}`);
+    lines.push(`Target         : ${model.metadata.target.local.targetRoot}`);
+    lines.push(`Tool           : ${model.metadata.tool.toolPackageName}@${model.metadata.tool.toolPackageVersion}`);
+    lines.push(`Generated      : ${model.metadata.generatedAt}`);
+    lines.push(`Duration       : ${formatDuration(model.metadata.totalDurationMs)}`);
+    lines.push("");
+    // 2-3. Verdict and reasons
+    lines.push(divider());
+    lines.push("VERDICT");
+    lines.push(divider());
+    lines.push(`Verdict: ${model.verdict} (${model.verdictHumanLabel})`);
+    lines.push(`Next step: ${sanitize(model.recommendedNextStep)}`);
+    if (model.verdictReasons.length > 0) {
+        lines.push("");
+        lines.push("Verdict reasons:");
+        for (const r of model.verdictReasons) {
+            lines.push(`  [${r.impact}] ${r.code}: ${sanitize(r.summary)}`);
+            lines.push(`    -> ${sanitize(r.recommendedAction)}`);
+        }
+    }
+    lines.push("");
+    // 4. Target identity
+    lines.push(divider());
+    lines.push("TARGET IDENTITY");
+    lines.push(divider());
+    lines.push(`Target root    : ${model.metadata.target.local.targetRoot}`);
+    lines.push(`Tool root      : ${model.metadata.target.local.toolRoot}`);
+    lines.push(`Package        : ${model.metadata.target.local.packageName ?? "(unknown)"}`);
+    lines.push(`Git branch     : ${model.metadata.target.local.branch ?? "(unavailable)"}`);
+    lines.push(`Git commit     : ${model.metadata.target.local.commit ?? "(unavailable)"}`);
+    lines.push("");
+    // 5-6. Classification
+    lines.push(divider());
+    lines.push("ANDROID PROJECT CLASSIFICATION");
+    lines.push(divider());
+    lines.push(`${model.detectionSummary.title}: ${model.detectionSummary.summary}`);
+    lines.push(`${model.androidProjectSummary.title}: ${model.androidProjectSummary.summary}`);
+    lines.push(`${model.uiToolkitSummary.title}: ${model.uiToolkitSummary.summary}`);
+    lines.push("");
+    // 7. Module summary
+    lines.push(divider());
+    lines.push("MODULE SUMMARY");
+    lines.push(divider());
+    if (model.moduleSummary.length === 0) {
+        lines.push("(no modules detected)");
+    }
+    else {
+        for (const m of model.moduleSummary) {
+            lines.push(`  ${m.path.padEnd(30)} kind=${m.kind.padEnd(12)} uiToolkit=${m.uiToolkit ?? "uncertain"}`);
+        }
+    }
+    lines.push("");
+    // 8. Environment and execution summary
+    lines.push(divider());
+    lines.push("ENVIRONMENT AND EXECUTION SUMMARY");
+    lines.push(divider());
+    lines.push(`Requested Gradle operations: ${model.metadata.requestedGradleOperations.length > 0 ? model.metadata.requestedGradleOperations.join(", ") : "(none — static-only validation, no Gradle process executed)"}`);
+    if (model.environmentLimitations.length > 0) {
+        for (const note of model.environmentLimitations)
+            lines.push(`  - ${sanitize(note)}`);
+    }
+    lines.push("");
+    // 9-13. Manifest / permissions / components / intent-filters / deep-links
+    lines.push(divider());
+    lines.push("MANIFEST SUMMARY");
+    lines.push(divider());
+    lines.push(sanitize(model.manifestSummary.summary));
+    lines.push("");
+    lines.push(divider());
+    lines.push("PERMISSIONS SUMMARY");
+    lines.push(divider());
+    lines.push(sanitize(model.permissionsSummary.summary));
+    lines.push("");
+    lines.push(divider());
+    lines.push("EXPORTED COMPONENT SUMMARY");
+    lines.push(divider());
+    lines.push(sanitize(model.componentSummary.summary));
+    lines.push("");
+    lines.push(divider());
+    lines.push("INTENT-FILTER SUMMARY");
+    lines.push(divider());
+    lines.push(sanitize(model.intentFilterSummary.summary));
+    lines.push("");
+    lines.push(divider());
+    lines.push("DEEP-LINK SUMMARY");
+    lines.push(divider());
+    lines.push(sanitize(model.deepLinkSummary.summary));
+    lines.push("");
+    // 14. Static Gradle metadata
+    lines.push(divider());
+    lines.push("STATIC GRADLE METADATA");
+    lines.push(divider());
+    lines.push(sanitize(model.gradleMetadataSummary.summary));
+    if (model.gradleCheckSummary)
+        lines.push(sanitize(model.gradleCheckSummary.summary));
+    lines.push("");
+    // 15. Optional Gradle operation results
+    lines.push(divider());
+    lines.push("OPTIONAL GRADLE OPERATION RESULTS");
+    lines.push(divider());
+    if (model.gradleOperationResults.length === 0) {
+        lines.push("No optional Gradle operations were requested — zero Gradle processes executed.");
+    }
+    else {
+        for (const op of model.gradleOperationResults) {
+            lines.push(`  ${op.id} — status=${op.status} ran=${op.ran}`);
+            if (op.command) {
+                lines.push(`    command: ${sanitize(op.command.command)} ${op.command.args.map(sanitize).join(" ")}`);
+                lines.push(`    cwd: ${op.command.cwd}  exitCode: ${op.command.exitCode ?? "null"}  timedOut: ${op.command.timedOut}`);
+            }
+            if (op.durationMs !== undefined)
+                lines.push(`    duration: ${formatDuration(op.durationMs)}`);
+            if (op.skipInfo)
+                lines.push(`    skip reason: ${sanitize(op.skipInfo.reason)}`);
+            for (const w of op.warnings)
+                lines.push(`    warning: ${sanitize(w)}`);
+        }
+    }
+    lines.push("");
+    // 15b. Advanced security checks (v0.4.1 Batch 8)
+    lines.push(divider());
+    lines.push("ADVANCED SECURITY CHECKS");
+    lines.push(divider());
+    if (model.advancedSecurityChecks.length === 0) {
+        lines.push("(none ran — not applicable to this target)");
+    }
+    else {
+        for (const c of model.advancedSecurityChecks) {
+            renderCheckSummaryLines(lines, c);
+        }
+    }
+    lines.push("");
+    // 15c. External tool results (v0.4.1 Batch 8)
+    lines.push(divider());
+    lines.push("EXTERNAL TOOL RESULTS");
+    lines.push(divider());
+    lines.push(`Requested external tools: ${model.metadata.requestedExternalTools.length > 0 ? model.metadata.requestedExternalTools.join(", ") : "(none — zero external-tool process execution)"}`);
+    if (model.metadata.requestedExternalTools.length > 0) {
+        lines.push(`Effective network policy: ${model.metadata.externalNetworkPolicy}`);
+    }
+    if (model.externalToolChecks.length === 0) {
+        lines.push("No external tools were requested.");
+    }
+    else {
+        for (const c of model.externalToolChecks) {
+            renderCheckSummaryLines(lines, c);
+        }
+    }
+    lines.push("");
+    // 15d. Candidate evidence (review required, distinct from confirmed findings)
+    lines.push(divider());
+    lines.push("CANDIDATE EVIDENCE (REVIEW REQUIRED — NOT CONFIRMED FINDINGS)");
+    lines.push(divider());
+    lines.push(sanitize(model.candidateEvidenceSummary.summary));
+    for (const c of [...model.advancedSecurityChecks, ...model.externalToolChecks]) {
+        for (const candidate of c.candidateEvidence ?? []) {
+            lines.push(`  [${candidate.confidence}/${candidate.resolutionState}] ${candidate.ruleId} — ${sanitize(candidate.summary)}`);
+            lines.push(`    location: ${candidate.location.path}${candidate.location.line !== undefined ? `:${candidate.location.line}` : ""}`);
+        }
+    }
+    lines.push("");
+    // 16. Release metadata
+    lines.push(divider());
+    lines.push("RELEASE METADATA");
+    lines.push(divider());
+    lines.push(sanitize(model.releaseMetadataSummary.summary));
+    lines.push("");
+    // 17. Play-readiness checklist
+    lines.push(divider());
+    lines.push("PLAY-READINESS CHECKLIST PLACEHOLDERS");
+    lines.push(divider());
+    lines.push(sanitize(model.playReadinessSummary.summary));
+    for (const item of model.playReadinessItems) {
+        lines.push(`  [${item.status}] ${item.title}: ${sanitize(item.detail)}`);
+    }
+    lines.push("");
+    // 18. Findings grouped by severity
+    lines.push(divider());
+    lines.push("FINDINGS BY SEVERITY");
+    lines.push(divider());
+    const severityOrder = ["blocker", "major", "minor", "informational"];
+    let anyFindings = false;
+    for (const severity of severityOrder) {
+        const findings = model.findingsBySeverity[severity];
+        if (!findings || findings.length === 0)
+            continue;
+        anyFindings = true;
+        lines.push(`${severity.toUpperCase()} (${findings.length}):`);
+        for (const f of findings) {
+            lines.push(`  [${f.id}] ${sanitize(f.title)}`);
+            lines.push(`    category: ${f.category}`);
+            if (f.affectedFiles && f.affectedFiles.length > 0)
+                lines.push(`    path: ${f.affectedFiles.join(", ")}`);
+            lines.push(`    evidence: ${sanitize(f.evidence ?? "(none)")}`);
+            lines.push(`    ${sanitize(f.description)}`);
+            if (f.recommendation)
+                lines.push(`    recommendation: ${sanitize(f.recommendation)}`);
+        }
+    }
+    if (!anyFindings)
+        lines.push("(no findings)");
+    lines.push("");
+    // 19. Skipped/unsupported/not-run/inconclusive checks
+    lines.push(divider());
+    lines.push("SKIPPED, UNSUPPORTED, NOT-RUN, AND INCONCLUSIVE CHECKS");
+    lines.push(divider());
+    const nonPassing = model.checks.filter((c) => c.status !== "passed");
+    if (nonPassing.length === 0) {
+        lines.push("(all checks passed)");
+    }
+    else {
+        for (const c of nonPassing) {
+            lines.push(`  [${c.status}] ${c.id} — ${sanitize(c.title)}`);
+            if (c.skipInfo)
+                lines.push(`    reason: ${sanitize(c.skipInfo.reason)}`);
+        }
+    }
+    lines.push("");
+    // 20. Target mutation evidence
+    lines.push(divider());
+    lines.push("TARGET MUTATION EVIDENCE");
+    lines.push(divider());
+    lines.push(sanitize(model.targetMutationSummary.summary));
+    lines.push("");
+    // 21. Static-analysis limitations
+    lines.push(divider());
+    lines.push("STATIC-ANALYSIS LIMITATIONS");
+    lines.push(divider());
+    for (const limitation of model.staticAnalysisLimitations) {
+        lines.push(`  - ${limitation}`);
+    }
+    lines.push("");
+    // 22. Recommended next step
+    lines.push(divider());
+    lines.push("RECOMMENDED NEXT STEP");
+    lines.push(divider());
+    lines.push(sanitize(model.recommendedNextStep));
+    return lines.join("\n");
+}

package/dist/src/mobile/android/report/writeAndroidReportFiles.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+import { renderAndroidTextReport } from "./renderAndroidReport.js";
+import { serializeAndroidReportModel } from "./model.js";
+export function writeAndroidReportFiles(options) {
+    const reportDir = options.outDir;
+    if (!fs.existsSync(reportDir)) {
+        fs.mkdirSync(reportDir, { recursive: true });
+    }
+    const basename = `${options.prefix}-android-security-validation`;
+    const textPath = options.formats.includes("text") ? path.join(reportDir, `${basename}.txt`) : null;
+    const jsonPath = options.formats.includes("json") ? path.join(reportDir, `${basename}.json`) : null;
+    const writtenPaths = [];
+    if (textPath) {
+        fs.writeFileSync(textPath, renderAndroidTextReport(options.report), "utf8");
+        writtenPaths.push(textPath);
+    }
+    if (jsonPath) {
+        fs.writeFileSync(jsonPath, serializeAndroidReportModel(options.report), "utf8");
+        writtenPaths.push(jsonPath);
+    }
+    return { textPath, jsonPath, writtenPaths };
+}

package/dist/src/mobile/android/targetMetadata.js

@@ -0,0 +1,27 @@
+export function createAndroidTargetMetadata(partial) {
+    const { local, androidProfile, detection } = partial;
+    return {
+        local,
+        androidProfile,
+        classification: {
+            projectKind: detection.projectKind,
+            uiToolkit: detection.uiToolkit,
+        },
+        modules: detection.modules.map((module) => module.path),
+        applicationModules: detection.applicationModules,
+        libraryModules: detection.libraryModules,
+        manifestPaths: detection.manifestPaths,
+        gradleWrapper: partial.gradleWrapper ?? { present: detection.hasGradleWrapper },
+        releaseMetadata: partial.releaseMetadata ?? {
+            available: false,
+            note: "Release metadata summary is not implemented in this batch.",
+        },
+        environmentCapabilities: partial.environmentCapabilities ?? {
+            gradleAvailable: "unknown",
+            androidSdkAvailable: "unknown",
+            notes: ["Environment capability detection is not implemented in this batch."],
+        },
+        detectionConfidence: detection.confidence,
+        detectionEvidence: detection.evidence,
+    };
+}

package/dist/src/mobile/android/validate/androidVerdict.js

@@ -0,0 +1,248 @@
+// ---------------------------------------------------------------------------
+// v0.4.0 Batch 5 — initial Android verdict policy (agents.txt Batch 5
+// section 12).
+//
+// Reuses the existing security-validation ReleaseVerdict vocabulary (all
+// four machine values match or map directly — see result.ts's
+// AndroidVerdictValue comment) rather than a parallel Android-only
+// vocabulary. Precedence, evaluated in order, first match wins:
+//   1. not-ready-security-blocker-remains
+//   2. inconclusive-audit-environment-incomplete
+//   3. ready-except-optional-manual-checks
+//   4. ready-for-release-preparation
+// A stronger negative verdict is never overwritten by a weaker positive one.
+// ---------------------------------------------------------------------------
+const AUDIT_FINDING_DRIVEN_CATEGORIES = new Set(["android-permissions", "android-components", "android-intent-filters", "android-deep-links"]);
+const REQUIRED_CHECK_CATEGORIES = new Set([
+    "android-detection",
+    "android-manifest",
+    "android-permissions",
+    "android-components",
+    "android-intent-filters",
+    "android-deep-links",
+    "android-gradle",
+]);
+export function androidVerdictToHumanLabel(verdict) {
+    switch (verdict) {
+        case "ready-for-release-preparation":
+            return "ready for release preparation";
+        case "not-ready-security-blocker-remains":
+            return "not ready: security blocker remains";
+        case "ready-except-optional-manual-checks":
+            return "ready except optional manual checks";
+        case "inconclusive-audit-environment-incomplete":
+            return "inconclusive: android environment incomplete";
+    }
+}
+export function calculateAndroidVerdict(input) {
+    const { checks, findings, detection, playReadiness, targetMutation, multipleApplicationModules } = input;
+    const reasons = [];
+    const blockerFindings = findings.filter((f) => f.severity === "blocker");
+    const majorFindings = findings.filter((f) => f.severity === "major");
+    const minorOrInformationalFindings = findings.filter((f) => f.severity === "minor" || f.severity === "informational");
+    // Filtered by requirementLevel as well as category: optional Gradle
+    // operation checks (e.g. android-gradle-unit-test-debug) share the
+    // "android-gradle" category with the required static metadata check
+    // (android-gradle-metadata) but must never be treated as a required check
+    // — an optional operation's failure belongs in the advisory tier (section
+    // 12.5), not the not-ready tier.
+    const requiredChecks = checks.filter((c) => REQUIRED_CHECK_CATEGORIES.has(c.category) && c.requirementLevel === "required");
+    // Audit-family checks (permissions/components/intent-filters/deep-links)
+    // report status "failed" whenever ANY non-informational finding exists,
+    // regardless of severity (see audit/checkResultBuilder.ts) — that binary
+    // status is deliberately NOT used for the not-ready decision here, since a
+    // single minor finding would otherwise be indistinguishable from a
+    // blocker. Finding *severity* (checked separately above/below) is the
+    // authoritative signal for those four categories; a "failed" status only
+    // blocks the verdict for the non-audit required checks (detection,
+    // manifest parsing, Gradle metadata), where it reflects a genuine
+    // orchestration/parsing failure rather than a graded finding.
+    const failedRequired = requiredChecks.filter((c) => c.status === "failed" && !AUDIT_FINDING_DRIVEN_CATEGORIES.has(c.category));
+    const inconclusiveRequired = requiredChecks.filter((c) => c.status === "inconclusive" || c.status === "error");
+    const unsupportedRequired = requiredChecks.filter((c) => c.status === "unsupported");
+    const skippedOptional = checks.filter((c) => c.requirementLevel === "optional" && (c.status === "skipped" || c.status === "not-run"));
+    const failedOptional = checks.filter((c) => c.requirementLevel === "optional" && c.status === "failed");
+    // ---- 1. not-ready-security-blocker-remains ---------------------------------
+    if (blockerFindings.length > 0) {
+        for (const f of blockerFindings) {
+            reasons.push({
+                code: "android-blocker-finding",
+                summary: `Blocker-severity finding: ${f.title}`,
+                relatedFindingIds: [f.id],
+                severityOrStatus: "blocker",
+                impact: "blocking",
+                recommendedAction: f.recommendation ?? "Resolve this finding before release preparation.",
+            });
+        }
+        return { verdict: "not-ready-security-blocker-remains", recommendedNextStep: `Fix ${blockerFindings.length} blocker finding(s) before release.`, reasons };
+    }
+    if (majorFindings.length > 0) {
+        for (const f of majorFindings) {
+            reasons.push({
+                code: "android-major-finding",
+                summary: `Major-severity finding: ${f.title}`,
+                relatedFindingIds: [f.id],
+                severityOrStatus: "major",
+                impact: "blocking",
+                recommendedAction: f.recommendation ?? "Resolve or explicitly accept this finding before release preparation.",
+            });
+        }
+        return { verdict: "not-ready-security-blocker-remains", recommendedNextStep: `Review ${majorFindings.length} major finding(s) before release.`, reasons };
+    }
+    if (targetMutation.comparable && targetMutation.unexpectedChanges.length > 0) {
+        reasons.push({
+            code: "android-unexpected-target-modification",
+            summary: `Unexpected target change(s) observed: ${targetMutation.unexpectedChanges.join(", ")}`,
+            severityOrStatus: "blocking",
+            impact: "blocking",
+            recommendedAction: "Investigate why validation modified tracked target files and re-run.",
+        });
+        return { verdict: "not-ready-security-blocker-remains", recommendedNextStep: "An unexpected tracked target-file modification occurred during validation. Investigate before release.", reasons };
+    }
+    if (failedRequired.length > 0) {
+        for (const c of failedRequired) {
+            reasons.push({
+                code: "android-required-check-failed",
+                summary: `Required check failed: ${c.title}`,
+                relatedCheckId: c.id,
+                severityOrStatus: c.status,
+                impact: "blocking",
+                recommendedAction: "Investigate the failure evidence for this check.",
+            });
+        }
+        return { verdict: "not-ready-security-blocker-remains", recommendedNextStep: `Required check(s) failed: ${failedRequired.map((c) => c.title).join(", ")}.`, reasons };
+    }
+    // ---- 2. inconclusive-audit-environment-incomplete ---------------------------
+    // Profile mismatch: the target was not detected as Android at all. This
+    // must never read as "ready" — every required check above reports
+    // "unsupported", not "passed" (agents.txt Batch 5 section 9.3).
+    if (detection.projectKind === "non-android") {
+        reasons.push({
+            code: "android-profile-mismatch",
+            summary: "The --profile android target was not detected as an Android Gradle project.",
+            impact: "inconclusive",
+            recommendedAction: "Re-run against an Android Gradle project, or select a different --profile for this target.",
+        });
+        return {
+            verdict: "inconclusive-audit-environment-incomplete",
+            recommendedNextStep: "This target does not appear to be an Android Gradle project. Android validation could not run.",
+            reasons,
+        };
+    }
+    if (detection.projectKind === "partial" || detection.projectKind === "unknown") {
+        reasons.push({
+            code: "android-partial-detection",
+            summary: `Android project detection is partial or ambiguous (projectKind=${detection.projectKind}).`,
+            severityOrStatus: detection.confidence,
+            impact: "inconclusive",
+            recommendedAction: "Confirm the target is a complete Android Gradle project and re-run detection.",
+        });
+    }
+    if (inconclusiveRequired.length > 0) {
+        for (const c of inconclusiveRequired) {
+            reasons.push({
+                code: "android-required-check-inconclusive",
+                summary: `Required check is ${c.status}: ${c.title}`,
+                relatedCheckId: c.id,
+                severityOrStatus: c.status,
+                impact: "inconclusive",
+                recommendedAction: c.skipInfo?.recommendedNextAction ?? "Provide the missing evidence and re-run.",
+            });
+        }
+    }
+    if (unsupportedRequired.length > 0) {
+        for (const c of unsupportedRequired) {
+            reasons.push({
+                code: "android-required-check-unsupported",
+                summary: `Required check is unsupported: ${c.title}`,
+                relatedCheckId: c.id,
+                severityOrStatus: c.status,
+                impact: "inconclusive",
+                recommendedAction: c.skipInfo?.recommendedNextAction ?? "Provide the missing capability and re-run.",
+            });
+        }
+    }
+    if (multipleApplicationModules) {
+        reasons.push({
+            code: "android-multiple-application-modules",
+            summary: "Multiple application modules were detected; a single release target could not be selected.",
+            impact: "inconclusive",
+            recommendedAction: "Validate each application module individually, or confirm which module is the release target.",
+        });
+    }
+    if ((detection.projectKind === "partial" || detection.projectKind === "unknown") ||
+        inconclusiveRequired.length > 0 ||
+        unsupportedRequired.length > 0 ||
+        multipleApplicationModules) {
+        return {
+            verdict: "inconclusive-audit-environment-incomplete",
+            recommendedNextStep: "Required Android evidence is incomplete. Address the reasons above and re-run android validation.",
+            reasons,
+        };
+    }
+    // ---- 3. ready-except-optional-manual-checks ---------------------------------
+    if (minorOrInformationalFindings.length > 0) {
+        for (const f of minorOrInformationalFindings) {
+            reasons.push({
+                code: "android-review-finding",
+                summary: `${f.severity} finding: ${f.title}`,
+                relatedFindingIds: [f.id],
+                severityOrStatus: f.severity,
+                impact: "advisory",
+                recommendedAction: f.recommendation ?? "Review before release.",
+            });
+        }
+    }
+    if (skippedOptional.length > 0) {
+        for (const c of skippedOptional) {
+            reasons.push({
+                code: "android-optional-check-not-run",
+                summary: `Optional check was not run or skipped: ${c.title}`,
+                relatedCheckId: c.id,
+                severityOrStatus: c.status,
+                impact: "advisory",
+                recommendedAction: "Run explicitly via --android-gradle-operations if this evidence is needed.",
+            });
+        }
+    }
+    if (failedOptional.length > 0) {
+        for (const c of failedOptional) {
+            reasons.push({
+                code: "android-optional-check-failed",
+                summary: `Optional operation failed: ${c.title}`,
+                relatedCheckId: c.id,
+                severityOrStatus: c.status,
+                impact: "advisory",
+                recommendedAction: "Review the operation output; an optional build/test/lint failure is validation evidence, not a security finding.",
+            });
+        }
+    }
+    const manualPlayItems = playReadiness.items.filter((i) => i.status === "manual-check-required" || i.status === "unresolved" || i.status === "missing");
+    if (playReadiness.applicable && manualPlayItems.length > 0) {
+        reasons.push({
+            code: "android-play-readiness-manual-items",
+            summary: `${manualPlayItems.length} Play-readiness checklist item(s) require manual confirmation.`,
+            impact: "advisory",
+            recommendedAction: "Review the Play-readiness checklist section before publishing.",
+        });
+    }
+    if (reasons.length > 0) {
+        return {
+            verdict: "ready-except-optional-manual-checks",
+            recommendedNextStep: "No blocking or required-evidence gaps remain. Review the advisory items above (findings, skipped optional checks, and manual Play-readiness items) before release preparation.",
+            reasons,
+        };
+    }
+    // ---- 4. ready-for-release-preparation ----------------------------------------
+    reasons.push({
+        code: "android-ready",
+        summary: "All required static Android checks completed with no blocking findings, no unexpected target modification, and no outstanding advisory items.",
+        impact: "advisory",
+        recommendedAction: "Proceed with release preparation. This does not certify Google Play compliance or publication readiness.",
+    });
+    return {
+        verdict: "ready-for-release-preparation",
+        recommendedNextStep: "All required static Android checks passed. Proceed with release preparation (this is not a Google Play compliance or publication-readiness claim).",
+        reasons,
+    };
+}