@qulib/core 0.8.2 → 0.10.0

package/README.md

@@ -140,16 +140,38 @@ After a normal **`analyze`**, `output/report.json` includes **`gapAnalysis.costI
 Re-print that block from disk:
 
 ```bash
-npx tsx src/cli/index.ts cost doctor
-# or: npx tsx src/cli/index.ts cost doctor --report output/report.json
+qulib cost doctor
+# or: qulib cost doctor --report output/report.json
 ```
 
 ## CLI (from npm)
 
+**Release confidence — the flagship command:**
+
+```bash
+npx @qulib/core confidence --url https://example.com
+```
+
+Returns ship / caution / hold / block with a 0–100 score, top risks, and recommended next checks. Add `--repo` to also score test-automation maturity and API coverage.
+
+**Analyze (full gap report):**
+
 ```bash
 npx @qulib/core analyze --url https://example.com
 ```
 
+**Scaffold a test suite:**
+
+```bash
+npx @qulib/core scaffold --url https://example.com --framework cypress-e2e
+```
+
+**Score automation maturity (repo-only, no URL needed):**
+
+```bash
+npx @qulib/core score-automation --repo /path/to/repo
+```
+
 Use `npx playwright install chromium` the first time you scan (Playwright is a dependency).
 
 ## Programmatic API
@@ -323,31 +345,34 @@ qulib analyze --url https://yourapp.com --auth-storage-state ./qulib-storage-sta
 
 ## Sample report (fixture baseline)
 
-From the local fixture baseline used in v0.5.0 PR 1/2:
+The fixture tests in `packages/core/src/__tests__/analyze.fixtures.test.ts` assert structural shape — that `releaseConfidence` is a number, `gaps` is an array, and coverage scores are non-negative. Exact scores vary with each scoring version; re-run the fixture suite for current reference values.
+
+A minimal structural snapshot looks like:
 
 ```json
 {
   "status": "complete",
   "releaseConfidence": 68,
   "gaps": [
-    "... 4 total gap items ..."
+    "... gap items ..."
   ]
 }
 ```
 
-Use these as conservative reference numbers:
-- public fixture (`/`): `releaseConfidence: 68/100`, `gaps: 4`
-- auth-wall fixture (`/auth`): `releaseConfidence: 24/100`, `gaps: 2`
-- broken fixture (`/broken`): `releaseConfidence: 0/100`, `gaps: 6`
-
 ## MCP tools quick map
 
 | Tool | When to use | Key input |
 |---|---|---|
-| `analyze_app` | Main QA scan for release confidence + gaps | `url`, optional `auth`, optional LLM knobs |
-| `detect_auth` | Fast single-pass auth pattern guess | `url`, optional `timeoutMs` |
-| `explore_auth` | Deeper auth-path discovery on unfamiliar apps | `url`, optional `timeoutMs` |
-| `qulib_score_automation` | Score local repo automation maturity | absolute `repoPath`, optional `includeFullDimensions` |
+| **`qulib_score_confidence`** | **Flagship.** Fused verdict (ship/caution/hold/block) from all collectors | `url` and/or `repoPath`, optional `includeViews.replay` |
+| `qulib_analyze_app` | Live-app QA scan: release confidence + gaps + a11y | `url`, optional `auth`, optional LLM knobs |
+| `qulib_score_automation` | Score local repo test-automation maturity | absolute `repoPath`, optional `includeFullDimensions` |
+| `qulib_score_api` | Discover API endpoints and score their test coverage | absolute `repoPath`, optional `enableTier3`, `includeEndpointDetail` |
+| `qulib_scaffold_tests` | Generate Cypress scaffold from a live URL (`cypress-e2e` only; playwright not yet implemented) | `url`, optional `framework`, `maxPagesToScan`, `recipes` |
+| `qulib_explore_auth` | Deeper auth-path discovery on unfamiliar apps | `url`, optional `timeoutMs` |
+| `qulib_detect_auth` | Fast single-pass auth pattern guess | `url`, optional `timeoutMs` |
+| `analyze_app` | Legacy alias for `qulib_analyze_app` — kept for backwards compatibility | same as `qulib_analyze_app` |
+| `explore_auth` | Legacy alias for `qulib_explore_auth` — kept for backwards compatibility | same as `qulib_explore_auth` |
+| `detect_auth` | Legacy alias for `qulib_detect_auth` — kept for backwards compatibility | same as `qulib_detect_auth` |
 
 ## Output directories
 

package/bin/qulib.js

@@ -5,10 +5,9 @@ import { dirname, resolve } from 'node:path';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const cliPath = resolve(__dirname, '../src/cli/index.ts');
+const cliPath = resolve(__dirname, '../dist/cli/index.js');
 
-const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-const child = spawn(npxCmd, ['tsx', cliPath, ...process.argv.slice(2)], {
+const child = spawn(process.execPath, [cliPath, ...process.argv.slice(2)], {
   stdio: 'inherit',
 });
 

package/dist/__tests__/playwright-available.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lightweight helper used by test files that require a Playwright Chromium
+ * installation. Checks for the browser at the filesystem level — no side
+ * effects, no subprocess launch.
+ *
+ * Two ways to skip:
+ *   1. Set PLAYWRIGHT_SKIP=1 in the environment — explicit opt-out, useful for
+ *      fresh-clone CI jobs that intentionally skip browser tests.
+ *   2. The Playwright Chromium executable is simply absent from the expected
+ *      install path (e.g. the developer never ran `npx playwright install`).
+ *
+ * Usage in test files:
+ *
+ *   import { chromiumAvailable, CHROMIUM_SKIP_REASON } from './playwright-available.js';
+ *
+ *   test('my browser test', { skip: !chromiumAvailable, skipMessage: CHROMIUM_SKIP_REASON }, () => { ... });
+ *
+ * Or for a subtree of tests (t.before guard):
+ *
+ *   if (!chromiumAvailable) { t.skip(); return; }
+ */
+/**
+ * True when a Playwright Chromium browser binary is present on disk AND the
+ * caller has not set PLAYWRIGHT_SKIP=1.
+ */
+export declare const chromiumAvailable: boolean;
+/**
+ * Human-readable reason string passed to `t.skip()` / `skipMessage` so the
+ * skip is self-documenting in test output.
+ */
+export declare const CHROMIUM_SKIP_REASON: string;
+//# sourceMappingURL=playwright-available.d.ts.map

package/dist/__tests__/playwright-available.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-available.d.ts","sourceRoot":"","sources":["../../src/__tests__/playwright-available.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAC0C,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAEqE,CAAC"}

package/dist/__tests__/playwright-available.js

@@ -0,0 +1,35 @@
+/**
+ * Lightweight helper used by test files that require a Playwright Chromium
+ * installation. Checks for the browser at the filesystem level — no side
+ * effects, no subprocess launch.
+ *
+ * Two ways to skip:
+ *   1. Set PLAYWRIGHT_SKIP=1 in the environment — explicit opt-out, useful for
+ *      fresh-clone CI jobs that intentionally skip browser tests.
+ *   2. The Playwright Chromium executable is simply absent from the expected
+ *      install path (e.g. the developer never ran `npx playwright install`).
+ *
+ * Usage in test files:
+ *
+ *   import { chromiumAvailable, CHROMIUM_SKIP_REASON } from './playwright-available.js';
+ *
+ *   test('my browser test', { skip: !chromiumAvailable, skipMessage: CHROMIUM_SKIP_REASON }, () => { ... });
+ *
+ * Or for a subtree of tests (t.before guard):
+ *
+ *   if (!chromiumAvailable) { t.skip(); return; }
+ */
+import { chromium } from '@playwright/test';
+import { existsSync } from 'node:fs';
+/**
+ * True when a Playwright Chromium browser binary is present on disk AND the
+ * caller has not set PLAYWRIGHT_SKIP=1.
+ */
+export const chromiumAvailable = !process.env['PLAYWRIGHT_SKIP'] && existsSync(chromium.executablePath());
+/**
+ * Human-readable reason string passed to `t.skip()` / `skipMessage` so the
+ * skip is self-documenting in test output.
+ */
+export const CHROMIUM_SKIP_REASON = process.env['PLAYWRIGHT_SKIP']
+    ? 'PLAYWRIGHT_SKIP=1 is set — browser tests opted out. Unset PLAYWRIGHT_SKIP to enable.'
+    : 'Playwright Chromium is not installed. Run `npx playwright install chromium` to enable these tests.';

package/dist/adapters/ci-results-adapter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * CI-results evidence adapter (P4 — evidence collectors).
+ *
+ * Maps a CI run summary (test pass/fail counts, build status, optional flakiness
+ * data) into an `EvidenceItem` for `computeReleaseConfidence`, using the
+ * `ci-results` source kind reserved in confidence.schema.ts.
+ *
+ * Design:
+ *   - Pure function — no I/O, no side effects. The caller owns fetching the CI data
+ *     (e.g. from the `gh` API or a CI provider webhook); this adapter scores + maps.
+ *   - Applicability:
+ *       `applicable`     — a real run with ≥1 test executed
+ *       `not_applicable` — no CI run on record for this ref (e.g. no CI configured)
+ *       `unknown`        — run exists but results are incomplete/in-progress
+ *   - Score formula: pass-rate * build-weight * freshness-factor
+ *       pass-rate     = passed / (passed + failed + errored)  [0..1]
+ *       build-weight  = 0.85 if build succeeded, 0.0 if build failed (a build failure
+ *                       overrides the test pass-rate — tests that never ran are not "passing")
+ *       freshness      = 1.0 when ageSeconds < FRESH_THRESHOLD, decaying linearly to
+ *                       MIN_FRESHNESS over STALE_THRESHOLD. Beyond STALE_THRESHOLD the
+ *                       applicability is coerced to `unknown` (matches §2.6 rule 3 of the spec).
+ *   - A build failure OR 0 tests passing marks evidence ['critical'] and forces a
+ *     blocking recommendation (the aggregator uses recommendations for narrative).
+ *   - Multi-tenant: tenantId flows through unchanged (caller sets it on the EvidenceItem
+ *     via the `collector.tool` string; the full tenant stamp is the subject, not the item).
+ */
+import type { EvidenceItem } from '../schemas/confidence.schema.js';
+/**
+ * Raw CI run data the caller provides (from `gh run view --json`, provider API, etc.).
+ * Only the counts matter for scoring; everything else is for evidence strings + provenance.
+ */
+export interface CiRunInput {
+    /** ISO-8601 timestamp when the run completed. */
+    completedAt: string;
+    /** Whether the CI build step itself succeeded (compilation, lint, etc. — before tests). */
+    buildPassed: boolean;
+    /** Number of test cases that passed. */
+    testsPassed: number;
+    /** Number of test cases that failed (hard). */
+    testsFailed: number;
+    /** Number of test cases that errored (infra/setup failure, not assertion failure). */
+    testsErrored: number;
+    /**
+     * Optional: number of tests that were flaky (passed on retry). Presence lowers score
+     * slightly but doesn't fail the run — flaky tests are a warn, not a block.
+     */
+    testsFlaky?: number;
+    /**
+     * Optional: CI provider URL for the run (e.g. `https://github.com/…/actions/runs/…`).
+     * Never fabricated — omit rather than invent.
+     */
+    runUrl?: string;
+    /** Optional: CI workflow/pipeline name for the evidence string. */
+    workflowName?: string;
+    /**
+     * Optional: collector freshness budget override (seconds). Defaults to 24 h for stale.
+     */
+    staleAfterSeconds?: number;
+}
+/**
+ * Produce a `ci-results` EvidenceItem from a raw CI run summary.
+ *
+ * Deterministic and pure. Returns `not_applicable` when the run is absent, `unknown`
+ * when stale or incomplete, and `applicable` with a real score otherwise.
+ */
+export declare function ciResultsToEvidence(run: CiRunInput, collectedAt?: string): EvidenceItem;
+//# sourceMappingURL=ci-results-adapter.d.ts.map

