mr-onion

Phase 19 Decision Record — Path and Journey Mapping (Locked)

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.

Context

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.

Decisions

  1. The walkable graph is built from data that already exists.
    • Nodes are pages from the existing crawl page graph; edges are the actionable elements introspect already discovers (links, form submits, and other navigating actions) that connect one crawled page to another.
    • No new discovery mechanism — this is composition of Phase 16/17’s existing crawl and introspect output, not a new crawl pass.
  2. Journey tests are interactive by the roadmap’s own existing rule.
    • Walking a journey end to end almost always means submitting forms or triggering side effects on the live site — the “interactive tests skip unless explicitly enabled per run” rule (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.
  3. 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.

  4. A candidate journey is either an automatically-detected form-submit path or an explicitly named config-supplied flow.
    • Resolved (Emil, 2026-09-23): two sources, both real, neither guessed. Automatic: any path through the graph that ends in a form-submit action is a candidate — no config required, works on any site out of the box, mirrors how TFP-085’s dependency tests need no per-site config either. Explicit: the run config may also name specific flows by label (e.g. "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).
    • Ranking: a named-flow match always ranks above an automatic match — it’s explicit intent, not a guess, the same principle Phase 18’s Decision 4 correction landed on (don’t treat an inferred label as equivalent to a stated one). Among automatic matches, shorter paths rank above longer ones (fewer hops is a stronger “this looks like a real journey” signal than a long incidental one).
    • Duplicate paths (same page sequence found both ways) are surfaced once, keeping the higher rank.
    • Amended (Emil, 2026-09-23, during TFP-088 verification): a named flow’s 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).
  5. Candidate journeys are surfaced through a new UI screen, not a report-only list.
    • Resolved (Emil, 2026-09-23): a dedicated screen lists ranked candidates from TFP-089 with a per-journey select control and a “Generate selected” action, mirroring the existing best-practice-area selection UI already in the app. Selecting and generating writes the selection into run config for TFP-091 to read — not a report the user reads and manually re-runs generate against.
    • This makes TFP-090 a UI ticket, not a report-section ticket.
  6. Starting caps: max path length 6 hops, max 20 journeys surfaced.
    • Resolved (Emil, 2026-09-23) as a starting default, explicitly revisable once TFP-088 shows real graph sizes on an actual target — not a final, data-backed number.
    • No separate graph-size cap is needed: 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.
    • Max path length 6: long enough for a realistic multi-step flow (landing → category → detail → cart → checkout → confirmation is 5 hops) without walking into combinatorial path counts on a 100-node graph. Max 20 journeys surfaced: keeps TFP-090’s review screen a list a person can actually read, not a data dump.
    • Both numbers are configuration, not architecture — TFP-089 should read them as constants it can tune, not something hardcoded three layers deep, so the “revisit after real data” step is cheap.

Acceptance Criteria

  1. Site graph (TFP-088 — not gated on the placeholders above)
    • Against a real multi-page target, the graph’s edges match actual navigable actions on that target (a link or form-submit that really leads from page A to page B), not an inferred or assumed connection.
  2. Journey identification (TFP-089)
    • Against a real target with a known multi-step form-submit flow (e.g. a 2-3 page checkout or signup), that exact path is surfaced as a ranked candidate, naming its actual pages and the actionable element connecting each step - not an inferred or assumed sequence.
    • A config-named flow (entry page + exit page pair) produces the matching path and ranks above any automatically-detected candidate covering the same pages.
    • No candidate exceeds the 6-hop path-length default; no more than 20 candidates are surfaced.
  3. Review and selection (TFP-090)
    • Candidate journeys from TFP-089 appear listed in the new UI screen, each with a select control.
    • Selecting one or more journeys and using “Generate selected” carries exactly that selection into run config - not every candidate, and not none.
  4. Generation (TFP-091)
    • Against a real target, a selected multi-step journey runs as one generated test that asserts each step in sequence (not a bare “page loaded” check), and is skipped by default per Decision 2 like any other interactive test.
    • For a named-flow journey with a declared 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.
    • A selected journey joins the functional discovered surface for coverage purposes, same as any other discovered element: generated and run counts as covered; generated but skipped (interactive tests not enabled for the run) is bucketed under a dedicated interactive-skipped reason, never silently “covered” and never conflated with generator-gap; not selected at all is not-selected.
    • Verifying this against a real run surfaced a pre-existing defect, fixed in the same ticket: discovered-coverage matched executed test titles against title builders that omit the 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.

Regression Policy

Backlog

TFP-088 — Build the walkable site graph from crawl + introspect output

INT-08 evidence

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.

TFP-089 — Identify and rank candidate journeys

GEN-18 evidence

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.

INT-09 evidence

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.

TFP-090 — Surface candidate journeys for review

TFP-091 — Generate end-to-end tests for selected journeys

GEN-19 evidence

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.

RUN-15 evidence

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.

TFP-096 — Named-flow entry in the run-config UI

GEN-20 evidence

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.

  1. TFP-088 (unblocked, start now)
  2. Emil answers Decisions 4–6 — done, 2026-09-23, before TFP-088 landed.
  3. TFP-089 → TFP-090 → TFP-091, in sequence (each genuinely depends on the previous one’s output, unlike Phase 18’s parallel tickets)
  4. TFP-096, any time after TFP-089 — doesn’t block or depend on TFP-090/091, so it can slot in wherever’s convenient, including in parallel with them.

Suggested Milestone Gates

Gate A — Graph built

Gate B — Phase 19 complete

Met, 2026-09-23 (a9df7af).