@frankzhang2026/opencode-android-orchestrator 0.8.1 → 0.10.0

package/docs/SECURITY.md

@@ -1,9 +1,9 @@
 # Security model
 
 This document describes the security properties of
-`@frankzhang2026/opencode-android-orchestrator@0.8.1`. The lifecycle foundation
+`@frankzhang2026/opencode-android-orchestrator@0.10.0`. The lifecycle foundation
 completed the real OpenCode `1.14.22` and `1.15.13` release matrix in `0.2.0`;
-`0.8.1` retains that compatibility boundary.
+`0.10.0` retains that compatibility boundary.
 
 ## Security goals and non-goals
 
@@ -130,14 +130,23 @@ while Gradle settings/build files and orchestration resources remain protected.
 legacy configuration with no scope field as `primary`, preventing an implicit
 permission expansion.
 
-`unitTestsEnabled` and `lintEnabled` are the only operator-editable fields in
-the otherwise manifest-managed `automation/config.json`. Upgrade authenticates
+`unitTestsEnabled`, `lintEnabled`, and `commitMessagePrefixMode` are the
+operator-editable fields in the otherwise manifest-managed
+`automation/config.json`. Upgrade authenticates
 the remaining generated content before preserving those values, and doctor
 validates the resulting adaptive configuration. Task agents still cannot edit
 the protected file. Unit tests default on and lint defaults off; disabling unit
 verification does not remove the mandatory RED evidence step. Assemble, scope,
 evidence, and required device-test gates are unaffected.
 
+When commit prefix mode is `required`, the regular UTF-8 sidecar
+`automation/automation-commit-prefix` must contain exactly one active line.
+The installer creates a comments-only template without failing installation;
+normal preflight and contract execution then block until a human fills it.
+The file is not manifest-managed and is excluded from worktree, evidence, and
+commit pathsets. Accepted and abort-recovery commits read it from the recorded
+source worktree; manual Git commits remain outside this enforcement boundary.
+
 The optional repository-root `.automation-worktree-allowlist` is controlled by
 the local human operator, not by task agents. It accepts at most 256 exact,
 normalized repository-relative file paths in a regular file no larger than 64
@@ -157,7 +166,7 @@ writes the target package modes.
 ## Transaction and recovery safety
 
 `init` writes original-file backups before publishing a prepared manifest. It
-then applies validated files, runs the 44-case transaction suite and a shadow
+then applies validated files, runs the 46-case transaction suite and a shadow
 run, verifies final hashes/modes, and only then marks the manifest installed.
 Failure before completion restores originals and removes safely unchanged new
 files.

package/docs/TROUBLESHOOTING.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 Use this guide for
-`@frankzhang2026/opencode-android-orchestrator@0.8.1`.
+`@frankzhang2026/opencode-android-orchestrator@0.10.0`.
 
 ## Start with read-only evidence
 
@@ -11,7 +11,7 @@ From the repository root, capture:
 git status --short --branch
 git rev-parse HEAD
 opencode --version
-npx @frankzhang2026/opencode-android-orchestrator@0.8.1 doctor . --json
+npx @frankzhang2026/opencode-android-orchestrator@0.10.0 doctor . --json
 ```
 
 If installation never completed, doctor will correctly report a missing or
@@ -39,9 +39,9 @@ command-scoped override:
 
 ```sh
 npm --registry=https://registry.npmjs.org/ view \
-  @frankzhang2026/opencode-android-orchestrator@0.8.1 version
+  @frankzhang2026/opencode-android-orchestrator@0.10.0 version
 npx --yes --registry=https://registry.npmjs.org/ \
