taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/assets/skills/taphound-journey-generator/prompts/generate-step.md

@@ -0,0 +1,211 @@
+# Generate Next Proposed Step
+
+You are generating the next proposed step in a TapHound journey. You have:
+
+- **Goal**: the user's natural-language description of the test scenario.
+- **Project Context Index**: the compact module catalog.
+- **Selected module summaries**: only the shards cryptographically bound at
+  `generation start`, containing known Activities, screens, elements,
+  transitions, and Logcat candidates.
+- **Snapshot**: the current device state from `generation observe --json`,
+  including the `layout` array (all visible UI elements with their
+  properties) and the current `activity`.
+- **Completed steps**: a list of steps that have already succeeded in this
+  session.
+- **Base Flow**: optional bound reusable prefix metadata. Its exit Activity is
+  the generation starting checkpoint; its navigation is already complete.
+
+## Layout Structure
+
+`snapshot.layout` is an array of root `LayoutElement` objects, not a flat
+element list. Every element has recursive `children`; traverse the complete
+tree when finding a target. `LayoutElement.id` is an internal parser identity
+and is never a Locator field. Use only `resourceId`, `text`, and
+`contentDescription`, in that priority order, plus `within` and `index` when
+needed.
+
+## Your Task
+
+Determine the next single action that advances the Goal. Output one proposed
+step JSON object (without the `binding` field — the caller adds binding from
+the observe result).
+
+## How to Decide
+
+1. **Identify what remains**: Compare the Goal against completed steps. What
+   is the next logical action? Do not regenerate navigation already supplied by
+   the bound Base Flow.
+
+2. **Verify Context coverage**: Find `snapshot.activity` in the selected
+   module summaries. If no selected shard covers it, return
+   `{"error":"context coverage missing","activity":"..."}`. Do not read or
+   add an unbound shard after session start.
+
+3. **Verify hierarchy completeness**: Inspect `snapshot.windowHierarchy`
+   when present. If its status is `incomplete`, do not propose any action,
+   including Back or Wait. Return
+   `{"error":"window hierarchy incomplete","diagnostics":[...],"recovery":[...]}`
+   using the snapshot's exact diagnostics and recovery values. If the status
+   is `unknown`, continue only with elements already present in
+   `snapshot.layout`; never infer missing PopupWindow, dialog, or overlay
+   controls from the screenshot.
+
+4. **Find the target element**: Look through `snapshot.layout` for an element
+   that matches the next intended action:
+   - Match by `resourceId` first (highest priority).
+   - If no `resourceId` match, match by `text`.
+   - If no `text` match, match by `contentDescription`.
+   - If identity fields still match multiple live elements, first add `within`
+     with a deterministic ancestor Locator when available. Add zero-based
+     `index` only when identical candidates remain in that scope.
+   - Do not add Locator `evidence`. Core derives versioned semantic evidence
+     from the bound snapshot when it persists a resolvable indexed step.
+   - The element must be `enabled: true`.
+   - For `click`: prefer `clickable: true` elements.
+   - For `inputText`: the target should be `focusable: true` (an EditText).
+     Do not include a `locator` for `inputText` — the Core uses the focused
+     element.
+   - For `swipe`: the target should be `scrollable: true` with `bounds`.
+   - For `scrollTo`: specify both `locator` (target) and `container`
+     (scrollable parent).
+
+5. **Detect cross-app transitions**: Before proposing a `click` on a trigger
+   that opens an external app, check whether the element clearly initiates a
+   cross-app transition (e.g., a camera button, "choose from gallery", "attach
+   file", share sheet). If so, return a `bridge` signal (see **Cross-app
+   flows** in Rules) instead of a `click`. If an External Flow was bound at
+   `generation start --external-flow` and its `escapedPackageName` matches the
+   scenario, include `"flow": "<name>"` in the bridge signal so the caller can
+   pass `--flow` to `generation bridge` for deterministic auto replay.
+
+6. **Determine activity.before**: This is `snapshot.activity` (the current
+   Activity class). The proposed step only includes `activity.before` —
+   never `activity.after`. The Core determines the after-Activity from
+   live device observation after executing the action.
+
+7. **Add expect (optional)**: Only if there is a deterministic, verifiable
+   outcome:
+   - `element`: a specific element should appear after the action (e.g., a
+     search input field appears after clicking "open search"). Optional
+     predicates: `enabled` and `clickable` compare the resolved element's
+     state exactly on every poll (so `enabled: true` also waits-until-enabled
+     within `timeoutMs`); `absent: true` passes only when the locator matches
+     zero elements — use it for "element disappears" semantics, never combined
+     with `enabled`/`clickable`.
+   - `logcat`: a specific log line should be emitted (e.g., the source code
+     shows `Log.i("SearchViewModel", "submitted query=" + query)` — use
+     `tag: "SearchViewModel"`, `pattern: "submitted query=..."`,
+     `match: "literal"`). A `literal` pattern must be the stable prefix of the
+     logged message, never a whole line copied from a device run: drop every
+     run-varying tail such as `@1f3a2b` identity hashes, object `toString()`
+     dumps, timestamps, durations, counts, and generated IDs. When only a
+     varying middle can identify the event, use `match: "regex"` and anchor
+     the stable words instead of the varying text.
+   - `activity`: a specific Activity should be foregrounded.
+   - Do not add expectations you cannot verify from source code or Context.
+   - Do not invent log patterns that don't exist in the source.
+
+## Output Format
+
+A single JSON object matching one of the step types in
+`schemas/proposed-step-envelope.json` `$defs/ProposedStep`, but **without**
+the `binding` field. The caller wraps it with binding and snapshot using
+`scripts/envelope.mjs bind` (offline validation, binding auto-filled from the
+preceding observe/step output).
+
+Example (click):
+```json
+{
+  "action": "click",
+  "locator": { "resourceId": "open_search" },
+  "activity": {
+    "before": "dev.taphound.demo.MainActivity"
+  },
+  "expect": {
+    "type": "element",
+    "locator": { "resourceId": "search_input" },
+    "timeoutMs": 3000
+  }
+}
+```
+
+Example (inputText):
+```json
+{
+  "action": "inputText",
+  "text": "hello world",
+  "activity": {
+    "before": "dev.taphound.demo.SearchActivity"
+  }
+}
+```
+
+Example (bridge — auto replay with a bound External Flow):
+```json
+{
+  "bridge": true,
+  "scenario": "photoCapture",
+  "triggerLocator": { "resourceId": "camera_button" },
+  "flow": "camera/photo-capture",
+  "description": "Capture photo via system camera",
+  "activity": {
+    "before": "dev.taphound.demo.ProfileActivity"
+  }
+}
+```
+
+Example (bridge — manual replay, no flow):
+```json
+{
+  "bridge": true,
+  "scenario": "pickFile",
+  "triggerLocator": { "text": "Choose file" },
+  "description": "Pick a file via system file picker",
+  "activity": {
+    "before": "dev.taphound.demo.ChatActivity"
+  }
+}
+```
+
+## Rules
+
+- Never use coordinates, visual guessing, or annotated-label fallback.
+- Never act when `snapshot.windowHierarchy.status` is `incomplete`.
+- The proposed step only includes `activity.before`, never `activity.after`.
+  The Core determines `after` from live device observation.
+- Locator priority is fixed: `resourceId` > `text` > `contentDescription`.
+  Do not use multiple fields simultaneously unless that is the only way to
+  disambiguate. `within` limits matching to a deterministic ancestor's
+  descendants; `index` is zero-based and applies only after all identity
+  fields have narrowed the live Layout candidates.
+- The `snapshot.layout` from `observe` is the live device layout — it is
+  the source of truth for element matching, not the static XML files from
+  Context generation. The same `resourceId` may appear in different layout
+  XML files, but only one layout is active at runtime. Match against what
+  `observe` returns.
+- Activities from library/feature modules are valid navigation targets.
+  Use the fully qualified class name from the manifest or source.
+- Do not include `binding` — the caller adds it from the observe result.
+- Do not include `fallback` — proposals do not support fallback.
+- **Cross-app flows**: If the next action would open an external app (system
+  camera, image/file picker, share sheet), do NOT propose a `click` step. That
+  will fail with `PACKAGE_ESCAPE`. Instead, return:
+  `{"bridge": true, "scenario": "photoCapture|pickImage|pickFile|custom",
+  "triggerLocator": {...}, "description": "..." (required for custom)}`
+  The caller will use `generation bridge` to execute it. Only return this when
+  the target element clearly initiates a cross-app transition (e.g., a camera
+  button, "choose from gallery", "attach file").
+- When a bound External Flow matches the scenario, include `"flow": "<name>"`
+  in the bridge signal. The caller passes `--flow <name>` to
+  `generation bridge` so Core resolves the flow, stamps its steps as
+  `externalSteps`, and commits with `replayMode: "auto"` for deterministic
+  replay. If no flow is bound, omit `flow`; the step commits with
+  `replayMode: "manual"` and needs a human operator during finalize.
+- Do NOT include `externalSteps`, `escapedPackageName`, `replayMode`, or
+  `escapeTimeoutMs` in the bridge proposal. Core fills these from the resolved
+  flow and live device observation. The proposal only carries `flow` (the name)
+  and the standard bridge fields.
+- If no actionable element matches the Goal, return:
+  `{"error": "no matching element", "reason": "..."}`
+- If the Goal appears complete, return `{"complete": true}` instead of a
+  step.

