taphound 0.2.0-dev.12 → 0.2.0-dev.13

package/assets/skills/taphound-case-suite/SKILL.md

@@ -53,11 +53,13 @@ Use `node <skill>/scripts/ledger.mjs help` for the helper contract.
 
 ## Durable suite directory
 
-The caller chooses an explicit project-relative suite directory. A normal
-layout is:
+A Suite always lives in `.taphound/suites/<suite-id>/` under the project
+root; the helper derives that directory from the Suite ID and rejects any
+other location (and a Brief anywhere but its Case directory) with
+`CASE_SUITE_LOCATION`:
 
 ```text
-doc/development/<suite-id>/
+.taphound/suites/<suite-id>/
 ├── cases.json          # frozen user-approved Case catalog
 ├── case-ledger.json    # mutable, revisioned orchestration state
 ├── STATUS.md           # generated human view; never the Source of Truth
@@ -95,8 +97,7 @@ Create an input from `templates/suite-input.example.json`, then:
 
 ```bash
 node <skill>/scripts/ledger.mjs init \
-  --input /tmp/taphound-suite-input.json \
-  --out <project>/doc/development/<suite-id>
+  --input /tmp/taphound-suite-input.json
 ```
 
 Initialization canonicalizes `projectRoot`, validates dependency cycles and
@@ -215,7 +216,8 @@ Dispatch exactly one Case to `taphound-journey-brief-author` with:
 - exact catalog `sourceText` as `caseGoal`;
 - explicit context paths only;
 - output
-  `<suite>/briefs/<case-id>/taphound-journey-brief.md`.
+  `.taphound/suites/<suite-id>/briefs/<case-id>/taphound-journey-brief.md`
+  (the only path `briefReady` accepts).
 
 After authoring, compute its exact hash and transition:
 

package/assets/skills/taphound-case-suite/scripts/ledger.mjs

@@ -7,7 +7,11 @@ import {
 import {
   dirname, isAbsolute, join, relative, resolve, sep
 } from "node:path";
+import { fileURLToPath } from "node:url";
 
+// Suites are committed TapHound project material; the layout mirrors
+// SUITES_DIR in src/domain/workspace.ts.
+const SUITES_DIR = ".taphound/suites";
 const CATALOG = "cases.json";
 const LEDGER = "case-ledger.json";
 const STATUS = "STATUS.md";
@@ -82,23 +86,36 @@ function canonicalHash(value) {
   return digest(JSON.stringify(canonical(value)));
 }
 
-function exactKeys(value, required, optional = []) {
+// `contract` names the object and, for command inputs, the shipped template
+// so a rejected field points at the shape the command accepts.
+function exactKeys(value, required, optional = [], contract = undefined) {
+  const where = contract === undefined ? "" : ` in ${contract.name}`;
+  const hint = () => {
+    const fields = [...required, ...optional.map((key) => `${key}?`)];
+    return `; allowed fields: ${fields.join(", ")}${
+      contract?.template === undefined
+        ? ""
+        : `; see ${contract.template}`
+    }`;
+  };
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    fail("CASE_SUITE_INVALID", "Expected a JSON object");
+    fail("CASE_SUITE_INVALID", `Expected a JSON object${where}`);
   }
   const allowed = new Set([...required, ...optional]);
   for (const key of Object.keys(value)) {
     if (!allowed.has(key)) {
-      fail("CASE_SUITE_INVALID", `Unknown field "${key}"`);
+      fail("CASE_SUITE_INVALID", `Unknown field "${key}"${where}${hint()}`);
     }
   }
   for (const key of required) {
     if (!(key in value)) {
-      fail("CASE_SUITE_INVALID", `Missing required field "${key}"`);
+      fail("CASE_SUITE_INVALID", `Missing required field "${key}"${where}${hint()}`);
     }
   }
 }
 
+const TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
+
 function nonempty(value, label, max = 1000) {
   if (typeof value !== "string") {
     fail("CASE_SUITE_INVALID", `${label} must be a string`);
@@ -125,6 +142,14 @@ function assertSha(value, label) {
   }
 }
 
+function suiteDirectory(projectRoot, suiteId) {
+  return join(projectRoot, ...SUITES_DIR.split("/"), suiteId);
+}
+
+function suiteBriefPath(suiteId, caseId) {
+  return `${SUITES_DIR}/${suiteId}/briefs/${caseId}/taphound-journey-brief.md`;
+}
+
 function inside(root, path) {
   const rel = relative(root, path);
   return rel === "" || (
@@ -459,6 +484,13 @@ async function loadSuite(suitePath) {
   if (projectRoot !== catalog.projectRoot || !inside(projectRoot, root)) {
     fail("CASE_SUITE_INVALID", "Suite must stay beneath canonical projectRoot");
   }
+  if (root !== suiteDirectory(projectRoot, catalog.suiteId)) {
+    fail(
+      "CASE_SUITE_LOCATION",
+      `Suite ${catalog.suiteId} must live in ${SUITES_DIR}/${catalog.suiteId}, `
+        + `found ${relative(projectRoot, root)}; initialize it there`
+    );
+  }
   const ledger = parseLedger(await json(ledgerPath, LEDGER), catalog);
   const catalogSha256 = digest(catalogBytes);
   if (ledger.catalog.sha256 !== catalogSha256) {
@@ -599,7 +631,8 @@ function parseSuiteInput(value) {
   exactKeys(
     value,
     ["version", "suiteId", "title", "projectRoot", "cases"],
-    ["deviceSerial", "contextPath"]
+    ["deviceSerial", "contextPath"],
+    { name: "init input", template: join(TEMPLATES, "suite-input.example.json") }
   );
   if (value.version !== 1 || !suiteIdPattern.test(value.suiteId ?? "")
     || !isAbsolute(value.projectRoot ?? "")
@@ -629,9 +662,13 @@ function parseSuiteInput(value) {
 async function init(inputPath, outputPath) {
   const input = parseSuiteInput(await json(resolve(inputPath), "Suite input"));
   const projectRoot = await realpath(input.projectRoot);
-  const output = resolve(outputPath);
-  if (!inside(projectRoot, output) || output === projectRoot) {
-    fail("CASE_SUITE_INVALID", "Suite output must be a new directory inside projectRoot");
+  const output = suiteDirectory(projectRoot, input.suiteId);
+  if (outputPath !== undefined && resolve(outputPath) !== output) {
+    fail(
+      "CASE_SUITE_LOCATION",
+      `Suite directory must be ${SUITES_DIR}/${input.suiteId} under projectRoot `
+        + `(${output}); omit --out to use it: ${outputPath}`
+    );
   }
   await access(output).then(
     () => fail("CASE_SUITE_EXISTS", "Suite output already exists"),
@@ -708,7 +745,8 @@ function parseTransition(value) {
   exactKeys(
     value,
     ["version", "expectedRevision", "caseId", "from", "to", "reason"],
-    ["brief", "generation", "failure", "nextAction", "completion"]
+    ["brief", "generation", "failure", "nextAction", "completion"],
+    { name: "transition input", template: join(TEMPLATES, "transition.example.json") }
   );
   if (value.version !== 1 || !caseIdPattern.test(value.caseId ?? "")
     || !statuses.has(value.from) || !statuses.has(value.to)) {
@@ -861,10 +899,12 @@ async function transition(suitePath, inputPath) {
       const briefFile = await regularProjectFile(
         suite.projectRoot, request.brief, `${entry.id}.brief`
       );
-      if (!briefFile.relativePath.endsWith(
-        `/briefs/${entry.id}/taphound-journey-brief.md`
-      )) {
-        fail("CASE_SUITE_INVALID", "Brief path must be Case-specific");
+      const expectedBrief = suiteBriefPath(suite.catalog.suiteId, entry.id);
+      if (briefFile.relativePath !== expectedBrief) {
+        fail(
+          "CASE_SUITE_LOCATION",
+          `Brief for ${entry.id} must be ${expectedBrief}: ${briefFile.relativePath}`
+        );
       }
     }
     if (request.to === "generating") {
@@ -958,10 +998,18 @@ async function transition(suitePath, inputPath) {
 }
 
 function parseFlowRecord(value) {
-  exactKeys(value, [
-    "version", "expectedRevision", "name", "path", "sha256",
-    "exitActivity", "journey", "resolutionManifest", "report"
-  ]);
+  exactKeys(
+    value,
+    [
+      "version", "expectedRevision", "name", "path", "sha256",
+      "exitActivity", "journey", "resolutionManifest", "report"
+    ],
+    [],
+    {
+      name: "record-flow input",
+      template: join(TEMPLATES, "base-flow-record.example.json")
+    }
+  );
   if (value.version !== 1 || !flowNamePattern.test(value.name ?? "")) {
     fail("CASE_SUITE_INVALID", "Invalid Base Flow record");
   }
@@ -1154,12 +1202,26 @@ function help() {
     "TapHound Case Suite Ledger",
     "",
     "Commands:",
-    "  init --input <json> --out <suite-directory>",
+    "  init --input <json> [--out <project>/.taphound/suites/<suite-id>]",
     "  validate --suite <suite-directory>",
     "  status --suite <suite-directory> [--case <case-id>]",
     "  transition --suite <suite-directory> --input <json>",
     "  record-flow --suite <suite-directory> --input <json>",
-    "  recover-lock --suite <suite-directory>"
+    "  recover-lock --suite <suite-directory>",
+    "",
+    `Input templates live in ${TEMPLATES}: suite-input.example.json (init),`,
+    "transition.example.json (transition), base-flow-record.example.json",
+    "(record-flow). Unknown or missing fields are rejected with the allowed list.",
+    "",
+    `Layout: a Suite lives in <projectRoot>/${SUITES_DIR}/<suite-id>/ and each`,
+    "Case Brief in its briefs/<case-id>/taphound-journey-brief.md. Other",
+    "locations fail with CASE_SUITE_LOCATION.",
+    "",
+    "Ledger revision: every successful transition or record-flow increments",
+    "ledger.revision by exactly 1. Pass the current value as expectedRevision",
+    "(read it from `status`); a stale value fails without writing. It is",
+    "unrelated to TapHound generation session revisions (observe +1, step +3",
+    "with its post-action observation), which the ledger never stores."
   ].join("\n");
 }
 
@@ -1172,6 +1234,9 @@ async function main() {
   let output;
   if (command === "init") {
     const input = options(argv, ["--input", "--out"]);
+    if (input.input === undefined) {
+      fail("CASE_SUITE_USAGE", "init requires --input");
+    }
     output = await init(input.input, input.out);
   } else if (command === "validate") {
     const input = options(argv, ["--suite"]);

package/assets/skills/taphound-journey-brief-author/SKILL.md

@@ -104,7 +104,7 @@ Orchestrator (lean context)
 | contextOnly     | no       | `false`                                          | Run only the Context lifecycle (ensure/refresh/regenerate); skip Brief authoring |
 | observeSnapshot | no       | —                                                | Pre-captured `taphound observe --json` result    |
 | device          | no       | doctor auto-selects                              | Device serial                                    |
-| output          | no       | `.taphound/journeys/taphound-journey-brief.md`   | Brief output path (relative to project)          |
+| output          | no       | `.taphound/briefs/<caseId>/taphound-journey-brief.md` | Brief output path (relative to project); must be under `.taphound/briefs/` or `.taphound/suites/<suite-id>/briefs/` |
 
 **Hard rule**: NEVER search for or assume files named `plan.md`,
 `requirement.md`, or any convention. Read ONLY files the caller explicitly
@@ -114,13 +114,18 @@ passes via `contextPaths`. If no `contextPaths` are supplied, work from
 ## Output
 
 For a Brief run, the Skill writes a `taphound-journey-brief.md` at the
-`output` path and returns a structured JSON summary:
+`output` path and returns a structured JSON summary. Briefs are committed
+TapHound material: write them only under `.taphound/briefs/<caseId>/`
+(standalone) or `.taphound/suites/<suite-id>/briefs/<caseId>/` (Case Suite),
+never elsewhere in the project (for example `doc/` or the project root).
+`generation start --brief` rejects any other location with `BRIEF_INVALID`.
+Without a `caseId`, use a short kebab-case name of the Goal as the directory.
 
 ```json
 {
   "status": "authored",
   "caseId": "CASE-002",
-  "path": ".taphound/journeys/taphound-journey-brief.md",
+  "path": ".taphound/briefs/CASE-002/taphound-journey-brief.md",
   "sha256": "<exact-byte-hash>",
   "edgesVerified": 2,
   "edgesNeedsObservation": 1

package/assets/skills/taphound-journey-brief-author/prompts/brief-author-role.md

@@ -43,7 +43,9 @@ The orchestrator dispatches your task with:
 - **observeSnapshot** (optional): Pre-captured `taphound observe --json`
   result. Use it directly; do NOT call `taphound observe` when provided.
 - **output** (optional): Brief output path, defaults to
-  `.taphound/journeys/taphound-journey-brief.md` (relative to project).
+  `.taphound/briefs/<caseId>/taphound-journey-brief.md` (relative to
+  project). It must stay under `.taphound/briefs/` or
+  `.taphound/suites/<suite-id>/briefs/`; refuse any other location.
 
 ## Output
 

package/assets/skills/taphound-journey-brief-author/prompts/brief-author-role.zh-CN.md

@@ -31,7 +31,7 @@ generate`/`refresh`/`rehash`/`validate`/`status`/`list`、`taphound observe`。
 | contextPaths | 否 | 显式文档路径数组，只读这些 |
 | contextOnly | 否 | 为 `true` 时只运行 Context 生命周期（Phase 0），返回 Context 摘要 JSON，不写 Brief |
 | observeSnapshot | 否 | 预采集的 `taphound observe --json` 结果；提供则直接用，不再调 observe |
-| output | 否 | Brief 输出路径，默认 `.taphound/journeys/taphound-journey-brief.md` |
+| output | 否 | Brief 输出路径，默认 `.taphound/briefs/<caseId>/taphound-journey-brief.md`；只能位于 `.taphound/briefs/` 或 `.taphound/suites/<suite-id>/briefs/` 下，拒绝其他位置 |
 
 ## 输出
 

package/assets/skills/taphound-journey-generator/SKILL.md

@@ -86,7 +86,8 @@ risk confirmation, recovery, or final Replay rules.
 
 `journeyBrief` is the Skill-level handoff for one Journey Case. When present,
 it carries `{path, sha256}` pointing to a project-relative
-`taphound-journey-brief.md`. Bind the same path into Core with
+`taphound-journey-brief.md` under `.taphound/briefs/` or
+`.taphound/suites/<suite-id>/briefs/`. Bind the same path into Core with
 `generation start --brief <path>`: Core reads the file itself, computes the
 SHA-256 (never trust an agent-supplied hash), and persists `sourceBrief` in
 the session and the exported meta sidecar, so `journey check` reports
@@ -264,12 +265,18 @@ them with `MANUAL_STEP_REQUIRED`.
       node <skill>/scripts/envelope.mjs bind \
         --input <draft-envelope-path> \
         --from <previous-observe-or-step-output-path> \
-        --out <envelope-path>
+        --out <envelope-path> \
+        --project <project>
       ```
       The draft envelope needs only `version` and `proposal` (binding may be
       omitted or stale); `bind` fills `proposal.binding` from the preceding
       observe output, step output, or raw binding, adds `snapshotRef` when
-      absent, and validates the result offline. The helper contract:
+      absent, and validates the result offline. It also compares
+      `proposal.activity.before` with the bound snapshot's Activity (read
+      from `snapshotRef` under `--project`) and fails with
+      `ENVELOPE_ACTIVITY_MISMATCH`, naming the snapshot Activity, before any
+      device work. `activityCheck: "unverified"` in its output means no
+      snapshot was readable; Core still enforces the check on `step`. The helper contract:
       `node <skill>/scripts/envelope.mjs help`. The resulting shape:
       ```json
       {
@@ -375,10 +382,12 @@ the index with `taphound knowledge rehash --project <project> --json` and
    taphound journey check \
      --project <project> \
      --context .taphound/context/project-context.json \
+     --journey .taphound/journeys/<name>.json \
      --json
    ```
