@massa-ai/cursor-plugin 1.31.0 → 1.32.0

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "description": "massa-ai — semantic code search, memory, and context compression for Cursor"
 }

package/agent-profiles/balanced/massa-ai-audit-specialist.md

@@ -33,12 +33,13 @@ The `lens` field in the capability packet selects the audit behavior:
 | `requirements` | Requirements, spec, acceptance, scope alignment | `workflows/requirements/requirements-audit.md` |
 | `code-quality` | SOLID, Clean Code, KISS, YAGNI, DRY, maintainability | `workflows/code-quality/code-quality-audit.md` |
 | `performance` | Performance hotspots, allocation, latency, throughput | Domain-specific; no fixed reference |
+| `tests` | Coverage, regression protection, assertion quality, variation | `workflows/tests/tests-audit.md` |
 
 All lenses share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format).
 
 ## Inputs
 - `scope`: the target area, diff, or module to audit.
-- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance` (required).
+- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance | tests` (required).
 - `inputs`: recalled facts, existing audit reports, source pointers.
 - `sensors`: static checks available for the lens (lint, typecheck, security scanners).
 

package/agent-profiles/balanced/massa-ai-test-engineer.md

@@ -6,12 +6,13 @@ model: inherit
 # Test Engineer Agent Skill
 
 ## Mission
-Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria.
+Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria, and that catches the five distinct error classes a test suite must cover: business-logic errors, code no test touched, hardcoded-example brittleness, built-the-wrong-thing, and drift over time.
 
 ## Responsibilities
 - Define unit test cases for core logic.
 - Define integration test cases for boundaries.
 - Identify edge cases and negative scenarios.
+- Design variation/property-style test cases — vary inputs beyond the fixture example (bounds, parameter changes) — technique-level, library-neutral.
 - Produce a test plan aligned with acceptance criteria.
 - Ensure acceptance coverage maps to spec criteria.
 

package/agent-profiles/cheap/massa-ai-audit-specialist.md

@@ -33,12 +33,13 @@ The `lens` field in the capability packet selects the audit behavior:
 | `requirements` | Requirements, spec, acceptance, scope alignment | `workflows/requirements/requirements-audit.md` |
 | `code-quality` | SOLID, Clean Code, KISS, YAGNI, DRY, maintainability | `workflows/code-quality/code-quality-audit.md` |
 | `performance` | Performance hotspots, allocation, latency, throughput | Domain-specific; no fixed reference |
+| `tests` | Coverage, regression protection, assertion quality, variation | `workflows/tests/tests-audit.md` |
 
 All lenses share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format).
 
 ## Inputs
 - `scope`: the target area, diff, or module to audit.
-- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance` (required).
+- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance | tests` (required).
 - `inputs`: recalled facts, existing audit reports, source pointers.
 - `sensors`: static checks available for the lens (lint, typecheck, security scanners).
 

package/agent-profiles/cheap/massa-ai-test-engineer.md

@@ -6,12 +6,13 @@ model: inherit
 # Test Engineer Agent Skill
 
 ## Mission
-Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria.
+Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria, and that catches the five distinct error classes a test suite must cover: business-logic errors, code no test touched, hardcoded-example brittleness, built-the-wrong-thing, and drift over time.
 
 ## Responsibilities
 - Define unit test cases for core logic.
 - Define integration test cases for boundaries.
 - Identify edge cases and negative scenarios.
+- Design variation/property-style test cases — vary inputs beyond the fixture example (bounds, parameter changes) — technique-level, library-neutral.
 - Produce a test plan aligned with acceptance criteria.
 - Ensure acceptance coverage maps to spec criteria.
 

package/agent-profiles/heavy/massa-ai-audit-specialist.md

@@ -33,12 +33,13 @@ The `lens` field in the capability packet selects the audit behavior:
 | `requirements` | Requirements, spec, acceptance, scope alignment | `workflows/requirements/requirements-audit.md` |
 | `code-quality` | SOLID, Clean Code, KISS, YAGNI, DRY, maintainability | `workflows/code-quality/code-quality-audit.md` |
 | `performance` | Performance hotspots, allocation, latency, throughput | Domain-specific; no fixed reference |
+| `tests` | Coverage, regression protection, assertion quality, variation | `workflows/tests/tests-audit.md` |
 
 All lenses share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format).
 
 ## Inputs
 - `scope`: the target area, diff, or module to audit.
-- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance` (required).
+- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance | tests` (required).
 - `inputs`: recalled facts, existing audit reports, source pointers.
 - `sensors`: static checks available for the lens (lint, typecheck, security scanners).
 

package/agent-profiles/heavy/massa-ai-test-engineer.md

@@ -6,12 +6,13 @@ model: inherit
 # Test Engineer Agent Skill
 
 ## Mission
-Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria.
+Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria, and that catches the five distinct error classes a test suite must cover: business-logic errors, code no test touched, hardcoded-example brittleness, built-the-wrong-thing, and drift over time.
 
 ## Responsibilities
 - Define unit test cases for core logic.
 - Define integration test cases for boundaries.
 - Identify edge cases and negative scenarios.
+- Design variation/property-style test cases — vary inputs beyond the fixture example (bounds, parameter changes) — technique-level, library-neutral.
 - Produce a test plan aligned with acceptance criteria.
 - Ensure acceptance coverage maps to spec criteria.
 

package/agent-profiles/home/massa-ai-audit-specialist.md

@@ -33,12 +33,13 @@ The `lens` field in the capability packet selects the audit behavior:
 | `requirements` | Requirements, spec, acceptance, scope alignment | `workflows/requirements/requirements-audit.md` |
 | `code-quality` | SOLID, Clean Code, KISS, YAGNI, DRY, maintainability | `workflows/code-quality/code-quality-audit.md` |
 | `performance` | Performance hotspots, allocation, latency, throughput | Domain-specific; no fixed reference |
+| `tests` | Coverage, regression protection, assertion quality, variation | `workflows/tests/tests-audit.md` |
 
 All lenses share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format).
 
 ## Inputs
 - `scope`: the target area, diff, or module to audit.
-- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance` (required).
+- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance | tests` (required).
 - `inputs`: recalled facts, existing audit reports, source pointers.
 - `sensors`: static checks available for the lens (lint, typecheck, security scanners).
 

package/agent-profiles/home/massa-ai-test-engineer.md

@@ -6,12 +6,13 @@ model: inherit
 # Test Engineer Agent Skill
 
 ## Mission
-Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria.
+Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria, and that catches the five distinct error classes a test suite must cover: business-logic errors, code no test touched, hardcoded-example brittleness, built-the-wrong-thing, and drift over time.
 
 ## Responsibilities
 - Define unit test cases for core logic.
 - Define integration test cases for boundaries.
 - Identify edge cases and negative scenarios.
