wicked-crew 0.7.30 → 0.7.32

package/dist/qe/author-workflow.js

@@ -0,0 +1,377 @@
+/**
+ * `qe-author-tests` — the governed test-authoring workflow (wave 6: F-7R2-003/004/005/012/014/015,
+ * acceptance verdict R4-r2), workflows-as-data.
+ *
+ * ## Why a workflow, not a free-text run
+ *
+ * The studio's "New test" used to `POST /testing/recon` a plain free-text governed run: the planner
+ * split the brief at sentence boundaries into seven alternating agent units, two of them chat
+ * replies ("Gate protocol acknowledged … What is the next task?"), every gate a vacuous
+ * default-allow, no `skill_ref` anywhere (the 40-specialist QE domain never routed), no deliver
+ * phase (the LAST worker opened the PR from its own shell — invisible to the ledger), no campaign
+ * registered (the Test landing stayed empty), and the produced Playwright e2e was never executed by
+ * the run — it failed at its first check on the first independent run (R4-r2: 0 of 12 checks).
+ *
+ * This def is the fix, as data the engine validates AS AUTHORED (wicked-core#414 — a code-writing
+ * agent phase carries the evidence-floor pin, the verified-evidence phase carries it too):
+ *
+ *   recon   (agent, neutral, `wicked-garden-qe` plan)   — read the repo + its tests, detect the
+ *                                                          harness, map intent → behaviours → gaps
+ *   author  (agent, CREATOR, `wicked-garden-qe` author,  — write behaviour tests against the repo's
+ *            executes_code, evidence-floor pinned)         own harness + `tests/PLAN-<slug>.md`
+ *   verify  (TOOL, verified_evidence, pinned)            — {@link qeVerifyScript}: run the repo's own
+ *                                                          checks INCLUDING every produced test;
+ *                                                          FAIL if any fails or was never executed
+ *   review  (agent, EVALUATOR, `wicked-garden-qe` review,— independent fitness verdict; escalates a
+ *            pinned, human_confirm_if verdict_not_pass)     not-pass to a human, never auto-denies
+ *   deliver — NOT here. Appended per run by the ENGINE-side composition (`deliver: "pr"`, the
+ *             crew#393 default for a repo-scoped code-work def): the engine lifts, re-verifies,
+ *             pushes and opens the PR so the ledger records the delivery. A worker seat never
+ *             pushes (the wave-6 engine's remote-write fence refuses `git push`/`gh pr create`).
+ *
+ * The METHOD lives in the garden skill (`wicked-garden-qe`, actions plan/author/review) — each
+ * phase's inline `instructions` is a one-line orientation only, because a governed worker's prompt
+ * rides a single PTY line capped at 1022 bytes (wicked-core execute_wrapped.rs) and the planner
+ * folds the instructions onto that line beside the run intent.
+ *
+ * Crew-authored drop-in (like `capture-learnings`): NOT core-seeded, so `launchRun`'s
+ * `_writeBuiltinOverlay` write is the only way the engine resolves the id. Not `is_system`: it IS an
+ * operator-selectable work mode (the catalog finally carries something labelled test/QE — F-075).
+ */
+import { EVIDENCE_FLOOR_PIN } from '../core/deliver.js';
+/** The workflow id — `GET /workflows` lists it; `POST /testing/author` launches it. */
+export const QE_AUTHOR_TESTS_WORKFLOW = 'qe-author-tests';
+/** The garden skill every agent phase routes through (`skills/qe/SKILL.md`, actions by name). */
+export const QE_SKILL = 'wicked-garden-qe';
+/** The deterministic verification phase's id (its unit is `<run>:verify` on the wire). */
+export const QE_VERIFY_PHASE_ID = 'verify';
+/** Per-produced-file marker the verify phase prints: `QE-VERIFY: file=… harness=… exit=… status=…`. */
+export const QE_VERIFY_MARKER = 'QE-VERIFY:';
+/** Repo-own-checks marker: `QE-VERIFY-CHECK: harness=… cmd="…" exit=…`. */
+export const QE_VERIFY_CHECK_MARKER = 'QE-VERIFY-CHECK:';
+/** The one summary line: `QE-VERIFY-SUMMARY: produced=N executed=N passed=N failed=N …`. */
+export const QE_VERIFY_SUMMARY_MARKER = 'QE-VERIFY-SUMMARY:';
+/** Where the author phase must record its plan (glob, repo-relative). */
+export const QE_PLAN_GLOB = 'tests/PLAN-*.md';
+/** Ceiling for each phase's inline orientation — the PTY line also carries the intent. */
+export const QE_MAX_INLINE_INSTRUCTION_BYTES = 600;
+const RECON_INSTRUCTIONS = 'Phase 1/4 PLAN (qe skill, plan action): read the repository and its existing tests, detect the ' +
+    'test harness (vitest/jest/pytest/Playwright and any loopback e2e fixture), map the operator ' +
+    'intent to behaviours, and list the coverage gaps — cite file:line for anything you claim is ' +
+    'already covered. Analysis only: write no files.';
+const AUTHOR_INSTRUCTIONS = 'Phase 2/4 AUTHOR (qe skill, author action): write BEHAVIOUR tests for the planned gaps against ' +
+    "the repository's own harness, plus tests/PLAN-<slug>.md recording each test, the exact command " +
+    'that runs it and its observed result. RUN every test you write before claiming it. Never push, ' +
+    "never open or edit a pull request — the run's deliver phase does that.";
+const REVIEW_INSTRUCTIONS = 'Phase 4/4 REVIEW (qe skill, review action): judge the produced tests independently — behaviour ' +
+    'vs implementation coupling, every claim of existing coverage verified at file:line, no sleeps ' +
+    "or flaky waits, the PLAN matches what shipped, and the verify phase's QE-VERIFY report shows " +
+    'every produced test executed. Verdict PASS or FAIL with reasons. Read-only: change nothing.';
+/**
+ * The verify phase's script — the R4-r2 floor: a produced test that fails, or was never run, FAILS
+ * the unit. Runs in the run worktree as `bash -lc`:
+ *
+ *  1. BASE — the run branch's fork point off origin's default branch (the engine's own derivation
+ *     order: origin/HEAD, origin/main, origin/master; then a local main/master; else HEAD).
+ *  2. PRODUCED — every path changed/added since BASE plus every untracked file: the run's own work,
+ *     committed or not. Test files are the conventional shapes (`*.test.*`, `*.spec.*`, `*_test.py`,
+ *     `test_*.py`, `__tests__/`); fixtures, factories and the PLAN are produced but not "tests".
+ *  3. HARNESS per file — the REPOSITORY's own, resolved PER FILE by walking up from the file's
+ *     directory to the nearest marker (monorepo-aware — review H-1/M-1 of #536): Playwright
+ *     (`playwright.config.*` / `@playwright/test` in the nearest package.json) for `*.spec.*`, a
+ *     Python Playwright rig (imports `playwright`), vitest/jest from the nearest package.json that
+ *     declares them, pytest for every other test-shaped `.py` (nearest `pytest.ini` / `conftest.py`
+ *     / `tox.ini` / `pyproject.toml [tool.pytest]` / `setup.cfg [tool:pytest]` dir, else the root).
+ *     The RUNNER is the nearest `node_modules/.bin/<tool>` (or `.venv/bin/pytest` / an importable
+ *     pytest) from that package dir up to the worktree root — NEVER `npx` (a registry fetch on the
+ *     verify path) and NEVER a plain interpreter for a test-shaped file (a pytest module run as
+ *     `python3 file.py` defines its functions and exits 0 with zero assertions — a vacuous PASS).
+ *     A missing/unrunnable runner is NOT EXECUTED = fail, with "harness not available: <tool>" and
+ *     the remedy (install the dependencies in the worktree in the author phase). The runner runs
+ *     FROM its package dir with a package-relative path.
+ *  4. COLLECTED — every executed file must show ≥ 1 test in the RUNNER's own summary (pytest
+ *     `N passed` / `collected N items`, vitest `Tests N passed`, jest `N total`, Playwright
+ *     `N passed`, a Python rig's check/pass lines); exit 0 with 0 tests reported = NOT EXECUTED.
+ *  5. REPO CHECKS — the full unit suite of every (harness, package dir) a produced test used
+ *     (vitest/jest/pytest) runs once too, so the produced tests are verified INSIDE the repository's
+ *     own check, not beside it. The Playwright suite is not re-run whole (its produced specs ran
+ *     individually).
+ *  6. VERDICT — `QE-VERIFY-SUMMARY:` then exit 0 only when: ≥ 1 produced test, every one executed
+ *     with ≥ 1 test collected, none failed, the PLAN exists, and the repo checks passed. Every
+ *     refusal names its reason.
+ *
+ * `set -u -o pipefail` but NOT `-e`: each command's exit is captured deliberately. `exec 2>&1`
+ * keeps the transcript chronological (the engine appends stderr after stdout otherwise).
+ */
+export function qeVerifyScript() {
+    return [
+        'set -uo pipefail',
+        'exec 2>&1',
+        'echo "QE-VERIFY-BEGIN worktree=$PWD"',
+        // 1. base
+        'D=$(git symbolic-ref -q --short refs/remotes/origin/HEAD || true)',
+        'if [ -z "$D" ] || ! git rev-parse --verify -q "$D^{commit}" >/dev/null; then',
+        '  if git rev-parse --verify -q origin/main^{commit} >/dev/null; then D=origin/main;',
+        '  elif git rev-parse --verify -q origin/master^{commit} >/dev/null; then D=origin/master;',
+        '  elif git rev-parse --verify -q main^{commit} >/dev/null; then D=main;',
+        '  elif git rev-parse --verify -q master^{commit} >/dev/null; then D=master;',
+        '  else D=""; fi',
+        'fi',
+        'if [ -n "$D" ]; then BASE=$(git merge-base "$D" HEAD 2>/dev/null || git rev-parse HEAD); else BASE=$(git rev-parse HEAD); fi',
+        'echo "QE-VERIFY-BASE ref=${D:-HEAD} commit=$BASE"',
+        // 2. produced
+        'PRODUCED=$( { git diff --name-only --diff-filter=AMR "$BASE" -- . ; git ls-files --others --exclude-standard ; } | sort -u )',
+        'is_test_path() {',
+        '  case "$1" in *.md|*.json|*.snap|*.txt|*.yml|*.yaml|*.toml|*.lock|*.html|*.css|*.png|*.svg) return 1;; esac',
+        '  case "$1" in *.test.*|*.spec.*|*_test.py|test_*.py|*/test_*.py|__tests__/*|*/__tests__/*) return 0;; esac',
+        '  return 1',
+        '}',
+        // 3. harness detection — PER FILE, nearest marker dir walking UP from the file (monorepo-aware)
+        'pkg_has_dep() { [ -f "$1/package.json" ] && grep -Eq "\\"$2\\"[[:space:]]*:" "$1/package.json"; }',
+        'is_pw_dir() { ls "$1"/playwright.config.* >/dev/null 2>&1 || pkg_has_dep "$1" "@playwright/test"; }',
+        'is_vitest_dir() { pkg_has_dep "$1" vitest; }',
+        'is_jest_dir() { pkg_has_dep "$1" jest; }',
+        'is_py_dir() { [ -f "$1/pytest.ini" ] || [ -f "$1/conftest.py" ] || [ -f "$1/tox.ini" ] || { [ -f "$1/pyproject.toml" ] && grep -q "tool.pytest" "$1/pyproject.toml"; } || { [ -f "$1/setup.cfg" ] && grep -q "tool:pytest" "$1/setup.cfg"; }; }',
+        'nearest() { local d; d=$(dirname "$1"); while :; do if "$2" "$d"; then echo "$d"; return 0; fi; [ "$d" = "." ] && break; d=$(dirname "$d"); done; echo ""; return 1; }',
+        // the runner: the nearest node_modules/.bin/<tool> from the package dir up to the worktree root,
+        // spelled RELATIVE TO the package dir (every command runs from there: `./…` or `../…`) — NEVER npx
+        'find_bin() { local d="$1" up=""; while :; do if [ -x "$d/node_modules/.bin/$2" ]; then echo "${up:-./}node_modules/.bin/$2"; return 0; fi; [ "$d" = "." ] && break; d=$(dirname "$d"); up="../$up"; done; echo ""; return 1; }',
+        'find_pytest() { local d="$1" up=""; while :; do if [ -x "$d/.venv/bin/pytest" ]; then echo "${up:-./}.venv/bin/pytest"; return 0; fi; [ "$d" = "." ] && break; d=$(dirname "$d"); up="../$up"; done; if python3 -c "import pytest" >/dev/null 2>&1; then echo "python3 -m pytest"; return 0; fi; echo ""; return 1; }',
+        'resolve() {',
+        '  local d',
+        '  case "$1" in',
+        '    *.py)',
+        '      if grep -Eq "^[[:space:]]*(from|import)[[:space:]]+playwright" "$1" 2>/dev/null; then echo "playwright-python	$(dirname "$1")"; return; fi',
+        '      d=$(nearest "$1" is_py_dir); [ -n "$d" ] || d="."',
+        '      echo "pytest	$d"; return;;',
+        '  esac',
+        '  case "$1" in *.spec.*) d=$(nearest "$1" is_pw_dir); if [ -n "$d" ]; then echo "playwright	$d"; return; fi;; esac',
+        '  d=$(nearest "$1" is_vitest_dir); if [ -n "$d" ]; then echo "vitest	$d"; return; fi',
+        '  d=$(nearest "$1" is_jest_dir); if [ -n "$d" ]; then echo "jest	$d"; return; fi',
+        '  d=$(nearest "$1" is_pw_dir); if [ -n "$d" ]; then echo "playwright	$d"; return; fi',
+        '  echo "unknown	."',
+        '}',
+        // how many tests the RUNNER says it executed (its own summary line) — 0 = nothing ran
+        'sum_counts() { grep -E "$2" "$1" | tail -1 | awk \'{s=0; for(i=1;i<=NF;i++) if($i ~ /^[0-9]+$/ && $(i+1) ~ /^(passed|failed|flaky|skipped|total)/) s+=$i; print s}\'; }',
+        'collected() {',
+        '  local n=""',
+        '  case "$1" in',
+        '    pytest) n=$(sum_counts "$2" "[0-9]+ (passed|failed)"); [ "${n:-0}" -gt 0 ] || n=$(grep -Eo "collected [0-9]+ item" "$2" | tail -1 | grep -Eo "[0-9]+");;',
+        '    vitest) n=$(sum_counts "$2" "^[[:space:]]*Tests[[:space:]]");;',
+        '    jest) n=$(grep -Eo "[0-9]+ total" "$2" | tail -1 | grep -Eo "[0-9]+");;',
+        '    playwright) n=$(sum_counts "$2" "[0-9]+ (passed|failed|flaky)");;',
+        '    playwright-python) n=$(grep -Eci "passed|\\bpass\\b|✓|\\"checks\\"|\\bok\\b" "$2");;',
+        '  esac',
+        '  echo "${n:-0}"',
+        '}',
+        'P=0; E=0; PASS=0; FAIL=0; NX=0; PLAN=""; HARNESSES=""',
+        'not_executed() { NX=$((NX+1)); echo "QE-VERIFY: file=$1 harness=$2 pkg=$3 cmd=\\"\\" exit=- tests=0 status=not-executed reason=\\"$4\\""; echo "qe-verify: $1 — $4"; }',
+        'while IFS= read -r f; do',
+        '  [ -n "$f" ] || continue',
+        '  case "$f" in tests/PLAN-*.md|*/tests/PLAN-*.md) PLAN="$f";; esac',
+        '  is_test_path "$f" || continue',
+        '  P=$((P+1))',
+        '  R=$(resolve "$f"); H="${R%%	*}"; PKG="${R#*	}"',
+        '  rel="$f"; [ "$PKG" = "." ] || rel="${f#$PKG/}"',
+        '  case "$H" in',
+        '    playwright) BIN=$(find_bin "$PKG" playwright) || { not_executed "$f" "$H" "$PKG" "harness not available: playwright (@playwright/test) — no node_modules/.bin/playwright from $PKG up to the worktree root; install the repository dependencies in the worktree (npm ci) in the author phase. The verify path never runs npx"; continue; }; CMD=("$BIN" test "$rel");;',
+        '    vitest) BIN=$(find_bin "$PKG" vitest) || { not_executed "$f" "$H" "$PKG" "harness not available: vitest — no node_modules/.bin/vitest from $PKG up to the worktree root; install the repository dependencies in the worktree (npm ci) in the author phase. The verify path never runs npx"; continue; }; CMD=("$BIN" run "$rel");;',
+        '    jest) BIN=$(find_bin "$PKG" jest) || { not_executed "$f" "$H" "$PKG" "harness not available: jest — no node_modules/.bin/jest from $PKG up to the worktree root; install the repository dependencies in the worktree (npm ci) in the author phase. The verify path never runs npx"; continue; }; CMD=("$BIN" "$rel");;',
+        '    pytest) PT=$(find_pytest "$PKG") || { not_executed "$f" "$H" "$PKG" "harness not available: pytest — no .venv/bin/pytest from $PKG up to the worktree root and python3 cannot import pytest; a test-shaped .py file is NEVER run as a plain script (it would pass with zero assertions). Install pytest in the worktree in the author phase"; continue; }; if [ "$PT" = "python3 -m pytest" ]; then CMD=(python3 -m pytest -q "$rel"); else CMD=("$PT" -q "$rel"); fi;;',
+        '    playwright-python) python3 -c "import playwright" >/dev/null 2>&1 || { not_executed "$f" "$H" "$PKG" "harness not available: playwright (python) — python3 cannot import playwright; pip install playwright && playwright install chromium in the author phase"; continue; }; CMD=(python3 "$rel");;',
+        '    *) not_executed "$f" unknown "$PKG" "no harness recognised — declare one the repository owns (playwright.config.*, vitest/jest in the nearest package.json, a pytest marker)"; continue;;',
+        '  esac',
+        '  case " $HARNESSES " in *" $H|$PKG "*) ;; *) HARNESSES="$HARNESSES $H|$PKG";; esac',
+        '  echo "QE-VERIFY-RUN file=$f harness=$H pkg=$PKG cmd=\\"${CMD[*]}\\""',
+        '  OUT=$(mktemp)',
+        '  ( cd "$PKG" && "${CMD[@]}" ) 2>&1 | tee "$OUT"; RC=${PIPESTATUS[0]}',
+        '  N=$(collected "$H" "$OUT"); rm -f "$OUT"',
+        '  E=$((E+1))',
+        '  if [ "$RC" -ne 0 ]; then FAIL=$((FAIL+1)); ST=failed;',
+        '  elif [ "${N:-0}" -lt 1 ]; then NX=$((NX+1)); E=$((E-1)); ST=not-executed; echo "qe-verify: $f — the $H runner exited 0 but reported 0 tests (nothing was collected or executed)";',
+        '  else PASS=$((PASS+1)); ST=passed; fi',
+        '  echo "QE-VERIFY: file=$f harness=$H pkg=$PKG cmd=\\"${CMD[*]}\\" exit=$RC tests=${N:-0} status=$ST"',
+        "done < <(printf '%s\\n' \"$PRODUCED\")",
+        // 4. repo checks — the full unit suite once per (harness, package dir) the produced tests used
+        'C=0; CF=0',
+        'for HP in $HARNESSES; do',
+        '  H="${HP%%|*}"; PKG="${HP#*|}"',
+        '  case "$H" in',
+        '    vitest) BIN=$(find_bin "$PKG" vitest); CMD=("$BIN" run);;',
+        '    jest) BIN=$(find_bin "$PKG" jest); CMD=("$BIN");;',
+        '    pytest) PT=$(find_pytest "$PKG"); if [ "$PT" = "python3 -m pytest" ]; then CMD=(python3 -m pytest -q); else CMD=("$PT" -q); fi;;',
+        '    *) echo "QE-VERIFY-CHECK: harness=$H pkg=$PKG skipped=full-suite (produced files ran individually)"; continue;;',
+        '  esac',
+        '  C=$((C+1))',
+        '  echo "QE-VERIFY-CHECK-RUN harness=$H pkg=$PKG cmd=\\"${CMD[*]}\\""',
+        '  ( cd "$PKG" && "${CMD[@]}" ); RC=$?',
+        '  [ "$RC" -eq 0 ] || CF=$((CF+1))',
+        '  echo "QE-VERIFY-CHECK: harness=$H pkg=$PKG cmd=\\"${CMD[*]}\\" exit=$RC"',
+        'done',
+        // 5. verdict
+        'echo "QE-VERIFY-SUMMARY: produced=$P executed=$E passed=$PASS failed=$FAIL not_executed=$NX plan=${PLAN:-missing} checks=$C checks_failed=$CF"',
+        '[ "$P" -gt 0 ] || { echo "qe-verify: FAIL — the author phase produced no test files; nothing was verified, so done cannot be asserted"; exit 1; }',
+        '[ -n "$PLAN" ] || { echo "qe-verify: FAIL — no tests/PLAN-*.md was produced (the plan records every test, the command that ran it and its result)"; exit 1; }',
+        '[ "$NX" -eq 0 ] || { echo "qe-verify: FAIL — $NX produced test file(s) were never executed (no available harness, or the runner reported 0 tests); a test that never ran proves nothing"; exit 1; }',
+        '[ "$FAIL" -eq 0 ] || { echo "qe-verify: FAIL — $FAIL of $E produced test file(s) failed under the repository harness"; exit 1; }',
+        '[ "$CF" -eq 0 ] || { echo "qe-verify: FAIL — $CF repository check(s) failed with the produced tests in the tree"; exit 1; }',
+        'echo "qe-verify: PASS — $E produced test file(s) executed and passed under the repository harness; plan $PLAN"',
+    ].join('\n');
+}
+function agentPhase(id, kind, instructions, over) {
+    return {
+        id,
+        kind,
+        instructions,
+        gate_type: 'execution',
+        gate: 'auto',
+        executes_code: false,
+        verified_evidence: false,
+        required_deliverables: [],
+        depends_on: [],
+        role: 'neutral',
+        skill_ref: QE_SKILL,
+        allowed_skills: [],
+        validator_pin: null,
+        ...over,
+    };
+}
+/** The verify TOOL phase — deterministic, pinned to the evidence floor (the run left a change),
+ *  `executes_code: false` like the deliver phase: engine-owned tooling, not governed agent work
+ *  (a Tool unit is never worktree-guarded, so the harness's caches cannot deny it). */
+export function qeVerifyPhase(dependsOn = ['author']) {
+    return {
+        id: QE_VERIFY_PHASE_ID,
+        kind: 'test',
+        executor: { type: 'tool', cmd: ['bash', '-lc', qeVerifyScript()] },
+        gate_type: 'execution',
+        gate: 'auto',
+        executes_code: false,
+        verified_evidence: true,
+        required_deliverables: [],
+        depends_on: dependsOn,
+        role: 'neutral',
+        skill_ref: null,
+        allowed_skills: [],
+        validator_pin: EVIDENCE_FLOOR_PIN,
+    };
+}
+/** The shipped definition (see the module doc). Exported as data — tests assert it, the adapter
+ *  serves it from `BUILTIN_WORKFLOWS`, and the engine validates it as authored at the overlay write. */
+export const QE_AUTHOR_TESTS_WORKFLOW_DEF = {
+    id: QE_AUTHOR_TESTS_WORKFLOW,
+    phases: [
+        agentPhase('recon', 'recon', RECON_INSTRUCTIONS, { gate_type: 'strategy', role: 'neutral' }),
+        agentPhase('author', 'build', AUTHOR_INSTRUCTIONS, {
+            depends_on: ['recon'],
+            role: 'creator',
+            executes_code: true,
+            validator_pin: EVIDENCE_FLOOR_PIN,
+        }),
+        qeVerifyPhase(['author']),
+        agentPhase('review', 'review', REVIEW_INSTRUCTIONS, {
+            depends_on: [QE_VERIFY_PHASE_ID],
+            role: 'evaluator',
+            gate: { human_confirm_if: 'verdict_not_pass' },
+            validator_pin: EVIDENCE_FLOOR_PIN,
+        }),
+    ],
+};
+/** `key=value` and `key="quoted value"` pairs of one marker line. */
+function fields(rest) {
+    const out = {};
+    const re = /([a-z_]+)=("([^"]*)"|\S*)/g;
+    for (const m of rest.matchAll(re))
+        out[m[1]] = m[3] !== undefined ? m[3] : (m[2] ?? '');
+    return out;
+}
+function int(v) {
+    const n = Number(v);
+    return Number.isInteger(n) && n >= 0 ? n : 0;
+}
+/**
+ * Parse the verify unit's transcript into a {@link QeVerifyReport}. `null` when the transcript
+ * carries no `QE-VERIFY-SUMMARY:` line (the phase never reached its verdict — the unit's status
+ * and `denial_reason` say why).
+ */
+export function parseQeVerifyOutput(text) {
+    const files = [];
+    const checks = [];
+    let summary = null;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith(QE_VERIFY_SUMMARY_MARKER)) {
+            summary = fields(line.slice(QE_VERIFY_SUMMARY_MARKER.length));
+        }
+        else if (line.startsWith(QE_VERIFY_CHECK_MARKER)) {
+            const f = fields(line.slice(QE_VERIFY_CHECK_MARKER.length));
+            if (f['skipped'] !== undefined || f['harness'] === undefined || f['exit'] === undefined)
+                continue;
+            checks.push({ harness: f['harness'], cmd: f['cmd'] ?? '', exit: int(f['exit']) });
+        }
+        else if (line.startsWith(QE_VERIFY_MARKER)) {
+            const f = fields(line.slice(QE_VERIFY_MARKER.length));
+            if (f['file'] === undefined)
+                continue;
+            const status = f['status'] === 'passed' || f['status'] === 'failed' ? f['status'] : 'not-executed';
+            // A file the runner ran but reported 0 tests for carries its exit code; a file never handed
+            // to a runner has `exit=-` (→ null).
+            const exit = f['exit'] === undefined || f['exit'] === '-' ? null : int(f['exit']);
+            files.push({
+                path: f['file'],
+                harness: f['harness'] ?? 'unknown',
+                cmd: f['cmd'] ?? '',
+                exit,
+                tests: int(f['tests']),
+                pkg: f['pkg'] === undefined || f['pkg'] === '' ? '.' : f['pkg'],
+                status,
+                ...(f['reason'] !== undefined && f['reason'] !== '' ? { reason: f['reason'] } : {}),
+            });
+        }
+    }
+    if (summary === null)
+        return null;
+    return {
+        files,
+        checks,
+        produced: int(summary['produced']),
+        executed: int(summary['executed']),
+        passed: int(summary['passed']),
+        failed: int(summary['failed']),
+        notExecuted: int(summary['not_executed']),
+        plan: summary['plan'] === undefined || summary['plan'] === 'missing' ? null : summary['plan'],
+        checksFailed: int(summary['checks_failed']),
+    };
+}
+function gateLabel(gate) {
+    if (typeof gate === 'object' && gate !== null && 'human_confirm' in gate)
+        return 'human';
+    if (typeof gate === 'object' && gate !== null && 'human_confirm_if' in gate)
+        return 'human_if_not_pass';
+    return 'auto';
+}
+export function qeAuthorPlan(def, seats, deliver) {
+    const phases = def.phases.map((p) => ({
+        id: p.id,
+        kind: p.kind,
+        role: p.role,
+        executor: p.executor?.type === 'tool' ? 'tool' : 'agent',
+        skillRef: p.skill_ref,
+        gate: gateLabel(p.gate),
+        executesCode: p.executes_code,
+    }));
+    if (deliver) {
+        phases.push({
+            id: 'deliver',
+            kind: 'build',
+            role: 'neutral',
+            executor: 'tool',
+            skillRef: null,
+            gate: 'auto',
+            executesCode: false,
+            engine: true,
+        });
+    }
+    return { workflow: def.id, phases, seats };
+}
+//# sourceMappingURL=author-workflow.js.map

