tinybeeai 0.0.0-stage → 0.16.1

package/docs/MULTI-REPO.md

@@ -0,0 +1,766 @@
+# Multiple repos, test repos, and GitHub Issues: build design
+
+A dot today watches one GitHub repo. Real teams split their product across several: a web app, an API, a test automation repo, and sometimes a docs repo. This design lets a dot hold a set of repos with a role each, reads every repo once into a short profile, runs suites that live in a separate test repo, and treats GitHub Issues as the tracker. Think of a new QA hire: on day one they skim each repo to learn where checkout lives and which tests cover it, then they keep that mental map current as merges land.
+
+Scope: Linear KAT-85 (multiple repos and the repo scan), KAT-86 (test automation repos), KAT-87 (GitHub Issues as ALM). No code changes with this document; section 5 lists the work. Code references are to `duonghaijoe/localdost` at `aceb957` (2026-10-08). Research was done on 2026-10-08; sources are in section 6, and items marked "to confirm" were not verified on a primary page.
+
+Status, 2026-10-19: tasks T3 and T4 of section 5 are built for Playwright (KAT-86): a PR check and a merge of an app repo run the suite of a Tests repo at a resolved ref, and the report names its specs `owner/name:path`. Where the build differs from the design below, the paragraph says so. Status, 2026-10-08: tasks M1 to M4 of section 5 are built. The `repo_scan` job runs from `POST /api/repos/:owner/:name/scan` (KAT-221) and the CLI. The profile endpoints and the bundled demo profile wait for the rest of the repo scanner (KAT-85 part 2). The API contract as built is in [API-V2.md](API-V2.md#repos).
+
+## Contents
+
+1. Data model: workspace repos and per-dot repo sets
+2. Repo scan and profile
+3. Test repos
+4. GitHub Issues as ALM
+5. Build tasks
+6. Sources
+
+---
+
+## 1. Data model: workspace repos and per-dot repo sets
+
+### 1.1 Current state
+
+- `Watch.repo` is one optional `{ owner, name, defaultBranch, pathFilters? }` (`src/types.ts`).
+- Fourteen modules read `watch.repo` or `w.repo` directly: `webhooks.ts` (matching), `monitor/pollers.ts` (cursor per repo), `integrations/github.ts` (`githubFor`), `runner/index.ts` (clone when no `workdir`), `review/checkout.ts`, `review/index.ts` (graph cache key), `flows/change.ts`, `flows/common.ts`, `flows/qa.ts`, `flows/ticks.ts`, `flows/ticketReview.ts`, `agent/prompts.ts`, `routes/review.ts`, `runner/aivision/cli.ts`.
+- The GitHub provider on the Setup page already has a repo picker (`optionKinds: ['repos']` in `src/connect/providers.ts`, stored as `settings.repos`). It lists repos from the App installations or the token, but nothing reads the selection: the dot form still takes `owner/name` as free text (`client/src/features/settings/watchForm.ts`).
+
+### 1.2 New model
+
+Two levels. The workspace holds every repo that localdost may read, connected once on the Setup page. A dot picks a subset of them and gives each a role.
+
+```ts
+// src/types.ts (add only)
+
+export type RepoRole = 'app' | 'test' | 'docs';
+
+/** A workspace repo: connected once, scanned once, shared by every dot that picks it. */
+export interface WorkspaceRepo {
+  id: string;                 // "owner/name", lower case
+  owner: string;
+  name: string;
+  defaultBranch: string;      // from GET /repos/{o}/{r} at add time, refreshed on scan
+  private: boolean;
+  addedAt: string;
+  /** Scan state of the latest profile. */
+  scan: {
+    state: 'queued' | 'scanning' | 'ready' | 'stale' | 'error';
+    sha?: string;             // profile built at this commit of the default branch
+    at?: string;
+    error?: string;
+    mode?: 'full' | 'incremental';
+  };
+  /** How events reach localdost for this repo, detected from deliveries and poll cursors. */
+  intake?: 'webhook' | 'poll' | 'none';
+  lastEventAt?: string;
+}
+
+/** One repo in a dot's set. */
+export interface WatchRepo {
+  repo: string;               // WorkspaceRepo.id
+  role: RepoRole;
+  /** Unset: the workspace repo's default branch. */
+  defaultBranch?: string;
+  pathFilters?: string[];
+  /** role 'app' only: which PRs of the repo the dot takes (KAT-354, docs/SETUP.md section PR scope). Unset: every PR. */
+  prScope?: PrScope;
+  /** role 'app' only: false runs no tests for the repo; it is still reviewed (KAT-361, docs/SANDBOX.md section Run tests per repo). Only false is stored. */
+  runTests?: boolean;
+  /** role 'app' only: the GitHub environment this repo's merge deploys to, and the seconds a merge waits for it (KAT-395, docs/SETUP.md section Deploy wait of one repo). Unset: the dot's. 0 seconds: this repo does not wait. */
+  deployEnvironment?: string;
+  waitForDeploySec?: number;
+  /** role 'test' only (section 3.2). */
+  test?: TestRepoConfig;
+  /** role 'test' only: app repos this suite exercises. Unset: every app repo of the dot. */
+  targets?: string[];
+}
+
+export interface Watch {
+  // existing fields unchanged, including repo?
+  repos?: WatchRepo[];
+  /** pr_check waits this long for a deployment_status preview before it falls back to baseUrl. Default 0. */
+  waitForPreviewSec?: number;
+}
+```
+
+Rules:
+
+- A dot may hold any number of repos. At least one `app` repo is required when the dot holds a `test` repo, because test repos run against an app.
+- `Watch.repo` stays (the types contract is add-only). On every save, the server writes `repo` from the first `app` repo in `repos`, so readers that have not moved yet keep working. Once all readers use the helper below, `repo` is a derived field only.
+- One helper replaces direct reads: `watchRepos(w): ResolvedRepo[]` in a new `src/repos.ts`. It returns `repos` when set, else a single `app` entry built from `repo`. `repoForEvent(w, ev)` returns the entry whose `repo` matches `ev.repo`, or null.
+- `githubFor(watch, event)` keeps its signature and picks the repo from `event.repo` through `repoForEvent`. A new `githubForRepo(id)` serves repo-level work that has no dot (scans, profile reads).
+
+### 1.3 Storage and migration
+
+New tables in `src/db.ts` (same `migrate()` mechanism, so creation is idempotent):
+
+| Table | Columns | Notes |
+|---|---|---|
+| `repos` | `owner`, `name`, `defaultBranch`, `private`, `scan` (json), `intake`, `lastEventAt` | `id` is `owner/name` lower case |
+| `repo_profiles` | `repoId`, `sha`, `profile` (json), `overrides` (json), `version`, `mode`, `scanMs`, `tokens` | Newest row per repo is the live profile; keep the last 5 for diffing |
+| `links` | `kind`, `from`, `to`, `source`, `watchId`, `meta` (json) | Section 4.4 |
+| `issue_state` | `repoId`, `number`, `bodyHash`, `updatedAt`, `testStatus` (json) | Sections 4.2 and 4.6 |
+
+Migration, run once at boot and safe to repeat (`migrateWatchRepos()` in `src/repos.ts`):
+
+1. For each watch with `repo` and no `repos`: insert a `repos` row when missing, then write `repos: [{ repo: id, role: 'app', defaultBranch, pathFilters }]`.
+2. For each id in the GitHub provider's `settings.repos`: insert a `repos` row when missing. After this step `settings.repos` mirrors the `repos` table and is written on every change, so the existing Setup picker keeps its state.
+3. Queue a `repo_scan` job for each repo with no profile. Demo mode skips real scans and loads a bundled profile for `demo/sample-app`.
+
+Rollback: an older build ignores `repos` and the new tables and still reads `repo`, which step 1 keeps filled.
+
+### 1.4 Event matching
+
+`watchMatches` in `src/webhooks.ts` changes for `source: 'github'`:
+
+- Match when `ev.repo` equals any entry of `watchRepos(w)`. A push also needs that entry's default branch.
+- The role picks the job. `app` repos keep today's table (`pr_check`, `post_merge`, `ci_failure`). `test` and `docs` repos follow section 3.6. Every default-branch push on any role also queues `repo_scan` for the workspace repo, once per repo and once only, whatever the number of dots (dedupe key `scan:<repo>:<sha>`).
+- `dispatchTrigger` already dedupes per dot (`<eventKey>:<watchId>:<jobKind>`), so two dots that share a repo each get their job.
+- A PR event also has to be in the repo entry's `prScope`. `dispatchTrigger` records a PR the scope keeps out as an event row with `skipped: 'out of scope: <rule>'` (the same way it records a stage that is off) and queues nothing for that dot. A push to the default branch is judged by the merged PR of its head commit (`GET /repos/{o}/{r}/commits/{sha}/pulls`), so the merge of a PR the scope keeps out starts no `post_merge` through the push either.
+
+The poller (`pollGithubOnce`) loops over the union of repos of all unpaused dots that poll, keyed by repo, so a repo shared by three dots is polled once. Cursor keys are already per repo (`github:<owner>/<name>:<branch>`).
+
+### 1.5 API
+
+| Method and path | Purpose |
+|---|---|
+| `GET /api/repos` | Workspace repos with scan state, intake, and the dots that use each |
+| `GET /api/repos/options?q=` | Repos visible to the GitHub connection (wraps the provider's `options('repos')`), marked when already added |
+| `POST /api/repos` body `{ repos: ["owner/name", ...] }` | Adds repos, reads each default branch, queues scans. 207 with per-repo errors |
+| `DELETE /api/repos/:owner/:name` | Removes a repo. 409 with the dot names when a dot still uses it |
+| `POST /api/repos/:owner/:name/scan` body `{ full?: boolean }` | Rescan now |
+| `GET /api/repos/:owner/:name/profile` | Profile with overrides applied, plus `raw` and `overrides` separately |
+| `PATCH /api/repos/:owner/:name/profile` | Saves overrides (section 2.8) |
+| `POST /api/dots`, `PATCH /api/dots/:id` | Accept `repos: WatchRepo[]`. A repo the connection can see but the workspace lacks is added on save. 400 when a test repo has no app repo |
+| `GET /api/dots/:id` | `dotView` adds `repos[]` with role, scan state, last event, and intake per repo |
+
+Live events: add `{ type: 'repo'; repo: WorkspaceRepo }` to `LiveEventV2` so scan progress updates the pages without a reload.
+
+### 1.6 UI
+
+Setup page, GitHub row: the existing picker becomes the workspace repo list. Each row shows the repo, a status indicator for the scan, the profile age, and how events arrive.
+
+```text
+GitHub   Connected as localdost-app[bot]                         [Test] [Disconnect]
+  Repositories                                                   [Add repos]
+  acme/shop-web       (o) Ready, scanned 2 h ago at 4f1c2a9      webhook   [Open]
+  acme/shop-api       (o) Scanning, 1,240 of 3,100 files         webhook   [Open]
+  acme/shop-e2e       (o) Ready, scanned 1 d ago at 9be0d11      poll      [Open]
+  acme/handbook       (!) Error: clone failed (403)              none      [Retry]
+```
+
+Dot dialog: the free-text Repository field becomes a multi-select picker with one row per picked repo. The role is a three-option segmented control. Branch and path filters sit behind a row-level "More" toggle that has a visible label. A test repo row adds its framework and ref fields (section 3.2).
+
+```text
+Repositories                                              [+ Add repository]
+  acme/shop-web    Role [App | Tests | Docs]   Branch main       More v
+  acme/shop-api    Role [App | Tests | Docs]   Branch main       More v
+  acme/shop-e2e    Role [App | Tests | Docs]   Branch main       More ^
+                   Framework  Playwright (detected)
+                   Test ref   [Default branch | Same branch as app PR | Fixed: ____]
+                   Folder     e2e/          Base URL variable  BASE_URL
+                   Tests      shop-web, shop-api
+```
+
+Dot detail page: a Repos section with one row per repo: role, scan state, last event, and the last run for that repo. Errors (a 403 on clone, no events for 7 days while the repo had pushes) show on the row with the action that fixes them.
+
+Mobile: rows stack to two lines at 390 px; the role control stays on one line. A visual check of both themes at 390x844 and 1280x800 is part of the UI tasks in section 5.
+
+---
+
+## 2. Repo scan and profile
+
+### 2.1 Method chosen
+
+**Choice: an in-process TypeScript scanner in three layers. The base layer reuses the regex scanners localdost already has. On top sits an Aider-style symbol map: tree-sitter tags parsed with `web-tree-sitter` (WASM), a reference graph, and PageRank. GitHub's languages API adds cheap facts before the clone. One small model call then names the feature areas and writes the glossary.** Repomix stays an optional chat export. OpenQodex `packages/graph` stays the planned call-graph upgrade (PR-REVIEW-QA.md task 37).
+
+| Candidate | Licence | Fit | Decision |
+|---|---|---|---|
+| Existing localdost scanners (`routes.ts`, `specs.ts`, `imports.ts`, `classify.ts`, CODEOWNERS and owner map parsers in `impact.ts`) | MIT (ours) | Offline, cached by sha. They already produce routes, specs, test ids, and import edges | Base layer |
+| Aider repo map [A1, A2] | Apache-2.0 | Tree-sitter tags for definitions and references, a graph with files as nodes and edges weighted by reference count, personalized PageRank, output fitted to a token budget (default 1,024 tokens). Offline, no service. Caches tags by file mtime in SQLite | Re-implement the method in TypeScript. Copy no code |
+| `web-tree-sitter` and grammar WASM files [A10] | MIT (tree-sitter core and the TypeScript, JavaScript, Python, Java, Go grammars) | Runs in Node with no native build. SPEC.md rules out native dependencies | Parser for the symbol map. npm licence of `web-tree-sitter` to confirm (repo is MIT) |
+| GitHub languages API [A6] | n/a | Bytes per language, one request, no clone | Pre-clone stack facts |
+| GitHub SBOM API [A7] | n/a | SPDX dependency list. The sync endpoint closes on 2026-11-13; the replacement is an async generate-then-fetch pair | Skip. Manifests in the clone give the same facts offline |
+| Repomix [A3, A4] | MIT | Packs a repo into one XML, Markdown, or JSON file with token counts. `--compress` keeps signatures through tree-sitter (marked experimental). Has an MCP mode. No incremental cache | Optional chat tool "pack this area", capped. Too large to serve as the profile |
+| code2prompt [A5] | MIT | Rust CLI that renders a repo into a prompt from templates | Overlaps with Repomix; no added value |
+| OpenQodex `packages/graph` [A8] | Apache-2.0 | TypeScript package next to the review code we already adapt | Later: callers two hops away, behind a flag |
+| Sourcegraph SCIP [A9] | Apache-2.0 (scip, scip-typescript); scip-python to confirm | Compiler-grade references. Each language needs its own indexer, and scip-typescript needs a working `tsconfig.json`. Full re-index each time | Too heavy for a scan on connect |
+| Universal Ctags [A11] | GPL-2.0 | Tags file per language. Usable only as a separate binary, which adds a system dependency. Aider moved away from it for the same install burden [A2] | Skip |
+| deepwiki-open [A12], DeepWiki MCP [A13] | MIT; hosted service | Wiki and diagrams from a FastAPI server with embeddings and many model calls. The hosted MCP serves public repos only | Too costly per repo and per merge; private repos need an account |
+| Code-graph MCP servers: codebase-memory-mcp [A14] (MIT, single binary, SQLite, incremental), code-graph-rag [A15] (MIT, needs Memgraph), CodeGraphContext [A16] (MIT, embedded graph DB), Serena [A17] (GPL-3.0 except its LSP layer), GitNexus [A18] (PolyForm Noncommercial) | Mixed | Built for an agent that edits code | Out of scope for the scan. A user can attach codebase-memory-mcp as an MCP connection for chat. Serena and GitNexus licences do not fit an MIT product |
+| AGENTS.md generators [A19] | Mixed | Every one found is model-driven over the whole repo | Too costly; the profile summary covers the need |
+
+Reasons, against the criteria in KAT-85:
+
+- Licence: the chosen path is MIT end to end. The Aider method is an algorithm, so a re-implementation carries no licence duty. Aider's own `queries/*.scm` files have no licence file in that folder and an unclear origin [A1], so localdost takes `tags.scm` files from the grammar repos, which are MIT, with a header and a `NOTICE` line (task R4).
+- No services: the scan is one Node job. State lives in SQLite and the data folder.
+- Offline: after the clone, the scan reads only the local checkout. The languages API call is optional.
+- Incremental: tags and import edges are cached per git blob sha. Aider keys its cache by mtime, which a fresh worktree resets; a blob sha survives that. A merge re-parses only the blobs it changed (section 2.5).
+- Compact output: hard caps per field (section 2.3) keep the profile JSON under 64 KB and the prompt block under 4 KB.
+
+### 2.2 Scan pipeline
+
+New `src/profile/`, job kind `repo_scan`, one job per repo and sha:
+
+1. **Mirror.** Keep one partial clone per repo at `data/mirrors/<owner>__<name>.git` (`git clone --filter=blob:none --bare`), refreshed with `git fetch`. Check out the default-branch head into `data/checkouts/scan-<repo>-<sha>` with `git worktree add --detach`. The review checkout and the test runner reuse the same mirror (section 3.3), so a repo is cloned once per workspace.
+2. **Inventory.** `checkoutView(root)` lists files (cap 8,000, today's `MAX_FILES`). Classify each file with `classFor`. Read manifests: `package.json` (with workspaces), `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `pyproject.toml`, `requirements*.txt`, `pom.xml`, `build.gradle*`, `go.mod`, `Gemfile`, `composer.json`, `Dockerfile*`, `docker-compose*.yml`, and Katalon `*.prj`.
+3. **Stack.** Languages from the GitHub languages API, or from file extensions when offline. Frameworks from manifest dependencies by a fixed table (Next.js, Remix, SvelteKit, Vite React, Angular, Vue, Express, Fastify, NestJS, Django, Flask, FastAPI, Rails, Spring Boot, and others). Each framework carries its evidence line.
+4. **Apps.** One app per deployable unit: each workspace package with a `start`, `dev`, or `build` script; each folder with a framework config (`next.config.*`, `vite.config.*`, `angular.json`, `manage.py`); each Dockerfile. Kind is `web`, `api`, `mobile`, `worker`, `cli`, or `library`.
+5. **Routes.** `detectRoutes` over route files and source files, with the framework table in PR-REVIEW-QA.md section 2.3. Each route is attached to its app by path prefix.
+6. **Tests.** Framework detection by config file and dependency (section 3.4 table). `specInventory` for JS, TS, and Python specs. New parsers for Java and Kotlin (JUnit annotations, `@Tag`, `@DisplayName`), Groovy scripts plus Katalon `Object Repository/*.rs` XML, and Cypress `cy.get('[data-cy=...]')`.
+7. **CI.** Parse `.github/workflows/*.yml` with the existing YAML parser: name, `on` triggers, job names, and whether a job runs tests (a `run` line that calls a known test command), deploys a preview, uploads coverage artifacts, or checks out another repo (`actions/checkout` with `repository:`, a strong hint of an app and test repo pair [B10]).
+8. **Owners.** `parseCodeowners` from `.github/CODEOWNERS`, `CODEOWNERS`, and `docs/CODEOWNERS`. Team handles only; no commit-author mining, so no personal data lands in the profile.
+9. **Symbol map.** Aider method: `tags.scm` queries yield definitions and references per file. Build a graph with an edge from a file that references a name to each file that defines it, weighted by the square root of the reference count. Personalize PageRank toward route files, entry points, and files named in the owner map. Keep the top 60 files with up to 8 symbols each.
+10. **Areas.** Draft areas from, in order: `.localdost/review.yml` owner map, route groups (first URL segment, `areaOfRoute`), monorepo packages, and path heuristics (`pathArea`). Merge drafts that share most of their files. Then one model call (section 2.6) names each area in user words, adds flows, and writes the summary and glossary.
+11. **Store.** Write a `repo_profiles` row, update `repos.scan`, publish a `repo` live event, and remove the worktree.
+
+### 2.3 Profile schema
+
+```ts
+// src/types.ts (add only)
+
+export interface RepoProfile {
+  version: 1;
+  repo: string;                       // owner/name
+  sha: string;
+  scannedAt: string;
+  mode: 'full' | 'incremental';
+  /** Three sentences at most: what the repo is and who uses it. */
+  summary: string;
+  stack: {
+    languages: { name: string; share: number }[];        // top 8
+    frameworks: { name: string; version?: string; evidence: string }[];
+    packageManagers: string[];
+    monorepo?: { tool: string; packages: string[] };      // top 40 packages
+  };
+  apps: {
+    id: string;                        // app1, app2, ...
+    name: string;
+    path: string;                      // folder
+    kind: 'web' | 'api' | 'mobile' | 'worker' | 'cli' | 'library';
+    framework?: string;
+    routeCount: number;
+    /** Env var or config key that sets its URL in tests, when found. */
+    baseUrlHint?: string;
+  }[];
+  routes: { app: string; route: string; method?: string; file: string; line: number; area?: string }[]; // cap 400
+  areas: ProfileArea[];                // cap 40
+  tests: {
+    frameworks: TestFrameworkInfo[];
+    specs: ProfileSpec[];              // cap 2,000 (MAX_SPECS)
+    smokeTag?: string;
+    tags: { tag: string; count: number }[];               // @smoke, @checkout, ...
+  };
+  ci: {
+    workflows: {
+      file: string;
+      name: string;
+      on: string[];
+      jobs: string[];
+      runsTests: boolean;
+      previewDeploy: boolean;
+      coverageArtifacts: string[];
+      checksOut: string[];             // other repos named in actions/checkout
+    }[];
+  };
+  owners: { pattern: string; owners: string[] }[];        // CODEOWNERS, cap 200
+  glossary: { term: string; meaning: string; paths?: string[] }[];  // cap 40
+  map: { file: string; rank: number; symbols: string[] }[];          // cap 60
+  /** Other repos or app URLs this repo names: test configs, workflow checkouts, README links. */
+  mentions: { repo?: string; url?: string; file: string; why: string }[];
+  stats: { files: number; truncated: boolean; parsedFiles: number; scanMs: number; modelTokens: number };
+}
+
+export interface ProfileArea {
+  id: string;                          // stable slug, e.g. "checkout"
+  name: string;                        // "Checkout and payment"
+  paths: string[];                     // globs
+  routes: string[];
+  flows: string[];                     // user words: "guest checkout with a coupon"
+  specs: string[];                     // spec paths in this repo
+  owners: string[];
+  keyFiles: string[];                  // top ranked files from the map
+  source: 'owner_map' | 'routes' | 'packages' | 'paths' | 'model' | 'user';
+  confidence: number;
+}
+
+export interface TestFrameworkInfo {
+  framework: 'playwright' | 'cypress' | 'webdriverio' | 'pytest' | 'junit' | 'katalon' | 'jest' | 'vitest' | 'other';
+  config?: string;                     // playwright.config.ts, cypress.config.ts, wdio.conf.ts, ...
+  dir: string;                         // testDir, specPattern root, Test Cases/
+  count: number;
+  kind: 'e2e' | 'unit' | 'api' | 'mixed';
+  baseUrl?: { config?: string; env?: string[] };
+}
+
+export interface ProfileSpec {
+  path: string;
+  framework: TestFrameworkInfo['framework'];
+  titles: string[];                    // cap 20 per spec
+  routes: string[];
+  testIds: string[];
+  texts: string[];                     // cap 20 per spec
+  tags: string[];
+  /** Page objects or Katalon test objects the spec uses (one import hop). */
+  uses: string[];
+  /** Issue references in titles, tags, or comments: "#123", "SHOP-12", "KAT-85". */
+  issues: string[];
+}
+```
+
+### 2.4 Storage
+
+- `repo_profiles` row per scan (section 1.3). The live profile is the newest row; reads apply `overrides` on top.
+- Blob cache at `data/repo-cache/<owner>__<name>/blobs.jsonl`: one line per git blob sha with its tags, import specifiers, routes, and spec facts. This cache makes refresh incremental. Each full scan drops entries for blobs that left the head tree.
+- The import graph cache (`data/graph-cache/<repo>/<sha>.json`) keeps its format and key. The scan writes it, so the first PR review after a scan finds it warm.
+
+### 2.5 Incremental refresh on merges
+
+- Trigger: a push to the default branch or a merged PR on the repo, from webhook or poll, queues `repo_scan` with `{ repo, sha, since: <profile sha> }`.
+- Coalesce: one scan per repo runs at a time. A newer sha replaces a queued older one. A repo rescans at most once per 10 minutes (`PROFILE_MIN_INTERVAL_SEC`), and the last push in a burst always gets a scan.
+- Delta: `git diff --name-status <since> <sha>` in the mirror. Only added and modified blobs are parsed; removed files leave the inventory. Stack, apps, and CI re-run only when a manifest, framework config, or workflow file changed. PageRank re-runs on the whole graph, which takes milliseconds.
+- Areas: the deterministic drafts are rebuilt every time. The model call runs again only when the drafts changed: a new top-level route segment, a new package, or a moved area path. Otherwise names, flows, and the glossary carry over by area id.
+- Full rescan: weekly, when `since` is not an ancestor of `sha` (force push), when the profile `version` changes, or on demand.
+
+### 2.6 Cost bounds
+
+| Item | Bound |
+|---|---|
+| Files listed | 8,000 (`MAX_FILES`); over the cap, `stats.truncated` and the UI say so |
+| Files parsed for tags | Source files under 256 KB, at most 5,000 per scan; generated, vendored, and lock files skipped by `classFor` |
+| Wall time | Target 60 s for a full scan of 8,000 files on a laptop, 5 s for a typical merge |
+| GitHub API | Two calls per full scan (repo, languages). Well inside 5,000 requests per hour for a token or App install [A6] |
+| Model calls | One per full scan, and one per incremental scan whose drafts changed. None in demo mode (mock backend) |
+| Model input | 24 KB: draft areas with paths and routes, top map entries, spec titles per area, first 2 KB of the README |
+| Model output | 2 KB JSON: area names, flows, summary, glossary. Checked by a schema and the prose rules in `check.ts` |
+| Model choice | The review backend in use (`claude-cli`, `codex-cli`, or `anthropic`), small model tier |
+| Prompt block for other flows | 4 KB per repo, 8 KB for all repos of one dot |
+
+### 2.7 How profiles feed other flows
+
+- **Impact mapping.** `buildImpactDrafts` gets the profiles of the dot's app repos. A changed file inside a profile area's paths maps to that area with `via: 'profile'` at confidence 0.85, or 0.95 when a user confirmed the area (`source: 'user'`). The owner map in the repo stays at 0.95. Areas keep their profile id, so one area has one name in every review. `ImpactArea['via']` gains `'profile'`.
+- **What to test.** The reviewer input gets a `<repo_profile>` block: summary, the touched areas with their flows and specs, glossary terms that appear in the diff, and the test frameworks. The spec inventory for `existingTest` becomes the union of the app repo's own specs and the specs of every linked test repo (section 3.1).
+- **Chat.** The dot's system prompt carries one summary line per repo. New read-only chat tools: `get_repo_profile(repo, area?)`, `find_tests(query)` across all repos of the dot, and `pack_area(repo, area)`, which runs Repomix with `--compress` on the area paths, capped at 30 KB.
+- **Ticket review.** Today the flow takes three title keywords and calls GitHub code search (`flows/ticketReview.ts`). New order: match the ticket text against area names, flows, glossary terms, route paths, and spec titles in every profile of the dot; take the top three areas; send their key files, routes, and specs as `codeHits`; call code search only when no area scores. This finds "the coupon field" in an area named "Checkout and payment" even when no file name contains the word coupon.
+- **Spec selection.** `pickSpecs` uses profile areas in place of `areaOf`, which today reads only `src/<area>/`.
+
+### 2.8 Viewing and correcting a profile
+
+Repo page `#/repos/<owner>/<name>`, reached from Setup and from the dot detail page. Sections: Summary, Stack, Apps and routes, Feature areas, Tests, CI, Owners, Glossary. Feature areas use a table with a detail drawer:
+
+```text
+Feature areas                                              [Rescan] [Save as review.yml]
+  Area                    Paths                  Routes   Specs   Owners      Source
+  Checkout and payment    src/checkout/**, ...   4        6       @web-pay    Model
+  Account and sign-in     src/auth/**            3        2       @identity   Owner map
+  Search                  src/search/**          1        0       -           Routes
+  2 files in no area: src/lib/money.ts, src/lib/date.ts                    [Assign]
+```
+
+A user can rename an area, edit its path globs, merge two areas, split one by path, delete one, assign unmapped files, edit flows, add or edit glossary terms, and mark a detected framework as wrong.
+
+- Edits save as `overrides` on the profile, keyed by area id and field. Rescans keep them. When a rescan no longer finds an area that has overrides, the area stays with a "no longer detected" mark until the user deletes it.
+- **Save as review.yml** drafts `.localdost/review.yml` from the corrected areas and sends it as an `open_pr` action (default rule `act_when_asked`; the button press is the ask). The owner map then lives in the repo, where code review covers it. Until `open_pr` execution exists (PR-REVIEW-QA.md task 33), the draft lands in the outbox with a copy button.
+- Chat can propose a correction ("checkout also covers src/lib/money.ts"). The proposal shows as a card with Apply and Dismiss, and nothing changes until the user applies it.
+
+---
+
+## 3. Test repos
+
+### 3.1 Cross-repo spec inventory
+
+A test repo has its own profile with `tests.specs` filled. When an app repo changes, the review links the change to specs in every test repo of the dot that targets that app.
+
+| Link | How | Confidence |
+|---|---|---|
+| Route | A changed route (from `routes.ts`) equals a spec route from `goto`, `cy.visit`, `browser.url`, `WebUI.navigateToUrl`, `driver.get`, after joining paths and dropping the origin | 0.8 |
+| Test id | A `data-testid`, `data-cy`, `data-test`, or `data-qa` value defined in a changed file (`definesValue`) appears in a spec, a page object it uses, or a Katalon test object | 0.8 |
+| Issue key | The PR closes or names an issue that a spec names in its title or tags (`@issue-123`, `#123`, `SHOP-12`) | 0.85 |
+| API path | A changed API route equals a request path in an API spec (`request.get`, `cy.request`, `requests.get`, RestAssured `given().get`) | 0.75 |
+| Visible text | Changed UI text appears in a spec text locator or a test object | 0.6 |
+| Area name | A spec path, describe title, or tag contains the area id or a glossary term of the touched area | 0.55 |
+
+Page objects matter here. Most test repos keep selectors and URLs in page objects or Katalon test objects, and the specs only call them. The scan follows one import hop from each spec: `imports.ts` for JS, TS, and Python, `import` lines for Java, and `findTestObject('...')` for Katalon. The page object's routes, test ids, and texts count for every spec that uses it.
+
+In types: `QaTestToRun.existingTest` and `QaTestAtRisk.path` may carry a repo prefix, `owner/name:path`. A path with no prefix keeps today's meaning, the app repo. `SpecLink` gains `repo`.
+
+### 3.2 Test repo config
+
+```ts
+export interface TestRepoConfig {
+  /** Detected on scan; the user can change it. */
+  framework: 'playwright' | 'cypress' | 'webdriverio' | 'pytest' | 'junit' | 'katalon';
+  /** Subfolder with the test project. Unset: repo root. */
+  dir?: string;
+  /** Which ref of the test repo runs against an app change. Default 'default'. */
+  ref?: 'default' | 'match_branch' | { fixed: string };
+  /** Overrides the adapter's command. Runs without a shell, like runner.command. */
+  command?: string;
+  /** Env var names the adapter sets to the app URL. Default per adapter. */
+  baseUrlEnv?: string[];
+  /** Env var names passed into the run, such as test user credentials. Each must start with LOCALDOST_TEST_. */
+  passEnv?: string[];
+  /** Text that marks a smoke spec. Default '@smoke'. */
+  smokeGrep?: string;
+  /** Katalon only. */
+  katalon?: { suite?: string; profile?: string; browser?: string; apiKeyEnv?: string };
+  /** Jobs that run this repo's specs. Default ['pr_check', 'post_merge']. */
+  on?: ('pr_check' | 'post_merge')[];
+}
+```
+
+Ref resolution for one app PR, first match wins:
+
+1. A line in the PR body, `localdost-tests-ref: <branch>`, pins the test repo to that branch when it exists. This covers the common case where the app change and its test change land in two PRs. Built as a branch name only: the `#<n>` and `owner/name@<branch>` forms of the first design are not built, and a branch the test repo lacks is said in a step and skipped.
+2. `match_branch`: when the test repo has a branch with the app PR's head branch name, use it, else the default branch.
+3. `{ fixed }`: that branch or tag.
+4. `default`: the test repo's default branch, as GitHub reports it.
+
+A merge uses rules 3 and 4 only. A fork PR uses rules 3 and 4 only: its body and branch name pick nothing. The run records the resolved ref and sha (`TestReport.testRepos`), and the PR comment names them under Details, so anyone can rerun the same tests. Built in `src/runner/test-repo.ts` (`resolveTestRef`). `TestRepoConfig` gained `label`, `setup` and `areas`, see [SANDBOX.md](SANDBOX.md#tests-repo).
+
+### 3.3 Runner checkout
+
+```ts
+export interface RunSpec {
+  // existing fields unchanged
+  /** Set: the run checks out this test repo at sha and runs its specs against baseUrl. */
+  testRepo?: { repo: string; ref: string; sha: string; config: TestRepoConfig };
+}
+```
+
+`run()` in `src/runner/index.ts`:
+
+- Workdir: a worktree of the test repo at `sha` in `<data>/worktrees/<runId>-a<attempt>-tests`, removed when the run ends and swept at boot with the app worktrees. Built on a cache folder `<data>/test-repos/<owner>__<name>`, a git folder with no files of its own that holds fetched commits, and not on the mirror of section 2.2 (R1 is not built). `runner.workdir` keeps working for single-repo dots and for the app repo.
+- Base URL: the app PR preview (`previewFor(appRepo, headSha)`), else the dot's `baseUrl`. Only the URL crosses from the app side; a test-repo run never checks out the app repo.
+- Install: docker mode runs the adapter's install step (`npm ci`, `pip install -r`, `mvn -q -DskipTests dependency:go-offline`) in the container. A named volume per repo and lockfile hash caches `node_modules`, `~/.m2`, and pip wheels, so a second run on the same lockfile skips the download.
+- Secrets: the existing credential filter applies. `passEnv` names must start with `LOCALDOST_TEST_`, and the run sees them with that prefix replaced by `TEST_` (`LOCALDOST_TEST_USER` becomes `TEST_USER`). A dot config therefore cannot forward `GITHUB_TOKEN` or a model key. The same rule and the same `TEST_` rename apply to `runner.passEnv` of a dot, which the runner reads today (docs/SANDBOX.md section Test login); `test.passEnv` of a test repo is built the same way, and falls back to the dot's `runner.passEnv` when the test repo lists none. The Katalon API key is the one exception: `katalon.apiKeyEnv` names it, and it goes only to `katalonc` as `-apiKey`.
+- Fork safety: a fork PR of an app repo never runs test repo code with the host environment. Built as: in local mode the batch is skipped, in Docker mode it runs only when no test login (`test.passEnv`, else the dot's `runner.passEnv`) would go with it, otherwise it is skipped with a sentence, and the body and branch of a fork PR never pick the ref. This replaces the first design, which followed `runner.trustForks`.
+- Batches: when a dot has app specs and a test repo, the runs go in sequence by default (`LOCALDOST_RUN_CONCURRENCY` raises it), and `mergeReports` combines them. Retries (`runSuite`) stay per batch.
+
+### 3.4 Framework adapters
+
+New `src/runner/adapters/`, one module per framework behind one interface:
+
+```ts
+export interface FrameworkAdapter {
+  id: TestRepoConfig['framework'];
+  /** Finds the framework in a checkout. */
+  detect(view: RepoView): { config?: string; dir: string; version?: string } | null;
+  /** Lists runnable tests without running them, when the framework can. */
+  list?(ctx: AdapterCtx): Promise<{ file: string; title: string; tags: string[] }[]>;
+  /** Builds the command for a selection. */
+  command(sel: Selection, ctx: AdapterCtx): { cmd: string; args: string[]; env: Record<string, string> };
+  install(ctx: AdapterCtx): { cmd: string; args: string[] } | null;
+  image(ctx: AdapterCtx): string;
+  /** Parses the report files into the shared result shape. */
+  parse(outDir: string, exec: ExecResult): ParsedReport;
+}
+
+export interface Selection {
+  files: string[];
+  titles?: string[];      // becomes a grep, -k, or -Dtest filter
+  tags?: string[];
+  all?: boolean;
+}
+```
+
+| Order | Framework | Select | Base URL | Report | Image |
+|---|---|---|---|---|---|
+| 1 | Playwright [B1, B2, B3] (exists for the app repo; moved behind the interface) | spec paths, `--grep`; `--list --reporter=json` lists tests | `BASE_URL`; the config must read it into `use.baseURL` | `--reporter=json` (existing parser) | `mcr.microsoft.com/playwright:v<version>-noble` |
+| 2 | Cypress [B4] | `--spec a,b`; default `specPattern` is `cypress/e2e/**/*.cy.{js,jsx,ts,tsx}` | `CYPRESS_BASE_URL` sets `baseUrl` | JUnit reporter to `<out>/r-[hash].xml` | `cypress/included:<version>` |
+| 3 | WebdriverIO [B5, B6] | `--spec` (flag to confirm) | `baseUrl` in a wrapper config | `@wdio/junit-reporter` set in the wrapper config, as the Playwright wrapper does today | Node image with Chrome |
+| 4 | pytest [B7, B8] | `path::Class::test`, `-k`, `-m`; `--collect-only -q` lists tests | `--base-url` when `pytest-base-url` is installed, else `BASE_URL` | `--junitxml=<out>/junit.xml` | `mcr.microsoft.com/playwright/python:v<version>-noble` |
+| 5 | JUnit 5 with Maven or Gradle [B9] | `-Dtest=Class#method`, tags through `<groups>`; Gradle `--tests` | `-Dbase.url=` plus `BASE_URL` | Surefire XML in `target/surefire-reports/`, Gradle XML in `build/test-results/` | `maven:3-eclipse-temurin-21`, `gradle:jdk21` |
+| 6 | Katalon Studio [B11] | `-testSuitePath` or `-testSuiteCollectionPath` (relative, no extension) | `-executionProfile` with a `baseUrl` variable | JUnit report in `-reportFolder` | Katalon Runtime Engine image; needs a Runtime Engine licence and `-apiKey` |
+
+One shared parser, `src/runner/junit-xml.ts`, turns JUnit XML into `ParsedReport` for adapters 2 to 6: a `testcase` with `failure` or `error` is failed, `skipped` is skipped, Surefire `flakyFailure` and `flakyError` count as flaky, and `classname` plus `name` give the title. It uses `fast-xml-parser` (MIT, no native code).
+
+Katalon specifics: `katalonc` runs in console mode with `-projectPath` (absolute, including the `.prj` file) and needs a Runtime Engine licence [B11]. The dot shows Katalon as runnable only when `katalon.apiKeyEnv` names a set variable, and the Setup page says why. Selection is coarse in the first version: whole suites from `katalon.suite`, plus smoke. A generated temporary suite that lists the linked test cases comes later (task T9). The folder layout this design assumes (`Test Cases/`, `Scripts/`, `Object Repository/*.rs`, `Test Suites/`, `Profiles/`) is to confirm against a sample project, since the docs page for it did not load.
+
+Live view: Playwright keeps its step reporter and browser frames. Other adapters stream stdout to the run log only.
+
+### 3.5 Results on the app PR
+
+- The test-repo report merges into the same `TestReport` through `mergeReports`. Each case's `file` gets the repo prefix, `acme/shop-e2e:tests/checkout.spec.ts`.
+- `whatToTest[].result` fills from those cases exactly as for app specs, so the checklist, verdict, check run, and sticky comment need no new path.
+- The sticky comment and the check summary add one line in the counts: "Ran 14 Shop tests from shop-e2e: 13 passed, 1 failed." The commit, the ref, why that ref, the tests chosen and the URL sit under Details ("acme/shop-e2e at main (9be0d11), because the default branch; tests: the whole suite; against https://pr-58.preview.acme.dev"). File links point to the test repo blob at that sha.
+- The check run stays on the app PR head sha. Annotations stay on app files, because GitHub annotates only files of the repo that owns the check. A failing test in the test repo is listed in the check summary with its link.
+- Flaky memory keys get the repo prefix, so one file name in two repos never mixes.
+
+### 3.6 Events for both repos
+
+| Repo role | Event | Job | What happens |
+|---|---|---|---|
+| app | PR opened, synchronize | `pr_check` | Review; app specs plus linked test-repo specs against the preview or base URL |
+| app | `deployment_status` success [B10] | none | Records the preview. With `waitForPreviewSec` set, a waiting `pr_check` starts now. A `post_merge` that waits for the deploy of its commit looks again now ([SETUP.md](SETUP.md#waiting-for-the-deploy)) |
+| app | merge or push to default | `post_merge` and `repo_scan` | Same as today plus test-repo specs against `baseUrl`, and a profile refresh |
+| test | PR opened, synchronize | `test_pr_check` (new) | Review the test diff with the existing test signals (assertion removed, test disabled, test config changed); run the changed specs against the dot's `baseUrl`; comment on the test PR |
+| test | merge or push to default | `repo_scan` | Refresh the spec inventory. A smoke run happens only when the dot turns it on |
+| test | `workflow_run` failure | `ci_failure` | Triage as today; the prompt adds the app repo merges since the last green run, since a nightly e2e failure usually points at an app change |
+| docs | merge or push to default | `repo_scan` | Profile only: glossary and flows from docs feed the areas |
+
+Polling covers PRs and pushes for every repo, as today. Webhooks need the GitHub App installed on every repo in the set, or a repo webhook on each. The Setup row shows the intake per repo, so a missing webhook on the test repo is visible.
+
+`test_pr_check` and `pr_check` share `flows/change.ts`; the role selects the spec source and the comment target. localdost runs the cross-repo suite itself, so the team needs no `repository_dispatch` or second-repo `actions/checkout` wiring [B10].
+
+---
+
+## 4. GitHub Issues as ALM
+
+### 4.1 Tracker kind github
+
+```ts
+// src/types.ts (the unions widen)
+
+export interface Watch {
+  tracker?:
+    | { kind: 'jira'; baseUrl: string; projectKeys: string[] }
+    | { kind: 'linear'; teamKeys: string[] }
+    | {
+        kind: 'github';
+        /** Repos whose issues this dot reviews. Default: the dot's app repos. */
+        repos?: string[];
+        /** Labels that mark requirements and defects, and labels to skip. */
+        labels?: { requirement?: string[]; defect?: string[]; ignore?: string[] };
+        /** Org issue types that count as requirements and defects. */
+        issueTypes?: { requirement?: string[]; defect?: string[] };
+        /** Only review issues in these milestones. Unset: all. */
+        milestones?: string[];
+      };
+}
+
+// Ticket.tracker and TriggerEvent.ticket.tracker: 'jira' | 'linear' | 'github'
+// Ticket gains: milestone?: string; issueType?: string; state?: 'open' | 'closed'; repo?: string
+```
+
+Widening these unions changes the contract in `src/types.ts`, which says add only. Widening breaks no reader that switches on `kind`, but each `switch` without a default case needs a check; task A1 lists them.
+
+Ticket key for GitHub: `owner/name#123`. `ticket.id` is the issue node id. `projectKey` is `owner/name`, so `watchMatches` compares it with `tracker.repos`.
+
+Issue types are org-level since April 2025, with Task, Bug, and Feature as defaults and up to 25 types [C3, C4]. Repos outside an org, or orgs that do not use types, fall back to labels. Sub-issues (up to 100 per parent [C5]) map to a requirement tree in the traceability view.
+
+### 4.2 Normalizer, poller, and webhooks
+
+`normalizeGithubIssue(eventName, payload)` in a new `src/integrations/github-issues.ts`. Action names come from the webhook reference [C8]:
+
+| Event and action | Trigger | Notes |
+|---|---|---|
+| `issues.opened` | `ticket_created` | Skip when the author is the localdost bot |
+| `issues.edited` with `changes.body` or `changes.title` | `ticket_updated` (new kind, job `ticket_review`) | Dedupe on a hash of the new body, so a repeated edit queues once |
+| `issues.labeled` with a requirement or defect label | `ticket_updated` | Only when the label brings the issue into scope |
+| `issues.typed` | `ticket_updated` | When the new type is in `issueTypes` |
+| `issues.milestoned` | `ticket_updated` | When the milestone is in `milestones` |
+| `issues.closed`, `issues.reopened` | none | Updates `issue_state` and the traceability view |
+| `issue_comment.created` with `/localdost review` on an issue | `ticket_updated` | Only from users with write access (`writePermission`), so outsiders cannot spend model calls |
+| `issue_comment.created` with `/localdost review` on a pull request | a review on demand of the PR (`pr_check`) | Only from users with write access, for each dot that watches the repo as an app repo (KAT-376) |
+| `issue_comment.edited` | existing path | Sticky PR comment ticks, unchanged |
+
+Pull requests also arrive as issue events. The normalizer drops any payload with `issue.pull_request` set.
+
+Dedupe keys: `github-issue:<owner/name>#<n>:created` and `github-issue:<owner/name>#<n>:edited:<bodyHash8>`. Webhook and poll share them.
+
+Poller: `pollGithubIssuesOnce(repo)` calls `GET /repos/{o}/{r}/issues?state=all&sort=updated&direction=asc&since=<cursor>&per_page=100`. It drops pull requests, emits `created` for issues created after the cursor, and emits `edited` when the body hash differs from `issue_state.bodyHash`. The first poll records a cursor and queues nothing, like the Linear poller. Interval `POLL_GITHUB_SEC`.
+
+The App and the token need one more permission, Issues read and write, and the App subscribes to the `issues` event. GITHUB.md's permission table and the App manifest in `src/connect/github-app.ts` change with task A2.
+
+### 4.3 Ticket review on issues
+
+- `fetchTicket` gets a `github` branch: `GET /repos/{o}/{r}/issues/{n}` into `Ticket` with labels, milestone, `type.name`, state, and author.
+- Acceptance criteria, first match wins: the section under a heading that matches "acceptance criteria" (the existing `extractAcceptanceCriteria`), the task list items (`- [ ]`) in the body, or the `### <label>` sections that GitHub renders from issue form templates.
+- The review comment is sticky per issue, marked `<!-- localdost:ticket-review -->`. A re-review edits that comment in place. Rule `ticket_comment` keeps its default `ask`.
+- The flow matches Jira and Linear, including the score floor and the profile-based code lookup from section 2.7.
+
+### 4.4 PR to issue links
+
+Three sources, stored in `links`:
+
+| Source | How | Kind |
+|---|---|---|
+| Closing keywords [C6] | Regex on PR title and body: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved, then `#N`, `owner/name#N`, or an issue URL. GitHub closes the issue only when the PR targets the default branch; localdost records the link for any base | `closes` |
+| Development sidebar | GraphQL `pullRequest.closingIssuesReferences` on every PR the dot checks. It also returns manual sidebar links (up to 10 per PR, any branch, cross-repo [C6]) that no text holds. Field signature to confirm [C9] | `closes` |
+| Timeline [C7] | `GET /repos/{o}/{r}/issues/{n}/timeline`: cross-reference events (a PR or issue mentions this one) and sub-issue and blocking events | `references`, `parent`, `blocks` |
+
+Jira keys and Linear identifiers in a PR title or branch already link a PR to a ticket for AI-Vision cases. The same function now writes `links` rows for all three trackers, so traceability works the same way for each.
+
+Test links: a spec that names an issue (`ProfileSpec.issues`) writes a `tests` link. A `whatToTest` item from a review of a PR that closes an issue writes a `covers` link with the run id.
+
+### 4.5 Defects filed as issues
+
+- New action kind `issue_create`, default rule `ask`. It runs on its own only when the user sets the rule to `act`.
+- When: a `post_merge` or `pr_check` verdict of `product_failure` with a case that failed on both retries. Flaky results and test failures never draft a defect.
+- Body: title from the failing scenario; steps from the test steps (Playwright step reporter or the `whatToTest` steps); expected and actual; the error text; links to the run, trace, and screenshot; the suspected PR; "Relates to #N" for each requirement linked to that PR. Labels: the dot's `labels.defect` (default `bug`) plus `localdost`. Issue type: the first `issueTypes.defect` when the org has types. Milestone: the linked requirement's milestone.
+- Duplicate guard: the body carries `<!-- localdost:defect sig=<hash of test id and first error line> -->`. Before drafting, localdost searches open issues for that marker. A match turns the draft into a `ticket_comment` on the existing issue: "Seen again in run <link>".
+- The same action targets Jira (create issue) and Linear (`issueCreate`) for those trackers in a later task, which mirrors True Platform's "Create Defects" for Jira [C2].
+
+### 4.6 Per-issue test status
+
+Computed on read from `links` and runs, and cached in `issue_state.testStatus`:
+
+| Status | Rule |
+|---|---|
+| Not tested | No linked PR has a run, and no spec links to the issue |
+| Passing | The latest run of every linked PR passed, and every linked spec passed in its latest run |
+| Failing | A linked spec or `whatToTest` item failed in the latest run, or an open defect links to the issue |
+| Partly tested | Some `whatToTest` items of the linked PRs are `not_run` |
+| Out of date | A linked PR has a newer head than its latest run |
+
+The app shows the status. Writing it back to GitHub is optional and off by default: a `qa: passing` or `qa: failing` label and a status line in the sticky ticket-review comment, both through the `ticket_comment` rule.
+
+### 4.7 Traceability view
+
+New client feature `client/src/features/trace/`: one table of requirements per dot, one row per issue, with a detail drawer. It works the same for Jira, Linear, and GitHub tickets.
+
+```text
+Traceability  [Milestone: 2026.11 v]  [Status: All v]  [Repo: acme/shop-web v]
+  Issue                         Type      PRs        Tests   Defects   Status
+  #412 Guest checkout coupon    Feature   #58 #61    6 / 7   1 open    (!) Failing
+  #418 Saved cards              Feature   #63        3 / 3   -         (o) Passing
+  #420 Order history filter     Task      -          0       -         ( ) Not tested
+```
+
+Drawer: issue summary and acceptance criteria, linked PRs with their last verdict, linked tests with the last result per run, defects, and the QA review comment. Export: the table as CSV, and a `ReportPage` of kind `readiness` per milestone.
+
+### 4.8 Match with the Katalon True Platform model
+
+Public Katalon docs, read on 2026-10-08, document no GitHub Issues ALM integration. True Platform lists Jira, Azure DevOps, and Xray as ALM integrations [C1]. Its GitHub integration syncs test cases and test suites between a repo and the platform [C10], and recent release notes add GitHub Server support and GitHub context for the Katalon AI assistant [C11]. If the True Platform team runs GitHub Issues as its ALM, that setup lives outside the public docs, and Huy should confirm the label and type conventions before task A4.
+
+This design therefore copies the shape of True Platform's Jira ALM model onto GitHub Issues [C2]:
+
+| True Platform with Jira | localdost with GitHub Issues |
+|---|---|
+| Pick Jira work item types to sync as requirements | `issueTypes.requirement` or `labels.requirement` |
+| Status and resolution mapping | Issue `state` plus `closed` reason; labels for anything finer |
+| Release-date fields | Milestone and its due date |
+| Requirement coverage: linked and executed test cases, pass and fail, defects [C11] | Per-issue test status (4.6) and the traceability view (4.7) |
+| "Link Defects" to existing issues, "Create Defects" as new issues | Duplicate guard comment, and `issue_create` behind the ask rule (4.5) |
+| Test cases synced from a GitHub repo | That repo joins the dot as a `test` repo; the scan reads its specs (section 3) |
+
+Two hand-offs keep the systems compatible. Katalon reporters upload JUnit and Playwright reports to True Platform, so a team can send localdost run results there through the `upload-report` path when it wants True Platform as the system of record. The Katalon MCP server can be attached as an MCP connection, so a dot's chat can read True Platform test cases and results next to the GitHub issues.
+
+---
+
+## 5. Build tasks
+
+Sizes: S is under half a day, M is one to two days, L is three days or more. Each row is one PR that passes review and CI on its own and leaves the product working. Dependencies in brackets.
+
+### Multiple repos (KAT-85, part 1)
+
+| # | PR | Size | Notes |
+|---|---|---|---|
+| M1 | Types (`RepoRole`, `WorkspaceRepo`, `WatchRepo`, `Watch.repos`, `waitForPreviewSec`, `repo` live event) and `src/repos.ts` with `watchRepos`, `repoForEvent`, unit tests | S | No behaviour change |
+| M2 | Move the 14 direct `watch.repo` readers to the helpers; `githubFor` picks the repo from the event; `githubForRepo` | M | [M1] Existing tests must pass unchanged; add a two-repo dot test |
+| M3 | `repos` table, `migrateWatchRepos`, `settings.repos` mirror, `/api/repos` endpoints (scan state stays `queued`) | M | [M1] Migration test on a copy of a real `localdost.db` |
+| M4 | `watchMatches` over repo sets, role-to-job routing for app repos, poller over the repo union, `repos` on the dots API with validation, `dotView` repos | M | [M2, M3] |
+| M5 | UI: Setup repo list, dot dialog repo picker with roles, dot detail Repos section | L | [M4] Screenshots of both themes at 390x844 and 1280x800 |
+
+### Repo scan and profile (KAT-85, part 2)
+
+| # | PR | Size | Notes |
+|---|---|---|---|
+| R1 | Mirror and worktree manager (`src/repos/mirror.ts`): partial clone, fetch, worktree add and remove, boot sweep. Review checkout uses it behind a flag | M | [M3] |
+| R2 | Deterministic scanner: inventory, stack, apps, routes, tests, CI, owners, mentions; `RepoProfile` types; `repo_profiles` storage; `repo_scan` job; blob cache; demo profile | L | [R1] Fixture repos: Next.js monorepo, Django, Spring Boot |
+| R3 | Licence material for tag queries: `tags.scm` files from MIT grammar repos with headers, `NOTICE` lines | S | Before R4 merges |
+| R4 | Symbol map: `web-tree-sitter`, tags for TS, JS, Python, Java, Go; reference graph; personalized PageRank; top 60 files | M | [R2, R3] |
+| R5 | Area drafts, the naming model call with schema and prose checks, glossary, mock backend output | M | [R2] |
+| R6 | Incremental refresh: triggers from push and merge, coalescing, delta parse, full-rescan rules, `PROFILE_MIN_INTERVAL_SEC` | M | [R2, M4] |
+| R7 | Consumers: impact `via: 'profile'`, `<repo_profile>` reviewer block, `pickSpecs` by area, ticket review by area, chat tools `get_repo_profile`, `find_tests`, `pack_area` (Repomix) | M | [R5] Re-run `npm run eval:qa-review`; impact accuracy must not drop |
+| R8 | Repo page, overrides `PATCH`, Save as review.yml through `open_pr`, chat proposal card | L | [R5, M5] Screenshots both themes |
+| R9 | Profile evals: expected areas for the three fixture repos, area precision and recall, scan time and token budget checks in CI | M | [R5] |
+
+### Test repos (KAT-86)
+
+| # | PR | Size | Notes |
+|---|---|---|---|
+| T1 | `TestRepoConfig`, `RunSpec.testRepo`, validation, test repo fields in the dot dialog | S | [M5] |
+| T2 | Cross-repo spec inventory and link rules (route, test id, issue key, API path, text, area), page object hop, repo-prefixed `existingTest` and `testsAtRisk` | M | [R2] |
+| T3 | Adapter interface; move the Playwright path behind it with no behaviour change; test repo checkout at a resolved ref (PR body directive, `match_branch`, fixed, default); `passEnv` rule; fork rule | M | [R1, T1] Built (2026-10-19, `src/runner/adapters/`, `src/runner/test-repo.ts`). The adapter covers the arguments, environment, image and report reading; the live view stays in `src/runner/index.ts`. R1 was not needed: the checkout uses its own cache folder |
+| T4 | Flow wiring: test-repo batch in `pr_check` and `post_merge`, `mergeReports` with prefixes, comment line, check summary, flaky keys, `waitForPreviewSec` | M | [T2, T3] Built (2026-10-19, `src/flows/testRepo.ts`) without T2: the tests are the whole suite, or the tests of the areas that `test.areas` maps. The fixture test repo for the demo shop is `test/fixtures/tests-repo`, used by `test/test-repo-e2e.test.ts`; the demo dot itself has no test repo yet |
+| T5 | Test repo events: `test_pr_check`, `ci_failure` context with app merges, scans on test repo merges | M | [T4, R6] |
+| T6 | `junit-xml.ts` parser and the Cypress adapter | M | [T3] |
+| T7 | WebdriverIO adapter with a wrapper config | S | [T6] |
+| T8 | pytest and JUnit (Maven, Gradle) adapters | M | [T6] |
+| T9 | Katalon adapter: detection, Object Repository parse, `katalonc` with the licence gate, generated suite for the selection | L | [T6] Needs a Runtime Engine licence on the test machine |
+| T10 | SANDBOX.md and GITHUB.md: test repos, install the App on every repo | S | [T4] |
+
+### GitHub Issues as ALM (KAT-87)
+
+| # | PR | Size | Notes |
+|---|---|---|---|
+| A1 | Widen the tracker unions; new `Ticket` fields; audit every `switch` on tracker kind | S | [M2] |
+| A2 | `github-issues.ts` normalizer, webhook routing for `issues` and `issue_comment.created`, Issues permission and event in the App manifest | M | [A1] |
+| A3 | Issue poller and `issue_state` | M | [A2] |
+| A4 | Ticket review on issues: fetch, acceptance criteria from headings, task lists, and issue forms; sticky comment; `/localdost review`; tracker settings UI for labels, types, milestones | M | [A2] Confirm True Platform label and type conventions first (4.8) |
+| A5 | `links` table; closing keyword parser; `closingIssuesReferences`; timeline; Jira and Linear keys through the same function | M | [A1] |
+| A6 | `issue_create` action kind (default `ask`), defect draft, signature guard, GitHub executor | M | [A5] |
+| A7 | Per-issue test status and the optional label write-back | S | [A5, T4] |
+| A8 | Traceability view, CSV export, milestone readiness report | L | [A7] Screenshots both themes |
+| A9 | `issue_create` executors for Jira and Linear | S | [A6] |
+| A10 | TRACKERS.md GitHub Issues section; GITHUB.md permissions | S | [A4] |
+
+### Order
+
+1. M1, M2, M3, M4. After these, a dot can hold several app repos with no scan yet.
+2. R1, R2, R3, R4, R5, R6, then M5 and R7. First useful release: multi-repo dots with profiles that feed impact and ticket review.
+3. A1 to A5 can run in parallel with step 2, since they depend only on M2.
+4. T1 to T5 with Playwright only. Second release: test repos on Playwright plus GitHub Issues review and links.
+5. T6, T7, T8, A6, A7, A8, R8, R9.
+6. T9 (Katalon, licence-gated), A9, and the docs tasks T10 and A10 with the features they describe.
+
+---
+
+## 6. Sources
+
+Fetched 2026-10-08.
+
+Repo understanding:
+
+- [A1] Aider `repomap.py` and `queries/`: https://raw.githubusercontent.com/Aider-AI/aider/main/aider/repomap.py , https://github.com/Aider-AI/aider/tree/main/aider/queries ; licence via https://api.github.com/repos/Aider-AI/aider
+- [A2] Aider repo map docs and the tree-sitter post: https://aider.chat/docs/repomap.html , https://aider.chat/2023/10/22/repomap.html
+- [A3] Repomix: https://github.com/yamadashy/repomix , https://repomix.com/guide/code-compress
+- [A4] Repomix MCP server: https://repomix.com/guide/mcp-server
+- [A5] code2prompt: https://github.com/mufeedvh/code2prompt
+- [A6] GitHub languages API and rate limits: https://docs.github.com/en/rest/repos/repos#list-repository-languages , https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api
+- [A7] GitHub SBOM API and its closing date: https://docs.github.com/en/rest/dependency-graph/sboms
+- [A8] OpenQodex: https://github.com/openqodex/openqodex , https://github.com/openqodex/openqodex/tree/main/packages/graph
+- [A9] SCIP: https://github.com/sourcegraph/scip , https://github.com/sourcegraph/scip-typescript , https://github.com/sourcegraph/scip-python
+- [A10] tree-sitter: https://github.com/tree-sitter/tree-sitter
+- [A11] Universal Ctags: https://github.com/universal-ctags/ctags , https://docs.ctags.io/en/latest/man/ctags.1.html
+- [A12] deepwiki-open: https://github.com/AsyncFuncAI/deepwiki-open
+- [A13] DeepWiki MCP: https://docs.devin.ai/work-with-devin/deepwiki-mcp
+- [A14] codebase-memory-mcp: https://github.com/DeusData/codebase-memory-mcp
+- [A15] code-graph-rag: https://github.com/vitali87/code-graph-rag
+- [A16] CodeGraphContext: https://github.com/CodeGraphContext/CodeGraphContext
+- [A17] Serena: https://github.com/oraios/serena
+- [A18] GitNexus: https://github.com/abhigyanpatwari/GitNexus
+- [A19] AGENTS.md generators: https://pypi.org/project/agsk , https://pi.dev/packages/pi-agentsmd
+
+Test repos:
+
+- [B1] Playwright configuration: https://playwright.dev/docs/test-configuration
+- [B2] Playwright CLI: https://playwright.dev/docs/test-cli
+- [B3] Playwright reporters: https://playwright.dev/docs/test-reporters
+- [B4] Cypress configuration: https://docs.cypress.io/app/references/configuration
+- [B5] WebdriverIO configuration: https://webdriver.io/docs/configuration
+- [B6] WebdriverIO JUnit reporter: https://webdriver.io/docs/junit-reporter
+- [B7] pytest usage: https://docs.pytest.org/en/stable/how-to/usage.html
+- [B8] pytest-base-url (MPL-2.0): https://pypi.org/project/pytest-base-url/
+- [B9] Maven Surefire: https://maven.apache.org/surefire/maven-surefire-plugin/examples/single-test.html , https://maven.apache.org/surefire/maven-surefire-plugin/examples/junit-platform.html
+- [B10] GitHub Actions events and checkout of a second repo: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows , https://github.com/actions/checkout
+- [B11] Katalon Runtime Engine command line: https://docs.katalon.com/katalon-studio/execute-tests/katalon-runtime-engine/command-line-syntax-in-katalon-runtime-engine
+
+GitHub Issues and Katalon:
+
+- [C1] Katalon Platform integrations: https://docs.katalon.com/katalon-studio/integrations/integrations-in-katalon-platform
+- [C2] Katalon Platform Jira integration: https://docs.katalon.com/katalon-platform/integrations/alm-and-test-management/jira-integration
+- [C3] GitHub issue types: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/managing-issue-types-in-an-organization
+- [C4] Issue types and sub-issues GA: https://github.blog/changelog/2025-04-09-evolving-github-issues-and-projects/
+- [C5] Sub-issues: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues
+- [C6] Linking a pull request to an issue: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue
+- [C7] Timeline events API: https://docs.github.com/en/rest/issues/timeline
+- [C8] Webhook events and payloads: https://docs.github.com/en/webhooks/webhook-events-and-payloads
+- [C9] GraphQL `PullRequest` object: https://docs.github.com/en/graphql/reference/objects#pullrequest
+- [C10] Katalon Platform GitHub integration: https://docs.katalon.com/katalon-platform/integrations/repository/github-integration
+- [C11] Katalon TestOps release notes: https://docs.katalon.com/katalon-platform/release-notes/katalon-testops-release-notes
+- Katalon MCP server: https://docs.katalon.com/katalon-platform/testops-mcp-server
+
+To confirm before the matching task: the `web-tree-sitter` npm licence (R4), the scip-python licence (not used), the Repomix library API (R7), the WebdriverIO `--spec` and `--baseUrl` flags (T7), the Katalon project folder layout (T9), and the `closingIssuesReferences` signature (A5).