+- Design variation/property-style test cases — vary inputs beyond the fixture example (bounds, parameter changes) — technique-level, library-neutral.
 - Produce a test plan aligned with acceptance criteria.
 - Ensure acceptance coverage maps to spec criteria.
 

package/agent-profiles/work/massa-ai-audit-specialist.md

@@ -33,12 +33,13 @@ The `lens` field in the capability packet selects the audit behavior:
 | `requirements` | Requirements, spec, acceptance, scope alignment | `workflows/requirements/requirements-audit.md` |
 | `code-quality` | SOLID, Clean Code, KISS, YAGNI, DRY, maintainability | `workflows/code-quality/code-quality-audit.md` |
 | `performance` | Performance hotspots, allocation, latency, throughput | Domain-specific; no fixed reference |
+| `tests` | Coverage, regression protection, assertion quality, variation | `workflows/tests/tests-audit.md` |
 
 All lenses share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format).
 
 ## Inputs
 - `scope`: the target area, diff, or module to audit.
-- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance` (required).
+- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance | tests` (required).
 - `inputs`: recalled facts, existing audit reports, source pointers.
 - `sensors`: static checks available for the lens (lint, typecheck, security scanners).
 

package/agent-profiles/work/massa-ai-test-engineer.md

@@ -6,12 +6,13 @@ model: inherit
 # Test Engineer Agent Skill
 
 ## Mission
-Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria.
+Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria, and that catches the five distinct error classes a test suite must cover: business-logic errors, code no test touched, hardcoded-example brittleness, built-the-wrong-thing, and drift over time.
 
 ## Responsibilities
 - Define unit test cases for core logic.
 - Define integration test cases for boundaries.
 - Identify edge cases and negative scenarios.
+- Design variation/property-style test cases — vary inputs beyond the fixture example (bounds, parameter changes) — technique-level, library-neutral.
 - Produce a test plan aligned with acceptance criteria.
 - Ensure acceptance coverage maps to spec criteria.
 

package/agents/massa-ai-audit-specialist.md

@@ -33,12 +33,13 @@ The `lens` field in the capability packet selects the audit behavior:
 | `requirements` | Requirements, spec, acceptance, scope alignment | `workflows/requirements/requirements-audit.md` |
 | `code-quality` | SOLID, Clean Code, KISS, YAGNI, DRY, maintainability | `workflows/code-quality/code-quality-audit.md` |
 | `performance` | Performance hotspots, allocation, latency, throughput | Domain-specific; no fixed reference |
+| `tests` | Coverage, regression protection, assertion quality, variation | `workflows/tests/tests-audit.md` |
 
 All lenses share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format).
 
 ## Inputs
 - `scope`: the target area, diff, or module to audit.
-- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance` (required).
+- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance | tests` (required).
 - `inputs`: recalled facts, existing audit reports, source pointers.
 - `sensors`: static checks available for the lens (lint, typecheck, security scanners).
 

package/agents/massa-ai-test-engineer.md

@@ -6,12 +6,13 @@ model: inherit
 # Test Engineer Agent Skill
 
 ## Mission
-Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria.
+Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria, and that catches the five distinct error classes a test suite must cover: business-logic errors, code no test touched, hardcoded-example brittleness, built-the-wrong-thing, and drift over time.
 
 ## Responsibilities
 - Define unit test cases for core logic.
 - Define integration test cases for boundaries.
 - Identify edge cases and negative scenarios.
+- Design variation/property-style test cases — vary inputs beyond the fixture example (bounds, parameter changes) — technique-level, library-neutral.
 - Produce a test plan aligned with acceptance criteria.
 - Ensure acceptance coverage maps to spec criteria.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/cursor-plugin",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/agents/audit-specialist/SKILL.md

@@ -38,12 +38,13 @@ The `lens` field in the capability packet selects the audit behavior:
 | `requirements` | Requirements, spec, acceptance, scope alignment | `workflows/requirements/requirements-audit.md` |
 | `code-quality` | SOLID, Clean Code, KISS, YAGNI, DRY, maintainability | `workflows/code-quality/code-quality-audit.md` |
 | `performance` | Performance hotspots, allocation, latency, throughput | Domain-specific; no fixed reference |
+| `tests` | Coverage, regression protection, assertion quality, variation | `workflows/tests/tests-audit.md` |
 
 All lenses share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format).
 
 ## Inputs
 - `scope`: the target area, diff, or module to audit.
-- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance` (required).
+- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance | tests` (required).
 - `inputs`: recalled facts, existing audit reports, source pointers.
 - `sensors`: static checks available for the lens (lint, typecheck, security scanners).
 

package/skills/agents/test-engineer/SKILL.md

@@ -12,12 +12,13 @@ metadata:
 # Test Engineer Agent Skill
 
 ## Mission
-Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria.
+Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria, and that catches the five distinct error classes a test suite must cover: business-logic errors, code no test touched, hardcoded-example brittleness, built-the-wrong-thing, and drift over time.
 
 ## Responsibilities
 - Define unit test cases for core logic.
 - Define integration test cases for boundaries.
 - Identify edge cases and negative scenarios.
+- Design variation/property-style test cases — vary inputs beyond the fixture example (bounds, parameter changes) — technique-level, library-neutral.
 - Produce a test plan aligned with acceptance criteria.
 - Ensure acceptance coverage maps to spec criteria.
 

package/skills/massa-ai/references/coding-guidelines.md

