@frankzhang2026/opencode-android-orchestrator 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.0 - 2026-08-29
+
+- Add the human-maintained `.automation-worktree-allowlist` for exact local
+  file paths that must not block orchestration. Approved tasks snapshot the
+  validated list and exclude those changes consistently from scope, hashes,
+  evidence, archival, and deterministic commits, including when the local
+  entries were already staged.
+- Reject patterns, directories, duplicates, unsafe paths, symlinks, oversized
+  control files, and protected orchestration, Gradle, Git, or planning paths;
+  treat renames as separate source and destination paths; expand the audited
+  Shell transaction suite from 38 to 42 cases.
+
 ## 0.3.0 - 2026-08-28
 
 - Add `all` and `primary` module scopes and make all-module task contracts the

package/README.md

@@ -3,9 +3,9 @@
 Reusable OpenCode orchestration for macOS Android projects.
 
 Version `0.2.0` is the first published lifecycle release. Version `0.3.0` adds
-default all-module orchestration, configurable Gradle verification tasks, and
-stricter contract/evidence validation while retaining the same certified
-OpenCode compatibility range.
+default all-module orchestration and stronger verification contracts. Version
+`0.4.0` adds a validated, exact-path worktree allowlist for intentional local
+changes while retaining the same certified OpenCode compatibility range.
 
 ## Documentation
 
@@ -36,8 +36,8 @@ even though the installer maintains its own verified recovery data.
 ## Quick start
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.3.0 init .
-npx @frankzhang2026/opencode-android-orchestrator@0.3.0 doctor .
+npx @frankzhang2026/opencode-android-orchestrator@0.4.0 init .
+npx @frankzhang2026/opencode-android-orchestrator@0.4.0 doctor .
 opencode --agent scheduled-planner .
 ```
 
@@ -47,7 +47,7 @@ a task contract without selecting a primary module. To intentionally restrict
 generated contracts to one module, opt into primary-module scope:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.3.0 init . \
+npx @frankzhang2026/opencode-android-orchestrator@0.4.0 init . \
   --module-scope primary \
   --primary-module :mobile
 ```
@@ -56,6 +56,36 @@ In all-module scope, `--primary-module` is optional and only chooses the
 default module used by the focused-test placeholder; it does not narrow which
 detected modules may be modified.
 
+### Allow intentional local worktree changes
+
+If one or more files must stay locally modified while orchestration runs,
+create `.automation-worktree-allowlist` in the Git repository root and edit it
+as a normal text file:
+
+```text
+# One exact repository-relative file path per line
+local/operator-note.txt
+config/developer-overrides.json
+```
+
+Blank lines and lines beginning with `#` are ignored. Entries must be exact
+file paths; directory entries and glob patterns are rejected. The control file
+itself is automatically ignored by orchestration, so it does not need a
+`.gitignore` rule merely to pass preflight.
+
+Allowlisted tracked, untracked, and staged changes do not block startup and are
+excluded from task scope, diff hashes, acceptance/abort evidence, and
+deterministic commits. Existing staged entries remain staged instead of being
+consumed by task or recovery commits. A rename has two paths, so both the old
+and new exact path must be listed if the whole rename should remain local.
+Protected orchestration, Gradle, Git, and planning paths cannot be allowlisted.
+Use this only for files that the task must not modify; remove an entry before
+starting a task that should change that file. The list is snapshotted at
+contract approval, so edits made during a running task apply to the next task.
+Task status exposes the effective snapshot to Coder and Reviewer sessions; an
+isolated task worktree receives an empty effective list so task-local edits are
+never hidden by source-worktree exclusions.
+
 The install transaction manages 45 project-local paths:
 
 | Resource group | Count | Installation behavior |
@@ -75,8 +105,9 @@ does not register Scheduler or launchd jobs.
 ## Status
 
 Version `0.1.0` was an early scaffold without a working installer. Version
-`0.2.0` introduced the complete managed lifecycle; version `0.3.0` builds on
-that release with all-module defaults and stronger verification contracts.
+`0.2.0` introduced the complete managed lifecycle, `0.3.0` added all-module
+defaults and stronger verification contracts, and `0.4.0` adds the bounded
+worktree allowlist described above.
 
 The cross-version plugin entry, OpenCode version doctor, Android/Gradle project
 discovery, audited V3 resources, and all deterministic V3 Shell transactions
@@ -135,7 +166,7 @@ Implemented checks include:
 - a write-capable `init` transaction that installs 45 managed files, preserves
   Shell executable modes, merges OpenCode JSON/JSONC and one bounded AGENTS
   block, and is byte-idempotent for an unchanged installed version
-- write-before-complete verification using the 38-case automation suite and a
+- write-before-complete verification using the 42-case automation suite and a
   read-only shadow run; any failure restores original files before reporting
   the error
 - an installation-aware, read-only doctor that authenticates the 45-file
