# Plan: Browser QA Integration

## Overview

Add a canonical browser QA workflow that integrates the existing browser runtime,
browser evidence, and workflow evidence skills without copying gstack's fat-skill
architecture. The plan promotes `browser-qa` as the new workflow-level name,
keeps deterministic capture in existing primitives, and migrates `web-qa` toward
a compatibility role. It also updates plan/execution guidance so browser-facing
acceptance work can require traceable `browser-session` evidence.

## Read First

- Primary source: `docs/plans/browser-qa-integration/browser-qa-integration-discussion-source.md`
- Source type: `discussion-to-implementation-doc`
- Open questions carried into execution: none

## Scope

- In scope: `browser-qa` workflow skill, `web-qa` compatibility treatment,
  catalog/tooling docs, plan/execution guidance, affected automation workflow
  references, a reusable QA report template, and focused tests.
- Out of scope: new nils-cli browser driver, persistent browser daemon,
  project-owned E2E suite design, raw browser profile export, and broad gstack
  workflow cloning.

## Assumptions

1. `browser-qa` is the canonical new name. `web-qa` should not remain the primary
   user-facing name for browser-backed QA.
2. Keep `web-qa` as a compatibility alias for at least one transition unless
   implementation discovers the skill has no external consumers.
3. `browser-qa` is a workflow skill under `skills/workflows/qa/`; lower-level
   primitives remain under `skills/tools/browser/` and
   `skills/tools/workflow-evidence/`.
4. The first implementation should be scriptless unless a deterministic helper is
   clearly needed. Existing primitives should own schemas, redaction, and
   command envelopes.
5. Browser QA evidence must be project-scoped and redacted by default.
6. The gstack QA report template is useful as a report shape, but agent-kit
   should adopt it under the canonical `browser-qa` workflow rather than
   copying gstack's wider `/qa` architecture.

## Sprint 1: Naming And Workflow Boundary

**Goal**: Establish `browser-qa` as the canonical workflow entrypoint while
preserving compatibility for existing `web-qa` references.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k 'browser_qa or web_qa'`,
  `scripts/check.sh --docs`, `scripts/check.sh --markdown`
- Verify: `browser-qa` is discoverable as the workflow name, and `web-qa` is no
  longer documented as the preferred entrypoint.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 1.1: Add the canonical browser-qa workflow skill

- **Location**:
  - `skills/workflows/qa/browser-qa/SKILL.md`
  - `skills/workflows/qa/README.md`
  - `skills/workflows/qa/browser-qa/tests/test_workflows_qa_browser_qa.py`
- **Description**: Create the scriptless workflow skill that owns browser QA
  orchestration. Define when to use it, its modes, required evidence, supported
  drivers, redaction guardrails, and relationship to lower-level primitives.
- **Dependencies**:
  - none
- **Complexity**: 4
- **Acceptance criteria**:
  - Skill contract validates through skill-governance.
  - The skill states that `browser-qa` is the canonical workflow entrypoint.
  - The skill supports report-only, fix-loop, and acceptance-gate modes.
  - The skill explains how it coordinates Browser, Chrome, Playwright,
    `agent-browser`, `web-evidence`, `browser-session`, `test-first-evidence`,
    `canary-check`, `review-evidence`, and `skill-usage`.
  - The workflow does not add placeholder scripts.
- **Validation**:
  - `scripts/check.sh --tests -- skills/workflows/qa/browser-qa/tests/test_workflows_qa_browser_qa.py`
  - `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh`

### Task 1.2: Convert web-qa into an explicit compatibility surface

- **Location**:
  - `skills/tools/browser/evidence/web-qa/SKILL.md`
  - `skills/tools/browser/evidence/web-qa/tests/test_tools_browser_web_qa.py`
- **Description**: Update the existing `web-qa` tool skill so it no longer reads
  as the canonical QA workflow. Preserve useful static/active evidence guidance
  only as a compatibility bridge and route new QA workflow use to `browser-qa`.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 3
- **Acceptance criteria**:
  - `web-qa` clearly says it is a compatibility entrypoint or legacy evidence
    bridge.
  - The compatibility text points to `browser-qa` for new browser-backed QA work.
  - Existing static `web-evidence` and `browser-session` examples remain
    available until references are migrated.
  - Tests fail if `web-qa` is reintroduced as the preferred canonical workflow.
- **Validation**:
  - `scripts/check.sh --tests -- skills/tools/browser/evidence/web-qa/tests/test_tools_browser_web_qa.py`

### Task 1.3: Update catalogs and naming references

- **Location**:
  - `README.md`
  - `skills/README.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
