QA Check — Execute Test Cases

Runs the test-cases.md artifact produced by /aif-qa and records execution status in qa-check.md. In agent mode, it also maintains reusable cross-QA execution memory under the QA root:

• agent-context.md — curated, current, reusable non-sensitive setup facts for future automated QA runs
• agent-history.md — append-only reusable learnings extracted from prior runs, not a per-run audit log

For browser/UI cases, agent mode saves executable replay scripts under the branch-specific browser-replay/ directory. Later runs execute those scripts first, including scripts for previously passed cases, so fixes are retested and prior behavior gets regression coverage without regenerating browser automation.

The skill is stack-free and agent-free: it does not assume a framework, package manager, browser tool name, or agent runtime. In agent mode, it uses the appropriate available execution surface for each case: live browser automation, CLI commands, project test runners, HTTP/API calls, database-safe read checks, file/document inspection, or other non-destructive automated verification.

Modes

If no mode is provided, ask the user which mode to run.

Workflow

Step 0: Load Config

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.description, paths.architecture, paths.qa (default: .ai-factory/qa)
• Language:
  • language.ui for AskUserQuestion prompts, progress messages, summaries, and next-step guidance
  • language.artifacts for the persisted qa-check.md artifact
  • language.technical_terms for human-readable technical terminology style in the artifact
  • If language.artifacts is missing, use language.ui
  • If both are missing, use en
• Git: git.enabled for branch resolution

If config.yaml does not exist, use defaults:

• DESCRIPTION.md: .ai-factory/DESCRIPTION.md
• ARCHITECTURE.md: .ai-factory/ARCHITECTURE.md
• QA artifacts: .ai-factory/qa/
• ui_language: en
• artifact_language: en
• technical_terms_policy: keep
• Git enabled: true

Store:

• ui_language = language.ui || "en"
• artifact_language = language.artifacts || language.ui || "en"
• technical_terms_policy = language.technical_terms || "keep"
• git_enabled = git.enabled when present, otherwise true
• qa_root = resolved paths.qa || ".ai-factory/qa/"
• qa_agent_context_path = <qa_root>/agent-context.md
• qa_agent_history_path = <qa_root>/agent-history.md

All AskUserQuestion prompts, user-visible explanations, per-case summaries, and final summaries MUST be written in ui_language.

The persisted qa-check.md artifact MUST be written in artifact_language.

Templates define structure, not language. Use the canonical English template in templates/QA-CHECK.md. If artifact_language is not en, translate headings, labels, status text, comments you author, and explanatory text to artifact_language before saving. Preserve checkbox syntax, test case IDs (TC-001), commands, paths, config keys, URLs, selectors, package names, API names, branch names, and raw error messages.

For artifact_language = ru, write human-readable prose, headings, statuses, summaries, and agent-authored comments in Russian. Preserve user wording except mandatory redaction of sensitive values before writing.

Apply technical_terms_policy while writing artifacts:

• keep — keep common technical terms such as browser, selector, viewport, endpoint, payload, regression, and fixture when clearer
• translate — translate human-readable technical terms where a natural target-language term exists
• mixed — translate ordinary prose terms while keeping code, infrastructure, and ecosystem terms unchanged

Step 0.1: Load Project Context

Read the resolved description path if it exists.

Read the resolved architecture path if it exists.

Read .ai-factory/skill-context/aif-qa-check/SKILL.md — MANDATORY if the file exists. Treat it as project-level overrides for this skill.

Read <paths.qa>/agent-context.md if it exists. Treat it as reusable, user-approved QA execution context for future automated runs: stable environment classes, canonical local/staging URLs, login route, test account role, allowed non-sensitive usernames, required seed data patterns, stable selectors, field identifiers, known redirects, startup prerequisites, safe command patterns, reusable test-filter conventions, environment notes, and service startup instructions.

Read <paths.qa>/agent-history.md if it exists. Treat it as append-only cross-QA memory from prior /aif-qa-check runs. Before asking the user or attempting automated execution, search it for reusable prior answers to the same blocker so the skill does not repeat avoidable mistakes.

agent-context.md and agent-history.md are global to all QA sets under paths.qa. They MUST NOT become logs for a specific QA plan. Do not write branch names, branch slugs, QA target paths, current artifact_dir, TC-* mappings, per-run summary counts, exhaustive command transcripts, assertion counts from a single run, one-off file checks, or plan-specific labels such as a numbered QA folder name. Write those details only to <paths.qa>/<branch-slug>/qa-check.md.

