@topy-ai/maggie 0.7.13 → 0.7.14

package/README.md

@@ -58,7 +58,23 @@ Then invoke the installed skills from your coding agent, for example:
 
 Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
-package ships 18 installable skills and a local-first MaggieDash foundation.
+package ships 19 installable skills and a local-first MaggieDash foundation.
+
+For repeatable browser QA, create a project-owned scenario manifest and record
+the test, fix, and retest lifecycle:
+
+```bash
+maggie qa start --project . \
+  --scenario-file .maggie/scenario-manifest.json \
+  --environment local --base-url http://localhost:4321
+maggie qa record --project . --run <run-id> \
+  --scenario HOME-001 --phase test --status pass \
+  --summary "Homepage smoke passed" --evidence .maggie/qa/home.png
+maggie qa summary --project . --run <run-id>
+```
+
+The QA workflow stores secret-free run state under `.maggie/qa-runs/` and
+keeps project-specific scenarios and evidence outside the npm package.
 
 For Google integrations, validate a redacted provider matrix before reporting
 access. The command fails closed on unknown scopes, missing Ads prerequisites,
@@ -114,6 +130,7 @@ maggie clone-to-template ...     # URL → validated marketplace template
 maggie marketplace ...           # catalog and on-demand template workflow
 maggie memory ...                # confirmed preferences and lessons
 maggie feedback ...              # redact, preview, submit, list
+maggie qa ...                    # scenario browser QA, fix/retest, release gate
 maggie localization ...          # plan, validate, review, publish, stale
 maggie service ...               # import, sync, generate, validate
 maggie seo performance ...       # sampled PageSpeed/CWV report and baseline
@@ -220,8 +237,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.13 update --project . --force
-npx @topy-ai/maggie@0.7.13 cleanup --project .
+npx @topy-ai/maggie@0.7.14 update --project . --force
+npx @topy-ai/maggie@0.7.14 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -231,7 +248,10 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.13 workflow adds field-aware section fan-out and locale coverage,
+The 0.7.14 workflow adds the general `maggie-qa-workflow` skill and `maggie qa`
+CLI for scenario manifests, secret-free browser evidence metadata, test/fix/
+retest lifecycle, adjacent regression checks, and explicit release gates. The
+0.7.13 workflow adds field-aware section fan-out and locale coverage,
 sibling-copy/media checks, disjoint page inventory, binding validation,
 idempotency and database-target identity gates, full W3C sitemap lastmod
 validation, and the accepted `X-Robots-Tag: noindex` response contract. The
@@ -484,6 +504,7 @@ python3 tools/clis/maggie_design.py rebrand \
 | `maggie-memory` | Persist confirmed preferences, conventions, lessons, and errors |
 | `maggie-content-localization` | Manage locale-aware translation, review, provenance, stale state, and publication gates |
 | `maggie-feedback` | Collect redacted feedback drafts and explicitly submit them to the NoBlox feedback endpoint |
+| `maggie-qa-workflow` | Run scenario-based browser QA with evidence, fix/retest lifecycle, and release gates |
 | `maggie-auth-reference` | Generate and validate traditional email/password auth with secure server-side sessions |
 | `maggie-blog` | Run a provider-neutral blog lifecycle with stable identity, topics, feeds, settings, and rollback |
 
@@ -528,12 +549,13 @@ repairs with `maggie dash sections validate`, `fanout-validate`,
 `maggie dash inventory` to classify published pages once into disjoint kinds.
 See the [quality contract examples](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/contracts/maggiedash/quality-contracts.md).
 
-The package includes all 18 installable skills: `maggie-blog-bootstrap`,
+The package includes all 19 installable skills: `maggie-blog-bootstrap`,
 `maggie-dash`, `maggie-clone`, `maggie-clone-to-template`, `maggie-marketplace`,
 `maggie-template`, `maggie-design`, `maggie-ops`, `maggie-deployment`,
 `maggie-project-context`, `maggie-seo-geo`, `maggie-social-share`,
 `maggie-service-booking`, `maggie-memory`, `maggie-content-localization`,