- **Description**: Move browser QA discovery to the workflow layer and keep lower
  browser tooling listed as primitives. Replace "web-qa active mode" wording
  with `browser-qa` where the intended behavior is workflow orchestration.
- **Dependencies**:
  - Task 1.1
  - Task 1.2
- **Complexity**: 3
- **Acceptance criteria**:
  - README lists `browser-qa` under workflow skills and no longer promotes
    `web-qa` as the main browser QA entrypoint.
  - Tooling index distinguishes `browser-qa` workflow from `web-evidence` and
    `browser-session` primitives.
  - Skill usage docs continue to reference `browser-session.json` as the browser
    evidence artifact.
- **Validation**:
  - `scripts/check.sh --docs`
  - `scripts/check.sh --markdown`

## Sprint 2: Integrated Browser QA Workflow

**Goal**: Define the end-to-end QA behavior so browser-facing acceptance checks
produce usable evidence and, when requested, a bounded fix loop.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k 'browser_qa or skill_usage or agent_workflow_primitives'`
- Verify: the new skill contract preserves evidence boundaries and names the
  correct primitive for each QA phase.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 2.1: Define mode selection and scenario intake

- **Location**:
  - `skills/workflows/qa/browser-qa/SKILL.md`
  - `skills/workflows/qa/browser-qa/tests/test_workflows_qa_browser_qa.py`
- **Description**: Specify how agents choose between static evidence, active
  report-only QA, active acceptance-gate QA, and fix-loop QA. Include scenario
  sources such as user requests, plan acceptance criteria, issue reports,
  release checks, CI/deploy previews, and project-specific test plans.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 3
- **Acceptance criteria**:
  - Static HTTP checks route to `web-evidence` only when browser behavior is not
    required.
  - Active browser checks require real browser work before success can be
    recorded.
  - Report-only mode cannot edit files or commit changes.
  - Fix-loop mode requires scoped reproduction evidence before production edits.
- **Validation**:
  - `scripts/check.sh --tests -- skills/workflows/qa/browser-qa/tests/test_workflows_qa_browser_qa.py`

### Task 2.2: Define artifact and redaction requirements

- **Location**:
  - `skills/workflows/qa/browser-qa/SKILL.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `skills/workflows/qa/browser-qa/tests/test_workflows_qa_browser_qa.py`
- **Description**: Define required artifact types for active QA, including
  screenshots, DOM observations, console summaries, network summaries, Playwright
  outputs, and `browser-session.json`. Preserve strict redaction rules for
  screenshots, URLs, storage, cookies, headers, and logs.
- **Dependencies**:
  - Task 2.1
- **Complexity**: 3
- **Acceptance criteria**:
  - Active QA evidence always records `browser-session verify` outcome.
  - The skill forbids retaining raw cookies, credentials, auth headers, tokenized
    URLs, secret form values, storage dumps, or unredacted network logs.
  - The skill explains what to do when only unsafe evidence is available.
  - Playwright artifacts are kept under `out/playwright/` through the existing
    wrapper contract.
- **Validation**:
  - `scripts/check.sh --tests -- -k browser_qa`
  - `scripts/check.sh --docs`

### Task 2.3: Define the bounded fix loop

- **Location**:
  - `skills/workflows/qa/browser-qa/SKILL.md`
  - `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
  - `skills/workflows/qa/browser-qa/tests/test_workflows_qa_browser_qa.py`
- **Description**: Specify the fix-loop path: reproduce with browser evidence,
  capture failing-test evidence or waiver, make the smallest scoped fix, run
  project validation, capture before/after evidence, and record final outcome.
- **Dependencies**:
  - Task 2.1
  - Task 2.2
- **Complexity**: 4
- **Acceptance criteria**:
  - Behavior-changing fixes require `test-first-evidence` failing evidence or an
    explicit waiver.
  - A local one-command canary may use `canary-check` but cannot replace
    project-required tests.
  - QA findings that need durable review tracking can link `review-evidence`.
  - The workflow stops and reports blocked when the fix exceeds scope or requires
    unsafe credentials/actions.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'browser_qa or skill_usage'`

