@massa-ai/cursor-plugin 1.27.0 → 1.30.0

package/skills/massa-ai/references/skill-architect/quality-checklist.md

@@ -0,0 +1,70 @@
+# Quality Checklist
+
+Use this checklist at the end of the Validate phase to ensure the skill
+meets all quality criteria before delivery.
+
+---
+
+## Structural Checks (Pass/Fail)
+
+These are hard requirements. Any failure must be fixed.
+
+- [ ] SKILL.md exists with exact casing
+- [ ] YAML frontmatter has opening and closing `---` delimiters
+- [ ] `name` field is present and kebab-case
+- [ ] `name` matches the folder name
+- [ ] `description` field is present
+- [ ] `description` is under 1024 characters
+- [ ] `description` contains no XML angle brackets (< >)
+- [ ] `name` does not contain "claude" or "anthropic"
+- [ ] No README.md inside the skill folder
+- [ ] Folder name is kebab-case (no spaces, no capitals, no underscores)
+
+## Description Quality (Score 1-5)
+
+Rate each and target 4+ on all:
+
+- [ ] **Specificity (1-5):** Does it describe a concrete capability?
+- [ ] **Trigger clarity (1-5):** Would the agent know when to load this?
+- [ ] **User language (1-5):** Does it use phrases a user would actually say?
+- [ ] **Scope boundaries (1-5):** Is it clear what this skill does NOT do?
+- [ ] **Pushiness (1-5):** Is it assertive enough to avoid undertriggering?
+
+## Instruction Quality (Score 1-5)
+
+- [ ] **Actionability (1-5):** Can the agent follow every step without ambiguity?
+- [ ] **Specificity (1-5):** Are instructions concrete (not "validate properly")?
+- [ ] **Examples (1-5):** Are there realistic input/output examples?
+- [ ] **Error handling (1-5):** Are common failures addressed?
+- [ ] **Progressive disclosure (1-5):** Is SKILL.md focused, with details in refs?
+- [ ] **Composability (1-5):** Does it play well with other skills?
+
+## Trigger Testing
+
+### Should trigger (test 3-5 phrases)
+
+1. [ ] "[Obvious request]" → triggers? Y/N
+2. [ ] "[Paraphrased request]" → triggers? Y/N
+3. [ ] "[Informal request]" → triggers? Y/N
+
+### Should NOT trigger (test 3-5 phrases)
+
+1. [ ] "[Unrelated task]" → stays silent? Y/N
+2. [ ] "[Similar but different scope]" → stays silent? Y/N
+3. [ ] "[Generic question]" → stays silent? Y/N
+
+## Performance Targets
+
+Aspirational benchmarks (adapt to your skill):
+
+- [ ] Triggers on ≥90% of relevant queries
+- [ ] Completes workflow without user correction
+- [ ] Consistent results across separate sessions
+- [ ] No failed tool/API calls per workflow
+- [ ] Users don't need to prompt the agent about next steps
+
+## Final Sign-Off
+
+- [ ] User has reviewed the skill
+- [ ] Test phrases produce expected behavior
+- [ ] Skill is packaged and ready for upload

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