Only promote information into agent-context.md or agent-history.md when it is likely to help future unrelated QA runs. Prefer stable patterns over concrete one-off run facts. Example: Laravel backend checks use php artisan test --filter=<TestClass> is reusable; 05-profile-formula-recommendations ran ProfileReaderTest with 4 tests / 13 assertions is run-specific and belongs only in qa-check.md.

Never write global negative capability or scope claims unless they are true for the whole project. Do not write statements like browser automation is not required, browser URL is not used, all QA is backend/CLI, or these cases are backend-test/cli/file-docs to agent-context.md or agent-history.md when that conclusion came from one QA plan. Instead, keep it branch-specific in qa-check.md, or phrase a reusable conditional rule such as For backend-only QA cases, browser automation is not required; browser/UI cases still require Browser or Playwright MCP.

Never treat either file as a source of secrets. If either file contains an apparent password, token, cookie, authorization header, one-time code, or other secret, ignore that value for execution and redact it the next time the file is rewritten or appended to.

Step 0.2: Parse Arguments and Resolve Branch

Parse $ARGUMENTS:

1. Detect mode: first word matching human or agent; remove it from arguments.
2. Detect branch: remaining text, if any, is the branch label.
3. If no mode was provided, ask in ui_language which mode to run:
   • Human-guided QA
   • Automated-agent QA

Resolve the working branch:

If git_enabled = false or the repository is not a git work tree:
  If branch was provided in arguments → use it as the resolved branch label
  Otherwise → set resolved_branch = "manual"
If git_enabled = true and the repository is a git work tree:
  If branch was provided in arguments → use it as the resolved branch
  Otherwise → run: git branch --show-current

Store:

• resolved_branch
• artifact_dir = <resolved paths.qa>/<branch-slug>
• test_cases_path = <artifact_dir>/test-cases.md
• qa_check_path = <artifact_dir>/qa-check.md
• browser_replay_dir = <artifact_dir>/browser-replay

Compute branch-slug with the exact same algorithm as /aif-qa:

1. Replace every character not in [A-Za-z0-9._-] with -, collapse consecutive -, trim leading/trailing -, and use branch if empty. Then MUST truncate safe_slug to the first 40 ASCII characters. Because the normalized safe_slug alphabet is [A-Za-z0-9._-], byte length and character length are identical.
2. Run git hash-object --stdin <<< "<resolved_branch>" and take the first 8 hex characters as hash8.
3. Combine: branch-slug = "<safe_slug>-<hash8>".

Step 1: Verify QA Inputs

Check for <artifact_dir>/test-cases.md.

If it is missing, STOP and ask in ui_language whether to:

1. Run /aif-qa test-cases <resolved_branch> first
2. Cancel

Read test-cases.md. Extract test cases by IDs (TC-001, TC-002, etc.), titles, priority, type, execution surface when present, preconditions, steps, expected results, and test data. Preserve their order.

Compute source binding metadata before creating or modifying qa-check.md:

• source_digest — deterministic digest of the full test-cases.md content using git hash-object --no-filters <test_cases_path> when available, or git hash-object --stdin over the exact file content.
• case_digests — deterministic per-case digest for each extracted TC-NNN, computed from that case's canonical block including title, priority, type, preconditions, steps, expected result, and test data.
• tested_revision — when git_enabled = true and the repository is a git work tree, run git rev-parse HEAD and record the resolved commit SHA.
• worktree_digest — when git_enabled = true and the repository is a git work tree, record a deterministic digest of the current working tree state so dirty-tree QA cannot be reused after local changes without a commit.
• manual_build_id — when git_enabled = false or the repository is not a git work tree, ask the user for an explicit build/version identifier before creating or resuming results. Do not accept an empty identifier.
• replay_script_digests — for each existing canonical <browser_replay_dir>/TC-NNN.js, hash the exact file content with git hash-object --no-filters <path> when available, or another stable SHA-1/SHA-256 digest. This binds evidence to the automation that actually ran even though QA-owned replay files are excluded from worktree_digest.

Canonicalize each per-case digest input exactly:

1. Extract the raw Markdown block from the line containing the case's TC-NNN identifier through the line before the next TC-NNN block or end of file.
2. Normalize line endings from CRLF or CR to LF.
3. Remove trailing spaces and tabs from each line.
4. Trim leading and trailing blank lines from the extracted block.
5. Preserve the original field order, bullet markers, indentation, internal blank lines, Markdown punctuation, and all remaining whitespace. Do not sort fields, collapse whitespace, or rewrite bullets.
6. Wrap the normalized block with raw block boundaries before hashing: BEGIN TC-NNN\n<normalized block>\nEND TC-NNN\n.
7. Hash the wrapped block with git hash-object --stdin when available, or another stable SHA-1/SHA-256 digest if git is unavailable.

Compute worktree_digest exactly when git is enabled and a git work tree exists:

1. Capture git status --porcelain=v1 --untracked-files=all.
2. Capture git diff --binary HEAD --.
3. Exclude qa_check_path and every file under browser_replay_dir from the status, diff, and untracked-file digest inputs so QA-owned result/replay artifacts do not stale their own results. Do not exclude test_cases_path; source changes are also tracked by source_digest.
4. For each remaining untracked file listed by porcelain status, append UNTRACKED <path> <content-digest> where <content-digest> is git hash-object --no-filters <path> when the file is readable.
5. Normalize line endings in the combined input to LF and hash it with git hash-object --stdin.
6. If the filtered work tree input is clean, record the digest of the canonical string clean\n.

If mode = agent, perform Step 1.1 before creating or modifying qa-check.md. Existing qa-check.md may be inspected read-only during this gate.

If qa-check.md exists, read it and resume from existing statuses only after comparing stored binding metadata to the current binding metadata:

• If tested_revision changed, mark every prior result as Stale and unchecked, preserve prior comments/evidence as historical context, and require retest. Do not count stale pass/fail/block statuses as current.
• If worktree_digest changed, mark every prior result as Stale and unchecked, preserve prior comments/evidence as historical context, and require retest. Do not count stale pass/fail/block statuses as current.
• If manual_build_id changed, treat it the same as a tested revision change.
• If source_digest changed, compare case_digests. Preserve current status only for cases whose per-case digest is unchanged and whose tested revision/manual build id and worktree digest are unchanged.
• If an existing case's digest changed, mark that case Stale, unchecked, and require retest.
• If a new case appears, add it as unchecked Pending.
• If a prior case no longer exists in test-cases.md, keep its historical entry marked Stale or move it to an artifact-language "Stale / Removed Cases" section; never count it as current.
• Do not overwrite prior pass/fail comments unless the user explicitly chooses to retest that case.
• If a canonical replay file's actual content digest differs from the Script digest recorded for that case, mark the case Stale, preserve the previous replay metadata/evidence, and require a proof run of the changed script. Missing legacy script-digest or target-fingerprint metadata means the script is unproven, not matching.
• Revision, worktree, or manual-build staleness alone does not invalidate a browser replay script. It remains reusable only while its embedded case digest, embedded target fingerprint, and actual script digest match the current case, approved target, and previously recorded script digest.

If qa-check.md does not exist, create it from templates/QA-CHECK.md using the extracted test cases and source binding metadata. Every case starts unchecked and Pending.

Step 1.1: Agent Mode Capability and Safety Preflight

Agent mode is user-only (disable-model-invocation: true) because it can perform live browser actions, shell commands, local service calls, and other checks with meaningful side effects.

Before executing any case or writing qa-check.md in agent mode:

1. Detect available execution capabilities from the current runtime tools:
   • shell/CLI command execution
   • project test runners and build tools available through shell
   • live browser automation through in-app Browser or Playwright MCP
   • HTTP/API checks available through existing project tooling or safe shell commands
   • file, document, and repository inspection through Read/Grep/Glob
2. Classify each test case by the evidence surface it requires: browser-ui, cli, backend-test, api, file-docs, database-read, hybrid, human, or unknown. If the case has an explicit Execution surface: field, use it unless the case text clearly contradicts it; record any override in agent-history.md.
3. Choose the least invasive capability that can produce concrete evidence for that case. Browser automation is REQUIRED for browser/UI-observable cases and hybrid cases whose expected result depends on rendered web behavior. Do not substitute CLI commands, unit tests, static inspection, or backend checks for a browser/UI case; those may be recorded only as supporting evidence.
4. If a case requires browser automation, prefer the in-app Browser capability if available. If in-app Browser is not available, use Playwright MCP if available.
   • Prefer a browser capability that can execute a saved Playwright-compatible page script when replay scripts exist.