### Task 2.4: Adopt the browser QA report template

- **Location**:
  - `skills/workflows/qa/browser-qa/assets/templates/qa-report-template.md`
  - `skills/workflows/qa/browser-qa/SKILL.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `skills/workflows/qa/browser-qa/tests/test_workflows_qa_browser_qa.py`
- **Description**: Adapt gstack's QA report template into the canonical
  `browser-qa` workflow. Keep it as a reusable report artifact, not a copied
  fat-skill implementation.
- **Dependencies**:
  - Task 2.1
  - Task 2.2
  - Task 2.3
- **Complexity**: 2
- **Acceptance criteria**:
  - The template includes a 0-100 health score and category scores for Console,
    Links, Visual, Functional, UX, Performance, and Accessibility.
  - The template includes before/after screenshot evidence fields for fix-loop
    reports.
  - The template includes a Ship Readiness table and PR summary line.
  - The skill explains when to use the report template and keeps raw evidence in
    `browser-session`, screenshots, Playwright, or static evidence artifacts.
  - Tests fail if the report template loses the scoring, before/after, or Ship
    Readiness sections.
- **Validation**:
  - `scripts/check.sh --tests -- -k browser_qa`
  - `scripts/check.sh --markdown`

## Sprint 3: Plan, CI, Release, And Issue Integration

**Goal**: Make `browser-qa` discoverable from the workflows that already need
browser-facing evidence.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k 'browser_qa or gh_fix_ci or release_workflow or issue_follow_up or plan_workflow'`,
  `scripts/check.sh --docs`
- Verify: plan execution, CI repair, release validation, and issue follow-up
  reference `browser-qa` consistently.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 3.1: Add browser QA guidance to planning and execution

- **Location**:
  - `skills/workflows/plan/create-plan/SKILL.md`
  - `skills/workflows/plan/execute-from-plan/SKILL.md`
  - `skills/workflows/plan/_shared/references/PLAN_AUTHORING_BASELINE.md`
  - `skills/workflows/plan/README.md`
  - `tests/test_plan_workflow_lifecycle_docs.py`
- **Description**: Add guidance that browser-facing acceptance criteria should
  name browser QA evidence when UI, layout, JavaScript, DOM interaction,
  authenticated browser state, console output, network behavior, or deploy
  preview inspection matters. Execution state should link `browser-session`
  evidence instead of copying large reports into the plan.
- **Dependencies**:
  - Task 1.1
  - Task 2.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Plan authoring guidance names `browser-qa` for browser-facing acceptance.
  - `execute-from-plan` records browser QA artifact paths in validation evidence.
  - Docs preserve that browser QA is conditional, not mandatory for every task.
- **Validation**:
  - `scripts/check.sh --tests -- tests/test_plan_workflow_lifecycle_docs.py`
  - `scripts/check.sh --docs`

### Task 3.2: Update automation workflow references

- **Location**:
  - `skills/automation/ci/gh-fix-ci/SKILL.md`
  - `skills/automation/ci/gh-fix-ci/tests/test_automation_gh_fix_ci.py`
  - `skills/automation/release/release-workflow/SKILL.md`
  - `skills/automation/release/release-workflow/tests/test_automation_release_workflow.py`
  - `skills/workflows/issue/issue-follow-up/SKILL.md`
  - `skills/workflows/issue/issue-follow-up/tests/test_workflows_issue_issue_follow_up.py`
- **Description**: Replace `web-qa active mode` references with `browser-qa`
  where the workflow needs browser behavior. Keep `web-evidence` references for
  static URL checks.
- **Dependencies**:
  - Task 1.3
- **Complexity**: 3
- **Acceptance criteria**:
  - CI repair guidance uses `browser-qa` for deploy previews and browser-only
    status evidence.
  - Release guidance uses `browser-qa` when validation requires JavaScript,
    screenshots, auth/cookies, console logs, or browser state.
  - Issue follow-up guidance uses `browser-qa` for browser-session evidence and
    keeps `web-evidence` for static HTTP evidence.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'gh_fix_ci or release_workflow or issue_follow_up'`

### Task 3.3: Add stale-reference and compatibility tests

- **Location**:
  - `skills/workflows/qa/browser-qa/tests/test_workflows_qa_browser_qa.py`
  - `skills/tools/browser/evidence/web-qa/tests/test_tools_browser_web_qa.py`
  - `tests/test_agent_workflow_primitives_skills.py`
  - `tests/test_docs_freshness_audit.py`
- **Description**: Add or update focused assertions so old `web-qa` wording does
  not creep back into canonical docs while compatibility references remain
  intentional.
- **Dependencies**:
  - Task 1.2
  - Task 1.3
  - Task 3.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Tests allow `web-qa` only in the compatibility skill and explicit migration
    notes.
  - Tests assert `browser-session` remains a primitive evidence recorder, not a
    browser driver.
  - Docs freshness and skill contract checks pass after path/catalog updates.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'browser_qa or web_qa or agent_workflow_primitives or docs_freshness'`

