archal 0.9.20 → 0.10.0

package/skills/autoloop/SKILL.md

@@ -7,12 +7,13 @@ argument-hint: "[repo, trace source, or failure description]"
 
 # Archal Autoloop
 
-You help users connect real agent traces to Archal. Your job is to wire the repo,
-trace source, harness contract, scenario contract, and GitHub PR path without
-guessing or leaking secrets.
+You help users connect real agent traces to Archal, then drive the loop that
+turns a production failure into a verified reproduction and, when the user
+opts in, a fix PR. Your job is to wire the repo, trace source, harness, and
+scenario without guessing or leaking secrets.
 
-Autoloop is not a replacement for `archal run`. It uses the same harness and clone
-routing ideas, but the trigger is a trace that already happened.
+Autoloop is not a replacement for `archal run`. It uses the same harness and
+clone routing, but the trigger is a trace that already happened.
 
 Autoloop is also not arbitrary production trace replay. It can reproduce a
 failure only when the trace, scenario contract, and seed templates contain
@@ -21,331 +22,351 @@ is thin, block and name the missing data instead of claiming reproduction.
 
 ## Product mental model
 
-Autoloop does this loop:
+Autoloop runs this loop:
 
 1. Import a trace and its child spans from a read-only source.
 2. Grade whether the trace contains a real failure.
 3. Build a reproduction scenario and clone seed from trace evidence plus
    repo-owned seed templates.
 4. Run the reproduction against service clones through the customer harness.
-5. If reproduced, patch the repo and open a GitHub issue or PR.
+5. If reproduced, patch the repo and open a GitHub PR.
 
 Steps 1-4 are **autoloop**: ingest -> grade -> find the failed trace ->
 reproduce on clones. Step 5 (writing the fix and opening the PR) is **autofix**,
 a separate opt-in step that is *not* part of autoloop until it is turned on.
-Both are per-agent toggles, switchable from the agents tab, the CLI, or by asking
-the Archal copilot in chat.
 
-The CLI maps these toggles to `--execution-policy`: `reproduce` runs autoloop
-only with autofix off, while `fix` turns autofix on (autoloop plus the fix/PR
-step). Narrower policies stop earlier:
+## Consent breakpoints (do these before you touch anything)
 
-| Policy | Stops after | Autofix |
-|--------|-------------|---------|
-| `observe` | import | off |
-| `grade` | grading | off |
-| `reproduce` | reproduction | off |
-| `fix` | PR or blocked fix status | on |
+Autoloop can act on the user's real repository and reads their production
+traces. Before you register a source or start a loop, walk the three
+breakpoints below **in order**. Each is a hard STOP: ask the question, wait for
+an explicit answer, and only then proceed. Do not batch them, do not assume a
+default, and do not start the loop until all three are answered.
 
-Do not invent or promote separate top-level judge, reproduce, fix, or
-trace-replay commands. The public command is `archal autoloop`. Local stop
-command is `archal detach` for file-backed trace directories.
+### Breakpoint 1 - PR-opening consent
 
-## Discover first
+STOP. Before anything else, state the consequence plainly and ask the user to
+choose:
 
-Before changing anything, inspect the repo:
+> Autoloop can open fix PRs on your repo automatically. With **Autofix ON**,
+> every imported production failure that reproduces gets a fix PR opened on
+> your repo. With **Autofix OFF**, autoloop stops after reproducing the failure
+> and opens no PRs; you (or your agent) take over from the reproduction.
+> Which do you want?
 