-   The newly published Journey must classify as `fresh`. `journey check`
-   audits every committed Journey under `.taphound/journeys` by comparing
+   The newly published Journey must classify as `fresh`. `--journey`
+   limits the audit to that Journey; without it `journey check` audits every
+   committed Journey under `.taphound/journeys` by comparing
    its sidecar bindings (project, config, and `contextSelection` module
    hashes, plus the Brief content hash when `sourceBrief` is bound) against
    the live project. `--strict` exits `1` when any Journey

package/assets/skills/taphound-journey-generator/prompts/consume-journey-brief.md

@@ -11,7 +11,9 @@ Use this prompt only when the caller supplied `journeyBrief`.
 ## Validation
 
 1. Resolve the path beneath the project root without following a symlink
-   outside it. Its basename must be `taphound-journey-brief.md`.
+   outside it. Its basename must be `taphound-journey-brief.md`, and it must
+   live under `.taphound/briefs/` or `.taphound/suites/<suite-id>/briefs/`
+   (Core rejects other locations with `BRIEF_INVALID`).
 2. Compute SHA-256 over the exact file bytes and compare it with the binding.
 3. Require YAML frontmatter values:
    - `schemaVersion: 2`

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

@@ -102,6 +102,15 @@ the observe result).
      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.
+   - **Screens that load asynchronously**: idle detection only proves the
+     layout tree stopped changing. A full-screen spinner or skeleton is a
+     static tree, so the post-action snapshot can be the loading state. When
+     an action opens a screen that loads, prefer an `element` expect on a
+     control of the loaded screen: Core polls until it appears and returns
+     that settled layout as the next snapshot. When the step needs a `logcat`
+     expect instead, follow it with a `wait` step whose `element` expect names
+     the loaded screen's control, rather than proposing the next action
+     against a loading snapshot.
    - Do not add expectations you cannot verify from source code or Context.
    - Do not invent log patterns that don't exist in the source.
 

