@nurix/etna 0.15.6 → 0.15.8

package/data/harnesses/{re/rules/re-discovery.md → discover/rules/discovery.md}

@@ -1,19 +1,32 @@
 # Discovery Reference — Scope Gate · Access Vector · Dimension Catalog
 
-The reference knowledge for **Discovery** (`re` harness, Mode 1). It carries all three of
-Discovery's steps in the order they run:
+The reference knowledge for **Discovery** (`discover` harness, Mode 1). It carries all three of
+Discovery's steps in the order they run (preceded by corpus-root resolution, Step 00 below):
 
 - **Part A — Scope-feasibility gate** (Step 0): resolve the target's identity and emit a verdict
   so the run never wastes effort on an infeasible target.
 - **Part B — Access vector** (Step 1): grade the four-axis capability vector that decides which
   dimensions are reachable and which method each uses.
 - **Part C — Dimension catalog** (Step 2): the canonical list of dimensions, their detection
-  signals, dump strategy, and owning agent.
+  signals, collection strategy, and owning agent.
 
 `ingestion` also reads **Part C** to dispatch the right agent with the right method.
 
 ---
 
+# Step 00 — Resolve the corpus root (before the gate)
+
+Before Part A, decide **where this run writes** — the harness picks intelligently, it does not hardcode `research/`:
+
+1. **Reuse an existing discovery corpus** if the project has one — search for any folder containing a prior run's `*/00-scope-verdict.md` (commonly `research/`, but also `recon/`, `discovery/`, `teardowns/`, `analysis/`, or a folder the user names).
+2. If several exist, prefer the one the user points at, else the most recently written.
+3. If none exists and the user hasn't named one, default to `research/` at the repo root.
+4. **Confirm the chosen root in one line** before writing `00-scope-verdict.md`.
+
+All `research/<target>/` paths in the harness are the *default form*, relative to the resolved `<corpus>/`.
+
+---
+
 # Part A — Scope-feasibility gate (Step 0)
 
 Run this **before** any dimension probing. It resolves the target's identity and emits one of four
@@ -146,11 +159,20 @@ The three named **cases** are presets over this vector — a target can light se
 (Liveblocks = source:full + runtime:reachable + auth:obtainable + presence:rich → nearly all
 dimensions). Rules:
 - **`auth:obtainable` is a hint, not actionable** — the harness never self-signs-up; it only counts as `have-login` if the *user* hands over a session.
