archal 0.9.19 → 0.10.0

package/skills/attach/SKILL.md

@@ -1,402 +0,0 @@
----
-name: attach
-description: Connect Archal Attach to a repo and trace source, validate prerequisites, configure trace schema mapping, and diagnose import, grade, reproduction, and PR-fix runs.
-user-invocable: true
-argument-hint: "[repo, trace source, or failure description]"
----
-
-# Archal Attach
-
-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.
-
-Attach 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.
-
-## Product mental model
-
-Attach does 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.
-
-Default policy is `fix`. Narrower policies stop earlier:
-
-| Policy | Stops after |
-|--------|-------------|
-| `observe` | import |
-| `grade` | grading |
-| `reproduce` | reproduction |
-| `fix` | PR or blocked fix status |
-
-Do not invent or promote separate top-level judge, reproduce, fix, or
-trace-replay commands. The public command is `archal attach`. Local stop
-command is `archal detach` for file-backed trace directories.
-
-## Discover first
-
-Before changing anything, inspect the repo:
-
-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
-   - 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 Attach 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:
-
-```bash
-npm install -D archal
-npx archal login
-npx archal usage
-```
-
-In CI or a customer repo, use:
-
-```bash
-export ARCHAL_TOKEN=archal_ws_...
-npx archal usage
-```
-
-Use a workspace API key for automated runs. Do not commit it.
-
-### 2. Add or verify `archal/harness.json`
-
-Minimal shape:
-
-```json
-{
-  "version": 1,
-  "local": {
-    "command": "node",
-    "args": ["agent.mjs"]
-  }
-}
-```
-
-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 Attach harness with that command.
-
-### 3. Add or verify `archal/scenario.md`
-
-The scenario describes the standing task and checks for this trace family.
-
-Required sections:
-
-```md
-# Scenario title
-
-## Setup
-Trace-family context and the starting state Archal should reconstruct.
-
-## Prompt
-The task the agent should complete.
-
-## Expected Behavior
-The answer key for grading and reproduction.
-
-## Success Criteria
-- [D] Deterministic clone-state check
-- [P] Probabilistic trace/output check
-
-## Config
-clones: stripe, slack
-timeout: 120
-```
-
-Keep model-visible instructions realistic. Do not tell the tested agent that it
-is in Archal, a clone-backed environment, or a special replay.
-
-### 4. Add seed templates when trace evidence is thin
-
-Recommended:
-
-```text
-archal/seeds/
-  stripe-billing-support.json
-  jira-escalations.json
-```
-
-Seed templates should contain stable service state for the task family. Attach
-can then fill in trace-specific identifiers. This is much safer than expecting
-weak traces to reconstruct full service state.
-
-## Hosted database source
-
-Use this when traces live in Postgres or Supabase.
-
-First, create or request a read-only database user. Then keep the URL in an env
-var:
-
-```bash
-export TRACE_DATABASE_URL='postgres://readonly:...'
-```
-
-Run a check:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source supabase \
-  --database-url-env TRACE_DATABASE_URL \
-  --source-id prod-agent-traces \
-  --check
-```
-
-Register:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source supabase \
-  --database-url-env TRACE_DATABASE_URL \
-  --source-id prod-agent-traces
-```
-
-This posts the source config to Archal and returns. It does not start a local
-watcher and does not write local source state.
-
-Use a secret reference when the customer already has one:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source postgres \
-  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces
-```
-
-`--database-url-secret-ref` must not contain a plaintext credential.
-
-## Trace schema mapping
-
-Defaults:
-
-| Concept | Default |
-|---------|---------|
-| trace table | `ai_traces` |
-| span table | `ai_spans` |
-| trace id | `id` |
-| span id | `id` |
-| span trace id | `trace_id` |
-| trace updated cursor | `updated_at` |
-| span updated cursor | `updated_at` |
-| cursor mode | `updated_at_id` |
-
-For a custom schema, pass mapping flags:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source postgres \
-  --database-url-env TRACE_DATABASE_URL \
-  --trace-table public.agent_traces \
-  --span-table public.agent_spans \
-  --trace-id-column trace_id \
-  --span-id-column span_id \
-  --span-trace-id-column trace_id \
-  --parent-span-id-column parent_span_id \
-  --trace-updated-at-column updated_at \
-  --span-updated-at-column updated_at
-```
-
-For append-only sources:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source supabase \
-  --database-url-env TRACE_DATABASE_URL \
-  --cursor-mode created_at_id \
-  --trace-created-at-column created_at \
-  --span-created-at-column created_at
-```
-
-Use filters for noisy sources:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source supabase \
-  --database-url-env TRACE_DATABASE_URL \
-  --source-workspace-id workspace_123 \
-  --source-agent-id support-agent \
-  --source-status failed error \
-  --source-trace-group billing-support \
-  --source-limit 250
-```
-
-## Local trace directory
-
-Use this for a local pilot or exported trace files:
-
-```bash
-npx archal attach ./prod-traces --repo . --execution-policy reproduce
-```
-
-Artifacts are written under:
-
-```text
-.archal/attach/
-  attachments.json
-  runs.jsonl
-  raw/
-  grades/
-  seeds/
-  runs/
-  fixes/
-  failed/
-  logs/
-```
-
-Stop the local file-backed loop:
-
-```bash
-npx archal detach ./prod-traces --repo .
-```
-
-Do not describe `archal detach` as a hosted source disable command.
-
-## Dashboard expectations
-
-The workspace dashboard has three Attach pages:
-
-- Imported traces: source status, imported rows, grade verdict, blocked reason.
-- Reproduced failures: seed evidence, reproduction status, clone parity, run
-  artifacts.
-- Opened issues/PRs: GitHub issue, PR, branch, checks, and fix status.
-
-Do not route users to an old single Attach page. The user-facing pages are the
-three workspace dashboard pages above.
-
-## How to diagnose failures
-
-Classify failures precisely:
-
-- Trace import failure: database/source auth, mapping, cursor, filters, bad
-  trace shape.
-- 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 Attach uses repo-local artifacts. Hosted Attach exposes the
-same phase information in the dashboard.
-
-| Artifact | What to inspect |
-|----------|-----------------|
-| `grades/<trace>/routing.json` | trace import route and selected phase |
-| `grades/<trace>/grade.json` | verdict, summary, and 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 |
-| `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.
-- 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.
-- Do not bypass the GitHub App PR workflow with direct pushes.
-- Redact raw trace payloads before sharing artifacts outside the workspace.
-
-## What to report back
-
-After setup or debugging, give the user:
-
-- command run
-- source provider and source id
-- repo full name
-- execution policy
-- dashboard pages to inspect
-- artifacts produced, if local
-- whether import, grade, seed, reproduce, and fix phases are ready
-- exact blocker if any
-- next command or next owner
-
-## Docs
-
-- Attach production traces: https://docs.archal.ai/guides/attach-production-traces
-- CLI reference: https://docs.archal.ai/cli/attach
-- 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