5. If a browser/UI case requires live browser automation and neither in-app Browser nor Playwright MCP is available, keep only that case unchecked, set status to Blocked, ask the user in ui_language to enable a live browser capability, and append this blocker to <paths.qa>/agent-history.md. Continue with other cases that can be verified through CLI, tests, API, or file/document checks.
6. Use <paths.qa>/agent-context.md, <paths.qa>/agent-history.md, test-cases.md, change-summary.md, project docs, current browser state, and repository scripts to determine the target URL, service startup commands, test commands, and environment.
7. For browser/UI cases that require authentication or specific user state, resolve a browser test identity before marking the case blocked:
   • First search agent-context.md, agent-history.md, test data, seeders/factories/fixtures, docs, local database-safe reads, and existing test users for a matching non-sensitive test identity.
   • If the environment is clearly local, test, or disposable development, and repository tooling provides a safe way to create or seed a synthetic test user/state, create the minimal disposable fixture needed for the case. Record the fixture identifier and setup command/evidence in qa-check.md.
   • If creating a fixture requires a password, role, tenant, workspace, feature flag, seed command, or any unclear setup decision, ask the user before blocking. Ask whether to provide an existing test account or authorize creating a disposable fixture.
   • If the user provides or authorizes disposable test credentials for a local or test environment, use them for this run. Store credentials in agent-context.md only if the user explicitly says they are reusable test-only credentials and safe to persist. Otherwise store only the username/role and where to retrieve the secret.
   • Never store production credentials, personal credentials, cookies, session tokens, one-time codes, or shared secrets in agent-context.md or agent-history.md.
8. If a user-suppliable prerequisite is missing, ask the user before blocking:
   • application URL or login URL
   • test account role or non-sensitive username
   • where to find credentials without exposing them in artifacts
   • authorization to create a disposable local/test browser fixture and the desired initial state
   • required startup state, seed data, feature flag, tenant, organization, or workspace
   • ambiguous login mechanism or authentication provider
   • stable selector, field identifier, or page route needed to continue
   • exact project command, test filter, service startup command, or safe API endpoint needed to continue
9. Save reusable non-sensitive answers to <paths.qa>/agent-context.md immediately only when the answer is general enough to help future QA sets. Append the redacted answer summary to <paths.qa>/agent-history.md only when it captures a reusable lesson; otherwise keep it in the branch-specific qa-check.md evidence/comment.
10. Determine and display the target environment, including URL when applicable and inferred environment class: local, development, staging, test, production, or unknown. For a browser target:

• Derive normalized_base_url from the resolved target URL by removing user information, query, and fragment; preserving scheme, host, port, and deployment base path; and removing a trailing slash except for the origin root.
• Compute target_fingerprint from the exact canonical input AIF TARGET\n<environment_class>\n<normalized_base_url>\n with git hash-object --stdin when available, or another stable SHA-1/SHA-256 digest.
• Record the environment class and target_fingerprint in qa-check.md. Never treat a replay created for another target fingerprint as matching.

11. Do not execute browser actions, API writes, CLI commands with side effects, database writes, destructive commands, payment, permission, email, notification, data export, or other external-side-effect steps against production or unknown targets without explicit user authorization immediately before execution. Record the authorization decision and target class in qa-check.md. Append it to agent-history.md only when it creates a reusable cross-QA policy or recurring authorization lesson; do not persist broad production authorization for future runs.
12. Inspect each case and proposed command for destructive, irreversible, payment, permission, email, notification, data export, database mutation, service restart, deployment, filesystem deletion, or other external-side-effect risk. Require explicit per-case authorization before executing any such case.
13. Prefer read-only and test-scoped commands. Do not run destructive shell commands such as rm, git reset, git checkout --, database resets, migrations against shared environments, deploy commands, or cleanup commands that delete user data unless the user explicitly authorizes the exact action.
14. If authorization is denied or unclear, leave the case unchecked, set status to Blocked, and write the blocker to qa-check.md without executing the risky action. Append the decision to agent-history.md only when it is a reusable cross-QA lesson, not merely a case-specific denial.

