From 6f9576d5b6451d78d08a2fec1d3291c02c13b001 Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 13 Oct 2026 16:12:17 +0200 Subject: [PATCH] Establish Playwright service intent and staged delivery workplans Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a13590-a16f-7f60-be60-fd71627bc99d --- .custodian-brief.md | 27 ++ .gitignore | 5 + .repo-classification.yaml | 11 + AGENTS.md | 280 ++++++++++++++++++ INTENT.md | 94 ++++++ README.md | 17 +- SCOPE.md | 22 ++ docs/demand-and-reuse.md | 66 +++++ ...P-PLAYWRIGHT-WP-0001-statehub-bootstrap.md | 61 ++++ ...PP-PLAYWRIGHT-WP-0002-consumer-contract.md | 76 +++++ ...RAPP-PLAYWRIGHT-WP-0003-service-package.md | 87 ++++++ ...LAYWRIGHT-WP-0004-consumer-verification.md | 78 +++++ workplans/README.md | 12 + 13 files changed, 835 insertions(+), 1 deletion(-) create mode 100644 .custodian-brief.md create mode 100644 .gitignore create mode 100644 .repo-classification.yaml create mode 100644 AGENTS.md create mode 100644 INTENT.md create mode 100644 SCOPE.md create mode 100644 docs/demand-and-reuse.md create mode 100644 workplans/RAPP-PLAYWRIGHT-WP-0001-statehub-bootstrap.md create mode 100644 workplans/RAPP-PLAYWRIGHT-WP-0002-consumer-contract.md create mode 100644 workplans/RAPP-PLAYWRIGHT-WP-0003-service-package.md create mode 100644 workplans/RAPP-PLAYWRIGHT-WP-0004-consumer-verification.md create mode 100644 workplans/README.md diff --git a/.custodian-brief.md b/.custodian-brief.md new file mode 100644 index 0000000..0e7fea4 --- /dev/null +++ b/.custodian-brief.md @@ -0,0 +1,27 @@ + +# Custodian Brief - rapp-playwright + +**Project:** rapp-playwright +**Domain:** infotech +**State Hub:** http://127.0.0.1:8000 +**Topic ID:** `595afc64-bd28-47bf-aafb-ba230b28371b` + +## Open Workplans + +### Bootstrap State Hub integration + +Workplan file: `workplans/RAPP-PLAYWRIGHT-WP-0001-statehub-bootstrap.md` + +Open tasks: +- T01 - Review generated integration files +- T02 - Verify local developer workflow +- T03 - Seed first real workplan + +## Session Start + +1. Read `INTENT.md`, `SCOPE.md`, and `AGENTS.md`. +2. Check inbox: `GET /messages/?to_agent=rapp-playwright&unread_only=true`. +3. Scan `workplans/`. +4. Update task statuses in workplan files as work progresses. + +Last generated: 2026-10-13 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e4e0199 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +# state-hub: track .claude/rules +# Claude Code local state (track shared rules; ignore machine-specific files) +.claude/* +!.claude/rules/ +!.claude/rules/*.md diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..f5a3b9a --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,11 @@ +repo_classification: + standard: Repo Classification Standard + version: '1.1' + classified_at: '2026-10-13' + classified_by: codex + category: tooling + domain: infotech + secondary_domains: [agents] + capability_tags: [configuration, deployment, operations] + business_stake: [technology, operations] + business_mechanics: [operation, control] diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b1ea4af --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,280 @@ +# rapp-playwright — Agent Instructions + +## Repo Identity + +**Purpose:** Provide and operate an agent-consumable Playwright and headless Chromium service for UI testing, screenshots and keyboard journeys. + +**Domain:** infotech +**Repo slug:** rapp-playwright +**Topic ID:** `595afc64-bd28-47bf-aafb-ba230b28371b` +**Workplan prefix:** `RAPP-PLAYWRIGHT-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Codex uses HTTP REST and +the `statehub` CLI by default. MCP is opt-in because the current Codex MCP bridge +adds severe call latency; the full administrative MCP surface remains available +to clients that need it. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | +| Optional local edge relay | http://127.0.0.1:18080 | + +When an operator has enabled the edge relay, set API_BASE to the relay URL. +Queueable writes return an explicit queued receipt if the central hub is +unreachable. Treat that as pending local evidence, then ask the operator to run +statehub outbox status/replay after connectivity returns. + +Codex workspace-write sandboxes need network access enabled to reach the host's +loopback listener. Bootstrap this once with `make -C ~/state-hub configure-codex` +and restart Codex. The canonical REST health endpoint is `/state/health`, not +`/health`. If a sandboxed loopback probe fails, retry it with escalated execution +before declaring State Hub unavailable; a managed Codex permission profile may +still enforce isolated networking. Experimental MCP can be enabled explicitly +with `make -C ~/state-hub configure-codex WITH_MCP=1`. + +Repository files cross machine boundaries through committed Forge revisions: +workstation agents push to Forgejo and cluster infrastructure reads a verified +commit into ephemeral storage. Neither side reads or writes the other's +checkout. `local_path` and `host_paths` describe host-local observations only. + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workplans for this domain +curl -s "http://127.0.0.1:8000/workplans/?topic_id=595afc64-bd28-47bf-aafb-ba230b28371b&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=rapp-playwright&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read?reader=rapp-playwright" \ + -H "Content-Type: application/json" -d '{}' +# Standing notices (to_agent "broadcast", kind "standing") stay until acknowledged: +# curl -s -X POST "http://127.0.0.1:8000/messages//ack" -H "Content-Type: application/json" -d '{"agent":"rapp-playwright"}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workplan_id": "", + "task_id": "" + }' +``` + +Omit `workplan_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe) +2. Check inbox: `GET /messages/?to_agent=rapp-playwright&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. If finishing a workplan: hand off **residuals** as live work records first + (intake with `origin: residual` + `origin_ref: `, or a next workplan / + decision / engagement). Do not park leftovers only in prose or `SCOPE.md`. + Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals. +3. Log: `POST /progress/` with a summary of what changed (name handoff ids) +4. After workplan file changes, run: + ```bash + uv run --project ~/repo-manager rmgr sync --path . --push + ``` + This assigns only missing deterministic identifiers, verifies the pushed + Forgejo commit and `primary/railliance01`, then requests one central + reconciliation. A queued receipt is pending evidence; rerun after + connectivity returns. Use `statehub fix-consistency` for a separate deep audit. + +--- + +## Credential and access routing + +**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** +for inference. Run this check **before** requesting secrets, API keys, SSH access, +login tokens, or database passwords — in any repo, not only `ops-warden`. + +ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every +other credential need belongs to another subsystem. **Do not** message +`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key. + +### Lookup (do this first) + +```bash +warden route find "" --json +warden route show --json +``` + +Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`). + +| Agent runtime | How to orient | +| --- | --- | +| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=rapp-playwright` is for coordination, not secret vending | +| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership | +| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` | + +### Quick routing table + +| I need… | Owner | ops-warden executes? | +| --- | --- | --- | +| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` | +| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only | +| Login / OIDC / MFA | key-cape / Keycloak | No — route only | +| Authorization decision | flex-auth | No — route only | +| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` | +| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only | + +### Anti-patterns (do not do these) + +- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc. +- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist +- Pasting secrets into Git, State Hub, workplans, logs, or chat + +### Other capabilities (reuse-surface) + +Non-credential capabilities are usually discovered through **reuse-surface** federation +(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in +every repo's agent instructions because it is high-frequency, high-risk, and easy to +get wrong. + +**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` + + + + +## Repository workflow and stopping boundary + +Read `INTENT.md`, `SCOPE.md`, `docs/demand-and-reuse.md` and `workplans/README.md`. +The initial assignment ends after planning, registration and the reuse-surface +notification. WP-0002 through WP-0004 remain proposed for subsequent work. + +This is a planning-only checkout. There are no install, build, lint, service-start +or browser-test commands yet. For documentation changes, check `git diff --check`, +Markdown links, YAML frontmatter and fenced task blocks. Run the repository sync +above to publish and reconcile work records, then inspect its receipt; use +`statehub fix-consistency --repo rapp-playwright --json` for a separate audit. +Future implementation must add and document real runtime verification commands. + +Keep service availability explicitly planned until browser and consumer receipts +exist. Reuse the existing `capability.infotech.headless-browser` registry record; +send provider contract and evidence updates to reuse-surface when authorized. +Content-explorer owns its acceptance tasks. No service endpoint, version pin, +deployment binding or working trial command may be invented to fill a placeholder. + +--- + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/RAPP-PLAYWRIGHT-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-RAPP-PLAYWRIGHT-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md`, workplan id +`RAPP-PLAYWRIGHT-WP-ADHOC-YYYY-MM-DD`, and task ids +`RAPP-PLAYWRIGHT-WP-ADHOC-YYYY-MM-DD-T01`, etc. `RAPP-PLAYWRIGHT-WP` includes its final `-WP` +token. Unqualified historic `ADHOC-*` ids are grandfathered and must not be +copied into new records. Use this only for low-risk work completed directly; +create a normal workplan for anything needing analysis, design, approval, +dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: RAPP-PLAYWRIGHT-WP-NNNN +type: workplan +title: "..." +domain: infotech +repo: rapp-playwright +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # deterministic UUIDv5; managed by Repo Manager +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Terminology:** workplan is the fleet term; `workstream` appears only in legacy +API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see +`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: RAPP-PLAYWRIGHT-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # deterministic UUIDv5; managed by Repo Manager +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +**Residuals when finishing:** actionable leftovers become live work records +before `status: finished` — usually an intake (`origin: residual`, +`origin_ref: RAPP-PLAYWRIGHT-WP-NNNN`) or a spawned workplan. Residual is a *role*, +not a kind. Fleet list lives on State Hub, not in `SCOPE.md`. + +To create a new workplan: +1. Write the file following the format above +2. Run `uv run --project ~/repo-manager rmgr sync --path . --push`. +3. Run `statehub fix-consistency` only when a separate deep audit is needed. diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..f25725d --- /dev/null +++ b/INTENT.md @@ -0,0 +1,94 @@ +# INTENT — rapp-playwright + +## Why this repo exists + +`rapp-playwright` provides and operates a reusable Playwright and headless +Chromium environment on Railiance so coding agents can arrange UI testing +without assembling a browser stack or copying another application's fixtures. +An agent should be able to discover availability, follow one documented command +path, exercise a target UI, and retrieve inspectable evidence of the result. + +The initial demand is content-explorer's `CONTENT-WP-0000-T04`: responsive +screenshots and a keyboard interaction walkthrough. Its environment lacked a +browser launcher, and discovery of existing source examples did not supply a +verified runnable path. [Demand evidence](docs/demand-and-reuse.md) separates +this delivery gap from reuse-surface's search and ranking defects. + +## What it owns + +- The agent consumption contract: availability/preflight, submission or session + setup, target reachability, execution, results, cleanup, and actionable failures. +- A reproducible Playwright/Chromium runtime with compatible pinned versions, + browser dependencies, immutable release identification, and upgrade checks. +- The thin service and client integration needed to expose that runtime through + a supported command path, with a minimal consumer-independent example. +- Per-run isolation, bounded concurrency and duration, cancellation, abandoned + run cleanup, and artifact lifecycle. Consumers must not see each other's + browser state or results. +- The Railiance workload package, health/readiness checks, resource envelope, + deployment evidence, recovery and rollback instructions. +- Evidence-backed availability reports and consumption references supplied to + reuse-surface when the service changes. + +## Consumer outcome + +From a fresh agent environment, a documented trial must say whether execution +is available **now** and where the browser runs. A local browser is not required +for the intended managed service path. Any required client setup must be named, +versioned and verified; an optional local fallback must be labeled separately. + +The trial opens a supplied reachable page, checks a meaningful rendered state, +captures desktop and narrow-viewport screenshots, and records a short keyboard +interaction with its observed result. It returns machine-readable status and +artifact references, plus the exact command, target, package/browser versions, +timestamps and assertion outcomes. Infrastructure/setup failures must be +distinguishable from failed UI assertions. A failed run must remain diagnosable. + +The contract must explain how a remote browser reaches a consumer's development +server; a workstation's `localhost` is not a remote browser's `localhost`. +Unreachable targets should produce a useful diagnosis and a supported setup path. + +## Ownership boundaries + +Consumers own their applications, fixtures, assertions, target authorization, +visual baseline decisions, and acceptance of their own tasks. This repo supplies +execution and evidence; it does not mark content-explorer's task done. + +Playwright owns its upstream browser automation APIs. Existing consumer examples +are reuse inputs, not service dependencies or an estate-wide technology mandate. +Reuse-surface owns capability discovery, relevance, maturity assessment, and the +existing `capability.infotech.headless-browser` record. This repo owns the +provider contract and runtime, not a competing registry or a second browser stack. + +Railiance platform owners govern cluster admission, shared networking and access +policy. Credential custody and identity stay with their established owners. +Service access and test authentication must use those lanes when required; +credentials and browser storage state must not enter ordinary result logs. + +## Initial scope and later decisions + +Start with Chromium, one consumer-independent trial, and the content-explorer +pilot. Native Playwright compatibility is the starting point. The contract +workplan will decide whether remote sessions, submitted jobs, or a combination +best satisfies agent use and artifact retrieval. Transport, endpoint, deployment +binding, package versions, and access mechanism are not selected by this intent. + +Multi-browser coverage, a general browser farm, unrestricted script execution, +arbitrary external-site automation, and a visual-baseline approval product are +outside the initial increment. They require demonstrated demand and explicit +scope decisions. + +## Success and availability + +Success means an independent coding agent follows the published instructions +without copying sibling fixtures, completes the screenshot/keyboard trial, +retrieves evidence, and can distinguish a service outage from a UI failure. +Isolation, timeouts and cleanup must have executed negative-case evidence. + +Planning, registration, image publication and a successful health check alone do +not prove this outcome. Availability advances only with runtime and consumer +receipts. Until then the service is **planned**, with no verified endpoint; +reuse-surface's existing source-reuse evidence remains unchanged. + +See [SCOPE.md](SCOPE.md) for current facts and [workplans](workplans/README.md) +for the staged implementation and verification gates. diff --git a/README.md b/README.md index d6a7cf5..d9656e5 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,18 @@ # rapp-playwright -Railiance wrapper for a playwright and headless chromium environment to support usecase testing. \ No newline at end of file +Railiance package for a Playwright and headless Chromium service that coding +agents can use to arrange UI tests, responsive screenshots, and keyboard journeys. + +**Status: planning only.** No service endpoint, runnable client, browser image, +or launch receipt is available from this repo yet. State Hub registration tracks +the work; it does not establish browser availability. + +- [Intent and ownership](INTENT.md) +- [Current scope](SCOPE.md) +- [Demand and sibling conventions](docs/demand-and-reuse.md) +- [Workplan sequence](workplans/README.md) + +The first consumer is content-explorer (`CONTENT-WP-0000-T04`). Discovery stays +with reuse-surface's existing `capability.infotech.headless-browser` record; +rapp-playwright owns service delivery. Implementation starts with the proposed +consumer contract workplan after the initial planning handoff. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..7d73505 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,22 @@ +# Scope — rapp-playwright + +As of 2026-10-13 this repository contains intent, demand analysis and proposed +delivery workplans. The bootstrap covers planning, State Hub integration and a +reuse-surface handoff. The user requested stopping at that boundary. + +There is no implemented service, client command, browser image, package +declaration, deployment, verified endpoint or browser run. No install, build, +lint or UI-test command is available yet. Documentation and work-record checks +are the applicable verification today. + +Future delivery is tracked in: + +| Workplan | Deliverable | Current state | +| --- | --- | --- | +| RAPP-PLAYWRIGHT-WP-0002 | Agent consumption contract and trial design | Proposed | +| RAPP-PLAYWRIGHT-WP-0003 | Reproducible service, client path and package | Proposed | +| RAPP-PLAYWRIGHT-WP-0004 | Deployment, independent consumer proof and discovery update | Proposed | + +Content-explorer's screenshot/keyboard task remains its own open work. Search +relevance and false-`new` plan-check results remain reuse-surface work. Neither is +completed by this repository's registration. diff --git a/docs/demand-and-reuse.md b/docs/demand-and-reuse.md new file mode 100644 index 0000000..3417e4a --- /dev/null +++ b/docs/demand-and-reuse.md @@ -0,0 +1,66 @@ +# Demand and reuse review — 2026-10-13 + +## Evidence inspected + +- [Content-explorer baseline plan](../../content-explorer/workplans/CONTENT-WP-0000-upstream-baseline.md): + T04 remains `todo`, requesting responsive screenshots and a keyboard walkthrough. +- [Content-explorer scope review](../../content-explorer/history/2026-10-12-1905-scope-against-intent.md): + no Chrome, Chromium, Firefox or Playwright launcher was found in its workstation + check; HTTP page-title retrieval did not produce browser evidence. This is the + consumer's dated observation, not a fresh launcher check in this session. +- [REUSE-IN-0001](../../reuse-surface/intakes/REUSE-IN-0001-headless-browser-runnable-answer.md), + State Hub intake `01a13530-89a8-77b0-bb95-ef16d74bb29b`: asks for current + availability and one verified command path with a page, screenshot and keyboard + interaction. Its owner response assigns browser delivery to rapp-playwright. +- [Existing capability record](../../reuse-surface/registry/capabilities/capability.infotech.headless-browser.md): + `capability.infotech.headless-browser`, D3/A2/C2/R2, with source reuse in + whynot-design, coulomb-social, core-hub and frontend-patterns. The planned + rapp-playwright provider is already named; endpoint and launch are unverified. + +The intake originally sought a workstation trial helper and explicitly did not +request a hosted browser farm. The user's direction for this repo adds a reusable +service. Preserve the small trial as the first acceptance gate while resolving +service transport and deployment in a dedicated contract step. Do not substitute +a list of source examples or a local installation recipe for the service goal. + +## Demand translated to acceptance + +| Consumer need | Provider requirement | Planned proof | +| --- | --- | --- | +| Can a browser execute now? | Preflight distinguishes service availability, client setup and target reachability | Reachable, unavailable, missing-client and unreachable-target outcomes | +| One useful next command | Versioned client/setup and trial path in provider docs and discovery guidance | Independent agent runs without sibling fixture copying | +| Responsive screenshots | Explicit viewports and downloadable artifacts | Desktop and narrow-viewport receipt | +| Keyboard walkthrough | Defined key sequence, focus/action and result assertions | Recorded interaction steps and observed result | +| Trustworthy result | Run identity, versions, target, timestamps, assertions and failure category | Machine-readable receipt for success and failure | +| Honest discovery | Planned versus verified service availability and provider references | Registry update backed by actual consumer receipt | + +The provider must document target reachability from the browser runtime. Local +development targets and deployed targets have different network requirements. +No arbitrary tunnel or external-site permission is implied by the service. + +The intake's false-`new` verdict and unrelated headless-service matches are +registry relevance issues. They remain reuse-surface's responsibility and do not +justify a duplicate browser capability. A2 means source/library reuse; it does +not mean the caller already has a browser installed. + +## Useful sibling structure + +| Inspected sibling source | Structure adopted here | +| --- | --- | +| [rapp-postgres intent](../../rapp-postgres/INTENT.md) | Purpose, explicit ownership, consumer boundaries and testable isolation | +| [rapp-issue-core intent](../../rapp-issue-core/INTENT.md) | Reproducible runtime, private consumption, version pinning and rollback | +| [rapp-canned-prompts bootstrap](../../rapp-canned-prompts/workplans/RCP-WP-0001-statehub-bootstrap.md) | Review generated integration files, document actual workflow, seed real workplans | +| [rapp-canned-prompts deployment](../../rapp-canned-prompts/workplans/RCP-WP-0002-first-deployment.md) | Separate declared/deployed/verified states and retain live evidence | +| [rapp-telemetry foundation](../../rapp-telemetry/workplans/RAPP-TELEMETRY-WP-0001-foundation.md) | Staged declaration, admission, runtime proof and owner dependencies; infotech/stack placement | + +Workplans use YAML frontmatter, stable repo-prefixed IDs, one fenced `task` block +per task section, explicit dependencies and acceptance evidence. Future delivery +is `proposed`/`todo`; bootstrap completion is not implementation completion. + +## Handoff + +An initial TAMQ update to reuse-surface was queued as +`m-dccbea4a-ac16-410e-a167-2d2dd8cc27a6`, confirming delivery ownership and planned +status. The final handoff will carry the registration and workplan references. +Reuse-surface remains the canonical record maintainer; no duplicate registry +entry is created here. diff --git a/workplans/RAPP-PLAYWRIGHT-WP-0001-statehub-bootstrap.md b/workplans/RAPP-PLAYWRIGHT-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..788a357 --- /dev/null +++ b/workplans/RAPP-PLAYWRIGHT-WP-0001-statehub-bootstrap.md @@ -0,0 +1,61 @@ +--- +id: RAPP-PLAYWRIGHT-WP-0001 +type: workplan +title: "Establish intent, delivery plans and State Hub integration" +domain: infotech +repo: rapp-playwright +topic_slug: stack +status: active +flavor: planning +owner: codex +created: "2026-10-13" +updated: "2026-10-13" +reuse_check: "Extend capability.infotech.headless-browser with a provider; preserve existing source-reuse evidence." +--- + +# Establish the provider planning baseline + +The requested stopping point is documentation, registration and notification. +Service implementation belongs to the subsequent proposed workplans. + +## Review demand and establish intent + +```task +id: RAPP-PLAYWRIGHT-WP-0001-T01 +status: done +priority: high +``` + +Reviewed CONTENT-WP-0000-T04, REUSE-IN-0001 and the existing capability record. +Recorded evidence and adopted sibling structures in `docs/demand-and-reuse.md`. +Authored `INTENT.md` and `SCOPE.md` with delivery ownership, consumer boundaries, +testable success criteria and planned availability. Sent the initial +reuse-surface update; no runtime availability was claimed. + +## Establish integration files and staged workplans + +```task +id: RAPP-PLAYWRIGHT-WP-0001-T02 +status: progress +priority: high +``` + +Review registration-generated AGENTS.md and offline brief. Document the actual +planning-only developer workflow. Verify the three proposed workplans cover +contract, reproducible service/package, and independent consumer proof with +dependencies and acceptance criteria. Validate links, work-record shape and +absence of unresolved template placeholders. + +## Register, verify projection and notify reuse-surface + +```task +id: RAPP-PLAYWRIGHT-WP-0001-T03 +status: todo +priority: high +``` + +Register rapp-playwright under infotech/stack with its actual checkout and Forge +remote. Synchronize all four workplans and their tasks, and verify repository, +host path and work records in State Hub. Notify reuse-surface with provider docs, +workplan references and the planned-only availability boundary. Retain receipts +in `docs/evidence/`. Stop after this handoff. diff --git a/workplans/RAPP-PLAYWRIGHT-WP-0002-consumer-contract.md b/workplans/RAPP-PLAYWRIGHT-WP-0002-consumer-contract.md new file mode 100644 index 0000000..2738aec --- /dev/null +++ b/workplans/RAPP-PLAYWRIGHT-WP-0002-consumer-contract.md @@ -0,0 +1,76 @@ +--- +id: RAPP-PLAYWRIGHT-WP-0002 +type: workplan +title: "Define the agent consumption contract and first browser trial" +domain: infotech +repo: rapp-playwright +topic_slug: stack +status: proposed +flavor: planning +owner: codex +depends_on: [RAPP-PLAYWRIGHT-WP-0001] +created: "2026-10-13" +updated: "2026-10-13" +reuse_check: "Extend capability.infotech.headless-browser; inspect its existing Playwright examples before implementing a wrapper." +--- + +# Agent consumption contract + +Entry: bootstrap and demand review exist. Exit: a reviewed contract and executable +trial specification cover the complete agent path without claiming availability. + +## Choose execution and target connectivity + +```task +id: RAPP-PLAYWRIGHT-WP-0002-T01 +status: todo +priority: high +``` + +Inspect the registered JS and Python examples and current upstream Playwright +contracts. Decide native remote sessions versus submitted jobs, documenting +client compatibility, artifact retrieval, per-run isolation and operational cost. +Define how workstation development servers and deployed URLs become reachable +from the browser. Record supported target/access boundaries and actionable +failure behavior. Avoid assuming remote localhost reaches the consumer. + +Acceptance: a decision record with a complete fresh-agent sequence, required +client setup, version negotiation/pinning, connectivity path and deployment owner. +No speculative endpoint is presented as live. + +## Specify availability, run lifecycle and evidence + +```task +id: RAPP-PLAYWRIGHT-WP-0002-T02 +status: todo +priority: high +``` + +Define preflight, run/session creation, progress, terminal result, cancellation, +timeouts and cleanup. Specify request inputs (target, viewports, actions/assertions, +time budget) and result fields (run ID, execution location, versions, target, +timestamps, per-assertion outcome, error category and artifact references). +Define artifact retention and authorized retrieval, and exclusion of credentials +and storage state from ordinary evidence. Distinguish unavailable service, +unreachable target, browser launch failure and failed UI assertion. + +Acceptance: documented request/result examples for success, UI failure and setup +failure; defined limits and lifecycle semantics; planned availability is explicit. + +## Design the minimal trial and content-explorer pilot + +```task +id: RAPP-PLAYWRIGHT-WP-0002-T03 +status: todo +priority: high +``` + +Specify a tiny JS-enabled fixture with deterministic interaction, desktop and +narrow viewports, a keyboard focus/action sequence and an observable assertion. +Write the proposed one-command trial flow including artifact retrieval. Map it +to CONTENT-WP-0000-T04 and identify the consumer-owned pinned OnCo target and +acceptance responsibilities. Agree on useful evidence without importing OnCo +or treating the fixture trial as the consumer's completed task. + +Acceptance: trial specification and consumer checklist are traceable to every +demand row; integration and failure cases are ready for WP-0003 implementation. diff --git a/workplans/RAPP-PLAYWRIGHT-WP-0003-service-package.md b/workplans/RAPP-PLAYWRIGHT-WP-0003-service-package.md new file mode 100644 index 0000000..d167a87 --- /dev/null +++ b/workplans/RAPP-PLAYWRIGHT-WP-0003-service-package.md @@ -0,0 +1,87 @@ +--- +id: RAPP-PLAYWRIGHT-WP-0003 +type: workplan +title: "Implement the reproducible browser service and Railiance package" +domain: infotech +repo: rapp-playwright +topic_slug: stack +status: proposed +flavor: implementation +owner: codex +depends_on: [RAPP-PLAYWRIGHT-WP-0002] +created: "2026-10-13" +updated: "2026-10-13" +reuse_check: "Use upstream Playwright/Chromium and existing consumer patterns; build only the missing provider integration." +--- + +# Service and package implementation + +Entry: WP-0002 contract reviewed. Exit: reproducible package and supported agent +path pass local integration and negative-case checks; live availability remains +unverified until WP-0004. + +## Package compatible Playwright and Chromium + +```task +id: RAPP-PLAYWRIGHT-WP-0003-T01 +status: todo +priority: high +``` + +Pin compatible client/server/browser versions, OS dependencies and build inputs. +Implement the chosen runtime, health and launch preflight; record browser version +and release identity. Follow current Railiance package/declaration schemas and +publish an immutable image with a verifiable digest when the build is ready. + +Acceptance: clean build launches Chromium against the fixture, version mismatch +fails clearly, image identity is reproducible and build/run instructions work. + +## Implement the agent path and artifact retrieval + +```task +id: RAPP-PLAYWRIGHT-WP-0003-T02 +status: todo +priority: high +``` + +Implement the contract's supported client or CLI path, preflight, run lifecycle, +result format and artifact retrieval. Deliver the standalone trial fixture and +documented command, including consumer dev-server reachability and required +setup. Reuse native Playwright APIs where they already solve the need. + +Acceptance: a fresh client runs the fixture, captures both viewports and keyboard +evidence, retrieves receipts/artifacts and gets distinct non-success outcomes +for setup failures and deliberately failing UI assertions. + +## Enforce isolation, limits and cleanup + +```task +id: RAPP-PLAYWRIGHT-WP-0003-T03 +status: todo +priority: high +``` + +Implement per-run browser/profile and artifact boundaries, access control, +target policy, bounded concurrency/time/resources, cancellation and abandoned-run +reaping. Use established credential custody if the contract requires credentials. + +Acceptance: execute cross-run cookie/storage/artifact access attempts, over-limit +submissions, timeout/cancel/disconnect and crash cases. Show denied access, +diagnosable outcomes and no leaked browser processes or retained sensitive state. + +## Prepare managed deployment and operations + +```task +id: RAPP-PLAYWRIGHT-WP-0003-T04 +status: todo +priority: high +``` + +Author the rapp declaration and deployment resources for the selected runtime, +with private access, resource limits, image digest, probes, network policy, +artifact lifecycle and owner bindings. Document capacity, upgrades, rollback and +operator diagnostics. Validate against current Railiance schemas and render tools. + +Acceptance: package validation and rendering pass; installation, smoke and +rollback commands are reviewable. Readiness reflects only evidence obtained; +local build success does not imply deployed service availability. diff --git a/workplans/RAPP-PLAYWRIGHT-WP-0004-consumer-verification.md b/workplans/RAPP-PLAYWRIGHT-WP-0004-consumer-verification.md new file mode 100644 index 0000000..e084768 --- /dev/null +++ b/workplans/RAPP-PLAYWRIGHT-WP-0004-consumer-verification.md @@ -0,0 +1,78 @@ +--- +id: RAPP-PLAYWRIGHT-WP-0004 +type: workplan +title: "Activate the service, prove agent consumption and update discovery" +domain: infotech +repo: rapp-playwright +topic_slug: stack +status: proposed +flavor: implementation +owner: codex +depends_on: [RAPP-PLAYWRIGHT-WP-0003] +created: "2026-10-13" +updated: "2026-10-13" +reuse_check: "Publish provider evidence through existing capability.infotech.headless-browser; do not fork discovery." +--- + +# Live service and consumer proof + +Entry: WP-0003 passed and deployment/access prerequisites are available through +their owners. Exit: a fresh independent agent can execute the documented trial, +content-explorer has a usable evidence path, and discovery accurately describes +the verified contract and its limits. + +## Admit and activate the managed workload + +```task +id: RAPP-PLAYWRIGHT-WP-0004-T01 +status: todo +priority: high +``` + +Confirm capacity, network/target reachability, access and credential lanes with +the responsible platform owners. Deploy the reviewed digest; verify health, +browser launch, result retrieval and failure diagnosis from the consumer network. +Exercise restart/recovery, cancellation and rollback against the deployed runtime. + +Acceptance: retained commands, release digest, endpoint/access documentation, +timestamps and live results demonstrate the contract. Record unavailable owner +dependencies as explicit waits rather than inferring admission from repo setup. + +## Run the independent trial and content-explorer pilot + +```task +id: RAPP-PLAYWRIGHT-WP-0004-T02 +status: todo +priority: high +``` + +Have a fresh coding-agent environment use the public-to-consumers instructions +without installing a local browser or copying sibling fixtures. Retrieve desktop +and narrow screenshots, keyboard interaction outcomes and a machine-readable +receipt. Repeat a failing UI assertion and unreachable-target case for diagnosis. +Then support content-explorer's pinned baseline target and its own T04 evidence +requirements. Keep source/data authorization and consumer task closure with that +repo. Record any remaining consumer gap explicitly. + +Acceptance: independent fixture receipt and consumer pilot evidence identify +commands, client/browser versions, target, assertions and retrievable artifacts; +content-explorer assesses its own completion. A health response alone cannot pass. + +## Publish verified availability and maintain reuse guidance + +```task +id: RAPP-PLAYWRIGHT-WP-0004-T03 +status: todo +priority: high +``` + +Publish the supported contract, setup/trial command, endpoint/access route, +limitations, versions, artifacts and operational evidence. Notify reuse-surface +to update the existing capability record and availability assessment. Supply +the exact usable next step for discovery responses and identify source-only +fallbacks explicitly. Leave registry ranking fixes with reuse-surface. + +Acceptance: inspect the maintained capability and published discovery response +to confirm the provider references and claimed availability match the receipts. +Retain the notification and readback evidence, synchronize work records, and +track any remaining delivery or consumer gap in a live follow-up work record. diff --git a/workplans/README.md b/workplans/README.md new file mode 100644 index 0000000..a884c7b --- /dev/null +++ b/workplans/README.md @@ -0,0 +1,12 @@ +# Workplans + +| ID | Purpose | Depends on | +| --- | --- | --- | +| [RAPP-PLAYWRIGHT-WP-0001](RAPP-PLAYWRIGHT-WP-0001-statehub-bootstrap.md) | Demand, intent, planning and State Hub bootstrap | — | +| [RAPP-PLAYWRIGHT-WP-0002](RAPP-PLAYWRIGHT-WP-0002-consumer-contract.md) | Decide the agent contract and runnable trial | WP-0001 | +| [RAPP-PLAYWRIGHT-WP-0003](RAPP-PLAYWRIGHT-WP-0003-service-package.md) | Implement the runtime, agent path and Railiance package | WP-0002 | +| [RAPP-PLAYWRIGHT-WP-0004](RAPP-PLAYWRIGHT-WP-0004-consumer-verification.md) | Activate, prove consumer use and update discovery | WP-0003 | + +WP-0002 through WP-0004 are proposed work for subsequent sessions. The initial +request ends after documentation, registration and notification; it does not +start service implementation or complete content-explorer's own acceptance task.