-`maggie-feedback`, `maggie-auth-reference`, and `maggie-blog`. Use the stable
+`maggie-feedback`, `maggie-qa-workflow`, `maggie-auth-reference`, and
+`maggie-blog`. Use the stable
 commands below after installation:
 
 ```bash

package/README.zh-TW.md

@@ -2,13 +2,13 @@
 
 [English README](README.md) · [完整繁體中文 README](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/README.zh-TW.md)
 
-`@topy-ai/maggie` 提供 18 個可安裝的 AI website workflow skills，支援
+`@topy-ai/maggie` 提供 19 個可安裝的 AI website workflow skills，支援
 Codex、Claude Code 與相容的 coding agents。
 
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.13 init --agent all
+npx @topy-ai/maggie@0.7.14 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -50,8 +50,13 @@ maggie dash inventory --pages-file .maggie/published-pages.json
 # Migration target identity (never prints or stores a database URL)
 maggie migration identity --identity-file .maggie/db-identity.json \
   --expected-file .maggie/service-db-identity.json
+
+# Scenario browser QA
+maggie qa start --project . --scenario-file .maggie/scenario-manifest.json \
+  --environment local --base-url http://localhost:4321
+maggie qa summary --project . --run <run-id>
 ```
 
-完整中文說明、18 個 skills 清單和 roadmap：
+完整中文說明、19 個 skills 清單和 roadmap：
 [繁體中文 README](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/README.zh-TW.md)
 · [Roadmap](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/ROADMAP.md)

package/bin/maggie.js

@@ -114,6 +114,7 @@ Usage:
   maggie localization <extract|plan|generate|preview|validate|review|publish|stale|glossary> [options]
   maggie seo performance|images|sitemap [options] (sitemap supports strict validate and agent-files)
   maggie feedback <collect|preview|submit|list> [options]
+  maggie qa <start|record|summary|export> [options]
   maggie site-audit URL [--crawl] [--access-log FILE] [--require-sitemap-request] [--languages en-GB,es-MX,ja-JP] [--check-hreflang]
   maggie site-audit URL --crawl --save-baseline FILE --reviewer NAME
   maggie site-audit URL --crawl --baseline FILE
@@ -406,6 +407,7 @@ try {
   else if (command === "memory") workflowCli("maggie_memory.py", args);
   else if (command === "localization") workflowCli("maggie_localization.py", args);
   else if (command === "feedback") workflowCli("maggie_feedback.py", args);
+  else if (command === "qa") workflowCli("maggie_qa_workflow.py", args);
   else if (command === "site-audit") workflowCli("site_audit.py", args);
   else if (command === "browser-audit") workflowCli("maggie_browser_audit.py", args);
   else if (command === "verification") workflowCli("maggie_verification.py", args);

package/bundled-skills/README.md

@@ -20,6 +20,7 @@ Skills are the agent-facing workflows. They compose with the tools in
 | `maggie-memory` | Persist confirmed preferences, project conventions, lessons, and error history across skill runs | local `.maggie/memory/` state |
 | `maggie-content-localization` | Plan, validate, review, publish, and age localized content with market, locale, provenance, and translation safeguards | localization contract, locale CLI |
 | `maggie-feedback` | Collect, redact, review, and explicitly submit feedback from skill runs | feedback CLI, hosted endpoint, GitHub Issue Forms |
+| `maggie-qa-workflow` | Run scenario-based browser QA with evidence, fix/retest lifecycle, and release gates | browser adapter, QA workflow CLI, scenario manifest |
 
 Read only the selected skill and its linked references for a task. Do not load
 all skills as one undifferentiated prompt.

package/bundled-skills/catalog.json

@@ -58,6 +58,10 @@
       "name": "maggie-project-context",
       "description": "Sync a site's safe AI CMO Project, selected brand voice, site settings, and CTA context into a local generated context file. Use when connecting a vibe-coded blog or existing website to AI CMO, refreshing brand context, or diagnosing missing CTA/project data."
     },