-  @frankzhang2026/opencode-android-orchestrator@0.8.1 upgrade . --json
+  @frankzhang2026/opencode-android-orchestrator@0.10.0 upgrade . --json
 ```
 
 This leaves the company's saved npm configuration unchanged. Use the option
@@ -60,15 +60,18 @@ Git-backed Superpowers plugin at runtime.
 | `MODULE_SCOPE_INVALID` or an invalid `--module-scope` argument | The value is not `all` or `primary`. | Use `all` for the default all-module contract or `primary` for an intentional single-module restriction. |
 | `PRIMARY_MODULE_AMBIGUOUS` | Restrictive `primary` scope has multiple possible Android modules. | Supply an exact Gradle path, for example `--module-scope primary --primary-module :mobile`, or use the default `all` scope. |
 | `PRIMARY_MODULE_NOT_FOUND` | The selected Gradle path was not detected. | Use a module path reported by doctor/project detection; do not pass a filesystem directory. |
-| `GRADLE_DISCOVERY_FAILED` | The temporary read-only Gradle configuration failed, or registered tasks could not form every required verification group. | Run `./gradlew help --no-configuration-cache --console=plain` and fix the reported project/JDK/dependency issue. Use `--gradle-verification-config` only for an intentional nonstandard task policy, and keep that file inside the target repository. |
+| `GRADLE_DISCOVERY_FAILED` | The temporary read-only Gradle configuration failed, or registered tasks could not form every required verification group. | Run `./gradlew help --no-configuration-cache --console=plain` and fix the reported project/JDK/dependency issue. Do not use the much larger `tasks --all` report as a discovery workaround. Use `--gradle-verification-config` only for an intentional nonstandard task policy. |
+| A real task exists but `jq '.gradleVerification.focusedTestTasks | index(":component_me:testDebugUnitTest")' automation/config.json` prints `null` | A version through `0.8.1` generated configuration from a partial static module set, commonly because settings logic was dynamic or a convention plugin applied Android indirectly. | Upgrade with `--refresh-gradle-discovery`; do not add 30+ modules or tasks by hand. Then rerun the `jq` check and review the regenerated module/path/task diff. |
 | Unit tests did not run | `unitTestsEnabled` is false. | Set it to `true` in `automation/config.json`, commit the change, and rerun the gate. |
 | Unit tests run but should be skipped | `unitTestsEnabled` is true, which is the default. | Set it to `false` in `automation/config.json`; RED evidence remains mandatory. |
 | Lint did not run | `lintEnabled` is false, which is the default. | Set it to `true` in `automation/config.json`, commit the change, and rerun the gate. |
 | Lint runs but should be skipped | `lintEnabled` is true. | Set it to `false` in `automation/config.json` and commit the change. |
+| Doctor warns that the commit prefix is unconfigured, or preflight says it is required | `commitMessagePrefixMode` defaults to `required`, and init/upgrade created a comments-only `automation/automation-commit-prefix` template. | Edit that file once and put the current company prefix on exactly one non-comment line. Do not start the task until preflight passes. |
+| Commit-prefix validation reports multiple lines, whitespace, size, or a symlink | The human-owned prefix file is ambiguous or unsafe. | Replace it with a regular UTF-8 text file containing one active line of at most 256 bytes; blank and `#` comment lines are allowed. |
 | Invalid `--long-command-timeout-ms` | The value is not an integer from `120000` through `7200000`. | Use the `1800000` ms default or pass an intentional bounded value to `init`/`upgrade`; do not edit the generated config directly. |
 | Android SDK failure | No valid explicit SDK, `ANDROID_HOME`, `ANDROID_SDK_ROOT`, or `local.properties` `sdk.dir` was found. | Configure one real SDK root containing `platforms/` and `build-tools/`. Do not publish `local.properties`. |
 | Missing `git`, `jq`, `rg`, `shasum`, or Java | Required deterministic command is unavailable on `PATH`. | Install or restore the missing command, record its version, and rerun the read-only checks. |
