@slowcook-ai/cli 0.19.5 → 0.20.0

package/dist/commands/gate/github.d.ts

@@ -0,0 +1,27 @@
+/**
+ * design #9 — map GitHub PR reviews to the Approval shape `isGateSatisfied`
+ * grades. Pure + unit-tested; the live `gh api` fetch lives in ./index.ts.
+ *
+ * The identity classification is the load-bearing bit: a review authored by a
+ * Bot account (GitHub `user.type === "Bot"`, or a login ending in `[bot]`, or a
+ * known slowcook bot handle) is marked `identityType: "bot"` so it can never
+ * satisfy a human-review gate — the automation cannot self-approve.
+ */
+import type { Approval } from "./model.js";
+/** Subset of the GitHub PR-review payload we consume. */
+export interface GhReview {
+    user?: {
+        login?: string;
+        type?: string;
+    } | null;
+    state?: string;
+}
+/** Logins always treated as bots regardless of the GitHub `type` field. */
+export declare const BOT_LOGINS: ReadonlyArray<string>;
+/**
+ * Convert raw PR reviews into Approvals. Dismissed/pending reviews are dropped.
+ * Only the latest review per author is kept (GitHub returns reviews
+ * chronologically; a later review supersedes an earlier one from the same user).
+ */
+export declare function mapReviewsToApprovals(reviews: GhReview[]): Approval[];
+//# sourceMappingURL=github.d.ts.map

package/dist/commands/gate/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/github.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,yDAAyD;AACzD,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,eAAO,MAAM,UAAU,EAAE,aAAa,CAAC,MAAM,CAAsB,CAAC;AAsBpE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAcrE"}

package/dist/commands/gate/github.js

@@ -0,0 +1,46 @@
+/** Logins always treated as bots regardless of the GitHub `type` field. */
+export const BOT_LOGINS = ["github-actions"];
+function isBot(login, type) {
+    if (type === "Bot")
+        return true;
+    if (login.endsWith("[bot]"))
+        return true;
+    if (BOT_LOGINS.includes(login))
+        return true;
+    return false;
+}
+function mapState(state) {
+    switch (state) {
+        case "APPROVED":
+            return "approved";
+        case "CHANGES_REQUESTED":
+            return "rejected";
+        case "COMMENTED":
+            return "commented";
+        default:
+            return null; // DISMISSED / PENDING / unknown → not a signal
+    }
+}
+/**
+ * Convert raw PR reviews into Approvals. Dismissed/pending reviews are dropped.
+ * Only the latest review per author is kept (GitHub returns reviews
+ * chronologically; a later review supersedes an earlier one from the same user).
+ */
+export function mapReviewsToApprovals(reviews) {
+    const latestByAuthor = new Map();
+    for (const r of reviews) {
+        const login = (r.user?.login ?? "").toLowerCase();
+        if (!login)
+            continue;
+        const state = mapState(r.state);
+        if (!state)
+            continue;
+        latestByAuthor.set(login, {
+            byHandle: login,
+            state,
+            identityType: isBot(login, r.user?.type ?? undefined) ? "bot" : "human",
+        });
+    }
+    return [...latestByAuthor.values()];
+}
+//# sourceMappingURL=github.js.map

package/dist/commands/gate/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../../../src/commands/gate/github.ts"],"names":[],"mappings":"AAiBA,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAA0B,CAAC,gBAAgB,CAAC,CAAC;AAEpE,SAAS,KAAK,CAAC,KAAa,EAAE,IAAwB;IACpD,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,QAAQ,CAAC,KAAyB;IACzC,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,mBAAmB;YACtB,OAAO,UAAU,CAAC;QACpB,KAAK,WAAW;YACd,OAAO,WAAW,CAAC;QACrB;YACE,OAAO,IAAI,CAAC,CAAC,+CAA+C;IAChE,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAmB;IACvD,MAAM,cAAc,GAAG,IAAI,GAAG,EAAoB,CAAC;IACnD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAClD,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE;YACxB,QAAQ,EAAE,KAAK;YACf,KAAK;YACL,YAAY,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO;SACxE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC;AACtC,CAAC"}

