# corva-fe-ai-tools

Two things in one repo:

1. **`@corva/fe-ai-tools`** — the standalone, versioned Ask Corva **app-tools kit** (result
   builders, command/overlay/budget primitives, `createToolset`, the register/eval
   hooks, the param readers, and an executable reusable fault matrix) imported by DC and
   platform FE apps. Source in [`src/`](src/); `yarn build` (tsup) / `yarn test` (Vitest) /
   `yarn lint`. React is a peer dependency.
2. **The coverage playbook** — instruction library for covering Corva FE apps with Ask Corva
   AI tools, eval suites, dialogue scenarios, scripts, and coverage tracking (everything
   below).

Use this repo as the working playbook. Links to `corva-web-frontend` are freshness
references only — an agent should start here, pick the right workflow, and execute
without first reading another repo.

## Start here — what do you need to do?

| I need to… | Go to |
| --- | --- |
| **Onboard an app** — add Ask Corva tools and cover it | [workflows/README.md](workflows/README.md) |
| **Maintain an already-covered DC or built-in platform app** | [workflows/README.md](workflows/README.md) with `maintain --range <base>...<head>` |
| **Re-qualify an existing app on the current toolkit contract** | [workflows/existing-app-upgrade-prompt.md](workflows/existing-app-upgrade-prompt.md) |
| **Inspect or roll out the toolkit across repositories** | [docs/reference/fleet-management.md](docs/reference/fleet-management.md); [evolution and future automation](docs/reference/fleet-evolution.md) |
| **Close an app PR and synchronize coverage/Jira** | [docs/reference/delivery-sync.md](docs/reference/delivery-sync.md) |
| **Test an app / see how the agent uses its tools** | [workflows/testing/](workflows/testing/) — Recipe E for acceptance; Recipe A for exploration/debugging |
| **Understand how Ask Corva works** (concepts first) | **New to Ask Corva?** ↓ (next section) |
| Work on **platform-core tools / multi-app routing** | [workflows/platform/](workflows/platform/) - core contract, host confirmation, integration proof |
| See **what's already covered** / the backlog | [docs/coverage/](docs/coverage/) |
| **Plan or track** multi-wave work (tiers, statuses, waves) | [plans/README.md](plans/README.md) |

Every onboarded app gets an Ask Corva tool surface, dialogue scenarios, and a live
acceptance pass. **Only the apps already listed as anchors** in
[docs/coverage/coverage-policy.md](docs/coverage/coverage-policy.md) additionally get
a full graded eval suite. Onboarding reads that policy; it does not select or score
anchors itself.

## New to Ask Corva? Read this first

If you have never seen Ask Corva, spend five minutes on the mental model before
touching a workflow. The workflow READMEs assume you know these two things — they
own the *process*, not the concepts.

1. [docs/reference/architecture.md](docs/reference/architecture.md) — how a user
   prompt becomes a UI change, what a "deferred tool" is, how a tool reaches the
   agent (`prompt → agent → app-call-tool → your handler → state`). The *why*
   behind every convention; includes the agent roster + glossary.
2. [docs/reference/tool-authoring.md](docs/reference/tool-authoring.md) — what a
   tool is, the two kinds, and exactly how one looks (folder shape, envelope, and
   the class-specific description standard).
3. [docs/reference/app-tool-structure.md](docs/reference/app-tool-structure.md) —
   the canonical layered `src/ai-tools` module, import boundaries, deterministic
   gate, and independent structure verdict.
4. [docs/reference/eval-harness.md](docs/reference/eval-harness.md) — how the
   harness drives the real UI and grades state (read when you reach testing/evals).
5. [docs/reference/platform-surfaces.md](docs/reference/platform-surfaces.md) — the
   three tiers of CWF frontend tools (global core, platform surface, DC app), which
   tier a capability belongs to, and the surface-registry contract. Read with
   [docs/coverage/cwf-tools.md](docs/coverage/cwf-tools.md), the inventory of every
   tool CWF ships and the condition under which the agent can see it.
