karajan-code 4.57.3 → 4.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.57.3",
+  "version": "4.59.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli/register-pipeline.js

@@ -15,6 +15,7 @@ import { statusCommand } from "../commands/status.js";
 import { loadPlan } from "../plan/plan-store.js";
 import { withConfig } from "./_shared.js";
 import { publishPrReview } from "../review/publish-pr.js";
+import { verifyPrReview } from "../review/verify-pr.js";
 import { thirdPartyReviewCommand } from "../review/third-party-review.js";
 
 /**
@@ -258,8 +259,10 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--walked <route>", "Recorrido comprobado como lo haría una persona (repetible) — queda en el veredicto", (v, prev) => [...(prev || []), v], [])
     .option("--walked-with <tool>", "Con qué se comprobó el recorrido (por ejemplo chrome-devtools)")
     .option("--publish-pr <n>", "Publish the cross-AI verdicts of a PR's commits on it as one GitHub review")
+    .option("--verify-pr <n>", "CI check: every commit of the PR is listed, with its diff hash, in the kj review a member published")
     .option("--third-party", "Review someone else's PR (--range base...head): reviewer only, no own-work gates, no verdict stored")
     .option("--json", "With --third-party: print the review as one JSON document on stdout")
+    .option("--lens <lens>", "With --third-party: what the reviewer looks at; qa = test coverage, weak assertions, flakiness, test data")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
         // KJC-TSK-1075 (#2227): a third-party PR, for reviewer agents; own work keeps every gate.
@@ -273,6 +276,14 @@ export function registerPipeline(program, { pkgVersion }) {
           logger.info(r.published ? `✓ PR #${flags.publishPr}: review published (${r.commits} commit(s))` : `PR #${flags.publishPr}: ${r.reason}`);
           return;
         }
+        // KJC-TSK-1088: the CI side of the same review; a commit without its verdict fails the check.
+        if (flags.verifyPr) {
+          const r = await verifyPrReview({ projectDir: config.projectDir || process.cwd(), pr: flags.verifyPr });
+          if (r.ok) logger.info(`✓ PR #${flags.verifyPr}: ${r.commits} commit(s), each with its cross-AI verdict`);
+          else logger.error(`✗ PR #${flags.verifyPr}:\n  - ${r.problems.join("\n  - ")}`);
+          process.exitCode = r.ok ? 0 : 1;
+          return;
+        }
         // ENV-B1 (KJC-TSK-0637): the gate mode records a verdict tied to
         // the exact diff so the pre-commit hook can enforce cross-AI review.
         if (flags.staged || flags.check || flags.range || flags.installGate || flags.prune) {

package/src/harden/sandbox.js

@@ -60,8 +60,13 @@ export function probeSandbox({ platform = process.platform, which = whichOnPath,
 // Outside the project only kj's state and package caches are writable, and the
 // supervisor and the phone key stay out of reach.
 const METHOD_SANDBOX = {
-  excludedCommands: ["gh *", "kj review *"],
-  denyWrite: [".karajan/harness", ".karajan/supervisor-provenance.json", "~/.karajan/supervisor-phone.json"],
+  // KJC-TSK-1114: with these denied, the Sentinel's Bash-text guards step aside (plan KJC-TSK-1081);
+  // kj worktree runs outside, it is the sanctioned way to create and remove lanes.
+  excludedCommands: ["gh *", "kj review *", "kj worktree *"],
+  denyWrite: [
+    ".karajan/harness", ".karajan/hooks", ".claude/settings.json", ".karajan/supervisor-provenance.json", "~/.karajan/supervisor-phone.json",
+    "kj.config.yml", ".ragignore", ".kj/worktrees",
+  ],
   allowWrite: ["~/.karajan", "~/.npm/_cacache", "~/.npm/_logs", "~/.npm/_npx", "~/.cache", "~/.config/configstore"],
   allowedDomains: [
     "github.com", "api.github.com", "*.githubusercontent.com", "uploads.github.com", "registry.npmjs.org",

package/src/harden/sentinel/sentinel-bash-write.mjs

@@ -2,7 +2,7 @@
 // ADR 0014). Inside the repo, files are written through Edit/Write only, the path
 // every gate guards. Copied byte for byte into .karajan/harness; `root` injected.
 // The stated limit: a program you run can write files; only a sandbox stops that.
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { headIndex, shellSegments, withoutRedirections } from "./sentinel-shell.mjs";
@@ -100,3 +100,29 @@ export const writesRepo = (t, root) => {
   }
   return !rel.startsWith("..") && !rel.startsWith("/");
 };
+
+/** The project's sandbox settings: the local file wins over the shared one; unreadable is none. */
+const sandboxOf = (root) => {
+  for (const file of ["settings.local.json", "settings.json"]) {
+    const p = join(root, ".claude", file);
+    if (!existsSync(p)) continue;
+    try {
+      return JSON.parse(readFileSync(p, "utf8")).sandbox ?? null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+};
+
+/**
+ * KJC-TSK-1114 (plan KJC-TSK-1081): does the host sandbox already deny Bash writes to
+ * every one of these repo-relative paths? Only then does a guard that reads Bash text
+ * step aside. A sandbox that is off, can be bypassed or misses a path covers nothing.
+ */
+export const sandboxCovers = (root, paths) => {
+  const sb = sandboxOf(root);
+  if (sb?.enabled !== true || sb.allowUnsandboxedCommands !== false) return false;
+  const denied = (sb.filesystem?.denyWrite ?? []).map((d) => String(d).replace(/^\.\//, "").replace(/\/+$/, ""));
+  return paths.every((p) => denied.some((d) => p === d || p.startsWith(d + "/")));
+};

package/src/harden/sentinel-hooks.js

@@ -479,7 +479,7 @@ import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, STATE, branchOf, foreignLa
 // KJC-TSK-0915 (ADR 0014): the shell reader is a real, unit-tested module copied here as is.
 import { isGhIssueCreate, isPublishCommand, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues, stripTextOnlyCommandValues } from "./sentinel-shell.mjs";
 import { DISCARD_VERBS, discardOf, foreignLost, removedFiles } from "./sentinel-discard.mjs";
-import { shellWrites, writesRepo } from "./sentinel-bash-write.mjs";
+import { sandboxCovers, shellWrites, writesRepo } from "./sentinel-bash-write.mjs";
 const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
 const inOrder = (want, got) => { let i = 0; for (const w of got) if (w === want[i] && ++i === want.length) return true; return false; };
 // KJC-BUG-0333: a publish is read per simple command by the shell reader, so
@@ -547,7 +547,9 @@ process.stdin.on("end", () => {
     // the Read/Grep tools are for. Shell indirection (variables, globs,
     // substitution) cannot be resolved from command text: that vector is
     // caught by the Stop gate's checksum verification, which blocks the turn.
-    if (tool === "Bash" && PROTECTED.test(String(input.command || "").replaceAll("\\\\", "/"))) {
+    // KJC-TSK-1114: where the host sandbox denies writing them, the sandbox guards them instead.
+    const SUPERVISOR_PATHS = [".claude/settings.json", ".karajan/hooks", ".karajan/harness"];
+    if (tool === "Bash" && PROTECTED.test(String(input.command || "").replaceAll("\\\\", "/")) && !sandboxCovers(ROOT, SUPERVISOR_PATHS)) {
       console.error("karajan sentinel: los ficheros del supervisor no se tocan desde Bash — consultalos con la tool Read/Grep; solo el humano los modifica, fuera de la sesion." + doc("supervisor"));
       process.exit(2);
     }
@@ -745,6 +747,8 @@ process.stdin.on("end", () => {
         console.error("karajan sentinel: git worktree add/remove/prune no se ejecuta desde una sesion — estructura del repo, sin escape; usa kj worktree start|done." + doc("cross-lane"));
         process.exit(2);
       }
+      // KJC-TSK-1114: where the host sandbox denies writing the lanes, it confines Bash itself.
+      if (!sandboxCovers(ROOT, [".kj/worktrees"])) {
       // Deny-unless-known-read-only: un allowlist de verbos mutadores era
       // esquivable (dd, interpretes). Solo un comando SIMPLE de lectura (sin
       // encadenar ni redirigir) puede nombrar otro carril; leer carriles es
@@ -876,10 +880,13 @@ process.stdin.on("end", () => {
           if (lane && laneDeny(m[1], lane)) process.exit(2);
         }
       }
+      }
     }
     // KJC-BUG-0237 (#1886): the repo is written through Edit/Write only, the path every gate
     // guards. After the lane guard, whose message is the precise one for another lane.
-    if (tool === "Bash") {
+    // KJC-TSK-1114: gates run at commit now; what only this guard kept, the governance
+    // files, the host sandbox denies where it covers them.
+    if (tool === "Bash" && !sandboxCovers(ROOT, ["kj.config.yml", ".ragignore"])) {
       let moved = false; // after cd/pushd/popd, a relative target cannot be placed: fail-closed
       // $( ) and backticks run even inside double quotes: their bodies, read from the raw text, are commands too.
       const raw = String(input.command || "");

package/src/privacy/scan.js

@@ -82,6 +82,16 @@ const SEMVER_JOIN = String.raw`\s*(?:(?:\|\||-)\s*${SEMVER_OP}?|${SEMVER_OP})\s*
 const SEMVER_VALUE = new RegExp(String.raw`^\s*${SEMVER_OP}?\s*${SEMVER_TOKEN}(?:${SEMVER_JOIN}${SEMVER_TOKEN})*\s*$`);
 
 /** KJC-BUG-0380: a pair is discarded only when it is a real latitude, longitude. */
+// KJC-TSK-1118: the test card numbers payment providers publish (Stripe, Braintree,
+// Adyen, PayPal docs). Only these exact numbers; a card one digit away still warns.
+const TEST_CARDS = new Set([
+  "4242424242424242", "4000056655665556", "4111111111111111", "4012888888881881", "4000000000000002",
+  "5555555555554444", "5105105105105100", "2223003122003222", "5200828282828210",
+  "378282246310005", "371449635398431", "6011111111111117", "6011000990139424",
+  "3056930009020004", "36227206271667", "3530111333300000", "3566002020360505",
+]);
+const isTestCard = (match) => TEST_CARDS.has(match.replaceAll(/[\s-]/g, ""));
+
 function inGpsRange(_match, lat, lng) {
   return Math.abs(Number(lat)) <= 90 && Math.abs(Number(lng)) <= 180;
 }
@@ -124,6 +134,14 @@ const CONTEXT_DISCARDS = [
   // range (latitude up to 90, longitude up to 180), joined by a comma. A lone
   // number or a pair out of range still warns.
   { type: "gps-pair", re: /(?<![\d.])(-?\d{1,3}\.\d{4,})\s*,\s*(-?\d{1,3}\.\d{4,})(?![\d.])/g, keep: inGpsRange },
+  // KJC-TSK-1118: numbers reserved for fiction and tests, the good practice for test data.
+  // NANP 555-0100..0199 (with an optional +1 and area code); Ofcom's drama ranges:
+  // 07700 900xxx, 020 7946 0xxx and 01632 960xxx (0 or +44). Nothing around them.
+  { type: "fictional-phone", re: /(?<![\d+])(?:\+?1[\s.-]?)?\(?\d{3}\)?[\s.-]?555[\s.-]?01\d{2}(?!\d)/g },
+  { type: "fictional-phone-uk", re: /(?<![\d+])(?:\+44\s?|0)7700\s?900\d{3}(?!\d)/g },
+  { type: "fictional-phone-uk", re: /(?<![\d+])(?:\+44\s?|0)20\s?7946\s?0\d{3}(?!\d)/g },
+  { type: "fictional-phone-uk", re: /(?<![\d+])(?:\+44\s?|0)1632\s?960\d{3}(?!\d)/g },
+  { type: "test-card", re: /(?<!\d)\d(?:[\s-]?\d){13,18}(?!\d)/g, keep: isTestCard },
   { type: "plan-id", re:/(?<![A-Za-z0-9])plan-20\d\d(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])(?:[01]\d|2[0-3])[0-5]\d[0-5]\d-[a-z0-9]{4}(?![A-Za-z0-9])/g },
 ];
 

package/src/review/pr-security.js

@@ -11,6 +11,7 @@ import { loadPrivacyList, scanText } from "../privacy/scan.js";
 import { isGeneratedPath, splitAddedByFile } from "../privacy/diff-scope.js";
 import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 import { cooldownAdvisories } from "./dep-cooldown.js";
+import { repoPrivacyAllow, withRepoAllow } from "./repo-privacy.js";
 
 const CREDENTIAL_IDS = new Set(CREDENTIAL_PATTERNS.map((p) => p.id));
 const BLOCKING_SEMGREP = new Set(["ERROR", "WARNING"]);
@@ -58,11 +59,13 @@ export async function semgrepCheck({ projectDir, files, collect = collectSemgrep
 }
 
 /** Every security and privacy check of the PR's diff. */
-export async function prSecurityChecks({ diff, projectDir, config }) {
+export async function prSecurityChecks({ diff, projectDir, config, range }) {
   const files = splitAddedByFile(diff).map((f) => f.file);
+  // KJC-TSK-1112: the reviewed repo's allow list, as it stands at the base of the range.
+  const list = withRepoAllow(loadPrivacyList(), await repoPrivacyAllow({ projectDir, range }));
   return [
     secretsCheck(diff, config),
-    privacyCheck(diff),
+    privacyCheck(diff, { list }),
     injectionCheck(diff),
     await cooldownCheck(diff, { thresholdHours: config?.supply_chain?.cooldown_hours }),
     await semgrepCheck({ projectDir, files }),

package/src/review/publish-pr.js

@@ -7,7 +7,7 @@
 import { runCommand } from "../utils/process.js";
 import { diffHash, loadVerdict } from "./verdict-store.js";
 
-const MARKER = (head) => `<!-- kj-review head=${head} -->`;
+export const MARKER = (head) => `<!-- kj-review head=${head} -->`;
 
 // gh runs in the project's own directory, so it reads and writes the same repo the verdicts belong to.
 async function json(run, cmd, args, cwd) {

package/src/review/repo-privacy.js

@@ -0,0 +1,36 @@
+/**
+ * KJC-TSK-1112: the reviewed repo's own allow list for the privacy check of a
+ * third-party PR. Only `allow` is read: a personal list never lives in a repo
+ * (it is sensitive, see privacy/scan.js). The file is read at the BASE of the
+ * range, never at the head, so a PR cannot add the exemption it needs.
+ */
+import { parse as parseYaml } from "yaml";
+import { runCommand } from "../utils/process.js";
+
+const REPO_PRIVACY = ".karajan/privacy.yml";
+
+const baseOf = (range) => {
+  const base = String(range).split(/\.{2,3}/)[0];
+  if (!base || base === range) throw new Error(`cannot read the base of the range ${range}: pass <base>...<head>`);
+  return base;
+};
+
+/** The repo's allow list at the base of the range; empty when the base has no such file. */
+export async function repoPrivacyAllow({ projectDir, range, run = runCommand }) {
+  const base = baseOf(range);
+  const res = await run("git", ["-C", projectDir, "show", `${base}:${REPO_PRIVACY}`]);
+  if (res.exitCode !== 0) {
+    if (/does not exist|exists on disk, but not in/.test(res.stderr ?? "")) return [];
+    throw new Error(`git show ${base}:${REPO_PRIVACY} failed: ${(res.stderr || "").trim()}`);
+  }
+  let raw;
+  try {
+    raw = parseYaml(res.stdout) || {};
+  } catch (err) {
+    throw new Error(`${REPO_PRIVACY} at ${base} is not valid YAML: ${err.message}`, { cause: err });
+  }
+  return Array.isArray(raw.allow) ? raw.allow.map(String).map((s) => s.trim()).filter(Boolean) : [];
+}
+
+/** The user's privacy list with the repo's allow added; the personal list stays the user's own. */
+export const withRepoAllow = (list, repoAllow) => ({ ...list, allow: [...list.allow, ...repoAllow] });

package/src/review/review-lens.js

@@ -0,0 +1,19 @@
+/**
+ * KJC-TSK-1117: a review lens changes what the reviewer looks at, not how strict
+ * it is (that is review_mode). The qa lens puts a QA rubric before the task, so a
+ * PR of test automation is judged on whether its tests would catch bugs.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getTemplatesRoot } from "../utils/templates-root.js";
+
+const RUBRICS = { qa: "reviewer-qa.md" };
+export const LENSES = Object.keys(RUBRICS);
+
+/** The reviewer's task under a lens; no lens leaves it as it is. */
+export async function lensTask(lens, task) {
+  if (!lens) return task;
+  if (!Object.hasOwn(RUBRICS, lens)) throw new Error(`unknown review lens "${lens}": use ${LENSES.join(", ")}`);
+  const rubric = (await readFile(join(getTemplatesRoot(), "roles", RUBRICS[lens]), "utf8")).trim();
+  return task ? `${rubric}\n\n## Task\n\n${task}` : rubric;
+}

package/src/review/third-party-review.js

@@ -14,6 +14,7 @@ import { isGenerated } from "./loc-budget.js";
 import { prSecurityChecks } from "./pr-security.js";
 import { sonarCheck } from "./pr-sonar.js";
 import { batchDiff, splitByFile } from "./diff-batches.js";
+import { lensTask } from "./review-lens.js";
 import { DIFF_CLIP_CHARS } from "../prompts/diff-clip.js";
 
 // KJC-BUG-0378: a reviewer call per batch; past this many, files are left out and named.
@@ -37,7 +38,7 @@ export async function thirdPartyReview({ range, config, projectDir, logger, task
   // KJC-BUG-0379 (#2263): the house requirements (size, commits, attribution, tests) travel apart:
   // on another repo with other conventions they must not read as findings next to security.
   const policyChecks = await requirements({ range, projectDir, config });
-  const checks = [...await security({ diff, projectDir, config }), await sonar({ diff, config, projectDir })];
+  const checks = [...await security({ diff, projectDir, config, range }), await sonar({ diff, config, projectDir })];
   // KJC-BUG-0378 (#2263): the whole diff, in batches of whole files that fit the reviewer's
   // prompt; what does not fit is named in the coverage and the verdict cannot be approved.
   const provider = resolveRole(config, "reviewer").provider || null;
@@ -91,7 +92,9 @@ export async function thirdPartyReviewCommand({ flags, config, out = process.std
   const log = (msg) => err.write(`${msg}\n`);
   const logger = { info: log, warn: log, error: log, debug: () => {} };
   try {
-    print(await review({ range: flags.range, config, projectDir: config.projectDir || process.cwd(), logger, task: flags.task ?? null }));
+    // KJC-TSK-1117: a lens (qa) puts its rubric before the task.
+    const task = await lensTask(flags.lens ?? null, flags.task ?? null);
+    print(await review({ range: flags.range, config, projectDir: config.projectDir || process.cwd(), logger, task }));
     return 0;
   } catch (e) {
     print({ error: e.message });

package/src/review/verify-pr.js

@@ -0,0 +1,59 @@
+/**
+ * KJC-TSK-1088: CI proof that every commit of a PR carries its cross-AI
+ * verdict, so skipping the pre-commit hook (--no-verify) cannot leave a commit
+ * unreviewed. It reads the review kj review --publish-pr posted for the PR's
+ * head, written by a member of the repo, and recomputes the hash of the diff
+ * each commit brought: a listed hash that no longer matches is no proof.
+ */
+import { runCommand } from "../utils/process.js";
+import { diffHash } from "./verdict-store.js";
+import { MARKER } from "./publish-pr.js";
+
+const TRUSTED = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
+// One line per commit, as publish-pr writes it: - `<sha7>` headline: approved by X (diff <hash12>)...
+const LISTED = /^- `([0-9a-f]{7})` .*?\(diff ([0-9a-f]{12})\)/gm;
+
+async function json(run, args, cwd) {
+  const res = await run("gh", args, { cwd });
+  if (res.exitCode !== 0) throw new Error(`gh ${args.slice(0, 3).join(" ")} failed: ${(res.stderr || res.stdout || "").trim()}`);
+  return JSON.parse(res.stdout || "null");
+}
+
+// KJC-BUG-0386: git abbreviates the object ids of the index lines by the clone's object
+// count (or core.abbrev, 4 up to the full 40), so the publisher and CI may print the
+// same diff with ids of other lengths.
+const ABBREVS = Array.from({ length: 37 }, (_, i) => i + 4);
+
+/** The diff hashes of a commit under every abbreviation git may have used where it was reviewed. */
+async function hashesOf(projectDir, sha, run) {
+  const hashes = new Set();
+  for (const n of ABBREVS) {
+    const res = await run("git", ["-C", projectDir, "diff", `--abbrev=${n}`, `${sha}^`, sha]);
+    if (res.exitCode !== 0) throw new Error(`git diff ${sha.slice(0, 7)} failed: ${(res.stderr || "").trim()}`);
+    hashes.add(diffHash(res.stdout).slice(0, 12));
+  }
+  return hashes;
+}
+
+/**
+ * @returns {Promise<{ok: boolean, commits: number, problems: string[]}>}
+ */
+export async function verifyPrReview({ projectDir, pr, run = runCommand }) {
+  const info = await json(run, ["pr", "view", String(pr), "--json", "headRefOid,commits"], projectDir);
+  const commits = info.commits ?? [];
+  // One review per line, every page: --slurp is missing from the gh that distros ship.
+  const res = await run("gh", ["api", "--paginate", `repos/{owner}/{repo}/pulls/${pr}/reviews`, "--jq", ".[] | {body, author_association}"], { cwd: projectDir });
+  if (res.exitCode !== 0) throw new Error(`gh api reviews failed: ${(res.stderr || res.stdout || "").trim()}`);
+  const reviews = (res.stdout || "").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  const review = reviews.findLast((r) => TRUSTED.has(r.author_association) && String(r.body ?? "").includes(MARKER(info.headRefOid)));
+  if (!review) {
+    return { ok: false, commits: commits.length, problems: [`no kj review published by a member for head ${info.headRefOid.slice(0, 7)}: run kj review --publish-pr ${pr}`] };
+  }
+  const listed = new Map([...review.body.matchAll(LISTED)].map((m) => [m[1], m[2]]));
+  const problems = [];
+  for (const c of commits) {
+    const hash = listed.get(c.oid.slice(0, 7));
+    if (!hash || !(await hashesOf(projectDir, c.oid, run)).has(hash)) problems.push(`${c.oid.slice(0, 7)} (${c.messageHeadline}): no approved verdict for the diff it brings`);
+  }
+  return { ok: problems.length === 0, commits: commits.length, problems };
+}

package/templates/roles/reviewer-qa.md

@@ -0,0 +1,18 @@
+# Review lens: QA
+
+Review this PR as a QA engineer, not only as a developer. Most of it may be test code: judge whether the tests would catch the bugs they exist for.
+
+## Blocking (in the diff only)
+
+- **No test for new behavior**: the change adds or changes behavior and no test exercises it.
+- **Tests that cannot fail**: no assertion, assertions only on mocks, `toBeTruthy`/`assert True` on values that are always truthy, a caught exception that swallows the failure.
+- **Flaky by construction**: fixed sleeps or timeouts instead of waiting on a condition, order dependence between tests, shared mutable state, real clock, randomness or network without control, retries that hide a failure.
+- **Real personal data or production credentials in test data.**
+
+## Suggestions (non-blocking)
+
+- **Missing scenarios**: name the edge and error cases the new tests skip (empty, boundary, invalid input, permissions, concurrency).
+- **Weak assertions**: only a status code, only "element exists", snapshots standing in for a precise check.
+- **Fragile selectors**: CSS chains, XPath by index or text that changes; prefer roles, labels or `data-testid`.
+- **Test data**: prefer values reserved for testing (emails on `example.com`/`example.org`/`.test`, fictional phone ranges such as 555-01xx or 07700 900xxx, the test card numbers each payment provider publishes) or generated data (factories, faker), created and cleaned up by each test.
+- **Structure**: one behavior per test, names that say the scenario and the expected result, page objects and flows that keep selectors out of the test body, no duplicated setup.