package/assets/skills/taphound-journey-generator/prompts/select-flow.md

@@ -0,0 +1,91 @@
+# Select a Reusable Base Flow
+
+You are selecting an existing TapHound Flow to reuse before AI-driven Journey
+generation.
+
+## Inputs
+
+- **Goal**: the user's natural-language test scenario.
+- **Project Context Index**: the current validated module catalog.
+- **Flow catalog**: exact output from `taphound journey list-flows --json`.
+
+## Selection Procedure
+
+1. Ignore every Flow whose `status` is not `valid`. Report invalid candidates;
+   never silently repair or bypass them.
+2. Identify the Activity or screen where the Goal's business-specific actions
+   begin.
+3. Require the first resolved step to start from a stable Activity that cold
+   launch deterministically reaches. `run.activity` is only the cold-launch
+   entry and may redirect immediately. Never require a transient Splash
+   Activity to remain foreground long enough to become the Flow's first
+   checkpoint.
+4. Keep only Flows whose `exitActivity` is a deterministic prerequisite for
+   that screen and whose traversed Activities are covered by the Context
+   modules selected for generation.
+5. Prefer the deepest valid Flow, meaning the candidate that eliminates the
+   largest reusable navigation prefix. For a Goal inside a chat detail screen,
+   prefer `chat/open-thread` over `core/launch-home` when both are valid.
+6. Do not select by filename alone. A name containing `core`, `home`, or a Goal
+   keyword is not proof that the Flow is applicable.
+7. If no candidate is applicable, return `{"selected": null}` and generate from
+   the normal launch state.
+
+## Output
+
+```json
+{
+  "selected": "chat/open-thread",
+  "reason": "Deepest valid Flow whose exit Activity is the Goal's chat screen"
+}
+```
+
+or:
+
+```json
+{
+  "selected": null,
+  "reason": "No valid Flow ends at a prerequisite screen for this Goal"
+}
+```
+
+## Safety Rules
+
+- A Flow with missing dependencies, a cycle, an Activity boundary mismatch, or
+  stale resolution evidence is unusable.
+- If a selected Flow fails Core replay, stop and report `FLOW_REPLAY_FAILED`.
+  Read its Flow name, Verify report path, primary failure, failed-step summary,
+  and recovery guidance. Repair or re-record the shared Flow; do not silently
+  regenerate it.
+- Do not accept "the device is already on Home" as proof that a failed Flow
+  replayed exactly.
+- Bypass reuse only when the user explicitly requests generation without a
+  base Flow.
+
+## Stable Launch Anchor Example
+
+Model `core/launch-home` as readiness at the stable Home destination, not as a
+timing-sensitive `Splash -> Home` transition:
+
+```json
+{
+  "version": 1,
+  "kind": "flow",
+  "name": "core/launch-home",
+  "includes": [],
+  "steps": [{
+    "action": "wait",
+    "activity": {
+      "before": "com.example.app.HomeActivity",
+      "after": "com.example.app.HomeActivity"
+    },
+    "expect": {
+      "type": "element",
+      "locator": { "resourceId": "home_root" },
+      "timeoutMs": 3000
+    }
+  }]
+}
+```
+
+Choose an element unique to the ready Home screen for the expectation.