6. [docs/reference/canon-revisions.md](docs/reference/canon-revisions.md) — the
   numbered log of canon changes. Every covered app stamps the revision it shipped
   under, so a repo opened later can apply just the delta instead of a re-read.

## App coverage flow

[`workflows/README.md`](workflows/README.md) is the only owner of initial coverage
and later maintenance: stage order, independent review, repair, evidence freshness,
Git delivery, and handoff. A concrete invocation runs through final tests, commit,
push, draft PR, required PR checks, and exact remote-PR-head validation without an
intermediate Git-authorization pause. Start with one absolute app path and an
explicit mode:

```md
@workflows/README.md /absolute/path/to/app onboard
@workflows/README.md /absolute/path/to/app maintain --range <base>...<head>
```

The stage guides under `workflows/<stage>/README.md` contain execution detail for
discovery, tools, scenarios, anchor evals, and live testing. Platform-core and
multi-app integration are routed by [workflows/platform/](workflows/platform/).

## App launchers (onboard / test)

Two launchers turn a few answers into a ready start: they locate the app repo
(cloning it with `--clone` if absent), seed its live-test `.env`, write a
machine-readable JSON result, and print where to start + the operational
gotchas, then point you back into this README for the navigation. Run them from
the repo root (or by absolute path — they resolve their own location):

```bash
# Cover an app (add AI tools) — the slug is all it needs (interactive prompt):
scripts/launch/onboard.sh

# …or headless (how the agent runs it, after taking the repo from you):
scripts/launch/onboard.sh --repo directional-surveys-and-projections [--clone] [--dry-run]

# Test an app (drive the agent live) — repo + recipe:
scripts/launch/test-app.sh --repo directional-surveys-and-projections --recipe E [--clone]

# Print the questions a script asks (the agent reads this to know what to ask you):
scripts/launch/onboard.sh --print-questions
```

The app name is derived from the slug; onboarding follows
[the canonical flow](workflows/README.md) in order.
Anchor membership is read from `docs/coverage/coverage-policy.md`, not decided by
the launcher or inferred during onboarding.

`--repo` takes a slug (`corva-dc-fe-<slug>` is inferred for DC apps), `owner/name`,
a GitHub URL, or a local path. `--dry-run` previews clone/`.env` actions without
performing them; an existing `.env` is never overwritten.

## Library map

Where everything lives (the journey above is the *order*; this is the *index*).