@@ -65,3 +65,12 @@ For multi-step tasks, state a brief plan:
 ```
 
 Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## 5. File Shape for Agent Readers
+
+**Read mechanics, not module depth.**
+
+- A one-subject file up to ~500 lines is fine — a single agent read stays coherent, cheap in tokens, and a coding agent can hold the whole file in context with headroom for the rest of the task.
+- A file over ~600 lines must be flagged for splitting — even one-subject, it crowds out the rest of the working context and pushes reads toward pagination.
+- Splitting one subject across many files does not reduce read cost — it multiplies it: one subject spread over N files costs N reads, and each file boundary loses context (per-hop navigation cost).
+- This guidance derives from agent read mechanics, not from module depth. Depth is a separate concept, and this section makes no depth claim: depth is NOT a lines-of-code ratio (`references/architecture-deepening-lens.md` Rejected Framings) — a deep module can be tiny and a shallow wrapper can be long. Do not phrase file-size guidance as a depth metric; it is scoped to single-agent read cost only.

package/skills/massa-ai/references/implementation-delivery.md

@@ -111,6 +111,7 @@ report:
 - the PR URL,
 - the check names that passed,
 - what is still unverified (skipped jobs, absent checks),
+- the change's category trust status (`bun skills/massa-ai/scripts/lessons.ts --root . trust status --category <kebab>`) as advisory reading-depth context — it never substitutes for the approval decision below,
 
 then stop and ask. If the user approves, merge with the repository's configured
 strategy and delete the branch. If the repository auto-releases on merge, say so

package/skills/massa-ai/references/lessons.md

@@ -66,6 +66,58 @@ bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed [--scope
 | `quarantined` | A confirmed lesson penalized ≥`quarantine_threshold` times (failed when applied) |
 | **pruned** | A `candidate` that never recurred within `window_days` (default 45) |
 
+## Trust Ramp and Quality-Metric Trend (Advisory)
+
+Two additional append-only record kinds accumulate in `.specs/lessons.json` beside
+lessons: reviewer-feedback records (`data.reviews`) and quality-metric snapshots
+(`data.metrics`). Both are derived state — `lessons.ts` computes streaks, trusted
+flags, and trend verdicts at read time from the event log; there is no cached
+`streak`/`trusted` flag anywhere in the store, so there is no invalidation step,
+and demotion is emergent: a `major` record simply caps the trailing streak window
+the next time the log is read.
+
+### Categories
+
+A review category is a free-form kebab-case label supplied at record time (e.g.
+`installer`, `admin-ui`) — the same convention as the existing `--scope` flag.
+There is no fixed taxonomy; the label is whatever the recording agent or user
+chooses.
+
+### Feedback levels
+
+- `none` — no reviewer feedback; extends the category's streak.
+- `minor` — a small correction; also extends the streak.
+- `major` — resets the category's streak to 0 and demotes a trusted category
+  back to untrusted.
+
+### Trust threshold
+
+`trust_threshold` (default 30) is the number of consecutive `none`/`minor`
+records a category needs before `trust status` marks it `trusted`. The
+comparison is `>=`: a streak sitting exactly at the threshold is trusted.
+
+### Advisory-only scope
+
+Trust status governs reading depth only — how closely a human scrutinizes a
+diff before approving it. It never governs, gates, or substitutes for per-PR
+merge approval: `references/implementation-delivery.md`'s "Approval for one PR
+does not carry to the next" clause is unaffected by any trust state.
+
+### Commands
+
+```bash
+bun skills/massa-ai/scripts/lessons.ts --root . review add --category <kebab> --feedback none|minor|major --source <ref>
+bun skills/massa-ai/scripts/lessons.ts --root . trust status [--category <kebab>]
+bun skills/massa-ai/scripts/lessons.ts --root . metrics add --feature <slug> --result PASS|FAIL --fix-iterations <n> --surviving-mutants <n> --acs-total <n> --acs-covered <n>
+bun skills/massa-ai/scripts/lessons.ts --root . metrics trend
+```
+
+`trust status` with no `--category` lists every category with its streak,
+total review count, and trusted state; an empty store reports
+`(no review records)`, exit 0. `metrics trend` prints every snapshot
+oldest-first followed by `trend: improving|stable|degrading`, or
+`trend: insufficient data` when fewer than two snapshots exist — both exit 0.
+
 ## No-Script Fallback
 
 If `lessons.ts` is unavailable or cannot run, record `Lessons: skipped - script unavailable` in the validation report or evidence gate, keep the raw signal in the report, and do not hand-edit `lessons.json`. A future run with the script can import the validated signal.

package/skills/massa-ai/references/spec-driven/validate.md

@@ -218,6 +218,16 @@ The script enforces grounding (mandatory `--source`) and owns all bookkeeping. A
 
 Persist durable memory for verified outcomes worth reusing via `remember` with tags `workflow:spec-driven`, `entity:<slug>`, and `memory:episodic|procedural` as appropriate.
 
+### 11. Record Metric Snapshot (MANDATORY)
+
+Immediately after validation completes, record this run's quality-metric snapshot so "is the harness improving or degrading" is answerable from data, not memory:
+
+```bash
+bun skills/massa-ai/scripts/lessons.ts --root . metrics add --feature <slug> --result PASS|FAIL --fix-iterations <n> --surviving-mutants <n> --acs-total <n> --acs-covered <n>
+```
+
+Derive the flags from this validation's own evidence: `--result` from the Verdict, `--acs-total`/`--acs-covered` from the Spec-Anchored Acceptance Criteria check, `--surviving-mutants` from the Discrimination Sensor's survived count, and `--fix-iterations` from the fix-loop iteration count used this run.
+
 ---
 
 ## Verdicts

package/skills/massa-ai/scripts/lessons.ts

@@ -23,6 +23,9 @@
  *   export     Export the lessons store as JSON (round-trips with import).
  *   import     Import lessons from JSON (merge by dedup key; best-effort massa-ai memory).
  *   selftest   Run stdlib regressions (normalization).
+ *   review     Append reviewer-feedback records and derive per-category trust streaks.
+ *   trust      Print derived per-category trust status (advisory only, AEH-03).
+ *   metrics    Append quality-metric snapshots and print the derived trend verdict (AEH-05).
  *
  * Exit codes: 0 ok, 2 usage/validation error (e.g. missing grounding).
  */
@@ -43,6 +46,7 @@ const SIGNALS: Record<string, string> = {
 const SIGNAL_KEYS_SORTED = Object.keys(SIGNALS).sort();
 
 const DEFAULTS = { promote_threshold: 2, window_days: 45, quarantine_threshold: 2 };
+const RAMP_DEFAULTS = { trust_threshold: 30 };
 
 // massa-ai supported memory types (references/mcp-tools.md). `procedural` is a
 // TAG, never a type. Lessons are procedural knowledge -> type `pattern`.
@@ -69,6 +73,25 @@ interface Lesson {
   [key: string]: unknown;
 }
 
+/** Reviewer-feedback event (AEH-03). Append-only; category is a free-form kebab-case label. */
+interface ReviewRecord {
+  category: string;
+  feedback: "none" | "minor" | "major";
+  source: string;
+  recordedAt: string;
+}
+
+/** Per-validation quality-metric snapshot (AEH-05). Append-only. */
+interface MetricSnapshot {
+  feature: string;
+  result: "PASS" | "FAIL";
+  fixLoopIterations: number;
+  survivingMutants: number;
+  acsTotal: number;
+  acsCovered: number;
+  recordedAt: string;
+}
+
 interface Store {
   schema: number;
   promote_threshold: number;
@@ -76,6 +99,13 @@ interface Store {
   quarantine_threshold: number;
   next_id: number;
   lessons: Lesson[];
+  // Ramp-only fields (AEH-03/05) - absent on legacy stores, lazily backfilled by
+  // ensureRampFields() inside the new review/trust/metrics commands only, NEVER in
+  // load(), so every legacy command keeps reading/writing the store byte-identically
+  // to before this feature (pyts-golden protection).
+  trust_threshold?: number;
+  reviews?: ReviewRecord[];
+  metrics?: MetricSnapshot[];
   [key: string]: unknown;
 }
 
@@ -433,6 +463,60 @@ function find(data: Store, signal: string, text: string): Lesson | null {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Trust ramp + metric-trend derivations (AEH-03, AEH-05)
+//
+// review/metrics records are append-only events; streak, trusted, and trend
+// verdict are all derived at read time from the log (design Approach A) - no
+// cached state, so demotion on a `major` record is emergent rather than a
+// write-path invariant that needs its own tests.
+// ---------------------------------------------------------------------------
+
+/**
+ * Lazily backfills the ramp-only fields (`trust_threshold`, `reviews`, `metrics`)
+ * onto an in-memory store. Called ONLY from the new review/trust/metrics commands -
+ * NEVER from `load()` - so every legacy command keeps reading/writing the store
+ * byte-identically to before this feature (pyts-golden protection).
+ */
+function ensureRampFields(data: Store): void {
+  pySetDefault(data as unknown as Record<string, unknown>, "trust_threshold", RAMP_DEFAULTS.trust_threshold);
+  pySetDefault(data as unknown as Record<string, unknown>, "reviews", []);
+  pySetDefault(data as unknown as Record<string, unknown>, "metrics", []);
+}
+
+/** Count of trailing none|minor records for `category`, scanning newest-first until a major. */
+function categoryStreak(data: Store, category: string): number {
+  const records = (data.reviews ?? []).filter((r) => r.category === category);
+  let count = 0;
+  for (let i = records.length - 1; i >= 0; i--) {
+    if (records[i]!.feedback === "major") break;
+    count++;
+  }
+  return count;
+}
+
+function isTrusted(data: Store, category: string): boolean {
+  const threshold = data.trust_threshold ?? RAMP_DEFAULTS.trust_threshold;
+  return categoryStreak(data, category) >= threshold;
+}
+
+/** Scalar trend score for one snapshot - lower is better. FAIL*100 + mutants*10 + fixIters + uncoveredACs. */
+function trendScore(s: MetricSnapshot): number {
+  return (s.result === "FAIL" ? 100 : 0) + s.survivingMutants * 10 + s.fixLoopIterations + (s.acsTotal - s.acsCovered);
+}
+
+/** Compares the last two snapshots' scores (lower = better). <2 snapshots -> "insufficient data". */
+function trendVerdict(snapshots: MetricSnapshot[]): string {
+  if (snapshots.length < 2) return "insufficient data";
+  const last = snapshots[snapshots.length - 1]!;
+  const prev = snapshots[snapshots.length - 2]!;
+  const lastScore = trendScore(last);
+  const prevScore = trendScore(prev);
+  if (lastScore < prevScore) return "improving";
+  if (lastScore > prevScore) return "degrading";
+  return "stable";
+}
+
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -737,6 +821,108 @@ function cmdStatus(root: string): number {
   return 0;
 }
 
+interface ReviewAddArgs {
+  category: string;
+  feedback: string;
+  source: string;
+  project: string;
+}
+
+function cmdReviewAdd(root: string, args: ReviewAddArgs): number {
+  const category = (args.category || "").trim();
+  const source = (args.source || "").trim();
+  const data = load(root);
+  ensureRampFields(data);
+  const record: ReviewRecord = {
+    category,
+    feedback: args.feedback as ReviewRecord["feedback"],
+    source,
+    recordedAt: now(),
+  };
+  data.reviews!.push(record);
+  save(root, data);
+  const streak = categoryStreak(data, category);
+  console.log(`REVIEW ${category} (streak=${streak}, trusted=${isTrusted(data, category)})`);
+  return 0;
+}
+
+function cmdTrustStatus(root: string, categoryFilter: string): number {
+  const data = load(root);
+  ensureRampFields(data);
+  const reviews = data.reviews ?? [];
+  let categories = Array.from(new Set(reviews.map((r) => r.category)));
+  if (categoryFilter) {
+    categories = categories.filter((c) => c === categoryFilter);
+  }
+  categories.sort(pyStringCompare);
+  if (!categories.length) {
+    console.log("(no review records)");
+    return 0;
+  }
+  const threshold = data.trust_threshold ?? RAMP_DEFAULTS.trust_threshold;
+  for (const category of categories) {
+    const total = reviews.filter((r) => r.category === category).length;
+    const streak = categoryStreak(data, category);
+    const trusted = streak >= threshold;
+    console.log(`${category}: streak=${streak}/${threshold} total=${total} trusted=${trusted ? "yes" : "no"}`);
+  }
+  return 0;
+}
+
+/** Parses a required non-negative-integer flag value; prints an error naming `flagName` on failure. */
+function parseNonNegativeInt(value: string, flagName: string): number | null {
+  const n = Number(value);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {
+    console.error(`ERROR: ${flagName} must be a non-negative integer, got ${pyRepr(value)}`);
+    return null;
+  }
+  return n;
+}
+
+function cmdMetricsAdd(root: string, raw: Record<string, string>): number {
+  const feature = (raw.feature || "").trim();
+  const result = raw.result as MetricSnapshot["result"];
+  const fixLoopIterations = parseNonNegativeInt(raw["fix-iterations"]!, "--fix-iterations");
+  if (fixLoopIterations === null) return 2;
+  const survivingMutants = parseNonNegativeInt(raw["surviving-mutants"]!, "--surviving-mutants");
+  if (survivingMutants === null) return 2;
+  const acsTotal = parseNonNegativeInt(raw["acs-total"]!, "--acs-total");
+  if (acsTotal === null) return 2;
+  const acsCovered = parseNonNegativeInt(raw["acs-covered"]!, "--acs-covered");
+  if (acsCovered === null) return 2;
+
+  const data = load(root);
+  ensureRampFields(data);
+  const snapshot: MetricSnapshot = {
+    feature,
+    result,
+    fixLoopIterations,
+    survivingMutants,
+    acsTotal,
+    acsCovered,
+    recordedAt: now(),
+  };
+  data.metrics!.push(snapshot);
+  save(root, data);
+  console.log(
+    `METRICS ${feature} (result=${result}, survivingMutants=${survivingMutants}, fixIters=${fixLoopIterations}, acs=${acsCovered}/${acsTotal})`,
+  );
+  return 0;
+}
+
+function cmdMetricsTrend(root: string): number {
+  const data = load(root);
+  ensureRampFields(data);
+  const snapshots = data.metrics ?? [];
+  for (const s of snapshots) {
+    console.log(
+      `${s.feature} result=${s.result} fixIters=${s.fixLoopIterations} survivingMutants=${s.survivingMutants} acs=${s.acsCovered}/${s.acsTotal} recordedAt=${s.recordedAt}`,
+    );
+  }
+  console.log(`trend: ${trendVerdict(snapshots)}`);
+  return 0;
+}
+
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -744,7 +930,9 @@ function cmdStatus(root: string): number {
 const PROG = "lessons.ts";
 
 function usageError(msg: string): void {
-  process.stderr.write(`usage: ${PROG} [-h] [--root ROOT] {init,add,penalize,list,observe,export,import,prune,status,selftest} ...\n${PROG}: error: ${msg}\n`);
+  process.stderr.write(
+    `usage: ${PROG} [-h] [--root ROOT] {init,add,penalize,list,observe,export,import,prune,status,selftest,review,trust,metrics} ...\n${PROG}: error: ${msg}\n`,
+  );
 }
 
 interface FlagSpec {
@@ -894,9 +1082,57 @@ async function main(argv: string[]): Promise<number> {
     case "selftest":
       return selftestNorm();
 
+    case "review": {
+      const sub = rest[0];
+      if (sub === "add") {
+        const parsed = parseFlags(rest.slice(1), [
+          { name: "--category", required: true },
+          { name: "--feedback", required: true, choices: ["none", "minor", "major"] },
+          { name: "--source", required: true },
+          { name: "--project", default: "" },
+        ]);
+        if (!parsed) return 2;
+        return cmdReviewAdd(absRoot, parsed as unknown as ReviewAddArgs);
+      }
+      usageError(`argument cmd: invalid choice: ${pyRepr(sub ?? "")} (choose from 'add')`);
+      return 2;
+    }
+
+    case "trust": {
+      const sub = rest[0];
+      if (sub === "status") {
+        const parsed = parseFlags(rest.slice(1), [{ name: "--category", default: "" }]);
+        if (!parsed) return 2;
+        return cmdTrustStatus(absRoot, parsed.category!);
+      }
+      usageError(`argument cmd: invalid choice: ${pyRepr(sub ?? "")} (choose from 'status')`);
+      return 2;
+    }
+
+    case "metrics": {
+      const sub = rest[0];
+      if (sub === "add") {
+        const parsed = parseFlags(rest.slice(1), [
+          { name: "--feature", required: true },
+          { name: "--result", required: true, choices: ["PASS", "FAIL"] },
+          { name: "--fix-iterations", required: true },
+          { name: "--surviving-mutants", required: true },
+          { name: "--acs-total", required: true },
+          { name: "--acs-covered", required: true },
+        ]);
+        if (!parsed) return 2;
+        return cmdMetricsAdd(absRoot, parsed);
+      }
+      if (sub === "trend") {
+        return cmdMetricsTrend(absRoot);
+      }
+      usageError(`argument cmd: invalid choice: ${pyRepr(sub ?? "")} (choose from 'add', 'trend')`);
+      return 2;
+    }
+
     default:
       usageError(
-        `argument cmd: invalid choice: ${pyRepr(cmd)} (choose from 'init', 'add', 'penalize', 'list', 'observe', 'export', 'import', 'prune', 'status', 'selftest')`,
+        `argument cmd: invalid choice: ${pyRepr(cmd)} (choose from 'init', 'add', 'penalize', 'list', 'observe', 'export', 'import', 'prune', 'status', 'selftest', 'review', 'trust', 'metrics')`,
       );
       return 2;
   }

package/skills/massa-ai/workflows/architecture/architecture-fix.md

@@ -86,6 +86,19 @@ Not for findings-only architecture review — route to `workflows/architecture/a
 > - firewall: raw test output/logs summarized
 > - memory: suggest-only; main agent persists reusable verification recipes
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 11. Verify each completed finding:
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`

package/skills/massa-ai/workflows/bugs/bugs-fix.md

@@ -76,6 +76,19 @@ Not for findings-only bug discovery — route to `workflows/bugs/bugs-audit.md`.
 > - memory: suggest-only; main agent persists reusable verification recipes
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
    - Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 10. Verify each completed finding:
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`