@@ -213,7 +244,7 @@ preparation alone as resource installation;
 ## Init
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.3.0 init .
+npx @frankzhang2026/opencode-android-orchestrator@0.4.0 init .
 opencode --agent scheduled-planner .
 ```
 
@@ -236,7 +267,7 @@ Android Gradle project, an executable Gradle Wrapper, `git`, `jq`, `rg`,
 2. rejects all unresolved content or mode conflicts;
 3. backs up every existing managed path and publishes a `prepared` manifest;
 4. writes missing or approved merged files with verified hashes and modes;
-5. runs the 38 automation tests and `shadow-run.sh`;
+5. runs the 42 automation tests and `shadow-run.sh`;
 6. marks the manifest `installed` only after both checks pass.
 
 Verification failure automatically restores originals and records rollback
@@ -300,7 +331,7 @@ preflight verifies both resolved permissions and tool discovery.
 ### Phase 2 mutating-tool decision
 
 The 2026-08-25 evaluation remains **NO-GO for mutating custom tools in
-`0.3.0`**.
+`0.4.0`**.
 The fixed Shell allowlist remains the only entry point for state transitions,
 Git mutations, and agent launches. OpenCode custom tools provide typed arguments
 and workspace context, but a normal permission prompt is not the workflow's
@@ -327,7 +358,7 @@ the immediately preceding `question` result and bind at least the approval
 kind, task ID, session, message, relevant sealed SHA/branch, timestamp, and
 nonce. It must also retain fixed-script authentication, strict state
 preconditions, project/worktree bounds, abort propagation that terminates child
-processes, bounded structured output, exact per-agent permissions, the 38-case
+processes, bounded structured output, exact per-agent permissions, the 42-case
 transaction suite, and real `1.14.22`/`1.15.13` integration tests. Internal
 Coder/Reviewer transition scripts remain private orchestration details rather
 than public tools.
@@ -360,7 +391,7 @@ For an older healthy installation, the command:
    backup set;
 4. writes only changed managed resources and restores or removes resources no
    longer managed by the new version;
-5. runs the 38 automation tests and a mutation-free shadow run before swapping
+5. runs the 42 automation tests and a mutation-free shadow run before swapping
    the active manifest;
 6. records upgrade history below `.automation-plugin/history/`.
 

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-Party Notices
 
-Last reviewed for `0.3.0` on 2026-08-28.
+Last reviewed for `0.4.0` on 2026-08-29.
 
 The published package does not vendor `node_modules`, third-party binaries, or
 third-party Skill source. Its compiled JavaScript imports the direct runtime

package/dist/installer/init.js

@@ -229,7 +229,7 @@ export function verifyInitializedProject(targetDirectory, runner = runInitProces
     const automationTests = runner(join(targetDirectory, "scripts/automation/tests/run-tests.sh"), [], { cwd: targetDirectory, timeoutMs: 300_000 });
     const shadowRun = runner(join(targetDirectory, "scripts/automation/shadow-run.sh"), [], { cwd: targetDirectory, timeoutMs: 120_000 });
     const checks = [
-        processCheck("automation-tests", "Automation transaction tests", automationTests, (stdout) => /(?:^|\n)1\.\.38(?:\n|$)/.test(stdout)),
+        processCheck("automation-tests", "Automation transaction tests", automationTests, (stdout) => /(?:^|\n)1\.\.42(?:\n|$)/.test(stdout)),
         processCheck("shadow-run", "Read-only shadow run", shadowRun, shadowOutputIsSafe),
     ];
     return {

package/dist/installer/opencode-config.d.ts

@@ -1,9 +1,9 @@
 export declare const ORCHESTRATOR_PACKAGE_NAME = "@frankzhang2026/opencode-android-orchestrator";
-export declare const ORCHESTRATOR_PACKAGE_VERSION = "0.3.0";
-export declare const ORCHESTRATOR_PLUGIN_REFERENCE = "@frankzhang2026/opencode-android-orchestrator@0.3.0";
+export declare const ORCHESTRATOR_PACKAGE_VERSION = "0.4.0";
+export declare const ORCHESTRATOR_PLUGIN_REFERENCE = "@frankzhang2026/opencode-android-orchestrator@0.4.0";
 export declare const OPENCODE_CONFIG_SCHEMA_URL = "https://opencode.ai/config.json";
 export declare const SUPERPOWERS_PLUGIN_REFERENCE = "superpowers@git+https://github.com/obra/superpowers.git#v6.2.0";
-export declare const REQUIRED_PLUGIN_REFERENCES: readonly ["superpowers@git+https://github.com/obra/superpowers.git#v6.2.0", "@frankzhang2026/opencode-android-orchestrator@0.3.0"];
+export declare const REQUIRED_PLUGIN_REFERENCES: readonly ["superpowers@git+https://github.com/obra/superpowers.git#v6.2.0", "@frankzhang2026/opencode-android-orchestrator@0.4.0"];
 export type OpenCodeConfigMergeErrorCode = "AMBIGUOUS_CONFIG" | "CONFIG_NOT_FILE" | "CONFIG_READ_FAILED" | "CONFIG_SYMLINK" | "DUPLICATE_PLUGIN" | "DUPLICATE_PROPERTY" | "INVALID_JSONC" | "INVALID_PLUGIN_ENTRY" | "PLUGIN_NOT_ARRAY" | "PLUGIN_VERSION_CONFLICT" | "ROOT_NOT_OBJECT" | "TARGET_NOT_DIRECTORY";
 export declare class OpenCodeConfigMergeError extends Error {
     readonly code: OpenCodeConfigMergeErrorCode;

package/dist/installer/opencode-config.js

@@ -2,7 +2,7 @@ import { lstatSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { applyEdits, findNodeAtLocation, getNodeValue, modify, parseTree, printParseErrorCode, } from "jsonc-parser";
 export const ORCHESTRATOR_PACKAGE_NAME = "@frankzhang2026/opencode-android-orchestrator";
-export const ORCHESTRATOR_PACKAGE_VERSION = "0.3.0";
+export const ORCHESTRATOR_PACKAGE_VERSION = "0.4.0";
 export const ORCHESTRATOR_PLUGIN_REFERENCE = `${ORCHESTRATOR_PACKAGE_NAME}@${ORCHESTRATOR_PACKAGE_VERSION}`;
 export const OPENCODE_CONFIG_SCHEMA_URL = "https://opencode.ai/config.json";
 export const SUPERPOWERS_PLUGIN_REFERENCE = "superpowers@git+https://github.com/obra/superpowers.git#v6.2.0";

package/docs/MIGRATION.md

@@ -1,7 +1,7 @@
 # Migration guide
 
 This guide covers migration to
-`@frankzhang2026/opencode-android-orchestrator@0.3.0`. Pin the exact version and
+`@frankzhang2026/opencode-android-orchestrator@0.4.0`. Pin the exact version and
 prove the migration in a disposable clone before changing a long-lived
 repository.
 
@@ -9,9 +9,9 @@ repository.
 
 | Current state | Correct command after release | Important distinction |
 | --- | --- | --- |
-| No orchestrator files or manifest | `npx @frankzhang2026/opencode-android-orchestrator@0.3.0 init .` | Normal new installation; all detected Android modules are enabled by default. |
+| No orchestrator files or manifest | `npx @frankzhang2026/opencode-android-orchestrator@0.4.0 init .` | Normal new installation; all detected Android modules are enabled by default. |
 | Published `0.1.0` scaffold only | Remove any project-local `@0.1.0` plugin reference after review, then run `init`. | `0.1.0` did not create a usable managed installation and cannot be upgraded. |
-| Healthy `0.2.0` manifest-managed installation | Run the fixed `0.3.0` doctor, then `upgrade`. | The missing module-scope field is treated as `primary` unless the upgrade explicitly selects `all`. |
+| Healthy `0.2.0` or `0.3.0` manifest-managed installation | Run the fixed `0.4.0` doctor, then `upgrade`. | A missing module-scope field is treated as `primary`; an existing scope is preserved unless explicitly changed. |
 | Manually copied V3 files, no `.automation-plugin/manifest.json` | Finish active tasks, preserve historical evidence separately, then run `init`. | Exact files can be reused; differing managed files fail as conflicts. |
 | Healthy older manifest-managed installation | Run `doctor`, then the fixed target version's `upgrade`. | `upgrade` requires a valid installed manifest and intact original backups. |
 | Healthy current-version manifest | Run `doctor`; repeated `init` or same-version `upgrade` is verification-only and byte-idempotent. | Do not reinstall or delete the manifest. |
@@ -36,7 +36,7 @@ removes unchanged plugin-created files, and retains drift for manual review.
 5. If a managed manifest already exists, run:
 
    ```sh
-   npx @frankzhang2026/opencode-android-orchestrator@0.3.0 doctor . --json
+   npx @frankzhang2026/opencode-android-orchestrator@0.4.0 doctor . --json
    ```
 
    Do not proceed with `upgrade` unless the installation checks pass.
@@ -52,14 +52,14 @@ scaffold, not as an older managed installation.
 If the project OpenCode configuration contains an exact
 `@frankzhang2026/opencode-android-orchestrator@0.1.0` entry, save the file and
 remove only that obsolete entry in a reviewed Git change before running
-`0.3.0 init`. The merger deliberately rejects a different version of the same
+`0.4.0 init`. The merger deliberately rejects a different version of the same
 managed package; it will not silently replace the reference. A global npm
 installation of `0.1.0` alone does not require project-file cleanup.
 
 After release, initialize with the fixed version:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.3.0 init .
+npx @frankzhang2026/opencode-android-orchestrator@0.4.0 init .
 ```
 
 New installations default to all-module scope, so multiple application modules
@@ -105,15 +105,15 @@ installer to guess which customization should survive.
 Use the lifecycle command selected by the active manifest:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.3.0 doctor . --json