package/dist/adapters/ci-results-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-results-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/ci-results-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,iCAAiC,CAAC;AASxF;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,WAAW,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,CA+GvF"}

package/dist/adapters/ci-results-adapter.js

@@ -0,0 +1,143 @@
+/**
+ * CI-results evidence adapter (P4 — evidence collectors).
+ *
+ * Maps a CI run summary (test pass/fail counts, build status, optional flakiness
+ * data) into an `EvidenceItem` for `computeReleaseConfidence`, using the
+ * `ci-results` source kind reserved in confidence.schema.ts.
+ *
+ * Design:
+ *   - Pure function — no I/O, no side effects. The caller owns fetching the CI data
+ *     (e.g. from the `gh` API or a CI provider webhook); this adapter scores + maps.
+ *   - Applicability:
+ *       `applicable`     — a real run with ≥1 test executed
+ *       `not_applicable` — no CI run on record for this ref (e.g. no CI configured)
+ *       `unknown`        — run exists but results are incomplete/in-progress
+ *   - Score formula: pass-rate * build-weight * freshness-factor
+ *       pass-rate     = passed / (passed + failed + errored)  [0..1]
+ *       build-weight  = 0.85 if build succeeded, 0.0 if build failed (a build failure
+ *                       overrides the test pass-rate — tests that never ran are not "passing")
+ *       freshness      = 1.0 when ageSeconds < FRESH_THRESHOLD, decaying linearly to
+ *                       MIN_FRESHNESS over STALE_THRESHOLD. Beyond STALE_THRESHOLD the
+ *                       applicability is coerced to `unknown` (matches §2.6 rule 3 of the spec).
+ *   - A build failure OR 0 tests passing marks evidence ['critical'] and forces a
+ *     blocking recommendation (the aggregator uses recommendations for narrative).
+ *   - Multi-tenant: tenantId flows through unchanged (caller sets it on the EvidenceItem
+ *     via the `collector.tool` string; the full tenant stamp is the subject, not the item).
+ */
+// Freshness constants (seconds). Configurable at call-site via CiRunInput.
+const DEFAULT_FRESH_THRESHOLD_S = 60 * 60 * 4; // 4 h
+const DEFAULT_STALE_THRESHOLD_S = 60 * 60 * 24; // 24 h
+const MIN_FRESHNESS = 0.5; // floor before we coerce to unknown
+const CI_WEIGHT = 0.10; // matches DEFAULT_WEIGHTS['ci-results'] in confidence.ts
+/**
+ * Produce a `ci-results` EvidenceItem from a raw CI run summary.
+ *
+ * Deterministic and pure. Returns `not_applicable` when the run is absent, `unknown`
+ * when stale or incomplete, and `applicable` with a real score otherwise.
+ */
+export function ciResultsToEvidence(run, collectedAt) {
+    const now = collectedAt ?? new Date().toISOString();
+    const source = 'ci-results';
+    const weight = CI_WEIGHT;
+    // Freshness computation.
+    const ageMs = Date.parse(now) - Date.parse(run.completedAt);
+    const ageS = Math.max(0, ageMs / 1000);
+    const staleThreshold = run.staleAfterSeconds ?? DEFAULT_STALE_THRESHOLD_S;
+    if (ageS > staleThreshold) {
+        return {
+            source,
+            score: 0,
+            weight,
+            applicability: 'unknown',
+            blocking: false,
+            evidence: [
+                `CI run completed at ${run.completedAt} — stale (${Math.round(ageS / 3600)}h > ${staleThreshold / 3600}h threshold).`,
+            ],
+            recommendations: ['Re-run CI against the current commit before shipping.'],
+            reason: `CI run is stale (${Math.round(ageS / 3600)}h old, threshold ${staleThreshold / 3600}h).`,
+            collectedAt: now,
+            collector: { tool: 'qulib.ci-results-adapter' },
+        };
+    }
+    const total = run.testsPassed + run.testsFailed + run.testsErrored;
+    // Build failure: tests may not even have run — score 0, blocking recommendation.
+    if (!run.buildPassed) {
+        const evidence = [`Build FAILED (${run.workflowName ?? 'CI workflow'}).`];
+        if (total > 0)
+            evidence.push(`${run.testsPassed}/${total} tests passed before build failure.`);
+        if (run.runUrl)
+            evidence.push(`Run: ${run.runUrl}`);
+        return {
+            source,
+            score: 0,
+            weight,
+            applicability: 'applicable',
+            blocking: false, // the aggregator decides blocking; we report honestly
+            evidence,
+            recommendations: ['Fix the build failure before shipping.'],
+            collectedAt: now,
+            collector: { tool: 'qulib.ci-results-adapter', inputRef: run.runUrl },
+        };
+    }
+    // No tests ran at all — cannot score honestly.
+    if (total === 0) {
+        return {
+            source,
+            score: 0,
+            weight,
+            applicability: 'unknown',
+            blocking: false,
+            evidence: [
+                `Build passed (${run.workflowName ?? 'CI workflow'}) but 0 tests executed.`,
+                ...(run.runUrl ? [`Run: ${run.runUrl}`] : []),
+            ],
+            recommendations: ['Add a test suite to CI for a meaningful confidence signal.'],
+            reason: 'Build passed but zero tests were executed — no test signal.',
+            collectedAt: now,
+            collector: { tool: 'qulib.ci-results-adapter', inputRef: run.runUrl },
+        };
+    }
+    // Normal case: compute pass-rate.
+    const passRate = run.testsPassed / total; // 0..1
+    const freshnessRatio = ageS <= DEFAULT_FRESH_THRESHOLD_S
+        ? 1.0
+        : MIN_FRESHNESS +
+            (1 - MIN_FRESHNESS) *
+                (1 - (ageS - DEFAULT_FRESH_THRESHOLD_S) / (staleThreshold - DEFAULT_FRESH_THRESHOLD_S));
+    const rawScore = passRate * freshnessRatio;
+    const score = Math.round(Math.max(0, Math.min(100, rawScore * 100)));
+    const evidence = [];
+    evidence.push(`${run.testsPassed}/${total} tests passed` +
+        (run.testsFailed > 0 ? ` (${run.testsFailed} failed)` : '') +
+        (run.testsErrored > 0 ? ` (${run.testsErrored} errored)` : '') +
+        ` — ${Math.round(passRate * 100)}% pass-rate.`);
+    if (run.workflowName)
+        evidence.push(`Workflow: ${run.workflowName}.`);
+    if (run.testsFlaky && run.testsFlaky > 0) {
+        evidence.push(`${run.testsFlaky} test(s) flaky (passed on retry).`);
+    }
+    if (run.runUrl)
+        evidence.push(`Run: ${run.runUrl}`);
+    if (freshnessRatio < 1.0) {
+        evidence.push(`Freshness factor ${freshnessRatio.toFixed(2)} applied (run age ${Math.round(ageS / 3600)}h).`);
+    }
+    const recommendations = [];
+    if (run.testsFailed > 0)
+        recommendations.push(`Fix ${run.testsFailed} failing test(s) before shipping.`);
+    if (run.testsErrored > 0)
+        recommendations.push(`Investigate ${run.testsErrored} errored test(s) (infra/setup).`);
+    if (run.testsFlaky && run.testsFlaky > 0) {
+        recommendations.push(`Stabilize ${run.testsFlaky} flaky test(s) to improve signal quality.`);
+    }
+    return {
+        source,
+        score,
+        weight,
+        applicability: 'applicable',
+        blocking: false,
+        evidence,
+        recommendations,
+        collectedAt: now,
+        collector: { tool: 'qulib.ci-results-adapter', inputRef: run.runUrl },
+    };
+}