package/assets/skills/taphound-journey-generator/scripts/envelope.mjs

@@ -9,7 +9,7 @@
 // schema changes, update this script and its test together.
 import process from "node:process";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 const sha256Pattern = /^[a-f\d]{64}$/;
 const generationIdPattern = /^[A-Za-z\d](?:[A-Za-z\d._-]*[A-Za-z\d])?$/;
@@ -456,7 +456,36 @@ async function readJsonFile(path, label) {
   }
 }
 
-async function bind(inputPath, fromPath, outPath) {
+// The Activity the bound snapshot was captured on, taken from the bind source
+// (full observe/step output), the inline envelope snapshot, or the
+// Store-owned snapshot file under the project root. Undefined when none of
+// them is readable; Core still enforces the check on `generation step`.
+async function boundSnapshotActivity(source, envelope, snapshotRef, projectRoot) {
+  const inline = [
+    ["bind source snapshot", source.snapshot],
+    ["bind source nextSnapshot", source.nextSnapshot],
+    ["envelope.snapshot", envelope.snapshot]
+  ];
+  for (const [from, snapshot] of inline) {
+    if (isPlainObject(snapshot) && typeof snapshot.activity === "string") {
+      return { activity: snapshot.activity, from };
+    }
+  }
+  const ref = envelope.snapshotRef ?? snapshotRef;
+  if (typeof ref !== "string" || !snapshotRefPattern.test(ref)) {
+    return undefined;
+  }
+  try {
+    const snapshot = JSON.parse(await readFile(join(projectRoot, ref), "utf8"));
+    return isPlainObject(snapshot) && typeof snapshot.activity === "string"
+      ? { activity: snapshot.activity, from: ref }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function bind(inputPath, fromPath, outPath, projectRoot) {
   const envelope = await readJsonFile(inputPath, "envelope input");
   exactKeys(
     "envelope input",
@@ -494,6 +523,23 @@ async function bind(inputPath, fromPath, outPath) {
       : { snapshot: envelope.snapshot })
   };
   validateEnvelope(bound);
+  const snapshotActivity = await boundSnapshotActivity(
+    source,
+    bound,
+    snapshotRef,
+    projectRoot
+  );
+  const before = proposal.activity?.before;
+  if (snapshotActivity !== undefined && before !== snapshotActivity.activity) {
+    fail(
+      "ENVELOPE_ACTIVITY_MISMATCH",
+      `proposal.activity.before ${String(before)} does not match the bound snapshot Activity ${
+        snapshotActivity.activity
+      } (from ${snapshotActivity.from}); set activity.before to ${
+        snapshotActivity.activity
+      }`
+    );
+  }
   if (outPath !== undefined) {
     const absolute = resolve(outPath);
     await mkdir(dirname(absolute), { recursive: true });
@@ -505,7 +551,8 @@ async function bind(inputPath, fromPath, outPath) {
       exitCode: 0,
       path: outPath,
       binding,
-      ...(snapshotRef === undefined ? {} : { snapshotRef })
+      ...(snapshotRef === undefined ? {} : { snapshotRef }),
+      activityCheck: snapshotActivity === undefined ? "unverified" : "matched"
     })}\n`);
     return;
   }
@@ -532,16 +579,22 @@ function help() {
     "Commands:",
     "  validate --input <envelope.json>",
     "      Validate one generation step envelope offline (no device, no session).",
-    "  bind --input <envelope.json> --from <observe-or-step-output.json> [--out <path>]",
+    "  bind --input <envelope.json> --from <observe-or-step-output.json> [--out <path>] [--project <root>]",
     "      Fill proposal.binding (and snapshotRef when absent) from the preceding",
     "      observe output, step output, or raw binding, then validate.",
+    "      It also checks proposal.activity.before against the bound snapshot's",
+    "      Activity (from the full output, the inline snapshot, or the snapshot",
+    "      file under --project, default the current directory) and fails with",
+    "      ENVELOPE_ACTIVITY_MISMATCH naming the snapshot Activity. With --out,",
+    "      activityCheck reports \"matched\" or \"unverified\" (no readable snapshot).",
     "",
     "bind writes the bound envelope to --out; without --out the bound envelope",
     "itself is the single stdout JSON value.",
     "",
-    "Revision rule: each accepted step advances the session revision by 2 and",
-    "each observe by 1, so one observe-then-step cycle needs baseRevision + 3.",
-    "Prefer binding from the latest output instead of computing revisions."
+    "Revision rule: observe advances the session revision by 1. A succeeded",
+    "step advances it by 2 for the step plus 1 for the post-action observation",
+    "behind nextBinding, so consecutive steps are 3 apart. Never compute",
+    "revisions: bind from the latest observe or step output."
   ].join("\n");
 }
 
@@ -558,11 +611,11 @@ async function main() {
     return;
   }
   if (command === "bind") {
-    const input = options(argv, ["--input", "--from", "--out"]);
+    const input = options(argv, ["--input", "--from", "--out", "--project"]);
     if (input.input === undefined || input.from === undefined) {
       fail("ENVELOPE_USAGE", "bind requires --input and --from");
     }
-    await bind(input.input, input.from, input.out);
+    await bind(input.input, input.from, input.out, resolve(input.project ?? "."));
     return;
   }
   fail("ENVELOPE_USAGE", `Unknown command ${command}`);

package/dist/application/generation/proposed-step-validator.js

@@ -51,7 +51,11 @@ function validateBinding(session, snapshot, proposal) {
         throw new GenerationOperationError("PACKAGE_ESCAPE", "Foreground package escaped the generation target");
     }
     if (snapshot.activity !== proposal.activity.before) {
-        throw new GenerationOperationError("SNAPSHOT_STALE", "Proposal before Activity does not match the current snapshot");
+        throw new GenerationOperationError("SNAPSHOT_STALE", `Proposal before Activity ${proposal.activity.before} does not match the current snapshot Activity ${snapshot.activity}`, {
+            field: "activity.before",
+            expected: snapshot.activity,
+            actual: proposal.activity.before
+        });
     }
 }
 function validateAction(snapshot, proposal) {

package/dist/application/journey/journey-check-service.d.ts

@@ -30,7 +30,7 @@ export interface JourneyCheckResult {
     entries: readonly JourneyCheckEntry[];
     summary: JourneyCheckSummary;
 }
-export type JourneyCheckErrorCode = "CONFIG_INVALID";
+export type JourneyCheckErrorCode = "CONFIG_INVALID" | "JOURNEY_NOT_FOUND";
 export declare class JourneyCheckError extends Error {
     readonly code: JourneyCheckErrorCode;
     readonly name = "JourneyCheckError";
@@ -41,6 +41,12 @@ export interface JourneyCheckInput {
     config: TapHoundConfig;
     project: ProjectDescription;
     bundle: ProjectContext;
+    /**
+     * Restrict the check to these Journeys. Each selector is a project-relative
+     * Journey path (`.taphound/journeys/<name>.json`) or a Journey name
+     * (`<name>`). A selector that matches no committed Journey fails.
+     */
+    journeys?: readonly string[] | undefined;
 }
 export interface JourneyCheckDependencies {
     store: Pick<JourneyCompositionStore, "read" | "listJourneyPaths" | "readJourneyMeta">;

package/dist/application/journey/journey-check-service.js

@@ -21,6 +21,21 @@ function journeyName(journeyPath) {
         : journeyPath;
     return withoutPrefix.slice(0, -".json".length);
 }
+function selectJourneys(paths, selectors) {
+    if (selectors === undefined || selectors.length === 0) {
+        return paths;
+    }
+    const normalize = (value) => value
+        .replaceAll("\\", "/")
+        .replace(/^\.\//, "");
+    const wanted = new Set(selectors.map(normalize));
+    const selected = paths.filter((path) => (wanted.has(path) || wanted.has(journeyName(path))));
+    const missing = [...wanted].filter((selector) => !selected.some((path) => (path === selector || journeyName(path) === selector)));
+    if (missing.length > 0) {
+        throw new JourneyCheckError("JOURNEY_NOT_FOUND", `No committed Journey matches ${missing.join(", ")} under ${JOURNEYS_DIR}`);
+    }
+    return selected;
+}
 function summarize(entries) {
     const summary = {
         total: entries.length,
@@ -54,7 +69,7 @@ export class JourneyCheckService {
         this.dependencies = dependencies;
     }
     check = async (input) => {
-        const paths = await this.dependencies.store.listJourneyPaths(input.projectRoot);
+        const paths = selectJourneys(await this.dependencies.store.listJourneyPaths(input.projectRoot), input.journeys);
         const projectHash = hashGenerationBinding(input.project);
         const configHash = hashGenerationBinding(input.config);
         const modulesById = new Map(input.bundle.modules.map((module) => [module.id, module]));

package/dist/application/report/report-writer.js

@@ -9,8 +9,12 @@ export function logcatEvidenceWarning(report) {
     if (entries.length === 0)
         return undefined;
     const lines = entries.reduce((total, entry) => total + entry.droppedLines, 0);
-    return `Warning: Logcat evidence is incomplete (${String(lines)} line(s) dropped); `
-        + "Logcat-based expectations fail closed on drops in their window";
+    if (entries.every((entry) => entry.expectationImpact === "none")) {
+        return `Warning (non-fatal): Logcat capture is partial (${String(lines)} line(s) dropped); `
+            + "no Logcat expectation failed, and those expectations fail closed on drops in their window";
+    }
+    return `Warning: Logcat evidence is incomplete (${String(lines)} line(s) dropped) `
+        + "and a Logcat expectation failed; the drops may be the cause";
 }
 function renderSummary(report) {
     const lines = [

package/dist/application/runtime/verify-runtime.js

@@ -658,6 +658,13 @@ export class VerifyRuntime {
                 ].includes(failure.code)
                     ? "error"
                     : "failed";
+        // Logcat expectations fail closed on a relevant drop, so drops can only
+        // have changed the outcome of a Logcat expectation that failed.
+        const expectationImpact = steps.some((step) => (step.expectation?.status === "failed"
+            && (step.expectation.type === "logcat"
+                || step.expectation.type === "logcatEvent")))
+            ? "possible"
+            : "none";
         const report = {
             schemaVersion: 4,
             ...(runtimes.some((runtime) => runtime.logcatStarted
@@ -675,7 +682,8 @@ export class VerifyRuntime {
                                 ...(metadata.lastDroppedAtMs === undefined ? {} : {
                                     lastDroppedAtMs: metadata.lastDroppedAtMs
                                 }),
-                                status: "incomplete"
+                                status: "incomplete",
+                                expectationImpact
                             }];
                     })
                 }

package/dist/application/wait/idle-waiter.js

@@ -115,7 +115,8 @@ export class IdleWaiter {
                     durationMs: this.clock.now() - startedAt
                 };
             }
-            const elapsedBeforePoll = this.clock.now() - startedAt;
+            const pollStartedAt = this.clock.now();
+            const elapsedBeforePoll = pollStartedAt - startedAt;
             polls += 1;
             let observation;
             try {
@@ -246,8 +247,15 @@ export class IdleWaiter {
                     ...telemetry(strategy, backend, fallbackUsed, frameActivityDetected, samplingDurationMs)
                 };
             }
+            // The interval runs from the start of one poll to the start of the
+            // next: a slow sample (a full hierarchy dump) eats into the wait
+            // instead of being added on top of it.
+            const sleepMs = Math.min(config.pollIntervalMs - (this.clock.now() - pollStartedAt), remainingMs);
+            if (sleepMs <= 0) {
+                continue;
+            }
             try {
-                await this.clock.sleep(Math.min(config.pollIntervalMs, remainingMs), signal);
+                await this.clock.sleep(sleepMs, signal);
             }
             catch (error) {
                 if (isAborted(signal)) {

package/dist/cli/commands/generation/session-commands.js

@@ -7,7 +7,7 @@ import { GenerationOperationError, flowReplayFailureDetails } from "../../../app
 import { GenerationSessionIdSchema, verificationPhaseLabel } from "../../../domain/generation.js";
 import { DEFAULT_DEVICE_ROLE } from "../../../domain/journey.js";
 import { ProjectRelativePathSchema } from "../../../domain/project-context.js";
-import { CONFIG_PATH, CONTEXT_INDEX_PATH } from "../../../domain/workspace.js";
+import { CONFIG_PATH, CONTEXT_INDEX_PATH, isJourneyBriefPath, JOURNEY_BRIEF_ROOTS } from "../../../domain/workspace.js";
 import { GenerationSessionStoreError } from "../../../ports/generation-session-store.js";
 import { errorMessage, writeJson, writeLine } from "../../output.js";
 import { canonicalProjectRoot } from "../../project-root.js";
@@ -52,6 +52,9 @@ export function createStartCommand(dependencies) {
                     catch (error) {
                         throw new GenerationOperationError("BRIEF_INVALID", `Journey Brief path must stay within the project: ${briefRequest} (${error instanceof Error ? error.message : String(error)})`);
                     }
+                    if (!isJourneyBriefPath(briefPath)) {
+                        throw new GenerationOperationError("BRIEF_INVALID", `Journey Brief must live under ${JOURNEY_BRIEF_ROOTS.join("/ or ")}/: ${briefPath}`);
+                    }
                     let bytes;
                     try {
                         bytes = await dependencies.readFile(resolve(projectRoot, briefPath));

package/dist/cli/commands/journey.js

@@ -213,6 +213,7 @@ function createCheckCommand(dependencies) {
         .option("--project <path>", "Android project root", dependencies.cwd())
         .option("--config <path>", "TapHound config path", CONFIG_PATH)
         .option("--context <path>", "Project Context index path")
+        .option("--journey <path-or-name...>", "Check only these Journeys (project-relative path or Journey name)")
         .option("--json", "Emit one machine-readable JSON value")
         .option("--strict", "Exit non-zero when any Journey is not fresh")
         .action(async (options) => {
@@ -245,7 +246,8 @@ function createCheckCommand(dependencies) {
                 projectRoot,
                 config,
                 project,
-                bundle: index.bundle
+                bundle: index.bundle,
+                journeys: options.journey
             });
             const notFresh = result.summary.total - result.summary.fresh;
             const exitCode = options.strict === true && notFresh > 0 ? 1 : 0;

package/dist/domain/report.d.ts

@@ -851,6 +851,10 @@ export declare const TapHoundReportV4Schema: z.ZodObject<{
     logcatEvidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
         role: z.ZodString;
         status: z.ZodLiteral<"incomplete">;
+        expectationImpact: z.ZodEnum<{
+            none: "none";
+            possible: "possible";
+        }>;
         droppedLines: z.ZodNumber;
         droppedBytes: z.ZodNumber;
         lastDroppedAtMs: z.ZodOptional<z.ZodNumber>;
@@ -1478,6 +1482,10 @@ export declare const TapHoundReportSchema: z.ZodObject<{
     logcatEvidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
         role: z.ZodString;
         status: z.ZodLiteral<"incomplete">;
+        expectationImpact: z.ZodEnum<{
+            none: "none";
+            possible: "possible";
+        }>;
         droppedLines: z.ZodNumber;
         droppedBytes: z.ZodNumber;
         lastDroppedAtMs: z.ZodOptional<z.ZodNumber>;

package/dist/domain/report.js

@@ -264,6 +264,7 @@ const ReportFields = {
     logcatEvidence: z.array(z.strictObject({
         role: DeviceRoleSchema,
         status: z.literal("incomplete"),
+        expectationImpact: z.enum(["none", "possible"]),
         droppedLines: z.number().int().positive(),
         droppedBytes: z.number().int().positive(),
         lastDroppedAtMs: z.number().nonnegative().optional()

package/dist/domain/workspace.d.ts

@@ -12,6 +12,15 @@ export declare const JOURNEY_SOURCES_DIR = ".taphound/sources";
 export declare const JOURNEYS_DIR = ".taphound/journeys";
 export declare const CONTRACTS_DIR = ".taphound/contracts";
 export declare const BASELINES_DIR = ".taphound/baselines";
+export declare const BRIEFS_DIR = ".taphound/briefs";
+export declare const SUITES_DIR = ".taphound/suites";
+/**
+ * Journey Briefs are committed project material: standalone Briefs live under
+ * `.taphound/briefs/`, Case Suite Briefs under `.taphound/suites/<suite-id>/`.
+ * Nothing else in the project may be bound as a Brief.
+ */
+export declare const JOURNEY_BRIEF_ROOTS: readonly [".taphound/briefs", ".taphound/suites"];
+export declare function isJourneyBriefPath(path: string): boolean;
 export declare const BUILD_DIR = ".taphound/build";
 export declare const GENERATIONS_DIR = ".taphound/build/generations";
 export declare const JOBS_DIR = ".taphound/build/jobs";

package/dist/domain/workspace.js

@@ -14,6 +14,18 @@ export const JOURNEY_SOURCES_DIR = `${TAPHOUND_DIR}/sources`;
 export const JOURNEYS_DIR = `${TAPHOUND_DIR}/journeys`;
 export const CONTRACTS_DIR = `${TAPHOUND_DIR}/contracts`;
 export const BASELINES_DIR = `${TAPHOUND_DIR}/baselines`;
+export const BRIEFS_DIR = `${TAPHOUND_DIR}/briefs`;
+export const SUITES_DIR = `${TAPHOUND_DIR}/suites`;
+/**
+ * Journey Briefs are committed project material: standalone Briefs live under
+ * `.taphound/briefs/`, Case Suite Briefs under `.taphound/suites/<suite-id>/`.
+ * Nothing else in the project may be bound as a Brief.
+ */
+export const JOURNEY_BRIEF_ROOTS = [BRIEFS_DIR, SUITES_DIR];
+export function isJourneyBriefPath(path) {
+    const normalized = posix.normalize(path.replaceAll("\\", "/"));
+    return JOURNEY_BRIEF_ROOTS.some((root) => normalized.startsWith(`${root}/`));
+}
 export const BUILD_DIR = `${TAPHOUND_DIR}/build`;
 export const GENERATIONS_DIR = `${BUILD_DIR}/generations`;
 export const JOBS_DIR = `${BUILD_DIR}/jobs`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taphound",
-  "version": "0.2.0-dev.12",
+  "version": "0.2.0-dev.13",
   "description": "Deterministic app journey recording and verification",
   "license": "Apache-2.0",
   "repository": {
@@ -30,7 +30,8 @@
   "files": [
     "dist",
     "assets/brand/taphound-mark.svg",
-    "assets/skills"
+    "assets/skills",
+    "scripts/feedback-pack.mjs"
   ],
   "engines": {
     "node": ">=22"

package/scripts/feedback-pack.mjs

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+// Redact and pack TapHound generation evidence for a feedback report.
+// Standalone: needs only Node.js and `tar`, not a TapHound checkout.
+//
+// Usage (run from the Android project root, or pass --project):
+//   node feedback-pack.mjs [--project <root>] [--package <pkg>]
+//     [--generation <id>]... [--run <runId>]... [--out <file.tgz>]
+//
+// Unlike `taphound diagnose export` (allowlisted counters, no evidence), this
+// keeps step timing, idle telemetry, and full layout snapshots, which is what
+// timing and screen-state problems need. See docs/diagnostics.md.
+//
+// Collects every JSON file under .taphound/build/generations/<id>/ (including
+// active .<id>.work bundles) and, optionally, .taphound/build/runs/<runId>/
+// report.json. Screenshots, Logcat text, and other non-JSON files are never
+// copied. Package, Activity/class names, resource ids, UI text, Logcat
+// tags/patterns, device serials, and absolute paths are replaced by stable
+// pseudonyms. The pseudonym mapping is written next to the archive, never
+// inside it, so you can translate references back.
+
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+import {
+  existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync,
+  statSync, writeFileSync
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+const HELP = `Usage: node feedback-pack.mjs [options]
+
+  --project <root>     Android project root (default: current directory)
+  --package <pkg>      App package (default: run.packageName in .taphound/config.json)
+  --org-prefix <pfx>   Extra class-name prefix to redact, e.g. com.acme (repeatable)
+  --generation <id>    Only this generation id (repeatable; default: all)
+  --run <runId>        Also include .taphound/build/runs/<runId>/report.json (repeatable)
+  --out <file>         Archive path (default: .taphound/build/diagnostics/
+                       taphound-feedback-<timestamp>.tgz)
+  --help               Show this help
+`;
+
+// Keys whose string values are free UI/business text.
+const TEXT_KEYS = new Set([
+  "text", "contentDescription", "hint", "title", "label", "tooltipText",
+  "pattern", "tag", "event", "literal", "inputText"
+]);
+// Keys whose whole subtree holds business values.
+const VALUE_TREE_KEYS = new Set(["fields", "values", "captures", "bindings"]);
+const SERIAL_KEYS = new Set(["deviceSerial", "serial", "device"]);
+// Keys holding diagnostic sentences that may quote UI text.
+const FREE_TEXT_KEYS = new Set([
+  "message", "reason", "detail", "details", "error", "summary", "diagnostic",
+  "description", "remediation", "stderr", "stdout", "hint"
+]);
+// Packages kept verbatim: they describe the platform, not the app.
+const PUBLIC_PREFIXES = [
+  "android.", "androidx.", "com.android.", "com.google.android.", "java.",
+  "kotlin.", "dalvik.", "io.appium.", "com.github.uiautomator"
+];
+
+const QUALIFIED = /^(?:[A-Za-z_$][\w$]*\.)+[A-Za-z_$][\w$]*$/;
+const RESOURCE_ID = /^([A-Za-z_][\w.]*):(id|string|drawable|layout)\/(.+)$/;
+const HEX_HASH = /^[a-f\d]{40,64}$/;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T[\d:.]+Z?$/;
+
+function parseArgs(argv) {
+  const options = {
+    project: process.cwd(), package: undefined, orgPrefixes: [],
+    generations: [], runs: [], out: undefined, help: false
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    const value = () => {
+      const next = argv[index + 1];
+      if (next === undefined || next.startsWith("--")) {
+        fail(`${flag} requires a value`);
+      }
+      index += 1;
+      return next;
+    };
+    switch (flag) {
+      case "--project": options.project = value(); break;
+      case "--package": options.package = value(); break;
+      case "--org-prefix": options.orgPrefixes.push(value()); break;
+      case "--generation": options.generations.push(value()); break;
+      case "--run": options.runs.push(value()); break;
+      case "--out": options.out = value(); break;
+      case "--help": case "-h": options.help = true; break;
+      default: fail(`Unknown option ${flag}\n\n${HELP}`);
+    }
+  }
+  options.project = resolve(options.project);
+  return options;
+}
+
+function fail(message) {
+  process.stderr.write(`error: ${message}\n`);
+  process.exit(1);
+}
+
+function readPackage(projectRoot) {
+  const configPath = join(projectRoot, ".taphound", "config.json");
+  if (!existsSync(configPath)) return undefined;
+  try {
+    return JSON.parse(readFileSync(configPath, "utf8"))?.run?.packageName;
+  } catch {
+    return undefined;
+  }
+}
+
+function listJsonFiles(directory) {
+  const files = [];
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) walk(path);
+      // Skip macOS AppleDouble "._*" companions of copied files.
+      else if (entry.isFile() && entry.name.endsWith(".json")
+        && !entry.name.startsWith("._")) files.push(path);
+    }
+  };
+  walk(directory);
+  return files.sort();
+}
+
+function collectSources(options) {
+  const buildRoot = join(options.project, ".taphound", "build");
+  const generationsRoot = join(buildRoot, "generations");
+  if (!existsSync(generationsRoot)) {
+    fail(`No generations directory at ${generationsRoot}`);
+  }
+  const wanted = new Set(options.generations);
+  const bundles = readdirSync(generationsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== ".locks")
+    .filter((entry) => {
+      const id = entry.name.replace(/^\.(.+)\.work$/, "$1");
+      return wanted.size === 0 || wanted.has(id);
+    })
+    .map((entry) => join(generationsRoot, entry.name));
+  if (bundles.length === 0) fail("No matching generation bundles found");
+
+  const files = bundles.flatMap(listJsonFiles);
+  for (const runId of options.runs) {
+    const report = join(buildRoot, "runs", runId, "report.json");
+    if (!existsSync(report)) fail(`Run report not found: ${report}`);
+    files.push(report);
+    const verdict = join(buildRoot, "runs", runId, "verdict.json");
+    if (existsSync(verdict)) files.push(verdict);
+  }
+  return { files, bundles };
+}
+
+class Redactor {
+  constructor({ packageName, orgPrefixes, projectRoot }) {
+    this.appPackage = packageName;
+    this.prefixes = [...new Set([
+      packageName,
+      packageName.split(".").slice(0, 2).join("."),
+      ...orgPrefixes
+    ])].filter((prefix) => prefix.includes("."));
+    this.paths = [[projectRoot, "<project>"], [homedir(), "~"]]
+      .filter(([path]) => path.length > 1);
+    this.maps = {
+      package: new Map([[packageName, "com.example.app"]]),
+      class: new Map(),
+      resource: new Map(),
+      text: new Map(),
+      resourceName: new Map(),
+      serial: new Map()
+    };
+  }
+
+  isPrivateName(value) {
+    if (PUBLIC_PREFIXES.some((prefix) => value.startsWith(prefix))) return false;
+    return this.prefixes.some(
+      (prefix) => value === prefix || value.startsWith(`${prefix}.`)
+    );
+  }
+
+  pseudo(kind, value, make) {
+    const map = this.maps[kind];
+    if (!map.has(value)) map.set(value, make(map.size + 1));
+    return map.get(value);
+  }
+
+  packageFor(value) {
+    if (this.maps.package.has(value)) return this.maps.package.get(value);
+    if (value.startsWith(`${this.appPackage}.`)) return undefined;
+    return this.pseudo("package", value, (n) => `com.example.other${n}`);
+  }
+
+  classFor(value) {
+    if (this.maps.package.has(value)) return this.maps.package.get(value);
+    return this.pseudo("class", value, (n) => {
+      const last = value.split(".").at(-1) ?? "";
+      const kind = /Activity$/.test(last) ? "Activity"
+        : /Fragment$/.test(last) ? "Fragment" : "Class";
+      return `com.example.app.${kind}${n}`;
+    });
+  }
+
+  // Pass 1: learn every sensitive value.
+  learn(value, key, inValueTree) {
+    if (Array.isArray(value)) {
+      for (const item of value) this.learn(item, key, inValueTree);
+      return;
+    }
+    if (value !== null && typeof value === "object") {
+      for (const [childKey, child] of Object.entries(value)) {
+        this.learn(child, childKey, inValueTree || VALUE_TREE_KEYS.has(childKey));
+      }
+      return;
+    }
+    if (typeof value !== "string" || value.length === 0) return;
+    if (SERIAL_KEYS.has(key) && !QUALIFIED.test(value)) {
+      this.pseudo("serial", value, (n) => `device-${n}`);
+      return;
+    }
+    if (key === "resourceId" && !value.includes(":")) {
+      // Some UI backends report bare resource names (e.g. "btn_submit").
+      this.pseudo("resourceName", value, (n) => `r${n}`);
+      return;
+    }
+    const resource = RESOURCE_ID.exec(value);
+    if (resource !== null) {
+      const [, owner, type] = resource;
+      if (owner !== "android" && !PUBLIC_PREFIXES.some((p) => `${owner}.`.startsWith(p))) {
+        this.pseudo("resource", value, (n) => {
+          const pkg = owner === this.appPackage ? "com.example.app" : "com.example.other";
+          return `${pkg}:${type}/r${n}`;
+        });
+      }
+      return;
+    }
+    if (QUALIFIED.test(value) && this.isPrivateName(value)) {
+      if (key.toLowerCase().includes("package")) this.packageFor(value);
+      else this.classFor(value);
+      return;
+    }
+    if (TEXT_KEYS.has(key) || inValueTree) {
+      if (HEX_HASH.test(value) || ISO_DATE.test(value)) return;
+      this.pseudo("text", value, (n) => `T${n}`);
+    }
+  }
+
+  finish() {
+    // Longest originals first so a substring never shadows its container.
+    const byLength = (a, b) => b[0].length - a[0].length;
+    const names = [...this.paths];
+    for (const kind of ["serial", "resource", "class", "package"]) {
+      for (const pair of this.maps[kind]) names.push(pair);
+    }
+    this.nameSubstrings = names.sort(byLength);
+    this.textSubstrings = [...this.maps.text, ...this.maps.resourceName]
+      .filter(([original]) => original.length >= 3)
+      .sort(byLength);
+    this.exactNames = new Map(names);
+  }
+
+  // Pass 2: rewrite values. Keys stay verbatim so the schema remains readable.
+  rewrite(value, key = "", inValueTree = false) {
+    if (Array.isArray(value)) {
+      return value.map((item) => this.rewrite(item, key, inValueTree));
+    }
+    if (value !== null && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [
+        childKey,
+        this.rewrite(child, childKey, inValueTree || VALUE_TREE_KEYS.has(childKey))
+      ]));
+    }
+    if (typeof value !== "string") return value;
+    if (this.exactNames.has(value)) return this.exactNames.get(value);
+    if (key === "resourceId" && this.maps.resourceName.has(value)) {
+      return this.maps.resourceName.get(value);
+    }
+    if ((TEXT_KEYS.has(key) || inValueTree) && this.maps.text.has(value)) {
+      return this.maps.text.get(value);
+    }
+    const withNames = this.rewriteString(value, this.nameSubstrings);
+    return FREE_TEXT_KEYS.has(key)
+      ? this.rewriteString(withNames, this.textSubstrings)
+      : withNames;
+  }
+
+  rewriteString(value, pairs = this.nameSubstrings) {
+    // Placeholders keep one replacement's output from matching another original.
+    let result = value;
+    const pending = [];
+    for (const [original, replacement] of pairs) {
+      if (!result.includes(original)) continue;
+      const token = `\u0000${pending.length}\u0000`;
+      result = result.split(original).join(token);
+      pending.push([token, replacement]);
+    }
+    for (const [token, replacement] of pending) {
+      result = result.split(token).join(replacement);
+    }
+    return result;
+  }
+
+  mapping() {
+    return Object.fromEntries(Object.entries(this.maps).map(
+      ([kind, map]) => [kind, Object.fromEntries(
+        [...map].map(([original, replacement]) => [replacement, original])
+      )]
+    ));
+  }
+
+  counts() {
+    return Object.fromEntries(Object.entries(this.maps).map(
+      ([kind, map]) => [kind, map.size]
+    ));
+  }
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const packageName = options.package ?? readPackage(options.project);
+  if (typeof packageName !== "string" || !QUALIFIED.test(packageName)) {
+    fail("Cannot determine the app package; pass --package <pkg>");
+  }
+  const { files, bundles } = collectSources(options);
+  const redactor = new Redactor({
+    packageName, orgPrefixes: options.orgPrefixes, projectRoot: options.project
+  });
+
+  const documents = [];
+  for (const file of files) {
+    try {
+      documents.push([file, JSON.parse(readFileSync(file, "utf8"))]);
+    } catch {
+      process.stderr.write(`skip (not valid JSON): ${relative(options.project, file)}\n`);
+    }
+  }
+  for (const [, document] of documents) redactor.learn(document, "", false);
+  redactor.finish();
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  // The diagnostics directory sits in the Git-ignored build subtree.
+  const out = resolve(options.out ?? join(
+    options.project, ".taphound", "build", "diagnostics",
+    `taphound-feedback-${stamp}.tgz`
+  ));
+  mkdirSync(dirname(out), { recursive: true });
+  const staging = mkdtempSync(join(tmpdir(), "taphound-feedback-"));
+  const root = join(staging, "taphound-feedback");
+  try {
+    for (const [file, document] of documents) {
+      const relativePath = redactor.rewriteString(
+        relative(options.project, file).split(sep).join("/")
+      );
+      const target = join(root, ...relativePath.split("/"));
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, `${JSON.stringify(redactor.rewrite(document), null, 2)}\n`);
+    }
+    writeFileSync(join(root, "README.txt"), [
+      "TapHound feedback bundle (redacted).",
+      `Generation bundles: ${bundles.length}`,
+      `JSON files: ${documents.length}`,
+      `Pseudonyms: ${JSON.stringify(redactor.counts())}`,
+      "Screenshots, Logcat text, and non-JSON files are excluded.",
+      ""
+    ].join("\n"));
+
+    const tar = spawnSync(
+      "tar", ["-czf", out, "-C", staging, "taphound-feedback"],
+      {
+        shell: false,
+        stdio: ["ignore", "inherit", "inherit"],
+        // Stop macOS bsdtar from adding AppleDouble "._*" xattr entries.
+        env: { ...process.env, COPYFILE_DISABLE: "1" }
+      }
+    );
+    if (tar.error !== undefined || tar.status !== 0) {
+      fail(`tar failed${tar.error ? `: ${tar.error.message}` : ""}`);
+    }
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+
+  const mappingPath = out.replace(/\.t(?:ar\.)?gz$/, "") + ".mapping.json";
+  writeFileSync(mappingPath, `${JSON.stringify(redactor.mapping(), null, 2)}\n`);
+
+  process.stdout.write([
+    `Archive:  ${out} (${statSync(out).size} bytes)`,
+    `Mapping:  ${mappingPath}  <- keep this local, do NOT share`,
+    `Bundles:  ${bundles.map((bundle) => basename(bundle)).join(", ")}`,
+    `Files:    ${documents.length} JSON`,
+    `Redacted: ${JSON.stringify(redactor.counts())}`,
+    "Review:   tar -xzf <archive> and grep for anything still sensitive before sharing.",
+    ""
+  ].join("\n"));
+}
+
+main();