-| `Bundled Orchestrator skill is unavailable` | The installed `0.8.1` package is incomplete, damaged, or loaded from an unsupported partial copy. | Reinstall the exact package, inspect its `resources/third-party/superpowers-v6.2.0/skills/` entries, restart OpenCode, and rerun `opencode debug skill`. Do not add an external Superpowers plugin as a fallback. |
+| `Bundled Orchestrator skill is unavailable` | The installed `0.10.0` package is incomplete, damaged, or loaded from an unsupported partial copy. | Reinstall the exact package, inspect its `resources/third-party/superpowers-v6.2.0/skills/` entries, restart OpenCode, and rerun `opencode debug skill`. Do not add an external Superpowers plugin as a fallback. |
 | The exact Superpowers v6.2.0 plugin remains after upgrade | That entry existed in the verified pre-install OpenCode file and is therefore user-owned. | Leave it in place or remove it as a separate reviewed configuration change. Upgrade only removes the old Orchestrator-managed entry. |
 
 Version `0.6.0` always passes `--no-configuration-cache` to its temporary
@@ -77,12 +80,23 @@ Gradle task-discovery invocation. This overrides a repository-level
 the project's files or normal build behavior. Deleting the project's
 Configuration Cache is therefore neither required nor a durable repair.
 
+Version `0.9.0` makes the same bounded Gradle invocation authoritative for
+both modules and tasks. It checks applied `com.android.*` plugins after project
+evaluation and reads `TaskContainer.names`, avoiding the volume and apparent
+silence of `./gradlew tasks --all --console=plain | rg ...` in a large build.
+For an existing installation, run:
+
+```sh
+npx @frankzhang2026/opencode-android-orchestrator@0.10.0 upgrade . \
+  --refresh-gradle-discovery
+```
+
 Version `0.7.0` raises direct managed long-running lifecycle commands to at
 least `1800000` milliseconds. A higher timeout already supplied by the caller
 is preserved; unrelated Bash commands are unchanged. To configure one hour,
 run `upgrade . --long-command-timeout-ms 3600000` on a healthy installation.
 If a command still reports `120000 ms`, confirm that the project manifest and
-OpenCode plugin reference are both `0.8.1`, restart the OpenCode session so the
+OpenCode plugin reference are both `0.10.0`, restart the OpenCode session so the
 plugin reloads, and rerun doctor before attempting recovery.
 
 After installation, inspect OpenCode discovery separately:
@@ -137,7 +151,7 @@ Common fail-closed codes include:
 | `PLUGIN_VERSION_CONFLICT` | The same managed package identity has another reference/version. | Review and remove or migrate only the obsolete entry; never let init silently replace it. |
 | `DUPLICATE_PLUGIN` or `DUPLICATE_PROPERTY` | Configuration identity is ambiguous. | Correct the JSON/JSONC structure without discarding unrelated fields or comments. |
 | `INVALID_JSONC` or `ROOT_NOT_OBJECT` | OpenCode configuration cannot be merged safely. | Repair the user-owned file and validate it before retrying. |
-| `AGENTS_BLOCK_CONFLICT` or `AGENTS_MARKERS_INVALID` | During `init`, the bounded block was modified; or a lifecycle command found partial, out-of-order, or duplicate markers. | Keep project-specific instructions outside one valid marker pair. `0.8.1 upgrade` preserves marker-external changes and replaces the old managed block; malformed marker structure still requires manual repair. |
+| `AGENTS_BLOCK_CONFLICT` or `AGENTS_MARKERS_INVALID` | During `init`, the bounded block was modified; or a lifecycle command found partial, out-of-order, or duplicate markers. | Keep project-specific instructions outside one valid marker pair. `0.10.0 upgrade` preserves marker-external changes and replaces the old managed block; malformed marker structure still requires manual repair. |
 | `FILE_SYMLINK`, `TARGET_SYMLINK`, or `CONFIG_SYMLINK` | A managed target or ancestor is a symbolic link. | Replace it only after understanding ownership and destination. The installer intentionally does not follow it. |
 | `PLAN_STALE` or `TARGET_MODIFIED` | A file changed between planning and application. | Stop concurrent edits, inspect the diff, and rerun from a stable state. |
 
@@ -156,8 +170,8 @@ configuration.
 | --- | --- | --- |
 | `MANIFEST_MISSING`, `MANIFEST_INVALID`, or `MANIFEST_STATE` | No trustworthy installed manifest is available. | Do not invent a manifest or copy one from another project. Determine whether this is an uninstalled/manual setup or an interrupted transaction. |
 | `EXISTING_INSTALLATION_DIFFERENT` | `init` found another installed inventory/version. | Use `upgrade` for a healthy older manifest. |
