qfai 2.1.1 → 2.2.0

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { G as GraphProcess } from './process-C21nTvkT.cjs';
+
 type IssueSeverity = "info" | "warning" | "error";
 type IssueCategory = "canonical" | "change";
 type IssueLocation = {
@@ -93,6 +95,16 @@ type ValidationTimings = {
     uiuxBudgetMs: number;
     htmlMockMs: number;
     htmlMockBudgetMs: number;
+    /**
+     * What each validator of the UI/UX group took, slowest first. The validators run side by side
+     * on one event loop, so each time includes waiting for the others: the parts overlap, do not
+     * add up to `uiuxMs`, and can credit a fast validator with another's time. They say where to
+     * look, not how the time divides.
+     */
+    uiuxParts: readonly {
+        name: string;
+        ms: number;
+    }[];
 };
 type ValidationResult = {
     toolVersion: string;
@@ -129,42 +141,14 @@ type ValidationResult = {
     timings?: ValidationTimings;
 };
 
-type RenderEvidenceConfig = {
-    enabled?: boolean;
-    viewports?: string[];
-    out?: string;
-    baseUrl?: string;
-    failOpen?: boolean;
-};
-
 type FailOn = "never" | "warning" | "error";
 type OutputFormat = "text" | "github";
-type TraceabilitySeverity = "warning" | "error";
-/**
- * The value set of the retired orphanContractsPolicy. Compatibility fields
- * annotate their type with this one: referencing the public alias would trigger
- * `@typescript-eslint/no-deprecated` and force a lint-suppression comment. Delete
- * this internal type when the compatibility acceptance ends.
- */
-type RetiredOrphanContractsPolicy = "error" | "warning" | "allow";
-/**
- * @deprecated validation.traceability.orphanContractsPolicy is retired.
- * No check reads it, so setting it changes nothing. It stays for the
- * compatibility period only, so existing TypeScript consumers that import it
- * keep type-checking.
- */
-type OrphanContractsPolicy = RetiredOrphanContractsPolicy;
 type QfaiPaths = {
     contractsDir: string;
     specsDir: string;
     discussionDir: string;
     outDir: string;
     skillsDir: string;
-    /**
-     * @deprecated Use paths.skillsDir.
-     * It is still read for compatibility and is not used on the main validation path.
-     */
-    promptsDir: string;
     srcDir: string;
     testsDir: string;
     /**
@@ -178,6 +162,10 @@ type QfaiPaths = {
      */
     migrationsDir?: string;
 };
+type QfaiForbiddenIdentifier = {
+    sha256: string;
+    byteLength: number;
+};
 type QfaiValidationConfig = {
     failOn: FailOn;
     /**
@@ -186,6 +174,8 @@ type QfaiValidationConfig = {
      * (QFAI-STORY-016). Unset means no term is checked.
      */
     staleTerms?: string[];
+    /** Hash-only identifiers checked against tracked names and current file bytes. */
+    forbiddenIdentifiers?: QfaiForbiddenIdentifier[];
     testStrategy: {
         /**
          * When true (default), `qfai validate` reports the silent-placeholder
@@ -195,42 +185,10 @@ type QfaiValidationConfig = {
          * Set to false to opt out while migrating an existing project.
          */
         forbidTestTodoStubs: boolean;
-        /**
-         * @deprecated A dead knob: no validation reads it, so setting it to true
-         * raises no diagnostic. It is already removed from the shipped
-         * `qfai.config.yaml` and will be removed from the type in the next major
-         * release. As with paths.promptsDir, the default and the parsing stay as
-         * they were until then (this is a public type, so existing TypeScript
-         * consumers can keep referring to it as a `boolean`).
-         */
-        requireLayerTags: boolean;
-        /**
-         * @deprecated Treated the same as `testStrategy.requireLayerTags`.
-         */
-        requireSizeTags: boolean;
     };
     traceability: {
         testFileGlobs: string[];
         testFileExcludeGlobs: string[];
-        /**
-         * @deprecated Retired. No check reads it, so setting it changes nothing,
-         * and loading it reports QFAI-CFG-001 as an error. It stays as an optional
-         * field for the compatibility period only, so existing config object
-         * literals keep type-checking.
-         */
-        brMustHaveSc?: boolean;
-        /**
-         * @deprecated Retired. The finding for a missing SC test reference has a
-         * fixed severity, so this value is not read. It stays as an optional field
-         * for the compatibility period only.
-         */
-        scNoTestSeverity?: TraceabilitySeverity;
-        /**
-         * @deprecated Retired. The orphan-contract finding no longer exists, so
-         * this value is not read. It stays as an optional field for the
-         * compatibility period only.
-         */
-        orphanContractsPolicy?: RetiredOrphanContractsPolicy;
     };
 };
 type QfaiOutputConfig = {
@@ -272,19 +230,15 @@ type QfaiUiuxConfig = {
      * key declares nothing.
      */
     surfacePaths?: string[];
-    renderEvidence?: RenderEvidenceConfig;
     audit?: QfaiUiuxAuditConfig;
 };
 type QfaiPrototypingExecutionConfig = {
     targetUrl?: string | null;
     /**
-     * Browser tool handed to the AI evaluator sub-agent.
-     *
-     * Only `"playwright"` is accepted. `"playwright-cli"` is retired:
-     * `normalizePrototypingExecution` rejects the value, and the doctor probe
-     * reports `D-DEPRECATED-PROBE` at `error`.
+     * Browser tool handed to the AI evaluator sub-agent. Only `"playwright"` is
+     * accepted.
      */
-    browserTool: "playwright" | "playwright-cli";
+    browserTool: "playwright";
 };
 type QfaiPrototypingConfig = {
     execution?: QfaiPrototypingExecutionConfig;
@@ -404,449 +358,20 @@ declare function resolvePath(root: string, config: QfaiConfig, key: ConfigPathKe
 declare function readRejectedPrimaryUiContract(loaded: ConfigLoadResult): string | undefined;
 
 type AtddTestKind = "e2e" | "api" | "integration";
-type AtddUnknownRefKind = "us" | "tc" | "conApi" | "conDb";
-type AtddUnknownRef = {
-    file: string;
-    token: string;
-    kind: AtddUnknownRefKind;
-};
-type AtddForbiddenRef = {
-    file: string;
-    ids: string[];
-};
-type AtddSpecRefs = Map<string, Map<string, Set<string>>>;
-type AtddTraceabilityScan = {
-    globs: string[];
-    /**
-     * Files collected, which is also the number an acceptance layer owns.
-     *
-     * The collector drops a file in no acceptance layer before it is counted,
-     * so this is the count the coverage rules are computed from rather than a
-     * match total a reader has to discount.
-     */
-    matchedFileCount: number;
-    truncated: boolean;
-    limit: number;
-    /**
-     * The selecting patterns whose files could not all be read, each with the
-     * reason. The others were still scanned, so a reference missing from the
-     * tests only these select is not evidence those tests hold none.
-     */
-    unreadable: string[];
-    /**
-     * Directories the scan could not read and read past, in POSIX form: relative
-     * to the repository, or absolute where a scanned root lies outside it. The
-     * rest of each pattern reaching one was still read, but no test inside the
-     * directory is counted.
-     */
-    unreadableDirectories: string[];
-};
-/**
- * Obligation refs bucketed by ID kind.
- *
- * Shared by the two partitions the coverage result reports: `missing` (owed and
- * referenced nowhere) and `coveredByCarrierOnly` (owed, referenced, but from no
- * carrier that declares a runnable test).
- */
-type AtddObligationRefs = {
-    us: string[];
-    tc: string[];
-    conApi: string[];
-    conDb: string[];
-};
-type AtddTraceabilityMissing = AtddObligationRefs;
-type AtddCodeTraceabilityResult = {
-    specsRoot: string;
-    /**
-     * The configured tests directory, resolved.
-     *
-     * The bound on the per-spec owner scan. Test paths are absolute, so a
-     * checkout that itself lives under `/srv/integration/spec-0002/repo` has an
-     * ancestor pair that reads exactly like the canonical layout, and a flat
-     * `tests/integration/a.test.ts` inside it was attributed to `0002`.
-     */
-    testsRoot: string;
-    contractsApiRoot: string;
-    /**
-     * Spec number -> the directory `collectSpecEntries` enumerated for it.
-     *
-     * Two questions, one map. **Existence** is not the same as `specUsIds.has(n)`:
-     * a spec created moments ago has a directory and empty catalogues, and scope
-     * logic that asks the id maps treats it as nonexistent — so a typo naming it
-     * is handled as repo-wide when that spec's own gate would in fact own it.
-     * **Its path** is the enumerated one, never `spec-${n}` rebuilt from the
-     * number: on a case-sensitive filesystem a `SPEC-0001/` directory is valid and
-     * kept verbatim by `listSpecDirs`, and a synthesised lower-case path would
-     * send the CLI report and the GitHub annotation at a file that is not there.
-     */
-    declaredSpecDirs: Map<string, string>;
-    /**
-     * Scanned test file, normalised as the findings name it -> the spec whose
-     * `<layer>/spec-NNNN/` directory holds it, at `paths.testsDir` or at a
-     * package's own test root. A file in no such directory has no entry.
-     */
-    testFileSpecOwners: Map<string, string>;
-    /**
-     * Every declared `US-*`, active and deferred alike — the same
-     * declared-not-owed distinction the contract sets draw. A deferred story is
-     * still a known id, so an E2E test written ahead of its slice must not become
-     * a `QFAI-ATDD-101` unknown reference.
-     */
-    specUsIds: Map<string, Set<string>>;
-    /**
-     * `US-*` refs excluded from the `QFAI-ATDD-111` obligation because their
-     * story declares `- x-qfai-status: planned`, formatted as `SPEC-NNNN:US-…`.
-     * Reported at `info` (`QFAI-ATDD-118`) so the deferral stays visible rather
-     * than silently shrinking the gate — the same treatment `QFAI-ATDD-114` and
-     * `-116` give the two contract kinds.
-     *
-     * Restricted to specs that owe `QFAI-ATDD-111` at all: under surface typing a
-     * non-UI-bearing spec's stories are already outside the E2E gate, so nothing
-     * there is deferred by the marker.
-     */
-    deferredUsIds: string[];
-    specTcIds: Map<string, Set<string>>;
-    /**
-     * Every declared `API-NNNN`, active and deferred alike. This is the public
-     * meaning the field has always had — adding `x-qfai-status: planned` defers
-     * the test obligation, it does not un-declare the contract, so an external
-     * consumer using this set for "is this ID declared?" must keep seeing it.
-     */
-    apiContractIds: Set<string>;
-    /** The subset that carries the `QFAI-ATDD-113` obligation. */
-    activeApiContractIds: Set<string>;
-    /**
-     * `API-NNNN` IDs excluded from the `QFAI-ATDD-113` obligation because their
-     * contract declares `x-qfai-status: planned`. Reported as `info` so the
-     * deferral stays visible instead of silently shrinking the gate.
-     */
-    deferredApiContractIds: Set<string>;
-    contractsDbRoot: string;
-    /** Every declared `DB-NNNN`, active and deferred alike. */
-    dbContractIds: Set<string>;
-    /** The subset that carries the `QFAI-ATDD-115` obligation. */
-    activeDbContractIds: Set<string>;
-    /** `DB-NNNN` IDs deferred by `-- x-qfai-status: planned`; reported at `info`. */
-    deferredDbContractIds: Set<string>;
-    refs: {
-        us: AtddSpecRefs;
-        tc: AtddSpecRefs;
-        api: Map<string, Set<string>>;
-        /**
-         * `DB-NNNN` references found in integration tests. L3 Integration is the
-         * layer whose declared scope is real-infrastructure integration including
-         * the database, so it is the one that can actually exercise a DB contract.
-         */
-        db: Map<string, Set<string>>;
-    };
-    unknown: AtddUnknownRef[];
-    forbidden: {
-        tcInApi: AtddForbiddenRef[];
-        tcInE2e: AtddForbiddenRef[];
-        /** TC annotated under integration although its declared Level routes elsewhere. */
-        tcInIntegration: AtddForbiddenRef[];
-    };
-    missing: AtddTraceabilityMissing;
-    /**
-     * Owed obligations whose every carrier declares no test a runner collects.
-     *
-     * Satisfaction is a text match, and the scan deliberately reads past test
-     * code so a Gherkin feature or a markdown ledger can carry annotations. The
-     * consequence is that a bullet list of IDs discharges `QFAI-ATDD-111` /
-     * `-112` / `-113` / `-115` exactly as an executable acceptance test does, and
-     * `missing: []` cannot tell the two apart. Reported at `info`
-     * (`QFAI-ATDD-119`) and persisted into the summary artifact for the same
-     * reason `unitComponentTcIds` is: a coverage scan must never leave "covered
-     * by a test" and "covered by an ID written down" indistinguishable.
-     *
-     * Membership is decided per carrier by {@link hasRunnableTestStructure}, not
-     * by extension: markdown never qualifies, a `.feature` with a `Scenario:`
-     * does, and a `.test.ts` holding only an annotation comment does not — so
-     * renaming the ledger cannot clear the obligation. Skip state is out of
-     * scope, so this asserts a test is *declared*, never that it is enabled.
-     *
-     * Empty whenever `scan.truncated` is set or `scan.unreadable` or
-     * `scan.unreadableDirectories` is not empty: an executable carrier may sit
-     * past the file limit or in what was not read, so the claim is unproven and
-     * suppressed rather than guessed.
-     */
-    coveredByCarrierOnly: AtddObligationRefs;
-    /**
-     * Formatted missing TC ref -> the test kind its declared `Level` routes to.
-     * Lets the CLI phrase `QFAI-ATDD-112` (message, `suggested_action`, report)
-     * per declared layer instead of naming `tests/integration/**` for every TC.
-     */
-    missingTcHomes: Map<string, AtddTestKind>;
-    /**
-     * `TC-*` refs excluded from the `QFAI-ATDD-112` obligation because their
-     * declared `Level` is Unit or Component. Reported at `info`
-     * (`QFAI-ATDD-117`) so the exclusion is visible rather than silent — the
-     * shape a coverage scan must never take, since "nothing owed" and "nothing
-     * scanned" are otherwise indistinguishable. No validate rule demands a test
-     * for them.
-     */
-    unitComponentTcIds: string[];
-    /**
-     * `TC-*` refs declaring a `Level` of L4/API or L5/E2E.
-     *
-     * `catalog/test-layers.md` states that a `TC-*` row's `Level` stays within
-     * L1-L3: L4's goal is a `API-NNNN` and L5's is a `US-*`, so an oracle that
-     * derives to either means the obligation is filed under the wrong ID type —
-     * not that the test case is an L4/L5 test.
-     *
-     * The routing table sends such a row to `tests/api/**` or `tests/e2e/**`
-     * rather than rejecting it, so that the row is reported once by the rule
-     * naming the real cause (`QFAI-ATDD-128`) instead of twice as "uncovered in
-     * integration" and "forbidden in api".
-     *
-     * Every declared row, not only the ones missing an annotation: the defect is
-     * the row's own `Level`, and covering it changes nothing about that.
-     */
-    misfiledLevelTcIds: string[];
-    /**
-     * Carrier files whose suite is bound through a variable, so nothing static —
-     * including this scan — can say whether their tests run.
-     *
-     * Reported rather than counted, for the same reason `unitComponentTcIds` is:
-     * the coverage gate's evidence here is a string in a file, and "nothing owed"
-     * must not look like "nothing checked".
-     */
-    computedSuiteCarriers: string[];
-    /**
-     * `TC-*` refs a status marker in their own block suspends, each with the
-     * status and — for `external` — where the obligation is really verified.
-     *
-     * Reported at `info` for the same reason `QFAI-ATDD-118` reports a deferred
-     * story: an exit nobody can see is one nobody reviews.
-     */
-    deferredTcIds: DeferredTc[];
-    /**
-     * `TC-*` refs that claim `external` and name no verifier.
-     *
-     * They keep their obligation. The marker is not a way to say "not here": it
-     * is a way to say where the obligation is met instead, and without that it
-     * says nothing a reader can act on.
-     */
-    unsupportedTcStatusIds: string[];
-    /** Test files outside the scanned roots; surfaced instead of dropped. */
-    skippedTestFiles: string[];
-    scan: AtddTraceabilityScan;
-};
 /** Test directory each `AtddTestKind` owns, for user-facing messages. */
 declare const ATDD_TEST_KIND_DIRS: Record<AtddTestKind, string>;
 /**
  * The same map rendered against the project's configured `paths.testsDir`.
  *
  * The scan already follows `testsDir`, so a project that renamed it to e.g.
- * `spec-tests` would otherwise be told by `QFAI-ATDD-112` to annotate
- * `tests/api/**` — a directory the scan never reads, leaving the finding
- * unclearable. A root-level layout (`testsDir: "."`) is the same trap in the
- * other direction: the scan reads `api/**` at the repository root, so the
+ * `acceptance` would otherwise be told to annotate `tests/api/**` — a directory
+ * the scan never reads. A root-level layout (`testsDir: "."`) is the same trap in
+ * the other direction: the scan reads `api/**` at the repository root, so the
  * `tests/` segment must be dropped rather than kept.
  * {@link ATDD_TEST_KIND_DIRS} stays as the default-shaped fallback for callers
  * with no config in hand.
  */
 declare function atddTestKindDirs(testsDirRelative: string): Record<AtddTestKind, string>;
-declare function evaluateAtddCodeTraceability(root: string, config: QfaiConfig): Promise<AtddCodeTraceabilityResult>;
-/**
- * Reads the declared `Level` of every TC in `06_Test-Cases.md` so the TC
- * obligation can be routed by declared layer instead of being hard-pinned to
- * `tests/integration/**`.
- *
- * Both shipped shapes are read, matching `parseTestCases` in
- * `core/atdd/scaffold.ts`: the heading form (`## TC-NNNN` plus `- Level: L4`
- * meta lines) and the table form. Heading form wins on duplicates; within
- * either form the first declaration wins. Every `TC-ID` table is scanned, not
- * just the first — a spec may split its catalogue across several tables, and
- * only scanning the first silently dropped the later tables' layers.
- */
-declare function collectTcLevels(rawTcText: string): Map<string, string>;
-declare function collectDeclaredTcIds(rawTcText: string): Set<string>;
-/**
- * Every heading-form TC id, whether or not the block declares a `Level`.
- *
- * The level collector yields a pair only when a `- Level:` line follows the
- * heading, so it cannot answer "does this spec declare this TC?" — a
- * level-less TC is still declared. {@link collectDeclaredTcIds} reads this
- * for that reason.
- */
-declare function collectHeadingTcIdsFrom(rawTcText: string): string[];
-/**
- * Where a declared `Level` routes its ATDD annotation obligation, or `null`
- * when it owes none at all (Unit / Component).
- *
- * **The single answer to "what does this `Level` mean for ATDD".** One
- * question answered in several places is several chances for the routing rule
- * and the exclusion rule to disagree about the same cell.
- *
- * `undefined` means the spec declares no `Level` for the TC (no column, no
- * row): that is not "no obligation", it is the default home.
- */
-declare function resolveAtddHomeKind(level: string | undefined): AtddTestKind | null;
-/**
- * Splits the declared `US-*` ids into those that still owe an E2E reference and
- * those a `- x-qfai-status: planned` marker defers.
- *
- * The deferred half is returned as formatted `SPEC-NNNN:US-…` refs — the shape
- * `narrowToScope` filters and the CLI prints — so a `--spec` run reports its own
- * deferrals only, exactly as it does for `QFAI-ATDD-117`.
- *
- * Only a spec inside `usObligationScope` can defer anything. A non-UI-bearing
- * spec's stories are already outside `QFAI-ATDD-111` under surface typing, so
- * reporting them at `QFAI-ATDD-118` would claim an obligation was suspended
- * that never existed — and its remediation would tell the implementer to add an
- * E2E annotation there, the annotation-only E2E that the surface-scope rule
- * exists to prevent.
- */
-/** A suspended test case, carried with what suspended it. */
-type DeferredTc = {
-    /** `SPEC-NNNN:TC-NNNN`, the form every ref list here uses. */
-    ref: string;
-    status: TcVerificationStatus;
-    /** Where the obligation is verified. Present whenever `status` is `external`. */
-    verifiedBy?: string;
-};
-declare const PLANNED_CONTRACT_KEY = "x-qfai-status";
-/**
- * True when the contract declares itself not yet implemented.
- *
- * `/qfai-sdd` authors contracts in Phase 0 (Contracts-first) but slices them in
- * Phase 2, so between the second contract and the last slice every declared
- * `API-NNNN` would otherwise be a `QFAI-ATDD-113` error. The marker makes the
- * deferral explicit and reviewable in the contract itself.
- *
- * The marker is only honoured at the **document root**. A text scan that
- * accepted any indentation would let an `x-qfai-status: planned` on a single
- * OpenAPI operation defer the whole file, silently dropping the API-test
- * obligation for every other `API-NNNN` it declares. The document is therefore
- * parsed (YAML is a superset of JSON, so both contract formats go through the
- * same path) and only a top-level key counts. An unparseable document falls
- * back to a column-0 text match, which cannot see a nested key either.
- */
-declare function isPlannedApiContract(text: string): boolean;
-/**
- * What a test case says about where it is verified.
- *
- * `planned` is the `US-*` deferral, one layer down: the test is not written
- * yet, the obligation is suspended, and the marker keeps it visible rather than
- * silent.
- *
- * `external` is the state the story marker has no counterpart for. Some
- * acceptance criteria are true of the deployment rather than of the code — a
- * TLS floor, an HTTPS redirect terminated by the platform — and no layer the
- * annotation gate routes to can observe them. Before this, every exit was
- * closed: annotating anyway makes the gate green over a test that checks
- * something else, a waiver may not cover an error, and retiring the row walks
- * up the coverage rules until the requirement itself is deleted.
- */
-type TcVerificationStatus = "planned" | "external";
-/** A test case's declared status, with the pointer `external` requires. */
-type TcStatusDeclaration = {
-    status: TcVerificationStatus;
-    /** Where the obligation is verified. Required for `external`. */
-    verifiedBy?: string;
-};
-/** The key an `external` test case names its real verifier with. */
-declare const TC_VERIFIED_BY_KEY = "x-qfai-verified-by";
-/**
- * Status markers declared in `06_Test-Cases.md`, by test case id.
- *
- * **Read from a `##`-or-deeper `TC-NNNN` block only, never from the table.**
- * That is the design, not a limitation. The field evidence behind this marker
- * is that two test cases looked identical from the spec's side — same level,
- * same note calling them deployment-bound — and only one of them actually was;
- * a marker cheap enough to write in a table cell would have been applied to
- * both, and the one that was observable in-process would have lost its only
- * real test.
- *
- * So deferring a test case costs a block of its own. The author has to lift the
- * row out of the table, write the status, and — for `external` — name where the
- * obligation is really checked. That is the price of the exit, and it is meant
- * to be paid deliberately.
- *
- * Fenced samples and HTML comments are masked first, on the same terms as
- * {@link collectTcLevels}: a block in a format example must not defer a real
- * test case.
- */
-declare function collectTcStatuses(rawTcText: string): Map<string, TcStatusDeclaration>;
-/**
- * Whether a declaration actually suspends the annotation obligation.
- *
- * `external` without a pointer does not. The pointer is the whole cost of the
- * marker: without it the line says only "not here", which is the blanket
- * silencer this exit exists to avoid being. Such a test case keeps its
- * obligation and is reported, so the marker cannot be written and forgotten.
- */
-declare function suspendsObligation(declaration: TcStatusDeclaration): boolean;
-/**
- * The `US-*` ids a spec pack defers from the `QFAI-ATDD-111` obligation.
- *
- * A story whose acceptance cannot be observed at E2E in this slice had no
- * in-band way to say so: `API-NNNN` and `DB-NNNN` both defer with
- * `x-qfai-status: planned`, while a `US-*` could only be left uncovered (a hard
- * `QFAI-ATDD-111` error), covered by a test asserting nothing, or erased by
- * declaring the whole spec non-user-facing. This is the per-story counterpart.
- *
- * Fenced samples and HTML comments are masked first, on the same terms as
- * {@link collectTcLevels}: an illustrative block showing the marker must not
- * silently drop a real story's obligation.
- *
- * A block opens at either shape {@link collectDeclaredUsIds} declares an id from — a
- * `##`-or-deeper heading ({@link US_HEADING_RE}) or a catalog list entry
- * ({@link US_LIST_ITEM_RE}) — and closes at the next opener or any heading, so
- * every declared story can carry the marker and none inherits a neighbour's.
- *
- * A catalog entry closes on its Markdown item boundary as well: its block ends
- * at the first non-blank line that does not reach the entry's *content* column —
- * the column its marker plus the whitespace after it ends at, which is where
- * Markdown puts the item's own children. Without that, prose or a blank line
- * after `- US-0001: …` left the entry open to the next heading, and a
- * document-level `- x-qfai-status: planned` written well outside it deferred
- * US-0001 — the very leak the document-root rule closes on the heading side.
- *
- * Comparing against the *marker* column instead would leave a narrower version
- * of the same leak: under a column-0 `- US-0001: …` a one-space-indented
- * ` - x-qfai-status: planned` clears the marker column while falling short of
- * the two columns a child needs, so Markdown reads it as a separate list item
- * and the entry must already be closed by then. The marker has to sit *inside*
- * the entry, indented to its content.
- */
-declare function collectPlannedUsIds(rawUsText: string): Set<string>;
-/**
- * The `US-*` ids a spec pack declares, read from the entries that declare them.
- *
- * An entry is a `##`-or-deeper heading ({@link US_HEADING_RE}) or a catalog
- * list item ({@link US_LIST_ITEM_RE}) — the two shapes
- * {@link collectPlannedUsIds} already opens a block at. A mention anywhere else
- * is prose about a story, not a declaration of one.
- *
- * What this replaces took the union of those entries and every loose
- * `US-NNNN` in the file, so any sentence naming an id declared it. A note
- * reserving a deleted story's id — the id is retired, do not reuse it — made
- * the story live again, and `QFAI-ATDD-111` then demanded an E2E reference
- * for something with no entry, no acceptance criteria and no behaviour. The
- * three ways out all cost something: an annotation with nothing behind it, the
- * note hidden in an HTML comment where the people it warns cannot read it, or
- * the id spelled so the scan misses it.
- *
- * This is the rule {@link collectDeclaredTcIds} already applies one document
- * over, for the same reason: an id read from somewhere other than its
- * declaration carries an obligation nobody wrote.
- *
- * Fenced samples and HTML comments are masked first, so an illustrative block
- * showing the entry shape declares nothing.
- */
-declare function collectDeclaredUsIds(rawUsText: string): Set<string>;
-/**
- * True when a DB contract declares itself not yet implemented.
- *
- * The counterpart of `isPlannedApiContract`, and deliberately a different rule:
- * the API marker counts at the document root only, while this one counts on any
- * line of the file. Exported so the shipped estimator procedure, which has to
- * describe both forms, can be pinned against the behaviour rather than restate
- * it and drift.
- */
-declare function isPlannedDbContract(text: string): boolean;
 /**
  * The extensions a set of globs names, and whether any of them was too large to
  * write out.
@@ -905,11 +430,6 @@ type TestLayerRoots = {
 /** Shared directory crosswalk for acceptance checks and migration. */
 declare function createTestLayerRoots(root: string, config: QfaiConfig): TestLayerRoots;
 declare function resolveTestKind(filePath: string, roots: TestLayerRoots): AtddTestKind | null;
-/**
- * The owning spec of a test file, read as {@link layerSpecNumber} reads it, for
- * callers outside the scan. `null` for a file in no acceptance layer.
- */
-declare function atddTestOwnerProbe(root: string, config: QfaiConfig): (absolutePath: string) => string | null;
 /**
  * Whether a directory carries a package manifest, memoised per scan.
  *
@@ -1017,22 +537,6 @@ declare function extractAcSpecNumber(acId: string): string | null;
 declare function extractCaseSpecNumber(caseId: string): string | null;
 declare function extractScSpecNumber(scId: string): string | null;
 
-declare const CANONICAL_PROTOTYPING_SURFACES: readonly ["web", "mobile", "desktop", "cli", "mixed"];
-type CanonicalPrototypingSurface = (typeof CANONICAL_PROTOTYPING_SURFACES)[number];
-
-/**
- * Prototyping surface helpers.
- *
- * Kept here: surface-type helpers and a `playwright-cli` constant used by
- * the capture wiring.
- */
-
-declare const PROTOTYPING_SUPPORTED_SURFACES: readonly ["web", "mobile", "desktop", "mixed"];
-type PrototypingSurface = CanonicalPrototypingSurface;
-type PrototypingBrowserTool = "playwright-cli";
-declare function isValidPrototypingSurface(value: unknown): value is PrototypingSurface;
-declare function isSupportedPrototypingSurface(surface: string): surface is PrototypingSurface;
-
 /**
  * The input source preflight selected: the discussion pack, or an imported
  * specification the caller names with `importPath`. An explicit user
@@ -1113,6 +617,17 @@ type ValidationOptions = {
     flowIds?: readonly string[];
 };
 declare function validateProject(root: string, configResult?: ConfigLoadResult, options?: ValidationOptions): Promise<ValidationResult>;
+/**
+ * The parts of the UI/UX group, slowest first. The html-mock part leaves out the one-off load of
+ * its parser, as the group's own time does.
+ */
+declare function orderUiuxParts(parts: readonly {
+    name: string;
+    ms: number;
+}[], htmlMockLoadMs: number): {
+    name: string;
+    ms: number;
+}[];
 /**
  * Count findings by severity, skipping suppressed ones. `counts` is the SSOT
  * every gate reads, so anything that rebuilds a `ValidationResult` from an
@@ -1224,6 +739,44 @@ declare function classifyAgainstDeclaration(declaringDir: string, packageDir: st
  * statement but still a statement.
  */
 declare function findDeclaringDir(root: string): Promise<string | null>;
+/**
+ * The range the nearest `package.json` declaring qfai gives it, or `null` when
+ * no manifest at or above `root` declares it with a text range.
+ *
+ * Read from the manifest {@link findDeclaringDir} stops at, so the range and the
+ * directory it is compared against are one declaration.
+ */
+declare function readDeclaredQfaiRange(root: string): Promise<string | null>;
+/**
+ * The lowest version a dependency range admits, as `x.y.z`, or `null` when the
+ * range does not state one this reads.
+ *
+ * Only the forms a project writes for a pinned dependency are read: an exact
+ * version, and a caret, tilde or `>=` range, each optionally followed by more
+ * comparators (`>=2.1.1 <3`). A tag (`latest`), a wildcard (`2.x`), an
+ * alternative (`||`), a protocol (`workspace:`, `file:`, `github:`) and a
+ * partial version (`^2.1`) answer `null`, so nothing is compared against them.
+ */
+declare function lowestVersionOfRange(range: string): string | null;
+/** Whether `version` is strictly older than `other`; `false` where either is unreadable. */
+declare function isOlderVersion(version: string, other: string): boolean;
+/** An installed qfai that is older than the version the project declares. */
+type InstalledOlderThanDeclared = {
+    readonly installed: string;
+    readonly declaredRange: string;
+    readonly declaredLowest: string;
+};
+/**
+ * Whether the running qfai is older than the lowest version this project's
+ * dependency declaration admits.
+ *
+ * The declaration is the only record of "the qfai this tree was written for"
+ * that a project keeps: the files `qfai init` writes carry no version. An
+ * installed copy below that floor is the state a lockfile that moved after the
+ * last install leaves, and every rule whose input is a generated file can then
+ * disagree with the tree for a reason that is not in the tree.
+ */
+declare function compareInstalledToDeclared(installed: string, declaredRange: string | null): InstalledOlderThanDeclared | null;
 /**
  * Whether `packageDir` is an installed copy resolved from outside `root`.
  *
@@ -1287,6 +840,9 @@ declare function validateContracts(root: string, config: QfaiConfig): Promise<Is
 declare function validateUiContractParse(root: string, config: QfaiConfig): Promise<Issue[]>;
 declare function lintSql(text: string, file: string): Issue[];
 
+declare const CANONICAL_PROTOTYPING_SURFACES: readonly ["web", "mobile", "desktop", "cli", "mixed"];
+type CanonicalPrototypingSurface = (typeof CANONICAL_PROTOTYPING_SURFACES)[number];
+
 type SurfaceType = CanonicalPrototypingSurface | "non-ui";
 declare const DISCUSSION_UI_BEARING_SURFACES: Set<SurfaceType>;
 declare const DISCUSSION_NON_UI_SURFACES: Set<SurfaceType>;
@@ -1295,137 +851,6 @@ declare function isDiscussionUiBearingSurfaceType(surface: SurfaceType): boolean
 declare function isNonUiDiscussionSurface(surface: SurfaceType): boolean;
 declare function requiresVisualBrowserEvidence(surface: SurfaceType): boolean;
 
-type BrowserQaPhase = "smoke" | "interaction" | "visual" | "accessibility";
-declare const BROWSER_QA_PHASES: readonly BrowserQaPhase[];
-type BrowserQaPhaseStatus = "passed" | "executed" | "failed" | "skipped";
-type BrowserQaFindingSeverity = "info" | "warn" | "warning" | "error";
-interface BrowserQaFinding {
-    phase: BrowserQaPhase;
-    severity: BrowserQaFindingSeverity;
-    summary: string;
-    detail: string;
-    screen_id?: string;
-    selector?: string;
-    evidence_refs: string[];
-    repair_suggestions: string[];
-    category?: BrowserQaPhase;
-    message?: string;
-    route?: string;
-    repair_hint?: string;
-}
-type BrowserQaScreenContractRef = {
-    screen_id: string;
-    route?: string;
-    primary_tasks?: string[];
-};
-type BrowserQaPhaseResult = {
-    phase: BrowserQaPhase;
-    status: BrowserQaPhaseStatus;
-    findings: BrowserQaFinding[];
-    repair_suggestions: string[];
-    evidence_refs: string[];
-    checks_performed: string[];
-    skippedReason?: string;
-    screen_id?: string;
-    route?: string;
-};
-type BrowserQaInput = {
-    htmlContent?: string;
-    targetUrl?: string;
-    routes?: string[];
-    surface: SurfaceType;
-    required?: boolean;
-    executionSource?: "html" | "url" | "none";
-    screenContracts?: BrowserQaScreenContractRef[];
-};
-type BrowserQaRunResult = {
-    phases: BrowserQaPhaseResult[];
-    provider: string;
-    timestamp: string;
-};
-type BrowserQaSummary = {
-    providerId: string;
-    phases: Record<BrowserQaPhase, {
-        status: BrowserQaPhaseStatus;
-        findingsCount: number;
-        checksCount: number;
-        passed?: number;
-        failed?: number;
-    }>;
-    totalFindings: number;
-    totalRepairs: number;
-    skippedReasons: string[];
-};
-interface BrowserQaProvider {
-    providerId: string;
-    canRun(surface: SurfaceType): boolean;
-    runSmoke(input: BrowserQaInput): Promise<BrowserQaPhaseResult>;
-    runInteraction(input: BrowserQaInput): Promise<BrowserQaPhaseResult>;
-    runVisual(input: BrowserQaInput): Promise<BrowserQaPhaseResult>;
-    runAccessibility(input: BrowserQaInput): Promise<BrowserQaPhaseResult>;
-}
-
-declare function runBrowserQaOrchestrated(input: BrowserQaInput, provider?: BrowserQaProvider): Promise<BrowserQaRunResult>;
-declare function summarizeBrowserQaResult(result: BrowserQaRunResult): BrowserQaSummary;
-
-/**
- * Render evidence types
- *
- * Canonical types for the render evidence capture pipeline.
- */
-type RenderCaptureTarget = {
-    targetId: string;
-    route?: string;
-    descriptor?: string;
-    viewport: string;
-    width?: number;
-    height?: number;
-};
-type RenderCaptureAdapter = {
-    captureScreenshot(target: RenderCaptureTarget, outputDir: string): Promise<string>;
-    captureHtml?(target: RenderCaptureTarget, outputDir: string): Promise<string>;
-};
-type RenderEvidenceEntryResult = {
-    capture_id: string;
-    target: string;
-    status: "captured" | "skipped" | "failed";
-    screenshot_path?: string;
-    html_path?: string;
-    viewport: string;
-    reason?: string;
-};
-type RenderRunnerResult = {
-    entries: RenderEvidenceEntryResult[];
-    filesWritten: string[];
-    surface?: string;
-    mode?: string;
-    generatedAt?: string;
-    coverageSummary?: {
-        total: number;
-        captured: number;
-        failed: number;
-        skipped: number;
-    };
-};
-
-/**
- * Render runner
- *
- * Executes render capture for a list of targets, producing truthful
- * evidence entries. No placeholder paths are emitted.
- */
-
-/**
- * Run render capture for all targets.
- *
- * - adapter present + capture succeeds → `captured` with real file paths
- * - adapter present + capture throws → `failed` with reason
- * - adapter absent → `skipped` with reason
- */
-declare function runRenderCapture(targets: RenderCaptureTarget[], outputDir: string, adapter?: RenderCaptureAdapter, options?: {
-    required?: boolean;
-}): Promise<RenderRunnerResult>;
-
 declare const ARCHETYPES: readonly ["minimal", "bold", "corporate", "playful", "organic", "tech", "elegant", "casual"];
 type Archetype = (typeof ARCHETYPES)[number];
 declare const COLOR_KEYS: readonly ["primary", "secondary", "accent", "surface", "surface_muted", "text", "text_muted", "danger", "warning", "success", "border", "overlay"];
@@ -1535,12 +960,8 @@ declare const DESIGN_MD_SAMPLE_MARKER = "QFAI-SAMPLE-DESIGN-MD";
  * an unauthored brand as the project's brand contract, and to surface the
  * same condition from `qfai validate` (QFAI-DCON-034).
  *
- * Two detectors, because the marker only covers samples seeded by releases
- * that carry it:
- *   1. `DESIGN_MD_SAMPLE_MARKER` — current samples, survives any edit that
- *      leaves the comment in place.
- *   2. Legacy content fingerprint — samples seeded before the marker
- *      existed, which `qfai init` will never overwrite.
+ * The test is `DESIGN_MD_SAMPLE_MARKER`, which survives any edit that leaves
+ * the comment in place.
  *
  * `text` is `unknown` rather than `string` because this is re-exported from
  * `core/index.ts` and so is reachable from untyped JavaScript, where a caller
@@ -1551,7 +972,74 @@ declare const DESIGN_MD_SAMPLE_MARKER = "QFAI-SAMPLE-DESIGN-MD";
  */
 declare function isUnreplacedDesignMdSample(text: unknown): boolean;
 
+interface GraphPreparation {
+    runtime: "installed" | "not-ready";
+    tools?: {
+        codegraph: "installed" | "not-ready";
+        graphify: "installed" | "not-ready";
+    };
+    code: "code-ready" | "code-not-ready";
+    documents: "documents-not-ready";
+    failedStep?: string;
+    recovery?: string;
+    previousInstallation?: "retained" | "none";
+}
+
+type GraphHookHost = "claude" | "codex" | "copilot" | "vscode";
+
+interface GraphHostFacts {
+    host: GraphHookHost;
+    version?: string;
+    configuration: "configured" | "not-configured" | "failed";
+    denialEvent?: string;
+    failureProtocol?: "supported" | "unsupported" | "unverified";
+    trust: "required" | "granted" | "not-required" | "unknown";
+}
+interface GraphHostProtection {
+    host: GraphHookHost;
+    version?: string;
+    state: "configured" | "trust-required" | "runtime-verified" | "unsupported" | "failed";
+    events: readonly string[];
+    recovery: string;
+    configuration?: GraphHostFacts["configuration"];
+    trust?: GraphHostFacts["trust"];
+}
+
+interface GraphSettingsComposition {
+    files: string[];
+    conflicts: string[];
+}
+
+type GraphIntegrationPreparation = GraphPreparation & GraphSettingsComposition & {
+    hosts: GraphHostProtection[];
+};
+declare function prepareGraphIntegration(root: string, run?: GraphProcess): Promise<GraphIntegrationPreparation>;
+
+declare function renderGraphPreparation(preparation: GraphPreparation, hosts?: readonly GraphHostProtection[]): string;
+
+interface GraphReuseEnvironment {
+    platform: string;
+    architecture: string;
+    machine: string;
+}
+
+interface DocumentPreparation {
+    status: "prepared" | "not-ready" | "failed";
+    source?: "current" | "restored" | "generated";
+    reuse?: "published" | "unavailable";
+    recovery?: string;
+}
+interface ExternalProcessingRequest {
+    readonly destination: string;
+    readonly scope: readonly string[];
+    readonly backend: string;
+    readonly model: string;
+    readonly worktree: string;
+}
+type ApproveExternalProcessing = (request: ExternalProcessingRequest) => Promise<boolean>;
+declare function prepareDocumentAnalysis(root: string, run?: GraphProcess, approveExternal?: ApproveExternalProcessing, environment?: GraphReuseEnvironment): Promise<DocumentPreparation>;
+
 /** Run one ordered spec-to-story migration step from the current project root. */
 declare function runMigrationStep(step: number, argv: string[]): Promise<number>;
 
-export { AC_GHERKIN_SECTION, ARCHETYPES, ATDD_TEST_KIND_DIRS, type Archetype, type AtddCodeTraceabilityResult, type AtddForbiddenRef, type AtddObligationRefs, type AtddSpecRefs, type AtddTestKind, type AtddTraceabilityMissing, type AtddTraceabilityScan, type AtddUnknownRef, type AtddUnknownRefKind, BROWSER_QA_PHASES, COLOR_KEYS, type ColorKey, type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, DESIGN_MD_SAMPLE_MARKER, DISCUSSION_NON_UI_SURFACES, DISCUSSION_UI_BEARING_SURFACES, type DeferredTc, type DesignMd, type DesignMdColors, type DesignMdFonts, type DesignMdRadius, type DesignMdShadow, FONT_KEYS, type FailOn, type FenceMaskOptions, type FontKey, ID_PREFIXES, type IdFormatPrefix, type IdPrefix, type InvalidIdOccurrence, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type OrphanContractsPolicy, type OutputFormat, PLANNED_CONTRACT_KEY, PROTOTYPING_SUPPORTED_SURFACES, type ParseError, type ParseResult, type PrototypingBrowserTool, type PrototypingSurface, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiPrototypingConfig, type QfaiPrototypingExecutionConfig, type QfaiReportConfig, type QfaiReviewProfile, type QfaiRoutingEntry, type QfaiUiuxAuditConfig, type QfaiUiuxConfig, type QfaiValidationConfig, RADIUS_KEYS, type RadiusKey, type ReportData, type RunSddPreflightOptions, SHADOW_KEYS, SKIPPED_WORKFLOWS_MESSAGE, type SddPreflightResult, type SddPreflightSource, type SddPreflightStatus, type ShadowKey, TC_VERIFIED_BY_KEY, type TcStatusDeclaration, type TcVerificationStatus, type TestFileExtensions, type TestLayerRoots, type TraceabilitySeverity, VISUAL_BROWSER_SURFACES, type ValidationCounts, type ValidationIssue, type ValidationOptions, type ValidationProfile, type ValidationResult, type ValidationTimings, type ValidationWaiverAction, type ValidationWaiverDowngradeTo, type ValidationWaiverEntry, type ValidationWaiverMatch, type ValidationWaiverScope, type ValidationWaiverSeverity, type ValidationWaiverSuppressed, type ValidationWaivers, WORKFLOW_MODE_MESSAGE, type WorkflowMode, atddAcceptanceLayerFilter, atddAcceptanceTestGlobs, atddTestKindDirs, atddTestOwnerProbe, classifyAgainstDeclaration, classifyToolLocation, collectDeclaredTcIds, collectDeclaredUsIds, collectHeadingTcIdsFrom, collectPlannedUsIds, collectTcLevels, collectTcStatuses, countIssues, createReportData, createTestLayerRoots, defaultConfig, deriveAtddFilePattern, deriveTestFileExtensions, evaluateAtddCodeTraceability, extractAcSpecNumber, extractAllIds, extractBrSpecNumber, extractCapSpecNumber, extractCaseSpecNumber, extractIds, extractInvalidIdOccurrences, extractInvalidIds, extractScSpecNumber, extractSpecNumber, extractUsSpecNumber, findConfigRoot, findDeclaringDir, findLinkingNodeModules, findPackageJsonUpward, formatReportJson, formatReportMarkdown, getConfigPath, isDiscussionUiBearingSurfaceType, isNonUiDiscussionSurface, isPlannedApiContract, isPlannedDbContract, isSupportedPrototypingSurface, isUnreplacedDesignMdSample, isValidPrototypingSurface, lintSql, loadConfig, locateToolAgainstProject, maskFencedCodeBlocks, packageRootProbe, parseDesignMd, reachedThroughLinkedNodeModules, readRejectedPrimaryUiContract, readSkippedWorkflows, readTestFileExtensions, readWorkflowMode, requiresVisualBrowserEvidence, resolveAtddHomeKind, resolvePath, resolveTestKind, resolveToolPackageDir, resolveToolVersion, resolvesThroughOwnNodeModules, routingEntryName, runBrowserQaOrchestrated, runMigrationStep, runRenderCapture, runSddPreflight, summarizeBrowserQaResult, suspendsObligation, validateContracts, validateDesignMd, validateProject, validateUiContractParse };
+export { AC_GHERKIN_SECTION, ARCHETYPES, ATDD_TEST_KIND_DIRS, type ApproveExternalProcessing, type Archetype, type AtddTestKind, COLOR_KEYS, type ColorKey, type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, DESIGN_MD_SAMPLE_MARKER, DISCUSSION_NON_UI_SURFACES, DISCUSSION_UI_BEARING_SURFACES, type DesignMd, type DesignMdColors, type DesignMdFonts, type DesignMdRadius, type DesignMdShadow, type DocumentPreparation, type ExternalProcessingRequest, FONT_KEYS, type FailOn, type FenceMaskOptions, type FontKey, ID_PREFIXES, type IdFormatPrefix, type IdPrefix, type InstalledOlderThanDeclared, type InvalidIdOccurrence, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type OutputFormat, type ParseError, type ParseResult, type QfaiConfig, type QfaiForbiddenIdentifier, type QfaiOutputConfig, type QfaiPaths, type QfaiPrototypingConfig, type QfaiPrototypingExecutionConfig, type QfaiReportConfig, type QfaiReviewProfile, type QfaiRoutingEntry, type QfaiUiuxAuditConfig, type QfaiUiuxConfig, type QfaiValidationConfig, RADIUS_KEYS, type RadiusKey, type ReportData, type RunSddPreflightOptions, SHADOW_KEYS, SKIPPED_WORKFLOWS_MESSAGE, type SddPreflightResult, type SddPreflightSource, type SddPreflightStatus, type ShadowKey, type TestFileExtensions, type TestLayerRoots, VISUAL_BROWSER_SURFACES, type ValidationCounts, type ValidationIssue, type ValidationOptions, type ValidationProfile, type ValidationResult, type ValidationTimings, type ValidationWaiverAction, type ValidationWaiverDowngradeTo, type ValidationWaiverEntry, type ValidationWaiverMatch, type ValidationWaiverScope, type ValidationWaiverSeverity, type ValidationWaiverSuppressed, type ValidationWaivers, WORKFLOW_MODE_MESSAGE, type WorkflowMode, atddAcceptanceLayerFilter, atddAcceptanceTestGlobs, atddTestKindDirs, classifyAgainstDeclaration, classifyToolLocation, compareInstalledToDeclared, countIssues, createReportData, createTestLayerRoots, defaultConfig, deriveAtddFilePattern, deriveTestFileExtensions, extractAcSpecNumber, extractAllIds, extractBrSpecNumber, extractCapSpecNumber, extractCaseSpecNumber, extractIds, extractInvalidIdOccurrences, extractInvalidIds, extractScSpecNumber, extractSpecNumber, extractUsSpecNumber, findConfigRoot, findDeclaringDir, findLinkingNodeModules, findPackageJsonUpward, formatReportJson, formatReportMarkdown, getConfigPath, isDiscussionUiBearingSurfaceType, isNonUiDiscussionSurface, isOlderVersion, isUnreplacedDesignMdSample, lintSql, loadConfig, locateToolAgainstProject, lowestVersionOfRange, maskFencedCodeBlocks, orderUiuxParts, packageRootProbe, parseDesignMd, prepareDocumentAnalysis, prepareGraphIntegration, reachedThroughLinkedNodeModules, readDeclaredQfaiRange, readRejectedPrimaryUiContract, readSkippedWorkflows, readTestFileExtensions, readWorkflowMode, renderGraphPreparation, requiresVisualBrowserEvidence, resolvePath, resolveTestKind, resolveToolPackageDir, resolveToolVersion, resolvesThroughOwnNodeModules, routingEntryName, runMigrationStep, runSddPreflight, validateContracts, validateDesignMd, validateProject, validateUiContractParse };