+- **A *claimed* login is `auth:claimed` (confidence medium), not `auth:have-login` (high), until a cheap live probe confirms it.** A user saying "I'm logged in" — or a session being merely *expected* — is not proof: profiles expire, a fresh tab may not restore an in-memory token, and a deep-link can bounce to a login wall while the root looks authed. Grade `auth:claimed` until Discovery (or the `session` agent's first step) navigates the app and confirms an **authenticated surface** (a dashboard, a populated `viewer`/`/me`, a token in the store) — only then promote to `have-login`. Grading a claimed login `high` lets a session collapse to `blocked` after dispatch, with the wasted dispatch hidden behind a confident grade.
 - **Dimension-level access overrides the target headline** for method selection (a Case-1 target can still have a Case-3 session dimension).
 - Method swaps on axis *value*: `source:full` ⇒ `clone-and-map`; `source:partial` ⇒ `source-map-reassembly`; `runtime:reachable + source:none` ⇒ `bundle-string-mine` + wire-capture.
 
 Discovery records the resolved vector in the `access_grade` frontmatter of `00-recon-plan.md`.
 
+> **Hypotheses are not facts (seed them tagged, never echo them).** Any *derived inference* Discovery
+> makes beyond the four graded axes — e.g. "this `localStorage` key implies a GraphQL backend", "this
+> host is the realtime endpoint" — is recorded in `00-recon-plan.md` **as a labelled hypothesis**, never
+> as a plan fact, and is tagged `verify:may-be-stale` when seeded to a collector (CLAUDE.md Mode 2) so
+> Ingestion **re-derives** rather than echoes it. A wrong inference seeded as framing propagates: a real
+> run's `apolloAnonId ⇒ GraphQL` guess was repeated (hedged) by two captures before the `session` dimension
+> refuted it (the backend was RSC + Server Actions; the key was an Apollo.io tracker).
+
 ---
 
 # Part C — The dimension catalog (Step 2)
@@ -163,7 +185,7 @@ Discovery records the resolved vector in the `access_grade` frontmatter of `00-r
 | 4 | **api** | `api` | runtime/presence | OpenAPI/GraphQL → endpoint catalog (+ **MCP/tool-catalog fold-in**) |
 | 5 | **website** | `website` | presence | crawl public pages → features, pricing, positioning |
 | 6 | **community** | `community` | presence | first-party changelog/issues/discord themes |
-| 7 | **session** | `session` | auth:have-login | delegate to the session playbook (§9 of `re-ingestion`: 3-pass, P0–P6) |
+| 7 | **session** | `session` | auth:have-login | delegate to the session playbook (§9 of `ingestion`: 3-pass, P0–P6) |
 | 8 | **deployed-client-bundle** | `deployed-client-bundle` | runtime:reachable | unauth SPA: route table, API-path catalog, flags, env, source maps |
 | 9 | **infra-backend-fingerprint** | `infra-backend-fingerprint` | runtime/presence | DNS, cert-transparency, CDN/cloud, headers (+ **sub-processor/trust fold-in**) |
 | 10 | **wire-capture** | `wire-capture` | runtime (source:none) | the 3-rung ladder for non-browser/no-source clients (gated) |
@@ -172,6 +194,11 @@ Discovery records the resolved vector in the `access_grade` frontmatter of `00-r
 > **Deferred (available on request, not built):** `external-reputation` (G2/Reddit/HN — the only
 > "what others say" surface) and `hiring-intel` (job posts leak the backend stack). Strong
 > candidates, declined for this iteration. Re-add via self-correction if a run needs them.
+> **Conditional trigger:** when `community` returns **no first-party feedback loop** (no public
+> issues/roadmap/changelog/forum — feedback funnelled to a gated channel), flag `external-reputation`
+> as **recommended-for-this-run** in `00-recon-plan.md`, so the user-sentiment blind spot is a surfaced
+> choice rather than a silent gap (the `community` user-pain claims are then capped at tentative —
+> evaluation closed-feedback cap).
 
 An **absent** dimension is a finding — record it with its evidence; never silently drop it.
 
@@ -182,15 +209,39 @@ See git history / the source playbook for the full strategy text; in brief:
   packages + internal dep hierarchy, return a per-package work-list for the main-session fan-out.
 - **docs** — prefer in-repo docs, then `llms.txt`/`llms-full.txt`, then crawl; organize by section.
 - **packages** — per public package: registry metadata, `exports` map + `.d.ts` type surface, health.
+  **Registry-ownership cheap-test (grade ownership before calling an SDK "partial/unverified").** Read
+  the registry `author`/`maintainers`/`summary`/`project_urls`/`Homepage` fields and check the
+  dependency set for a generator fingerprint (Stainless: `httpx`/`pydantic`/`anyio`/`distro`/`sniffio`
+  + in-file "generated by Stainless" headers; Speakeasy; OpenAPI-Generator). An `author`/`summary` that
+  says "official … library for the X API" + a vendor-domain `project_urls` confirms **official**
+  ownership at **high** confidence even when the *source* repo is private — the published tarball IS the
+  public-API mirror (a high-confidence `registry-metadata` anchor), so it is **not** "partial." Tag a
+  genuinely third-party/community package (different author/scope) as such, but don't down-grade an
+  official-but-private-source SDK to "unverified."
 - **api** — fetch the spec verbatim, build an endpoint catalog (auth, envelope, pagination, webhooks).
+  **Grade the method from a RETRIEVED artifact, never a label.** Before grading `openapi-verbatim`,
+  actually fetch the candidate spec URL and confirm a **parseable JSON/YAML body** — a docs page merely
+  *titled* "OpenAPI" with no served `spec.json` (or a `/swagger` that 403s) is `docs-reconstructed`
+  (capped medium), and Discovery must pre-grade it that way so the plan matches reality. **A
+  sibling-declared host/op/route count is a coverage checklist (a floor), never a ceiling** — every
+  collector expands from sibling-mined hosts/routes and records the predicted-vs-found delta.
   **NEW fold-in:** also probe MCP/tool surfaces — `/.well-known/mcp`, an MCP server manifest, a
   function-calling tool schema, an LLM "actions" file — and write `raw/tool-catalog.md` (an MCP tool
-  list *is* an API catalog; it lives here, not in its own dimension).
+  list *is* an API catalog; it lives here, not in its own dimension). **Unauth MCP-probe recipe (when
+  the tool catalog itself is auth-gated):** a `GET /mcp` → `405` body often names the transport
+  (e.g. "stateless; only POST is supported" = streamable-HTTP); `GET /sse` presence/absence tells
+  legacy-SSE vs streamable; and `/.well-known/oauth-authorization-server` + `/.well-known/oauth-protected-resource/{name}`
+  reveal the **OAuth/PKCE model + issuer** (e.g. a `jwks_uri` on the auth vendor names Clerk/Auth0/etc.)
+  — all without a token. Capture transport + auth + issuer from these, reconstruct the tool list from
+  docs/SDK, and mark the verbatim `tools/list` **partial** (OAuth-gated).
 - **website** — crawl home/features/pricing/customers/integrations; extract positioning, pricing
   matrix, target market.
 - **community** — *first-party only*: changelog cadence + direction, issue/discussion themes, blog.
 - **session** — the deepest, opt-in, user-gated dimension; delegates to the session playbook in