Redaction is mandatory for agent comments/evidence and all human-entered comments/evidence:

• Redact credentials, cookies, authorization values, session tokens, API keys, bearer tokens, basic auth values, one-time codes, and personal secrets.
• Redact sensitive URL parameters such as token, access_token, refresh_token, id_token, code, secret, password, passwd, pwd, auth, key, api_key, session, sid, and jwt.
• Replace redacted values with [REDACTED] before writing comments or evidence to qa-check.md.
• Do not paste raw browser storage, cookies, request headers, authorization headers, or token-bearing URLs into the artifact.

Step 2: Human Mode

Run exactly one pending or selected test case at a time.

For each case:

1. Show only that test case's title, priority, preconditions, steps, test data, and expected result.
2. Include a short per-case summary in ui_language.
3. The summary question MUST mean: "Test this and answer whether it works." For ui_language = ru, use exactly: Протестируйте и ответьте работает или нет.
4. Ask the user for the result:
   • Works / completed
   • Does not work / failed
   • Stop for now
5. If the user says it works, mark the case as checked ([x]) in qa-check.md, set status to Passed, and add the current mode as human.
6. If the user says it failed, keep the checkbox unchecked ([ ]), set status to Failed, ask for the reason, and write the user's explanation as the comment while preserving user wording except mandatory redaction of sensitive values.
7. Save qa-check.md after every case so progress survives context resets.

Do not show the next test case until the current one has a result or the user stops.

Step 3: Agent Mode

Agent mode MUST produce concrete, case-appropriate evidence. Browser execution, CLI output, automated test output, API responses, backend command results, database-safe read results, or file/document inspection can each be enough to mark a case passed when that evidence directly covers the case steps and expected result.

Internal deterministic invariants MUST be treated as automated checks, not manual QA. Cases involving service-method calls, cache state, materialized rows, exact arrays, raw database values, formula outputs, CLI internals, or similar non-human-observable behavior should be classified as backend-test, cli, api, or database-read as appropriate. First look for existing tests or commands that already cover the invariant. If existing tests are found and pass, mark the corresponding TC-* case Passed with the test class/name, command/filter, exit status, and assertion/result summary as evidence. If one test run covers multiple TC-* cases, reuse that evidence on every covered case and optionally summarize the shared run under "Supporting Automated Checks". If no suitable automated coverage exists, keep the case Blocked with a blocker such as Missing automated test coverage for backend invariant; do not ask the user to manually verify internal arrays or raw database values.

Determine the test target:

• If agent-context.md, agent-history.md, test-cases.md, change-summary.md, project docs, or current browser state clearly identify a URL, use it.
• If repository scripts, test files, package manifests, Makefiles, framework commands, or docs clearly identify a safe command or test filter for a CLI/backend/API/docs case, use it.
• If no URL, command, startup state, credentials location, test filter, or required fixture is clear, ask the user for the missing detail, then persist only the non-sensitive reusable facts to agent-context.md.
• Do not invent credentials, URLs, commands, fixtures, or environment assumptions.
• Use the target environment and authorizations collected in Step 1.1. Reconfirm if navigation redirects to a different host or a more sensitive environment.

Browser Replay Contract

For every browser-ui case, and every hybrid case with browser steps:

1. Use <browser_replay_dir>/TC-NNN.js as the canonical replay artifact. Keep one case per file so a failed case can be rerun independently.
2. Write the smallest Playwright-compatible async (page) => { ... } expression. This is the format accepted by browser run-code capabilities. Do not add imports, a test framework, fixtures, generated wrappers, or project dependencies. Include navigation, stable selectors, inputs/actions, and explicit assertions that throw on mismatch.
3. Start every canonical script with exactly these metadata lines, followed by the async expression:
   • // aif-case-digest: <case_digest>
   • // aif-target-fingerprint: <target_fingerprint> Use the quoted placeholder "AIF_BASE_URL" for navigation instead of persisting an absolute target URL. Immediately before execution, replace that quoted placeholder in memory with a correctly JSON-encoded normalized_base_url; do not modify the saved file. Never write passwords, tokens, cookies, authorization values, one-time codes, personal secrets, or token-bearing URLs into the script. Reuse an already authenticated browser session or obtain secrets through the authorized runtime mechanism.
