@haystackeditor/cli 0.25.1 → 0.26.0

package/README.md

@@ -37,49 +37,24 @@ or `HAYSTACK_TELEMETRY_DISABLED=1` to turn this telemetry off.
 
 ---
 
-## For AI agents: the machine-readable contract
-
-Most consumers of this CLI are coding agents. These invariants hold everywhere:
-
-- **`--json` means pure stdout.** When `--json` is passed, stdout carries exactly
-  one JSON document (NDJSON stream for `setup --json`); all progress, spinners,
-  and prose go to stderr. On failure, stdout still gets a versioned error
-  envelope (`haystack schema error`: `{"schema_version": "1.0.0", "status":
-  "error", "error": "..."}`) and the process exits 1.
-- **Every JSON payload is versioned and schema'd.** Payloads carry
-  `schema_version`; print the contract with `haystack schema <name>`
-  (`haystack schema` lists all: `triage`, `pr`, `pr-status`, `inbox`, `ask`,
-  `traces`, `submit`, `action`, `cloud-verifier`, `error`, `setup`). Schemas
-  are JSON-Schema 2020-12 and CI-guarded against drift.
-- **One state vocabulary.** All state tokens are snake_case across every
-  command: verdicts are `good_to_merge` / `needs_review` / `needs_input`;
-  feed buckets are `analyzing`, `good_to_merge`, `issues`, `needs_assignment`,
-  `needs_shepherding`, etc. No command emits kebab-case states.
-- **PR refs are uniform.** Every command taking a PR accepts `123`, `#123`,
-  `owner/repo#123`, or a GitHub PR URL. Bare numbers infer the repo from the
-  `origin` remote.
-- **Exit codes**: 0 = the requested action happened (a created PR with findings
-  is still 0 — read the verdict from the JSON); 1 = it did not. Commands never
-  print an error and exit 0.
-- **Waiting is bounded and skippable.** `submit` waits up to 10 min for
-  analysis, `triage` polls up to 5 min, `review` up to 25 min; every waiting
-  command takes `--no-wait`. Non-terminal outcomes include a `next` field with
-  the follow-up command (usually `haystack triage <ref> --json`).
-- **"review" disambiguation**: `haystack review` re-runs the *machine*
-  analysis. For *human* review use `haystack submit --review` or
-  `haystack request-review`.
-
-**The agent workflow for submitting:**
-
-```bash
-haystack submit --json          # emits the submit payload incl. ref + analysis verdict
-haystack triage <ref> --json    # poll findings later / after --no-wait
-```
-
-**`haystack mcp`** runs a stdio MCP server exposing the same payloads as tools:
-`inbox_list`, `pr_get`, `pr_status`, `triage_get`, `ask_haystack`,
-`dismiss`, `mark_reviewed`, `undismiss`, `request_review`, `trigger_review`,
-and `schema`.
+## For coding agents
+
+Most users of this CLI are coding agents. What to know:
+
+- **After a change, run `haystack verify`** inside the checkout. Nothing needs
+  to be committed or pushed. Say what you were asked to do with
+  `--intent "<the task, in the user's words>"`, and what to try with
+  `--idea "<as you would tell a tester>"` (repeat it for more).
+- **First time in a repository**, `haystack init --yes` sets it up and starts
+  onboarding the app. `haystack verify onboarding` shows where onboarding is.
+  When onboarding asks a question, answer it with
+  `haystack verify answer <question-id> <choice>`.
+- **`--json` means pure stdout.** stdout carries exactly one JSON document and
+  everything else goes to stderr. A failure still prints the error envelope
+  (`haystack schema error`) and exits 1. `haystack schema <name>` prints any
+  command's contract.
+- **When Haystack gets in your way**, tell us in a sentence and keep going:
+  `haystack feedback "<what happened>"`. The team sees it at once.
 
 **`haystack verify`** shows the product blast radius of your current change:
 where it shows up in the running app, and what broke. Inside a git checkout