+    {
+      "name": "maggie-qa-workflow",
+      "description": "Run scenario-based browser QA with explicit evidence, fix/retest lifecycle, and release-gate decisions for web projects."
+    },
     {
       "name": "maggie-seo-geo",
       "description": "Plan, audit, create, rewrite, and measure content for AI CMO's paid SEO and GEO workflow. Use for topic opportunities, AI visibility, technical SEO, extractable article structure, sitemap-based rewrites, GSC readback, or SEO/GEO client reports."

package/bundled-skills/maggie-qa-workflow/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: maggie-qa-workflow
+description: Run scenario-based browser QA with explicit evidence, fix/retest lifecycle, and release-gate decisions for web projects.
+metadata:
+  version: 1.0.0
+---
+
+# Maggie QA Workflow
+
+Use this skill when a web project needs repeatable user-scenario testing that
+connects browser evidence to a fix, a same-scenario retest, adjacent regression
+checks, and an explicit Pass/Blocked/Fail release decision. It is framework
+neutral and does not replace the project's browser-control or test tools.
+Follow the shared [memory hook](../../references/memory-hook.md) before and
+after the run; memory and feedback remain bounded by the privacy rules below.
+
+## Prepare a scenario manifest
+
+Create `.maggie/scenario-manifest.json` or pass another JSON file with a
+non-empty `scenarios` array. Each scenario needs a unique `id`; useful fields
+include `title`, `group`, `priority`, `routes`, `persona`, `auth`, `browser`,
+and `viewport`. Keep project-specific scenarios in the project; do not ship
+them in the Maggie package.
+
+## Start and record a run
+
+The CLI stores only secret-free run state under `.maggie/qa-runs/`. Screenshots
+and logs stay in the project and are represented by relative paths and hashes.
+Use a real browser adapter for visible interaction, computed layout,
+console/network evidence, final URLs, and response status:
+
+```bash
+maggie qa start --project . \
+  --scenario-file .maggie/scenario-manifest.json \
+  --run-id local-qa-001 --environment local \
+  --base-url http://localhost:4321 --browser chrome \
+  --commit "$(git rev-parse --short HEAD)"
+
+maggie qa record --project . --run local-qa-001 \
+  --scenario HOME-001 --phase test --status pass \
+  --summary "Homepage navigation and consent passed" \
+  --evidence .maggie/qa-runs/local-qa-001/home.png
+```
+
+For a failure, record expected behavior, actual behavior, and a stable error
+fingerprint. A failed scenario cannot be silently changed to Pass:
+
+```bash
+maggie qa record --project . --run local-qa-001 \
+  --scenario SEARCH-001 --phase test --status fail \
+  --summary "Search dialog did not open" \
+  --expected "Selecting a result opens its detail page" \
+  --actual "The click leaves the dialog open" \
+  --error-fingerprint search-dialog-click-stale \
+  --evidence .maggie/qa-runs/local-qa-001/search-console.txt
+
+maggie qa record --project . --run local-qa-001 \
+  --scenario SEARCH-001 --phase fix \
+  --resolution "Guarded the dialog transition after the selected result is resolved" \
+  --validation "focused browser check and project build passed"
+
+maggie qa record --project . --run local-qa-001 \
+  --scenario SEARCH-001 --phase retest --status pass \
+  --summary "Search result opens the detail page" \
+  --evidence .maggie/qa-runs/local-qa-001/search-retest.png
+```
+
+`fix` must follow a recorded failure. `retest` must follow a test and, when
+the test failed, a fix. After a fix, retest the original scenario and at least
+one adjacent scenario affected by the same surface.
+
+## Gate and release evidence
+
+The run gate is `fail` when any scenario fails, `blocked` when there is no
+failure but pending/blocked/inconclusive scenarios remain, and `pass` only
+when every scenario passes. Missing credentials, unsafe fixtures, a real
+mobile viewport, a payment sandbox, or a fault-injection environment are
+explicit blockers; never guess around them.
+
+```bash
+maggie qa summary --project . --run local-qa-001
+maggie qa summary --project . --run local-qa-001 --format markdown
+maggie qa export --project . --run local-qa-001 \
+  --output docs/qa-runs/local-qa-001.md
+```
+
+Before calling a release Pass, also run the relevant build, accessibility,
+SEO, media, API, and deployment-canary checks. A green build, HTTP 200, source
+class, or one guest smoke is not browser QA evidence.
+
+## Privacy and feedback
+
+Do not put passwords, tokens, cookies, full private URLs, personal data,
+provider response bodies, or secrets in run state, screenshots, or exported
+reports. When the same workflow defect is reusable across projects, create a
+privacy-safe draft through `maggie-feedback`; submitting it remains an explicit
+user-confirmed action. Do not promote a project-specific preference directly
+to active memory.
+
+The implementation is `tools/clis/maggie_qa_workflow.py`; it is intentionally
+small enough to run without a browser dependency and delegates browser
+interaction to the host agent/browser capability.

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+"""Track project scenario-based browser QA from test through retest.
+
+The command stores secret-free run state in ``.maggie/qa-runs``. Browser
+interaction remains with the selected browser skill; this CLI records the
+scenario, evidence references, fix event and final release decision.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+
+DEFAULT_SCENARIOS = Path(".maggie") / "scenario-manifest.json"
+VALID_STATUSES = {"pending", "pass", "fail", "blocked", "inconclusive"}
+VALID_PHASES = {"test", "fix", "retest"}
+SECRET_RE = re.compile(
+    r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|authorization|cookie)\s*[=:]\s*)[^\s,;]+"
+)
+EMAIL_RE = re.compile(r"\b[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}\b")
+QUERY_SECRET_RE = re.compile(r"(?i)([?&](?:token|key|secret|password|code|id_token|access_token)=)[^&\s]+")
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def safe_text(value: object, limit: int = 1200) -> str:
+    text = str(value or "").strip()
+    text = SECRET_RE.sub(r"\1[REDACTED]", text)
+    text = QUERY_SECRET_RE.sub(r"\1[REDACTED]", text)
+    text = EMAIL_RE.sub("[REDACTED_EMAIL]", text)
+    return text[:limit]
+
+
+def safe_base_url(value: object) -> str:
+    """Keep the origin only so reports do not retain private paths or queries."""
+    text = safe_text(value, 500)
+    try:
+        parsed = urlsplit(text)
+        if parsed.scheme and parsed.hostname:
+            netloc = parsed.hostname
+            if parsed.port:
+                netloc = f"{netloc}:{parsed.port}"
+            return urlunsplit((parsed.scheme, netloc, "", "", ""))
+    except ValueError:
+        pass
+    return text
+
+
+def project_root(value: str | os.PathLike[str]) -> Path:
+    return Path(value).expanduser().resolve()
+
+
+def load_json(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"could not read JSON {path}: {error}") from error
+    if not isinstance(value, dict):
+        raise ValueError(f"JSON root must be an object: {path}")
+    return value
+
+
+def scenario_records(path: Path) -> list[dict]:
+    manifest = load_json(path)
+    scenarios = manifest.get("scenarios")
+    if not isinstance(scenarios, list) or not scenarios:
+        raise ValueError("scenario manifest must contain a non-empty scenarios array")
+    result = []
+    seen: set[str] = set()
+    for item in scenarios:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            raise ValueError("each scenario must be an object with an id")
+        scenario_id = item["id"]
+        if scenario_id in seen:
+            raise ValueError(f"duplicate scenario id: {scenario_id}")
+        seen.add(scenario_id)
+        result.append(item)
+    return result
+
+
+def run_directory(project: Path) -> Path:
+    directory = project / ".maggie" / "qa-runs"
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def normal_run_id(value: str | None) -> str:
+    if value:
+        value = re.sub(r"[^A-Za-z0-9._-]+", "-", value).strip("-")
+        if not value:
+            raise ValueError("run id cannot be empty")
+        return value
+    return "qa-" + datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+
+
+def run_path(project: Path, value: str) -> Path:
+    candidate = Path(value).expanduser()
+    if candidate.suffix == ".json" or candidate.parent != Path("."):
+        path = candidate if candidate.is_absolute() else project / candidate
+    else:
+        path = run_directory(project) / f"{normal_run_id(value)}.json"
+    path = path.resolve()
+    if not path.is_file():
+        raise ValueError(f"QA run does not exist: {path}")
+    return path
+
+
+def write_json(path: Path, value: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def calculate(run: dict) -> dict:
+    counts = {status: 0 for status in VALID_STATUSES}
+    lifecycle_counts = {"ready": 0, "fix_pending": 0}
+    for item in run.get("scenarios", {}).values():
+        status = item.get("status", "pending")
+        counts[status] = counts.get(status, 0) + 1
+        lifecycle_counts["fix_pending" if item.get("lifecycle") == "fix_pending" else "ready"] += 1
+    if counts["fail"]:
+        gate = "fail"
+    elif counts["pending"] or counts["blocked"] or counts["inconclusive"]:
+        gate = "blocked"
+    else:
+        gate = "pass"
+    return {"gate": gate, "counts": counts, "lifecycle": lifecycle_counts, "total": sum(counts.values())}
+
+
+def start(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    manifest_path = project_root(args.scenario_file) if Path(args.scenario_file).is_absolute() else project / args.scenario_file
+    records = scenario_records(manifest_path)
+    run_id = normal_run_id(args.run_id)
+    path = run_directory(project) / f"{run_id}.json"
+    if path.exists():
+        raise ValueError(f"QA run already exists: {path}")
+    scenarios = {
+        item["id"]: {
+            "id": item["id"],
+            "group": item.get("group", ""),
+            "title": item.get("title", ""),
+            "priority": item.get("priority", "P2"),
+            "routes": item.get("routes", []),
+            "auth": item.get("auth", ""),
+            "browser": bool(item.get("browser", True)),
+            "status": "pending",
+            "lifecycle": "ready",
+            "history": [],
+        }
+        for item in records
+    }
+    try:
+        manifest_label = str(manifest_path.relative_to(project))
+    except ValueError:
+        # Do not persist an absolute path outside the project. The basename is
+        # enough to identify the source without leaking a local filesystem
+        # layout into a shareable run artifact.
+        manifest_label = manifest_path.name
+    run = {
+        "schemaVersion": "maggie.qa-run.v1",
+        "runId": run_id,
+        "createdAt": now(),
+        "updatedAt": now(),
+        "project": hashlib.sha256(str(project).encode()).hexdigest()[:16],
+        "environment": safe_text(args.environment),
+        "baseUrl": safe_base_url(args.base_url),
+        "browser": safe_text(args.browser),
+        "commit": safe_text(args.commit),
+        "release": safe_text(args.release),
+        "scenarioManifest": manifest_label,
+        "scenarios": scenarios,
+    }
+    run["summary"] = calculate(run)
+    write_json(path, run)
+    print(json.dumps({"runId": run_id, "path": str(path), "summary": run["summary"]}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def evidence(value: str, project: Path) -> dict:
+    clean = safe_text(value, 500)
+    path = Path(value).expanduser()
+    if path.is_file():
+        resolved = path.resolve()
+        try:
+            display = str(resolved.relative_to(project))
+        except ValueError:
+            display = resolved.name
+        return {"path": display, "sha256": hashlib.sha256(resolved.read_bytes()).hexdigest()}
+    return {"reference": clean}
+
+
+def record(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    path = run_path(project, args.run)
+    run = load_json(path)
+    scenarios = run.get("scenarios", {})
+    item = scenarios.get(args.scenario)
+    if not isinstance(item, dict):
+        raise ValueError(f"scenario is not in this run: {args.scenario}")
+    phase = args.phase
+    if phase not in VALID_PHASES:
+        raise ValueError(f"phase must be one of: {', '.join(sorted(VALID_PHASES))}")
+    if phase in {"test", "retest"} and args.status not in VALID_STATUSES - {"pending"}:
+        raise ValueError("test and retest require status pass, fail, blocked or inconclusive")
+    if phase == "fix" and not args.resolution:
+        raise ValueError("fix requires --resolution")
+    if phase == "fix" and item.get("status") != "fail":
+        raise ValueError("fix can only follow a recorded fail; use retest after a blocked or inconclusive run")
+    if phase == "retest" and not any(event.get("phase") == "test" for event in item.get("history", [])):
+        raise ValueError("retest requires an earlier test event")
+    if phase == "retest" and item.get("status") == "fail" and not any(event.get("phase") == "fix" for event in item.get("history", [])):
+        raise ValueError("a failed scenario must have a recorded fix before retest")
+    if phase == "test" and args.status == "fail" and not (args.expected and args.actual and args.error_fingerprint):
+        raise ValueError("a failed test requires --expected, --actual and --error-fingerprint")
+    event = {
+        "at": now(),
+        "phase": phase,
+        "status": args.status if phase != "fix" else "fix_pending",
+        "summary": safe_text(args.summary),
+        "expected": safe_text(args.expected),
+        "actual": safe_text(args.actual),
+        "errorFingerprint": safe_text(args.error_fingerprint, 300),
+        "issue": safe_text(args.issue, 500),
+        "resolution": safe_text(args.resolution),
+        "validation": safe_text(args.validation),
+        "evidence": [evidence(value, project) for value in args.evidence],
+    }
+    item.setdefault("history", []).append(event)
+    if phase == "fix":
+        item["lifecycle"] = "fix_pending"
+    else:
+        item["status"] = args.status
+        item["lifecycle"] = "ready"
+    run["updatedAt"] = now()
+    run["summary"] = calculate(run)
+    write_json(path, run)
+    print(json.dumps({"runId": run.get("runId"), "scenario": args.scenario, "event": event, "summary": run["summary"]}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def markdown(run: dict) -> str:
+    summary = run.get("summary") or calculate(run)
+    lines = [
+        f"# Maggie QA run `{run.get('runId', '')}`",
+        "",
+        "<!-- Generated by maggie_qa_workflow.py. Evidence is metadata-only. -->",
+        "",
+        f"- Environment: `{run.get('environment') or 'not provided'}`",
+        f"- Base URL: `{run.get('baseUrl') or 'not provided'}`",
+        f"- Browser: `{run.get('browser') or 'not provided'}`",
+        f"- Commit/release: `{run.get('commit') or 'not provided'}` / `{run.get('release') or 'not provided'}`",
+        f"- Gate: **{summary.get('gate', 'blocked').upper()}**",
+        "",
+        "## Scenario summary",
+        "",
+        "| ID | Priority | Scenario | Status | Lifecycle | Last result |",
+        "|---|---|---|---|---|---|",
+    ]
+    for scenario in run.get("scenarios", {}).values():
+        history = scenario.get("history", [])
+        last = history[-1] if history else {}
+        result = safe_text(last.get("summary") or last.get("actual") or "Not tested", 180).replace("|", "\\|")
+        lines.append(f"| {scenario.get('id')} | {scenario.get('priority')} | {scenario.get('title')} | **{scenario.get('status')}** | {scenario.get('lifecycle')} | {result} |")
+    lines += ["", "## Fix and retest history", ""]
+    for scenario in run.get("scenarios", {}).values():
+        for event in scenario.get("history", []):
+            lines.append(f"### {scenario.get('id')} — {event.get('phase')} ({event.get('at')})")
+            lines.append("")
+            if event.get("summary"): lines.append(f"- Summary: {event['summary']}")
+            if event.get("expected"): lines.append(f"- Expected: {event['expected']}")
+            if event.get("actual"): lines.append(f"- Actual: {event['actual']}")
+            if event.get("errorFingerprint"): lines.append(f"- Error fingerprint: `{event['errorFingerprint']}`")
+            if event.get("resolution"): lines.append(f"- Resolution: {event['resolution']}")
+            if event.get("validation"): lines.append(f"- Validation: {event['validation']}")
+            references = event.get("evidence", [])
+            if references: lines.append(f"- Evidence: {', '.join(str(value.get('path') or value.get('reference')) for value in references)}")
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def summary(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    run = load_json(run_path(project, args.run))
+    result = run.get("summary") or calculate(run)
+    if args.format == "markdown":
+        print(markdown(run))
+    else:
+        print(json.dumps({"runId": run.get("runId"), **result}, ensure_ascii=False, indent=2))
+    return 0 if result.get("gate") == "pass" else 1
+
+
+def export_run(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    run = load_json(run_path(project, args.run))
+    output = Path(args.output).expanduser()
+    if not output.is_absolute(): output = project / output
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(markdown(run), encoding="utf-8")
+    print(json.dumps({"runId": run.get("runId"), "output": str(output.resolve()), "gate": run.get("summary", {}).get("gate")}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(description=__doc__)
+    root.add_argument("--project", default=".")
+    commands = root.add_subparsers(dest="command", required=True)
+
+    start_parser = commands.add_parser("start")
+    start_parser.add_argument("--project", default=argparse.SUPPRESS)
+    start_parser.add_argument("--scenario-file", default=str(DEFAULT_SCENARIOS))
+    start_parser.add_argument("--run-id")
+    start_parser.add_argument("--environment", required=True)
+    start_parser.add_argument("--base-url", required=True)
+    start_parser.add_argument("--browser", default="chrome")
+    start_parser.add_argument("--commit", default="")
+    start_parser.add_argument("--release", default="")
+
+    record_parser = commands.add_parser("record")
+    record_parser.add_argument("--project", default=argparse.SUPPRESS)
+    record_parser.add_argument("--run", required=True)
+    record_parser.add_argument("--scenario", required=True)
+    record_parser.add_argument("--phase", choices=sorted(VALID_PHASES), required=True)
+    record_parser.add_argument("--status", choices=sorted(VALID_STATUSES - {"pending"}))
+    record_parser.add_argument("--summary", default="")
+    record_parser.add_argument("--expected", default="")
+    record_parser.add_argument("--actual", default="")
+    record_parser.add_argument("--error-fingerprint", default="")
+    record_parser.add_argument("--issue", default="")
+    record_parser.add_argument("--resolution", default="")
+    record_parser.add_argument("--validation", default="")
+    record_parser.add_argument("--evidence", action="append", default=[])
+
+    for name in ("summary", "export"):
+        command = commands.add_parser(name)
+        command.add_argument("--project", default=argparse.SUPPRESS)
+        command.add_argument("--run", required=True)
+        if name == "summary": command.add_argument("--format", choices=("json", "markdown"), default="json")
+        else: command.add_argument("--output", required=True)
+    return root
+
+
+def main() -> int:
+    args = parser().parse_args()
+    try:
+        if args.command == "start": return start(args)
+        if args.command == "record": return record(args)
+        if args.command == "summary": return summary(args)
+        return export_run(args)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"QA workflow error: {safe_text(error)}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.13",
+  "version": "0.7.14",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",