4. A replay is matching only when all three bindings agree: embedded case_digest, embedded target_fingerprint, and actual script_digest versus the last proof recorded in qa-check.md. Verify all three before every replay. A target mismatch MUST stop execution until the currently displayed and authorized target is verified and the script is explicitly rebound; rebinding changes the script digest and requires a new proof run.
5. Create a missing or outdated script before its first execution whenever the case is mechanically clear. Compute its script_digest, execute it once, and use that first execution as its proof run; do not automatically execute a new or updated script a second time.
   • If interactive browser work was required to clarify the mechanics and the saved script changed after the observed run, mark the new script Unproven. Do not immediately rerun it.
   • An unproven or changed script may run only after its stated preconditions have been explicitly restored or verified. If the case can create, submit, send, delete, mutate permissions/settings, or cause another external side effect, obtain a new per-case authorization that explicitly says this is a repeat execution. Cleanup/reset actions remain subject to the same safety rules and authorization.
   • Record Script digest as a current evidence binding only after that exact file content has executed. For an unproven file, keep Script digest: n/a, set Proof status: Unproven, and record its computed candidate digest in the comment/evidence until a proof run completes.
6. Before modifying any existing canonical script for repair, rebinding, or clarified mechanics, compute its old script digest and preserve it verbatim as <browser_replay_dir>/history/TC-NNN-<old_script_digest>.js. Record the archived path, old digest, and initial error in qa-check.md. Never execute history files automatically.
7. Classify replay failures without hiding product regressions:
   • Syntax or browser-runner failure → automation defect; archive, repair, recompute script_digest, and require a new proof run under the precondition/side-effect rules above.
   • Missing selector → first preserve the original script and initial browser error/state. Repair the locator only when concrete browser evidence proves the same semantic element and expected behavior are still present and only locator mechanics changed. Record that proof. Otherwise mark the case Failed; never choose a merely similar element or bypass the missing step.
   • Script reaches an assertion and observed behavior differs → mark the case Failed; this is regression/fix evidence, not a reason to regenerate the script.
8. On any run after revision, worktree, or manual build changes, replay all current matching browser scripts, including cases that previously passed and failed. The capability/safety preflight and per-case side-effect authorization still apply to every replay. When safe and supported, execute non-stateful scripts in one browser session or batch to reduce setup and tool calls.
9. Record the canonical path, case digest, script digest, target fingerprint, proof status, execution capability, and result in the case's Browser replay and Evidence fields in qa-check.md. Proven means that exact script content executed; it does not mean the product result passed.
10. If the available in-app Browser supports only discrete actions, read the saved script as the exact action/assertion program and replay it through those actions. If Playwright MCP can execute the file body directly, prefer direct execution. Do not regenerate known steps merely because the execution surface changed.
11. Treat replay as the regression baseline, not the only browser check. After replay, decide whether one bounded exploratory pass is justified from concrete change risk:

• Run it when the change affects shared UI, layout, navigation, authentication, permissions, state transitions, or another cross-cutting flow; when the bug cause or fix behavior remains uncertain; when a matching replay needed repair because application behavior changed; or when replay exposed unexpected adjacent behavior.
• Skip it when the fix is narrow and isolated, matching replay directly exercises the changed behavior, no adjacent high-risk path is affected, and replay passes.
• When running it, inspect only directly affected adjacent routes, states, or edge inputs. Do not start open-ended browsing or regenerate working replay steps.
• Record Browser exploration: Ran or Browser exploration: Skipped, the reason, scope, and concise redacted findings in qa-check.md.
• A new finding does not silently become a source test case. Record it in qa-check.md and recommend adding it through /aif-qa test-cases; create its replay script after it has a TC-NNN case.

For each pending or selected case:

1. Select the execution surface from the case classification:
   • browser-ui: execute the matching saved browser replay first; create or prove it only when missing or nonmatching by case, target, or script digest, then navigate with Browser or Playwright MCP and execute UI steps.
   • cli: run the relevant project command and inspect exit code/output.
   • backend-test: find and run the narrowest existing relevant test command or test filter first; broaden only when needed for confidence. Passing automated coverage is valid pass evidence for the case.
   • api: call the endpoint through existing project tooling, safe local commands, or browser/network capability as appropriate.
   • file-docs: inspect generated files, docs, config, or repository contents with Read/Grep/Glob and, when useful, project validation commands.
   • database-read: use only safe read-only checks unless the user explicitly authorizes mutation in a test-scoped environment.
   • hybrid: combine the necessary surfaces and record each evidence type.