-  `re-ingestion` §9 (3-pass, P0–P6, captures/raw/curls).
+  `ingestion` §9 (3-pass, P0–P6, captures/raw/curls). For any `auth:have-login`/`auth:claimed`
+  target, Discovery **seeds the Pass-2 decision** (`pass2: offered-pending | declined-by-user |
+  deferred`) into `00-recon-plan.md`, so a Pass-1-only (read-only) session is a *recorded choice*, not a
+  silent omission of the write surface (ingestion §9.2).
 
 ## 8 — deployed-client-bundle — `deployed-client-bundle`
 
@@ -198,15 +249,22 @@ See git history / the source playbook for the full strategy text; in brief:
 (marketing) and `session` (authenticated). Works on closed SaaS with no repo and no login.
 
 **Detection:** an app subdomain (`app.<target>.*`) or SPA route serves a JS bundle;
-`sourceMappingURL` present; a `/assets/*.js` graph.
+`sourceMappingURL` present; a `/assets/*.js` graph. **Two cheap Discovery probes pre-grade the method
+and surface a leak early:** (a) does an entry chunk's `sourceMappingURL` resolve to a `.map`-200? →
+pre-grade `source-map-reassembly` (confidence high — original `src/` recovers). (b) probe a few
+bootstrap-config paths (`/config`, `/backend/config/*`, `/env.json`, a runtime-config endpoint) — a
+200 here is both a method pre-grade and a possible unauth config/secret leak (a finding).
 
 **Strategy:** fetch the main bundle(s); string-mine the **route table**, the **API-path catalog**
-(→ shared `raw/api-path-catalog.md`, `source: bundle`), **feature flags** (→ shared
-`raw/feature-flags.md`), embedded **env config** (`VITE_*`, `NEXT_PUBLIC_*`, public keys —
-field-names only, redact values), and reassemble **source maps** if shipped (`method:
-source-map-reassembly`, confidence high). Digest huge bundles, don't paste.
+(→ append to the shared `dimensions/_shared/api-path-catalog.md`, `source: bundle` — ingestion §6),
+**feature flags** (→ shared `dimensions/_shared/feature-flags.md`), embedded **env config** (`VITE_*`,
+`NEXT_PUBLIC_*`, public keys — field-names only, redact values), and reassemble **source maps** if
+shipped (`method: source-map-reassembly`, confidence high). Digest huge bundles, don't paste. This
+dimension **owns** the app-API bundle mine — other dimensions cite its catalog by path, never re-mine
+the same bundle (ingestion §6).
 
-**Artifacts:** `_summary.md` + `raw/{route-table.md, api-path-catalog.md, feature-flags.md, env-config.md, bundle-map.md}`.
+**Artifacts:** `_summary.md` + `raw/{route-table.md, env-config.md, bundle-map.md}` + appends to the
+shared `dimensions/_shared/{api-path-catalog.md, feature-flags.md}`.
 
 ## 9 — infra-backend-fingerprint — `infra-backend-fingerprint`
 
