apphx 2.0.0 → 2.1.0

package/examples/uni-app.factory.json

@@ -4,15 +4,68 @@
   "allowLocalExecution": false,
   "allowCloudBuild": false,
   "packageTarget": "aab",
-  "executionEnv": ["ANDROID_HOME", "ANDROID_DEVICE_ID"],
+  "obfuscation": {
+    "options": {
+      "code": {
+        "removeComments": true
+      }
+    }
+  },
+  "executionEnv": [
+    "ANDROID_HOME",
+    "ANDROID_DEVICE_ID"
+  ],
   "verification": {
-    "prerequisites": [["node", "--version"], ["java", "-version"], ["adb", "version"]],
-    "checks": [["npm", "run", "lint"], ["npm", "test", "--", "--runInBand"]],
-    "runtime": [["npm", "run", "test:e2e", "--", "--platform", "android", "--device", "${ANDROID_DEVICE_ID}"]]
+    "prerequisites": [
+      [
+        "node",
+        "--version"
+      ],
+      [
+        "java",
+        "-version"
+      ],
+      [
+        "adb",
+        "version"
+      ]
+    ],
+    "checks": [
+      [
+        "npm",
+        "run",
+        "lint"
+      ],
+      [
+        "npm",
+        "test",
+        "--",
+        "--runInBand"
+      ]
+    ],
+    "runtime": [
+      [
+        "npm",
+        "run",
+        "test:e2e",
+        "--",
+        "--platform",
+        "android",
+        "--device",
+        "${ANDROID_DEVICE_ID}"
+      ]
+    ]
   },
   "packaging": {
     "provider": "local",
-    "commands": [["./native/android/gradlew", "-p", "native/android", ":app:bundleRelease"]],
+    "commands": [
+      [
+        "./native/android/gradlew",
+        "-p",
+        "native/android",
+        ":app:bundleRelease"
+      ]
+    ],
     "artifactPath": "native/android/app/build/outputs/bundle/release/app-release.aab"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apphx",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Host-native harness for verified Flutter, Java Android, Swift, React Native, Expo, uni-app and MyGo macOS delivery",
   "license": "MIT",
   "type": "module",

package/skills/apphx/SKILL.md

@@ -32,7 +32,7 @@ Read the bundled [requirement example](resources/requirement.json), resolving `r
 
 If the user supplied an existing task id or asked to resume it, including a scheduled wake, **skip enqueue**. Read `status` and continue that exact id/config with `next`; never reconstruct its requirement or create a second task for the same work.
 
-The requirement must describe a real audience, purpose, differentiators, framework, explicit `platform` (`ios`, `android` or `macos`), neutral top-level `version`, `channel` (`local`, `app-store`, `google-play`) and concrete acceptance scenarios/constraints. `version` defaults to `1.0.0` and `channel` to `local`; neither belongs in `apple`. `screenshotsDir` is also top-level. Java Android is Android-only; Swift is iOS-only; MyGo is macOS/local-only; App Store requires iOS and Google Play requires Android/AAB. Preserve the user's product; do not substitute a simpler app. Require honest privacy behavior, no hidden features/review bypass and real screenshots. The optional top-level `apple` metadata block is owner documentation for a manual store submission, never a requirement or a claim of approval. Shared purpose/audience is not a duplicate-admission error; assess meaningful distinction in the selected channel's research. Do not invent ownership, account eligibility, signing credentials or legal attestations.
+The requirement must describe a real audience, purpose, differentiators, framework, explicit `platform` (`ios`, `android` or `macos`), neutral top-level `version`, `channel` (`local`, `app-store`, `google-play`) and concrete acceptance scenarios/constraints. `version` defaults to `1.0.0`, `channel` to `local` and optional `priority` to `P1` (`P0` highest, `P2` lowest); priority only orders the `next --any` queue scan, it never overrides eligibility, budgets or acceptance gates. Neither belongs in `apple`. `screenshotsDir` is also top-level. Java Android is Android-only; Swift is iOS-only; MyGo is macOS/local-only; App Store requires iOS and Google Play requires Android/AAB. Preserve the user's product; do not substitute a simpler app. Require honest privacy behavior, no hidden features/review bypass and real screenshots. The optional top-level `apple` metadata block is owner documentation for a manual store submission, never a requirement or a claim of approval. Shared purpose/audience is not a duplicate-admission error; assess meaningful distinction in the selected channel's research. Do not invent ownership, account eligibility, signing credentials or legal attestations.
 
 ```sh
 apphx enqueue /absolute/control/requirement.json --config /absolute/control/factory.json --build-only
@@ -44,7 +44,7 @@ Keep the returned immutable job id and workspace. New projects have no `project`
 
 For **iOS App Store releases only**, omitting both `baseJobId` and `project.sourceDir` automatically pins the most recently enqueued finished same-product/platform/channel predecessor (`built`, `ready`, `approved` or `released`), recording `baseJobId`, `baseDigest` and `automaticBase: true`. Explicit source/base selection keeps its existing precedence and validation. The latest matching predecessor must have the same framework and valid unchanged source/dependency proof; a stale or incompatible latest version stops rather than falling back to an older version or starting fresh. Prior same-product history without a finished predecessor also stops; only a first-ever release without history may start new. Do not ask the owner to classify each release as new/update or manually copy code. A previous release is a source reuse baseline when available, not a differentiation unit; prior versions are release context, not competing portfolio products requiring artificial differentiation. Preserve application identity and data compatibility. Reuse and minimal changes are preferences, not a ban on theme, display-name, content, function or architecture changes needed for the product and its actual quality gaps.
 
-For a batch, enqueue the entire requested set before starting research so pending peers are visible to every review. With a configured inbox, submit its individual requirements and run `apphx scan --config /absolute/control/factory.json --build-only`; otherwise enqueue each requirement once and retain its returned job id. Drive each id through `next` and its returned action. A repair verdict is a continuation of that same job, not a request for manual classification, owner-written code or a replacement task. Continue eligible jobs while another is blocked or deferred, respect each due time and existing host scheduling/attempt limits, and never reuse one package's review for the batch.
+For a batch, enqueue the entire requested set before starting research so pending peers are visible to every review. With a configured inbox, submit its individual requirements and run `apphx scan --config /absolute/control/factory.json --build-only`; otherwise enqueue each requirement once and retain its returned job id. Drive each id through `next` and its returned action, or drive the whole queue uniformly with `apphx next --any --config /absolute/control/factory.json --build-only`, which returns the earliest-due actionable task; a single job is just a queue of one. A repair verdict is a continuation of that same job, not a request for manual classification, owner-written code or a replacement task. Continue eligible jobs while another is blocked or deferred, respect each due time and existing host scheduling/attempt limits, and never reuse one package's review for the batch.
 
 Research and review compare the same-channel portfolio including pending batch peers, using their supplied versions and available read-only source. If `next` or `complete` rejects changed peer context, abandon that exact stale token and request a fresh turn within existing budgets; do not reuse its verdict or create a replacement task. Packaging rechecks the accepted comparison before and after commands. A peer-only change returns unchanged own source to review rather than discarding its runtime proof. Scheduling notes and unrelated-channel/same-product history are not peer-comparison changes.
 
@@ -57,6 +57,41 @@ Read the JSON from `next`; do not guess stages from memory. Use `--build-only` t
 - **`action: "wait"`**: inspect the job's status, reason, error and due time. Report the exact blocker or scheduled time; do not busy-loop, automatically grant permission, or retry a failed command until it happens to pass. Resume with `next` after the prerequisite/due time is satisfied and the user intends to continue.
 - **`action: "done"`**: inspect the persisted outcome. `built` plus a recorded local artifact is successful local packaging. Blocked/failed/rejected outcomes are not success merely because no action remains. Report the artifact kind/path/digest and evidence, or the exact unmet requirement.
 
+### Queue loop (single jobs and batches)
+
+For unattended, batch or multi-requirement operation, loop the whole queue instead of enumerating ids yourself. The scan is ordered by priority lane (`P0` first, then `P1`, `P2`) and then due time; a deferred higher-priority job is skipped and the loop continues to the next safe action.
+
+```sh
+apphx next --any --config /absolute/control/factory.json --build-only
+```
+
+- Returns `{action:"host", job, turn}` for the earliest-due host turn: perform that one phase and finish with `complete`, exactly as for `next <id>`.
+- Returns `{action:"step", job}` for the earliest-due deterministic stage: run `apphx step JOB_ID --config /absolute/control/factory.json --build-only` once, then iterate.
+- Returns `{action:"idle", nextAt, pendingErrors, summary}` when nothing is due: read `summary` first for the terminal audit — the queue is truly finished only when every job is `built` or `failed` and no new requirements exist; a queue with `blocked`/`waiting`/`queued`/`running` jobs is merely stopped, not done. Inspect and report `pendingErrors` (stale or changed turn context that blocked a claim), then end this wake. `nextAt` is the earliest future due time; let the host scheduler resume then — never busy-loop, run `step` repeatedly on your own, or extend a loop past the owner-requested bound.
+
+Repeat until `idle` or the requested bound. Research, build and review turns all flow through the same loop, so the whole pipeline advances queue-wide. Every iteration re-reads the persisted packet from `next --any`; never plan the next action from memory of the previous one. Blocked jobs never stall the queue: the scan continues to the next safe action. The queue worker lock and per-job turn tokens already serialize deterministic stages; schedule one queue-owning session at a time. An active turn found in the queue resumes under the same rules as `next <id>`; if the prior session's completion is unconfirmed, follow the scheduled-wake rule below.
+
+- After each `step` or `complete` that returns a `built` job, or right before ending an `idle` wake, email authors with `apphx notify --any --config /absolute/control/factory.json --build-only`. It sends only to gate-passed (`built`) tasks that were not yet notified, is idempotent (receipt persisted in task state and events), and records failures as `notifyError` for retry. Configure `notify.email` (`from`, `to`, `smtpHost`, `smtpPort`, optional `secure`, `user`, `passwordEnv`, `subject`, `body`) in `factory.json`; a requirement's optional `authorEmail` overrides `to`. The SMTP password is read from the named environment variable at send time and never stored or printed. Notification is a local courtesy, never a store submission.
+
+Keep a stable re-entry instruction for scheduled wakes: it only names the control project and `factory.json` and says to run `apphx status`/`apphx next --any` and follow this loop; never bake job ids, prompts, verdicts or task state into it — the current packet is always re-read from the CLI at wake time. A complete three-requirement walkthrough from enqueue to built lives in the shipped package example `examples/queue-loop-demo.md` (package root, next to this skill's package).
+
+### Multi-role team (roles on every host turn)
+
+Every host turn payload carries `role` — the ordered list of agents to adopt for that stage (defaults: research `["product-analyst"]`; build `["developer"]`; review `["architect-review", "qa-engineer", "acceptance-reviewer"]`). Override or add roles per factory with `roles: { "research": [...], "build": [...], "review": [...] }` — role names are free-form, so missing agents (e.g. `security-review`, `performance-analyst`) are added in the config, not in the CLI.
+
+**Role adoption is host-capability-aware.** Run `apphx hosts` and read the `delegation` note for your host:
+
+- Hosts with native subagents (Codex, Claude Code, Hermes; others per their note): adopt all turn roles inside one session — parallel where roles only need fresh contexts, serial where one role consumes another's output. Still disclose which roles shared a context.
+- Hosts without subagents (stock Pi, Gemini; Cursor/OpenCode per version): run each role in its **own fresh session**, one after another, reading the same job id/config/turn. Exactly one session completes the token.
+- Independence is never downgraded silently: if a review role cannot run in a fresh non-implementer context, pause and ask the owner for that session (stock Pi rule above), or have another host run it. Do not fabricate independence.
+
+**Review verdict aggregation**: the completing session merges the typed verdicts of all review roles — union of `findings`, and `acceptanceEvidence` must still cover every acceptance requirement with attributable concrete evidence (record which role observed what). Approve only when no role has blocking findings; a role with zero attributable evidence is a missing role, not a pass.
+
+- **product-analyst (research)**: requirement grooming, feasibility, honest differentiation, privacy and plan; output is the typed research verdict.
+- **developer (build)**: first produce the architecture design — run 2-3 independent design contexts (different models/providers when the host supports it), record each proposal plus a critique and the synthesized decision in `docs/architecture.md` inside the workspace, then implement the request in parallel module slices under the decided design, recording which slice follows which decision.
+- **architect-review / qa-engineer / acceptance-reviewer (review)**: three fresh independent contexts that did not implement the change. The architect checks implementation against `docs/architecture.md` and module boundaries; the QA engineer checks empty/error states, accessibility, edge cases and quality; the acceptance reviewer covers every acceptance requirement with concrete observed evidence and issues the typed verdict. Exactly one session completes the token.
+- **PM (no host turn)**: project management is the deterministic control plane — `next --any` ordering (priority lane, due time, insertion), budgets, retries, repair loops, `notify --any` and the terminal audit. Work assignment is computed by the queue, never delegated to a model, so it stays auditable and replayable. Which model each role runs on is a host decision (see the shipped example `examples/multi-role-agents.md`); apphx only names roles.
+
 For a scheduled wake, the host scheduler owns timing and non-overlap; do not create an apphx daemon or a second schedule. Check `status` first: if it is `running` and the prior execution's completion is unconfirmed, stop and ask the owner rather than taking over its token. Respect the requested bound (for example one persisted action), then report state and exit. A `wait` or `done` result ends this wake; it does not authorize changing permissions, increasing budgets or polling indefinitely. A fresh scheduled session may review only if it did not implement the change and genuinely inspects the saved source/evidence. Missing independent review or human authorization pauses the work; never manufacture approval to keep a schedule moving.
 
 To stop an active host phase without completing it:
@@ -134,9 +169,9 @@ The deterministic `step` executes configured prerequisite/static/runtime checks
 
 ### Optional deterministic obfuscation (runs between build and verify)
 
-When the factory config sets `obfuscation`, completing the build turn advances to an `obfuscate` step before verification: the runner executes `obfuscation.command` (default `obfuscator`) with `--project <workspace project> --config <obfuscation.configPath> --framework <stack>` and the optional `--seed`, so the verified and packaged code is the obfuscated code. `configPath` is resolved against the factory config directory and must exist as a regular file. The obfuscated source is exactly what verify checks, review approves and package ships; obfuscation never runs after verification.
+When the factory config sets `obfuscation`, completing the build turn automatically advances to an `obfuscate` step before verification (no per-requirement work): the runner executes `obfuscation.command` (default `obfuscator`) with `--project <workspace project> --config <rules file> --framework <stack>` and the optional `--seed`, so the verified and packaged code is the obfuscated code. Rules come from exactly one of `obfuscation.configPath` (resolved against the factory config directory; must exist as a regular file) or `obfuscation.options` (inline rules of the same shape; the harness materializes a temporary snapshot that is removed after the stage, and the bundled obfuscator validates the rules at run time). `apphx init` writes a conservative default block (`options: { code: { removeComments: true } }`) into new factory files; delete it or strengthen it per project. The obfuscated source is exactly what verify checks, review approves and package ships; obfuscation never runs after verification.
 
-The bundled `obfuscator` package is deterministic: identical project + config + seed produce byte-identical output, in place, never writing outside the walked owned project. Installing `apphx` also installs the `obfuscator` executable (the package ships the private obfuscator), and `apphx obfuscator <project> --config <file> [--framework <stack>] [--seed <text>]` runs it directly; the harness default `obfuscation.command` resolves to that bundled executable. Point `obfuscation.command` at a different binary only to override it. Its JSON config supports:
+The bundled `obfuscator` package is deterministic: identical project + config + seed produce byte-identical output, in place, never writing outside the walked owned project. Installing `apphx` also installs the `obfuscator` executable (the package ships the private obfuscator), and `apphx obfuscator <project> --config <file> [--framework <stack>] [--seed <text>]` runs it directly; the harness default `obfuscation.command` resolves to that bundled executable. Point `obfuscation.command` at a different binary only to override it. To run the same obfuscator directly outside a job, trigger the companion apphx-obfuscator skill (installed together with apphx). Its JSON config supports:
 - `project`: `name: { from, to }` (whole-word display-name scrub in framework config files), `directories: [...]` (seeded directory renames with reference rewrites), `uuids: true` (Xcode-UUID remapping that preserves the internal reference graph)
 - `resources`: `rename: { mappings, generated }` (asset stem renames with reference rewrites; `generated` deterministically renames that many discovered stems to seed-derived tokens), `hashPerturb: { bytes }` (decode-safe hash perturbation for PNG/JPEG/GIF), `images: { recolor, recolorAll }` (PNG color remap / hue-shift / invert / channel order)
 - `content`: `sensitiveWords`, `controlColors`, `fontColors` (whole-word scrub and hex-color remap across text and code, never binary payloads)

package/skills/apphx/resources/requirement.json

@@ -5,6 +5,7 @@
   "platform": "ios",
   "channel": "local",
   "version": "1.0.0",
+  "priority": "P1",
   "screenshotsDir": "build/screenshots",
   "purpose": "离线规划多个行李包的重量，完成出发打包与返程核对，减少遗漏和超重",
   "audience": "需要管理随身包与托运行李的个人旅客",

package/skills/apphx-obfuscator/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apple App Factory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/apphx-obfuscator/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: apphx-obfuscator
+description: Run the deterministic apphx obfuscator directly on an owned project copy from a JSON rules file. Supports ObjC/Swift symbol renaming, XOR string encryption, Flutter symbol/resource obfuscation, DFA sensitive-word filtering, junk code/files, resource cleaning, project identity renames and image transforms. Use for review-hardening a local app before verification or packaging; never use it to evade lawful review of code the owner cannot lawfully ship.
+---
+
+# apphx-obfuscator
+
+Run the bundled deterministic obfuscator on a project you own. Same CLI, config and determinism contract as the `obfuscate` stage of the apphx pipeline, but triggered directly, without enqueuing a job.
+
+## Prerequisites and command form
+
+The `apphx` CLI owns the bundled obfuscator. Use the project's package manager form when `apphx` is a local dependency: `pnpm exec apphx`, `yarn exec apphx` or `npm exec --offline --package=apphx -- apphx`. Confirm with `apphx --version`, then run:
+
+```text
+apphx obfuscator <project> --config <rules.json> [--framework <stack>] [--seed <text>]
+```
+
+- `<project>`: absolute or relative path to the project copy to transform in place.
+- `--config`: obfuscator rules as JSON (required; see below). Relative paths resolve against the current directory.
+- `--framework`: `flutter|android-java|swift|react-native|expo|uni-app|mygo` (required unless set in config).
+- `--seed`: determinism seed. Defaults to `config.seed`, then a hash of the rules file.
+
+## Rules file
+
+JSON matching the obfuscator schema. At least one section must be present; every subsection is optional and empty subsections are no-ops.
+
+```json
+{
+  "framework": "swift",
+  "seed": "my-seed",
+  "code": {
+    "removeComments": true,
+    "encryptStrings": { "excludes": [] },
+    "renameIdentifiers": { "mappings": {}, "patterns": [], "generated": 32 },
+    "junkCode": { "lines": 2 },
+    "keywords": {}
+  },
+  "resources": {
+    "rename": { "mappings": {}, "generated": 64 },
+    "hashPerturb": { "bytes": 16 },
+    "images": { "recolor": [{ "from": "#ff0000", "to": "#00ff00", "tolerance": 20 }], "scale": { "width": 512 }, "flatten": { "bgColor": "#ffffff" } }
+  },
+  "project": { "name": { "from": "Demo", "to": "Acme" }, "directories": [], "uuids": true },
+  "content": { "sensitiveWords": {}, "dfa": { "words": [], "replace": "*", "keywordMix": { "prefix": "zm" } } },
+  "objc": {
+    "symbols": { "algorithmType": 0, "methodPrefix": "zk", "propertyPrefix": "zk", "classPrefix": "ZF", "replaceClassPrefix": { "from": "Demo", "to": "ZF" }, "magicColor": {} },
+    "stringEncryption": { "encryptionNum": 77, "encryptedName": "NNC_NSSTRING" },
+    "junkCode": { "amount": 2, "rubPrefix": "OBFObj" },
+    "junkFiles": { "count": 2, "amount": 1, "language": "OC" },
+    "cleanResources": { "ignore": [] },
+    "projectIdentity": { "projectName": "Acme", "folderPrefix": "zk", "imagePrefix": "img", "imageAlgorithm": 0 }
+  },
+  "flutter": {
+    "prefixWord": "zk",
+    "missAlgorithmType": 0,
+    "classWhiteList": ["MyApp"],
+    "methodWhiteList": [],
+    "variableWhiteList": [],
+    "features": { "variable": true, "className": true, "method": true, "resourceName": true, "resourceHash": true, "deleteNotes": true, "uuid": true }
+  }
+}
+```
+
+`objc` covers iOS/ObjC/Swift symbol renaming, XOR string encryption with `.pch`/Swift decryptor injection, junk code/files, unused-resource cleaning and project identity renames (project name, folders, xcassets images, xib/storyboard references). `flutter` covers Dart class/method/variable renaming, resource names and hash perturbation, UUID remapping and comment removal. `content.dfa` is a DFA sensitive-word filter over a built-in lexicon plus your extra words.
+
+## Determinism and safety
+
+- Identical project + rules + seed produce byte-identical output. No wall-clock, locale or `Math.random` state is consulted.
+- The obfuscator only writes inside the walked project and skips generated/vendor directories. Run it on a **copy** of the project, never on the only checkout, unless the user explicitly says otherwise.
+- Obfuscation changes the code that verification, review and packaging see. In the apphx pipeline, changing the obfuscation config invalidates prior verification proof and requires renewed verification and review.
+- Keep the app buildable: after obfuscating, run the normal build/verify steps; any breakage is a rules-file problem to fix and retry.
+- Do not weaken acceptance, verification or signing to accommodate obfuscation output.