2. Execute the test steps as written, adapting only mechanics that are obvious from the selected surface.
3. If execution stalls because of missing credentials, missing browser fixture, unavailable services, unclear setup, blocked navigation, missing selector knowledge, ambiguous field mapping, unknown route, unknown command, missing fixture, or unclear test filter, search agent-context.md and agent-history.md first. For browser/UI auth or user-state gaps, try safe local/test fixture discovery or creation as described in Step 1.1 before blocking. If the answer or fixture is not already available, ask the user exactly for the missing information or authorization before marking the case blocked.
4. When the user provides usable non-sensitive information, continue the case in the same run. Update agent-context.md with durable cross-QA facts and append the resolved friction to agent-history.md only if it is likely to recur in future QA sets. Keep case-specific details in qa-check.md.
5. If the user cannot provide the missing information, the service remains unavailable, authorization is denied, the required capability is unavailable, or a side-effect risk remains unresolved, keep the checkbox unchecked ([ ]), set status to Blocked, and write the blocker.
6. Compare the observed result to the expected result.
7. If observed behavior matches, mark the case checked ([x]), set status to Passed, and add concise redacted evidence. Evidence may be a browser observation, command and exit status, test name and result, API response summary, file path and matched condition, or other concrete observation.
8. If observed behavior does not match, keep the checkbox unchecked ([ ]), set status to Failed, and write a concrete redacted problem comment with observed vs expected behavior.
9. Save qa-check.md after every case.

Before the final summary, write detailed per-run evidence to qa-check.md, not to root-level memory. This includes the current branch/QA target, commands executed, exit codes, assertion counts, supporting file checks, case mappings, summary counts, and one-off blockers.

After writing qa-check.md, extract only reusable cross-QA learnings:

• Update <paths.qa>/agent-context.md when a discovered fact is durable and likely useful for future QA sets.
• Append to <paths.qa>/agent-history.md only when a blocker, selector, command pattern, test-filter convention, API endpoint pattern, route, setup note, or authorization decision is likely to recur beyond the current QA set.
• It is valid to append nothing to agent-history.md for a successful run that produced no new reusable learning.
• Never append a full run transcript, branch/QA target, per-run summary counts, exact assertion totals, or current QA-plan label to agent-history.md.

Keep <paths.qa>/agent-context.md concise and current; prefer stable facts over one-off observations. Do not write raw passwords, tokens, cookies, authorization headers, one-time codes, private personal data, token-bearing URLs, branch names, QA target paths, or run summaries.

Use screenshots or browser state observations when the active runtime makes them available, but do not require screenshots to pass a test.

Step 4: Final Summary

After stopping or finishing, report in ui_language:

• total test cases
• passed
• failed
• blocked
• pending
• path to qa-check.md
• path to browser-replay/ when browser scripts were created or executed
• path to agent-context.md and agent-history.md when agent mode ran or requested missing execution context
• next recommended action

If mode = agent and one or more current cases are Blocked, split them into human-verifiable blocked cases and automation-only blocked cases before ending.

• Offer human-guided continuation only for blocked cases whose execution surface is human, browser-ui, hybrid with human-observable steps, or unknown.
• Do NOT offer human-guided continuation for blocked backend-test, cli, api, file-docs, or database-read cases when the blocker is missing automated coverage, missing command/test filter, unavailable service, or another technical automation prerequisite. For those cases, recommend adding/running the appropriate automated check or providing the missing command/fixture/context.
• If at least one human-verifiable blocked case exists, ask the user in ui_language whether to run those eligible blocked cases now in human-guided mode.
• If the user agrees, continue in the same invocation using Step 2, but only for eligible blocked cases. Preserve existing agent blocker comments as context and append the human result/comment under the same case.
• If the user declines or stops, keep those cases unchecked and Blocked.
• Write the handoff decision and any resolved blocked cases to qa-check.md. Append to agent-history.md only when the handoff revealed a reusable cross-QA lesson.

If any case failed, the next recommended action should be to fix the issue and rerun /aif-qa-check <mode> <resolved_branch>.