@@ -231,12 +289,23 @@ what hosts it *might* call; the capture says what it *actually* calls.
 **Detection:** a non-browser client exists (from distribution-artifacts) OR an unauth SPA makes
 structured XHRs worth a tap, AND the appropriate ethics rung is authorized.
 
-**Strategy:** the **3-rung ladder** (lowest privilege first) — see `re-ingestion` §7.1:
+**Strategy:** the **3-rung ladder** (lowest privilege first) — see `ingestion` §7.1:
 1. browser network tap (unauth, default) → `wire-tap-browser`;
 2. HAR export → `wire-har`;
-3. mitmproxy (**gated, opt-in, user-run, first-party traffic only**) → `wire-mitmproxy`.
+3. mitmproxy (**gated, opt-in, user-run, first-party traffic only**) → `wire-mitmproxy`;
+4. **first-party SDK-harness** (when the product publishes an official SDK + the *user* can provision keys) — scaffold + instrument a throw-away client you own (`document_start` taps, full wire) → `sdk-harness` (`ingestion` §7.1). The deepest lane for a `runtime:reachable + source:none` product whose SDK is the only public mirror of the runtime; gated like rung 3.
+
+**Fold note (common path):** when there is no separate non-browser client, wire-capture **folds into
+`session`** (which owns the browser singleton), **never into a curl/WebFetch collector** (a non-browser
+collector cannot run rung-1's in-page tap, and routing it there yields zero `source: wire` rows —
+ingestion §7.1). The folded rung-1 *is* the interceptor `session` installs; its observed paths
+append to the shared `dimensions/_shared/api-path-catalog.md` as `source: wire`. A folded wire-capture
+still leaves a one-paragraph `_summary.md` (`status: folded`, naming the fold target) — never a silent
+drop.
 
-**Artifacts:** `_summary.md` + `captures/wire-narrative.md` + `raw/{flows.json (redacted/digested), api-path-catalog.md (source: wire)}` + `curls.md`. Record the chosen rung + authorization in `_meta`.
+**Artifacts:** `_summary.md` + `captures/wire-narrative.md` + `raw/flows.json (redacted/digested)` +
+appends to shared `dimensions/_shared/api-path-catalog.md (source: wire)` + `curls.md`. Record the
+chosen rung + authorization in `_meta`.
 
 ## 11 — distribution-artifacts — `distribution-artifacts`
 
@@ -251,9 +320,9 @@ capability map). **Electron** — `npx asar extract app.asar` → map JS modules
 route/API/flag catalog from the desktop client (often richer than web). **mobile** — `Info.plist`/
 `AndroidManifest` hosts, ATS exceptions, embedded-SDK list from strings (**redact any embedded
 keys**). **CLI** — help text/subcommands = an API catalog. Read the artifact's EULA first (see
-`re-ingestion` §7.2); never silently decompile a restrictively-licensed binary.
+`ingestion` §7.2); never silently decompile a restrictively-licensed binary.
 
-**Artifacts:** `_summary.md` + `raw/{extension-manifest.md, electron-asar-map.md, mobile-strings.md, cli-catalog.md}` (whichever apply) + `raw/api-path-catalog.md` (source: distribution).
+**Artifacts:** `_summary.md` + `raw/{extension-manifest.md, electron-asar-map.md, mobile-strings.md, cli-catalog.md}` (whichever apply) + appends to shared `dimensions/_shared/api-path-catalog.md` (source: distribution).
 
 ---
 

package/data/harnesses/{re/rules/re-evaluation.md → discover/rules/evaluation.md}

@@ -23,6 +23,29 @@ coherent picture, **weighted by how each claim was obtained**, with disagreement
 `distribution-artifacts` are mutually independent and independent of marketing. **`website` and
 `docs` are NOT independent** for *feature claims* (docs often restate marketing) — two of them
 agreeing is still one source. A bundle-declared route + a session-observed route ARE independent.