| Path | Purpose |
| --- | --- |
| [workflows/README.md](workflows/README.md) | Canonical one-app onboarding, maintenance, independent review, repair, and handoff. |
| [workflows/app-coverage-prompt.md](workflows/app-coverage-prompt.md) | Fillable one-app orchestration prompt for onboarding or maintenance. |
| [workflows/existing-app-upgrade-prompt.md](workflows/existing-app-upgrade-prompt.md) | Ready-to-run prompt for re-qualifying and migrating an already-covered app. |
| [workflows/discover-queries/](workflows/discover-queries/) | Discover real user queries → `{app}/ai-tests/queries.json`. |
| [workflows/tools/](workflows/tools/) | Add Ask Corva tools and durable repo-local maintenance instructions to a Dev Center app repo. |
| [workflows/tools/checklist.md](workflows/tools/checklist.md) | Single independent final checklist for source truth, module ownership, evidence, and candidate-bound structure proof. |
| [workflows/scenarios/](workflows/scenarios/) | Author per-app dialogue scenarios from `queries.json` for every app. |
| [workflows/evals/](workflows/evals/) | Author an anchor-only eval suite from `queries.json`, and drive it to green. |
| [workflows/testing/](workflows/testing/) | Live & interactive agent testing for any app or multi-app dashboard (Recipes A–E + the eval suite). |
| [workflows/platform/](workflows/platform/) | Route built-in platform apps and maintain platform-core/multi-app behavior. |
| [docs/reference/](docs/reference/architecture.md) | Source-of-truth concept docs: architecture, tool authoring, eval harness, eval architecture. |
| [docs/reference/delivery-sync.md](docs/reference/delivery-sync.md) | Mandatory target-app PR → immediate Jira → coverage-artifact synchronization contract. |
| [docs/coverage/cwf-tools.md](docs/coverage/cwf-tools.md) | Every frontend tool corva-web-frontend ships, with effect, replay/confirmation policy, and the availability condition that decides what the agent can pick. |
| [fleet/](fleet/registry.json) | Registry, manifest-v2 current state, interaction observations, generated health report, and migration schemas. |
| [docs/reference/fleet-evolution.md](docs/reference/fleet-evolution.md) | Bounded evolution from read-only inventory to pull-request automation and optional agent-assisted review. |
| [docs/coverage/](docs/coverage/) | Tool coverage inventory + DC-app backlog owned by this repo. |
| [plans/](plans/README.md) | Planning + execution framework (task tiers, waves, changelog) for features and bugs. |
| [plans/scripts/run-program.sh](plans/scripts/run-program.sh) + `yarn pb:auto:dc` | Autonomous epoch-loop driver for an in-flight program record (one `claude -p` per epoch; requires an explicit program record and a clean worktree). Human-invoked, autonomous once running; coordinates via `pb-deliver-dc-corva`. Not used by `/pb-feature` or `/pb-bugfix` agents. |
| [plans/scripts/watch-program.sh](plans/scripts/watch-program.sh) + `yarn pb:watch` | Read-only dashboard over the running driver: lock owner, epoch count, current record hash, per-branch CI. Safe to leave open. |
| [scripts/](scripts/) | Deterministic validation + pre-flight guardrails, plus the `launch/` folder (`onboard.sh` / `test-app.sh` + shared `lib/common.sh`) that locates/clones an app repo, seeds its `.env`, and routes into a workflow. |

Two changelogs exist by design — keep them separate:

- **`CHANGELOG.md`** (release-facing) is generated by `release-please` from
  conventional commits; it tracks `@corva/fe-ai-tools` ship versions and is the
  source consumers pin against.
- **`plans/changelog.md`** (playbook-facing) is append-only, names the touched
  plan/program area per commit, and is what `scripts/verify.sh` enforces through
  `plans/scripts/check-playbook.sh`.

Editing one is not a substitute for the other.

Workflow folders use short, repeated filenames: `README.md` (entry point +
execution contract), `checklist.md` (final quality gates, where kept separate),
`schema.json` / `example.json` (machine-readable contract + example), `examples/`
(worked-example files for that workflow only).

## Contracts and ownership

This repo is the **source of truth** and owns: the workflow playbooks; scripts and
validation gates; the coverage inventory + DC-app backlog; and the concept reference
in [docs/reference/](docs/reference/architecture.md) — [architecture.md](docs/reference/architecture.md)
(data flow, agent roster, glossary), [tool-authoring.md](docs/reference/tool-authoring.md),
[eval-harness.md](docs/reference/eval-harness.md), and
[eval-architecture.md](docs/reference/eval-architecture.md) (the anchor/concentrate model).

CWF (`corva-web-frontend/docs/ai-agent/`) keeps only the code-coupled docs
that must update in the same session as the source: `code-map.md` (file map),
`ownership.md` (decision log), `capabilities.md` (matrix tied to platform eval case
IDs). Re-sync the reference docs here against those three when the FE changes.

Live testing produces dated run reports **with the code under test** — platform
sessions in `corva-web-frontend/ai-tests/runs/`, per-app sessions in
`{app}/ai-tests/runs/` — evidence logs, not reference docs, and not in this playbook.

## Validation

Before considering changes done, run the gates (a non-zero exit is a hard stop):

```bash
yarn verify                      # package + playbook + review-gate + diff gates
```

The individual commands remain documented in [scripts/README.md](scripts/README.md).
To verify a specific commit range, run `CHECK_RANGE=base...head yarn verify`.

Changes under `plans/features|bugs|testing/` also need a same-session
[plans/changelog.md](plans/changelog.md) entry naming each touched area — the
playbook gate enforces it.