@massa-ai/cursor-plugin 1.30.0 → 1.32.0

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