+**Same artifact ⇒ one source.** Two dimensions that string-mine the *same* static asset (one bundle /
+one spec / one binary) are **one source** — never a band-bump — even when they report different
+counts; the divergent counts are a **reported range, not a flagged conflict** (`deployed-client-bundle`
+278 vs `website` 361 over one bundle is one finding with a range, not corroboration and not a conflict).
+**OSS distribution clients are an independent corroboration lane.** An API-surface claim resting on a
+single *third-party* wrapper (a community MCP server, an unofficial SDK) is tentative — but a
+**first-party open-source integration client** (`distribution-artifacts`: a Unity/Figma/CLI plugin or
+published SDK source) that calls the same routes is **independent of both marketing and the third-party
+wrapper**, and corroborates it → promotes. (A legacy/granular route family seen only in a third-party
+MCP becomes a real finding once the official OSS client calls it too.)
+
+**Closed-feedback confidence cap.** When the `community` dimension finds **no first-party feedback
+loop** (no public issues / roadmap / changelog / forum — feedback funnelled to a gated channel), its
+user-pain / most-requested-feature claims are **inference-from-changelog only → capped at
+`low`/tentative**, never promoted on changelog frequency alone. The surface that *would* corroborate
+user sentiment is `external-reputation` (a deferred dimension) — flag it as recommended-for-this-run
+when this cap fires (see discovery Part C deferred-dimension trigger).
+
+**Write-side-unobserved cap.** A `session` dimension carrying `write_side_observed: false` (a
+Pass-1-only run) has observed feature *existence/gating* but **not** feature *execution behavior*. Any
+marketed generate/submit/launch *behavior* claim therefore stays **tentative and is never promoted to
+fact** from marketing/docs alone — render the write-side gap **once** from the frontmatter flag, not
+re-hedged per rollup.
 
 **Presentation mapping:** high → stated as fact; low/single-source → hedged as tentative;
 conflicted → flagged. (This is the "lighter" form of the provenance-weighting — done inline in the
@@ -58,11 +81,19 @@ prose, not via a separate `claims.yaml`.)
 # <Target> — Data Model & API / SDK Surface
 ## Core entities          (domain objects + relations; ER-style — when the runtime exposes an RBAC verb
                            taxonomy, derive the entity set from it: `X_CREATE/VIEW/EDIT/DELETE` ⇒ entity X)
-## Integration surface    (SDK/packages public API · REST/HTTP catalog · realtime/wire protocol — flag
-                           where the app's OWN API differs from the published/developer API; that split is common)
+## Integration surface    (SDK/packages public API · REST/HTTP catalog · realtime/wire protocol)
+## Published-vs-app-own API diff  (emit WHENEVER the target publishes a developer/partner/MCP API —
+                            common for mature SaaS, but not universal. The app the SPA runs on is frequently
+                            a different, broader, differently-authed API than the published one: list ops the
+                            app uses that the public API omits, AND public ops the app never calls — both are
+                            findings. If there is NO published API, say so explicitly: "no published API — the
+                            app surface is the only surface" is itself the finding, not an empty section.)
 ## Auth & tenancy model   (token type, where it lives, scope expression)
-## Three-way API-path diff (the seam rule: bundle-declared vs session-observed vs wire-observed —
-                            dormant/unshipped routes are findings)
+## API-path diff (adaptive, N-way over the runtime sources present)  (the seam rule: bundle-declared vs
+                            session-observed vs wire-observed. Title it for the sources ACTUALLY run —
+                            enumerate only those lanes; an absent lane [session blocked / wire folded] is a
+                            recorded gap, NOT a structural hole to apologize for. Dormant/unshipped routes
+                            are findings.)
 ## Cross-dimension reconciliation  (published surface [api/packages/docs] vs observed wire [session/
                             wire-capture]; document drift — published=fact, observed-drift=tentative)
 ## Open questions
@@ -104,3 +135,8 @@ prose, not via a separate `claims.yaml`.)
 4. Tag every claim with provenance; weight per the rules above; flag every disagreement; record
    every gap. A confident doc built on one low-confidence dimension is worse than an honest
    "single-source, unverified."
+
+> **Classifying a raw observation** — to turn a storage-key prefix, an auth tell, an envelope shape,
+> or a realtime frame into a *named* stack finding, use the fingerprint tables in
+> `tradecraft.md` (storage→stack, auth-provider, API-envelope, realtime-trap). They name what
+> a finding *is*; this file governs how confidently to *state* it.