package/dist/commands/gate/index.d.ts

@@ -0,0 +1,2 @@
+export declare function gate(args: string[], _version: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/gate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"AAmCA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC1E"}

package/dist/commands/gate/index.js

@@ -0,0 +1,68 @@
+/**
+ * design #9 — `slowcook gate check`. The dispatch-time HITL halt: refuse to let
+ * a stage proceed until a human in the required role has approved on the PR.
+ *
+ *   slowcook gate check --stage <refine|plate|brew> --pr <n> [--repo owner/name]
+ *
+ * Exit 0 = gate satisfied (advance). Exit 1 = blocked (a human in the required
+ * role(s) must approve, or a rejection must be resolved). Because approvals are
+ * classified by identity (./github.ts) and only human reviewers in the role's
+ * handle-list count (./model.ts), the automation cannot satisfy its own gate.
+ */
+import { execFileSync } from "node:child_process";
+import { loadReviewers } from "./reviewers.js";
+import { DEFAULT_GATES, isGateSatisfied } from "./model.js";
+import { mapReviewsToApprovals } from "./github.js";
+function val(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+function fetchReviews(repo, pr) {
+    const out = execFileSync("gh", ["api", `repos/${repo}/pulls/${pr}/reviews`, "--paginate"], {
+        encoding: "utf8",
+    });
+    return JSON.parse(out);
+}
+function detectRepo() {
+    const out = execFileSync("gh", ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"], {
+        encoding: "utf8",
+    });
+    return out.trim();
+}
+export async function gate(args, _version) {
+    const sub = args[0];
+    if (sub !== "check") {
+        console.error("usage: slowcook gate check --stage <stage> --pr <n> [--repo owner/name]");
+        process.exit(64);
+    }
+    const rest = args.slice(1);
+    const stage = val(rest, "--stage");
+    const pr = val(rest, "--pr");
+    if (!stage || !pr) {
+        console.error("gate check: --stage and --pr are required");
+        process.exit(64);
+    }
+    const gateDef = DEFAULT_GATES.find((g) => g.stage === stage);
+    if (!gateDef) {
+        console.error(`gate check: no gate defined for stage '${stage}' (have: ${DEFAULT_GATES.map((g) => g.stage).join(", ")})`);
+        process.exit(64);
+    }
+    const repo = val(rest, "--repo") ?? detectRepo();
+    const reviewers = loadReviewers(process.cwd());
+    const approvals = mapReviewsToApprovals(fetchReviews(repo, pr));
+    const verdict = isGateSatisfied(gateDef, reviewers, approvals);
+    if (verdict.satisfied) {
+        console.log(`gate '${stage}' ✓ satisfied — ${verdict.reason}`);
+        return;
+    }
+    // Blocked. Name exactly who must act.
+    const need = verdict.rejected
+        ? verdict.reason
+        : verdict.missingRoles
+            .map((r) => `${r} (${reviewers.roles[r]?.join(", ") || "no reviewers configured in .brewing/reviewers.yaml"})`)
+            .join("; ");
+    console.error(`gate '${stage}' ✗ blocked-on-review — ${verdict.reason}`);
+    console.error(`  needs approval from: ${need}`);
+    process.exit(1);
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/gate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAa,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAiB,MAAM,aAAa,CAAC;AAEnE,SAAS,GAAG,CAAC,IAAc,EAAE,IAAY;IACvC,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,EAAU;IAC5C,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,IAAI,UAAU,EAAE,UAAU,EAAE,YAAY,CAAC,EAAE;QACzF,QAAQ,EAAE,MAAM;KACjB,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;AACvC,CAAC;AAED,SAAS,UAAU;IACjB,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,gBAAgB,CAAC,EAAE;QAClG,QAAQ,EAAE,MAAM;KACjB,CAAC,CAAC;IACH,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc,EAAE,QAAgB;IACzD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;QACpB,OAAO,CAAC,KAAK,CAAC,yEAAyE,CAAC,CAAC;QACzF,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACnC,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;IAED,MAAM,OAAO,GAAqB,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;IAC/E,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,0CAA0C,KAAK,YAAY,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1H,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,UAAU,EAAE,CAAC;IACjD,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,qBAAqB,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,eAAe,CAAC,OAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAEhE,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,SAAS,KAAK,mBAAmB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/D,OAAO;IACT,CAAC;IACD,sCAAsC;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ;QAC3B,CAAC,CAAC,OAAO,CAAC,MAAM;QAChB,CAAC,CAAC,OAAO,CAAC,YAAY;aACjB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,oDAAoD,GAAG,CAAC;aAC9G,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,OAAO,CAAC,KAAK,CAAC,SAAS,KAAK,2BAA2B,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzE,OAAO,CAAC,KAAK,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/commands/gate/model.d.ts

@@ -0,0 +1,55 @@
+/**
+ * design #9 — HITL role gates: the gate-integrity core.
+ *
+ * Decides whether a pipeline stage may proceed past a human-review gate.
+ * The load-bearing security property: an approval only counts if it
+ * comes from a HUMAN identity that is in the configured handle-list for
+ * the required role. A bot/agent approval, or an approval from someone
+ * not assigned that role, NEVER satisfies a gate. This is what makes the
+ * halt unforgeable by the automation driving the pipeline.
+ */
+import { type ReviewersConfig } from "./reviewers.js";
+export type Role = "pm" | "designer" | "qa";
+export type Stage = "refine" | "plate" | "brew" | string;
+export interface Gate {
+    stage: Stage;
+    requiredRoles: Role[];
+    approvalSignal: "review" | "comment";
+    onRejectTarget: Stage;
+}
+export interface Approval {
+    /** GitHub handle of the approver. */
+    byHandle: string;
+    state: "approved" | "rejected" | "commented";
+    /** bot = slowcook-*[bot] / the driving agent; human = a real reviewer. */
+    identityType: "human" | "bot";
+}
+export interface GateVerdict {
+    satisfied: boolean;
+    /** required roles lacking a valid human approval. */
+    missingRoles: Role[];
+    /** a valid human reviewer for a required role rejected. */
+    rejected: boolean;
+    /** human-readable summary. */
+    reason: string;
+}
+/**
+ * The standard pipeline gates. refine is signed off by a PM, plate by a
+ * designer, and brew needs BOTH qa and designer before code ships.
+ */
+export declare const DEFAULT_GATES: Gate[];
+/**
+ * Evaluate a gate against the reviewer roster and the observed approvals.
+ *
+ * - A valid approval for role R = human + state 'approved' + handle in
+ *   the role's configured list.
+ * - A valid rejection for role R = same, but state 'rejected'.
+ * - `rejected` is true if ANY required role has a valid rejection; a
+ *   rejected gate is never satisfied (and routes back to onRejectTarget,
+ *   handled by the caller).
+ * - `missingRoles` lists required roles with no valid approval.
+ * - `satisfied` requires every required role to have a valid approval
+ *   AND no valid rejection.
+ */
+export declare function isGateSatisfied(gate: Gate, reviewers: ReviewersConfig, approvals: Approval[]): GateVerdict;
+//# sourceMappingURL=model.d.ts.map

package/dist/commands/gate/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEnE,MAAM,MAAM,IAAI,GAAG,IAAI,GAAG,UAAU,GAAG,IAAI,CAAC;AAC5C,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,aAAa,EAAE,IAAI,EAAE,CAAC;IACtB,cAAc,EAAE,QAAQ,GAAG,SAAS,CAAC;IACrC,cAAc,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC;IAC7C,0EAA0E;IAC1E,YAAY,EAAE,OAAO,GAAG,KAAK,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,qDAAqD;IACrD,YAAY,EAAE,IAAI,EAAE,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,IAAI,EAI/B,CAAC;AAwBF;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,eAAe,EAC1B,SAAS,EAAE,QAAQ,EAAE,GACpB,WAAW,CAoBb"}

package/dist/commands/gate/model.js

@@ -0,0 +1,64 @@
+/**
+ * design #9 — HITL role gates: the gate-integrity core.
+ *
+ * Decides whether a pipeline stage may proceed past a human-review gate.
+ * The load-bearing security property: an approval only counts if it
+ * comes from a HUMAN identity that is in the configured handle-list for
+ * the required role. A bot/agent approval, or an approval from someone
+ * not assigned that role, NEVER satisfies a gate. This is what makes the
+ * halt unforgeable by the automation driving the pipeline.
+ */
+import { resolveRole } from "./reviewers.js";
+/**
+ * The standard pipeline gates. refine is signed off by a PM, plate by a
+ * designer, and brew needs BOTH qa and designer before code ships.
+ */
+export const DEFAULT_GATES = [
+    { stage: "refine", requiredRoles: ["pm"], approvalSignal: "review", onRejectTarget: "refine" },
+    { stage: "plate", requiredRoles: ["designer"], approvalSignal: "review", onRejectTarget: "plate" },
+    { stage: "brew", requiredRoles: ["qa", "designer"], approvalSignal: "review", onRejectTarget: "brew" },
+];
+/**
+ * True when `approvals` contains an approval in `state` for role `role`
+ * that is BOTH human-authored AND from a handle configured for that role
+ * in `reviewers`. Handle matching is case-insensitive (both sides
+ * lowercased). This is the single chokepoint enforcing the integrity
+ * property — a bot identity or an unconfigured handle can never pass.
+ */
+function hasValidSignal(reviewers, approvals, role, state) {
+    const allowed = new Set(resolveRole(reviewers, role)); // already lowercased on load
+    return approvals.some((a) => a.identityType === "human" &&
+        a.state === state &&
+        allowed.has(a.byHandle.toLowerCase()));
+}
+/**
+ * Evaluate a gate against the reviewer roster and the observed approvals.
+ *
+ * - A valid approval for role R = human + state 'approved' + handle in
+ *   the role's configured list.
+ * - A valid rejection for role R = same, but state 'rejected'.
+ * - `rejected` is true if ANY required role has a valid rejection; a
+ *   rejected gate is never satisfied (and routes back to onRejectTarget,
+ *   handled by the caller).
+ * - `missingRoles` lists required roles with no valid approval.
+ * - `satisfied` requires every required role to have a valid approval
+ *   AND no valid rejection.
+ */
+export function isGateSatisfied(gate, reviewers, approvals) {
+    const rejectingRoles = gate.requiredRoles.filter((role) => hasValidSignal(reviewers, approvals, role, "rejected"));
+    const missingRoles = gate.requiredRoles.filter((role) => !hasValidSignal(reviewers, approvals, role, "approved"));
+    const rejected = rejectingRoles.length > 0;
+    const satisfied = !rejected && missingRoles.length === 0;
+    let reason;
+    if (rejected) {
+        reason = `rejected by ${rejectingRoles.join(", ")}`;
+    }
+    else if (missingRoles.length > 0) {
+        reason = `blocked: missing ${missingRoles.join(", ")} approval`;
+    }
+    else {
+        reason = "satisfied";
+    }
+    return { satisfied, missingRoles, rejected, reason };
+}
+//# sourceMappingURL=model.js.map

package/dist/commands/gate/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/commands/gate/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,WAAW,EAAwB,MAAM,gBAAgB,CAAC;AA8BnE;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAW;IACnC,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE;IAC9F,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,UAAU,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE;IAClG,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE;CACvG,CAAC;AAEF;;;;;;GAMG;AACH,SAAS,cAAc,CACrB,SAA0B,EAC1B,SAAqB,EACrB,IAAU,EACV,KAA8B;IAE9B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,6BAA6B;IACpF,OAAO,SAAS,CAAC,IAAI,CACnB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,YAAY,KAAK,OAAO;QAC1B,CAAC,CAAC,KAAK,KAAK,KAAK;QACjB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAU,EACV,SAA0B,EAC1B,SAAqB;IAErB,MAAM,cAAc,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CACxD,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,CAAC,CACvD,CAAC;IACF,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAC5C,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,CAAC,CAClE,CAAC;IACF,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,CAAC,QAAQ,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC;IAEzD,IAAI,MAAc,CAAC;IACnB,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,GAAG,eAAe,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACtD,CAAC;SAAM,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,GAAG,oBAAoB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;IAClE,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,WAAW,CAAC;IACvB,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AACvD,CAAC"}

package/dist/commands/gate/reviewers.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+declare const ReviewersConfigSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    roles: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>, z.ZodTransform<Record<string, string[]>, Record<string, string[]>>>;
+}, z.core.$strip>;
+export type ReviewersConfig = z.infer<typeof ReviewersConfigSchema>;
+declare const EMPTY_DEFAULT: ReviewersConfig;
+/**
+ * Load `.brewing/reviewers.yaml`. Returns an empty roster
+ * (`{ schema_version: 1, roles: {} }`) when the file is absent — a repo
+ * with no roster has no configured reviewers, so every role gate is
+ * unsatisfiable until one is authored (fail-closed). Throws on parse
+ * error / schema violation so a mis-authored roster surfaces loudly
+ * rather than silently granting or denying approvals.
+ */
+export declare function loadReviewers(repoRoot: string): ReviewersConfig;
+/**
+ * Returns the configured handles for a role (already lowercased), or an
+ * empty array when the role is unset. An empty array means the role can
+ * never be satisfied — fail-closed by design.
+ */
+export declare function resolveRole(cfg: ReviewersConfig, role: string): string[];
+export { EMPTY_DEFAULT };
+//# sourceMappingURL=reviewers.d.ts.map