package/assets/skills/taphound-journey-generator/references/bridge.md

@@ -0,0 +1,35 @@
+# Cross-Application Bridge
+
+When the Goal requires a cross-app flow (system camera, image/file picker,
+share sheet), a regular `generation step` proposal fails with `PACKAGE_ESCAPE`.
+Use `generation bridge` instead. Core clicks the trigger, detects the escape,
+optionally executes a bound External Flow's steps inside the escaped package,
+waits for return, and captures the post-return snapshot.
+
+```bash
+taphound generation bridge \
+  --project <project> --session <generationId> \
+  --scenario photoCapture \
+  --trigger-locator '{"resourceId":"camera_button"}' \
+  --flow camera/photo-capture \
+  --return-timeout-ms 60000 --escape-timeout-ms 3000 \
+  --compact --json
+```
+
+**Auto bridge** (deterministic): pass `--flow <name>` to bind a Phase 2
+External Flow. The step commits with `replayMode: "auto"`. **Manual bridge**:
+omit `--flow`; commits with `replayMode: "manual"` (human operator required
+during finalize). Options: `--scenario` (`photoCapture`, `pickImage`,
+`pickFile` built-in, or `custom` with `--description`), `--trigger-locator`
+(inline JSON, must be clickable), `--return-timeout-ms`, `--escape-timeout-ms`
+(default 3000; no escape fails with `BRIDGE_NO_ESCAPE`).
+
+Bridge goes through risk confirmation like any step. Failure codes:
+`BRIDGE_NO_ESCAPE`, `SCENARIO_PACKAGE_MISMATCH`, `BRIDGE_NOT_RETURNED`,
+`EXTERNAL_FLOW_NOT_FOUND`, `EXTERNAL_FLOW_STALE`,
+`EXTERNAL_PACKAGE_MISMATCH`, `EXTERNAL_ACTIVITY_MISMATCH`,
+`EXTERNAL_STEP_FAILED`, `EXTERNAL_LOCATOR_STRICTNESS` (external steps require
+`resourceId`-only locators), `MANUAL_STEP_REQUIRED` (non-interactive finalize
+with manual replay — bind an External Flow or use a TTY).
+
+A successful bridge returns `nextBinding` and `nextSnapshotRef` like any step.