package/dist/qe/author-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"author-workflow.js","sourceRoot":"","sources":["../../src/qe/author-workflow.ts"],"names":[],"mappings":"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"}

package/dist/qe/ledger.d.ts

@@ -6,15 +6,31 @@
  * this daemon owns: a DomainStore rooted at `<repo>/.wicked-qe/` (legacy
  * `<repo>/.wicked-testing/` — see qeLedgerRoot) holding `runs` and
  * `verdicts`, plus the public evidence manifest at
- * `<root>/evidence/<run-id>/manifest.json`. This module reads that state
- * through the wicked-ledger package API (public entry, no deep imports) and
- * never writes a domain record — the QE pipeline is the only writer.
+ * `<root>/evidence/<run-id>/manifest.json`.
  *
- * ONE deliberate mutation is allowed: `rebuildIndex()`, which regenerates the
- * store's DERIVED SQLite index from the canonical JSON files when the two
- * disagree (see `readAcceptanceState`). Canonical JSON is authoritative by the
- * ledger's own schema contract; the index is a cache, and rebuilding a cache
- * is not a write to the ledger's record of what happened.
+ * READ-ONLY means read-only (F-E2E-013). This module reads the ledger's
+ * CANONICAL JSON files directly and never opens a `DomainStore`: opening one
+ * is a write — `new DomainStore(root)` mkdirs the root, reaps `.tmp.*` files,
+ * creates `wicked-qe.db` (+ WAL/SHM) inside the checkout, runs migrations and
+ * a stale-run UPDATE sweep — and the index-healing `rebuildIndex()` this
+ * module used to call on top of that bulk-inserted every canonical row into
+ * the fresh index, which is where a legacy ledger's scenarios without
+ * `format_version` failed ("SQLite write failed … NOT NULL constraint"). A
+ * GET must leave the repository byte-identical. Canonical JSON is
+ * authoritative by the ledger's own schema contract (the SQLite index is a
+ * derived cache), so reading it directly loses nothing — and a record that
+ * cannot be parsed is surfaced as a read failure (`error`), never skipped
+ * into a cleaner answer.
+ *
+ * ATTRIBUTION (F-E2E-013): the gate answers about ONE crew run, so a verdict
+ * is served only when it can be tied to that run — see {@link ReadSubject}.
+ * "The newest PASS in the store" is not evidence about a run that recorded
+ * none (the regression: an onboarding run that failed at plan time was shown a
+ * two-month-old PASS from the repo's committed legacy ledger). Among the QE
+ * runs that ARE this run's, deny-dominates holds ACROSS them: each QE run's
+ * newest verdict is its current judgment, and one non-PASS among those denies
+ * (review of #539, F2 — a later PASS on scenario Y must not mask a FAIL on
+ * scenario X inside the same crew run).
  */
 import type { EvidenceManifest, RunRecord, VerdictRecord } from 'wicked-ledger';
 /**
@@ -28,6 +44,15 @@ import type { EvidenceManifest, RunRecord, VerdictRecord } from 'wicked-ledger';
  */
 export declare const DEFAULT_QE_LEDGER_DIRNAME = ".wicked-qe";
 export declare const LEGACY_QE_LEDGER_DIRNAME = ".wicked-testing";
+/**
+ * The field a QE writer running INSIDE a governed run stamps on the ledger run
+ * (and/or verdict) it records: the crew run id the engine hands every worker as
+ * `WICKED_RUN_ID`. Canonical JSON preserves any field a writer supplies, so this
+ * needs no ledger schema change; a record carrying it is attributed to that run
+ * regardless of timing. (garden's QE runner does not stamp it yet — a wave-7
+ * follow-up; until then lifetime linkage below is the inferred fallback.)
+ */
+export declare const CREW_RUN_ID_FIELD = "crew_run_id";
 /** The configured ledger dir name: `WICKED_QE_LEDGER_DIR` env override, else the default. */
 export declare function qeLedgerDirName(): string;
 /**
@@ -41,48 +66,123 @@ export declare function qeLedgerDirName(): string;
  */
 export declare function qeLedgerRoot(repoRoot: string): string;
 /**
- * The acceptance-relevant slice of a repo's ledger.
+ * The crew run a ledger read is FOR — what a verdict has to be tied to before
+ * it is served as that run's acceptance evidence.
+ */
+export interface RunLinkage {
+    /** The crew run id (what a QE writer inside the run sees as `WICKED_RUN_ID`). */
+    runId: string;
+    /**
+     * Epoch millis the crew run started — its `sessionStarted` capture time from
+     * the durable event log. `null` when the log records no start (an unknown
+     * window links nothing: evidence that cannot be placed inside the run is not
+     * the run's evidence).
+     */
+    startedAt: number | null;
+    /**
+     * Epoch millis the run reached a terminal state — the FIRST terminal frame in
+     * its log (`sessionCompleted` / `sessionFailed` / `runCancelled`); `null`
+     * while it is live (window open).
+     */
+    finishedAt: number | null;
+    /**
+     * Set when the run's event log could not be read at all (the read binding
+     * threw) — a different fact from "the log records no start", with a
+     * different remedy, so the denial names it (review of #539, F5).
+     */
+    logUnreadable?: string;
+}
+/**
+ * What a read is scoped to: an explicit QE run (`?qeRun=<id>` — the caller
+ * asserts the linkage), or the crew run whose evidence is wanted.
+ */
+export type ReadSubject = {
+    qeRunId: string;
+} | {
+    run: RunLinkage;
+};
+/**
+ * How the served verdict was tied to the crew run — or why none was. Always
+ * populated on a found ledger; the route serves it so the answer explains itself.
+ */
+export type QeAttribution = 
+/** The caller pinned the QE run (`?qeRun=`); its newest verdict is served. */
+{
+    kind: 'pinned';
+    qeRunId: string;
+}
+/** The ledger run (or one of its verdicts) carries `crew_run_id` naming this crew run. */
+ | {
+    kind: 'stamped';
+    qeRunId: string;
+}
+/** INFERRED: the QE run started inside this crew run's recorded lifetime (not stamped by the writer). */
+ | {
+    kind: 'run-window';
+    qeRunId: string;
+    qeRunStartedAt: string;
+}
+/** Nothing in the ledger is this run's evidence; `reason` says what the ledger does hold. */
+ | {
+    kind: 'none';
+    reason: string;
+};
+/**
+ * One line a human can read on `gate.reason`: HOW the served verdict was tied to
+ * the run, with the inferred kind labelled as such — an operator must be able to
+ * tell "the writer said so" from "it happened while the run was live".
+ */
+export declare function describeAttribution(a: QeAttribution): string;
+/**
+ * The acceptance-relevant slice of a repo's ledger, scoped to one subject.
  *
  * `found: false` means the repo has no ledger at all (the dir is absent) —
  * a distinct fact from "a ledger with no verdicts", and the gate treats both
  * as a deny with different reasons. `error` carries a read-layer failure
- * (store threw); it is never set on an ordinary empty ledger.
+ * (unreadable dir, a record that is not valid JSON); it is never set on an
+ * ordinary empty ledger.
  */
 export interface QeAcceptanceState {
     /** Absolute ledger root that was read (or probed). */
     root: string;
     /** Whether the ledger root exists on disk. */
     found: boolean;
-    /** The QE run the verdict belongs to, when resolvable. */
+    /** The QE run the served verdict belongs to, when resolvable. */
     run: RunRecord | null;
-    /** The governing verdict row — newest first, the ledger's system of record. */
+    /**
+     * The governing verdict for the subject: among the attributed QE runs' newest
+     * verdicts, the newest non-PASS if there is one (deny-dominates), else the
+     * newest PASS.
+     */
     verdict: VerdictRecord | null;
     /** The public evidence manifest for that run, when present and parseable. */
     manifest: EvidenceManifest | null;
     /** Absolute path the manifest was read from (null when absent). */
     manifestPath: string | null;
-    /** Read-layer failure detail (store open/read threw). */
+    /** How `verdict` was tied to the subject, or why nothing was. */
+    attribution: QeAttribution;
+    /** How many live verdicts the ledger holds in total — the repo-level picture the scoped read was carved from. */
+    ledgerVerdicts: number;
+    /**
+     * How many QE runs are attributed to the subject (each contributes its newest
+     * verdict to the deny-dominates set `verdict` was resolved over). 1 for a pin.
+     */
+    attributedVerdicts: number;
+    /** Read-layer failure detail (a record could not be read or parsed). */
     error?: string;
 }
 /**
- * Read the ledger's current acceptance state for a repo.
+ * Read the ledger's acceptance state for a repo, scoped to `subject`.
  *
- * The newest verdict row governs (`opts.qeRunId` narrows to one QE run's
- * newest verdict instead). The verdicts TABLE is the system of record — the
- * manifest is the public artifact built from it at run finalization, returned
- * here as display evidence, never as a gate input: a run can legitimately be
- * re-reviewed after its manifest was built, and the newer verdict row wins.
+ * The verdicts TABLE is the system of record — the manifest is the public
+ * artifact built from it at run finalization, returned here as display
+ * evidence, never as a gate input: a run can legitimately be re-reviewed
+ * after its manifest was built, and the newer verdict row wins.
  *
- * Index-drift healing: the store is dual-write (canonical JSON + a derived
- * SQLite index) and a writer that degraded to JSON-only leaves the index
- * behind. When the index answers "no verdicts" but canonical verdict files
- * exist, the index is provably stale, so it is rebuilt from JSON once and
- * re-read — otherwise a ledger full of evidence would read as "missing
- * evidence ⇒ deny", a wrong answer in the honest direction but still wrong.
+ * Reads canonical JSON only (see the module header): nothing under the ledger
+ * root is created, modified or removed by this call.
  */
-export declare function readAcceptanceState(repoRoot: string, opts?: {
-    qeRunId?: string;
-}): Promise<QeAcceptanceState>;
+export declare function readAcceptanceState(repoRoot: string, subject: ReadSubject): Promise<QeAcceptanceState>;
 /** The summary of a manifest the acceptance route serves (never the full artifact list). */
 export interface QeManifestSummary {
     manifestVersion: string;

package/dist/qe/ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/qe/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEhF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,eAAe,CAAC;AACtD,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D,6FAA6F;AAC7F,wBAAgB,eAAe,IAAI,MAAM,CAGxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQrD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,KAAK,EAAE,OAAO,CAAC;IACf,0DAA0D;IAC1D,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IACtB,+EAA+E;IAC/E,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAClC,mEAAmE;IACnE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAaD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAqC5B;AAgBD,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACzE;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,iBAAiB,CAa/E"}
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/qe/ledger.ts"],"names":[],"mappings":"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"}