-| `EXISTING_INSTALLATION_INVALID` or `INSTALLATION_INVALID` | Manifest, installed files, or required backups failed structural or content validation. In `0.8.0`, this also reported an active manifest whose mode was not exactly `0600`. | Preserve the project and `.automation-plugin/`; use `0.8.1 upgrade` for mode-only drift, and inspect other doctor details or recovery history. |
-| `INSTALLED_FILES_MODIFIED` | Upgrade found content/existence drift in an ordinary managed file or missing/modified backup content. | Move intentional customization out of ordinary managed paths or choose manual recovery. `0.8.1` separately merges user-owned `AGENTS.md` content and does not reject mode-only drift. |
+| `EXISTING_INSTALLATION_INVALID` or `INSTALLATION_INVALID` | Manifest, installed files, or required backups failed structural or content validation. In `0.8.0`, this also reported an active manifest whose mode was not exactly `0600`. | Preserve the project and `.automation-plugin/`; use `0.10.0 upgrade` for mode-only drift, and inspect other doctor details or recovery history. |
+| `INSTALLED_FILES_MODIFIED` | Upgrade found content/existence drift in an ordinary managed file or missing/modified backup content. | Move intentional customization out of ordinary managed paths or choose manual recovery. `0.10.0` separately merges user-owned `AGENTS.md` content and does not reject mode-only drift. |
 | `VERSION_DOWNGRADE_REFUSED` | Target package is older than the installed manifest. | Use a newer fixed package version; never edit the manifest version. |
 | `UPGRADE_IN_PROGRESS` or `UNINSTALL_IN_PROGRESS` | `.automation-plugin/upgrade.json` or `uninstall.json` records an unfinished transaction. | Inspect the marker and matching recovery directory. Do not delete the marker merely to retry. |
 | `POST_UPGRADE_VERIFICATION_FAILED` | New resources failed verification. | The implementation attempts a complete old-version rollback; verify the old manifest and inspect upgrade evidence. |
@@ -168,7 +182,7 @@ configuration.
 Installer control paths are:
 
 - active manifest: `.automation-plugin/manifest.json` (new manifests are
-  written as `0600`; mode-only drift does not block `0.8.1 upgrade`);
+  written as `0600`; mode-only drift does not block `0.10.0 upgrade`);
 - first-install/original backups: `.automation-plugin/backups/<id>/`;
 - upgrade marker and snapshots: `.automation-plugin/upgrade.json` and
   `.automation-plugin/upgrades/<id>/`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frankzhang2026/opencode-android-orchestrator",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Reusable OpenCode orchestration for Android projects",
   "license": "MIT",
   "author": "frankzhang2026",

package/templates/README.md

@@ -14,7 +14,7 @@ Migrated template roots:
 - `.opencode/skills`: the three `scheduled-quality-*` skills
 - `scripts/automation`: all 29 deterministic V3 Bash transactions and their
   test runner, preserved as executable files
-- `automation`: the portable V4 configuration render source, both JSON Schemas,
+- `automation`: the portable V5 configuration render source, both JSON Schemas,
   and the task contract example
 - `docs/plans/README.md`: the human-approved plan authoring contract
 - `AGENTS.md.fragment`: a bounded managed block for non-destructive
@@ -43,6 +43,14 @@ policy. Verification switches live in `automation/config.json`:
 Discovered task lists are retained even while their corresponding gate is
 disabled.
 
+Schema V5 also sets `commitMessagePrefixMode` to `required`. After managed
+resources are written, init/upgrade creates the human-owned
+`automation/automation-commit-prefix` comments-only template when missing.
+That sidecar is not a packaged template or manifest-managed resource: users
+fill one active line, may change it between commits, and upgrade/uninstall
+preserve it. An unconfigured required file blocks task startup but remains a
+warning during install/upgrade shadow verification.
+
 After read-only planning succeeds, `init` creates a comment-only
 `.automation-worktree-allowlist` if it is missing and preserves any existing
 regular file. This user-editable control file remains outside the managed