package/dist/commands/gate/reviewers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewers.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/reviewers.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,qBAAqB;;;iBAazB,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,QAAA,MAAM,aAAa,EAAE,eAGpB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAa/D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAExE;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/commands/gate/reviewers.js

@@ -0,0 +1,69 @@
+/**
+ * design #9 — HITL role gates: reviewer roster.
+ *
+ * Reads `.brewing/reviewers.yaml` to map review roles (pm, designer, qa,
+ * …) to the GitHub handles authorised to satisfy that role's gate. This
+ * roster is the trust anchor for the gate-integrity core: an approval
+ * only counts if its author is a configured handle for the required
+ * role (see `./model.js`).
+ *
+ * Handles are lowercased on load so downstream matching against the
+ * (also lowercased) approver handle is case-insensitive — GitHub login
+ * comparison is case-insensitive and a gate must not be bypassable by a
+ * casing mismatch.
+ *
+ * Single source of truth: nothing else should hard-code the roster
+ * location or shape.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+const ReviewersConfigSchema = z.object({
+    schema_version: z.literal(1),
+    // role -> list of GitHub handles. Lowercased on load (see transform).
+    roles: z
+        .record(z.string(), z.array(z.string()))
+        .default({})
+        .transform((roles) => {
+        const out = {};
+        for (const [role, handles] of Object.entries(roles)) {
+            out[role] = handles.map((h) => h.toLowerCase());
+        }
+        return out;
+    }),
+});
+const EMPTY_DEFAULT = {
+    schema_version: 1,
+    roles: {},
+};
+/**
+ * Load `.brewing/reviewers.yaml`. Returns an empty roster
+ * (`{ schema_version: 1, roles: {} }`) when the file is absent — a repo
+ * with no roster has no configured reviewers, so every role gate is
+ * unsatisfiable until one is authored (fail-closed). Throws on parse
+ * error / schema violation so a mis-authored roster surfaces loudly
+ * rather than silently granting or denying approvals.
+ */
+export function loadReviewers(repoRoot) {
+    const p = join(repoRoot, ".brewing", "reviewers.yaml");
+    if (!existsSync(p)) {
+        return { schema_version: 1, roles: {} };
+    }
+    const raw = YAML.parse(readFileSync(p, "utf8"));
+    const parsed = ReviewersConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid .brewing/reviewers.yaml: ${parsed.error.issues.map((i) => i.message).join("; ")}`);
+    }
+    return parsed.data;
+}
+/**
+ * Returns the configured handles for a role (already lowercased), or an
+ * empty array when the role is unset. An empty array means the role can
+ * never be satisfied — fail-closed by design.
+ */
+export function resolveRole(cfg, role) {
+    return cfg.roles[role] ?? [];
+}
+export { EMPTY_DEFAULT };
+//# sourceMappingURL=reviewers.js.map

package/dist/commands/gate/reviewers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewers.js","sourceRoot":"","sources":["../../../src/commands/gate/reviewers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5B,sEAAsE;IACtE,KAAK,EAAE,CAAC;SACL,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;SACvC,OAAO,CAAC,EAAE,CAAC;SACX,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QACnB,MAAM,GAAG,GAA6B,EAAE,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;CACL,CAAC,CAAC;AAIH,MAAM,aAAa,GAAoB;IACrC,cAAc,EAAE,CAAC;IACjB,KAAK,EAAE,EAAE;CACV,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC;IACvD,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,cAAc,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC1C,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,oCAAoC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3F,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAoB,EAAE,IAAY;IAC5D,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/commands/recon/shape-preserve.d.ts

@@ -30,12 +30,50 @@ export interface ExtractedShape {
     hasHeader: boolean;
     /** Component name (best-effort). */
     componentName: string | null;
+    /**
+     * design #10 — dense, paradigm-aware per-element class facts. Unlike
+     * `visualTokens` (filtered through the 17-item TOKENS_OF_INTEREST
+     * allowlist), this captures the element's *actual* utility-class set so
+     * the shape test can assert `brewed ⊇ mock` containment per element and
+     * drift can't hide in unpinned classes. Optional + additive: absent on
+     * hand-built fixtures and pre-#10 callers.
+     */
+    elementClasses?: ElementClassFacts[];
+}
+/** design #10 — one element's testid anchor + its utility-class tokens. */
+export interface ElementClassFacts {
+    /** data-testid on the element, or null (anchor for per-element assertions). */
+    testid: string | null;
+    /** Utility-shaped class tokens on the element (string-literal classNames only). */
+    tokens: string[];
 }
 /**
  * Scan a mock UI file, return the SHAPE-relevant facts after stripping
  * mock-only chrome subtrees.
  */
 export declare function extractShape(absFile: string, repoRoot: string): ExtractedShape | null;
+/**
+ * design #10 — extract per-element utility-class facts from a (mock-chrome-
+ * stripped) source. Paradigm-aware: only reads STRING-LITERAL classNames
+ * (`className="..."` / `'...'` / plain backtick). `className={...}` brace
+ * expressions — CSS-modules (`{styles.x}`), `cx(...)`, conditional template
+ * literals with `${}` — are SKIPPED, because their tokens are either hashed
+ * identifiers (noise, not design intent) or computed; extracting them would
+ * be over-extraction. Styling fidelity for those mocks defers to the #8 eye.
+ *
+ * Pairs each element's tokens with its `data-testid` (the stable anchor for
+ * per-element containment assertions). Only elements carrying ≥1 utility
+ * token are returned.
+ */
+export declare function extractElementClasses(source: string): ElementClassFacts[];
+/**
+ * Heuristic: is `t` a utility-class token (Tailwind-shaped) rather than a
+ * component/module identifier? Keeps lowercase-led tokens + any token with
+ * a utility marker (`-`, `:`, `[`); drops capitalised identifiers and the
+ * empty string. Errs permissive — string-literal classNames in a utility
+ * mock are virtually all utilities.
+ */
+export declare function isUtilityShaped(t: string): boolean;
 /**
  * Strip JSX subtrees marked as mock-only chrome. Two conventions:
  *   1. data-mock-chrome="true" attribute on the wrapping element

package/dist/commands/recon/shape-preserve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shape-preserve.d.ts","sourceRoot":"","sources":["../../../src/commands/recon/shape-preserve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,IAAI,EAAY,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iFAAiF;IACjF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAWD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAiBrF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAY9D;AA0GD,UAAU,SAAS;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAK/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAiFjE;AAkFD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA+E/E;AAGD,OAAO,EAAE,IAAI,IAAI,KAAK,EAAE,CAAC"}
+{"version":3,"file":"shape-preserve.d.ts","sourceRoot":"","sources":["../../../src/commands/recon/shape-preserve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,IAAI,EAAY,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iFAAiF;IACjF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACtC;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mFAAmF;IACnF,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAWD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAkBrF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAoBzE;AAkBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAIlD;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAY9D;AA0GD,UAAU,SAAS;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAK/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAqHjE;AA6FD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA+E/E;AAGD,OAAO,EAAE,IAAI,IAAI,KAAK,EAAE,CAAC"}

package/dist/commands/recon/shape-preserve.js

@@ -45,7 +45,76 @@ export function extractShape(absFile, repoRoot) {
     const testids = [...new Set(extractTestids(cleaned))];
     const visualTokens = [...new Set(extractTokens(cleaned, TOKENS_OF_INTEREST))];
     const hasHeader = /<header\b/.test(cleaned);
-    return { file: fileRel, testids, visualTokens, hasHeader, componentName };
+    const elementClasses = extractElementClasses(cleaned);
+    return { file: fileRel, testids, visualTokens, hasHeader, componentName, elementClasses };
+}
+/**
+ * design #10 — extract per-element utility-class facts from a (mock-chrome-
+ * stripped) source. Paradigm-aware: only reads STRING-LITERAL classNames
+ * (`className="..."` / `'...'` / plain backtick). `className={...}` brace
+ * expressions — CSS-modules (`{styles.x}`), `cx(...)`, conditional template
+ * literals with `${}` — are SKIPPED, because their tokens are either hashed
+ * identifiers (noise, not design intent) or computed; extracting them would
+ * be over-extraction. Styling fidelity for those mocks defers to the #8 eye.
+ *
+ * Pairs each element's tokens with its `data-testid` (the stable anchor for
+ * per-element containment assertions). Only elements carrying ≥1 utility
+ * token are returned.
+ */
+export function extractElementClasses(source) {
+    const facts = [];
+    // Iterate JSX opening tags (and self-closing). Attr blob is captured
+    // non-greedily up to the tag close.
+    for (const m of source.matchAll(/<[A-Za-z][\w.]*\b([^>]*?)\/?>/g)) {
+        const attrs = m[1] ?? "";
+        const className = literalClassName(attrs);
+        if (className === null)
+            continue; // dynamic/module/no className → skip
+        const tokens = className
+            .split(/\s+/)
+            .map((t) => t.trim())
+            .filter((t) => isUtilityShaped(t));
+        if (tokens.length === 0)
+            continue;
+        const tidMatch = attrs.match(/data-testid\s*=\s*["']([^"']+)["']/);
+        facts.push({
+            testid: tidMatch?.[1] ?? null,
+            tokens: [...new Set(tokens)],
+        });
+    }
+    return facts;
+}
+/**
+ * Return the string-literal value of a `className` attribute from a tag's
+ * attr blob, or null when the className is absent or a brace expression
+ * (`className={...}` — dynamic/module/computed; intentionally not read).
+ * Plain backtick literals are read only when they contain no `${}`.
+ */
+function literalClassName(attrs) {
+    const dq = attrs.match(/className\s*=\s*"([^"]*)"/);
+    if (dq)
+        return dq[1] ?? "";
+    const sq = attrs.match(/className\s*=\s*'([^']*)'/);
+    if (sq)
+        return sq[1] ?? "";
+    const bt = attrs.match(/className\s*=\s*`([^`]*)`/);
+    if (bt && !bt[1]?.includes("${"))
+        return bt[1] ?? "";
+    return null;
+}
+/**
+ * Heuristic: is `t` a utility-class token (Tailwind-shaped) rather than a
+ * component/module identifier? Keeps lowercase-led tokens + any token with
+ * a utility marker (`-`, `:`, `[`); drops capitalised identifiers and the
+ * empty string. Errs permissive — string-literal classNames in a utility
+ * mock are virtually all utilities.
+ */
+export function isUtilityShaped(t) {
+    if (!t)
+        return false;
+    if (/[-:[]/.test(t))
+        return true; // bg-primary, hover:..., min-h-[44px]
+    return /^[a-z][a-z0-9]*$/.test(t); // flex, grid, block, hidden, relative
 }
 /**
  * Strip JSX subtrees marked as mock-only chrome. Two conventions:
@@ -272,6 +341,39 @@ export function synthesiseShapeTestFileV2(opts) {
                 lines.push(`      expect(container.querySelector("header")).toBeTruthy();`);
                 lines.push(`    });`);
             }
+            // design #10 — per-element class containment (brewed ⊇ mock), anchored
+            // by testid. Asserts the rendered element keeps the mock's utility-class
+            // set; brew may ADD real-data classes (containment, not equality) but
+            // not DROP the mock's styling.
+            for (const ec of shape.elementClasses ?? []) {
+                if (!ec.testid || ec.tokens.length === 0)
+                    continue;
+                lines.push(`    it("[data-testid=${ec.testid}] keeps mock class tokens", () => {`);
+                lines.push(`      const { queryByTestId } = render(<${cn} />);`);
+                lines.push(`      const el = queryByTestId(${JSON.stringify(ec.testid)});`);
+                lines.push(`      expect(el, ${JSON.stringify(`expected [data-testid=${ec.testid}] in rendered <${cn} />`)}).toBeTruthy();`);
+                lines.push(`      const have = (el?.getAttribute("class") ?? "").split(/\\s+/);`);
+                lines.push(`      const missing = ${JSON.stringify(ec.tokens)}.filter((t) => !have.includes(t));`);
+                lines.push(`      expect(missing, "dropped mock class tokens").toEqual([]);`);
+                lines.push(`    });`);
+            }
+            // design #10 — no-testid dense coverage: tokens on unanchored elements
+            // can't be matched per-element, so assert each survives SOMEWHERE in the
+            // rendered tree (file-level containment via [class*=]). Excludes tokens
+            // already covered by a testid-anchored or visualToken assertion.
+            const anchoredV2 = new Set((shape.elementClasses ?? []).filter((e) => e.testid).flatMap((e) => e.tokens));
+            const noTestidTokens = [
+                ...new Set((shape.elementClasses ?? [])
+                    .filter((e) => !e.testid)
+                    .flatMap((e) => e.tokens)
+                    .filter((t) => !anchoredV2.has(t) && !shape.visualTokens.includes(t))),
+            ];
+            for (const token of noTestidTokens) {
+                lines.push(`    it("rendered DOM keeps mock class token '${token}'", () => {`);
+                lines.push(`      const { container } = render(<${cn} />);`);
+                lines.push(`      expect(container.querySelector('[class*="${token}"]')).toBeTruthy();`);
+                lines.push(`    });`);
+            }
             lines.push(`  });`);
             lines.push(``);
         }
@@ -333,6 +435,15 @@ function synthesiseShapeTestFileV1(opts) {
                 lines.push(`      expect(src).toMatch(/className=[^>]*\\b${escapeRegexForTest(token)}\\b/);`);
                 lines.push(`    });`);
             }
+            // design #10 — dense token containment (file-level, source-grep).
+            // Coarse vs v2's per-element render assertion, but robust to bracket/
+            // colon/slash tokens; ensures the mock's full utility set survives brew.
+            const denseTokens = [...new Set((shape.elementClasses ?? []).flatMap((e) => e.tokens))].filter((t) => !shape.visualTokens.includes(t));
+            for (const token of denseTokens) {
+                lines.push(`    it("preserves mock class token '${token}'", () => {`);
+                lines.push(`      expect(src).toContain(${JSON.stringify(token)});`);
+                lines.push(`    });`);
+            }
             if (shape.hasHeader) {
                 lines.push(`    it("retains a <header> element (semantic landmark)", () => {`);
                 lines.push(`      expect(src).toMatch(/<header\\b/);`);