-npx @frankzhang2026/opencode-android-orchestrator@0.3.0 upgrade . --json
+npx @frankzhang2026/opencode-android-orchestrator@0.4.0 doctor . --json
+npx @frankzhang2026/opencode-android-orchestrator@0.4.0 upgrade . --json
 ```
 
 `upgrade` verifies the installed manifest, every managed file, and every
 first-install backup before it creates recovery state. It reconstructs merged
 OpenCode and AGENTS content from the original pre-install files, carries that
 recovery lineage forward, snapshots the current version, writes the new
-resources, and reruns the 38 automation tests plus the shadow run.
+resources, and reruns the 42 automation tests plus the shadow run.
 
 Upgrade preserves an installed `androidProject.moduleScope`. A legacy
 manifest-managed configuration without that field is treated as `primary`,
@@ -138,7 +138,7 @@ the source of drift and use the recorded recovery data.
 Run all checks from the detected Git root:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.3.0 doctor .
+npx @frankzhang2026/opencode-android-orchestrator@0.4.0 doctor .
 opencode debug config
 opencode debug agent scheduled-planner
 opencode debug agent scheduled-coder
@@ -153,7 +153,7 @@ Verify all of the following before switching normal work to the plugin:
 - doctor has no failed check;
 - all three agents, four commands, and required skills are discoverable;
 - both read-only custom tools resolve for the scheduled agents;
-- the Shell suite ends with `1..38`;
+- the Shell suite ends with `1..42`;
 - shadow output contains `"mutationPerformed": false`;
 - `git status --short` contains only the reviewed installation diff;
 - no Git push, launchd registration, extra candidate worktree, or copied Android

package/docs/SECURITY.md

@@ -1,9 +1,9 @@
 # Security model
 
 This document describes the security properties of
-`@frankzhang2026/opencode-android-orchestrator@0.3.0`. The lifecycle foundation
+`@frankzhang2026/opencode-android-orchestrator@0.4.0`. The lifecycle foundation
 completed the real OpenCode `1.14.22` and `1.15.13` release matrix in `0.2.0`;
-`0.3.0` retains that compatibility boundary.
+`0.4.0` retains that compatibility boundary.
 
 ## Security goals and non-goals
 
@@ -52,7 +52,7 @@ modify local files; this package does not claim to protect against that actor.
 
 OpenCode permission prompts are also not semantic workflow approval. They can
 be accepted for the remainder of a session and may be auto-approved. For that
-reason `0.3.0` exposes only `android_orchestrator_status` and
+reason `0.4.0` exposes only `android_orchestrator_status` and
 `android_orchestrator_doctor` as custom tools. State-changing wrappers remain a
 NO-GO until a one-use, non-model-forgeable receipt can bind the approval kind,
 task, session/message, sealed SHA or branch, time, and nonce.
@@ -112,6 +112,13 @@ while Gradle settings/build files and orchestration resources remain protected.
 legacy configuration with no scope field as `primary`, preventing an implicit
 permission expansion.
 
+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
+KiB. Patterns, directories, duplicates, Git metadata, planning artifacts, and
+configured protected paths fail closed. The control file itself is protected
+and excluded from orchestration change views.
+
 The installed manifest is `0600`. Installer control, backup, recovery, and
 history directories are created with private `0700` defaults; backup files
 preserve the original file mode where recovery requires it. Shell resources
@@ -121,7 +128,7 @@ non-executable.
 ## Transaction and recovery safety
 
 `init` writes original-file backups before publishing a prepared manifest. It
-then applies validated files, runs the 38-case transaction suite and a shadow
+then applies validated files, runs the 42-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.
@@ -151,6 +158,13 @@ the recorded before/after hashes and Git refs.
   ready. Successful integration creates exactly one combined local commit.
 - Scope gates inspect tracked and untracked changes, reject protected paths and
   obvious test weakening, and bind the accepted result to a diff SHA.
+- An approved task snapshots the validated worktree allowlist. Listed local
+  changes are excluded consistently from cleanliness, scope, hashes, evidence,
+  archival, and commits; explicit commit pathsets preserve allowlisted staged
+  entries, and rename detection cannot hide an unlisted source path. Changing
+  the control file mid-task cannot widen the active snapshot. Status exposes
+  the effective list to Coder and Reviewer sessions and returns an empty list
+  inside isolated task worktrees.
 - Integration reruns verification before a fast-forward. It never pushes.
 - A successfully integrated task branch is deleted only after the original
   branch reaches the verified commit. Failure preserves the branch for
@@ -209,6 +223,9 @@ commit installer recovery data unless an explicit internal policy requires it.
   validating its storage and cleanup policy.
 - Recovery evidence improves auditability but increases local sensitive-data
   retention.
+- A human can intentionally hide a product-file change by allowlisting its
+  exact path. Such a file is outside the task's reviewed and committed result;
+  remove it from the list before any task that is expected to modify it.
 - Real dual-version end-to-end acceptance and a clean install from the final
   tarball remain mandatory release gates.
 

package/docs/TROUBLESHOOTING.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 Use this guide for
-`@frankzhang2026/opencode-android-orchestrator@0.3.0`.
+`@frankzhang2026/opencode-android-orchestrator@0.4.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.3.0 doctor . --json
+npx @frankzhang2026/opencode-android-orchestrator@0.4.0 doctor . --json
 ```
 
 If installation never completed, doctor will correctly report a missing or
@@ -60,6 +60,26 @@ plugins, required skills, agent permissions, and both read-only custom tools.
 If it fails, preserve its exact output. Do not broaden an agent's default-deny
 permissions to make discovery pass.
 
+## Worktree allowlist failures
+
+Use `.automation-worktree-allowlist` only for intentional local changes that
+must remain outside every task diff and commit. The file belongs in the Git
+repository root, with one exact repository-relative file path per line.
+
+| Symptom | Likely cause | Safe response |
+| --- | --- | --- |
+| `Git worktree is dirty` | At least one tracked or untracked change is not listed. | Inspect `git status --short`. Commit/revert the task-relevant change, or add only an intentionally local exact file path to the allowlist. |
+| `must be exact file paths, not patterns` | An entry contains `*`, `?`, or bracket syntax. | Replace it with each exact file path; directory-wide bypasses are intentionally unsupported. |
+| `must not include a protected path` or `reserved or unsafe` | The entry targets orchestration, Gradle, Git metadata, a plan, or another protected path. | Remove the entry. Protected control and planning files must remain visible to the gates. |
+| `must be a regular file, not a symlink` | The control file is a symlink or another unsupported file type. | Replace it with a small regular text file at the repository root. |
+| A task does not include a file you expected it to edit | The path was in the snapshot taken at contract approval. | Finish/abort the active task, remove the entry, then start and approve a new task. |
+| A local rename still blocks startup | Only the new or old name is listed. | Add both exact paths; rename detection treats the source deletion and destination addition independently. |
+
+The control file itself does not block orchestration and does not require a
+`.gitignore` entry for that purpose. Git may still display it in ordinary
+`git status`, which is separate from the orchestrator's filtered view. Staged
+allowlisted entries remain staged and are not consumed by task or abort commits.
+
 ## Installation conflicts
 
 Common fail-closed codes include:

package/package.json

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

package/templates/.opencode/agents/scheduled-coder.md

@@ -111,5 +111,8 @@ non-interactive run. If anything is ambiguous or blocked, stop and report the ex
 reason; the deterministic scripts own state transitions.
 
 You may edit only paths allowed both by this agent and by the task contract.
+Treat `.automation-worktree-allowlist` and the status JSON's
+`runtime.effectiveWorktreeAllowlist` paths as human-owned local state: never
+edit, stage, report, or use them as task evidence.
 Passing tests never grants permission to push, merge, create worktrees, alter
 automation rules, or declare the task ready for review yourself.

package/templates/.opencode/agents/scheduled-reviewer.md

@@ -82,7 +82,8 @@ The orchestrator message must contain exactly one task ID or the compatibility
 selector token `NEXT_REVIEWING`. Load
 `scheduled-quality-reviewer` before reviewing. Treat coder summaries as
 untrusted claims: inspect the approved contract, actual Git diff, and original
-evidence, then obtain fresh verification through the deterministic submission
-script. Never edit the repository and never repair findings yourself. Submit
-exactly one evidence-backed decision before spending steps on optional report
-navigation.
+evidence, excluding `.automation-worktree-allowlist` and the status JSON's
+`runtime.effectiveWorktreeAllowlist` paths from findings, then obtain fresh
+verification through the deterministic submission script. Never edit the
+repository and never repair findings yourself. Submit exactly one
+evidence-backed decision before spending steps on optional report navigation.

package/templates/.opencode/skills/scheduled-quality-coder/SKILL.md

@@ -35,11 +35,14 @@ it with `./scripts/automation/block-task.sh <TASK-ID> <reason>` before stopping.
 3. Branch by deterministic state:
 
    - For `PENDING`, run `./scripts/automation/claim-task.sh <TASK-ID>`. It
-     performs preflight, verifies that the only initial worktree changes are
-     the two sealed, uncommitted planning artifacts, captures the green
-     baseline, and changes the task to `CODING`. Never edit, stage, or remove
-     those planning artifacts; the integrator will include them in the final
-     combined commit.
+     performs preflight, verifies that the only orchestration-visible initial
+     changes are the two sealed, uncommitted planning artifacts, captures the
+     green baseline, and changes the task to `CODING`. The status JSON's
+     `runtime.effectiveWorktreeAllowlist` contains human-owned local paths that
+     are outside the task; do not edit, stage, report, or reason from those
+     paths or from `.automation-worktree-allowlist`. Never edit, stage, or
+     remove the planning artifacts; the integrator will include them in the
+     final combined commit.
    - For `CODING` with reviewer feedback, read `review.json` and implement only
      the requested in-contract repair. Do not claim again and do not replace
      the original RED evidence.
@@ -72,7 +75,8 @@ it with `./scripts/automation/block-task.sh <TASK-ID> <reason>` before stopping.
 Stop immediately when any of these occur:
 
 - requirement ambiguity or conflict;
-- any initial task-root change beyond the two sealed planning artifacts;
+- any orchestration-visible initial task-root change beyond the two sealed
+  planning artifacts;
 - missing plugin, skill, tool, device, or dependency;
 - a requested edit outside `allowedPaths` or inside protected paths;
 - no meaningful failing test can be written;

package/templates/.opencode/skills/scheduled-quality-reviewer/SKILL.md

@@ -28,10 +28,13 @@ you review.
    sealed-SHA comparison. Use that compact evidence object; do not try to read
    the external shared evidence directory or search generated Gradle report
    directories. Inspect the actual tracked product change with exactly
-   `git diff`. The plan and task contract remain uncommitted and are included
-   in the sealing scripts' full task SHA even when plain `git diff` does not
-   render those untracked files; their hashes are protected, and only product
-   paths count against `allowedPaths` and `maxChangedFiles`.
+   `git diff`, but exclude `.automation-worktree-allowlist` and every exact
+   path in `runtime.effectiveWorktreeAllowlist` from findings; they are
+   human-owned local state outside the sealed task. The plan and task contract
+   remain uncommitted and are included in the sealing scripts' full task SHA
+   even when plain `git diff` does not render those untracked files; their
+   hashes are protected, and only product paths count against `allowedPaths`
+   and `maxChangedFiles`.
 5. Check each acceptance criterion against observable behavior. Inspect for
    regression risk, missing edge cases, out-of-scope changes, test deletion,
    ignored tests, relaxed assertions, and implementation-shaped tests.

package/templates/AGENTS.md.fragment

@@ -13,6 +13,10 @@ and this managed block as orchestration infrastructure. Product tasks must not
 modify them unless an explicitly approved task is scoped to maintaining the
 orchestrator itself.
 
+`.automation-worktree-allowlist` is a human-maintained control file. Agents
+must not create or edit it. Its exact repository-relative file entries are
+excluded from orchestration changes for the next approved task.
+
 Only a fresh OpenCode single-choice `question` selection can grant an
 orchestration approval. Approval-like text in ordinary chat is not approval.
 The orchestrator must not push Git changes or register scheduler/launchd jobs.

package/templates/automation/config.json

@@ -47,6 +47,7 @@
     ]
   },
   "protectedPaths": [
+    ".automation-worktree-allowlist",
     ".opencode/",
     ".automation-plugin/",
     "automation/",

package/templates/automation/tasks/TASK-TEMPLATE.json.example

@@ -13,6 +13,7 @@
     "**/src/androidTest/**"
   ],
   "forbiddenPaths": [
+    ".automation-worktree-allowlist",
     ".opencode/**",
     ".automation-plugin/**",
     "automation/**",

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

@@ -59,6 +59,7 @@ if [[ -d "$task_root" ]]; then
         changed_paths=()
         changed_path_count=0
         product_path_count=0
+        changed_path_list="$(automation_changed_paths_at "$task_root")"
         while IFS= read -r path; do
             if [[ -n "$path" ]]; then
                 changed_paths+=("$path")
@@ -67,16 +68,10 @@ if [[ -d "$task_root" ]]; then
                     product_path_count=$((product_path_count + 1))
                 fi
             fi
-        done < <(automation_changed_paths_at "$task_root")
+        done <<< "$changed_path_list"
 
-        git -C "$task_root" status --short --branch > "$evidence_dir/abort-status.txt"
-        {
-            git -C "$task_root" diff --binary HEAD --
-            while IFS= read -r path; do
-                [[ -n "$path" ]] || continue
-                git -C "$task_root" diff --binary --no-index -- /dev/null "$task_root/$path" || [[ "$?" -eq 1 ]]
-            done < <(git -C "$task_root" ls-files --others --exclude-standard | LC_ALL=C sort)
-        } > "$evidence_dir/aborted.diff"
+        automation_worktree_status_at "$task_root" > "$evidence_dir/abort-status.txt"
+        automation_worktree_patch_at "$task_root" > "$evidence_dir/aborted.diff"
 
         if [[ "$changed_path_count" -gt 0 ]]; then
             for path in "${changed_paths[@]}"; do
@@ -92,7 +87,7 @@ if [[ -d "$task_root" ]]; then
             done
             if [[ "$product_path_count" -gt 0 ]]; then
                 git -C "$task_root" add -- "${changed_paths[@]}"
-                git -C "$task_root" commit -m "Archive aborted work for $task_id"
+                git -C "$task_root" commit --only -m "Archive aborted work for $task_id" -- "${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

@@ -134,7 +134,7 @@ 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 -m "Implement $title ($task_id)"
+git -C "$task_root" commit --only -m "Implement $title ($task_id)" -- "${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/acceptance-report.sh

@@ -52,17 +52,10 @@ while IFS= read -r path; do
 done < <(automation_product_changed_paths_at "$task_id" "$AUTOMATION_ROOT")
 changed_paths_json="$(printf '%s\n' "${changed_paths[@]}" | jq -Rsc 'split("\n") | map(select(length > 0))')"
 planning_artifacts_json="$(jq -c '[.planPath, .contractPath]' "$origin_file")"
-diff_stat="$(git -C "$AUTOMATION_ROOT" diff --stat HEAD --)"
-untracked_paths="$(git -C "$AUTOMATION_ROOT" ls-files --others --exclude-standard | LC_ALL=C sort)"
+diff_stat="$(automation_worktree_diff_stat_at "$AUTOMATION_ROOT")"
 
 sealed_diff="$evidence_dir/sealed.diff"
-{
-    git -C "$AUTOMATION_ROOT" diff --binary HEAD --
-    while IFS= read -r path; do
-        [[ -n "$path" ]] || continue
-        git -C "$AUTOMATION_ROOT" diff --binary --no-index -- /dev/null "$AUTOMATION_ROOT/$path" || [[ "$?" -eq 1 ]]
-    done <<< "$untracked_paths"
-} > "$sealed_diff"
+automation_worktree_patch_at "$AUTOMATION_ROOT" > "$sealed_diff"
 
 report_file="$evidence_dir/acceptance-report.json"
 jq -n \

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

@@ -48,6 +48,7 @@ for planning_path in "$plan_rel" "$contract_rel"; do
         automation_die "planning artifact must remain a new untracked file until the combined task commit: $planning_path"
     fi
 done
+worktree_allowlist_json="$(automation_worktree_allowlist_file_json_at "$source_root")"
 
 automation_require_command git
 automation_require_command jq
@@ -159,11 +160,13 @@ jq -n \
     --arg taskBranch "$task_branch" \
     --arg worktreeBase "$worktree_base" \
     --arg createdAt "$(automation_now)" \
+    --argjson worktreeAllowlist "$worktree_allowlist_json" \
     '{taskId: $taskId, sourceRoot: $sourceRoot, originalBranch: $originalBranch,
       baselineHead: $baselineHead, workspaceStrategy: $workspaceStrategy,
       taskRoot: $taskRoot, repositoryLeaseRequired: true,
       planningArtifactsCommitPolicy: "withProductChanges",
       taskBranch: $taskBranch, worktreeBase: $worktreeBase,
+      worktreeAllowlist: $worktreeAllowlist,
       codingCycle: 0, reviewCycles: 0, createdAt: $createdAt}' \
     | automation_record_json "$workspace_file"
 

package/templates/scripts/automation/lib.sh

@@ -47,6 +47,9 @@ AUTOMATION_STATE_DIR="$AUTOMATION_RUNTIME_ROOT/state"
 AUTOMATION_EVIDENCE_DIR="$AUTOMATION_RUNTIME_ROOT/evidence"
 AUTOMATION_LOCKS_DIR="$AUTOMATION_RUNTIME_ROOT/locks"
 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_info() {
     printf '[automation] %s\n' "$*"
@@ -383,12 +386,235 @@ automation_array_matches_path() {
     return 1
 }
 
+automation_validate_worktree_allowlist_entry_at() {
+    local root="$1"
+    local path="$2"
+    local config_file="$root/automation/config.json"
+    local protected
+
+    if [[ -z "$path" ]]; then
+        automation_die "worktree allowlist entries must not be empty"
+        return 1
+    fi
+    if [[ "$path" == [[:space:]]* || "$path" == *[[:space:]] ]]; then
+        automation_die "worktree allowlist entries must not have leading or trailing whitespace: $path"
+        return 1
+    fi
+    case "$path" in
+        *[[:cntrl:]]*|*'\\'*)
+            automation_die "worktree allowlist entries must use plain repository-relative paths: $path"
+            return 1
+            ;;
+        *'*'*|*'?'*|*'['*|*']'*)
+            automation_die "worktree allowlist entries must be exact file paths, not patterns: $path"
+            return 1
+            ;;
+    esac
+    case "/$path/" in
+        *'//'*|*'/./'*|*'/../'*)
+            automation_die "worktree allowlist entries must be normalized repository-relative paths: $path"
+            return 1
+            ;;
+    esac
+    case "$path" in
+        /*|./*|.|..|.git|.git/*|docs/plans|docs/plans/*|"$AUTOMATION_WORKTREE_ALLOWLIST_RELATIVE_PATH")
+            automation_die "worktree allowlist entry is reserved or unsafe: $path"
+            return 1
+            ;;
+    esac
+    if [[ -d "$root/$path" ]]; then
+        automation_die "worktree allowlist entries must identify files, not directories: $path"
+        return 1
+    fi
+
+    if [[ ! -f "$config_file" ]]; then
+        automation_die "missing automation configuration while validating worktree allowlist: $config_file"
+        return 1
+    fi
+    if ! jq -e '.protectedPaths | type == "array" and all(.[]; type == "string" and length > 0)' \
+        "$config_file" >/dev/null; then
+        automation_die "automation protectedPaths are invalid while validating the worktree allowlist"
+        return 1
+    fi
+    while IFS= read -r protected; do
+        if automation_path_matches "$path" "$protected"; then
+            automation_die "worktree allowlist must not include a protected path: $path"
+            return 1
+        fi
+    done < <(jq -r '.protectedPaths[]' "$config_file")
+    return 0
+}
+
+automation_worktree_allowlist_file_entries_at() {
+    local root="$1"
+    local allowlist_file="$root/$AUTOMATION_WORKTREE_ALLOWLIST_RELATIVE_PATH"
+    local byte_count line existing
+    local entry_count=0
+    local -a entries=()
+
+    if [[ ! -e "$allowlist_file" && ! -L "$allowlist_file" ]]; then
+        return 0
+    fi
+    if [[ -L "$allowlist_file" || ! -f "$allowlist_file" ]]; then
+        automation_die "worktree allowlist must be a regular file, not a symlink: $allowlist_file"
+        return 1
+    fi
+    byte_count="$(wc -c < "$allowlist_file" | tr -d '[:space:]')"
+    if [[ ! "$byte_count" =~ ^[0-9]+$ ]] || \
+       [[ "$byte_count" -gt "$AUTOMATION_WORKTREE_ALLOWLIST_MAX_BYTES" ]]; then
+        automation_die "worktree allowlist exceeds $AUTOMATION_WORKTREE_ALLOWLIST_MAX_BYTES bytes: $allowlist_file"
+        return 1
+    fi
+
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        line="${line%$'\r'}"
+        [[ -n "$line" && "$line" != \#* ]] || continue
+        automation_validate_worktree_allowlist_entry_at "$root" "$line" || return 1
+        if [[ "$entry_count" -gt 0 ]]; then
+            for existing in "${entries[@]}"; do
+                if [[ "$existing" == "$line" ]]; then
+                    automation_die "duplicate worktree allowlist entry: $line"
+                    return 1
+                fi
+            done
+        fi
+        entry_count=$((entry_count + 1))
+        if [[ "$entry_count" -gt "$AUTOMATION_WORKTREE_ALLOWLIST_MAX_ENTRIES" ]]; then
+            automation_die "worktree allowlist exceeds $AUTOMATION_WORKTREE_ALLOWLIST_MAX_ENTRIES entries"
+            return 1
+        fi
+        entries[${#entries[@]}]="$line"
+    done < "$allowlist_file"
+
+    if [[ "$entry_count" -gt 0 ]]; then
+        for line in "${entries[@]}"; do
+            printf '%s\n' "$line"
+        done
+    fi
+    return 0
+}
+
+automation_worktree_allowlist_entries_json() {
+    local entries="$1"
+    if [[ -z "$entries" ]]; then
+        printf '[]\n'
+    else
+        printf '%s\n' "$entries" | jq -Rsc 'split("\n") | map(select(length > 0))'
+    fi
+}
+
+automation_worktree_allowlist_file_json_at() {
+    local root="$1"
+    local entries
+    entries="$(automation_worktree_allowlist_file_entries_at "$root")" || return 1
+    automation_worktree_allowlist_entries_json "$entries"
+}
+
+automation_effective_worktree_allowlist_entries_at() {
+    local root="$1"
+    local resolved_root
+    local lease_file="$AUTOMATION_LOCKS_DIR/repository.workspace.lease/lease.json"
+    local task_id workspace_file source_root task_root resolved_source resolved_task entry
+
+    resolved_root="$(cd "$root" && pwd -P)" || {
+        automation_die "unable to resolve worktree root for allowlist: $root"
+        return 1
+    }
+    if [[ -f "$lease_file" ]]; then
+        task_id="$(jq -er '.taskId' "$lease_file")" || {
+            automation_die "repository lease is invalid while resolving the worktree allowlist"
+            return 1
+        }
+        workspace_file="$(automation_workspace_path "$task_id")"
+        if [[ -f "$workspace_file" ]] && jq -e 'has("worktreeAllowlist")' "$workspace_file" >/dev/null; then
+            jq -e \
+                --argjson max "$AUTOMATION_WORKTREE_ALLOWLIST_MAX_ENTRIES" \
+                '.worktreeAllowlist as $entries |
+                 ($entries | type == "array") and
+                 ($entries | length <= $max) and
+                 ($entries | length == (unique | length)) and
+                 all($entries[]; type == "string" and length > 0)' \
+                "$workspace_file" >/dev/null || {
+                    automation_die "workspace worktreeAllowlist snapshot is invalid: $workspace_file"
+                    return 1
+                }
+            source_root="$(jq -er '.sourceRoot' "$workspace_file")" || return 1
+            task_root="$(automation_workspace_task_root "$workspace_file")" || return 1
+            resolved_source="$(cd "$source_root" 2>/dev/null && pwd -P || true)"
+            resolved_task="$(cd "$task_root" 2>/dev/null && pwd -P || true)"
+            if [[ "$resolved_root" == "$resolved_source" ]]; then
+                while IFS= read -r entry; do
+                    [[ -n "$entry" ]] || continue
+                    automation_validate_worktree_allowlist_entry_at "$root" "$entry" || return 1
+                    printf '%s\n' "$entry"
+                done < <(jq -r '.worktreeAllowlist[]' "$workspace_file")
+                return 0
+            fi
+            if [[ "$resolved_root" == "$resolved_task" ]]; then
+                return 0
+            fi
+        fi
+    fi
+
+    automation_worktree_allowlist_file_entries_at "$root"
+}
+
+automation_effective_worktree_allowlist_json_at() {
+    local root="$1"
+    local entries
+    entries="$(automation_effective_worktree_allowlist_entries_at "$root")" || return 1
+    automation_worktree_allowlist_entries_json "$entries"
+}
+
+automation_worktree_path_is_allowlisted() {
+    local path="$1"
+    local entries="$2"
+    local entry
+
+    [[ "$path" == "$AUTOMATION_WORKTREE_ALLOWLIST_RELATIVE_PATH" ]] && return 0
+    while IFS= read -r entry; do
+        [[ -n "$entry" ]] || continue
+        [[ "$path" == "$entry" ]] && return 0
+    done <<< "$entries"
+    return 1
+}
+
+automation_filter_worktree_paths_at() {
+    local root="$1"
+    local paths="$2"
+    local allowlist path
+
+    allowlist="$(automation_effective_worktree_allowlist_entries_at "$root")" || return 1
+    while IFS= read -r path; do
+        [[ -n "$path" ]] || continue
+        if ! automation_worktree_path_is_allowlisted "$path" "$allowlist"; then
+            printf '%s\n' "$path"
+        fi
+    done <<< "$paths"
+    return 0
+}
+
+automation_tracked_changed_paths_at() {
+    local root="$1"
+    local paths
+    paths="$(git -C "$root" diff --no-renames --name-only HEAD -- | LC_ALL=C sort -u)" || return 1
+    automation_filter_worktree_paths_at "$root" "$paths"
+}
+
+automation_untracked_paths_at() {
+    local root="$1"
+    local paths
+    paths="$(git -C "$root" ls-files --others --exclude-standard | LC_ALL=C sort -u)" || return 1
+    automation_filter_worktree_paths_at "$root" "$paths"
+}
+
 automation_changed_paths_at() {
     local root="$1"
-    {
-        git -C "$root" diff --name-only HEAD --
-        git -C "$root" ls-files --others --exclude-standard
-    } | LC_ALL=C sort -u
+    local tracked untracked
+
+    tracked="$(automation_tracked_changed_paths_at "$root")" || return 1
+    untracked="$(automation_untracked_paths_at "$root")" || return 1
+    printf '%s\n%s\n' "$tracked" "$untracked" | awk 'NF' | LC_ALL=C sort -u
 }
 
 automation_changed_paths() {
@@ -461,20 +687,71 @@ automation_changed_paths_between() {
 
 automation_worktree_diff_sha() {
     local root="${1:-$AUTOMATION_ROOT}"
-    local path
+    local tracked_paths untracked_paths path
+    tracked_paths="$(automation_tracked_changed_paths_at "$root")" || return 1
+    untracked_paths="$(automation_untracked_paths_at "$root")" || return 1
     {
-        git -C "$root" diff --binary HEAD --
+        while IFS= read -r path; do
+            [[ -n "$path" ]] || continue
+            git -C "$root" diff --binary --no-renames HEAD -- "$path"
+        done <<< "$tracked_paths"
         while IFS= read -r path; do
             [[ -n "$path" ]] || continue
             printf 'UNTRACKED %s\0' "$path"
             git -C "$root" hash-object -- "$path"
-        done < <(git -C "$root" ls-files --others --exclude-standard | LC_ALL=C sort)
+        done <<< "$untracked_paths"
     } | shasum -a 256 | awk '{print $1}'
 }
 
+automation_worktree_diff_stat_at() {
+    local root="${1:-$AUTOMATION_ROOT}"
+    local tracked_paths path
+    local -a paths=()
+
+    tracked_paths="$(automation_tracked_changed_paths_at "$root")" || return 1
+    while IFS= read -r path; do
+        [[ -n "$path" ]] && paths[${#paths[@]}]="$path"
+    done <<< "$tracked_paths"
+    if [[ "${#paths[@]}" -gt 0 ]]; then
+        git -C "$root" diff --stat --no-renames HEAD -- "${paths[@]}"
+    fi
+    return 0
+}
+
+automation_worktree_patch_at() {
+    local root="${1:-$AUTOMATION_ROOT}"
+    local tracked_paths untracked_paths path
+
+    tracked_paths="$(automation_tracked_changed_paths_at "$root")" || return 1
+    untracked_paths="$(automation_untracked_paths_at "$root")" || return 1
+    while IFS= read -r path; do
+        [[ -n "$path" ]] || continue
+        git -C "$root" diff --binary --no-renames HEAD -- "$path"
+    done <<< "$tracked_paths"
+    while IFS= read -r path; do
+        [[ -n "$path" ]] || continue
+        git -C "$root" diff --binary --no-index -- /dev/null "$root/$path" || [[ "$?" -eq 1 ]]
+    done <<< "$untracked_paths"
+    return 0
+}
+
+automation_worktree_status_at() {
+    local root="${1:-$AUTOMATION_ROOT}"
+    local changed_paths path
+
+    changed_paths="$(automation_changed_paths_at "$root")" || return 1
+    printf 'branch %s\n' "$(automation_current_branch "$root")"
+    while IFS= read -r path; do
+        [[ -n "$path" ]] && printf 'changed %s\n' "$path"
+    done <<< "$changed_paths"
+    return 0
+}
+
 automation_worktree_is_clean() {
     local root="${1:-$AUTOMATION_ROOT}"
-    [[ -z "$(git -C "$root" status --porcelain --untracked-files=all)" ]]
+    local changed_paths
+    changed_paths="$(automation_changed_paths_at "$root")" || return 1
+    [[ -z "$changed_paths" ]]
 }
 
 automation_create_lock_dir() {

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

@@ -86,7 +86,7 @@ for _step in 1 2 3 4 5 6 7 8; do
             if [[ -f "$agent_runs" ]]; then
                 review_attempt="$(jq -s --argjson cycle "$review_cycle" '[.[] | select(.role == "scheduled-reviewer" and .cycle == $cycle)] | length' "$agent_runs")"
             fi
-            reviewer_prompt="Use \$scheduled-quality-reviewer with $task_id. This is fresh, non-interactive, read-only review attempt $review_attempt for sealed review cycle $review_cycle. Work within the step budget. Run exactly ./scripts/automation/status.sh $task_id once; its JSON already includes baseline, RED, ready, latest gate, current diff SHA, and the sealed-SHA comparison, so do not browse the external evidence directory. Then inspect the approved contract and run exactly git diff. Submit exactly one decision. Do not browse generated build reports, list the whole repository, retry denied command variants, or run Gradle commands separately before deciding: submit-review.sh performs and records the focused tests, full unit suite, assembleDebug, and lint for APPROVED. Reserve a tool call for submit-review.sh. Never edit, commit, merge, or push."
+            reviewer_prompt="Use \$scheduled-quality-reviewer with $task_id. This is fresh, non-interactive, read-only review attempt $review_attempt for sealed review cycle $review_cycle. Work within the step budget. Run exactly ./scripts/automation/status.sh $task_id once; its JSON already includes baseline, RED, ready, latest gate, current diff SHA, the sealed-SHA comparison, and runtime.effectiveWorktreeAllowlist, so do not browse the external evidence directory. Then inspect the approved contract and run exactly git diff, excluding the control file and every exact path in that effective list from review findings. Submit exactly one decision. Do not browse generated build reports, list the whole repository, retry denied command variants, or run Gradle commands separately before deciding: submit-review.sh performs and records the focused tests, full unit suite, assembleDebug, and lint for APPROVED. Reserve a tool call for submit-review.sh. Never edit, commit, merge, or push."
             run_agent scheduled-reviewer "$reviewer_prompt" "$review_cycle" "$review_attempt" || true
             if [[ "$(automation_read_state "$task_id")" == "REVIEWING" ]]; then
                 automation_transition_state "$task_id" "REVIEWING" "BLOCKED" "orchestrator" "reviewer exited without submitting a decision; sealed diff preserved for reviewer-only recovery"

package/templates/scripts/automation/scope-gate.sh

@@ -64,12 +64,13 @@ while IFS= read -r path; do
 done <<< "$changed_file_list"
 
 deleted_tests="$(
-    git -C "$AUTOMATION_ROOT" diff --name-only --diff-filter=D HEAD -- \
-        | while IFS= read -r path; do
-            if automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$path"; then
-                printf '%s\n' "$path"
-            fi
-        done
+    while IFS= read -r path; do
+        [[ -n "$path" ]] || continue
+        if [[ -n "$(git -C "$AUTOMATION_ROOT" diff --no-renames --name-only --diff-filter=D HEAD -- "$path")" ]] && \
+           automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$path"; then
+            printf '%s\n' "$path"
+        fi
+    done <<< "$changed_file_list"
 )"
 [[ -z "$deleted_tests" ]] || { automation_die "test deletion is forbidden: $deleted_tests"; exit 40; }
 
@@ -83,7 +84,7 @@ added_test_lines="$(
     while IFS= read -r path; do
         [[ -n "$path" ]] || continue
         if automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$path"; then
-            git -C "$AUTOMATION_ROOT" diff --unified=0 HEAD -- "$path"
+            git -C "$AUTOMATION_ROOT" diff --no-renames --unified=0 HEAD -- "$path"
         fi
     done <<< "$changed_file_list" \
         | awk '/^\+\+\+/ { next } /^\+/ { sub(/^\+/, ""); print }'
@@ -95,12 +96,14 @@ if printf '%s\n' "$added_test_lines" | rg -n "$weakening_pattern" >/dev/null; th
 fi
 
 while IFS= read -r untracked_test; do
-    if automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$untracked_test" && \
+    [[ -n "$untracked_test" ]] || continue
+    if ! git -C "$AUTOMATION_ROOT" ls-files --error-unmatch -- "$untracked_test" >/dev/null 2>&1 && \
+       automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$untracked_test" && \
         rg -n "$weakening_pattern" "$AUTOMATION_ROOT/$untracked_test" >/dev/null; then
         automation_die "potential test weakening detected in new test: $untracked_test"
         exit 40
     fi
-done < <(git -C "$AUTOMATION_ROOT" ls-files --others --exclude-standard)
+done <<< "$changed_file_list"
 
 if [[ "$planning_commit_policy" == "withProductChanges" ]]; then
     automation_info "scope gate passed ($changed_count product files; sealed planning artifacts excluded from the contract limit)"

package/templates/scripts/automation/status.sh

@@ -33,6 +33,7 @@ if [[ "$ready_json" != "null" ]]; then
 fi
 
 current_diff_sha=""
+effective_worktree_allowlist_json='[]'
 lease_json=null
 lease_matches=null
 original_head_current=""
@@ -41,6 +42,7 @@ task_branch_exists=null
 if [[ "$workspace_json" != "null" ]]; then
     task_root="$(jq -r '.taskRoot // .taskWorktree // empty' <<< "$workspace_json")"
     if [[ -n "$task_root" && -d "$task_root" ]]; then
+        effective_worktree_allowlist_json="$(automation_effective_worktree_allowlist_json_at "$task_root")"
         current_diff_sha="$(automation_worktree_diff_sha "$task_root")"
     fi
     source_root="$(jq -r '.sourceRoot // empty' <<< "$workspace_json")"
@@ -97,6 +99,7 @@ jq -n \
     --argjson repositoryLease "$lease_json" \
     --argjson repositoryLeaseMatches "$lease_matches" \
     --argjson taskBranchExists "$task_branch_exists" \
+    --argjson effectiveWorktreeAllowlist "$effective_worktree_allowlist_json" \
     --arg originalHeadCurrent "$original_head_current" \
     --argjson originalBranchDrifted "$original_branch_drifted" \
     --arg evidence "$evidence_dir" \
@@ -106,6 +109,7 @@ jq -n \
         repositoryLease: $repositoryLease,
         repositoryLeaseMatches: $repositoryLeaseMatches,
         taskBranchExists: $taskBranchExists,
+        effectiveWorktreeAllowlist: $effectiveWorktreeAllowlist,
         originalHeadCurrent: ($originalHeadCurrent | if length == 0 then null else . end),
         originalBranchDrifted: $originalBranchDrifted
       },

package/templates/scripts/automation/tests/run-tests.sh

@@ -82,6 +82,7 @@ write_workspace() {
 mkdir -p \
     "$fixture/automation/tasks" \
     "$fixture/docs/plans" \
+    "$fixture/local" \
     "$fixture/scripts/automation" \
     "$fixture/mobile-client/src/main/java/dev/example/orchestratorfixture" \
     "$fixture/mobile-client/src/test/java/dev/example/orchestratorfixture"
@@ -89,6 +90,8 @@ mkdir -p \
 cp "$SOURCE_SCRIPT_DIR"/*.sh "$fixture/scripts/automation/"
 chmod +x "$fixture/scripts/automation/"*.sh
 printf '%s\n' '# Approved test plan' > "$fixture/docs/plans/TASK-TEST-001.md"
+printf '%s\n' 'operator baseline' > "$fixture/local/operator-note.txt"
+printf '%s\n' 'rename baseline' > "$fixture/local/rename-source.txt"
 printf '%s\n' 'class ExistingFeature' > "$fixture/mobile-client/src/main/java/dev/example/orchestratorfixture/ExistingFeature.kt"
 
 printf '%s\n' \
@@ -166,6 +169,7 @@ jq -n '{
         ]
     },
     protectedPaths: [
+        ".automation-worktree-allowlist",
         ".opencode/",
         ".automation-plugin/",
         "automation/",
@@ -200,6 +204,7 @@ jq -n '{
         "mobile-client/src/test/java/dev/example/orchestratorfixture/**"
     ],
     forbiddenPaths: [
+        ".automation-worktree-allowlist",
         ".opencode/**",
         ".automation-plugin/**",
         "automation/**",
@@ -243,6 +248,74 @@ jq -n '{
     git commit -qm 'Create automation fixture'
 )
 
+printf '%s\n' \
+    '# Exact repository-relative paths intentionally kept local' \
+    'local/operator-note.txt' \
+    'local/generated-note.txt' \
+    > "$fixture/.automation-worktree-allowlist"
+printf '%s\n' 'operator local edit' > "$fixture/local/operator-note.txt"
+printf '%s\n' 'generated local state' > "$fixture/local/generated-note.txt"
+run_fixture ./scripts/automation/preflight.sh --source >/dev/null
+allowlisted_changes="$(run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_changed_paths')"
+[[ -z "$allowlisted_changes" ]] || fail "allowlisted paths remained visible: $allowlisted_changes"
+
+printf '%s\n' \
+    'local/operator-note.txt' \
+    'local/generated-note.txt' \
+    'local/rename-target.txt' \
+    > "$fixture/.automation-worktree-allowlist"
+git -C "$fixture" mv local/rename-source.txt local/rename-target.txt
+rename_changes="$(run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_changed_paths')"
+[[ "$rename_changes" == "local/rename-source.txt" ]] || \
+    fail "an allowlisted rename target hid its non-allowlisted source: $rename_changes"
+git -C "$fixture" mv local/rename-target.txt local/rename-source.txt
+printf '%s\n' \
+    '# Exact repository-relative paths intentionally kept local' \
+    'local/operator-note.txt' \
+    'local/generated-note.txt' \
+    > "$fixture/.automation-worktree-allowlist"
+pass 'exact tracked and untracked entries are ignored without hiding rename sources'
+
+printf '%s\n' 'must still block' > "$fixture/unapproved-change.txt"
+if run_fixture ./scripts/automation/preflight.sh --source >/dev/null 2>&1; then
+    fail 'preflight ignored a path that was not allowlisted'
+fi
+rm "$fixture/unapproved-change.txt"
+pass 'a non-allowlisted worktree change still blocks orchestration startup'
+
+printf '%s\n' 'automation/config.json' > "$fixture/.automation-worktree-allowlist"
+if run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_changed_paths >/dev/null' 2>/dev/null; then
+    fail 'worktree allowlist accepted a protected automation path'
+fi
+printf '%s\n' 'local/*.json' > "$fixture/.automation-worktree-allowlist"
+if run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_changed_paths >/dev/null' 2>/dev/null; then
+    fail 'worktree allowlist accepted a glob pattern'
+fi
+printf '%s\n' 'local' > "$fixture/.automation-worktree-allowlist"
+if run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_changed_paths >/dev/null' 2>/dev/null; then
+    fail 'worktree allowlist accepted a directory path'
+fi
+printf '%s\n' 'local/operator-note.txt' 'local/operator-note.txt' > "$fixture/.automation-worktree-allowlist"
+if run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_changed_paths >/dev/null' 2>/dev/null; then
+    fail 'worktree allowlist accepted duplicate entries'
+fi
+printf '%s\n' '../outside.txt' > "$fixture/.automation-worktree-allowlist"
+if run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_changed_paths >/dev/null' 2>/dev/null; then
+    fail 'worktree allowlist accepted a path outside the repository'
+fi
+rm "$fixture/.automation-worktree-allowlist"
+ln -s local/operator-note.txt "$fixture/.automation-worktree-allowlist"
+if run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_changed_paths >/dev/null' 2>/dev/null; then
+    fail 'worktree allowlist accepted a symbolic-link control file'
+fi
+rm "$fixture/.automation-worktree-allowlist"
+printf '%s\n' \
+    '# Exact repository-relative paths intentionally kept local' \
+    'local/operator-note.txt' \
+    'local/generated-note.txt' \
+    > "$fixture/.automation-worktree-allowlist"
+pass 'invalid, duplicate, symbolic-link, patterned, and protected allowlist input fails closed'
+
 run_fixture ./scripts/automation/validate-contract.sh TASK-TEST-001 >/dev/null
 pass 'valid version-3 configuration and task contract are accepted'
 
@@ -500,6 +573,8 @@ approved_baseline="$(jq -er '.baselineHead' "$runtime_root/workspaces/TASK-TEST-
 leased_status="$(run_fixture ./scripts/automation/status.sh TASK-TEST-004)"
 [[ "$(jq -r '.runtime.repositoryLeaseMatches' <<< "$leased_status")" == "true" ]] || fail 'status did not verify the repository lease'
 [[ "$(jq -r '.runtime.originalBranchDrifted' <<< "$leased_status")" == "false" ]] || fail 'status reported false branch drift'
+[[ "$(jq -c '.runtime.effectiveWorktreeAllowlist' <<< "$leased_status")" == '["local/operator-note.txt","local/generated-note.txt"]' ]] || \
+    fail 'status did not expose the approved in-place allowlist snapshot'
 if run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_acquire_repository_lease TASK-TEST-999 "$PWD" inPlaceExclusive' >/dev/null 2>&1; then
     fail 'a second task acquired the persistent repository lease'
 fi
@@ -508,6 +583,10 @@ pass 'persistent repository lease rejects a concurrent automation task'
 [[ "$(jq -r '.state' "$runtime_root/state/TASK-TEST-004.json")" == "PENDING" ]] || fail 'prepared task did not become PENDING'
 pass 'contract approval switches to a leased task branch while deferring the sealed plan and contract to the product commit'
 
+git -C "$fixture" add -- \
+    .automation-worktree-allowlist \
+    local/operator-note.txt \
+    local/generated-note.txt
 run_task "$task_root" ./scripts/automation/claim-task.sh TASK-TEST-004 >/dev/null
 printf '%s\n' 'class OrchestratedFlowTest { fun expectedBehavior() = Unit }' > "$task_root/mobile-client/src/test/java/dev/example/orchestratorfixture/OrchestratedFlowTest.kt"
 run_task "$task_root" ./scripts/automation/record-red.sh TASK-TEST-004 'expected missing behavior' -- dev.example.orchestratorfixture.OrchestratedFlowTest >/dev/null
@@ -517,6 +596,15 @@ run_task "$task_root" ./scripts/automation/begin-review.sh TASK-TEST-004 >/dev/n
 run_task "$task_root" env AUTOMATION_FAKE_GREEN=1 ./scripts/automation/submit-review.sh TASK-TEST-004 APPROVED 'Fresh review confirms the sealed behavior and scope.' >/dev/null
 run_task "$task_root" ./scripts/automation/acceptance-report.sh TASK-TEST-004 >/dev/null
 [[ "$(jq -r '.changedPaths | length' "$runtime_root/evidence/TASK-TEST-004/acceptance-report.json")" -eq 2 ]] || fail 'acceptance package omitted product paths'
+if jq -e '.changedPaths | any(. == "local/operator-note.txt" or . == "local/generated-note.txt")' \
+    "$runtime_root/evidence/TASK-TEST-004/acceptance-report.json" >/dev/null; then
+    fail 'acceptance package included an allowlisted local path'
+fi
+if rg -F 'diff --git a/local/operator-note.txt b/local/operator-note.txt' "$runtime_root/evidence/TASK-TEST-004/sealed.diff" >/dev/null || \
+   rg -F 'diff --git a/local/generated-note.txt b/local/generated-note.txt' "$runtime_root/evidence/TASK-TEST-004/sealed.diff" >/dev/null || \
+   rg -F 'diff --git a/.automation-worktree-allowlist b/.automation-worktree-allowlist' "$runtime_root/evidence/TASK-TEST-004/sealed.diff" >/dev/null; then
+    fail 'sealed diff included allowlisted local content'
+fi
 [[ "$(jq -r '.evidence.qualityGate' "$runtime_root/evidence/TASK-TEST-004/acceptance-report.json")" == "PASSED" ]] || fail 'acceptance package omitted quality-gate status'
 acceptance_card="$(run_fixture ./scripts/automation/show-acceptance-review.sh TASK-TEST-004)"
 [[ "$acceptance_card" == *"人工验收提醒"* ]] || fail 'acceptance review did not actively identify the human gate'
@@ -555,6 +643,27 @@ for combined_path in \
         awk -v expected="$combined_path" '$0 == expected { found = 1 } END { exit !found }' || \
         fail "combined task commit omitted $combined_path"
 done
+if git -C "$fixture" diff-tree --no-commit-id --name-only -r "$combined_commit" | \
+    rg -x 'local/(operator-note|generated-note)\.txt|\.automation-worktree-allowlist' >/dev/null; then
+    fail 'combined task commit included an allowlisted local path or its control file'
+fi
+[[ "$(cat "$fixture/local/operator-note.txt")" == "operator local edit" ]] || fail 'tracked allowlisted content changed during integration'
+[[ "$(cat "$fixture/local/generated-note.txt")" == "generated local state" ]] || fail 'untracked allowlisted content changed during integration'
+staged_allowlist_paths="$(git -C "$fixture" diff --cached --name-only HEAD -- | LC_ALL=C sort)"
+for staged_allowlist_path in \
+    .automation-worktree-allowlist \
+    local/generated-note.txt \
+    local/operator-note.txt; do
+    printf '%s\n' "$staged_allowlist_paths" | \
+        awk -v expected="$staged_allowlist_path" '$0 == expected { found = 1 } END { exit !found }' || \
+        fail "integration consumed a staged allowlisted path: $staged_allowlist_path"
+done
+run_fixture bash -c 'source ./scripts/automation/lib.sh; automation_worktree_is_clean' || fail 'allowlisted local state made the integrated source root dirty'
+pass 'in-place integration preserves allowlisted local state without evidence or commit leakage'
+git -C "$fixture" restore --staged -- \
+    .automation-worktree-allowlist \
+    local/operator-note.txt \
+    local/generated-note.txt
 [[ "$(jq -r '.contractCommit' "$runtime_root/evidence/TASK-TEST-004/origin.json")" == "$combined_commit" ]] || fail 'origin evidence did not bind the contract to the combined task commit'
 [[ "$(jq -r '.pushed' "$runtime_root/evidence/TASK-TEST-004/integration.json")" == "false" ]] || fail 'integration evidence did not forbid push'
 [[ "$(jq -r '.method' "$runtime_root/evidence/TASK-TEST-004/integration.json")" == "inPlaceExclusive-fast-forward" ]] || fail 'integration did not use the in-place fast-forward path'
@@ -579,6 +688,10 @@ jq \
     > "$fixture/automation/tasks/TASK-TEST-008.json"
 run_fixture ./scripts/automation/prepare-contract-review.sh TASK-TEST-008 '批准方案，生成计划和任务合同。' >/dev/null
 run_fixture env AUTOMATION_SKIP_AGENT_RUN=1 ./scripts/automation/approve-and-run.sh TASK-TEST-008 '合同已复核，批准自动执行到人工验收阶段。' >/dev/null
+git -C "$fixture" add -- \
+    .automation-worktree-allowlist \
+    local/operator-note.txt \
+    local/generated-note.txt
 printf '%s\n' 'class AbortArchive { fun value() = "preserved" }' > "$fixture/mobile-client/src/main/java/dev/example/orchestratorfixture/AbortArchive.kt"
 printf '%s\n' 'must not be archived automatically' > "$fixture/out-of-contract.txt"
 if run_fixture ./scripts/automation/abort-task.sh TASK-TEST-008 '中止任务，封存修改并恢复原分支。' >/dev/null 2>&1; then
@@ -592,10 +705,27 @@ abort_recovery_commit="$(jq -er '.recoveryCommit' "$runtime_root/evidence/TASK-T
 git -C "$fixture" cat-file -e "$abort_recovery_commit:mobile-client/src/main/java/dev/example/orchestratorfixture/AbortArchive.kt" || fail 'abort recovery commit omitted the allowed change'
 git -C "$fixture" cat-file -e "$abort_recovery_commit:docs/plans/TASK-TEST-008.md" || fail 'abort recovery commit omitted the sealed plan'
 git -C "$fixture" cat-file -e "$abort_recovery_commit:automation/tasks/TASK-TEST-008.json" || fail 'abort recovery commit omitted the sealed contract'
+if git -C "$fixture" diff-tree --no-commit-id --name-only -r "$abort_recovery_commit" | \
+    rg -x 'local/(operator-note|generated-note)\.txt|\.automation-worktree-allowlist' >/dev/null; then
+    fail 'abort recovery commit included an allowlisted local path or its control file'
+fi
+staged_abort_allowlist_paths="$(git -C "$fixture" diff --cached --name-only HEAD -- | LC_ALL=C sort)"
+for staged_allowlist_path in \
+    .automation-worktree-allowlist \
+    local/generated-note.txt \
+    local/operator-note.txt; do
+    printf '%s\n' "$staged_abort_allowlist_paths" | \
+        awk -v expected="$staged_allowlist_path" '$0 == expected { found = 1 } END { exit !found }' || \
+        fail "abort consumed a staged allowlisted path: $staged_allowlist_path"
+done
 [[ ! -f "$fixture/mobile-client/src/main/java/dev/example/orchestratorfixture/AbortArchive.kt" ]] || fail 'abort left archived code on the original branch'
 [[ "$(jq -r '.state' "$runtime_root/state/TASK-TEST-008.json")" == "ABORTED" ]] || fail 'allowed abort did not reach ABORTED'
 [[ ! -d "$runtime_root/locks/repository.workspace.lease" ]] || fail 'allowed abort did not release the repository lease'
 pass 'abort refuses unrelated files and archives allowed uncommitted changes in a recovery commit'
+git -C "$fixture" restore --staged -- \
+    .automation-worktree-allowlist \
+    local/operator-note.txt \
+    local/generated-note.txt
 
 planning_only_baseline="$(git -C "$fixture" rev-parse HEAD)"
 printf '%s\n' '# Planning-only abort plan' > "$fixture/docs/plans/TASK-TEST-009.md"
@@ -635,9 +765,17 @@ run_fixture ./scripts/automation/prepare-contract-review.sh TASK-TEST-007 '批
 run_fixture env AUTOMATION_SKIP_AGENT_RUN=1 ./scripts/automation/approve-and-run.sh TASK-TEST-007 '合同已复核，批准自动执行到人工验收阶段。' >/dev/null
 isolated_task_root="$(jq -er '.taskRoot' "$runtime_root/workspaces/TASK-TEST-007.json")"
 [[ "$isolated_task_root" != "$fixture" && -d "$isolated_task_root" ]] || fail 'optional isolated strategy did not create a separate task root'
+[[ "$(jq -r '.worktreeAllowlist | length' "$runtime_root/workspaces/TASK-TEST-007.json")" -eq 2 ]] || fail 'isolated workspace did not retain the approved allowlist snapshot'
 [[ -f "$isolated_task_root/docs/plans/TASK-TEST-007.md" && -f "$isolated_task_root/automation/tasks/TASK-TEST-007.json" ]] || fail 'isolated task root did not receive the sealed planning artifacts'
 [[ ! -e "$fixture/docs/plans/TASK-TEST-007.md" && ! -e "$fixture/automation/tasks/TASK-TEST-007.json" ]] || fail 'isolated preparation left duplicate planning artifacts in the source root'
 [[ "$(git -C "$fixture" worktree list --porcelain | awk '/^worktree / { count++ } END { print count + 0 }')" -eq 2 ]] || fail 'isolated strategy created more than one additional worktree'
+isolated_status="$(run_task "$isolated_task_root" ./scripts/automation/status.sh TASK-TEST-007)"
+[[ "$(jq -c '.runtime.effectiveWorktreeAllowlist' <<< "$isolated_status")" == '[]' ]] || \
+    fail 'status applied the source allowlist inside an isolated task root'
+printf '%s\n' 'task-local edit must stay visible' > "$isolated_task_root/local/operator-note.txt"
+isolated_visible_paths="$(run_task "$isolated_task_root" bash -c 'source ./scripts/automation/lib.sh; automation_changed_paths')"
+printf '%s\n' "$isolated_visible_paths" | rg -x 'local/operator-note.txt' >/dev/null || fail 'source allowlist hid a task-local isolated-worktree edit'
+git -C "$isolated_task_root" restore -- local/operator-note.txt
 run_task "$isolated_task_root" ./scripts/automation/claim-task.sh TASK-TEST-007 >/dev/null
 printf '%s\n' 'class IsolatedFlowTest { fun expectedBehavior() = Unit }' > "$isolated_task_root/mobile-client/src/test/java/dev/example/orchestratorfixture/IsolatedFlowTest.kt"
 run_task "$isolated_task_root" ./scripts/automation/record-red.sh TASK-TEST-007 'expected missing behavior' -- dev.example.orchestratorfixture.IsolatedFlowTest >/dev/null