aitester-bdd 0.2.0__tar.gz

aitester_bdd-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Lint
+        run: uv run ruff check src/
+      - name: Test
+        run: uv run pytest tests/ -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - name: Build package
+        run: uv build
+      - name: Verify wheel contents
+        run: |
+          pip install dist/*.whl --target /tmp/verify
+          python -c "import sys; sys.path.insert(0,'/tmp/verify'); from aitester_bdd.engine.context import WalkContext; print(WalkContext.from_env())"
+
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - name: Install docs dependencies
+        run: uv sync --extra docs
+      - name: Build docs
+        run: uv run mkdocs build --strict
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        id: deployment
+        uses: actions/deploy-pages@v4

aitester_bdd-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/aitester-bdd
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

aitester_bdd-0.2.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv-cache/
+
+# Tools
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Robot Framework artifacts
+log.html
+report.html
+output.xml
+selenium-screenshot-*.png
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project-specific
+output/
+debug/
+*.local.yaml
+.env
+failures.jsonl
+walk_log.jsonl
+emit.jsonl
+site/

aitester_bdd-0.2.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-16
+
+### Added
+
+- **`I explore` keyword** — fluid LLM-driven test execution within the rule DAG. The walker hands its browser session to the agent loop at topo-sort time; no separate browser lifecycle.
+- **`I explore and author` keyword** — same as explore, but also writes a pinned `.robot` suite from the journey.
+- **`I ask LLM` action + `llm_response_contains` / `llm_response_semantic` state checks** — interact with LLMs as a plan-phase action (deferred execution, not immediate).
+- **WalkContext dataclass** — centralizes runtime configuration (headed, step_delay_ms, run_timeout_s, disabled_aspects). Replaces scattered `os.environ.get()` calls.
+- **`step_delay` aspect** — step delay is now a proper AOP aspect (fires via `after_action` hook), not an inline `time.sleep`.
+- **`--headed` and `--step-delay` CLI flags** on `aitester run` for visual observation.
+- **Three runtime backends** — `agent-browser` (default, zero-install), `playwright` (in-process speed), `nodriver` (bot-detection-resistant). Declared via `${ENGINE}` variable in the suite.
+- **Session isolation** — each adapter instance gets its own session UUID; cookies never leak between test runs or authoring sessions.
+- **Scenario isolation** — `clear_state()` between scenarios so each Robot test case starts clean.
+- **`state_setup` configuration** — suite-level auth/consent actions that run once before any scenario.
+- **Quality gates** — `min_records`, `filled_pct`, `max_failed_pct` assertions on captured artifacts.
+- **Expansion (TIER 2)** — parametric capture over elements or Cartesian combinations.
+- **`visual_semantic` state check** — multimodal screenshot-to-LLM judge.
+- **Shell action + assertions** — `When I run shell`, `Then last shell exit`, stdout/stderr checks.
+- **GitHub Actions CI** — lint + test on Python 3.11/3.12/3.13, build verification, docs deployment.
+- **`py.typed` marker** — enables downstream type checking.
+
+### Changed
+
+- **Headed mode now works for all backends** — previously the walker always passed `headless=True` regardless of env var. Now `WalkContext.headed` flows correctly to `BrowserAdapter.new_session()`.
+- **Aspect disabling centralized** — `AITESTER_DISABLE_ASPECTS` is read once at `WalkContext` construction, not per-registry-build.
+
+### Fixed
+
+- Duplicate `SKILL.md` in wheel (force-include removed; `packages` directive already includes it).
+- Test suite: `declare_parents` → `and_declare_parents`, `set_rule_timeout` → `and_set_rule_timeout` renames propagated to all tests.
+- 138 lint errors resolved (unused imports, `Optional` → `X | None`, import ordering, undefined forward refs).
+
+## [0.1.0] - 2026-04-01
+
+### Added
+
+- Initial release: keyword library, walker, BrowserAdapter, AspectRegistry, trajectory/instrument/diagnose aspects.
+- Authoring agent loop (DeepAgents + LangGraph) with `aitester author` CLI.
+- `aitester run` CLI for executing authored suites.
+- Rule DAG with parent-child composition, guards, retry-redo, interrupt dismissal.
+- SKILL.md grammar reference for the authoring agent.
+- Wikipedia quickstart example.

aitester_bdd-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kundeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aitester_bdd-0.2.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: aitester-bdd
+Version: 0.2.0
+Summary: LLM-driven BDD test authoring for Robot Framework — turn an intention + live app into a .robot suite
+Project-URL: Homepage, https://github.com/kundeng/aitester-bdd
+Project-URL: Repository, https://github.com/kundeng/aitester-bdd
+Project-URL: Issues, https://github.com/kundeng/aitester-bdd/issues
+Author: kundeng
+License: MIT
+License-File: LICENSE
+Keywords: ai,bdd,llm,robotframework,test-generation,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Robot Framework
+Classifier: Framework :: Robot Framework :: Library
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing :: Acceptance
+Classifier: Topic :: Software Development :: Testing :: BDD
+Requires-Python: >=3.11
+Requires-Dist: deepagents>=0.0.15
+Requires-Dist: langchain-openai>=0.2
+Requires-Dist: langchain>=0.3
+Requires-Dist: langgraph>=0.2.50
+Requires-Dist: litellm>=1.50
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: robotframework>=7.0
+Requires-Dist: typer>=0.12
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.45; extra == 'playwright'
+Requires-Dist: robotframework-browser>=18.0; extra == 'playwright'
+Provides-Extra: stealth
+Requires-Dist: nodriver>=0.40; extra == 'stealth'
+Description-Content-Type: text/markdown
+
+# aitester-bdd
+
+**LLM-driven BDD test authoring for Robot Framework.** Give it a story and a live web app; an agent explores the target via the `agent-browser` CLI, then writes a deterministic `.robot` suite with selectors grounded in the actual DOM it observed — or files a bug report when the system is broken in a way that prevents authoring.
+
+## What it is
+
+A Robot Framework library that turns a plain-English intention into a deterministic, executable `.robot` test suite. **Run-time has no LLM in the loop** — the authored suite is plain RF code that runs reproducibly, no tokens consumed on PR gates.
+
+## What's novel
+
+| | aitester-bdd |
+|---|---|
+| **Intention → `.robot` suite** | An agent loop drives the live target via shell-out to `agent-browser` (Playwright under the hood), writes a Robot Framework suite with selectors grounded in the snapshots it actually took. |
+| **Bug-report exit channel** | When the SUT is broken in a way that prevents authoring (missing UI, broken auth flow, untestable terminal state), the agent writes `triage/<story>.md` rather than inventing selectors. |
+| **Three pluggable runtime backends** | `agent-browser` (default, zero-install) / `playwright` (in-process speed) / `nodriver` (bot-detection-resistant). Same `.robot` runs on any. |
+| **AOP failure aspect** | Each failed rule ships with an AI-written natural-language diagnosis (SUT-vs-test classification) plus a full MDP trajectory in `walk_log.jsonl`. |
+| **Rule DAG with parent-child composition** | Ported from WISE RPA BDD. Position-determined state checks (guard vs observation), retry-with-redo, scope inheritance — all expressed via Given/When/Then. |
+
+## Status
+
+**Alpha.** Authoring verified end-to-end on public sites (example.com, en.wikipedia.org, the-internet.herokuapp.com) and on a real internal SPA (login + chat + tool-rendering verification).
+
+## How fast is it?
+
+Authoring is **headless DeepAgents on Claude Opus 4.7** shelling out to the `agent-browser` CLI. Typical wall-time for a single suite:
+
+| Site / scope | Steps | Wall time |
+|---|---:|---:|
+| example.com smoke (heading + link) | 9 | ~27s |
+| en.wikipedia.org search + article check (5 assertions) | 27 | ~70s |
+| Real SPA login + chat + multi-rule verification | 50-80 | 2-3 min |
+
+The agent batches multiple `agent-browser` subcommands per shell call (`open && snapshot && get count ...`) so ~1 LLM round-trip handles 2-4 browser ops. Most remaining wall-time is **SUT-bound** (waiting for the app's own LLM to stream a response) — not authoring overhead.
+
+## Quick start
+
+```bash
+# 1. Install
+pip install aitester-bdd
+npm i -g agent-browser
+
+# 2. Point at an LLM endpoint. Defaults assume claude-code-proxy:
+export AITESTER_LLM_MODEL=cc/claude-opus-4-7
+export OPENAI_BASE_URL=http://localhost:20128/v1
+export OPENAI_API_KEY=placeholder
+
+# 3. Author a suite from a story
+aitester author \
+  --story "Open the homepage, search for 'BDD', verify the article heading and a paragraph containing 'BDD'." \
+  --base-url https://en.wikipedia.org \
+  --out wiki_smoke.robot
+
+# 4. Run it (no LLM at run time)
+aitester run wiki_smoke.robot
+```
+
+For visibility into the agent's exploration, add `--debug` to `aitester author`. Every LLM turn and shell call streams to stderr with timestamps.
+
+Output sidecar files at `<output_dir>/`:
+- `walk_log.jsonl` — every MDP transition (rule_enter / before_action / after_action / state_check / dismiss / emit / rule_exit)
+- `failures.jsonl` — failure context + AI diagnosis for every failed rule
+- `emit.jsonl` — explicit `And I emit "..."` captures (intention-driven; only when the story is a diagnostic probe)
+
+## Three runtime backends, one authored suite
+
+`AITESTER_BROWSER=` picks the driver at run-time:
+
+| Backend | Default? | Setup | Best for |
+|---------|----------|-------|----------|
+| `agent-browser` | ✓ | none — CLI ships its own browser | most cases; same driver author + run, zero install friction |
+| `playwright` | | `aitester init-browser` once | action-heavy tests where subprocess latency matters |
+| `nodriver` | | `pip install aitester-bdd[stealth]` + Edge/Chrome | bot-detected sites (DataDome / Cloudflare BM / etc.) |
+
+Same `.robot` runs on any of the three.
+
+## Architecture (one paragraph)
+
+The LLM is the author, not the runtime. At authoring time, a DeepAgents/LangGraph agent reads `SKILL.md` as its system prompt, drives the live target by shelling out to the `agent-browser` CLI (via DeepAgents' `LocalShellBackend.execute` tool), and emits a `.robot` file with selectors grounded in real snapshots — or writes a bug report when the system is broken in a way that prevents authoring. The agent batches multiple `agent-browser` subcommands per shell call (`open && snapshot && get count …`) so each LLM round-trip drives multiple browser ops. At run time, plain Robot Framework executes the suite via one of three pluggable browser backends; no LLM in the loop. Failures fire an AOP `diagnose` aspect that hands the LLM the MDP trajectory plus snapshot and asks "why?" — short natural-language diagnoses land on `RuleResult.ai_diagnosis` and `failures.jsonl`. The walker, gotcha-fixes, and AspectRegistry are ported from the WISE RPA BDD skill.
+
+## License
+
+MIT

aitester_bdd-0.2.0/README.md

@@ -0,0 +1,82 @@
+# aitester-bdd
+
+**LLM-driven BDD test authoring for Robot Framework.** Give it a story and a live web app; an agent explores the target via the `agent-browser` CLI, then writes a deterministic `.robot` suite with selectors grounded in the actual DOM it observed — or files a bug report when the system is broken in a way that prevents authoring.
+
+## What it is
+
+A Robot Framework library that turns a plain-English intention into a deterministic, executable `.robot` test suite. **Run-time has no LLM in the loop** — the authored suite is plain RF code that runs reproducibly, no tokens consumed on PR gates.
+
+## What's novel
+
+| | aitester-bdd |
+|---|---|
+| **Intention → `.robot` suite** | An agent loop drives the live target via shell-out to `agent-browser` (Playwright under the hood), writes a Robot Framework suite with selectors grounded in the snapshots it actually took. |
+| **Bug-report exit channel** | When the SUT is broken in a way that prevents authoring (missing UI, broken auth flow, untestable terminal state), the agent writes `triage/<story>.md` rather than inventing selectors. |
+| **Three pluggable runtime backends** | `agent-browser` (default, zero-install) / `playwright` (in-process speed) / `nodriver` (bot-detection-resistant). Same `.robot` runs on any. |
+| **AOP failure aspect** | Each failed rule ships with an AI-written natural-language diagnosis (SUT-vs-test classification) plus a full MDP trajectory in `walk_log.jsonl`. |
+| **Rule DAG with parent-child composition** | Ported from WISE RPA BDD. Position-determined state checks (guard vs observation), retry-with-redo, scope inheritance — all expressed via Given/When/Then. |
+
+## Status
+
+**Alpha.** Authoring verified end-to-end on public sites (example.com, en.wikipedia.org, the-internet.herokuapp.com) and on a real internal SPA (login + chat + tool-rendering verification).
+
+## How fast is it?
+
+Authoring is **headless DeepAgents on Claude Opus 4.7** shelling out to the `agent-browser` CLI. Typical wall-time for a single suite:
+
+| Site / scope | Steps | Wall time |
+|---|---:|---:|
+| example.com smoke (heading + link) | 9 | ~27s |
+| en.wikipedia.org search + article check (5 assertions) | 27 | ~70s |
+| Real SPA login + chat + multi-rule verification | 50-80 | 2-3 min |
+
+The agent batches multiple `agent-browser` subcommands per shell call (`open && snapshot && get count ...`) so ~1 LLM round-trip handles 2-4 browser ops. Most remaining wall-time is **SUT-bound** (waiting for the app's own LLM to stream a response) — not authoring overhead.
+
+## Quick start
+
+```bash
+# 1. Install
+pip install aitester-bdd
+npm i -g agent-browser
+
+# 2. Point at an LLM endpoint. Defaults assume claude-code-proxy:
+export AITESTER_LLM_MODEL=cc/claude-opus-4-7
+export OPENAI_BASE_URL=http://localhost:20128/v1
+export OPENAI_API_KEY=placeholder
+
+# 3. Author a suite from a story
+aitester author \
+  --story "Open the homepage, search for 'BDD', verify the article heading and a paragraph containing 'BDD'." \
+  --base-url https://en.wikipedia.org \
+  --out wiki_smoke.robot
+
+# 4. Run it (no LLM at run time)
+aitester run wiki_smoke.robot
+```
+
+For visibility into the agent's exploration, add `--debug` to `aitester author`. Every LLM turn and shell call streams to stderr with timestamps.
+
+Output sidecar files at `<output_dir>/`:
+- `walk_log.jsonl` — every MDP transition (rule_enter / before_action / after_action / state_check / dismiss / emit / rule_exit)
+- `failures.jsonl` — failure context + AI diagnosis for every failed rule
+- `emit.jsonl` — explicit `And I emit "..."` captures (intention-driven; only when the story is a diagnostic probe)
+
+## Three runtime backends, one authored suite
+
+`AITESTER_BROWSER=` picks the driver at run-time:
+
+| Backend | Default? | Setup | Best for |
+|---------|----------|-------|----------|
+| `agent-browser` | ✓ | none — CLI ships its own browser | most cases; same driver author + run, zero install friction |
+| `playwright` | | `aitester init-browser` once | action-heavy tests where subprocess latency matters |
+| `nodriver` | | `pip install aitester-bdd[stealth]` + Edge/Chrome | bot-detected sites (DataDome / Cloudflare BM / etc.) |
+
+Same `.robot` runs on any of the three.
+
+## Architecture (one paragraph)
+
+The LLM is the author, not the runtime. At authoring time, a DeepAgents/LangGraph agent reads `SKILL.md` as its system prompt, drives the live target by shelling out to the `agent-browser` CLI (via DeepAgents' `LocalShellBackend.execute` tool), and emits a `.robot` file with selectors grounded in real snapshots — or writes a bug report when the system is broken in a way that prevents authoring. The agent batches multiple `agent-browser` subcommands per shell call (`open && snapshot && get count …`) so each LLM round-trip drives multiple browser ops. At run time, plain Robot Framework executes the suite via one of three pluggable browser backends; no LLM in the loop. Failures fire an AOP `diagnose` aspect that hands the LLM the MDP trajectory plus snapshot and asks "why?" — short natural-language diagnoses land on `RuleResult.ai_diagnosis` and `failures.jsonl`. The walker, gotcha-fixes, and AspectRegistry are ported from the WISE RPA BDD skill.
+
+## License
+
+MIT

aitester_bdd-0.2.0/dev/architecture.md

@@ -0,0 +1,99 @@
+# Architecture
+
+## Three layers
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Authoring (LLM-in-the-loop, one-shot per suite)                 │
+│  ─────────────────────────────────────────────────────────────   │
+│  DeepAgents loop on top of LangGraph:                            │
+│    - SKILL.md as system prompt                                   │
+│    - TodoListMiddleware (planning) + LocalShellBackend (execute) │
+│    - Tool surface: `execute` (bash) + write_robot_suite +        │
+│      report_bug. No per-operation Python wrappers — the agent    │
+│      shells out to `agent-browser <subcommand> --json`,          │
+│      batching with `&&`.                                         │
+│  Retry harness wraps the inner loop (max_attempts, default 2)    │
+│  so a crash / recursion-limit retries with feedback.             │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              │ produces
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  Runtime (deterministic, no LLM)                                 │
+│  ─────────────────────────────────────────────────────────────   │
+│  • Robot Framework parses + walks the .robot file                │
+│  • aitester-bdd keyword library: rule DAG, observation gates,    │
+│    position-determined state checks, retry-with-redo guards      │
+│  • One of three browser backends (declared via ${ENGINE}):       │
+│      - agent-browser (default) — CLI subprocess, zero install    │
+│      - playwright (in-process) — install rfbrowser + browsers    │
+│      - nodriver (raw CDP) — bot-detection-resistant              │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              │ emits
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  Diagnostics                                                     │
+│  ─────────────────────────────────────────────────────────────   │
+│  • RF log.html / report.html / output.xml                        │
+│  • Verdict report (pass/fail per rule, evidence on failure)      │
+│  • Optional LLM post-mortem on failure (read RF log, suggest fix)│
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Heritage from WISE RPA BDD
+
+The engine borrows the Plan-then-Execute rule DAG model from the WISE RPA BDD skill — Robot Framework keywords build an in-memory plan during test case definition, then a single Suite Teardown step (`Then I finalize`) walks the plan against a live browser. This separates the **spec** (the rule tree) from the **execution** (the browser walk), which is what makes:
+
+- LLM-authored output deterministic (the LLM commits to a plan up front)
+- Observation gates clean (position-determined: before-action = guard, after-action = sync gate)
+- Parent-child rule composition meaningful (rules can declare prerequisite rules; the walker handles ordering)
+- Aspects (timing, screenshots, slow-mo, checkpoint) cross-cutting (modify behavior without touching rules)
+
+## What's different from WISE
+
+WISE's vocabulary is for **extraction**: artifacts, emits, merges, quality gates on extracted records. aitester-bdd's vocabulary is for **verification**: assertions on state, no data collection. The keyword library is a from-scratch design; only the underlying engine primitives carry over.
+
+## Two discovery modes
+
+### Black-box (Mode A)
+
+Input: a story + base_url. No source access. Agent crawls via accessibility snapshots, identifies entry points by looking.
+
+Use: validating customer-facing behavior of a deployed app you don't own; smoke-testing in foreign environments.
+
+Limitation: invisible code paths (admin-only routes, conditional features) stay invisible.
+
+### White-box (Mode B)
+
+Input: a story + base_url + source_root. Reads framework-specific source (FastAPI routes, React TSX components, Zustand stores). Cross-references against live snapshots to ground selectors.
+
+Use: testing apps you own with full source access. More complete coverage.
+
+Mode B internally falls back to Mode A for selector grounding — TSX source doesn't always tell you the rendered class (shadcn wraps, Tailwind transforms), so a live snapshot is still required for the actual selector.
+
+## Skill as grammar
+
+The `SKILL.md` shipped inside the wheel is the LLM's grammar at authoring time. It documents:
+
+- The shipped keyword vocabulary (Given/When/Then with concrete primitives)
+- The rule DAG shape (parents, guards, observations, actions, assertions)
+- The non-negotiables (no `When I wait`, no invented site-specific verbs, all selectors must come from a live snapshot)
+- The patterns library (auth flow, observation gates, dismiss scoping)
+- The agent contract (what the LLM is and isn't authorized to do)
+
+Without the skill loaded, the LLM emits prose. With it, the LLM emits valid `.robot` files that the engine can execute.
+
+## Where the LLM is and isn't in the loop
+
+| Phase | LLM? | Why |
+|---|---|---|
+| Discovery | Yes | Reads source, snapshots app, proposes structure |
+| Authoring | Yes | Composes the .robot file from story + snapshot |
+| Dryrun | No | Plain `robot --dryrun` — fast, no tokens |
+| Execution | No | Plain Robot Framework — deterministic, no tokens |
+| Diagnostics on failure | Optional | LLM can read RF log.html and suggest a refine, but the failure detection itself is non-LLM |
+| Refinement (loop) | Yes | Failed dryrun or execution feeds back into authoring |
+
+Token cost is bounded: one author call + N refine calls per scenario. Production CI runs `.robot` files plain — no LLM cost on PR gates.

aitester_bdd-0.2.0/dev/ideas.md

@@ -0,0 +1,39 @@
+# Ideas (parking lot)
+
+Items here are not committed work — just things we've thought about.
+File a real GitHub issue if/when one of these graduates to being scheduled.
+
+---
+
+## Inception: self-hosted explore + execute keywords
+
+Make the framework self-testable. Add two **private** Robot keywords next to the
+existing `aitester author` / `aitester run` CLI:
+
+```robot
+When I explore "${story}" against "${url}" into "${suite_path}"
+When I execute "${suite_path}"
+Then verdict last passed
+```
+
+- Thin wrappers over `authoring.agent_loop.author_with_agent` and
+  `engine.walk.run_suite` (the same code paths the CLI uses today).
+- The skill (SKILL.md) is already embeddable via `aitester_bdd.skill.load_skill()`;
+  meta-tests can reference the loader without duplicating content.
+- Ship a small suite under `aitester_bdd/meta/` (e.g. `meta/explore.robot`,
+  `meta/execute.robot`) that exercises both keywords against a fixed simple
+  target (example.com or a local httpbin).
+- CLI commands collapse to convenience over the keywords.
+
+**Cost / friction:**
+
+- `I explore` invokes a real LLM — ~30-60s + LLM cost per run. Best as a
+  nightly soak gate, not every-commit CI.
+- Meta-tests must assert on *structure* (suite parses, executes, passes /
+  fails as expected), not exact selectors — the LLM will produce slightly
+  different suites across runs.
+- ~250 LOC + 2-3 fixture stories + 1 small CLI subcommand for `aitester meta`.
+
+**Why park it:** worth doing once aitester-bdd is stable enough to be
+its own customer. Not blocking the migration of the prismi3 tests off the
+vendored `src/aitester/`.

aitester_bdd-0.2.0/docs/changelog.md

@@ -0,0 +1,3 @@
+# Changelog
+
+See [CHANGELOG.md](https://github.com/kundeng/aitester-bdd/blob/main/CHANGELOG.md) for the full release history.