@@ -126,45 +101,25 @@ is no time limit, and Ctrl-C stops waiting, never the crawl. It then prints:
 
 `--no-wait` prints the crawl's current state and returns. `--account <login>`
 picks a saved account, and `--repo owner/repo` names the repository when
-`origin` does not. `--json` prints one document, `{ "schema_version", "crawl" }`,
-where `crawl` is the crawl as the service returns it, with its `answer` (what it
-found so far, or its answer once its time is up) while no sealed `manifest`
-exists (or `null` when no crawl of the capture could be started);
-`haystack schema verify` prints its schema. Exit codes follow
-`haystack case-batch status`: 0 when the crawl answered or finished (the bugs
+`origin` does not. `--json` prints the same report as one document: the
+headline, the findings (bugs first, each with its steps), where the change showed
+up, what became of each idea, and what never ran (`haystack schema verify`).
+`--raw` prints the crawl's whole record as the service returns it, for scripts;
+it is large (`haystack schema verify-raw`). Exit codes: 0 when the crawl
+answered or finished (the bugs
 it found are in the output) or is still running under `--no-wait`; 2 when it ended
 without finishing (stopped early, or cancelled because a newer stop in the
 repository replaced it) or the machines it used could not be proven shut down;
 1 when the command failed or no crawl could be started.
 
-**The stop hook.** `haystack hooks install-session --cli claude` installs a
-Claude Code Stop hook that runs `haystack verify precompute --hook` whenever an
-agent turn stops. It captures the checkout within five seconds and hands the
-request to a detached sender; the service then starts the change's analysis
-and, for a repository set up for crawling, its crawl in the background, so
-`haystack verify` usually finds the crawl already running or finished. A newer stop in the same repository replaces an
-older crawl that has not finished. `haystack verify precompute` (without
-`--hook`) submits the same capture in the foreground and prints one line for
-the crawl it started.
-
-The hosted fleet run of exact pushed commits stays available:
-
-```bash
-haystack verify hosted start owner/repo --base <sha> --head <sha> --json
-haystack verify hosted status cv_<48-lowercase-hex-characters> --wait --json
-haystack verify history owner/repo --limit 20
-```
-
-Intent is optional there: `--intent-file <path>` accepts JSON with exactly
-`problem`, `goal`, and `intended_outcomes`. It waits up to 35 minutes by
-default; pass `--no-wait` to return after the fleet run is queued. Repeating the
-same repository, commits, and intent reuses the same run; choose a new
-`--idempotency-key` when a fresh execution is intentional. A fresh run on the
-same base reuses the repository's onboarding: phases that finished are not
-redone, and a phase that stopped terminally starts again once the fleet runs a
-different engine release (on the same release it stays stopped). A wait that expires
-prints `timed_out: true` and `next_command`, then exits 2. Use the returned
-account-bound `next_command` verbatim on machines with multiple saved accounts.
+**The stop hook.** `haystack init` installs a Claude Code Stop hook that runs
+`haystack verify precompute --hook` whenever an agent turn stops. It captures
+the checkout within five seconds and hands the request to a detached sender;
+the service then starts the change's crawl in the background, so
+`haystack verify` usually finds the crawl already running or finished. A newer
+stop in the same repository replaces an older crawl that has not finished.
+`haystack verify precompute` (without `--hook`) submits the same capture in the
+foreground and prints one line for the crawl it started.
 
 Retained fleet cases remain available through their exact case IDs:
 
@@ -173,67 +128,10 @@ haystack verify cases <run-id> --repo owner/repo
 haystack verify explore <run-id> <case-id> --repo owner/repo
 ```
 
-Agents can use the same lifecycle with `haystack verify hosted mcp --account
-<login>`. Its tools are `verify_start`, `verify_status`, and `verify_wait`.
-
-To repeat independent fleet runs for one exact commit pair:
-
-```bash
-haystack verify hosted reproducibility owner/repo \
-  --base <40-character-commit-sha> \
-  --head <40-character-commit-sha> \
-  --runs 3 --json
-```
-
-The report includes each run's fleet receipt. Each ordinal has a distinct
-idempotency key derived from the printed series key, repository, commits, and
-intent; `--series-key <key>` resumes the same series. Independent plans do not
-share an execution identity, so reproducibility remains unestablished and the
-command exits 2. A timeout stops the series and includes the active run's resume
-command.
-
-**`haystack case-batch`** runs an already-generated product-fuzzing case
-batch on the hosted coordinator. The laptop only submits and polls: it holds no
-fleet credential, creates no VM, and kills nothing.
-
-```bash
-haystack case-batch submit --repository owner/repo \
-  --base <40-character-commit-sha> --head <40-character-commit-sha> \
-  --cases cases.json --combinations space.json --max-concurrent 200 --json
-haystack case-batch status <run-id> --repository owner/repo --watch --json
-haystack case-batch cancel <run-id> --repository owner/repo
-haystack case-batch bundle <run-id> --repository owner/repo --out ./bundle
-```
-
-Cases and the combination space travel inline and the whole request is bounded
-at 8 MiB; no source patch is sent unless `--source-patch <file>` names the
-precompute-captured `{ cacheKey, patchSha256, patchGzBase64 }` record.
-`status` follows the case cursor to the end of the list and prints one row per
-case — id, position, status, unknown reason, wall time and whether cleanup was
-proven — including when the batch ends `incomplete`, which exits 2 with a
-summary rather than a single failure. `haystack schema case-batch` prints the
-`--json` schema.
-
-**`haystack setup --json`** speaks NDJSON: events (`question`, `permission`,
-`progress`, `result`) on stdout, replies on stdin keyed by
-`requestID`/`permissionID`. `haystack schema setup` documents the full
-protocol, including the reply shapes. Pre-supply answers with `--repo`,
-`--yes`, `--no-auto-merge`, or `--answers <file>` to skip questions. Note:
-`--yes` enables auto-merge (the wizard default) — pass `--no-auto-merge` to
-opt out.
-
 ---
 
 ## CLI Commands
 
-### `haystack setup`
-
-Interactive onboarding wizard — scan your repos and generate `.haystack.json`:
-
-```bash
-haystack setup
-```
-
 ### `haystack init`
 
 Sets the repository up for `haystack verify` and starts onboarding the app. It
@@ -278,311 +176,18 @@ without waiting, shows them to you, then runs `haystack login` to finish.
 haystack logout
 ```
 
-### `haystack submit`
-
-Create a PR from current changes. Runs pre-PR triage (code review, rules validation), pushes your branch, and opens the PR.
-
-```bash
-haystack submit                      # Triage -> create PR -> wait for analysis
-haystack submit --json               # Agent mode: one JSON doc on stdout, progress on stderr
-haystack submit --title "Fix auth"   # Custom PR title
-haystack submit --draft              # Create as draft PR
-haystack submit --force              # Skip triage checks
-haystack submit --no-wait            # Don't wait for analysis results
-```
-
-**Pre-PR triage**: two checkers run in parallel, each one structured call to
-`gpt-6-astra` over the OpenAI Responses API at reasoning effort `xhigh`.
-The key comes from `OPENAI_API_KEY`
-if set, else from the SSM SecureString `/haystack/secrets/shared/prod/OPENAI_API_KEY`
-(us-west-2) through the default AWS credential chain (e.g. `AWS_PROFILE=prod`).
-With neither, each checker reports `no OpenAI key (...)` and submit continues.
-
-- **code-review** reads `git diff -U10 origin/<base>...HEAD` and reports objective bugs.
-- **rules-validator** runs when `.haystack/pr-rules.yml` or an agent
-  instruction file (`CLAUDE.md`, `AGENTS.md`, `COPILOT.md`, `.cursorrules`,
-  `.github/copilot-instructions.md`) exists, and checks the diff against them.
-
-Each finding carries `file`, `line`, `severity` (`error`/`warning`/`info`),
-`category`, a one-sentence summary and a concrete failure scenario; results
-are saved to `.haystack/triage/<checker>.json`. A finding with severity
-`error` stops the submit (`--force` skips triage). A checker that cannot run
-(missing key, API error, stalled stream) prints `code review failed: <error>`
-and the submit continues. The reviewer sees only the diff, not the rest of the
-repository. `--triage-timeout <sec>` (or `.haystack.json` `triage.timeoutMs`)
-aborts a checker whose response stream has been silent that long (default
-300s); there is no total-time cap.
-
-The `--json` payload (`haystack schema submit`) reports the PR ref, the
-resolved title/body and where each came from, auto-merge/auto-fix state with
-its source (flag vs `.haystack.json`), and the analysis outcome in the shared
-verdict vocabulary.
-
-**Review routing**: By default, PRs go to the auto-merge queue -- if analysis passes, the PR is merged automatically. Use `--review` to route it for human review instead:
-
-```bash
-haystack submit --review             # Needs review (goes to assignment queue)
-haystack submit --review octocat     # Request review from a specific teammate
-```
-
-When `--review` is used without a username, the PR is labeled `haystack:needs-review` and appears in your team's assignment queue. When a username is provided, that person is also requested as a reviewer on GitHub.
-
-### `haystack triage`
-
-View Haystack analysis results for any PR. Shows the same data as the Haystack web feed: rating, verdict, structured findings with details, verified bugs, human review reasons, and agent fix prompts.
-
-```bash
-haystack triage                             # Last submitted PR
-haystack triage 42                          # Current repo, PR #42
-haystack triage owner/repo#99               # Fully qualified
-haystack triage https://github.com/o/r/pull/1  # From GitHub URL
-haystack triage 42 --json                   # Machine-readable JSON output
-haystack triage 42 --no-wait                # Don't wait if analysis is pending
-haystack triage --hook                      # Minimal one-liner (for session hooks)
-haystack triage --clear                     # Clear pending submit state
-```
-
-When called without a PR identifier, checks the last PR submitted via `haystack submit`. The `--hook` flag produces a single-line summary with the Haystack rating, designed for session-start hooks.
-
-The `--json` output includes every finding and its customer-facing `suggested_fix` when available.
-
-### `haystack inbox list`
-
-List PRs in your Haystack inbox with the reason each PR is present and the next action:
-
-```bash
-haystack inbox list
-haystack inbox list --json
-```
-
-### `haystack pr get`
-
-Get the useful state of one PR: triage and minimal merge blockers:
-
-```bash
-haystack pr get 42
-haystack pr get owner/repo#42 --json
-```
-
-### `haystack ask`
-
-Ask Haystack Chat about a PR. Machine output contains the answer and every customer-facing source Chat consulted:
-
-```bash
-haystack ask 42 "Why is this finding legitimate?"
-haystack ask owner/repo#42 "Show the implementation" --json
-haystack ask owner/repo#42 "What about its callers?" --session <session-id> --json
-```
-
-Chat may search the complete authorized repository when the changed files are insufficient. Search results and fetched source are included in `evidence`.
-
-### `haystack review`
-
-Trigger a fresh *machine* analysis of a PR's current head (Haystack analyzes once at PR open; later pushes only get a resolution check). For requesting *human* review, use `haystack request-review`.
-
-```bash
-haystack review 42                   # Re-analyze and wait for the result
-haystack review 42 --no-wait         # Trigger and exit
-haystack review 42 --json            # Machine-readable outcome (schema: action)
-```
-
-### `haystack request-review`
+### `haystack feedback`
 
-Tag a PR as needing human review (adds `haystack:needs-review`), optionally requesting a specific GitHub user:
+Tell the Haystack team something went wrong, confused you, or is missing. It
+lands with the team at once, with the CLI version, your platform and the
+checkout's repository.
 
 ```bash
-haystack request-review 42                 # Into the needs-assignment queue
-haystack request-review 42 octocat         # Also request review from octocat
-haystack request-review 42 --json
+haystack feedback "verify said the app never started, but it was up on :3000"
+haystack feedback --run cv_<id> "the bug it reported is the intended change"
+echo "longer report" | haystack feedback -
 ```
 
-### `haystack dismiss`
-
-Dismiss analysis findings for a PR, moving it from "Issues Found" to "Good to Merge" in the feed. The override is tied to the PR's current HEAD commit.
-
-```bash
-haystack dismiss 42                  # Dismiss findings for PR #42
-haystack dismiss acme/widgets#99     # Dismiss for specific repo
-haystack dismiss 42 --json           # Machine-readable (schema: action)
-```
-
-### `haystack undismiss`
-
-Clear all overrides (dismissed findings and/or review-not-needed) for a PR, returning it to its original feed bucket.
-
-```bash
-haystack undismiss 42                # Undo overrides for PR #42
-haystack undismiss acme/widgets#99   # Undo for specific repo
-```
-
-### `haystack mark-reviewed`
-
-Mark human review as not needed for a PR, moving it from "Needs Review" to "Good to Merge" in the feed. The override is tied to the PR's current HEAD commit.
-
-```bash
-haystack mark-reviewed 42                  # Mark review not needed for PR #42
-haystack mark-reviewed acme/widgets#99     # Mark for specific repo
-```
-
-### `haystack pr-status`
-
-Show what bucket a PR is in within the Haystack pipeline (analyzing, good-to-merge, issues, needs-assignment, etc.):
-
-```bash
-haystack pr-status 42                          # Current repo, PR #42
-haystack pr-status acme/widgets#99             # Specific repo
-haystack pr-status https://github.com/o/r/pull/1  # From URL
-haystack pr-status 42 --json                   # Machine-readable output
-```
-
-### `haystack config`
-
-Manage user preferences:
-
-```bash
-# Agentic tool selection
-haystack config agentic-tool              # Show current setting
-haystack config agentic-tool opencode     # Use Haystack billing (default)
-haystack config agentic-tool claude-code  # Use your Claude Max subscription
-haystack config agentic-tool codex        # Use your ChatGPT subscription
-
-# Auto-merge for safe PRs
-haystack config auto-merge           # Show current status
-haystack config auto-merge on        # Enable auto-merge
-haystack config auto-merge off       # Disable auto-merge
-
-# AI reviewer wait list (merge queue waits for ALL configured bots before merging)
-haystack config wait-for-reviewers                    # Show status
-haystack config wait-for-reviewers add cursor         # Wait for Cursor BugBot
-haystack config wait-for-reviewers add cursor coderabbit  # Add multiple
-haystack config wait-for-reviewers remove cursor      # Stop waiting
-haystack config wait-for-reviewers clear              # Wait for none
-# Also accepts raw GitHub bot usernames (must end in [bot]):
-haystack config wait-for-reviewers add cursor-bugbot[bot]
-```
-
-Reviewer names are validated: anything that is neither a known friendly name
-nor a `...[bot]` username is rejected (a stored typo would make the merge
-queue wait forever for a bot that can't post).
-
-### `haystack skills`
-
-Manage AI skills for your coding CLI:
-
-```bash
-haystack skills install              # Install portable .agents/skills
-haystack skills install --cli codex  # Portable install for Codex
-haystack skills install --cli claude # Also install Claude command shims
-haystack skills install --cli manual # Install portable skills and print their location
-haystack skills list                 # List available skills
-haystack skills scaffold-provisional-universe --input /tmp/facts.json # Write a missing-authority receipt
-haystack skills prepare-universe-review --json # Build a filtered reviewer source snapshot
-haystack skills validate-universe --json # Parse and cross-check universe artifacts
-```
-
-Installed skills include `/map-cloud-verifier-universe`, which asks the
-customer's coding agent to map the application's production dependencies and
-uses a read-only reviewer subagent to check the map before Cloud Verifier
-onboarding. It first checks for an authoritative hosted-deployment source; if
-that source is private, it produces a provisional map and one bounded request
-for a summary from the customer's local replicator or catalog. It never asks
-for production credentials or direct Haystack access to production.
-
-Start a customer-owned Cloud Verifier adapter before a universe map exists, from
-only the three selections the user actually makes — which application, which
-environment, and which approved replica destination:
-
-```bash
-haystack cloud-verifier connector bootstrap \
-  --application-id Checkout \
-  --environment-id production \
-  --destination-policy-file ./replica-destination-policy.json
-```
-
-Application and environment accept a plain name and are normalized to stable IDs
-(`application:checkout`, `environment:production`); pass an explicit
-`application:<id>` when you want to choose it yourself. The destination is named
-by its approved policy document, whose SHA-256 the command computes and reports.
-Pass `--destination-policy-sha256 <64-hex>` instead only if your tooling already
-holds the digest. Exactly one of the two is required.
-
-The scaffold stays blocked until the customer's coding agent completes bounded
-local discovery and provider-profile conformance. It includes the lifecycle and
-binding executable, encrypted connector-owned vault contract, cold golden
-refresh scheduler, and a setup/update-only reviewer-subagent request. No
-reviewer runs on ordinary verification requests or routine golden refreshes.
-
-### `haystack hooks`
-
-Manage git hooks for AI agent quality checks:
-
-```bash
-# Install hooks
-haystack hooks install
-haystack hooks install --force       # Overwrite existing hooks
-
-# Status
-haystack hooks status                # Check installation status
-
-# Session hooks (triage on CLI start; Claude Code's Stop hook starts a crawl,
-# see `haystack verify`)
-haystack hooks install-session              # Auto-detect CLIs
-haystack hooks install-session --cli claude # Claude Code only
-haystack hooks install-session --cli all    # All detected CLIs
-haystack hooks session-status               # Check session hook status
-```
-
-### `haystack case-batch`
-
-Submit and poll product-fuzzing case batches on the hosted coordinator
-(`CASE-BATCH-V1`):
-
-```bash
-# Submit an ordered batch against one frozen world pair
-haystack case-batch submit --repository owner/repo \
-  --base <sha> --head <sha> \
-  --cases cases.json --combinations space.json \
-  --base-world frz_<16-hex> --head-world frz_<16-hex> \
-  --max-concurrent 200 --per-case-wall-ms 15000 --total-budget-ms 600000 --json
-
-# Read every per-case outcome; --watch polls until terminal or --max-wall
-haystack case-batch status <run-id> --repository owner/repo --watch --json
-
-# Request cancellation (a claimed batch drains until its owner proves cleanup)
-haystack case-batch cancel <run-id> --repository owner/repo
-
-# Download the replay bundle, verifying every artifact digest
-haystack case-batch bundle <run-id> --repository owner/repo --out ./bundle
-```
-
-`bundle` requires the service's sealed SHA-256 for `manifest.json` (served as
-its ETag), because the manifest is the one artifact with no parent digest to
-check it against; without it the command fails and writes nothing. Every other
-artifact is checked against the sha256 and byte length the manifest declares
-for it.
-
-Knobs and what turning them does:
-
-| Flag | Default | Effect |
-|------|---------|--------|
-| `--max-concurrent <n>` | the case count, capped at 500 | Ceiling only. Admitted concurrency is the smaller of it and the fleet's free capacity; the run's receipt reports both. |
-| `--per-case-wall-ms <ms>` | 120000 | A case that overruns is killed and recorded `UNKNOWN`/`wall-budget`, never dropped. Above the MVP's measured 103.8 s maximum, so it does not kill cases running at today's cost. |
-| `--total-budget-ms <ms>` | 1800000 (the contract ceiling) | Bounds launches from the first launch. Cases already launched run to their own wall budget. |
-| `--warm-settle-ms <ms>` | absent (0) | Each arm adopts only a warm clone that has been ready at least this long, 0 to the per-case wall. A clone adopted right after its restore attaches cold (quiet fleet: connectMs 5.8 s at 0 vs 1.1 s after 3.5-6 s of idle); each second of settle can delay a case's first create by up to a second. |
-| `--idempotency-key <key>` | derived from the whole submission | An exact retry returns the original run; a new key is a new execution. |
-| `--interval <seconds>` | 10 | Polling interval while `--watch` is set. |
-| `--max-wall <minutes>` | 45 | Total polling wall. Hitting it prints the snapshot, says `timed_out`, and exits 2. |
-
-`status` exits 0 for a `completed` batch with cleanup proven, and 2 for
-`incomplete`, `cancelled`, unproven cleanup, or a wait that hits `--max-wall`.
-Either way every per-case row is printed. A `--json` row from a v4 batch also
-carries `node_ids: { base1, head }` (the node each arm's VM was placed on) and
-`failure: { source, arm, error_class, error_code, node_id }` (the typed fact
-behind an `UNKNOWN` that is not an arrival or wall outcome, and behind an
-`arrival-failed` whose two arms stalled on the same step, `same-step-stall`); each
-is `null` when the outcome has none. A case in `--cases` may carry `repeatIndex` (1-16), which
-must be part of its `contentDigest`, to run as a repeat next to its original.
-
 ### `haystack db profile`
 
 Describe your production Postgres database so Haystack can build a full-size
@@ -722,27 +327,6 @@ whole profile succeeds. On a primary, dead-row shares come from
 `pg_stat_user_tables`; a table with rows but no counts there (statistics reset)
 stops the run and asks for `ANALYZE` on that table.
 
-### `haystack policy`
-
-Manage review policies (`.haystack/review-policy.md`):
-
-```bash
-# List and inspect
-haystack policy list                          # List all policies
-
-# Add policies
-haystack policy add                           # Interactive add
-haystack policy add "Database changes"        # Start with name
-haystack policy add-instruction "Never flag weak test coverage as needing review"
-
-# Remove policies
-haystack policy remove "Database changes"
-
-# Initialize with defaults
-haystack policy init                          # Create with sensible defaults
-haystack policy init --force                  # Overwrite existing
-```
-
 ---
 
 ## How It Works

package/dist/capture/app-config.js

@@ -12,8 +12,9 @@
  *   publish  the directories (relative to the app) the build step publishes the manifest into, so haystack-capture-step,
  *            which loads nothing of the CLI, can withdraw a stale current.json there when the manifest was not made.
  */
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, posix } from 'node:path';
 import { CAPTURE_KEY_PATTERN, CAPTURE_STATUS_PATH, CAPTURE_VERSION } from '../commands/capture-contract.js';
 import { haystackFetch, haystackJson } from '../utils/haystack-api.js';
 export const CAPTURE_CONFIG_PATH = '.haystack/capture.json';
@@ -42,6 +43,29 @@ export function readCaptureConfig(appDir) {
     }
     return parsed;
 }