## Sprint 4: Repository Gate And Rollout Notes

**Goal**: Validate the whole integration and leave a clear follow-up path for
eventual `web-qa` removal if desired.
**Demo/Validation**:

- Command(s): `scripts/check.sh --pre-commit`
- Verify: all docs, skill contract, markdown, script, and test gates pass.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 4.1: Run full validation and fix drift

- **Location**:
  - repository-wide validation output
- **Description**: Run the repository gate, fix docs/index/test drift, and ensure
  any new skill path is represented in catalog and governance checks.
- **Dependencies**:
  - Task 1.1
  - Task 1.2
  - Task 1.3
  - Task 2.1
  - Task 2.2
  - Task 2.3
  - Task 2.4
  - Task 3.1
  - Task 3.2
  - Task 3.3
- **Complexity**: 2
- **Acceptance criteria**:
  - `scripts/check.sh --pre-commit` passes or any residual failure is documented
    with exact command output and owner.
  - No generated or run artifacts are committed unless they are project-defined
    documentation or tests.
- **Validation**:
  - `scripts/check.sh --pre-commit`

### Task 4.2: Document the web-qa removal decision point

- **Location**:
  - `skills/tools/browser/evidence/web-qa/SKILL.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - optional follow-up issue or `docs/plans/` source if removal is deferred
- **Description**: Make the transition state explicit. If `web-qa` remains, state
  the compatibility window and the criteria for future removal. If it is removed
  in the same implementation, document the breaking-change rationale and update
  all references.
- **Dependencies**:
  - Task 4.1
- **Complexity**: 2
- **Acceptance criteria**:
  - Future agents can tell whether `web-qa` is a supported alias, deprecated
    compatibility surface, or removed skill.
  - Any deferred removal has a clear tracker or documented cleanup condition.
- **Validation**:
  - `scripts/check.sh --docs`
  - `scripts/check.sh --markdown`

## Testing Strategy

- Unit/docs tests: add focused tests for `browser-qa` skill wording, mode
  selection, primitive boundaries, report template fields, and redaction
  guardrails.
- Integration-style docs tests: update existing workflow tests for CI, release,
  issue follow-up, and plan lifecycle references.
- Skill governance: run `validate_skill_contracts.sh` and layout checks after
  adding the new workflow skill.
- Repository gate: run `scripts/check.sh --pre-commit` before commit.

## Risks & gotchas

- Renaming `web-qa` too aggressively may break agents or docs that already know
  that skill name.
- Keeping both names without a clear hierarchy may make discovery worse. The
  implementation must consistently call `browser-qa` canonical.
- `browser-session` can be mistaken for a browser driver. Docs and tests should
  keep that boundary explicit.
- Static `web-evidence` can be overused for browser-only claims. The new workflow
  must preserve the static-vs-active decision rule.
- Browser artifacts can accidentally retain secrets. Redaction and artifact
  retention rules should be first-class acceptance criteria, not optional notes.
- QA scores can create false precision if unsupported by evidence. Reports
  should tie scores back to observed artifacts and mark untested areas clearly.
- Adding a workflow skill under a new `skills/workflows/qa/` taxonomy may require
  catalog and docs freshness updates beyond the skill file itself.

## Rollback plan

- If `browser-qa` proves too broad during implementation, keep the existing
  `web-qa` skill untouched and land only docs clarifying that browser evidence
  remains primitive-level.
- If compatibility gets confusing, revert `web-qa` changes and keep only the new
  `browser-qa` workflow plus updated references.
- If validation fails because the new taxonomy is too much for one change, split
  the rollout: first add `browser-qa` and docs, then migrate `web-qa` references
  in a follow-up.