-1. `package.json` and scripts: how is the agent run? What tests should a fix PR
-   pass?
-2. Existing Archal files:
-   - `.archal.json`
-   - `.archal/harness.*`
-   - `archal/harness.json`
-   - `archal/scenario.md`
-   - `archal/run-input.yaml`
-   - `archal/seeds/*.json`
-   - `scenarios/*.md`
-3. Service SDKs and likely clones:
-   - `stripe` -> `stripe`
-   - `@octokit/rest`, `octokit` -> `github`
-   - `@slack/web-api`, `@slack/bolt` -> `slack`
-   - `jira`, `jira-client`, `jira.js` -> `jira`
-   - `@linear/sdk` -> `linear`
-   - `@supabase/supabase-js`, `pg` -> `supabase`
-   - `googleapis` -> `google-workspace`
-4. GitHub remote:
-   ```bash
-   git remote get-url origin
-   ```
-   Hosted sources and `--execution-policy fix` need a GitHub remote.
-5. Trace source shape, if available:
-   - provider: local files, Postgres, Supabase
-   - or local/client-ingested sources normalized through `archal trace-source`
-     such as file, HTTP/OTel, Langfuse, Braintrust, S3/GCS, or custom JSON
-   - trace table and span table names
-   - id columns
-   - parent span column
-   - timestamp/cursor columns
-   - status, workspace, trace group, and agent filters
-
-Never print secrets while inspecting. If you need to show a database URL, show
-only the env var name or secret reference.
-
-## Preconditions
-
-You need these before a full hosted Autoloop setup:
-
-- Archal CLI installed in the repo or reachable with `npx archal`
-- authenticated user (`archal login`) or `ARCHAL_TOKEN=archal_ws_...`
-- GitHub App installed on the target repo
-- repo origin that resolves to `github.com/<owner>/<repo>`
-- read-only trace source credential
-- headless harness command
-- `archal/scenario.md` for the trace family
-- optional but strongly recommended `archal/seeds/*.json`
-- model/provider keys required by the user's agent and tests
-
-If any prerequisite is missing, make the smallest safe change and explain what
-is still required. Do not continue into a fake reproduction.
-
-## Safe setup flow
-
-### 1. Install and authenticate
-
-Prefer project-local install:
+Map the answer explicitly and never rely on the CLI default:
 
-```bash
-npm install -D archal
-npx archal login
-npx archal usage
-```
+| User wants | Pass | Autofix |
+|------------|------|---------|
+| Fix PRs opened automatically | `--execution-policy fix` | ON |
+| Reproduce only, no PRs | `--execution-policy reproduce` | OFF |
 
-In CI or a customer repo, use:
+The bare `archal autoloop` default is `fix`, which opens PRs. **Never let that
+default stand in silently.** Always pass an explicit `--execution-policy` that
+matches the user's answer. The reproduce-only promise is real: with
+`--execution-policy reproduce`, autoloop grades and replays against clones and
+then stops, with no fix and no PR.
 
-```bash
-export ARCHAL_TOKEN=archal_ws_...
-npx archal usage
-```
+### Breakpoint 2 - GitHub App install (only if the user chose fix PRs)
 
-Use a workspace API key for automated runs. Do not commit it.
+If the user chose **reproduce only**, skip this breakpoint and note that the
+fix path stays off.
 
-### 2. Add or verify `archal/harness.json`
+If the user chose **fix PRs**, STOP and explain, then wait for confirmation:
 
-Minimal shape:
+> The fix-PR path needs the **Archal GitHub App** installed on the target repo
+> and linked to your Archal workspace. The app is granted least-privilege
+> access: write to repository contents (to push a fix branch) and to pull
+> requests (to open the PR), plus read-only access to Actions, checks, commit
+> statuses, and metadata so it can watch its own PR's checks. It gets **no**
+> issue access, and it opens a PR from a fix branch rather than pushing to your
+> default branch. Install it from the Archal dashboard's integrations /
+> connect-repo flow, then tell me once it is installed (or say you'd rather stay
+> reproduce-only).
 
-```json
-{
-  "version": 1,
-  "local": {
-    "command": "node",
-    "args": ["agent.mjs"]
-  }
-}
-```
+Do not proceed to a `fix` policy until the user confirms. Verify the install
+with the machine check before starting the loop:
 
-The command must be headless and repeatable. It should run the real agent path,
-not a hand-authored mock. During reproduction, Archal invokes this command
-through `archal run`, so the agent should read the task from `AGENT_TASK` and
-print its final answer to stdout. If the project already has `.archal.json` for
-`archal run`, align the Autoloop harness with that command.
+```bash
+npx archal autoloop --repo . --execution-policy fix --check --json
+```
 
-### 3. Add or verify `archal/scenario.md`
+The `GitHub App auth` check must pass (a repo-scoped PR token can be minted). A
+failing check tells you exactly what is missing; relay that, don't guess.
 
-The scenario describes the standing task and checks for this trace family.
+### Breakpoint 3 - read-only database connection string
 