package/dist/adapters/cypress-e2e-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cypress-e2e-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/cypress-e2e-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAY,MAAM,mCAAmC,CAAC;AA2ClG,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,WAAW,iBAAiB;IAErC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IA4BhD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}
+{"version":3,"file":"cypress-e2e-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/cypress-e2e-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAY,MAAM,mCAAmC,CAAC;AA+DlG,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,WAAW,iBAAiB;IAErC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAiChD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}

package/dist/adapters/cypress-e2e-adapter.js

@@ -38,15 +38,38 @@ function renderStep(step) {
             return `    // TODO: ${step.description}`;
     }
 }
+/**
+ * Render a recipe-specific step override for Cypress.
+ * Returns null when no override applies — falls through to renderStep.
+ */
+function renderRecipeStep(step, scenario) {
+    const tags = scenario.tags ?? [];
+    // a11y recipe: title assertion — cy.title() instead of cy.get('title')
+    if (tags.includes('recipe-a11y') && step.action === 'assert-text' && step.target === 'title') {
+        return `    cy.title().should('not.be.empty');`;
+    }
+    // a11y recipe: nav count using proper Cypress assertion
+    if (tags.includes('recipe-a11y') && step.action === 'assert-count') {
+        const t = step.target != null ? JSON.stringify(step.target) : null;
+        if (t) {
+            return `    cy.get(${t}).its('length').should('be.gte', ${parseInt(step.value ?? '1', 10)});`;
+        }
+    }
+    return null;
+}
 export class CypressE2EAdapter {
     adapterType = 'cypress-e2e';
     render(scenario) {
         const slug = slugify(scenario.title);
         const filename = `${slug}.cy.ts`;
-        const stepLines = scenario.steps.map(renderStep).join('\n');
+        const stepLines = scenario.steps
+            .map((step) => renderRecipeStep(step, scenario) ?? renderStep(step))
+            .join('\n');
+        const recipeTag = (scenario.tags ?? []).find((t) => t.startsWith('recipe-'));
+        const recipeComment = recipeTag ? `\n// recipe: ${recipeTag.replace('recipe-', '')}` : '';
         const code = [
             `// ${scenario.description}`,
-            `// qulib-generated — scenario: ${scenario.id}`,
+            `// qulib-generated — scenario: ${scenario.id}${recipeComment}`,
             ``,
             `describe(${JSON.stringify(scenario.title)}, () => {`,
             `  it(${JSON.stringify(scenario.description)}, () => {`,

package/dist/adapters/playwright-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/playwright-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAY,MAAM,mCAAmC,CAAC;AAiDlG,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,WAAW,gBAAgB;IAEpC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IA8BhD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}
+{"version":3,"file":"playwright-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/playwright-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAY,MAAM,mCAAmC,CAAC;AAqElG,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,WAAW,gBAAgB;IAEpC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAmChD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}

package/dist/adapters/playwright-adapter.js

@@ -44,15 +44,38 @@ function renderStep(step) {
             return `    // TODO: ${step.description}`;
     }
 }
+/**
+ * Render a recipe-specific step override for Playwright.
+ * Returns null when no override applies — falls through to renderStep.
+ */
+function renderRecipeStep(step, scenario) {
+    const tags = scenario.tags ?? [];
+    // a11y recipe: title assertion — page.title() instead of page.locator('title')
+    if (tags.includes('recipe-a11y') && step.action === 'assert-text' && step.target === 'title') {
+        return `    expect(await page.title()).not.toBe('');`;
+    }
+    // a11y recipe: nav count using Playwright count()
+    if (tags.includes('recipe-a11y') && step.action === 'assert-count') {
+        const t = step.target != null ? JSON.stringify(step.target) : null;
+        if (t) {
+            return `    expect(await page.locator(${t}).count()).toBeGreaterThanOrEqual(${parseInt(step.value ?? '1', 10)});`;
+        }
+    }
+    return null;
+}
 export class PlaywrightAdapter {
     adapterType = 'playwright';
     render(scenario) {
         const slug = slugify(scenario.title);
         const filename = `${slug}.spec.ts`;
-        const stepLines = scenario.steps.map(renderStep).join('\n');
+        const stepLines = scenario.steps
+            .map((step) => renderRecipeStep(step, scenario) ?? renderStep(step))
+            .join('\n');
+        const recipeTag = (scenario.tags ?? []).find((t) => t.startsWith('recipe-'));
+        const recipeComment = recipeTag ? `\n// recipe: ${recipeTag.replace('recipe-', '')}` : '';
         const code = [
             `// ${scenario.description}`,
-            `// qulib-generated — scenario: ${scenario.id}`,
+            `// qulib-generated — scenario: ${scenario.id}${recipeComment}`,
             ``,
             `import { test, expect } from '@playwright/test';`,
             ``,

package/dist/adapters/pr-metadata-adapter.d.ts

@@ -0,0 +1,75 @@
+/**
+ * PR-metadata evidence adapter (P4 — evidence collectors).
+ *
+ * Maps a pull-request review/checks payload (as returned by `gh pr view --json
+ * reviewDecision,statusCheckRollup,mergeable,number,url,additions,deletions`)
+ * into an `EvidenceItem` for `computeReleaseConfidence`, using the
+ * `deploy-metadata` source kind — the closest P3-reserved kind for
+ * PR-level ship-readiness.
+ *
+ * Design:
+ *   - Pure function. The caller fetches the `gh` JSON; this adapter scores it.
+ *   - Applicability:
+ *       `applicable`     — a PR exists and review/check state is readable
+ *       `not_applicable` — no PR for this ref (direct push, script, etc.)
+ *       `unknown`        — PR exists but checks are still pending / state ambiguous
+ *   - Score formula (0..100):
+ *       Base 60 points:  PR is open and merge-ready (no conflicts)
+ *       +20: reviewDecision === 'APPROVED'
+ *       +20: all status checks pass (statusCheckRollup every entry state === 'SUCCESS')
+ *       Deductions:
+ *         -10: any failing status check  (per failing check, capped at 20)
+ *         -15: reviewDecision === 'CHANGES_REQUESTED'
+ *   - The adapter NEVER fabricates a PR number or URL; if absent from the payload
+ *     the evidence strings omit them (WAVE-GUARDRAILS: no fabricated data).
+ */
+import type { EvidenceItem } from '../schemas/confidence.schema.js';
+/**
+ * Status-check entry shape from `gh pr view --json statusCheckRollup`.
+ * Only the fields we actually use — extra fields are harmlessly ignored.
+ */
+export interface StatusCheck {
+    /** e.g. "SUCCESS", "FAILURE", "PENDING", "SKIPPED", "NEUTRAL" */
+    state: string;
+    /** CI job/check name — optional, used for the evidence string */
+    name?: string;
+    /** Direct URL to the check — never fabricated; omit rather than invent */
+    targetUrl?: string;
+}
+/** GitHub review decision values as returned by the `gh` CLI. */
+export type ReviewDecision = 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED' | null | undefined;
+/** Mergeable state as returned by `gh pr view --json mergeable`. */
+export type MergeableState = 'MERGEABLE' | 'CONFLICTING' | 'UNKNOWN' | null | undefined;
+/**
+ * Raw PR payload the caller provides. All fields are optional — the adapter
+ * degrades gracefully when partial data is available.
+ */
+export interface PrMetadataInput {
+    /** PR number. Never fabricated — omit if absent. */
+    number?: number;
+    /** PR URL. Never fabricated — omit if absent. */
+    url?: string;
+    /** Review decision from the `gh` response. null/undefined = no review yet. */
+    reviewDecision?: ReviewDecision;
+    /** Array of status check entries (the `statusCheckRollup` field). */
+    statusCheckRollup?: StatusCheck[];
+    /**
+     * Whether the PR is currently mergeable (no conflicts).
+     * null/UNKNOWN counts as unknown-state.
+     */
+    mergeable?: MergeableState;
+    /** ISO-8601 when this payload was collected. Defaults to now. */
+    collectedAt?: string;
+    /**
+     * Set to true when there is explicitly NO PR for this ref (e.g. direct push).
+     * Produces a `not_applicable` contribution so the aggregator abstains honestly.
+     */
+    noPr?: boolean;
+}
+/**
+ * Produce a `deploy-metadata` EvidenceItem from a PR metadata payload.
+ * Returns `not_applicable` when `noPr` is true, `unknown` when checks are
+ * pending or state is ambiguous, and `applicable` with a real score otherwise.
+ */
+export declare function prMetadataToEvidence(input: PrMetadataInput, collectedAt?: string): EvidenceItem;
+//# sourceMappingURL=pr-metadata-adapter.d.ts.map

package/dist/adapters/pr-metadata-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-metadata-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/pr-metadata-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,iCAAiC,CAAC;AAIxF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iEAAiE;AACjE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC;AAErG,oEAAoE;AACpE,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,CAAC;AAExF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,WAAW,EAAE,CAAC;IAClC;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,CA+H/F"}