package/assets/skills/taphound-journey-generator/references/mid-session.md

@@ -0,0 +1,44 @@
+# Correcting and Adjusting a Generation Session
+
+**Rewind a wrong committed step** with `step --replace` instead of restarting
+the session or building workarounds on top of a mistake:
+
+```bash
+taphound generation step \
+  --project <project> --session <generationId> \
+  --replace <index> \
+  --compact --json
+```
+
+Core replays the stored candidate prefix `[0, index)` through the same
+cold-launch replay engine as finalize (honoring the session's current idle
+policy), truncates the candidate to that prefix, and binds a fresh
+post-replay snapshot. The response matches `observe` plus `status:
+"replaced"`, `stepIndex`, `remainingStepCount`, and `truncatedStepCount`;
+the next proposal must bind the returned revision and snapshot. The index
+must be an integer in `[0, candidateStepCount]` (`0` cold-resets without
+replay); an index inside the bound Base Flow prefix fails with
+`FLOW_INVALID`; `--input` and `--replace` are mutually exclusive. Replace is
+rejected with `CONFIG_INVALID` unless the session is `active` with no
+in-flight step, no pending confirmation, and verification and publication
+both `notRun`. A prefix replay failure returns `VERIFICATION_FAILED` and
+leaves the session untouched; superseded step evidence stays in the bundle
+as an audit trail.
+
+**Hot-adjust the idle policy** when `IDLE_TIMEOUT` recurs or the screen
+needs a different stability strategy:
+
+```bash
+taphound generation config idle \
+  --project <project> --session <generationId> \
+  --strategy layoutDiff --timeout-ms 20000 \
+  --json
+```
+
+At least one of `--strategy`, `--poll-interval-ms`, `--stable-polls`,
+`--timeout-ms` is required; the patch merges onto the session's current
+policy and advances the session revision, so the next proposal must bind
+the new revision. Rejected with `CONFIG_INVALID` unless the session is
+`active` with no in-flight step, no pending confirmation, and verification
+and publication both `notRun`. Subsequent observe, step, and finalize replay
+honor the stored policy; `generation status` reports it as `idlePolicy`.