@@ -0,0 +1,364 @@
+#!/usr/bin/env bun
+/**
+ * Validate a skill folder against Skill Architect requirements.
+ *
+ * Usage:
+ *   bun scripts/validate_skill.ts <path-to-skill-folder>
+ *   bun scripts/validate_skill.ts <path-to-skill-folder> --format json
+ *   bun scripts/validate_skill.ts <path-to-skill-folder> --json-out /tmp/skill-report.json
+ *
+ * Exit codes:
+ *   0 = pass (warnings allowed)
+ *   1 = fail (at least one error)
+ *
+ * Token-efficient workflow: run once with --json-out, then reuse the saved
+ * JSON for feedback/review without re-running validation.
+ *
+ * TypeScript port of the former validate_skill.py (Skill Architect,
+ * Useful-Agent-Skills). Frontmatter is parsed with Bun's built-in real YAML
+ * parser (`Bun.YAML.parse`) — same precedent as
+ * scripts/__tests__/workflow-bun-cache.test.ts — so the Python version's
+ * PyYAML/stdlib fallback split is gone.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import path from "path";
+
+type Severity = "error" | "warning";
+
+interface Check {
+  name: string;
+  passed: boolean;
+  message: string;
+  severity: Severity;
+}
+
+interface Results {
+  path: string;
+  checks: Check[];
+  passed: number;
+  failed: number;
+  warnings: number;
+  parser_mode: string;
+  next_steps: string[];
+  summary?: string;
+}
+
+const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+
+export function validateSkill(skillPath: string): Results {
+  const results: Results = {
+    path: skillPath,
+    checks: [],
+    passed: 0,
+    failed: 0,
+    warnings: 0,
+    parser_mode: "unknown",
+    next_steps: [],
+  };
+
+  const addCheck = (name: string, passed: boolean, message: string, severity: Severity = "error") => {
+    results.checks.push({ name, passed, message, severity });
+    if (passed) results.passed += 1;
+    else if (severity === "warning") results.warnings += 1;
+    else results.failed += 1;
+  };
+
+  // --- Check 1: Folder exists ---
+  if (!existsSync(skillPath) || !statSync(skillPath).isDirectory()) {
+    addCheck("folder_exists", false, `Path is not a directory: ${skillPath}`);
+    results.summary = "FAIL — folder not found";
+    return results;
+  }
+  addCheck("folder_exists", true, "Skill folder exists");
+
+  // --- Check 2: Folder name is kebab-case ---
+  const folderName = path.basename(path.normalize(skillPath));
+  const isKebab = KEBAB_RE.test(folderName);
+  addCheck("folder_kebab_case", isKebab, `Folder name '${folderName}' ${isKebab ? "is" : "is NOT"} kebab-case`);
+
+  // --- Check 3: SKILL.md exists (exact casing) ---
+  const entries = readdirSync(skillPath);
+  const hasSkillMd = entries.includes("SKILL.md");
+  addCheck("skill_md_exists", hasSkillMd, hasSkillMd ? "SKILL.md exists" : "SKILL.md not found (case-sensitive)");
+
+  const wrongCasings = entries.filter((e) => e.toLowerCase() === "skill.md" && e !== "SKILL.md");
+  if (wrongCasings.length > 0) {
+    addCheck("skill_md_casing", false, `Found wrong casing: ${wrongCasings[0]} (must be exactly SKILL.md)`);
+  }
+
+  if (!hasSkillMd) {
+    results.summary = "FAIL — SKILL.md not found";
+    return results;
+  }
+
+  // --- Check 4: No README.md ---
+  const hasReadme = entries.some((e) => e.toLowerCase() === "readme.md");
+  addCheck(
+    "no_readme",
+    !hasReadme,
+    hasReadme ? "README.md found — remove it (skills are for agents, not humans)" : "No README.md in skill folder",
+  );
+
+  // --- Check 5: Parse frontmatter ---
+  const content = readFileSync(path.join(skillPath, "SKILL.md"), "utf8");
+  const fmMatch = FRONTMATTER_RE.exec(content);
+  if (!fmMatch) {
+    addCheck("frontmatter_delimiters", false, "Missing or malformed --- delimiters in frontmatter");
+    results.summary = "FAIL — frontmatter parse error";
+    return results;
+  }
+  addCheck("frontmatter_delimiters", true, "YAML frontmatter delimiters present");
+
+  let fm: Record<string, unknown>;
+  try {
+    const parsed = Bun.YAML.parse(fmMatch[1]);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("Frontmatter is not a YAML mapping");
+    }
+    fm = parsed as Record<string, unknown>;
+    results.parser_mode = "bun-yaml";
+    addCheck("frontmatter_valid_yaml", true, "Frontmatter is valid YAML (parsed with Bun.YAML)");
+  } catch (e) {
+    addCheck("frontmatter_valid_yaml", false, `YAML parse error: ${e instanceof Error ? e.message : String(e)}`);
+    results.summary = "FAIL — YAML parse error";
+    return results;
+  }
+
+  // --- Check 6: name field ---
+  const name = fm.name;
+  if (!name) {
+    addCheck("name_present", false, "Missing 'name' field in frontmatter");
+  } else {
+    addCheck("name_present", true, `name: ${name}`);
+    const isNameKebab = KEBAB_RE.test(String(name));
+    addCheck("name_kebab_case", isNameKebab, `name '${name}' ${isNameKebab ? "is" : "is NOT"} kebab-case`);
+
+    const nameLower = String(name).toLowerCase();
+    const hasReserved = nameLower.includes("claude") || nameLower.includes("anthropic");
+    addCheck(
+      "name_not_reserved",
+      !hasReserved,
+      hasReserved ? "Name contains 'claude' or 'anthropic' (reserved)" : "Name does not use reserved terms",
+    );
+
+    const namesMatch = String(name) === folderName;
+    addCheck(
+      "name_matches_folder",
+      namesMatch,
+      namesMatch
+        ? `name '${name}' matches folder '${folderName}'`
+        : `name '${name}' does NOT match folder '${folderName}'`,
+      "warning",
+    );
+  }
+
+  // --- Check 7: description field ---
+  const desc = fm.description;
+  if (!desc) {
+    addCheck("description_present", false, "Missing 'description' field in frontmatter");
+  } else {
+    const descStr = String(desc).trim();
+    addCheck("description_present", true, `description present (${descStr.length} chars)`);
+
+    addCheck("description_length", descStr.length <= 1024, `Description length: ${descStr.length}/1024 chars`);
+
+    const hasXml = descStr.includes("<") || descStr.includes(">");
+    addCheck(
+      "description_no_xml",
+      !hasXml,
+      hasXml ? "XML angle brackets found in description (forbidden)" : "No XML brackets in description",
+    );
+
+    const triggerKeywords = ["use when", "use for", "use this", "trigger", "ask for", "asks to", "says", "mentions"];
+    const descLower = descStr.toLowerCase();
+    const hasTriggers = triggerKeywords.some((kw) => descLower.includes(kw));
+    addCheck(
+      "description_has_triggers",
+      hasTriggers,
+      hasTriggers
+        ? "Description includes trigger guidance"
+        : "Missing trigger phrases — add 'Use when...' guidance (mandatory per CONTRIBUTING.md)",
+    );
+
+    const negativeKeywords = ["do not use", "don't use", "not for", "not intended for"];
+    const hasNegativeScope = negativeKeywords.some((kw) => descLower.includes(kw));
+    addCheck(
+      "description_has_negative_scope",
+      hasNegativeScope,
+      hasNegativeScope
+        ? "Description includes negative scope"
+        : "Missing negative scope — add 'Do NOT use for...' guidance (mandatory per CONTRIBUTING.md)",
+    );
+  }
+
+  // --- Check 7b: metadata field ---
+  const metadata = fm.metadata;
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    addCheck(
+      "metadata_present",
+      false,
+      "Missing 'metadata' field in frontmatter (expected metadata.version and metadata.author)",
+      "warning",
+    );
+  } else {
+    addCheck("metadata_present", true, "metadata field present");
+    const meta = metadata as Record<string, unknown>;
+
+    const metaVersion = meta.version;
+    addCheck(
+      "metadata_version",
+      Boolean(metaVersion),
+      metaVersion ? `metadata.version: ${metaVersion}` : "Missing metadata.version",
+      "warning",
+    );
+
+    const metaAuthor = meta.author;
+    addCheck(
+      "metadata_author",
+      Boolean(metaAuthor),
+      metaAuthor ? `metadata.author: ${metaAuthor}` : "Missing metadata.author",
+      "warning",
+    );
+  }
+
+  // --- Check 8: Body content ---
+  const body = content.slice(fmMatch[0].length);
+  const lineCount = body.trim().split("\n").length;
+  addCheck(
+    "body_line_count",
+    lineCount <= 500,
+    `SKILL.md body: ${lineCount} lines ${lineCount <= 500 ? "(good)" : "(consider moving content to references/)"}`,
+    lineCount > 500 ? "warning" : "error",
+  );
+
+  const hasExamples = /(example|user says|result:)/i.test(body);
+  addCheck(
+    "body_has_examples",
+    hasExamples,
+    hasExamples ? "Instructions include examples" : "Consider adding usage examples",
+    "warning",
+  );
+
+  const hasErrorHandling = /(error|fail|troubleshoot|issue|problem|if.*fails)/i.test(body);
+  addCheck(
+    "body_has_error_handling",
+    hasErrorHandling,
+    hasErrorHandling ? "Instructions include error handling" : "Consider adding error handling guidance",
+    "warning",
+  );
+
+  // --- Check 9: Optional files ---
+  const refsDir = path.join(skillPath, "references");
+  if (entries.includes("references") && existsSync(refsDir) && statSync(refsDir).isDirectory()) {
+    for (const ref of readdirSync(refsDir)) {
+      const refMentioned = body.includes(ref) || body.includes(`references/${ref}`);
+      addCheck(
+        `ref_linked_${ref}`,
+        refMentioned,
+        refMentioned
+          ? `references/${ref} is referenced in SKILL.md`
+          : `references/${ref} exists but is not referenced in SKILL.md`,
+        "warning",
+      );
+    }
+  }
+
+  // --- Summary ---
+  if (results.failed === 0) {
+    results.summary =
+      `PASS — ${results.passed} checks passed` + (results.warnings > 0 ? `, ${results.warnings} warnings` : "");
+  } else {
+    results.summary = `FAIL — ${results.failed} errors, ${results.warnings} warnings`;
+    results.next_steps = results.checks
+      .filter((c) => !c.passed && c.severity === "error")
+      .map((c) => `Fix check '${c.name}': ${c.message}`);
+  }
+
+  return results;
+}
+
+function printReport(results: Results, verbose: boolean): void {
+  const bar = "=".repeat(60);
+  const line = "─".repeat(60);
+  console.log(`\n${bar}`);
+  console.log("  Skill Validation Report");
+  console.log(`  Path: ${results.path}`);
+  console.log(`  Parser: ${results.parser_mode}`);
+  console.log(`${bar}\n`);
+
+  for (const check of results.checks) {
+    if (check.passed && !verbose) continue;
+    const icon = check.passed ? "✅" : check.severity === "warning" ? "⚠️" : "❌";
+    console.log(`  ${icon} ${check.name}: ${check.message}`);
+  }
+
+  console.log(`\n${line}`);
+  console.log(`  ${results.summary}`);
+  console.log(`  Passed: ${results.passed} | Failed: ${results.failed} | Warnings: ${results.warnings}`);
+  console.log(`${line}\n`);
+
+  if (results.next_steps.length > 0) {
+    console.log("  Next steps:");
+    results.next_steps.forEach((step, i) => console.log(`    ${i + 1}. ${step}`));
+    console.log("");
+  }
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  let skillPath: string | undefined;
+  let format: "human" | "json" | "both" = "human";
+  let verbose = false;
+  let prettyJson = false;
+  let jsonOut: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--format") {
+      const v = args[++i];
+      if (v !== "human" && v !== "json" && v !== "both") {
+        console.error(`Invalid --format: ${v} (choose human|json|both)`);
+        process.exit(2);
+      }
+      format = v;
+    } else if (a === "--verbose") verbose = true;
+    else if (a === "--pretty-json") prettyJson = true;
+    else if (a === "--json-out") jsonOut = args[++i];
+    else if (a === "-h" || a === "--help") {
+      console.log(
+        "Usage: bun scripts/validate_skill.ts <path> [--format human|json|both] [--verbose] [--pretty-json] [--json-out FILE]\n" +
+          "Tip: use --json-out FILE to save full results and avoid re-running for later feedback.",
+      );
+      process.exit(0);
+    } else if (!a.startsWith("-") && skillPath === undefined) skillPath = a;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      process.exit(2);
+    }
+  }
+
+  if (!skillPath) {
+    console.error("Missing required argument: path to the skill folder");
+    process.exit(2);
+  }
+
+  const results = validateSkill(skillPath);
+  const reportJson = JSON.stringify(results, null, prettyJson ? 2 : undefined);
+
+  if (format === "human" || format === "both") {
+    printReport(results, verbose);
+    if (!jsonOut) console.log("  Tip: add --json-out FILE to reuse this report without re-running.\n");
+  }
+  if (format === "json" || format === "both") {
+    if (format === "both") console.log("--- JSON Report ---");
+    console.log(reportJson);
+  }
+  if (jsonOut) {
+    writeFileSync(jsonOut, reportJson);
+    if (format === "human" || format === "both") console.log(`  JSON report saved to: ${jsonOut}`);
+  }
+
+  process.exit(results.failed === 0 ? 0 : 1);
+}

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

@@ -0,0 +1,246 @@
+---
+name: pr-review
+description: "Explicit-route workflow to review a hosted GitHub Pull Request or GitLab Merge Request across six dimensions — security, requirements, test coverage, architecture, regression, performance — using massa-ai roster subagents, then post inline comments plus one consolidated summary through the host CLI (gh or glab). Use when the user says review PR 128, review this MR, or code review this pull request. Do NOT use for local working-diff review (audit workflows), creating PRs, replying to review comments, or fixing CI."
+license: CC-BY-4.0
+metadata:
+  version: "1.0.0"
+---
+
+Attribution: adapted from the `pr-review` skill by github.com/augusto-dmh
+(TLC skills catalog), licensed CC-BY-4.0. Host abstraction (GitLab support),
+massa-ai roster dispatches, memory/index/`.specs/` integration, and channel
+discipline are this repository's additions; repository contracts win on any
+conflict with the base.
+
+### PR Review
+
+Use when the user explicitly asks to review a hosted PR (Pull Request, GitHub) or
+MR (Merge Request, GitLab) — "review PR 128", "review this MR", "check pull request
+42". Explicit route only: never auto-trigger during coding. Local working-tree diff
+review stays with the audit workflows and `massa-ai-reviewer`; this workflow exists
+to **post findings back to the host**.
+
+Load `references/project-context.md` (intake sweep) before the first substantive
+read. Resolve `projectId` and `workflowSessionId` = `pr-review-<number>` per the
+Core Contract, and run a budgeted `recall` (limit ≤ 3, minImportance ≥ 0.7) for
+prior review conventions and known regression patterns.
+
+## Execution Contract (non-negotiable)
+
+1. **Orchestration-only.** The main agent never authors a review finding. It
+   gathers context, dispatches the review subagents, dedupes their returned
+   findings, and posts. Doing the review inline — even for a small diff — is a
+   failure of this workflow.
+2. **Comment-only, never destructive.** Forbidden in every circumstance:
+   `gh pr review --approve`, `gh pr review --request-changes`, `gh pr merge`,
+   `glab mr approve`, `glab mr revoke`, `glab mr merge`, and the raw
+   `POST …/approve` / `POST …/unapprove` endpoints. Posting notes or discussions
+   never approves — keep it that way. Never modify repository files.
+3. **Subagents never touch the host.** Review subagents are read-only and
+   host-agnostic: they receive the diff and context in their packet and return
+   findings in their reply block. Only the orchestrator executes `gh`/`glab`.
+4. **File-body posting.** Every multiline body is written to a temp file and
+   posted with the host's file-body mechanism (`--body-file` / `-F body=@file`).
+   Inlining a multiline `--body` string is the protocol's most common failure.
+5. **Ask, never guess.** No PR/MR reference in the request → ask for it. Host CLI
+   cannot resolve the reference → stop and surface the CLI error output.
+
+## Step 1 — Initialize
+
+### 1a. Resolve the host
+
+Order: explicit user statement > CLI probe > git remote host. Probe with
+`gh repo view` / `glab repo view` **exit status** (glab's no-remote error text is
+not a documented stable string — never match on the message). Both probes fail →
+stop and report which CLI is missing or unauthenticated (`gh auth status` /
+`glab auth status`). Both succeed (mirrored repo) → ask the user which host to
+review on; a posted comment is outward-facing. Record `HOST ∈ {github, gitlab}`.
+
+### 1b. PR/MR context (via the command map below)
+
+Resolve repository identity, then fetch: title + body/description + source
+branch, the head anchor (`{SHA}` on GitHub; the full `diff_refs`
+`{base_sha, head_sha, start_sha}` triple on GitLab), the full diff, and the
+changed-file list. Then load the existing inline-comment inventory as
+`{id, path, line, body}` records — **page to completion** (GitLab discussions
+default to 20 per page; pin `per_page=100` and loop) — used for dedupe,
+`[RESOLVED]` replies, and threading.
+
+### 1c. Project discovery (the adaptive spine)
+
+Probe the repository once and record a DISCOVERY MAP passed verbatim to every
+subagent. Prefer evidence the project states over guesses; mark absences `none`.
+
+```
+TEST:          <command CI actually runs> | globs: <...> | unit vs e2e: <split | none>
+REQS:          tracker=<GH #42 | Jira KEY-123 | GitLab #42 | none> ; specs=<paths | none>
+CONVENTIONS:   <doc/skill paths that state rules | none-found>
+REVIEW_SKILLS: <project-local review skill paths | none>
+INDEX:         <massa-ai retrieval state: fresh | stale | unavailable — CLI fallback>
+```
+
+- **TEST**: the CI workflow config is authoritative; manifests are fallback.
+- **REQS Track A (tracker)**: ticket key from branch name or PR/MR body —
+  `gh issue view {N} --json title,body` / `glab issue view {N} --output json`;
+  Jira only through an already-configured Atlassian MCP (never invent a host).
+- **REQS Track B (in-repo)**: `.specs/project/FEATURES.json` and
+  `.specs/features/<slug>/{spec,tasks}.md` acceptance criteria matched by branch,
+  ticket, or feature stem; then `docs/`, ADR/RFC directories, `*-spec.md`.
+- **CONVENTIONS/REVIEW_SKILLS**: `CONTRIBUTING*`, `ARCHITECTURE*`, `AGENTS.md`,
+  `CLAUDE.md`, `docs/**` convention files, `.claude/skills/`, `.cursor/skills/`.
+- **INDEX**: `list_projects` freshness first; when fresh, `project_map` or
+  `get_architecture` for orientation and `impact_analysis` over the PR/MR diff
+  for centrality-ranked hotspots; `search` under `references/synapse-policy.md`
+  when two or more related searches are planned. Index results are leads until
+  confirmed against the diff — never evidence on their own. Server or index
+  unavailable → record it and continue per `references/graceful-degradation.md`.
+
+## Host Command Map
+
+The orchestrator reads every host operation from this table. `{REPO}`/`{PR}` are
+GitHub coordinates; `{MR}` is the GitLab IID; `:id` is glab's project placeholder
+(resolved from the current repo's remote — 8 placeholders are documented:
+`:branch :fullpath :group :id :namespace :repo :user :username`).
+
+| Operation | GitHub (`gh`) | GitLab (`glab`) |
+| --- | --- | --- |
+| Identity | `gh repo view --json nameWithOwner -q .nameWithOwner` → `{REPO}` | `glab repo view --output json --jq .path_with_namespace` (project id: `--jq .id`) |
+| Metadata | `gh pr view {PR} --json title,body,headRefName,headRefOid` → `{SHA}` | `glab mr view {MR} --output json` → `title`, `description`, `source_branch`, `sha`, `diff_refs.{base_sha,head_sha,start_sha}` |
+| Full diff | `gh pr diff {PR}` | `glab mr diff {MR} --raw` |
+| Changed files | `gh pr diff {PR} --name-only` | `glab api "projects/:id/merge_requests/{MR}/diffs?per_page=100&page={N}"` → `new_path`/`old_path`, page to completion |
+| Existing comments | `gh api repos/{REPO}/pulls/{PR}/comments` | `glab api "projects/:id/merge_requests/{MR}/discussions?per_page=100&page={N}"` → note `id`, `position.new_path`, `position.new_line`, `body` |
+| Inline comment | `gh api repos/{REPO}/pulls/{PR}/comments -F body=@body.md -f commit_id={SHA} -f path={path} -F line={N} -f side=RIGHT` | `glab api --method POST "projects/:id/merge_requests/{MR}/discussions" -F body=@body.md -f "position[position_type]=text" -f "position[base_sha]={base}" -f "position[head_sha]={head}" -f "position[start_sha]={start}" -f "position[new_path]={path}" -f "position[old_path]={old}" -F "position[new_line]={N}"` |
+| Thread reply | `gh api repos/{REPO}/pulls/{PR}/comments/{COMMENT_ID}/replies -F body=@body.md` | `glab api --method POST "projects/:id/merge_requests/{MR}/discussions/{DISCUSSION_ID}/notes" -F body=@body.md` |
+| Summary | `gh pr review {PR} --comment --body-file summary.md` | `glab api --method POST "projects/:id/merge_requests/{MR}/notes" -F body=@summary.md` |
+
+Anchoring and flag semantics (load-bearing, verified against official docs):
+
+- **GitHub `line={N}`** is the 1-based line number in the **head file** on side
+  `RIGHT` — count from the hunk header across added and context lines. A
+  diff-relative offset returns 422 or lands on the wrong line.
+- **GitLab added line** ⇒ send `position[new_line]` and **omit** `old_line`
+  (removed line: the reverse; context line: both). `new_path` **and** `old_path`
+  are both required for `position_type=text` — take `old_path` from the `/diffs`
+  inventory, never assume it equals `new_path` (renames break that).
+- **`-F`/`--field` expands `@file` and infers types on both CLIs; `-f`/
+  `--raw-field` does neither** — `-f body=@body.md` posts the literal string
+  `@body.md`. Use `-F` for bodies and line numbers, `-f` for plain strings.
+  glab's `-F` also switches the default method to POST.
+- `glab mr note create` has experimental inline flags (`--file`, `--line`,
+  `--reply`) — GitLab marks them "might be unstable or removed at any time"; the
+  stable `glab api` paths above are the contract. A plain summary may also use
+  `glab mr note create {MR} < summary.md` (body from stdin).
+
+## Step 2 — Dispatch the review (two waves)
+
+Six dimensions run as read-only roster dispatches under
+`references/agent-orchestration.md` (wave cap 4 → wave 1 = rows 1–4, wave 2 =
+rows 5–6). Each packet carries: the dimension row below, the DISCOVERY MAP, the
+PR/MR intent (title/body/branch), the existing-comment inventory, the diff
+trimmed to hunks relevant to the dimension per `references/context-firewall.md`,
+the severity labels, and the reply contract.
+
+| # | Dimension | Agent | Packet delta (lens / scope) | Marker `{type}` |
+| --- | --- | --- | --- | --- |
+| 1 | Security | `massa-ai-audit-specialist` | `lens: security` — secrets, authn/authz on new endpoints, injection, unsafe deserialization, PII in logs, permissive CORS, leaking payload fields | `security` |
+| 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` |
+| 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
+share only the lens label, not a knowledge domain; they stay separate dispatches.
+
+> **Dispatch: `massa-ai-audit-specialist`** (role: `audit-specialist`) — charter `skills/agents/audit-specialist/SKILL.md`
+> - trigger: pr-review Step 2, dimension rows 1–5 (one dispatch per row)
+> - scope: the PR/MR diff and surrounding context for one dimension row; never the whole repository
+> - permissions: read-only; no host CLI calls, no posting
+> - inputs: exact `projectId`, parent `workflowSessionId`, dimension row (lens + scope), DISCOVERY MAP, PR/MR intent, trimmed diff, existing-comment inventory, severity labels, reply contract
+> - sensors: second-pass sweep — re-read the full trimmed diff, list every file/hunk not commented on, and state per file why it is clean for this dimension before returning
+> - output: structured reply block — findings rows `{path, head-line, severity, marker type, title, body ≤ 6 lines, recommendation}` + exactly one positive highlight + files-swept-clean list; when uncertain a finding is real, withhold it (the source protocol's high-confidence bar, applied qualitatively)
+> - firewall: raw diff/log/search output summarized, never returned raw
+> - memory: suggest-only; the main agent persists durable outcomes
+> - 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: pr-review Step 2, dimension row 6 (regression & hallucination)
+> - scope: the full PR/MR diff against the repository's real symbol surface
+> - permissions: read-only; no host CLI calls, no posting
+> - inputs: exact `projectId`, parent `workflowSessionId`, dimension row 6, DISCOVERY MAP, PR/MR intent, full diff, existing-comment inventory, severity labels, reply contract
+> - sensors: verify referenced symbols exist (`search_definitions`/`get_references` when INDEX is fresh, else grep); second-pass sweep as above
+> - output: structured reply block — findings rows tagged `{unrelated-deletion | phantom-reference | wrong-signature | duplicate | weakened-check | dead-code}` + one positive highlight + files-swept-clean list; withhold uncertain findings
+> - firewall: raw diff/log/search output summarized, never returned raw
+> - memory: suggest-only; the main agent persists durable outcomes
+> - 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
+
+Severity labels (all dimensions): 🚨 Critical (bugs/logic errors that will fail) ·
+🔒 Security · ⚡ Performance · ⚠️ Warning (smells/maintainability) ·
+💡 Suggestion. A failed or unavailable dispatch is reported in the summary as a
+skipped dimension with its reason — never silently dropped.
+
+## Step 3 — Post inline findings (orchestrator only)
+
+For every returned finding, in order:
+
+1. **Dedupe**: drop it when an existing comment sits within ±3 lines of the same
+   path/line (inventory from 1b) or another dimension already produced the same
+   `{path, line}` finding (keep the higher severity; note both markers).
+2. **Resolve check**: when an existing comment's issue is fixed by this diff,
+   reply `[RESOLVED] This appears resolved by the recent changes.` on that thread
+   via the reply command (GitHub: the comment's `id`; GitLab: its
+   `discussion_id`).
+3. **Anchor**: only added (`+`) diff lines on the head revision, per the
+   anchoring semantics above. A finding with no `+` line to stand on goes to the
+   summary instead.
+4. **Body**: temp file, starting with the invisible marker
+   `<!-- pr-review:{type} -->`, then `[severity emoji] — [short title]`, the
+   evidence-grounded body, and a `**Recommendation:**` line. No AI/assistant/
+   tool attribution anywhere — write as a reviewer. Specific, actionable,
+   collegial; always explain why.
+5. **Post** with the inline-comment command for `HOST`.
+
+## Step 4 — Consolidated summary
+
+Assemble from the reply blocks (no extra subagent) and post one summary via the
+summary command:
+
+```markdown
+## 📋 PR Review Summary
+
+| | |
+|---|---|
+| **Host / target** | {github PR #N | gitlab MR !N} @ {head sha} |
+| **Dimensions** | 6 (Security · Requirements & DoD · Tests · Architecture · Regression · Performance) |
+| **Detected runner** | {TEST row | none found} |
+| **Requirements source** | {tracker / spec paths / none} |
+| **Project refs loaded** | {CONVENTIONS + REVIEW_SKILLS rows} |
+| **Findings** | {N} across {M} files |
+
+### 🔒 Security ({N}) / 🚨 Critical ({N}) / ⚡ Performance ({N}) / ⚠️ Warnings ({N}) / 💡 Suggestions ({N})
+- [`path/file:L42`] Finding title — one line each, grouped by severity
+
+### 📋 Requirements
+{✅/🟡/❌ rows from dimension 2, with `path:line` evidence}
+
+### 🔍 Files with no findings
+- `path` — swept clean by {dimensions} (omit section when every logic file got a comment; config/lock/declaration files excluded)
+
+### ✅ Highlights
+- one per dimension
+
+> See inline comments for details. {Skipped dimensions/sensors with reasons, if any.}
+```
+
+Zero findings overall → post "✅ No issues found across all review dimensions."
+with the metadata table intact.
+
+## Completion
+
+- Emit Conversation Feedback status updates at wave boundaries when that policy
+  is active; expand every abbreviation on first use in user-facing output.
+- Persist durable outcomes only (recurring review pattern, confirmed project
+  convention) with the required memory tags; do not fabricate memories.
+- Close with `references/evidence-gate.md`: counts posted vs deduped vs withheld,
+  skipped dimensions/sensors with reasons, and the summary URL/reference.
+<!-- validator anchors: comment-only | added (+) diff lines | page to completion | two waves -->