If human-verifiable cases remain blocked after an agent-mode run and the user did not continue them in human mode, the next recommended action should be to run /aif-qa-check human <resolved_branch> for those cases or provide the missing execution context. If automation-only cases remain blocked, recommend adding/running the required automated test, command, fixture, service, or context instead. Do not imply that a blocked case is a product defect unless there is concrete observed evidence.

Artifact Ownership and Config Policy

• Primary ownership: <paths.qa>/<branch-slug>/qa-check.md, canonical <paths.qa>/<branch-slug>/browser-replay/TC-NNN.js, preserved <paths.qa>/<branch-slug>/browser-replay/history/*.js, <paths.qa>/agent-context.md, and <paths.qa>/agent-history.md.
• Read policy: may read <paths.qa>/<branch-slug>/change-summary.md, test-plan.md, test-cases.md, <paths.qa>/agent-context.md, and <paths.qa>/agent-history.md as QA context.
• Write policy: persistent writes are limited to qa-check.md, branch-specific browser-replay/TC-NNN.js and browser-replay/history/*.js, agent-context.md, and agent-history.md; do not rewrite test-cases.md, test-plan.md, change-summary.md, or config.yaml.
• Config policy: config-aware, read-only. Reads paths.description, paths.architecture, paths.qa, language.ui, language.artifacts, language.technical_terms, and git.enabled; never writes config.yaml.

Critical Rules

1. MUST NOT run without test-cases.md.
2. MUST show only one case at a time in human mode.
3. MUST ask the user whether the case works in human mode.
4. MUST preserve failed-user comment wording except mandatory redaction of sensitive values before writing.
5. MUST NOT mark a case passed in agent mode without concrete evidence from an appropriate execution surface for that case.
6. MUST NOT block non-browser cases merely because live browser automation is unavailable.
7. MUST classify deterministic internal/backend/CLI/API/database invariant cases as automated checks and MUST NOT route them to human manual QA as a substitute for missing automated coverage.
8. MUST bind current results to (tested_revision and worktree_digest) or manual_build_id, plus source_digest and case_digests.
9. MUST mark stale results stale when the tested revision, worktree digest, manual build id, full source digest, or per-case digest changes.
10. MUST require explicit authorization for production/unknown targets and destructive or external-side-effect cases.
11. MUST redact credentials, cookies, authorization values, tokens, and sensitive URL parameters before writing comments or evidence.
12. MUST save progress after every case.
13. MUST read agent-context.md and agent-history.md before automated execution and before asking the user for setup facts, so prior answers are reused.
14. MUST ask the user for missing user-suppliable execution context before blocking an agent-mode case for missing URL, credentials, login route, field identifiers, setup state, selectors, commands, test filters, fixtures, or similar recoverable information.
15. MUST NOT block a browser/UI case for missing login credentials or user state until it has searched reusable context, existing fixtures, seeders/factories, docs, and safe local/test data; attempted safe disposable fixture creation when the environment is local/test and tooling is available; or asked the user for credentials, fixture setup, or authorization to create a disposable fixture.
16. MUST persist reusable test-only credentials in agent-context.md only after explicit user permission, and MUST never persist production credentials, personal credentials, cookies, session tokens, one-time codes, or shared secrets.
17. MUST write only reusable non-sensitive cross-QA answers and discovered stable execution facts to agent-context.md, and MUST append to agent-history.md only when a recurring reusable learning or blocker pattern was discovered.
18. MUST ask whether to continue eligible blocked agent-mode cases in human mode before ending an agent run with any current human-verifiable Blocked cases.
19. MUST save browser/UI automation as case-, target-, and content-bound browser-replay/TC-NNN.js scripts and execute matching scripts before generating new browser actions.
20. MUST replay matching scripts for previously passed browser cases after revision, worktree, or manual build changes so regressions are checked.
21. MUST NOT add a browser test dependency or runner solely for replay artifacts.
22. MUST make and record an evidence-based browser exploration decision after replay; replay is a baseline, not a replacement for bounded exploration when concrete change-risk signals exist.
23. MUST NOT automatically execute a new or updated replay twice; repeat execution requires restored/verified preconditions and renewed authorization for external side effects.
24. MUST treat a missing selector as a possible product regression unless concrete evidence proves only locator mechanics changed, preserving the original script and error before repair.
25. MUST verify case_digest, target_fingerprint, and script_digest before replay and require a proof run after any script change or target rebinding.