package/skills/massa-ai/workflows/code-quality/code-quality-audit.md

@@ -76,6 +76,7 @@ Findings-only: do not edit code unless the user separately asks for fixes.
    - Magic values: repeated strings, event names, timeouts, numeric thresholds, status codes.
    - Generic names: `data`, `info`, `result`, `value`, `temp`, `manager`, `handler`, `helper` without useful qualification, using `references/naming-standards.md` to filter conventional short-scope or framework-required names.
    - Long parameter lists: more than 3-4 positional parameters.
+   - File shape: flag multi-subject files (unrelated exported surfaces bundled together) and any file over ~600 lines, regardless of subject count — it crowds out working context for the rest of the task (see `references/coding-guidelines.md` "File shape for agent readers"). Do NOT flag a single-subject file for line count alone below that bound.
    - Needlessly indirect code: pass-through wrappers, one-use abstractions, helper layers with no behavior, factories/builders that only hide one constructor call.
    - Speculative surfaces: unused options, future-oriented hooks, extension points with one implementation, exported APIs with no evidence of use.
    - Complexity without payoff: deep nesting, miniature state machines, or polymorphism where a direct branch or data map would preserve clarity.
@@ -84,20 +85,20 @@ Findings-only: do not edit code unless the user separately asks for fixes.
 9. Investigation pass:
    - Use summary/enriched search, symbol tools, and targeted file reads to inspect target modules, semantic hotspots, public classes, interfaces, functions, and exported API surface.
    - Apply SOLID checks to non-test source only:
-     - Single Responsibility: flag classes/modules with distinct concern groups, such as validation plus persistence or formatting plus dispatch.
+     - Single Responsibility: flag classes/modules bundling distinct concern groups, such as validation plus persistence or formatting plus dispatch, only when separating them yields an externally-findable named unit (locatable by search or grep from outside the file) or measurably reduces change risk — never on concern-count or size alone.
      - Open/Closed: flag caller-side switches or if/else chains on type tags where adding a variant requires modifying existing files.
      - Liskov: flag subtypes that throw where the base does not, ignore required methods, or narrow the base contract.
      - Interface Segregation: flag interfaces that force implementors to define unused methods.
      - Dependency Inversion: flag hardcoded `new ConcreteType()` inside class bodies where abstraction or injection would be natural.
    - Apply Clean Code checks to test and non-test source:
      - Magic values: meaningful bare literals should be named constants, especially repeated strings, timeouts, thresholds, and event names.
-     - Function does more than one thing: if accurate description needs "and", recommend splitting.
+     - Function does more than one thing: split only when the result yields an externally-findable named unit (locatable by search or grep from outside the file) or measurably reduces change risk; never split on size or "more than one thing" alone.
      - Unqualified generic names: flag vague names without domain or role qualification.
      - What-comments: flag comments that restate code; keep only why comments for constraints, workarounds, or non-obvious invariants.
      - Half-finished surfaces: flag exported TODOs, stubs, placeholder returns, and "implement later" code.
      - Long parameter lists: flag more than 3-4 positional parameters; suggest an options object.
    - Apply KISS/YAGNI/DRY checks:
-     - KISS: flag abstractions, layers, indirection, or control flow that raise cognitive load without clearly improving readability, correctness, or constraint handling. Call out premature generalization, deep call chains, excessive configuration, and clever patterns that obscure intent. Prefer straightforward, explicit code a new reader can follow end-to-end: inline trivial abstractions, collapse unnecessary layers, choose boring solutions unless complexity is justified (real variability, hard constraints, or measured bottlenecks).
+     - KISS: flag abstractions, layers, indirection, or control flow that raise cognitive load without clearly improving readability, correctness, or constraint handling. Call out premature generalization, deep call chains, excessive configuration, and clever patterns that obscure intent. Prefer straightforward, explicit code a new reader can follow end-to-end: inline trivial abstractions, collapse unnecessary layers, choose boring solutions unless complexity is justified (real variability, hard constraints, or measured bottlenecks). When weighing whether to split instead of inline, apply the same discoverability-or-change-risk criterion used for the split lead above.
      - YAGNI: flag speculative features, extension points, and generic infrastructure with no concrete caller, requirement, or near-term use. Call out "just in case" hooks, over-parameterization, unused toggles, and frameworks introduced ahead of need. Prefer implementing only what current use cases demand, structured to evolve when real requirements appear. Defer generalization until duplication or constraints force it, and remove dead or unused paths aggressively.
      - DRY: flag duplicated logic, data transformations, or domain rules repeated without a strong reason (e.g., performance isolation or explicit decoupling). Highlight copy-paste patterns, parallel conditionals, and repeated constants that raise maintenance cost or inconsistency risk. Recommend consolidation into a single source of truth when it improves clarity and reduces bugs, but avoid over-abstraction that harms readability or adds indirection for trivial reuse.
      - Prefer delete, inline, or merge recommendations over replacement abstractions when simpler code preserves behavior.

package/skills/massa-ai/workflows/code-quality/code-quality-fix.md

@@ -48,9 +48,9 @@ Not for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or o
    - Standard: multi-file consolidation, shared behavior cleanup, public helper contract change, or meaningful test impact; define characterization checks first.
    - Spec-driven: broad redesign, unclear behavior, cross-boundary migration, or user-visible behavior change; pause and route to `workflows/spec-driven.md` or ask for approval.
 8. Apply code quality fixing methods:
-   - SOLID: separate mixed responsibilities only when the split reduces change risk; replace caller-side type switches with polymorphism or data maps only when new variants are real; preserve base contracts; narrow fat interfaces; inject dependencies when hardcoded concretes block testing or substitution.
-   - Clean Code: name domain concepts precisely using `references/naming-standards.md`, replace repeated magic values with named constants, split functions that truly do multiple things, remove code-restating comments, finish or delete stubs, and convert long positional parameter lists to options objects when it improves call-site clarity.
-   - KISS: inline shallow helpers, collapse needless layers, choose direct control flow over clever indirection, and remove configuration that hides rather than expresses behavior.
+   - SOLID: separate mixed responsibilities only when the split yields an externally-findable named unit (locatable by search or grep from outside the file) or reduces change risk; replace caller-side type switches with polymorphism or data maps only when new variants are real; preserve base contracts; narrow fat interfaces; inject dependencies when hardcoded concretes block testing or substitution.
+   - Clean Code: name domain concepts precisely using `references/naming-standards.md`, replace repeated magic values with named constants, split functions only when the result yields an externally-findable named unit (locatable by search or grep from outside the file) or measurably reduces change risk — never split on size or "more than one thing" alone — remove code-restating comments, finish or delete stubs, and convert long positional parameter lists to options objects when it improves call-site clarity.
+   - KISS: inline shallow helpers, collapse needless layers, choose direct control flow over clever indirection, and remove configuration that hides rather than expresses behavior. When choosing whether to split instead of inline, apply the same discoverability-or-change-risk criterion used for the Clean Code split direction above.
    - YAGNI: delete unused extension points, future hooks, unused options, one-implementation factories, and speculative public APIs when usage evidence is absent.
    - DRY: consolidate duplicated domain rules or transformations into one clear source of truth, but avoid abstractions that make trivial duplication harder to read.
    - AI-slop cleanup: remove generic wrappers, fabricated-looking abstractions, one-call factories, code-restating comments, and unused configurability when current usage evidence does not justify them.
@@ -83,6 +83,19 @@ Not for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or o
 > - memory: suggest-only; main agent persists reusable verification recipes
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
    - Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 11. Verify each completed finding:
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`

package/skills/massa-ai/workflows/debug.md

@@ -57,6 +57,19 @@ Before the first repository mutation, load `references/implementation-delivery.m
    - file-integrity checks for validation assets such as tests, specs, benchmarks, fixtures, and snapshots
 12. Fix the divergence point closest to the root cause
 13. Add regression coverage at the correct seam, or document why no valid regression seam exists
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 14. If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
      Rerun the original feedback loop, run the verification recipe, and remove temporary instrumentation unless intentionally retained as observability

package/skills/massa-ai/workflows/feature.md