+/** The directories (repository-relative, posix; '.' for the root) holding a .haystack/capture.json: those git lists
+ * (committed, or not yet), and the candidates that have one even when ignored. */
+export function captureConfigDirs(gitRoot, candidates) {
+    const listed = spawnSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', CAPTURE_CONFIG_PATH,
+        `:(glob)**/${CAPTURE_CONFIG_PATH}`], { cwd: gitRoot, encoding: 'utf8' });
+    if (listed.status !== 0)
+        throw new Error(`git ls-files failed in ${gitRoot}: ${listed.stderr.trim()}`);
+    return [...new Set([...listed.stdout.split('\0').filter(path => path !== '' && !path.split('/').includes('node_modules'))
+                .map(path => posix.dirname(posix.dirname(path))), ...candidates])].filter(dir => existsSync(captureConfigFile(join(gitRoot, dir)))).sort();
+}
+/** The apps (repository-relative, posix; '.' for the root) whose .haystack/capture.json records them: the user's earlier
+ * answer to which app serves production. Records git lists (committed, or not yet), and those in the candidate app
+ * directories even when ignored. */
+export function recordedApps(gitRoot, candidates) {
+    return captureConfigDirs(gitRoot, candidates).filter(dir => {
+        try {
+            return readCaptureConfig(join(gitRoot, dir))?.app === dir;
+        }
+        catch (error) {
+            throw new Error(`${posix.join(dir, CAPTURE_CONFIG_PATH)}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
 export function formatCaptureConfig(config) {
     return `${JSON.stringify(config, null, 2)}\n`;
 }