-Required sections:
+STOP whenever the trace source is a database (Postgres or Supabase). Do not
+accept a privileged or default connection string. Walk the user through
+creating a **read-only** role scoped to the trace tables, then:
 
-```md
-# Scenario title
+- The credential is passed by **environment variable name**, not value:
+  `--database-url-env <ENV_VAR_NAME>`. Never put the URL inline in a command,
+  never echo it, never commit it.
+- In hosted production, prefer a secret reference:
+  `--database-url-secret-ref <ref>` (the ref must not contain a plaintext
+  credential).
 
-## Setup
-Trace-family context and the starting state Archal should reconstruct.
+Ask the user to confirm the role is read-only and the URL lives in an env var
+or secret ref before you run any `--source` command. See
+`references/hosted-sources.md` for the read-only-role and flag detail.
 
-## Prompt
-The task the agent should complete.
+## Discover first
 
-## Expected Behavior
-The answer key for grading and reproduction.
+Before changing anything, inspect the repo:
 
-## Success Criteria
-- [D] Deterministic clone-state check
-- [P] Probabilistic trace/output check
+1. `package.json` and scripts: how is the agent run? What tests should a fix PR
+   pass?
+2. Auth: `archal usage` must pass. For hosted sources, CI, or headless agents,
+   use a workspace API key in `ARCHAL_TOKEN`, created by an owner/admin with
+   `archal workspace api-key create <label>`.
+3. GitHub remote: `git remote get-url origin`. Hosted sources and the `fix`
+   policy need an origin that resolves to `github.com/<owner>/<repo>`.
+4. Docker: high-fidelity reproduction needs Docker or sandbox mode available.
+   If Docker is unavailable, stop before claiming clone-backed reproduction.
+5. Existing Archal files: `.archal.json`, `archal/harness.json`,
+   `archal/scenario.md`, `archal/seeds/*.json`, `scenarios/*.md`.
+6. Service SDKs and likely clones: `stripe` -> `stripe`; `@octokit/rest`,
+   `octokit` -> `github`; `@slack/web-api`, `@slack/bolt` -> `slack`;
+   `jira.js` -> `jira`; `@linear/sdk` -> `linear`; `@supabase/supabase-js`,
+   `pg` -> `supabase`; `googleapis` -> `google-workspace`.
+7. Trace source shape: provider (local files, Postgres, Supabase), trace/span
+   table names, id columns, parent-span column, cursor columns, and any
+   workspace/agent/status/group filters.
+
+Never print secrets while inspecting. Show only the env var name or secret
+reference, never a database URL.
+
+## Setup files
+
+### `archal/harness.json`
 
-## Config
-clones: stripe, slack
-timeout: 120
+```json
+{ "version": 1, "local": { "command": "node", "args": ["agent.mjs"] } }
 ```
 
-Keep model-visible instructions realistic. Do not tell the tested agent that it
-is in Archal, a clone-backed environment, or a special replay.
+The command must be headless and repeatable, and run the real agent path (not a
+mock). During reproduction Archal invokes it through `archal run`, so the agent
+reads its task from `AGENT_TASK` and prints its final answer to stdout. Align it
+with the `agent` command in `.archal.json` if one exists.
 
-### 4. Add seed templates when trace evidence is thin
+### `archal/scenario.md`
 
-Recommended:
+Describes the standing task and checks for this trace family. Required sections:
+`# Title`, `## Setup`, `## Prompt`, `## Expected Behavior`,
+`## Success Criteria` (`[D]` deterministic, `[P]` probabilistic), `## Config`
+(`clones:`, `timeout:`). Keep model-visible instructions realistic: do not tell
+the tested agent it is in Archal, a clone-backed environment, or a replay.
 
-```text
-archal/seeds/
-  stripe-billing-support.json
-  jira-escalations.json
-```
+### Seed templates (when trace evidence is thin)
 
-Seed templates should contain stable service state for the task family. Autoloop
-can then fill in trace-specific identifiers. This is much safer than expecting
-weak traces to reconstruct full service state.
+Put stable service state for the task family under `archal/seeds/*.json` (e.g.
+`stripe-billing-support.json`). Autoloop fills in trace-specific identifiers.
+This is far safer than expecting a weak trace to reconstruct full service state.
 
-## Hosted database source
+## Register the loop
 
-Use this when traces live in Postgres or Supabase. Create a read-only DB user,
-keep the URL in `TRACE_DATABASE_URL` (or a secret ref in hosted production), then
-`--check` the source and re-run without `--check` to register it. Registration
-posts the source config to Archal and returns; hosted workers own polling after
-that, so local `archal detach` does not disable it.
+### Local trace directory (pilot / exported files)
 
-See `references/hosted-sources.md` for the full check, register, and
-`--database-url-secret-ref` flag blocks.
+```bash
+npx archal autoloop ./prod-traces --repo . --execution-policy reproduce
+```
 
-## Client-side trace ingestion
+Uses the policy from Breakpoint 1. Artifacts land under `.archal/autoloop/`
+(see the artifact guide below). Stop it with
+`npx archal autoloop detach ./prod-traces --repo .`.
 
-Use `archal trace-source` when traces are not already in a hosted Postgres or
-Supabase table. This command normalizes source-specific payloads into Archal
-trace upload envelopes, writes them to a trace directory, and can upload them to
-hosted Autoloop when workspace auth is available.
+### Hosted database source (Postgres / Supabase)
 
-Common paths:
+The source identity, schema mapping, cursor, and filters live in the
+`.archal.json` `autoloop` block, not in flags. The starter takes only `--repo`,
+`--source`, the credential (`--database-url-env` or `--database-url-secret-ref`),
+`--execution-policy`, `--check`, and `--json`. A minimal config names the source:
 
-```bash
-npx archal trace-source import ./exports --preview --json
-npx archal trace-source import ./exports --upload --repository owner/repo
-
-npx archal trace-source connect langfuse \
-  --base-url https://cloud.langfuse.com \
-  --api-key-env LANGFUSE_READ_KEY \
-  --out .archal/traces/inbox
-npx archal trace-source test langfuse
-npx archal trace-source sync langfuse --upload --repository owner/repo
-npx archal trace-source watch langfuse --upload --repository owner/repo
-
-npx archal trace-source connect custom --name "prod exporter" --out .archal/traces/inbox
-npx archal trace-source serve "prod exporter" --port 4319
+```jsonc
+// .archal.json
+{
+  "autoloop": {
+    "source": { "name": "prod-agent-traces" }
+  }
+}
 ```
 
-Use `archal trace-source status [source]` to inspect registry validation,
-cursor, and last-sync state. `watch` is for pull-style sources; push sources
-stay continuous through `serve`.
+Check first, then register (drop `--check` to register). Registration posts the
+source config to Archal and returns; hosted workers own polling after that, so
+`autoloop detach` does not disable a hosted source.
 
-## Trace schema mapping
+```bash
+npx archal autoloop --repo . --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --execution-policy reproduce --check --json
+```
 
-Hosted sources default to `ai_traces` / `ai_spans` with `id` / `trace_id`
-columns and `updated_at_id` cursor mode. When the customer's tables differ, pass
-mapping flags to override table names, id columns, parent-span column, and
-cursor columns; switch to `created_at_id` cursor mode for append-only sources;
-and use `--source-*` filters to scope noisy sources by workspace, agent, status,
-trace group, or limit.
+See `references/hosted-sources.md` for the read-only-role and secret-ref detail,
+and `references/trace-schema-mapping.md` when the customer's tables differ from
+the `ai_traces` / `ai_spans` defaults (custom columns, append-only cursor mode,
+and source filters). Both are configured under `autoloop.source` in `.archal.json`.
 
-See `references/trace-schema-mapping.md` for the full defaults table plus the
-custom-schema, append-only, and filter flag blocks.
+### Client-side ingestion (traces not already in a hosted table)
 
-## Local trace directory
+For traces not in a hosted Postgres/Supabase table, use the dashboard OTLP
+endpoint or drop normalized JSON files into an autoloop watch directory:
 
-Use this for a local pilot or exported trace files:
+- **Dashboard OTLP** — point the vendor's OpenTelemetry exporter at the OTLP
+  URL shown in the dashboard. Works for Langfuse, Braintrust, OTel, and custom
+  HTTP sources. No CLI command required.
+- **File drop** — place normalized Archal trace JSON files in the watch
+  directory and run `archal autoloop <trace-dir>`. The loop picks them up on
+  the next import cycle.
 
-```bash
-npx archal autoloop ./prod-traces --repo . --execution-policy reproduce
-```
+## Policy semantics
 
-Artifacts are written under:
-
-```text
-.archal/autoloop/
-  autoloops.json
-  runs.jsonl
-  raw/
-  grades/
-  seeds/
-  runs/
-  fixes/
-  failed/
-  logs/
-```
+Two independent toggles, both per-agent and switchable from the agents tab, the
+CLI, or the Archal copilot:
 
-Stop the local file-backed loop:
+- **Autoloop toggle** - whether the loop runs at all (import -> grade ->
+  reproduce). Off means no traces are processed.
+- **Autofix toggle** - whether the fix / PR phase runs. ON maps to
+  `--execution-policy fix`; OFF maps to `--execution-policy reproduce`.
 
-```bash
-npx archal detach ./prod-traces --repo .
-```
+`--execution-policy` stops the loop at a phase; narrower policies stop earlier:
+
+| Policy | Stops after | Autofix |
+|--------|-------------|---------|
+| `observe` | import | off |
+| `grade` | grading | off |
+| `seed` | seeding | off |
+| `reproduce` | reproduction | off |
+| `fix` | PR or blocked fix status | on |
 
-Do not describe `archal detach` as a hosted source disable command.
-
-## CLI-first operation
-
-Prefer CLI and artifact evidence for handoffs unless the user explicitly asks
-for a workspace page.
-
-- Local file-backed loops: `archal autoloop <trace-dir> --repo ...` starts the
-  watcher, `archal detach <trace-dir> --repo ...` stops it, `archal
-  autoloop-status --repo ...` summarizes trace jobs, and `archal
-  autoloop-reprocess --repo ... <trace-id>` retries terminal jobs after a
-  blocker is fixed.
-- Hosted database sources: `archal autoloop --source postgres|supabase ...`
-  registers the source and returns. Local `archal detach` does not disable a
-  hosted source because hosted workers own polling after registration.
-- Safe resume means re-running the same `archal autoloop` registration or
-  reprocessing a terminal local trace only after the missing evidence,
-  credential, mapping, harness, or GitHub blocker is corrected.
-
-Report exact artifact paths and statuses. Do not make dashboard pages the only
-place a user can understand what happened.
-
-## How to diagnose failures
-
-Classify failures precisely:
-
-- Trace import failure: database/source auth, mapping, cursor, filters, bad
-  trace shape.
-- Trace ingestion failure: `trace-source` adapter mismatch, rejected hosted
-  upload, missing workspace auth, bad idempotency key, or receiver auth failure.
-- Grade failure: judge could not determine expected outcome, missing evaluator
-  contract, trace lacks task context.
-- Missing evidence: trace does not contain enough state to seed. Add spans,
-  state snapshots, or repo-owned seed templates.
-- Reproduction failure: scenario or seed could not replay the failure against
-  clones. Inspect generated `scenario.md`, `seed.json`, and run manifest.
-- Agent behavior: the reproduced run shows the agent making the same wrong
-  service action it made in the original trace.
-- Harness issue: the agent command crashes, hangs, needs UI auth, or does not
-  reach clone-routed services.
-- Fix generation issue: patch does not apply, tests fail, no changes produced,
-  or generated PR metadata is incomplete.
-- GitHub issue: GitHub App missing, branch protection, permission denied, PR
-  checks unavailable.
-
-When evidence is insufficient, say so directly. Do not manufacture a seed or
-claim reproduction succeeded.
-
-## Artifact reading guide
-
-Local file-backed Autoloop uses repo-local artifacts. Hosted Autoloop exposes the
-same phase information in the dashboard.
+Policy is **pinned at import time**. Flipping a toggle affects future imports
+and retries, not runs that already imported under the old policy.
+
+## CLI surface
+
+Machine-readable, CLI only. Every command takes `--json` for scripting. Do not
+call raw REST endpoints or dashboard URLs.
+
+The starter flags are deliberately narrow: `--repo`, `--source`,
+`--database-url-env`, `--database-url-secret-ref`, `--execution-policy`,
+`--check`, and `--json`. Everything about the source itself — its name/id, schema
+mapping, cursor mode and watermarks, filters, metadata, and regression scenarios export —
+lives in the `.archal.json` `autoloop` block, not in flags. A retired flag now
+exits `2` with a message naming the config field to set instead.
+
+- `archal autoloop [trace-dir] --repo <repo> [--source postgres|supabase] [--execution-policy observe|grade|seed|reproduce|fix] [--check] [--json]`
+  starts a local file-backed loop or registers a hosted source.
+  - `--check --json` emits `{ ok, checks[], nextStep? }` and exits `2` when not
+    ready, `0` when ready. Read `checks[]` for the exact blocker.
+  - The starter (no `--check`) `--json` emits `{ ok, ... }` describing the
+    registered source or started loop.
+- `archal autoloop status [run-id] [--json]` - without a run id: local ledger
+  status for each trace job. `--json` emits `{ ok, jobs[] }`; each row is a
+  trace-job summary (`traceId`, `status`, `currentPhase`, `action`,
+  `nextAction`, `attemptSummary`, `checkSummary`, `artifactSummary`,
+  `reference`, `stale`, `retryable`, `updatedAt`, plus raw ledger fields such
+  as `prUrl` and `error` when present). `--wait --until terminal|pr
+  --poll-interval <seconds> --wait-timeout <seconds>` polls for CI gates and
+  exits `0` when the condition holds, `1` on timeout or a terminal-failed job;
+  the `--json` shape is identical with or without `--wait`, and a failed wait
+  emits `{ ok: false, jobs[], error, kind: "wait_failed" }`.
+  With a hosted `<run-id>`: fetches that run's status, grade evidence, and
+  artifacts. This is the take-over entry point. `--json` emits
+  `{ ok, run, gradeEvidence, artifacts }`; `--artifact <artifactId>` prints one
+  artifact's payload instead. The wait-family flags and `--repo` are local-only
+  and cannot be combined with a run id.
+- `archal autoloop reprocess [trace-id] | --all-failed` - re-queue terminal
+  local trace jobs after fixing the blocker. Hidden from help (repair escape
+  hatch), still runnable.
+- `archal autoloop detach <trace-dir>` - stop a local file-backed loop. Does
+  not disable a hosted source.
+
+Related commands used during take-over and debugging:
+
+- `archal reproduce failures <grades> --json` - turn failed grades into a
+  seedable reproduction package. `archal reproduce verify <package-dir> --json`
+  re-checks seed and run evidence for an existing package.
+- `archal grade trace --request <file> --json` - grade one trace.
+- `archal autoloop status --json` - inspect registered sources and job state.
+- `archal traces list|detail --json` - list and inspect uploaded traces.
+
+Exit codes across this family: `0` success, `1` failure, `2` usage error or
+not-ready. Failures under `--json` emit `{ ok: false, error, kind, ... }`.
+
+## Take-over workflow
+
+The killer use case: autoloop graded (and, under `reproduce`, replayed) a real
+production failure, and now a coding agent takes over to write and verify the
+fix. Runbook:
+
+1. **Find the run.** `archal autoloop status --json` for local jobs, or use the
+   hosted run id you were handed. Note the trace id and phase.
+2. **Pull the evidence into context.** `archal autoloop status <run-id> --json`
+   returns `run` (grade status, failure class, reproduction status, PR/branch
+   if any, blocking reason), `gradeEvidence` (score, threshold, summary,
+   per-criterion results), and `artifacts` (ids, types, sizes).
+3. **Fetch the artifact you need.** For a specific payload (grade summary,
+   generated scenario, seed, run manifest), pass its id:
+   `archal autoloop status <run-id> --artifact <artifactId> --json`. For a
+   local loop, the same evidence is on disk under `.archal/autoloop/` (see the
+   artifact guide).
+4. **Reproduce locally.** Turn the graded failure into a reproduction package
+   and replay it against clones: `archal reproduce failures <grades> --json`
+   (point `<grades>` at the local `grades/<trace>/grade.json` or a grade
+   artifact directory). This confirms the failure is real before you touch code.
+5. **Write the fix** in the repo.
+6. **Verify against the same reproduction.** `archal reproduce verify <package-dir> --json`
+   (or re-run step 4). The fix is done when the same reproduction that failed
+   now passes.
+7. **Watch it land.** With Autofix ON, autoloop opens the PR; gate on it with
+   `archal autoloop status --wait --until pr` or watch the
+   PR directly. With Autofix OFF, open the PR yourself once the reproduction
+   passes.
+
+## Diagnose failures
+
+Classify precisely; do not manufacture a seed or claim reproduction succeeded
+when evidence is thin.
+
+- **Trace import** - source auth, mapping, cursor, filters, or a bad trace shape.
+- **Trace ingestion** - rejected upload, missing workspace auth, bad idempotency
+  key, or OTLP receiver auth failure.
+- **Grade** - judge could not determine the expected outcome; missing evaluator
+  contract; trace lacks task context.
+- **Missing evidence** - trace lacks enough state to seed. Add spans, state
+  snapshots, or repo-owned seed templates.
+- **Reproduction** - scenario or seed could not replay the failure. Inspect the
+  generated `scenario.md`, `seed.json`, and run manifest.
+- **Harness** - agent command crashes, hangs, needs UI auth, or never reaches
+  clone-routed services.
+- **Fix generation** - patch does not apply, tests fail, no changes produced,
+  or PR metadata is incomplete.
+- **GitHub** - App missing, branch protection, permission denied, or PR checks
+  unavailable. Re-run `archal autoloop --check --json` to confirm.
+
+## Artifact reading guide (local loops)
+
+Local file-backed loops write repo-local artifacts; hosted loops expose the
+same phase information through `archal autoloop status <run-id>`.
 
 | Artifact | What to inspect |
 |----------|-----------------|
 | `grades/<trace>/routing.json` | trace import route and selected phase |
-| `grades/<trace>/grade.json` | verdict, summary, and reproduction decision |
+| `grades/<trace>/grade.json` | verdict, summary, reproduction decision |
 | `seeds/<trace>/scenario.md` | generated reproduction scenario |
-| `seeds/<trace>/seed.json` | generated seed request or materialized seed metadata |
-| `runs/<trace>/manifest.json` | reproduction status, command, attempts, evidence |
+| `seeds/<trace>/seed.json` | materialized seed metadata |
+| `runs/<trace>/manifest.json` | reproduction status, command, attempts |
 | `runs/<trace>/stdout.json` | machine-readable run output |
-| `runs/<trace>/stderr.log` | reproduction stderr |
 | `fixes/<trace>/status.json` | blocked fix status |
 | `fixes/<trace>/pr-details.md` | PR reviewer summary |
 | `fixes/<trace>/repo.patch` | patch captured when PR creation cannot complete |
 
 ## Security rules
 
-- Use read-only trace database credentials.
-- Never commit database URLs, API keys, model keys, or GitHub tokens.
-- Prefer `--database-url-env` locally and `--database-url-secret-ref` in hosted
-  production setup.
+- Use read-only trace database credentials (Breakpoint 3).
+- Never commit or echo database URLs, API keys, model keys, or GitHub tokens.
+  Prefer `--database-url-env` locally and `--database-url-secret-ref` in hosted
+  production.
 - Do not pass production write credentials to a clone-routed reproduction.
 - Do not add model-visible copy that reveals Archal or clone routing to the
   tested agent.
@@ -354,23 +375,17 @@ same phase information in the dashboard.
 
 ## What to report back
 
-After setup or debugging, give the user:
-
-- command run
-- source provider and source id
-- repo full name
-- execution policy
-- CLI status command to run next
-- artifacts produced, if local
-- whether import, grade, seed, reproduce, and fix phases are ready
-- exact blocker if any
-- next command or next owner
+After setup or debugging, give the user: the command run; the execution policy
+and how it maps to the Autofix answer from Breakpoint 1; source provider and id;
+repo full name; which phases (import, grade, seed, reproduce, fix) are ready;
+the exact blocker if any; local artifact paths if applicable; and the next CLI
+command or owner. Prefer CLI and artifact evidence over telling the user to open
+a dashboard page.
 
 ## Docs
 
 - Autoloop production traces: https://docs.archal.ai/guides/autoloop-production-traces
-- Autonomous loops: https://docs.archal.ai/guides/autoloop-production-traces
-- CLI reference: https://docs.archal.ai/cli/autoloop
+- Autoloop CLI: https://docs.archal.ai/cli/autoloop
 - Running with an agent: https://docs.archal.ai/guides/run-with-agent
 - Writing scenarios: https://docs.archal.ai/guides/writing-scenarios
 - Seeds: https://docs.archal.ai/guides/seeds