@jabworks/condux 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "OpenCode plugin for the condux workflow toolkit — bundles the condux skills and injects the specialist agents (coder, explorer, planner, researcher) plus an opt-in plan-review listener.",
   "type": "module",
   "publishConfig": {

package/skills/live-verification/SKILL.md

@@ -20,7 +20,7 @@ between "the pipeline passed" and "I watched it do the thing".
 
 | Change touches | Run this? |
 |---|---|
-| A rendered surface — page, component, story, dialog | **Yes** |
+| A rendered surface — page, component, story, dialog, a mobile app screen | **Yes** |
 | An endpoint, procedure, or CLI a human will call | **Yes** |
 | Behaviour behind a flag or a state the tests don't reach | **Yes** |
 | Types, docs, comments, config with no runtime effect | No — say so and skip |
@@ -43,6 +43,14 @@ Do not assume a dev server. In order:
 Start it in the background, wait for it to actually serve (poll the URL — do
 not `sleep` and hope), and note the URL in the report.
 
+**Mobile app: load the native recipe.** If the project is a mobile app —
+finalize's native-change test: an `expo` or `react-native` dependency, or a
+committed `android/` or `ios/` — read `references/native-app.md` now. Its
+target order replaces the list above; it picks the driving rung once (adb,
+`agent-device`, mobile-mcp, Expo's skills — recommended, never installed) and
+resolves `adb` to an absolute path. The claims, verdicts and report below are
+unchanged.
+
 **Mobile app: rebuild first when the change is native.** If finalize's
 `Native` line said *native rebuild* (or the diff touches the native layer —
 see finalize's native-change check), the installed app does not contain the
@@ -81,6 +89,12 @@ Order of checks, because this is where the defects were:
 4. **Keyboard.** Tab to it, Escape out of it, confirm focus lands somewhere
    sensible.
 
+**Mobile app:** the same four checks, translated — both themes via
+`cmd uimode night`; pressed, disabled and in-flight states in place of hover;
+the failure path in airplane mode; the system back (`keyevent 4`) in place of
+Tab and Escape, which must close what it opened. Every tap follows
+`native-app.md`'s stale-UI rules.
+
 ### Step 4 — Capture evidence
 
 One artifact per claim that has a visual or observable outcome — screenshot,
@@ -91,6 +105,12 @@ evidence file for the claim it supports and reference it from the report's
 claim table. Console errors and failed network requests seen along the way
 get reported even when they belong to another feature.
 
+**Mobile app:** evidence is a screenshot you have read back, or a recording
+for motion, and `native-app.md`'s log sweep stands in for console and network.
+A claim the emulator cannot settle — haptics, camera, push, feel — gets the
+`device-only` verdict and a line under the report's `For the phone:`, never ✓.
+The report adds the `Device` and `Build` header keys.
+
 Then write `report.md` into the same dir, in the shape of
 `references/report-template.md` — every run writes one, including runs where
 nothing could be driven (the template carries the fallback shape).
@@ -127,11 +147,16 @@ Wait timed out
 
 Two failed attempts on the same claim is the ceiling. Report and move on.
 
+On a mobile app, the device-side failures — an offline device, an emulator
+that won't boot, a stale binary — are in `native-app.md`'s part 8, under the
+same ceiling.
+
 ## Output Format
 
-The report shape — the fixed header table (Date / Target / Diff / Themes),
-the claim table (Claim | Evidence | Verdict), "Also seen", and the outcome
-line — lives in `references/report-template.md`, the canonical home. It also
+The report shape — the fixed header table (Date / Target / Diff / Themes,
+plus Device / Build on a native app run), the claim table (Claim | Evidence |
+Verdict), the phone checklist for `device-only` claims, "Also seen", and the
+outcome line — lives in `references/report-template.md`, the canonical home. It also
 carries the fallback shape for when nothing could be driven; that run still
 writes `report.md`, because an absent report is indistinguishable from a run
 that never happened. Fixed header keys and a fixed claim-table shape are what
@@ -142,7 +167,8 @@ make two runs of the same surface comparable.
 ```
 ✗ Reporting a claim as verified because the code looks right
 ✗ Inventing a screenshot, a response, or a result that wasn't observed
-✗ Installing a browser driver or scaffolding a test harness to get a result
+✗ Installing a browser or device driver, or scaffolding a test harness to get a result
+✗ Reporting a device-only claim as ✓
 ✗ sleep-then-check instead of polling for the condition
 ✗ Retrying the same selector more than twice
 ✗ Killing processes the run didn't start

package/skills/live-verification/references/native-app.md

@@ -0,0 +1,157 @@
+# Native app verification (Android)
+
+Loaded from Step 1 when the project is a mobile app — the same test as
+finalize's native-change check: an `expo` or `react-native` dependency in
+`package.json`, or a committed `android/` or `ios/` directory. A web project
+never reads this file.
+
+The claim/verdict/report contract in SKILL.md does not change. This file only
+says how to reach the app, drive it, and read its errors — and which claims an
+emulator cannot settle.
+
+## 1. Pick the rung
+
+Decide once, at the start of the run, and name the choice in the report's
+`Target` row. Three rungs, each optional, none ever installed by you:
+
+| Concern | Use, first match wins |
+|---|---|
+| Build and install | the `expo` plugin's `expo-dev-client` / `eas-simulator` skills, when they are in your skill list → the project's own build script → `npx expo run:android` |
+| Drive and read logs | `agent-device` on PATH (`command -v agent-device`) → mobile-mcp's `mobile_*` tools, when you have them → the core adb recipe below |
+
+When a driver rung is in use, follow **its** documentation for the commands
+(`agent-device help`, its bundled skills, the MCP tools' own descriptions) —
+this file deliberately does not restate them. Parts 5–7 below apply on every
+rung: they are about what counts as evidence, not about which tool taps.
+
+No driver installed is the normal case, not a gap — never install one, and
+never stop the run to ask.
+
+## 2. Target
+
+In order, before booting or building anything:
+
+1. **The project's own setup wins.** `AGENTS.md`, `README.md`, a
+   project-local skill for running the app, `package.json` scripts
+   (`android`, `start`, a dev-client script), and anything under `scripts/`
+   that boots an emulator or installs a build. Use them as written. When they
+   disagree, the prose that is newest wins over a script name — a script can
+   outlive the emulator it boots.
+2. **Is a device already attached?** `adb devices` (with the resolved path,
+   part 3). One device in the `device` state → use it. `offline` or
+   `unauthorized` → part 8.
+3. **No device** → boot the emulator the project's script names, or
+   `emulator -list-avds` and the first one. Poll until
+   `adb shell getprop sys.boot_completed` prints `1` — never a fixed sleep.
+4. **Metro.** A dev client loads JS from Metro: check port 8081 before
+   starting it, and run `adb reverse tcp:8081 tcp:8081` once per boot.
+5. **Package and scheme.** Read `android.package` and `scheme` from the app
+   config (`app.json` / `app.config.*`), or `applicationId` from
+   `android/app/build.gradle*`. Every launch and log filter below needs them.
+   An `app.config.*` can change both per build variant (a dev client often
+   carries a `.dev` suffix and its own scheme) — confirm the installed one
+   with `adb shell pm list packages <name>` before launching.
+
+## 3. Resolve adb once
+
+`adb` is often on the user's interactive PATH only, and an agent's shell keeps
+no state between calls — an `export PATH=…` or an `ADB=…` variable lasts one
+command.
+
+**A project-provided adb wins.** Some setups run the emulators on another
+host or OS and reach them through a wrapper script or a non-default adb
+server; the project's docs (part 2) name it. Use that, by absolute path.
+Otherwise resolve the absolute path once:
+
+```bash
+command -v adb || ls "$ANDROID_HOME/platform-tools/adb" "$ANDROID_SDK_ROOT/platform-tools/adb" 2>/dev/null | head -1
+```
+
+Then **write that literal path into every later command**. An adb that lists
+no devices while the project documents a running one is the wrong adb, not an
+empty machine — go back to the project's docs. Nothing found →
+stop and report the blocker with the exact next command to try (set
+`ANDROID_HOME`, or install platform-tools). Never install the SDK yourself.
+
+## 4. Drive
+
+The core recipe, written with `adb` for brevity — use the resolved path.
+
+| Need | Command |
+|---|---|
+| Launch at a screen | `adb shell am start -W -a android.intent.action.VIEW -d "<scheme>://<path>" <package>` |
+| Tap / swipe | `adb shell input tap <x> <y>` · `adb shell input swipe <x1> <y1> <x2> <y2> <ms>` |
+| Long-press | `adb shell input swipe <x> <y> <x> <y> 800` (a swipe that does not move) |
+| Drag, multi-step gestures | `adb shell input motionevent DOWN/MOVE/UP <x> <y>`, where the device's `input` lists it |
+| Type / keys | `adb shell input text '<text>'` · `adb shell input keyevent 4` (back) |
+| Screenshot | `adb exec-out screencap -p > <claim>.png` — then Read the PNG; an unread screenshot proves nothing |
+| Motion | `adb shell screenrecord --time-limit <s> /sdcard/<claim>.mp4`, then `adb pull` — a still cannot prove an animation |
+| UI tree | `adb exec-out uiautomator dump /dev/tty` — element text, ids and `bounds` |
+| Theme | `adb shell cmd uimode night yes` / `no` — both themes still gate a themed change |
+| Offline | `adb shell cmd connectivity airplane-mode enable` / `disable` |
+| Fresh state | `adb shell pm clear <package>` — only when the claim needs it; it wipes the user's app data |
+
+## 5. Stale UI
+
+Most wrong taps in the field came from acting on a picture of a screen that
+had already changed.
+
+- **Take a fresh screenshot before any tap that changes state**, and look at it.
+- **A `uiautomator dump` is true only for the moment it ran.** Re-dump after
+  every navigation, dialog, or list change.
+- **Coordinates come from a dump's `bounds`**, never estimated from an image.
+- **"could not get idle state"** means an animation is running. Poll the dump
+  again; a screen that never goes idle is a finding, not a reason to guess.
+
+## 6. Log sweep
+
+Runtime errors are part of the evidence — the same rule as the browser
+console.
+
+1. Before driving: `adb logcat -c`.
+2. After driving, the app's errors: `adb logcat -d -v time --pid=$(adb shell pidof -s <package>) '*:E'`.
+3. The JS layer: `adb logcat -d -v time -s ReactNativeJS:V`, plus Metro's own output.
+4. The app is gone (no pid) → it crashed: `adb logcat -d -b crash`. A crash on a
+   claim's path fails that claim.
+
+A LogBox or RedBox overlay is a finding: read it, record its message, then
+dismiss it. A RedBox on a claim's path fails that claim. Everything found here
+goes in the report's "Also seen", even when it belongs to another feature.
+
+## 7. What the emulator can't prove
+
+These claims get the **`device-only`** verdict, with the reason, and go on the
+report's phone checklist. Never ✓, whatever the emulator showed:
+
+| Claim touches | Why the emulator can't settle it |
+|---|---|
+| Haptics | no vibration hardware |
+| Camera, QR scanning, biometrics | simulated sources, not the real sensor path |
+| Push notification delivery | needs real FCM delivery on a signed-in device |
+| Feel — scroll, animation smoothness, startup time | judged on the slowest device you support, on a release build |
+| Sensors — GPS movement, motion, NFC, Bluetooth | mocked or absent |
+
+The emulator can still verify the *surrounding* behaviour — the button that
+triggers the haptic, the screen the scan result lands on. Split such a claim
+in two rather than giving the whole thing one verdict.
+
+## 8. When it goes wrong
+
+Environmental failures are results, not things to retry into the ground. The
+two-attempt ceiling from SKILL.md applies.
+
+| Failure | Response |
+|---|---|
+| `device offline` / `unauthorized` | one `adb reconnect`; still failing → report it |
+| Emulator won't boot, or no AVD exists | report it with the next command to try; never kill an emulator you did not start |
+| Metro port taken | report it; do not kill the process holding it |
+| The app shows old behaviour | the binary is stale — Step 1's rebuild-first rule; record what you drove in the `Build` key |
+| A tap does nothing | re-dump (part 5) and retry once; second miss → claim unchecked |
+
+## 9. iOS
+
+The core recipe is Android-only. It has not been verified against the iOS
+simulator, so this file does not pretend to cover it. For an iOS claim: use
+the driver rung (agent-device and mobile-mcp both drive the simulator) when
+one is present; otherwise report the claim **unchecked** with the blocker
+named — "no iOS driver; the core recipe is Android-only".

package/skills/live-verification/references/report-template.md

@@ -27,6 +27,37 @@ Also seen: <console errors, failed requests, off-feature breakage — or "nothin
 <n> claims failed. <fix + re-verify note, or "all green">
 ```
 
+A **native app run** (SKILL.md Step 1 detected a mobile app) adds two header
+keys and one block, and has a fourth verdict:
+
+```markdown
+# Live verification: <change>
+
+| | |
+|---|---|
+| Date | YYYY-MM-DD |
+| Target | <package> on <device> via <rung: adb / agent-device / mobile-mcp> |
+| Device | <emulator AVD + API level, or the physical model> |
+| Build | JS only / rebuilt at <commit> (from finalize's Native line) |
+| Diff | <branch or commit under test> |
+| Themes | light ✓ dark ✓ |
+
+| Claim | Evidence | Verdict |
+|---|---|---|
+| <behavior asserted, one line> | <file in this dir, or —> | ✓ / ✗ <what actually happened> |
+| <hardware-bound behavior> | <file, or —> | device-only — <why the emulator can't show it> |
+
+For the phone:
+- [ ] <claim> — <what to do on the device> — passes when <what you observe>
+
+Also seen: <logcat errors, LogBox/RedBox messages, Metro errors — or "nothing">
+
+<n> failed · <m> device-only (on the phone list) · <k> verified. <fix + re-verify note>
+```
+
+`For the phone:` carries one checkbox per `device-only` row and is omitted
+when there are none. A web run never shows `Device`, `Build`, or this block.
+
 When nothing could be driven, the report is still written — an absent
 `report.md` is indistinguishable from a run that never happened:
 
@@ -50,5 +81,6 @@ When nothing could be driven, the report is still written — an absent
 |---|---|
 | Everything a run produces lives inside its run dir — nothing at the verification root | Root-level orphans belonging to no run were observed in the wild; the dir is the unit of a run |
 | Evidence files are named for the claim they support and referenced from the claim table | The table is the index — an evidence file it doesn't reference is uncontextualized in a week |
-| Header keys are fixed: Date, Target, Diff, Themes (Themes only for UI surfaces) | Two runs of the same surface are diffable only when their headers line up |
+| Header keys are fixed: Date, Target, Diff, Themes (Themes only for UI surfaces); a native app run adds Device and Build | Two runs of the same surface are diffable only when their headers line up |
+| `device-only` is a verdict, not a pass — it never counts toward verified, and every one lands on the phone checklist | "Never report hardware validation that was not performed": a deferred check written as ✓ is read as done |
 | Every run writes `report.md`, including runs where nothing could be driven | Absence of a report must mean absence of a run, nothing else |

package/skills/preflight/SKILL.md

@@ -49,6 +49,12 @@ Run through this checklist. Every item must be answered honestly — not optimis
 │    No console.log, no debug code, no TODO comments that         │
 │    weren't there before, no commented-out blocks.               │
 │                                                                  │
+│  □ NO WORKAROUNDS                                               │
+│    Did anything here bypass a convention, widen a type,         │
+│    disable a rule, or special-case around a design just to      │
+│    make it land? Report it — the user decides whether it        │
+│    ships. Nothing bypassed → N/A, no commentary.                │
+│                                                                 │
 │  □ READY FOR FINALIZE                                           │
 │    All the above are yes → call /finalize                       │
 │    Any are no → fix first, then re-check                        │
@@ -100,6 +106,7 @@ a preflight failure like any other.
 | "The edge cases are unlikely"                  | They happen in production. Consider them now.            |
 | "The plan steps were mostly done"              | Mostly done is not done.                                 |
 | "I only changed one line, nothing could break" | One-line changes cause regressions too.                  |
+| "It's a small workaround, I'll do it properly later" | Later is a PR nobody opens. Report it; the user chooses.  |
 
 ## Output
 
@@ -112,6 +119,7 @@ a preflight failure like any other.
 □ Spec drift           ✓ / ✗ / N/A [notes]  (N/A = no spec for this task)
 □ No regressions       ✓ / ✗ [notes]
 □ Nothing left behind  ✓ / ✗ [notes]
+□ No workarounds       ✓ / ✗ / N/A [notes]  (N/A = nothing bypassed)
 
 → Ready for /finalize  [YES / NO — list blockers if NO]
 ```

package/skills/workflow/SKILL.md

@@ -42,6 +42,11 @@ Condux is **lean and proportional** — the opposite of "always run every gate."
 6. **House style rides along.** Before the first line of code in any tier, load
    the `coding-directive` skill if it is installed — skip silently when it
    isn't. Codebase mimicry and repo config still win over the directive.
+7. **Two tracks, one of them triggered.** Tactical is the task in front of you.
+   Strategic is the environment that produced it — would a narrower type, a
+   lint rule, or a written convention have made this task's bug impossible?
+   The strategic track is *not* a standing obligation; that would violate rule
+   1. It fires on a trigger, and the triggers are in Environment Hardening.
 
 ## Entry Contract
 
@@ -151,7 +156,7 @@ UIs), the combined menu must still carry the full CP-1 option set.
 
 | Option | What it does |
 |---|---|
-| **Verify it live** *(recommended when the change has a runnable surface)* | Load `live-verification` — drive the real UI or endpoint and check each claim against observed behaviour |
+| **Verify it live** *(recommended when the change has a runnable surface — an app on an emulator counts)* | Load the `live-verification` skill and follow it — including on a mobile app: drive the real UI, endpoint or emulator, check each claim against observed behaviour, and write its report |
 | **Code review** *(recommended)* | `/code-review` the diff before merging |
 | **Commit** | Load the `git-commit` skill if installed (conventional message from the diff, safe staging); otherwise follow the repo's commit conventions |
 | **Cut a release** | Load the `release` skill if installed — machinery detection, dry-run plan, then tag → push → GitHub release; otherwise follow the repo's release conventions |
@@ -253,6 +258,38 @@ Scope turns out bigger than the confirmed tier? Stop immediately, report what yo
 found ("this touches auth middleware, not just the UI"), re-confirm the tier before
 continuing. Never silently expand scope.
 
+## Environment Hardening
+
+The strategic track, fired by a trigger rather than run on every task. Two
+triggers, both observed rather than imagined:
+
+- **Repeated friction.** The same obstacle cost time twice — twice in this
+  task, or once here and once earlier in the session.
+- **A workaround taken.** You bypassed a convention, widened a type, disabled a
+  rule, or special-cased around a design to make the change land. `preflight`'s
+  no-workarounds box catches the ones you stopped noticing.
+
+When one fires, spend a sentence on the cause rather than the symptom. Agents
+succeed in a **pit of success** — an environment where the wrong thing is hard
+to express:
+
+| Lever | Looks like |
+|---|---|
+| Constrained surface | a narrower type, a smaller public API, an argument that cannot be passed wrong |
+| Rules that force correctness | a lint rule, a stricter compiler flag, a test that fails on the shape and not just the value |
+| Written convention | a line in `AGENTS.md` / `CLAUDE.md` or the house-style skill, so a reviewer cites it instead of re-deriving it |
+| Data the agent lacks | dev-server or production logs, a test database, browser access to watch the thing actually render |
+
+**The output is a sentence to the user, or a backlog item — never a new
+artifact.** Name the hardening and let the user decide. If a backlog skill
+(`record`, or the repo's own convention) is installed and they want it kept,
+file it there. Do not create a file for it, do not add a `.condux/` directory
+for it, and do not implement it inside the current task — that is scope
+expansion, which Escalating Mid-Task already forbids.
+
+**Silence is the correct output when neither trigger fired.** A clean SMALL
+task gets no hardening commentary at all.
+
 ## Red Flags
 
 Stop if you catch yourself doing any of these:
@@ -269,7 +306,9 @@ Stop if you catch yourself doing any of these:
 | Silently skipping discovery on a LARGE task | Ask — it's a soft gate, not a free pass |
 | Rewriting a test spec to make it pass | Stop and ask — never silently edit specs |
 | Auto-running code-review, commits, or agents | They're checkpoint choices; run only when picked |
+| Verifying live without loading `live-verification` | Load it — its `report.md` is the evidence (9 of 11 ad-hoc runs in a mobile eval left none) |
 | Auto-advancing past a checkpoint on MEDIUM/LARGE | The user owns every transition |
+| Absorbing a workaround silently so the change lands | Name it — that's a hardening trigger, and preflight asks for it anyway |
 | Expanding scope past the confirmed tier | Stop, report, re-confirm |
 
 ## Tips