@@ -39,15 +39,29 @@ Before the first repository mutation, load `references/implementation-delivery.m
    - Include a focused naming review when the feature introduces or renames identifiers. New names should use domain or precise role vocabulary, and public/persisted names should not change without explicit compatibility handling.
 9. For mobile features, capture the mobile context packet, choose shared vs platform-specific boundaries, state platform parity expectations, and include the cheapest relevant mobile verification sensor from `references/mobile-context.md`
 10. Use `references/agent-orchestration.md` only for isolated implementation slices or independent verification
-11. Implement the feature by PR group when `references/pr-task-fix.md` applies:
+11. Capture 1-5 testable acceptance criteria in the conversation before implementation starts, or reference an existing spec artifact (e.g. `.specs/features/<slug>/spec.md`) when one already states them. These captured acceptance criteria are the anchor the verification step below checks outcomes against.
+12. Implement the feature by PR group when `references/pr-task-fix.md` applies:
    - Order non-breaking groups by Data, Domain, then Presentation/Navigation, mapping those labels to repository boundaries when needed.
    - Validate each group with the verification recipe before committing.
    - Invoke `workflows/commit.md` for each verified group; do not duplicate commit staging, message, audit-exclusion, or Jira-prefix rules in this workflow.
    - When every group has a confirmed Jira key, follow the optional stacked branch flow in `references/pr-task-fix.md` (Jira-Key Stacked Branches).
-12. Run the verification recipe and report skipped checks explicitly. If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the feature's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
+13. Run the verification recipe and check outcomes against the captured acceptance criteria from step 11, not only against a generic verification recipe; report skipped checks explicitly. If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
-13. At completion, persist (run the scoring rubric from `references/decision-engine.md` for each):
+14. At completion, persist (run the scoring rubric from `references/decision-engine.md` for each):
    - Design decisions made via `remember` as scored `decision` memories
    - New patterns introduced via `remember` as scored `pattern` memories
    - Trade-offs accepted via `remember` as scored `conversation` memories
-14. Complete the Evidence Gate from `references/evidence-gate.md`
+15. Complete the Evidence Gate from `references/evidence-gate.md`

package/skills/massa-ai/workflows/general.md

@@ -34,6 +34,19 @@ Before the first repository mutation, load `references/implementation-delivery.m
     - if a recalled memory is stale or needs correction, call `memory_update` with `id` and the new `content` (re-embeds automatically); if a memory is obsolete, call `memory_delete` with `id` (hard-delete, severs graph edges)
     - for usage insights (search/cache patterns, recent activity), call `analytics` with `type` and `projectId`
     - skip transient details, raw logs, copied source, unverified hypotheses, and facts already captured in current non-stale memory
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the change's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 9. Complete the Evidence Gate from `references/evidence-gate.md` and report verification, changed artifacts, memory outcome, and residual risk.
 
 ## Failure Handling

package/skills/massa-ai/workflows/implementation/implementation-fix.md

@@ -78,6 +78,19 @@ Do not execute from chat summaries, inline review comments, remembered findings,
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
 
     Never run parallel writers against shared files or contracts.
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 11. Verify each completed finding with the Mandatory Verification Fix Gate from `references/verification-ladder.md`: run the report's Verification Suggestion or an equivalent deterministic command/artifact check, then run focused tests, build, lint, type, static, or runtime checks relevant to the source lens. Reinspect tests, fixtures, snapshots, types, specs, public contracts, and touched identifiers so validation assets were not weakened and names follow `references/naming-standards.md`. A finding cannot be marked `fixed` when a target-relevant command or artifact check exists but was not attempted; if verification cannot run, mark it `blocked`, `deferred`, or `skipped` with an allowed skipped-check reason.
 12. Produce a closure matrix with finding ID, source lens, status (`fixed`, `deferred`, `blocked`, `skipped`), changed files, command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, residual risk, and exact next step for deferred or blocked findings.
 13. If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:

package/skills/massa-ai/workflows/maestro/maestro-fix.md

@@ -62,6 +62,19 @@ Reject direct use without a saved `audits/maestro/<YYYY-MM-DD maestro-audit.md>`
    - Replace brittle selectors with stable selectors, accessibility labels, or test IDs already present.
    - Keep setup/teardown explicit, idempotent, and isolated.
    - Protect existing flows, subflows, fixtures, snapshots, baselines, report consumers, and CI commands unless the audit finding explicitly scopes them.
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 9. Use strict harness sensors:
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`

package/skills/massa-ai/workflows/mobile-figma/mobile-figma-fix.md

@@ -49,6 +49,19 @@ Do not execute from chat summaries, screenshots alone, remembered findings, or a
    - Keep XML/Compose, UIKit/SwiftUI, and KMP/native interoperability explicit. Do not duplicate one visual rule across layers when an established shared source owns it.
    - Do not weaken screenshot tests, previews, fixtures, assertions, test tags, resource IDs, content descriptions, or Maestro selectors to hide a mismatch.
    - Modify tracked Maestro flows only when the selected finding explicitly identifies the flow as incorrect or missing and the user-approved scope includes that change.
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 9. Verify after each coherent finding group:
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`

package/skills/massa-ai/workflows/pr-review.md

@@ -146,7 +146,7 @@ the severity labels, and the reply contract.
 | 2 | Requirements & DoD (Definition of Done) | `massa-ai-audit-specialist` | `lens: requirements` — score merged Track A + Track B criteria against the diff, evidence-or-zero: ✅ implemented (`path:line`) / 🟡 partial / ❌ missing; no source ⇒ report "requirements verification skipped" | `requirements` |
 | 3 | Architecture & conventions | `massa-ai-audit-specialist` | `lens: architecture` — extract every explicit rule from the profile's CONVENTIONS/REVIEW_SKILLS docs into a numbered matrix, grade each changed file PASS/VIOLATION/N/A; no docs ⇒ minimal generic boundary sweep, stated | `architecture` |
 | 4 | Performance | `massa-ai-audit-specialist` | `lens: performance` — only issues clearly visible in the diff: N+1 queries, unbounded fetches, per-row lazy I/O, sequential awaits of independent calls, loop-invariant recomputation, unbatched writes | `performance` |