package/templates/automation/config.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 5,
   "enabled": true,
   "mode": "orchestrated",
   "workspaceStrategy": "inPlaceExclusive",
@@ -10,6 +10,7 @@
   "maxReviewerRestarts": 2,
   "unitTestsEnabled": true,
   "lintEnabled": false,
+  "commitMessagePrefixMode": "required",
   "longCommandTimeoutMs": 1800000,
   "autoCleanupWorktrees": true,
   "pushAfterAcceptance": false,

package/templates/automation/config.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:frankzhang2026:opencode-android-orchestrator:automation-config:v4",
+  "$id": "urn:frankzhang2026:opencode-android-orchestrator:automation-config:v5",
   "title": "OpenCode task orchestration configuration",
   "type": "object",
   "additionalProperties": false,
@@ -38,6 +38,7 @@
     "maxReviewerRestarts",
     "unitTestsEnabled",
     "lintEnabled",
+    "commitMessagePrefixMode",
     "longCommandTimeoutMs",
     "autoCleanupWorktrees",
     "pushAfterAcceptance",
@@ -48,7 +49,7 @@
     "protectedPaths"
   ],
   "properties": {
-    "schemaVersion": { "const": 4 },
+    "schemaVersion": { "const": 5 },
     "enabled": { "type": "boolean" },
     "mode": { "enum": ["shadow", "orchestrated"] },
     "workspaceStrategy": {
@@ -61,6 +62,10 @@
     "maxReviewerRestarts": { "type": "integer", "minimum": 0, "maximum": 3 },
     "unitTestsEnabled": { "type": "boolean", "default": true },
     "lintEnabled": { "type": "boolean", "default": false },
+    "commitMessagePrefixMode": {
+      "enum": ["required", "disabled"],
+      "default": "required"
+    },
     "longCommandTimeoutMs": {
       "type": "integer",
       "minimum": 120000,

package/templates/scripts/automation/abort-task.sh

@@ -86,8 +86,9 @@ if [[ -d "$task_root" ]]; then
                 fi
             done
             if [[ "$product_path_count" -gt 0 ]]; then
+                commit_message="$(automation_commit_message_at "$source_root" "Archive aborted work for $task_id")"
                 git -C "$task_root" add -- "${changed_paths[@]}"
-                git -C "$task_root" commit --only -m "Archive aborted work for $task_id" -- "${changed_paths[@]}"
+                git -C "$task_root" commit --only -m "$commit_message" -- "${changed_paths[@]}"
                 recovery_commit="$(git -C "$task_root" rev-parse HEAD)"
             else
                 plan_rel="$(jq -er '.planPath' "$origin_file")"

package/templates/scripts/automation/accept-and-integrate.sh

@@ -74,6 +74,7 @@ sealed_diff_sha="$(automation_worktree_diff_sha "$task_root")"
 )
 report_file="$evidence_dir/acceptance-report.json"
 [[ "$(jq -er '.sealedDiffSha256' "$report_file")" == "$sealed_diff_sha" ]] || automation_die "acceptance report is stale"
+automation_read_commit_message_prefix_at "$source_root" >/dev/null
 
 automation_acquire_run_lock "$task_id"
 integration_complete=0
@@ -132,9 +133,10 @@ while IFS= read -r path; do
     [[ -n "$path" ]] && commit_paths+=("$path")
 done < <(automation_changed_paths_at "$task_root")
 [[ "${#commit_paths[@]}" -ge 3 ]] || automation_die "final commit must contain product changes and both planning artifacts"
-git -C "$task_root" add -- "${commit_paths[@]}"
 title="$(jq -er '.title' "$task_root/automation/tasks/$task_id.json")"
-git -C "$task_root" commit --only -m "Implement $title ($task_id)" -- "${commit_paths[@]}"
+commit_message="$(automation_commit_message_at "$source_root" "Implement $title ($task_id)")"
+git -C "$task_root" add -- "${commit_paths[@]}"
+git -C "$task_root" commit --only -m "$commit_message" -- "${commit_paths[@]}"
 product_commit="$(git -C "$task_root" rev-parse HEAD)"
 automation_worktree_is_clean "$task_root" || automation_die "task root is dirty after the combined task commit"
 git -C "$task_root" merge-base --is-ancestor "$baseline_head" "$product_commit" || automation_die "combined task commit is not based on the recorded pre-task baseline"

package/templates/scripts/automation/approve-and-run.sh

@@ -33,6 +33,7 @@ plan="$source_root/$plan_rel"
 [[ "$(git -C "$source_root" rev-parse HEAD)" == "$original_head" ]] || automation_die "original HEAD changed after contract review began"
 [[ "$(automation_file_sha256 "$contract")" == "$(jq -er '.contractSha256' "$origin_file")" ]] || automation_die "contract changed after proposal approval"
 [[ "$(automation_file_sha256 "$plan")" == "$(jq -er '.planSha256' "$origin_file")" ]] || automation_die "plan changed after proposal approval"
+automation_read_commit_message_prefix_at "$source_root" >/dev/null
 
 changed_paths=()
 while IFS= read -r path; do

package/templates/scripts/automation/lib.sh

@@ -50,6 +50,9 @@ AUTOMATION_WORKSPACES_DIR="$AUTOMATION_RUNTIME_ROOT/workspaces"
 AUTOMATION_WORKTREE_ALLOWLIST_RELATIVE_PATH=".automation-worktree-allowlist"
 AUTOMATION_WORKTREE_ALLOWLIST_MAX_BYTES=65536
 AUTOMATION_WORKTREE_ALLOWLIST_MAX_ENTRIES=256
+AUTOMATION_COMMIT_MESSAGE_PREFIX_RELATIVE_PATH="automation/automation-commit-prefix"
+AUTOMATION_COMMIT_MESSAGE_PREFIX_FILE_MAX_BYTES=4096
+AUTOMATION_COMMIT_MESSAGE_PREFIX_MAX_BYTES=256
 
 automation_info() {
     printf '[automation] %s\n' "$*"
@@ -111,7 +114,7 @@ automation_validate_config() {
             length > 0 and
             length == (unique | length) and
             all(.[]; gradle_task);
-        .schemaVersion == 4 and
+        .schemaVersion == 5 and
         (.enabled | type == "boolean") and
         (.mode == "shadow" or .mode == "orchestrated") and
         (.workspaceStrategy == "inPlaceExclusive" or .workspaceStrategy == "isolatedWorktree") and
@@ -122,6 +125,7 @@ automation_validate_config() {
         (.maxReviewerRestarts | type == "number" and . >= 0 and . <= 3 and floor == .) and
         (.unitTestsEnabled | type == "boolean") and
         (.lintEnabled | type == "boolean") and
+        (.commitMessagePrefixMode == "required" or .commitMessagePrefixMode == "disabled") and
         (.longCommandTimeoutMs | type == "number" and . >= 120000 and . <= 7200000 and floor == .) and
         (.autoCleanupWorktrees | type == "boolean") and
         .pushAfterAcceptance == false and
@@ -246,6 +250,92 @@ automation_config_value() {
     jq -r "$query" "$AUTOMATION_CONFIG"
 }
 
+automation_read_commit_message_prefix_at() {
+    local root="$1"
+    local config_file="$root/automation/config.json"
+    local prefix_file="$root/$AUTOMATION_COMMIT_MESSAGE_PREFIX_RELATIVE_PATH"
+    local mode byte_count line prefix prefix_bytes
+    local active_count=0
+
+    if [[ -L "$config_file" || ! -f "$config_file" ]]; then
+        automation_die "missing or unsafe automation configuration: $config_file"
+        return 1
+    fi
+    mode="$(jq -er '.commitMessagePrefixMode' "$config_file")" || {
+        automation_die "commitMessagePrefixMode is missing from $config_file"
+        return 1
+    }
+    case "$mode" in
+        disabled) return 0 ;;
+        required) ;;
+        *)
+            automation_die "unsupported commitMessagePrefixMode: $mode"
+            return 1
+            ;;
+    esac
+
+    if [[ ! -e "$prefix_file" && ! -L "$prefix_file" ]]; then
+        automation_die "commit-message prefix is required; fill $prefix_file before starting a task"
+        return 1
+    fi
+    if [[ -L "$prefix_file" || ! -f "$prefix_file" ]]; then
+        automation_die "commit-message prefix must be a regular file, not a symlink: $prefix_file"
+        return 1
+    fi
+    byte_count="$(wc -c < "$prefix_file" | tr -d '[:space:]')"
+    if [[ ! "$byte_count" =~ ^[0-9]+$ ]] || \
+       [[ "$byte_count" -gt "$AUTOMATION_COMMIT_MESSAGE_PREFIX_FILE_MAX_BYTES" ]]; then
+        automation_die "commit-message prefix file exceeds $AUTOMATION_COMMIT_MESSAGE_PREFIX_FILE_MAX_BYTES bytes: $prefix_file"
+        return 1
+    fi
+
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        line="${line%$'\r'}"
+        [[ -z "$line" || "$line" =~ ^[[:space:]]*$ || "$line" =~ ^[[:space:]]*# ]] && continue
+        active_count=$((active_count + 1))
+        if [[ "$active_count" -gt 1 ]]; then
+            automation_die "commit-message prefix must contain exactly one non-comment line: $prefix_file"
+            return 1
+        fi
+        if [[ "$line" == [[:space:]]* || "$line" == *[[:space:]] ]]; then
+            automation_die "commit-message prefix must not have leading or trailing whitespace"
+            return 1
+        fi
+        case "$line" in
+            *[[:cntrl:]]*)
+                automation_die "commit-message prefix must not contain control characters"
+                return 1
+                ;;
+        esac
+        prefix="$line"
+    done < "$prefix_file"
+
+    if [[ "$active_count" -eq 0 ]]; then
+        automation_die "commit-message prefix is not configured; fill $prefix_file before starting a task"
+        return 1
+    fi
+    prefix_bytes="$(printf '%s' "$prefix" | wc -c | tr -d '[:space:]')"
+    if [[ ! "$prefix_bytes" =~ ^[0-9]+$ ]] || \
+       [[ "$prefix_bytes" -gt "$AUTOMATION_COMMIT_MESSAGE_PREFIX_MAX_BYTES" ]]; then
+        automation_die "commit-message prefix exceeds $AUTOMATION_COMMIT_MESSAGE_PREFIX_MAX_BYTES UTF-8 bytes"
+        return 1
+    fi
+    printf '%s\n' "$prefix"
+}
+
+automation_commit_message_at() {
+    local root="$1"
+    local base_message="$2"
+    local prefix
+
+    prefix="$(automation_read_commit_message_prefix_at "$root")" || return 1
+    if [[ -n "$prefix" ]]; then
+        printf '%s %s\n' "$prefix" "$base_message"
+    else
+        printf '%s\n' "$base_message"
+    fi
+}
+
 automation_validate_gradle_task() {
     local task="${1:-}"
     local safe_task_pattern='^([A-Za-z][A-Za-z0-9_.-]*|(:[A-Za-z0-9_.-]+)+)$'
@@ -453,7 +543,7 @@ automation_validate_worktree_allowlist_entry_at() {
             ;;
     esac
     case "$path" in
-        /*|./*|.|..|.git|.git/*|docs/plans|docs/plans/*|"$AUTOMATION_WORKTREE_ALLOWLIST_RELATIVE_PATH")
+        /*|./*|.|..|.git|.git/*|docs/plans|docs/plans/*|"$AUTOMATION_WORKTREE_ALLOWLIST_RELATIVE_PATH"|"$AUTOMATION_COMMIT_MESSAGE_PREFIX_RELATIVE_PATH")
             automation_die "worktree allowlist entry is reserved or unsafe: $path"
             return 1
             ;;
@@ -608,6 +698,7 @@ automation_worktree_path_is_allowlisted() {
     local entry
 
     [[ "$path" == "$AUTOMATION_WORKTREE_ALLOWLIST_RELATIVE_PATH" ]] && return 0
+    [[ "$path" == "$AUTOMATION_COMMIT_MESSAGE_PREFIX_RELATIVE_PATH" ]] && return 0
     while IFS= read -r entry; do
         [[ -n "$entry" ]] || continue
         [[ "$path" == "$entry" ]] && return 0

package/templates/scripts/automation/orchestrate-task.sh

@@ -19,6 +19,7 @@ source_root="$(jq -er '.sourceRoot' "$workspace_file")"
 if [[ "$(jq -r '.repositoryLeaseRequired // false' "$workspace_file")" == "true" ]]; then
     automation_require_repository_lease "$task_id" "$source_root" "$workspace_strategy"
 fi
+automation_read_commit_message_prefix_at "$source_root" >/dev/null
 
 automation_acquire_run_lock "$task_id"
 trap 'automation_release_run_lock' EXIT

package/templates/scripts/automation/preflight.sh

@@ -47,6 +47,17 @@ mode="$(automation_config_value '.mode')"
 
 [[ "$enabled" == "true" ]] || fail_or_warn "automation is disabled"
 [[ "$mode" == "orchestrated" ]] || fail_or_warn "automation mode is $mode, not orchestrated"
+prefix_validation_error=""
+prefix_root="$AUTOMATION_ROOT"
+if [[ -n "$task_id" ]]; then
+    prefix_workspace_file="$(automation_workspace_path "$task_id")"
+    if [[ -f "$prefix_workspace_file" ]]; then
+        prefix_root="$(jq -er '.sourceRoot' "$prefix_workspace_file")"
+    fi
+fi
+if ! prefix_validation_error="$(automation_read_commit_message_prefix_at "$prefix_root" 2>&1 >/dev/null)"; then
+    fail_or_warn "$prefix_validation_error"
+fi
 
 if [[ "${AUTOMATION_TEST_MODE:-0}" != "1" ]]; then
     [[ -n "${ANDROID_HOME:-}" ]] || fail_or_warn "ANDROID_HOME is not set; configure the Android SDK environment before running OpenCode"

package/templates/scripts/automation/show-acceptance-review.sh

@@ -45,6 +45,8 @@ report_diff_sha="$(jq -er '.sealedDiffSha256' "$report_file")"
 changed_count="$(jq -er '.changedPaths | length' "$report_file")"
 max_changed_files="$(jq -er '.maxChangedFiles' "$report_file")"
 device_tests_required="$(jq -r '.deviceTestsRequired' "$report_file")"
+title="$(jq -er '.title' "$report_file")"
+commit_message="$(automation_commit_message_at "$source_root" "Implement $title ($task_id)")"
 
 printf '# 🔔 人工验收提醒\n\n'
 printf '自动执行已停在 `AWAITING_HUMAN`。下面内容已重新核对 sealed diff；此时代码、计划与任务合同均尚未提交或集成。\n\n'
@@ -58,6 +60,7 @@ printf '| 任务分支收尾 | 成功集成后自动删除；失败或阻塞时
 printf '| sealed diff SHA | `%s` |\n' "$report_diff_sha"
 printf '| 变更范围 | 实际 %s 个 / 合同上限 %s 个 |\n' "$changed_count" "$max_changed_files"
 printf '| 提交策略 | 代码、测试、计划与任务合同合并为一个提交 |\n'
+printf '| 预计提交信息 | `%s` |\n' "$commit_message"
 printf '| 自动证据 | Baseline ✓ · RED ✓ · G1–G6 ✓ · Reviewer APPROVED ✓ |\n'
 printf '\n## 必须重点复核\n\n'
 printf '### P0 · 真实行为是否满足合同\n\n'