package/assets/skills/taphound-journey-generator/schemas/external-flow.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "TapHound External Flow v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "name", "description", "escapedPackageName", "includes", "steps"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "externalFlow" },
+    "name": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$"
+    },
+    "description": { "type": "string", "minLength": 1 },
+    "escapedPackageName": {
+      "type": "string",
+      "pattern": "^(?:[A-Za-z_$][\\w$]*\\.)+[A-Za-z_$][\\w$]*$"
+    },
+    "expectedEscapeActivity": {
+      "type": "string",
+      "pattern": "^(?:[A-Za-z_$][\\w$]*\\.)+[A-Za-z_$][\\w$]*$"
+    },
+    "includes": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$"
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "object" }
+    }
+  }
+}

package/assets/skills/taphound-journey-generator/schemas/flow.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "TapHound Flow v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "name", "includes", "steps"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "flow" },
+    "name": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$"
+    },
+    "includes": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$"
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "object" }
+    }
+  }
+}

package/assets/skills/taphound-journey-generator/schemas/journey-source.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "TapHound Journey Source v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "name", "includes", "steps"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "journeySource" },
+    "name": { "type": "string", "minLength": 1 },
+    "includes": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$"
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "object" }
+    }
+  }
+}

package/assets/skills/{taphound-ai-journey → taphound-journey-generator}/schemas/observe-output.json

@@ -2,10 +2,10 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://taphound.dev/schemas/observe-output.json",
   "title": "TapHound generation observe --json Output",
-  "description": "Reference shape for the JSON result of `generation observe --json`. The agent parses this to extract binding fields and the full snapshot for the next proposed-step envelope.",
+  "description": "Reference shape for the JSON result of `generation observe --json`. snapshotRef is the authoritative project-relative snapshot evidence path. With --compact, snapshot is omitted and the agent reads snapshotRef before constructing the next proposed-step envelope.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["status", "exitCode", "generationId", "baseRevision", "snapshotHash", "snapshot"],
+  "required": ["status", "exitCode", "generationId", "baseRevision", "snapshotHash", "snapshotRef"],
   "properties": {
     "status": { "const": "observed" },
     "exitCode": { "const": 0 },
@@ -15,9 +15,14 @@
     },
     "baseRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
     "snapshotHash": { "type": "string", "pattern": "^[a-f\\d]{64}$" },
+    "snapshotRef": {
+      "type": "string",
+      "pattern": "^\\.taphound/build/generations/(?:\\.[^/]+\\.work|[^/]+)/evidence/snapshots/revision-\\d{6}/[^/]+/snapshot\\.json$",
+      "description": "Authoritative project-relative RuntimeSnapshot evidence path. Active sessions use the Store-owned .<generationId>.work bundle; publication atomically moves the same evidence to the final <generationId> bundle."
+    },
     "snapshot": {
       "type": "object",
-      "description": "Full RuntimeSnapshot. See proposed-step-envelope.json $defs/RuntimeSnapshot for the detailed schema.",
+      "description": "Full RuntimeSnapshot. Omitted only when --compact is used. See proposed-step-envelope.json $defs/RuntimeSnapshot for the detailed schema.",
       "required": ["version", "generationId", "baseRevision", "deviceSerial", "expectedPackageName", "foregroundPackageName", "activity", "pid", "capturedAt", "layout"],
       "properties": {
         "version": { "const": 1 },
@@ -35,7 +40,11 @@
         },
         "capturedAt": { "type": "string" },
         "screenshotPath": { "type": "string" },
-        "layout": { "type": "array" }
+        "layout": { "type": "array" },
+        "windowHierarchy": {
+          "type": "object",
+          "description": "Conservative comparison between visible touchable target-app windows and semantic layout roots. An incomplete status must block proposal generation."
+        }
       }
     }
   }