-| 5 | Test coverage | `massa-ai-audit-specialist` | `lens: performance`, scope: test coverage (the charter's lens set has no `tests` lens; `tests-audit.md` precedent) — new/changed behavior with no test, wrong level (unit vs integration), placement/naming vs profile TEST row, missing negative case, assertions that exercise but never assert | `tests` |
+| 5 | Test coverage | `massa-ai-audit-specialist` | `lens: tests` (dedicated lens: coverage, regression protection, assertion quality, variation — `tests-audit.md` precedent) — new/changed behavior with no test, wrong level (unit vs integration), placement/naming vs profile TEST row, missing negative case, missing variation beyond the fixture example, assertions that exercise but never assert | `tests` |
 | 6 | Regression & hallucination | `massa-ai-reviewer` | diff review — unrelated deletions, references to symbols absent from the repo, wrong signature/arity, duplicated existing logic, weakened error handling or assertions, leftover TODO/stub, dead code | `regression` |
 
 Consolidation check (≥ 5 subagents): recorded in the feature design — rows 4 and 5

package/skills/massa-ai/workflows/refactor.md

@@ -40,6 +40,7 @@ Before the first repository mutation, load `references/implementation-delivery.m
 8. Focus on pragmatic refactoring:
    - Identify over-abstracted code and propose Modular Monoliths
    - Reduce "abstraction cost" to make code more AI-navigable
+   - The primary payoff of extraction is extract-for-findability: create a named unit locatable by search or grep from outside the file — that is what makes code AI-navigable, not extraction volume alone
    - Verify changes do not break existing behavior using the verification recipe
 9. Execute by PR group when `references/pr-task-fix.md` applies:
    - Order non-breaking groups by Data, Domain, then Presentation/Navigation, mapping those labels to repository boundaries when needed.
@@ -52,4 +53,17 @@ Before the first repository mutation, load `references/implementation-delivery.m
 12. At completion, persist (run the scoring rubric from `references/decision-engine.md`):
    - Refactored architectural decisions via `remember` as scored `decision` memories
    - Identified and decoupled anti-patterns via `remember` as scored `pattern` memories
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the change's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 13. Complete the Evidence Gate from `references/evidence-gate.md`

package/skills/massa-ai/workflows/requirements/requirements-fix.md

@@ -78,6 +78,19 @@ Not for findings-only requirements review — route to `workflows/requirements/r
 > - memory: suggest-only; main agent persists reusable verification recipes
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
    - Main agent owns report parsing, traceability matrix, memory writes, final synthesis, and Evidence Gate.
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 11. Verify each completed finding:
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`

package/skills/massa-ai/workflows/security/security-fix.md

@@ -82,6 +82,19 @@ Not for findings-only security review — route to `workflows/security/security-
 > - memory: suggest-only; main agent persists reusable verification recipes
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
    - Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 11. Verify each completed finding:
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`

package/skills/massa-ai/workflows/spec-driven.md

@@ -110,6 +110,18 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
    - Update logical feature artifacts in `.specs/features/<slug>/` and `.specs/project/STATE.md` after meaningful progress.
     - Finish Execute by running `references/spec-driven/validate.md`. Dispatch `verification-agent` (author ≠ verifier) per `references/agent-orchestration.md`; the verification-agent always runs automatically and writes `.specs/features/<slug>/validation.md`. Without subagents, run the standalone fresh-eyes fallback in `validate.md`.
 
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the task's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 > **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
 > - trigger: spec-driven Execute final gate; author ≠ verifier independence required
 > - scope: the feature's git diff surface, test files, and spec ACs

package/skills/massa-ai/workflows/tests/tests-audit.md

@@ -16,6 +16,18 @@ Not to write, run, or fix test findings as the main task — route to `workflows
 
 Findings-only: do not edit code unless the user separately asks for fixes.
 
+### Gate / Error-Class Model
+
+Five gates, five distinct error classes. A green gate elsewhere never substitutes for a missing one — each row below is a gap this audit checks for independently:
+
+| Gate | Error class caught |
+| --- | --- |
+| Unit | Business-logic errors |
+| Coverage | Code no test touched |
+| Variation | Hardcoded-example brittleness |
+| Acceptance-criteria mapping | Built-the-wrong-thing |
+| Quality-metric trend | Drift over time |
+
 1. Resolve/reuse `workflowSessionId`: `test-audit-[entity]`
 2. Load shared references:
    - `references/codebase-investigation.md`
@@ -46,7 +58,7 @@ Findings-only: do not edit code unless the user separately asks for fixes.
 > - trigger: large scope, explicit parallel/subagent request, PR subagent invocation, or independent verification of high-impact finding
 > - scope: the tests audit target — test files, fixtures, harnesses, coverage
 > - permissions: read-only
-> - inputs: shared scope packet; `lens: performance` (test coverage is under the performance lens); recalled testing conventions, flaky tests, known regressions
+> - inputs: shared scope packet; `lens: tests`; recalled testing conventions, flaky tests, known regressions
 > - sensors: map behavior to tests; check missing tests for new branches, error paths, async logic, migrations; fixture health, assertion quality, flakiness root-cause
 > - output: findings with missing/weak coverage type, location, evidence, regression risk, severity, simplest test direction, deterministic sensor, verification suggestion
 > - firewall: raw diffs/logs/search output summarized, not returned raw
@@ -54,6 +66,8 @@ Findings-only: do not edit code unless the user separately asks for fixes.
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
 
     - Map changed or targeted behavior to existing tests, fixtures, mocks, and deterministic harnesses.
+   - Variation check: flag tests exercising only the single fixture example where input bounds or parameters can vary — hardcoded-example brittleness the unit gate cannot see.
+   - Trend check: read `bun skills/massa-ai/scripts/lessons.ts --root . metrics trend` and report the direction (improving, stable, degrading) when two or more snapshots exist; report `insufficient data` otherwise.
    - Check missing tests for new branches, error paths, auth/validation/persistence changes, async or race-prone logic, migrations, public contracts, and recalled bug patterns.
    - For mobile scopes, check KMP shared and platform-specific `actual` tests, Android/iOS harnesses, native bridge payload coverage, permissions, lifecycle, offline sync, deep links, push/background flows, UI snapshots/screenshots, device-matrix assumptions, and platform parity claims from `references/mobile-context.md`.
    - Check weak assertions, tests that only assert implementation details, fixture drift, nondeterminism, hidden network/time/filesystem dependencies, skipped tests, and weakened snapshots.

package/skills/massa-ai/workflows/tests/tests-fix.md

@@ -52,11 +52,25 @@ Not for findings-only test coverage, assertion quality, fixture health, flakines
    - Fixture drift: repair fixtures/builders to match current contracts while keeping them minimal and explicit.
    - Flakiness: prove root cause first; control time, randomness, async scheduling, filesystem, network, and global state with deterministic seams.
    - Missing sensor: add or document the focused command needed to prove the regression cannot recur.
+   - Variation: add varied-input cases (bounds, parameter changes) that exercise the behavior beyond the fixture example — never add a second copy of the fixture example.
    - Mobile coverage: prefer KMP/shared tests before device loops when the behavior is shared; use Android/iOS harnesses, bridge contract tests, screenshot/snapshot checks, lifecycle or permission simulations, and parity validation when the report finding requires them.
 9. Guard validation assets:
    - Never weaken assertions only to make the suite pass.
    - Do not delete coverage, snapshots, fixtures, or benchmarks unless the audit report explicitly calls them obsolete and behavior remains protected elsewhere.
    - Prefer production-code changes only when required to expose a deterministic seam or fix a real bug found while writing the audited test.
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: implementation complete, before the verification gate — never optional
+> - scope: the fix's diff surface and its task/AC context
+> - permissions: read-only
+> - inputs: diff, acceptance context, recalled code-quality conventions
+> - sensors: bugs, regressions, missing edge cases, smells introduced by the diff
+> - output: ranked findings, blocking vs advisory; blocking findings become fix items before verification runs
+> - firewall: summarized findings only, never raw diff dumps
+> - memory: suggest-only; main agent persists
+> - fallback: if the subagent is unavailable, run a standalone fresh-eyes review against this output contract and record the skipped-delegation reason
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
 10. Use strict harness sensors:
    - Never rely on AI subjective evaluation.
    - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`: