forge-lcdl

Handbook

Page mechanics artifacts and LCDL tasks

This document complements PLAYWRIGHT-DISCOVERY.md with schema boundaries between checklist PageMechanicsSpec, interactive-discover outputs, and focused helper tasks.

Two version-string conventions

Artifact Contract path Typical use
Checklist page_mechanics_v1 src/forge_lcdl/contracts/page_mechanics/v1/contract.md Structural reference: top-level schema_version page_mechanics_v1, actions as an ordered array of steps.
Discover output page_mechanics.v1 pw_quiz_mechanics_discover, pw_static_mcq_mechanics_discover schema_version literal page_mechanics.v1 (dot form). Interactive quiz discovery uses actions as a named-phase object tree—not necessarily the checklist array shape.

At integration boundaries, normalize version strings and actions layout explicitly (your runner may accept both shapes or compile phases into an array).

Validation split (forge-lcdl vs runtime)

Layer What it checks
forge_lcdl.schemas.page_mechanics_v1 validate_page_mechanics_shape, ACTION_KINDS, forbidden eval / execute_js / script, confidence coercion helpers.
Discover tasks pw_quiz_mechanics_discover validates actions phases recursively; allowed_action_kinds filter; no arbitrary JS fields.
Repair task pw_mechanics_repair rejects code-carrier keys; validates kind under actions; calls validate_page_mechanics_shape when actions is a list.
Consumer runtime Selector existence, stability across navigations, timeouts, grading correctness, loop termination—Playwright truth.

LCDL validation is lightweight and probe-grounded; it does not prove selectors work on production DOM.

task_id Role Contract
pw_page_kind_route Route page_kind and next_probe_needed contracts/pw_page_kind_route/v1/contract.md
pw_quiz_mechanics_discover Full interactive_quiz mechanics JSON contracts/pw_quiz_mechanics_discover/v1/contract.md
pw_static_mcq_mechanics_discover Static MCQ / HTML-first mechanics contracts/pw_static_mcq_mechanics_discover/v1/contract.md
pw_grading_signal_infer Infer correct_signal from submit deltas / feedback text contracts/pw_grading_signal_infer/v1/contract.md
pw_selector_harden Rank / reject selectors given inventories and constraints contracts/pw_selector_harden/v1/contract.md
pw_mechanics_repair Patch mechanics using validation_failure facts contracts/pw_mechanics_repair/v1/contract.md
pw_network_api_route_infer Classify API-backed traces; trace-grounded endpoint candidates contracts/pw_network_api_route_infer/v1/contract.md

Supporting extraction tasks (pw_chunk_classify, pw_extractor_synthesize_*, pw_incremental_diagnose) remain documented in EXTRACTION-CONVERGENCE.md.

Focused tasks (when to call)

pw_grading_signal_infer

Input: before_answer, after_dummy_submit, option_candidates, class_deltas, attribute_deltas, feedback_text.

Output: correct_signal (object with string kind, declarative selectors/patterns), confidence, evidence strings.

Use after you have deterministic before/after submit snapshots but grading taxonomy is ambiguous.

pw_selector_harden

Input: selector_candidates, element_inventory, html_snippets, constraints (e.g. prefer_roles, avoid_generated_classes, must_be_within_root).

Output: ranked_selectors and rejected_selectors as arrays of objects with purpose, selector, confidence, reason (ranked) or selector, reason (rejected).

Use when discovery proposes brittle CSS; feed ranked results back into operator_hints or the next mechanics discover pass.

pw_mechanics_repair

Input: url, previous_mechanics, validation_failure, optional operator_hints.

Output: repaired_mechanics, patch_summary, confidence, issues.

Use only after deterministic validation or runner failure surfaces structured facts—avoid sending megabytes of logs.

pw_network_api_route_infer

Input: url, page_probe, network_events (bounded rows).

Output: api_backed, confidence, three candidate arrays (question_endpoint_candidates, submit_endpoint_candidates, answer_endpoint_candidates), requires_browser_session, notes.

Candidates must reference url_path values present in network_events (enforced in forge-lcdl).

Safety

Aligned with CONTRIBUTING.md and task contracts:

  • Authorized surfaces only; no exam or paywall bypass guidance.
  • No extraction or logging of secrets, raw cookies, or tokens.
  • Avoid sending PII or credentials inside probes or hints.

Testing

Mirror forge-lcdl tests: ChatResult(True, json.dumps({...})) injectable chat, plus frozen JSON fixtures for probes and expected validator outcomes. Live gateway tests are optional (pytest -m granite).

See PLAYWRIGHT-DISCOVERY.md §5 for conventions.