Date: 2026-09-23
Scope: Combine the crawl page graph and introspect’s actionable elements
into a walkable site graph, surface candidate user journeys for review,
and generate end-to-end tests that walk selected paths.
Status: Complete. Gate B met 2026-09-23 (a9df7af); TFP-096, the non-gating follow-up, landed 2026-09-24 (1c3c130). Reconciled with git 2026-09-29.
docs/decisions/product-roadmap.md’s Phase 19 paragraph is one sentence
of intent, not a spec — thinner than Phase 18’s, which already had a
confirmed addendum to build from. Rather than invent journey-selection
heuristics or review-UI mechanics that were never decided, this record
locks what’s already true (independent of Phase 18; builds on data
Phase 17/prior crawl work already produces) and marks the genuine open
questions [PLACEHOLDER] for Emil to answer before the affected tickets
start. TFP-088 (the graph itself) does not depend on any of them and can
start immediately; TFP-089–091 were blocked until they’re answered.
Decisions 4-6 are now resolved (Emil, 2026-09-23) — see below. All three
were answerable without TFP-088’s output (product/UX calls, not
implementation details), except Decision 6’s exact numbers, which are
deliberately marked as a starting default rather than a tuned one; see
Decision 6.
Standing policy for this phase: same as Phase 18 — defects found
while building or verifying a ticket are fixed in that ticket, not
deferred; TEST_PLAN.md and doc updates land in the same commit as the
code they describe. See product-roadmap.md’s Sequencing note.
product-roadmap.md’s “Explicitly out of scope” list, already
locked) applies here directly. This is inherited, not a new decision:
journey tests are generated but skipped by default, the same as any
other side-effecting test.Phase 19 is independent of Phase 18, confirmed by the roadmap’s own text — sequencing between them is a scheduling choice, not a dependency, and this record doesn’t change that.
"signup", "checkout") as an entry page + exit page
pair; TFP-089 finds the path between them the same way it finds any
other path (see Decision 6’s length cap).exitPath doesn’t have to be a graph node. TFP-088 confirmed
the graph stops at a form-submit edge, because introspect never
submits a form - it observes, it doesn’t act (real live-target
evidence: the-internet.herokuapp.com’s /login -> /authenticate
is an edge, but the post-login redirect to /secure is not, since
nothing actually logs in during introspection). A login-style named
flow (entry /login, exit /secure) would never resolve under a
strict “exit must be a graph node” reading of the decision above.
Resolved: TFP-089 matches a named flow as far as the graph goes (the
form-submit edge counts as reaching it) and carries the declared
exitPath on the candidate as unverified. TFP-091 - which already
submits the form, since journey tests are interactive/side-effecting
per Decision 2 - makes reaching the declared exitPath part of its
generated test’s assertion. This keeps introspection read-only (no
new side effects added at graph-build time) and puts exit
verification exactly where side effects are already permitted, rather
than adding a new form-submitting introspection pass (rejected: would
break the read-only model Decisions 1 and 2 both rely on) or requiring
every named flow’s exit to already be a graph node (rejected: would
silently fail to find the login/checkout-style flows named flows exist
for in the first place).generate against.MAX_CRAWL_PAGES already bounds
crawl output to 100 pages (src/app/api/crawl/route.ts), so TFP-088’s
graph is already bounded to at most 100 nodes before Phase 19 adds
anything. The two caps that actually need a Phase-19-specific number
are journey path length and how many ranked candidates get surfaced.exitPath beyond the graph
(Decision 4’s amendment), the generated test’s final assertion is
that the app actually reaches exitPath after submitting - not just
that the submit produced no error.interactive-skipped reason, never silently “covered” and never
conflated with generator-gap; not selected at all is not-selected.TFxx-000: id prefix a
real Playwright run reports, so every discovered element across
functional, accessibility, reliability, and storage matching alike
came back uncovered/generator-gap on any real run, undetected because
RUN-10/RUN-11’s unit tests used bare titles. See TEST_PLAN.md’s
RUN-15 for the live probe and the fix; GEN-19 covers the
interactive-skipped bucket specifically.TEST_PLAN.md gets a case for the graph matching a real target’s
actual navigable structure as soon as TFP-088 lands.interactive-skipped and the
id-prefix matching defect found and fixed while verifying it.feature, crawlbaseUrl introspect/coverage
data so later tickets can read it without recomputing.TEST_PLAN.md case proving the graph’s edges match a real target’s
actual navigation (pick a target with at least one multi-page flow).Moved word for word from docs/test-plan/INT.md by TFP-253; the case’s row there links here.
Test: Per-baseUrl walkable site graph: nodes are pages, edges are the specific element that navigates from one page to another — link (<a href>), form-submit (form[action] / formaction), or action (onclick/data-href navigation) — composed from existing introspect output with no extra crawl pass (TFP-088, automated: npm run test:unit — src/lib/introspect/site-graph.test.ts, “an internal link is an edge naming the element that produces it”, “a form action and a formaction button are form-submit edges”, “external, anchor, mailto, download and inert links are not edges”, …)
Expected result: inspectPages returns a siteGraph (also on /api/introspect’s response, carried on ContentProfile, and so persisted into a run’s contentProfile); every edge names its from/to path, kind, the element’s tagName, visible text, and the raw attribute value it navigates by. External, anchor, mailto, download, and inert links are never edges; a link self-edge is dropped but a form-submit self-edge is kept; query/hash never create a distinct page (same normalization as the crawl). Verified live, called directly (inspectPages, not through the dev server — see INT-07): introspecting https://the-internet.herokuapp.com paths /, /login, /secure gives 46 nodes / 45 edges — 44 link edges from / (e.g. / → /login via <a href="/login"> “Form Authentication”, / → /add_remove_elements via <a href="/add_remove_elements/"> “Add/Remove Elements”, trailing slash normalized away) and one form-submit edge /login → /authenticate via the real <form action="/authenticate">; the 44 targets never introspected themselves (/abtest, /authenticate, …) are inspected: false leaf nodes. /secure redirects to /login when unauthenticated, so its snapshot lands on the /login node rather than creating a /secure one. Known limit: a form’s outcome is only knowable by submitting it, which introspect never does, so /login → /authenticate is where the graph stops — the /authenticate → /secure redirect after a successful login is not an edge.
feature{ label, entryPath,
exitPath } entries from run config; find the path from entryPath as
far as the graph goes (same traversal, same length cap) - a
form-submit edge counts as reaching the flow, per Decision 4’s
amendment, even when exitPath itself isn’t a graph node yet.
exitPath is carried on the candidate as declared-but-unverified;
TFP-091 is what actually verifies it.CandidateJourney type (path,
source: automatic/named, rank).TEST_PLAN.md cases per Acceptance Criteria §2 above.Moved word for word from docs/test-plan/GEN.md by TFP-253; the case’s row there links here.
Test: Candidate-journey review screen: TFP-089’s ranked journeys are listed with a per-journey select control, nothing pre-selected, and “Generate selected” writes exactly the selection into run config as contentRules.selectedJourneyIds (TFP-090, automated: tests/regression/testforge.journeys.spec.ts — “lists real candidates unselected, and ‘Generate selected’ carries exactly the selection into run config”, “changing the selection after generating blocks running until regenerated”; unit: src/lib/introspect/journeys.test.ts — “selectJourneys returns exactly the selected journeys…”, “normalizeContentRules carries selectedJourneyIds exactly, defaulting to none”)
Expected result: Against a real fixture site served by the spec itself (/ → /login link, /login form posting to /authenticate; introspected for real through the built app, no API stubbing) the “Candidate Journeys” section lists /login → /authenticate (#1) and / → /login → /authenticate (#2), each with its real step elements (“Sign in (link)”, “(form submit)”), both aria-pressed="false", and “Generate selected” disabled. The initial /api/generate request carried selectedJourneyIds: [] (default-off, never all). Selecting only #2 and using “Generate selected” sent a second /api/generate whose contentRules.selectedJourneyIds was exactly [#2's id] — not both, not none — and /api/introspect was called once in total (the reviewed scan is reused, so the ids still match). Changing the selection after generating shows “Generate the suite again after changing the selected journeys before running it.” until regenerated. An id no longer offered by the current scan is dropped, never sent. Since TFP-091 (GEN-19) the generator reads selectedJourneyIds, so “Generate selected” now adds one journey test per selected journey; before it, the selection was carried in run config only.
Moved word for word from docs/test-plan/INT.md by TFP-253; the case’s row there links here.
Test: Candidate journeys: every simple path of at most 6 hops ending in a form-submit edge (automatic), plus config-named flows ({ label, entryPath, exitPath }), deduped by page sequence, named-first then shortest-first, capped at 20 (TFP-089, automated: npm run test:unit — src/lib/introspect/journeys.test.ts, “a path ending in a form submit is a candidate…”, “a named flow whose exit is beyond the graph matches as far as the form submit and carries the exit as declared”, “a named flow outranks an automatic candidate over the same pages…”, “a journey of exactly the hop limit is surfaced; one hop over is excluded, not truncated”, “a named flow whose exit is reachable only past the hop limit is excluded with a warning, with no shorter fallback”, “no more than the journey cap is surfaced…”)
Expected result: inspectPages (and /api/introspect, via an optional namedFlows body field) returns ranked journeys, also carried on ContentProfile; each names its page sequence and the real element per hop (steps), and a named flow carries declaredExitPath with exitInGraph (Decision 4 amendment: an exit beyond a form-submit is declared, unverified, until TFP-091 submits). A path over MAX_JOURNEY_HOPS (6) is excluded, never truncated into a shorter one; a named flow only reachable past the cap is excluded with a warning, not replaced by a shorter fallback. Verified live, called directly (see INT-07): https://the-internet.herokuapp.com /, /login, /secure with named flow { login, /login, /secure } gives #1 named(login) /login > /authenticate via the real form “Username Password Login”, declaredExitPath /secure, exitInGraph: false; and #2 automatic / > /login > /authenticate (<a> “Form Authentication”, then that form) — the automatic /login > /authenticate is folded into #1. 25 real pages introspected with no named flows: 6 journeys, longest 3 hops, so the 6-hop/20-journey starting defaults held and were not retuned; the 2 distinct forms found (/forgot_password self-posting, /login → /authenticate) each appear as a 1-hop journey plus longer prefixed variants, which the shortest-first rank puts after them. Known limits: a <form> with no action attribute (e.g. /upload) posts to its own page by HTML rules, but a JS-driven form looks identical to introspect, so no edge is assumed for it; and the graph only has outgoing edges for introspected pages, so journeys are only as broad as the page set introspected.
feature, uifeature, generateexitPath (Decision 4’s
amendment) isn’t a graph node - i.e. it sits beyond the flow’s last
form-submit - the generated test’s final assertion is that the app
actually reaches exitPath after submitting, not just that the
submit didn’t error. This is where the flow’s exit is verified for
real, since TFP-089 only recorded it as declared.TEST_PLAN.md case proving a real journey test walks a real
multi-step path against a real target and produces a specific,
named pass/fail.Moved word for word from docs/test-plan/GEN.md by TFP-253; the case’s row there links here.
Test: End-to-end journey tests: one generated test per journey selected on the review screen walks its real pages and elements in order, asserts each step, and verifies a named flow’s declared exit for real; skipped unless interactive tests are enabled for the run (TFP-091, automated: tests/regression/testforge.journeys.spec.ts — “journey tests are skipped by default and reported as not covered, with their own reason”, “with interactive tests enabled a real journey walks every step and a named flow’s exit is verified for real”, “the run option appears only for a suite with journey tests, and its state reaches /api/run”; unit: src/lib/generate/mock/journey-tests.test.ts)
Expected result: Against a real fixture site through the built app’s own routes (no stubbing of introspect/generate/run): with enableInteractive off all three journey tests are reported Blocked (skipped) and listed as interactive-skipped in notTested, with the Functional row uncovered; with it on, the automatic journey / > /login > /authenticate (follow the real <a href="/login"> “Sign in”, then fill and submit the real <form action="/authenticate">, asserting the submit reached /authenticate without a 5xx) Passed; named flow signin (declared exit /secure) Passed because the post/redirect/get really lands on /secure; named flow broken (declared exit /nowhere) Failed with the specific message “the journey broken declares /nowhere as its exit, but after submitting the app ended on /secure”. Verified live against https://the-internet.herokuapp.com (generated from real introspection, run directly with TESTFORGE_INTERACTIVE=1): the automatic journey / > /login > /authenticate Passed (link “Form Authentication” then the real login form, /authenticate answered without a 5xx); named flow { login, /login, /secure } Failed with “the journey login declares /secure as its exit, but after submitting the app ended on /login” — correct and expected, since sample values are not that site’s credentials. Known limits: journey tests submit forms with generic sample values by input type (TestForge cannot know a real credential), so a login-style flow will fail its exit assertion against a real site until a flow can supply real input (Phase 20 territory); a journey is generated only into a functional suite that is itself being generated.
Moved word for word from docs/test-plan/RUN.md by TFP-253; the case’s row there links here.
Test: Coverage matches real executed tests to discovered elements despite the TFxx-000: id prefix real titles carry, and a skipped-by-default journey is neither “covered” nor a generator gap (TFP-091, automated: tests/regression/testforge.journeys.spec.ts — “a real run’s passing element checks are matched to their discovered elements”; unit: src/lib/report/discovered-coverage.test.ts — “an element’s check is matched to its discovered element when the executed title carries the TFxx id prefix a real run has”, “a generated journey that was skipped … stays uncovered with its own reason”)
Expected result: Defect found and fixed in this ticket: coverage matched executed titles against title builders that omit the TFFU-003: prefix Playwright reports, so on a real run every discovered element was reported untested — probed live against a one-form fixture, all 3 passing element checks (form element check: Name Go, form element check: n, action element check: Go) came back Functional uncovered, 0%, generator-gap. RUN-10/RUN-11’s unit tests used bare titles, so they could not see it. Now the same run reports Functional covered with no uncovered elements. Candidate journeys join the functional discovered surface: a journey generated into the suite counts (covered if it ran; interactive-skipped if it was skipped/blocked; generator-gap if no record); one not generated is listed as not-selected and not counted.
feature, uinamedFlows body field on /api/introspect, but nothing in
the app lets a user enter one — named flows are API-only today.
Flagged by Claude Code while building TFP-089, and confirmed against
the real UI before answering: src/app/page.tsx already has exactly
this shape of field (contentPathsInput, requiredHeadingsInput,
requiredTextInput, forbiddenTextInput), free-text lists under a
collapsible advanced section (isContentRulesCollapsed) — a named-
flow field fits that same slot.{ label, entryPath, exitPath } entries and passed as
/api/introspect’s namedFlows field — same parsing shape as the
existing content-rule inputs, not a new form-building pattern.TEST_PLAN.md case proving a named flow entered through the UI
produces the same ranked candidate a direct API call with that flow
would.label: /entry -> /exit (=> and the
arrow character also accepted), in the Content Rules section beside the
other free-text lists. Unlike those lists it splits on newlines only,
since a label may contain a comma. A line that does not parse is named
in an inline message rather than silently dropped. Editing the flows
after generating makes the suite stale, like the other content-aware
inputs. Real credentials for a flow are Phase 20’s (stored, never
inline); this field carries only the entry and exit paths.Moved word for word from docs/test-plan/GEN.md by TFP-253; the case’s row there links here.
Test: Named flows can be entered in the UI and behave exactly as if sent to the API (TFP-096, automated: tests/regression/testforge.journeys.spec.ts — “a named flow entered in the UI produces the same ranked candidates as the same flow sent to the API, and shows on the review screen”, “a line that is not a flow is reported, not silently ignored”; unit: src/app/_lib/derive.test.ts)
Expected result: A “Named flows” textarea in the Content Rules section takes one flow per line as label: /entry -> /exit (=> and the arrow character also accepted; a missing leading slash is added). Against the real fixture through the built app: entering signin: /login -> /secure sent /api/introspect exactly namedFlows: [{ label: "signin", entryPath: "/login", exitPath: "/secure" }], and the journeys in that response were identical (deep-equal, ids and ranks included) to a direct API call with the same flow; the Candidate Journeys screen listed it first as “Named flow: signin”, /login → /authenticate, with “Declared exit /secure” marked unverified. A line that does not parse is not dropped silently: an inline message names it (This line was not understood and will be ignored: "..."), and it disappears once the line is fixed. Editing the flows after generating marks the suite stale (Run blocked until regenerated), like the other content-aware inputs. A parsed flow survives the server’s normalizeNamedFlows unchanged, so the UI cannot show one flow and send another.
TEST_PLAN.md case against a real target.Met, 2026-09-23 (a9df7af).
TEST_PLAN.md
case proving real (not assumed) behavior: GEN-18 (review screen,
fixture site), GEN-19 (journey generation, fixture site +
the-internet.herokuapp.com live), INT-09 (journey identification,
same live target). RUN-15 covers the coverage-bucketing side
specifically, including the id-prefix defect found and fixed while
verifying TFP-091 — see Acceptance Criteria §4.