@mstar-harness/omp 3.6.0-alpha.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +63 -0
- package/agents/architect.md +35 -0
- package/agents/code-reviewer.md +90 -0
- package/agents/frontend-dev.md +33 -0
- package/agents/fullstack-dev-2.md +33 -0
- package/agents/fullstack-dev.md +33 -0
- package/agents/ops-engineer.md +33 -0
- package/agents/product-manager.md +35 -0
- package/agents/project-manager.md +32 -0
- package/agents/prompt-engineer.md +33 -0
- package/agents/qa-engineer.md +35 -0
- package/agents/qc-specialist-2.md +62 -0
- package/agents/qc-specialist-3.md +62 -0
- package/agents/qc-specialist.md +62 -0
- package/agents/writing-specialist.md +35 -0
- package/assets/icon.png +0 -0
- package/assets/logo-dark.png +0 -0
- package/assets/logo-dark.svg +6 -0
- package/assets/logo.png +0 -0
- package/assets/logo.svg +6 -0
- package/commands/amazing-pr-review.md +31 -0
- package/commands/codebase-audit.md +40 -0
- package/commands/iteration-drive.md +48 -0
- package/commands/iteration-loop.md +99 -0
- package/commands/iteration-start.md +122 -0
- package/dist/hooks/pre/mstar-gates.js +6579 -0
- package/dist/tools/mstar_dispatch_validate/index.js +6291 -0
- package/dist/tools/mstar_iteration_gate/index.js +6321 -0
- package/dist/tools/mstar_lease_verify/index.js +6343 -0
- package/dist/tools/mstar_path_resolve/index.js +6297 -0
- package/dist/tools/mstar_status_validate/index.js +6402 -0
- package/dist/tools/mstar_worktree_check/index.js +6343 -0
- package/harness-agents/architect.md +35 -0
- package/harness-agents/code-reviewer.md +90 -0
- package/harness-agents/frontend-dev.md +33 -0
- package/harness-agents/fullstack-dev-2.md +33 -0
- package/harness-agents/fullstack-dev.md +33 -0
- package/harness-agents/ops-engineer.md +33 -0
- package/harness-agents/product-manager.md +35 -0
- package/harness-agents/project-manager.md +32 -0
- package/harness-agents/prompt-engineer.md +33 -0
- package/harness-agents/qa-engineer.md +35 -0
- package/harness-agents/qc-specialist-2.md +62 -0
- package/harness-agents/qc-specialist-3.md +62 -0
- package/harness-agents/qc-specialist.md +62 -0
- package/harness-agents/writing-specialist.md +35 -0
- package/harness-commands/amazing-pr-review.md +31 -0
- package/harness-commands/codebase-audit.md +40 -0
- package/harness-commands/iteration-drive.md +48 -0
- package/harness-commands/iteration-loop.md +99 -0
- package/harness-commands/iteration-start.md +122 -0
- package/harness-skills/grill-me/SKILL.md +10 -0
- package/harness-skills/mstar-artifacts/SKILL.md +66 -0
- package/harness-skills/mstar-artifacts/references/knowledge-and-designs.md +110 -0
- package/harness-skills/mstar-artifacts/references/plan-files-and-reports.md +98 -0
- package/harness-skills/mstar-artifacts/references/plan-quality-bar.md +99 -0
- package/harness-skills/mstar-artifacts/references/status-and-residuals.md +472 -0
- package/harness-skills/mstar-artifacts/templates/README.md +7 -0
- package/harness-skills/mstar-artifacts/templates/plan.main.md +54 -0
- package/harness-skills/mstar-artifacts/templates/status.empty.json +5 -0
- package/harness-skills/mstar-audit/SKILL.md +151 -0
- package/harness-skills/mstar-audit/references/audit-playbook.md +175 -0
- package/harness-skills/mstar-audit/references/codebase-audit.md +103 -0
- package/harness-skills/mstar-audit/references/finding-format.md +69 -0
- package/harness-skills/mstar-audit/references/pr-review-seat-evidence.md +28 -0
- package/harness-skills/mstar-audit/references/pr-review.md +475 -0
- package/harness-skills/mstar-audit/references/security-review.md +219 -0
- package/harness-skills/mstar-branch-worktree/SKILL.md +236 -0
- package/harness-skills/mstar-branch-worktree/references/parallel-writable-pre-dispatch.md +68 -0
- package/harness-skills/mstar-coding-behavior/SKILL.md +167 -0
- package/harness-skills/mstar-compound/SKILL.md +109 -0
- package/harness-skills/mstar-compound/assets/resolution-template.md +94 -0
- package/harness-skills/mstar-compound/references/category-mapping.md +37 -0
- package/harness-skills/mstar-compound/references/compound-workflow.md +171 -0
- package/harness-skills/mstar-compound/references/concepts-vocabulary.md +44 -0
- package/harness-skills/mstar-compound/references/schema.yaml +122 -0
- package/harness-skills/mstar-compound-refresh/SKILL.md +154 -0
- package/harness-skills/mstar-compound-refresh/references/project-knowledge-bootstrap.md +164 -0
- package/harness-skills/mstar-conventions/SKILL.md +215 -0
- package/harness-skills/mstar-conventions/references/artifact-storage-paths.md +53 -0
- package/harness-skills/mstar-conventions/references/effort-estimation.md +38 -0
- package/harness-skills/mstar-conventions/references/harness-bootstrap-and-agents-layering.md +96 -0
- package/harness-skills/mstar-design-md/SKILL.md +142 -0
- package/harness-skills/mstar-design-md/references/completeness-checklist.md +181 -0
- package/harness-skills/mstar-design-md/references/design-md-spec.md +508 -0
- package/harness-skills/mstar-design-md/references/vercel-example.md +200 -0
- package/harness-skills/mstar-design-md/templates/DESIGN.dark.md.template +354 -0
- package/harness-skills/mstar-design-md/templates/DESIGN.md.template +474 -0
- package/harness-skills/mstar-dispatch-gates/SKILL.md +134 -0
- package/harness-skills/mstar-dispatch-gates/references/leaf-executor-checklist.md +23 -0
- package/harness-skills/mstar-engine-legacy/SKILL.md +53 -0
- package/harness-skills/mstar-engine-legacy/references/anti-recursion-checklists.md +58 -0
- package/harness-skills/mstar-engine-legacy/references/engine-check-boilerplate.md +26 -0
- package/harness-skills/mstar-engine-legacy/references/lease-protocol.md +92 -0
- package/harness-skills/mstar-engine-legacy/references/qc-seat-n-restatements.md +57 -0
- package/harness-skills/mstar-engine-legacy/references/status-field-history.md +186 -0
- package/harness-skills/mstar-harness-core/SKILL.md +196 -0
- package/harness-skills/mstar-host/SKILL.md +96 -0
- package/harness-skills/mstar-host/references/_shared/host-role-binding-core.md +51 -0
- package/harness-skills/mstar-host/references/_shared/plan-mode-bridge-core.md +91 -0
- package/harness-skills/mstar-host/references/codex.md +61 -0
- package/harness-skills/mstar-host/references/cursor-plan-mode-bridge.md +170 -0
- package/harness-skills/mstar-host/references/cursor.md +183 -0
- package/harness-skills/mstar-host/references/dsh.md +507 -0
- package/harness-skills/mstar-host/references/kimi-plan-mode-bridge.md +36 -0
- package/harness-skills/mstar-host/references/kimi.md +136 -0
- package/harness-skills/mstar-host/references/omp-plan-mode-bridge.md +32 -0
- package/harness-skills/mstar-host/references/omp.md +245 -0
- package/harness-skills/mstar-host/references/opencode.md +76 -0
- package/harness-skills/mstar-host/references/parallel-dispatch.md +68 -0
- package/harness-skills/mstar-host/references/zcode-plan-mode-bridge.md +36 -0
- package/harness-skills/mstar-host/references/zcode.md +129 -0
- package/harness-skills/mstar-iteration/SKILL.md +408 -0
- package/harness-skills/mstar-iteration/references/autonomous-direction-lock.md +90 -0
- package/harness-skills/mstar-iteration/references/command-shared-invariants.md +62 -0
- package/harness-skills/mstar-iteration/references/iteration-artifact-boundaries.md +103 -0
- package/harness-skills/mstar-iteration/references/iteration-compass-template.md +142 -0
- package/harness-skills/mstar-iteration/references/iteration-corpus-hygiene.md +45 -0
- package/harness-skills/mstar-iteration/references/iteration-workspace-readme-template.md +27 -0
- package/harness-skills/mstar-iteration/references/phase-2-worktree-lease.md +205 -0
- package/harness-skills/mstar-iteration/references/phase-3-iteration-close.md +105 -0
- package/harness-skills/mstar-iteration/references/phase-4-5-pr-delivery.md +85 -0
- package/harness-skills/mstar-iteration/references/phase5-helper-discovery.md +24 -0
- package/harness-skills/mstar-phase-gates/SKILL.md +118 -0
- package/harness-skills/mstar-project-governance/SKILL.md +119 -0
- package/harness-skills/mstar-review-qc/SKILL.md +76 -0
- package/harness-skills/mstar-review-qc/references/review-responsibility-boundaries.md +54 -0
- package/harness-skills/mstar-roles/SKILL.md +103 -0
- package/harness-skills/mstar-roles/references/_shared/leaf-executor-core.md +65 -0
- package/harness-skills/mstar-roles/references/architect.md +109 -0
- package/harness-skills/mstar-roles/references/code-reviewer.md +118 -0
- package/harness-skills/mstar-roles/references/frontend-dev.md +70 -0
- package/harness-skills/mstar-roles/references/fullstack-dev-shared.md +89 -0
- package/harness-skills/mstar-roles/references/ops-engineer.md +72 -0
- package/harness-skills/mstar-roles/references/product-manager.md +102 -0
- package/harness-skills/mstar-roles/references/project-manager/dispatch-and-assignment.md +200 -0
- package/harness-skills/mstar-roles/references/project-manager/plan-management.md +59 -0
- package/harness-skills/mstar-roles/references/project-manager/qa-trigger-matrix.md +56 -0
- package/harness-skills/mstar-roles/references/project-manager/qc-and-residuals.md +99 -0
- package/harness-skills/mstar-roles/references/project-manager/routing-and-dev-allocation.md +99 -0
- package/harness-skills/mstar-roles/references/project-manager.md +310 -0
- package/harness-skills/mstar-roles/references/prompt-engineer.md +65 -0
- package/harness-skills/mstar-roles/references/qa-engineer/acceptance-gate.md +62 -0
- package/harness-skills/mstar-roles/references/qa-engineer.md +71 -0
- package/harness-skills/mstar-roles/references/qc-specialist/deep-review-lenses.md +104 -0
- package/harness-skills/mstar-roles/references/qc-specialist/report-template.md +88 -0
- package/harness-skills/mstar-roles/references/qc-specialist/reviewer-checklist.md +44 -0
- package/harness-skills/mstar-roles/references/qc-specialist/reviewer-workflow.md +57 -0
- package/harness-skills/mstar-roles/references/qc-specialist-shared.md +120 -0
- package/harness-skills/mstar-roles/references/writing-specialist.md +88 -0
- package/harness-skills/mstar-sdd/SKILL.md +137 -0
- package/harness-skills/mstar-sdd/references/file-handoffs.md +85 -0
- package/harness-skills/mstar-sdd/references/implementer-continuation-prompt.md +44 -0
- package/harness-skills/mstar-sdd/references/implementer-prompt.md +56 -0
- package/harness-skills/mstar-sdd/references/sticky-implementer-session.md +103 -0
- package/harness-skills/mstar-sdd/references/task-reviewer-prompt.md +53 -0
- package/harness-skills/mstar-skill-authoring/SKILL.md +182 -0
- package/harness-skills/mstar-skill-authoring/references/regression-fixation.md +46 -0
- package/harness-skills/mstar-skill-authoring/references/skillsbench-authoring.md +154 -0
- package/harness-skills/mstar-strategy/SKILL.md +114 -0
- package/harness-skills/pm/SKILL.md +40 -0
- package/hooks/pre/mstar-gates.js +6579 -0
- package/package.json +45 -0
- package/plugin.json +49 -0
- package/skills/grill-me/SKILL.md +10 -0
- package/skills/mstar-artifacts/SKILL.md +66 -0
- package/skills/mstar-artifacts/references/knowledge-and-designs.md +110 -0
- package/skills/mstar-artifacts/references/plan-files-and-reports.md +98 -0
- package/skills/mstar-artifacts/references/plan-quality-bar.md +99 -0
- package/skills/mstar-artifacts/references/status-and-residuals.md +472 -0
- package/skills/mstar-artifacts/templates/README.md +7 -0
- package/skills/mstar-artifacts/templates/plan.main.md +54 -0
- package/skills/mstar-artifacts/templates/status.empty.json +5 -0
- package/skills/mstar-audit/SKILL.md +151 -0
- package/skills/mstar-audit/references/audit-playbook.md +175 -0
- package/skills/mstar-audit/references/codebase-audit.md +103 -0
- package/skills/mstar-audit/references/finding-format.md +69 -0
- package/skills/mstar-audit/references/pr-review-seat-evidence.md +28 -0
- package/skills/mstar-audit/references/pr-review.md +475 -0
- package/skills/mstar-audit/references/security-review.md +219 -0
- package/skills/mstar-branch-worktree/SKILL.md +236 -0
- package/skills/mstar-branch-worktree/references/parallel-writable-pre-dispatch.md +68 -0
- package/skills/mstar-coding-behavior/SKILL.md +167 -0
- package/skills/mstar-compound/SKILL.md +109 -0
- package/skills/mstar-compound/assets/resolution-template.md +94 -0
- package/skills/mstar-compound/references/category-mapping.md +37 -0
- package/skills/mstar-compound/references/compound-workflow.md +171 -0
- package/skills/mstar-compound/references/concepts-vocabulary.md +44 -0
- package/skills/mstar-compound/references/schema.yaml +122 -0
- package/skills/mstar-compound-refresh/SKILL.md +154 -0
- package/skills/mstar-compound-refresh/references/project-knowledge-bootstrap.md +164 -0
- package/skills/mstar-conventions/SKILL.md +215 -0
- package/skills/mstar-conventions/references/artifact-storage-paths.md +53 -0
- package/skills/mstar-conventions/references/effort-estimation.md +38 -0
- package/skills/mstar-conventions/references/harness-bootstrap-and-agents-layering.md +96 -0
- package/skills/mstar-design-md/SKILL.md +142 -0
- package/skills/mstar-design-md/references/completeness-checklist.md +181 -0
- package/skills/mstar-design-md/references/design-md-spec.md +508 -0
- package/skills/mstar-design-md/references/vercel-example.md +200 -0
- package/skills/mstar-design-md/templates/DESIGN.dark.md.template +354 -0
- package/skills/mstar-design-md/templates/DESIGN.md.template +474 -0
- package/skills/mstar-dispatch-gates/SKILL.md +134 -0
- package/skills/mstar-dispatch-gates/references/leaf-executor-checklist.md +23 -0
- package/skills/mstar-engine-legacy/SKILL.md +53 -0
- package/skills/mstar-engine-legacy/references/anti-recursion-checklists.md +58 -0
- package/skills/mstar-engine-legacy/references/engine-check-boilerplate.md +26 -0
- package/skills/mstar-engine-legacy/references/lease-protocol.md +92 -0
- package/skills/mstar-engine-legacy/references/qc-seat-n-restatements.md +57 -0
- package/skills/mstar-engine-legacy/references/status-field-history.md +186 -0
- package/skills/mstar-harness-core/SKILL.md +196 -0
- package/skills/mstar-host/SKILL.md +96 -0
- package/skills/mstar-host/references/_shared/host-role-binding-core.md +51 -0
- package/skills/mstar-host/references/_shared/plan-mode-bridge-core.md +91 -0
- package/skills/mstar-host/references/codex.md +61 -0
- package/skills/mstar-host/references/cursor-plan-mode-bridge.md +170 -0
- package/skills/mstar-host/references/cursor.md +183 -0
- package/skills/mstar-host/references/dsh.md +507 -0
- package/skills/mstar-host/references/kimi-plan-mode-bridge.md +36 -0
- package/skills/mstar-host/references/kimi.md +136 -0
- package/skills/mstar-host/references/omp-plan-mode-bridge.md +32 -0
- package/skills/mstar-host/references/omp.md +245 -0
- package/skills/mstar-host/references/opencode.md +76 -0
- package/skills/mstar-host/references/parallel-dispatch.md +68 -0
- package/skills/mstar-host/references/zcode-plan-mode-bridge.md +36 -0
- package/skills/mstar-host/references/zcode.md +129 -0
- package/skills/mstar-iteration/SKILL.md +408 -0
- package/skills/mstar-iteration/references/autonomous-direction-lock.md +90 -0
- package/skills/mstar-iteration/references/command-shared-invariants.md +62 -0
- package/skills/mstar-iteration/references/iteration-artifact-boundaries.md +103 -0
- package/skills/mstar-iteration/references/iteration-compass-template.md +142 -0
- package/skills/mstar-iteration/references/iteration-corpus-hygiene.md +45 -0
- package/skills/mstar-iteration/references/iteration-workspace-readme-template.md +27 -0
- package/skills/mstar-iteration/references/phase-2-worktree-lease.md +205 -0
- package/skills/mstar-iteration/references/phase-3-iteration-close.md +105 -0
- package/skills/mstar-iteration/references/phase-4-5-pr-delivery.md +85 -0
- package/skills/mstar-iteration/references/phase5-helper-discovery.md +24 -0
- package/skills/mstar-phase-gates/SKILL.md +118 -0
- package/skills/mstar-project-governance/SKILL.md +119 -0
- package/skills/mstar-review-qc/SKILL.md +76 -0
- package/skills/mstar-review-qc/references/review-responsibility-boundaries.md +54 -0
- package/skills/mstar-roles/SKILL.md +103 -0
- package/skills/mstar-roles/references/_shared/leaf-executor-core.md +65 -0
- package/skills/mstar-roles/references/architect.md +109 -0
- package/skills/mstar-roles/references/code-reviewer.md +118 -0
- package/skills/mstar-roles/references/frontend-dev.md +70 -0
- package/skills/mstar-roles/references/fullstack-dev-shared.md +89 -0
- package/skills/mstar-roles/references/ops-engineer.md +72 -0
- package/skills/mstar-roles/references/product-manager.md +102 -0
- package/skills/mstar-roles/references/project-manager/dispatch-and-assignment.md +200 -0
- package/skills/mstar-roles/references/project-manager/plan-management.md +59 -0
- package/skills/mstar-roles/references/project-manager/qa-trigger-matrix.md +56 -0
- package/skills/mstar-roles/references/project-manager/qc-and-residuals.md +99 -0
- package/skills/mstar-roles/references/project-manager/routing-and-dev-allocation.md +99 -0
- package/skills/mstar-roles/references/project-manager.md +310 -0
- package/skills/mstar-roles/references/prompt-engineer.md +65 -0
- package/skills/mstar-roles/references/qa-engineer/acceptance-gate.md +62 -0
- package/skills/mstar-roles/references/qa-engineer.md +71 -0
- package/skills/mstar-roles/references/qc-specialist/deep-review-lenses.md +104 -0
- package/skills/mstar-roles/references/qc-specialist/report-template.md +88 -0
- package/skills/mstar-roles/references/qc-specialist/reviewer-checklist.md +44 -0
- package/skills/mstar-roles/references/qc-specialist/reviewer-workflow.md +57 -0
- package/skills/mstar-roles/references/qc-specialist-shared.md +120 -0
- package/skills/mstar-roles/references/writing-specialist.md +88 -0
- package/skills/mstar-sdd/SKILL.md +137 -0
- package/skills/mstar-sdd/references/file-handoffs.md +85 -0
- package/skills/mstar-sdd/references/implementer-continuation-prompt.md +44 -0
- package/skills/mstar-sdd/references/implementer-prompt.md +56 -0
- package/skills/mstar-sdd/references/sticky-implementer-session.md +103 -0
- package/skills/mstar-sdd/references/task-reviewer-prompt.md +53 -0
- package/skills/mstar-skill-authoring/SKILL.md +182 -0
- package/skills/mstar-skill-authoring/references/regression-fixation.md +46 -0
- package/skills/mstar-skill-authoring/references/skillsbench-authoring.md +154 -0
- package/skills/mstar-strategy/SKILL.md +114 -0
- package/skills/pm/SKILL.md +40 -0
- package/tools/mstar_dispatch_validate.js +6291 -0
- package/tools/mstar_iteration_gate.js +6321 -0
- package/tools/mstar_lease_verify.js +6343 -0
- package/tools/mstar_path_resolve.js +6297 -0
- package/tools/mstar_status_validate.js +6402 -0
- package/tools/mstar_worktree_check.js +6343 -0
|
@@ -0,0 +1,475 @@
|
|
|
1
|
+
# Deep PR Review Process
|
|
2
|
+
|
|
3
|
+
Read-only, evidence-first review of a pull request / branch / diff, producing exactly one verdict: `ship it` / `needs fixes` / `blocked`. Runs under `mstar-audit` ยง `pr` variant, reusing the Recon โ Audit โ Vet discipline (recon = PR scope + repo guidance; vet = three-way attack). The reviewer never edits the worktree, never merges, and never approves-as-merge.
|
|
4
|
+
|
|
5
|
+
## Review pipeline (three-stage)
|
|
6
|
+
|
|
7
|
+
Deep PR review is a **three-stage pipeline**: collect โ domain review โ synthesis. One PR gets multi-seat coverage (code + security, split by domain) but exactly **one verdict and one GitHub Review**, synthesized and published by the main agent. Every seat is a read-only audit seat; only the main agent posts.
|
|
8
|
+
|
|
9
|
+
- **Stage 1 โ Collect**: PM fans out lightweight read-only agents by **domain** โ business domain / change surface / tech stack; use the host's lightest read-only agent (`scout` / `explorer` / `general` โ whatever the host offers). Each collect seat reads the changed files in its domain plus related context and returns **evidence in its result payload** (any seat may be **write-blocked** โ read-only sandbox / EPERM; the main agent extracts the payload and writes the evidence file โ ยง Local report archive / `references/pr-review-seat-evidence.md`): `file:line` observations, potential issue surfaces, and security-surface observations (the seat carries a security lens per `security-review.md` ยง2/ยง3 **research** discipline โ trace origin, never invent an attacker, never record secret values โ and still records MEDIUM / unverified items as **leads** in its evidence payload; the HIGH-only filter applies to formal findings, not leads). Collect seats produce **no** findings table, compute **no** verdict, and publish **nothing**.
|
|
10
|
+
- **Stage 2 โ Domain review**: mstar built-in roles (`code-reviewer` / `fullstack-dev` / `frontend-dev`) split along the same domain framing, each reviewing code + security in its domain (security via the `security-review.md` lens) and producing findings with **Merge class** (ยง Merge class). Each domain seat returns its findings in the **result payload** โ any seat may be **write-blocked**; the main agent writes the Stage 2 evidence file (ยง Local report archive / `references/pr-review-seat-evidence.md`). A large PR (>~300 changed lines, or spanning multiple change surfaces/domains) or a security-sensitive surface (auth, LLM, supply chain, data โ `security-review.md` ยง9 extended surfaces) adds an **independent cross-domain security seat**.
|
|
11
|
+
- **Stage 3 โ Synthesis (main agent)**: the main agent (the command's orchestrator) collects all domain findings + evidence files โ **dedupe** โ **three-way vet** (open each cited file yourself; `file:line` must genuinely support the claim) โ **tally** (ยง Tally and derived score โ formula unchanged) โ **verdict** โ report + **publish GitHub Review** (ยง Comment posting โ publishing authority belongs to the main agent). The main agent does not backfill uncollected / unreviewed domains โ a missing domain is declared in the report under `- unverified:` / `- notes:`. **The envelope is mandatory**: after the tally, the main agent **must** fold the accepted findings into a `mstar.review/v1` envelope (`synthesizeReview` โ or the equivalent engine call) and persist it via `mstar-harness persist review --key <plan-or-pr-id> --stdin` (or `getArtifactStore().put`); the Markdown archive is an optional human copy, **not** a substitute for the envelope.
|
|
12
|
+
- A domain whose seat returned **no evidence** (crashed / Blocked / empty output) is an **uncollected domain**, declared the same way under `- unverified:` / `- notes:`.
|
|
13
|
+
|
|
14
|
+
> **Engine check (when available):** run `mstar-harness persist review --key <plan-or-pr-id> --stdin` (or `import { synthesizeReview, validateMstarReviewV1 } from "@mstar-harness/engine"` in a host hook) to fold the accepted findings into the `mstar.review/v1` envelope and persist it โ `synthesizeReview` derives verdict/tally from `computePrTally` (pure, no I/O), and `kind: review` runs `validateMstarReviewV1` before put, refusing invalid envelopes (exit 1, nothing written). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
15
|
+
|
|
16
|
+
**Scale-driven fan-out** (reuses the existing sizing bands โ no new thresholds): Stage 1 collect seats scale with PR size; the extra security seat stays in Stage 2:
|
|
17
|
+
|
|
18
|
+
| Size | Stage 1 collect seats | Extra Stage 2 |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| Small (~โค300 / single surface) | 2 (code + security) | independent cross-domain security seat only if security-sensitive (`security-review.md` ยง9) |
|
|
21
|
+
| Large (>~300 / multi-domain) | 2โ3 by domain | cross-domain security seat as needed |
|
|
22
|
+
|
|
23
|
+
- The ~1000 band of ยง Sizing & change shape is unchanged (too large โ advise split); the pipeline fan-out threshold **is** the ~300 band โ there is no second set of numbers.
|
|
24
|
+
|
|
25
|
+
**Fan-out discipline**: every collect / domain seat is a **read-only audit seat** (shared contract โ `mstar-roles` `references/_shared/leaf-executor-core.md` Audit Mode). PM creates the worktree and resolves the diff basis **first** (ยง Worktree isolation), then fans out. Domain-seat Assignments may carry `Delegation: allowed (scout/explore only, read-only)` (reusing the full-audit pattern). **For three-stage seats, never-post is the permanent contract** โ posting is Stage 3 only, by the main agent: the main agent (the command's orchestrator) posts the review; review seats never post. Audit Mode, Hard Rule 2, and Mode C are aligned; no seat-level POST carve-out exists.
|
|
26
|
+
|
|
27
|
+
**Seat prompts** โ every seat loads the **seat evidence contract** at `references/pr-review-seat-evidence.md` (return evidence / findings in the result payload โ any seat may be **write-blocked**; the main agent writes the evidence files โ ยง Local report archive). Stage 1 collect seats get: the absolute path to `references/pr-review.md` and the sections to read, the review worktree absolute path, the absolute path to the pinned diff snapshot (when `worktree-setup` produced it โ passed as `--diff-file`), recon facts (language / framework / directories / what was skipped), decided tradeoffs, and **Hard Rules 4/5 verbatim** โ no findings table, no verdict. Stage 2 domain / security seats additionally load the **findings contract**: `references/finding-format.md`, `references/security-review.md` (security seats), and the instruction to produce findings with **Merge class** (ยง Merge class), return them in the result payload (writable seats may **best-effort** write the Stage 2 evidence file directly โ the main agent merges โ ยง Local report archive), and return only findings โ no fixes; never post.
|
|
28
|
+
|
|
29
|
+
> **Engine check (when available):** run `mstar pr-review seat-prompt --stage 1|2 --domain <d> --seat <id> --worktree <path> [--security] [--recon <fact> ...] [--diff-file <path>]` (or `import { prReviewSeatPrompt } from "@mstar-harness/engine"` in a host hook) to generate the prompt skeleton โ Hard Rules 4/5 verbatim, payload-return contract, no-verdict/no-post clauses, slug `<domain>-<seat>`, Merge-class instruction on stage 2. Judgment stays with the PM/agent: domain selection, which tradeoffs are decided, and whether the surface warrants the security lens. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
30
|
+
|
|
31
|
+
## Review depth (tiers)
|
|
32
|
+
|
|
33
|
+
PR review runs at one of three tiers โ `quick` / `default` / `deep` โ chosen by an explicit keyword or inferred from the change shape (ยง Inference ladder). `deep` is the current three-stage pipeline verbatim; `default` is the no-flag landing tier for small code PRs; `quick` serves explicit intent and tiny-mechanical diffs. Every tier keeps the same verdict contract: one verdict derived from the tally, one GitHub Review, posted by the main agent (ยง Verdict synthesis / ยง Comment posting).
|
|
34
|
+
|
|
35
|
+
| Tier | Seats | Domain split | Security coverage | Synthesis | Relative seat-time | Boundary |
|
|
36
|
+
| --- | --- | --- | --- | --- | --- | --- |
|
|
37
|
+
| `deep` | 4โ7 (2โ3 collect + 2โ3 domain + 0โ1 independent security) | 2โ3 by domain | in-domain lens **+ independent cross-domain security seat** | main agent, all three stages | longest (= current) | = current three-stage pipeline, verbatim |
|
|
38
|
+
| `default` | 2 (two domain seats; collection folded in = seat reuse) | 2 seats by dominant surface (code/tests, backend/frontend); single-surface PR โ second seat = dedicated same-domain security-lens seat | both seats carry the in-domain security lens; **no independent cross-domain seat** (cross-domain boundary issues still go to `- notes:`; the main agent may announce an upgrade to deep) | main agent (kept) | medium (โ ยฝ of deep) | typical โค~300 changed lines; PM may announce an upgrade to deep by risk shape and declare it in the report (`- notes:`); downgraded cuts are declared likewise |
|
|
39
|
+
| `quick` | 1 (single domain seat; collect + review in one pass) | none (one seat, one pass) | in-domain security lens in the same seat (ยง2/ยง3 discipline); **no independent seat**; sensitive surface + explicit quick โ lens still runs, report declares reduced coverage under `- notes:` | main agent (kept, smallest input) | shortest (โ ยผ) | recommended โค~300 / mechanical shape; report must declare tier |
|
|
40
|
+
|
|
41
|
+
**Inference ladder** (no flag given โ first hit wins):
|
|
42
|
+
1. **Explicit tier token** โ matched **only** as a dedicated flag token (`--quick` / `--default` / `--deep`) or a trailing standalone tier word (the `[quick|default|deep]` argument position), **never** as a substring of the `[pr|branch|scope]` argument (a branch/PR title containing `quick` or `default` does not set a tier) โ that tier; user intent beats every heuristic.
|
|
43
|
+
2. **Too large** (>~1000 changed lines) โ advise a split (existing rule); if the user insists on reviewing anyway โ `deep`.
|
|
44
|
+
3. **Sensitive surface** (`security-review.md` ยง9 extended surfaces โ auth / LLM / supply chain / data โ present in the diff) โ `deep` at any size; security-sensitive surfaces are never thinned.
|
|
45
|
+
4. **Large** (>~300 changed lines, or spanning multiple change surfaces/domains) โ `deep`; large PRs never silently fall back to reduced coverage.
|
|
46
|
+
5. **Small** (โค~300, single surface):
|
|
47
|
+
- tiny-mechanical shape (docs-only / rename / formatting / pure deletion โ the existing "tiny mechanical โ general only" shape test) โ `quick`;
|
|
48
|
+
- anything else (real code change) โ `default`.
|
|
49
|
+
|
|
50
|
+
The ladder reuses the existing ~100 / ~300 / ~1000 sizing bands โ no second set of numbers: ~100 is quick's recommended domain, ~300 is default's upper bound (above = large โ deep), ~1000 keeps its too-large meaning. Quick's typical lower band ~100 is operational guidance, not a separate trigger โ small real-code PRs near that boundary still default to `default` to preserve evidence depth.
|
|
51
|
+
|
|
52
|
+
**Conflict rule**: at most **one** tier keyword may be given. Any two of `quick` / `default` / `deep` appearing together โ **hard-stop conflict error** โ report the conflict and ask the user to pick one; never silently take a priority. Explicit `quick` on a security-sensitive surface is respected (trust + transparency), but the seat must still run its in-domain security lens and the report must declare `- notes:` "quick tier โ reduced coverage on a security-sensitive surface".
|
|
53
|
+
|
|
54
|
+
**Cuttable vs never-cut**:
|
|
55
|
+
- **Cuttable by tier**: seat count, stage-as-wave (Stage 1 as a separate wave), domain-split granularity, the independent security seat, the lens set, the seat-prompt ingredient set.
|
|
56
|
+
- **Never cut (any tier)**: the verdict-from-tally formula (one formula, all tiers), merge-class assignment + three-way vet, posting ownership (sole main agent), evidence discipline (`file:line` + self-check), Hard Rules 4/5, seats read-only, worktree isolation, the batch contract (first-only + backlog register), the local report archive contract incl. frontmatter, linked-issue AC counting.
|
|
57
|
+
- **Stage 3 is never skipped in any tier** โ `quick` just feeds it the smallest input; one verdict / one Review / main-agent posting is the product contract.
|
|
58
|
+
|
|
59
|
+
**Report `tier` declaration**: report frontmatter gains an optional `tier: quick | default | deep` (absent = `default` semantics, valid โ old reports stay valid). `quick` MUST declare its reduced coverage under `- notes:` (what did not run: independent security seat / Stage 1 wave / domain split); any announced upgrade or downgrade (e.g. PM announces deep-upgrade, or a downgraded cut happens) is declared the same way. Report template structure, tally counts, and the display contract are unchanged; tier never enters the report filename.
|
|
60
|
+
|
|
61
|
+
## Worktree isolation
|
|
62
|
+
- All git mechanics โ real-base resolution (never assume `main`), collision-free branch naming (`pr-<n>` โ `pr-<n>-<date>-<i>` loop before **any** fetch), explicit-refspec fetches (single-branch/narrowed fetch configs stay correct; do **not** substitute `gh pr checkout <n>` โ it lands on the PR-head name instead of the recorded branch, bypassing the ownership protocol), worktree creation, changeset pre-flight (untracked-only working-tree changes count as non-empty), diff-basis computation, sidecar recording, removal + prune + exact-branch deletion โ execute mechanically:
|
|
63
|
+
|
|
64
|
+
> **Engine check (when available):** run `mstar pr-review worktree-setup --pr <n> | --branch <b> | --diff | --working-tree | --commit <sha> [--path <dir>]` (or `import { pickReviewBranchName, preflightChangeset } from "@mstar-harness/engine"` in a host hook) to create the isolated review worktree (default location `<repo>/.worktrees/review-โฆ` per the mstar-branch-worktree convention, override with `--path <dir>`), compute the diff basis inside it, record a sidecar json, and print `{reviewBranch, worktreePath, base, mergeBase, diffCmd, diffFile}` โ `diffFile` is the pinned diff snapshot written beside the sidecar at `<parent-of-worktree>/.<wt-dirname>.prreview.diff` (`null` for `--diff` / `--working-tree` modes, which write no snapshot); clean up with `mstar pr-review worktree-cleanup --path <dir> --branch <name> --report-saved` โ removes the tree, prunes, deletes **exactly** the recorded branch (a foreign/unrecorded branch is refused), removes the snapshot file, and refuses removal while the local report is unsaved. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
65
|
+
|
|
66
|
+
The diff snapshot is a review artifact beside the sidecar (`.โนwt-dirnameโบ.prreview.diff` in the worktree's parent dir): setup writes it, cleanup removes it together with the worktree + sidecar, and a failed setup's rollback removes it too โ it is never an orphan. Ownership is fd-bound identity: setup records the snapshot's `dev`/`ino`/`mtime` in the sidecar, and cleanup opens the path, verifies the open fd against the recorded identity, and unlinks only after a rename proves the fd's inode is the one it verified โ a replaced file (even with identical bytes, or with a reused inode number on ext4) or a sidecar without the recorded identity is left in place with a note; a replacement swapped in mid-cleanup is restored via hard link โ never overwriting a concurrent occupant of the path (EEXIST leaves both files in place, nothing deleted). An interrupted setup (sidecar written, snapshot never recorded) is refused by the next `worktree-setup` with a cleanup hint โ the operator runs `mstar pr-review worktree-cleanup --path <dir> --branch <name|""> --report-saved` to remove the stale sidecar, then retries. Its range semantics: `## Commits` is the two-dot `base..head` form (commits reachable from head but not base), while `## Files changed` / `## Diff` use the three-dot merge-base pair โ the same split the seat reads.
|
|
67
|
+
|
|
68
|
+
Discipline that stays with the agent (behavior, not git mechanics):
|
|
69
|
+
|
|
70
|
+
- Review from a dedicated linked worktree โ **never the primary repo cwd, never another harness worktree** โ and compute the diff basis inside it against the recorded refs, three-dot style: **never the primary `HEAD`** (the primary checkout may sit on a different branch).
|
|
71
|
+
- Input-mode shape: bare branch reviews use a detached worktree against the fetched remote-tracking ref (no local ownership protocol, no local branch to delete); arbitrary-diff inputs verify stated provenance and read changed files locally โ no worktree, no branch, nothing to clean up; working-tree inputs take tracked + staged + untracked changes read in full (the review stays read-only โ no fixes, no stash; `comments: n/a-no-pr`); single-commit inputs verify provenance but read file context **at that commit** (`git show <sha>:<path>`), which diverges from the current checkout whenever HEAD โ `<sha>` or the file changed since.
|
|
72
|
+
- **Pre-flight before fanning out lenses** (every mode): named refs resolve (in modes that have refs) and the changeset is non-empty โ an empty changeset reports "no changes to review" and stops; never spawn lenses on an empty changeset.
|
|
73
|
+
- Record before computing: review cwd, `<review-branch>`, HEAD sha, merge-base.
|
|
74
|
+
- Clean up **once the local report is saved** โ the save runs in all three posting branches (`posted: yes` / `n/a-no-pr` / `failed`; ยง Local report archive), so cleanup never waits on POST success โ then delete **exactly** the recorded `<review-branch>` (provably this review's own branch); never delete a pre-existing branch. Never remove other harness worktrees.
|
|
75
|
+
|
|
76
|
+
## Scoping
|
|
77
|
+
|
|
78
|
+
- Review the diff basis vs base: changed files plus what the change touches.
|
|
79
|
+
- Read changed files **in full** โ diffs hide context.
|
|
80
|
+
- Inspect adjacent behavior when risk leaks past the named diff (importers, callers, dependent contracts).
|
|
81
|
+
- When the diff touches tests, read the tests before the implementation โ they carry intent.
|
|
82
|
+
- Verification claims in the PR description must be reproducible from the diff/CI; a claim that cannot be checked is an `unverified` lead, not evidence.
|
|
83
|
+
- **Domains** โ review is split by domain (**business domain / change surface / tech stack**; ยง Review pipeline). Each domain seat concludes **only on its own domain**.
|
|
84
|
+
- Cross-domain boundary issues (importers / callers reaching outside the seat's domain) โ record to the evidence file `- notes:`; the main agent decides whether an additional cross-domain seat is warranted.
|
|
85
|
+
|
|
86
|
+
## Sizing & change shape
|
|
87
|
+
|
|
88
|
+
- **Sizing bands:** ~100 changed lines โ reviewable; ~300 โ acceptable as one logical change; ~1000 โ too large โ advise a split (a `should-fix` finding with split advice, or a verdict note; never auto-`blocked`). Whole-file deletions and mechanical/automated refactors are exempt โ verify intent, not every line.
|
|
89
|
+
- **File-size watch:** a small diff that materially grows a file past ~1000 *total* lines โ advise extract/decompose first ("decompose, then add").
|
|
90
|
+
- **Split strategies:** stack ยท by file group ยท horizontal (shared code first) ยท vertical (full-stack slices); refactoring and feature work travel in separate changes.
|
|
91
|
+
- **Escalation by change shape:**
|
|
92
|
+
|
|
93
|
+
| Shape | Action |
|
|
94
|
+
| --- | --- |
|
|
95
|
+
| Database schema change | widen scrutiny |
|
|
96
|
+
| API contract change | widen scrutiny |
|
|
97
|
+
| New framework/library adoption | widen scrutiny |
|
|
98
|
+
| Performance-critical path | widen scrutiny โ playbook ยง3 Performance depth |
|
|
99
|
+
| Security-sensitive surface | widen scrutiny โ load `references/security-review.md` |
|
|
100
|
+
|
|
101
|
+
> **Engine check (when available):** run `mstar pr-review size --base <ref> --head <ref>` (or `import { prReviewSizing, resolvePrReviewTier } from "@mstar-harness/engine"` in a host hook) to classify the changeset into the bands above โ it prints the band, the inferred tier, the Stage-1 seat plan, split advice and the file-size watch, so band and fan-out decisions are never hand-derived. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
102
|
+
|
|
103
|
+
These shapes get deeper review, not automatic severity โ name the escalation in the review body.
|
|
104
|
+
|
|
105
|
+
## Concern lenses
|
|
106
|
+
|
|
107
|
+
Generic lenses:
|
|
108
|
+
|
|
109
|
+
- `general` โ repo guidance compliance, bugs, security, awkward complexity. Ignore lint-covered cosmetics.
|
|
110
|
+
- `technical-coverage` โ behavior coverage, real-surface proof, mock-heavy seams. Ignore blanket coverage demands.
|
|
111
|
+
- `silent-failures` โ swallowed errors, misleading fallbacks, unclassified failures, lossy logging.
|
|
112
|
+
|
|
113
|
+
Conditional lenses:
|
|
114
|
+
|
|
115
|
+
- `types` โ invariants, escape hatches (`any` / `as` / `unknown`), schema drift, parse-don't-validate. Apply when types carry meaning (API / data layer / migration).
|
|
116
|
+
- `cleanup` โ dead code, duplicate logic, indirection without value. Apply for refactors and added-then-removed surfaces.
|
|
117
|
+
- `comments` โ comment rot, docstring truthfulness. Apply when docs changed.
|
|
118
|
+
|
|
119
|
+
**Smell baseline** (under `general`): twelve labelled smells โ one line each, what it is โ remedy direction:
|
|
120
|
+
|
|
121
|
+
- Mysterious Name โ unclear what it does/why โ rename to intent.
|
|
122
|
+
- Duplicated Code โ same shape in โฅ2 places โ extract the shared form.
|
|
123
|
+
- Feature Envy โ method works mostly on another class's data โ move it there.
|
|
124
|
+
- Data Clumps โ same field groups travel together โ promote to a single object.
|
|
125
|
+
- Primitive Obsession โ domain concepts as bare primitives โ introduce a type.
|
|
126
|
+
- Repeated Switches โ same condition re-branched โ replace with a dispatcher.
|
|
127
|
+
- Shotgun Surgery โ one logical change touches many files โ consolidate the coupling.
|
|
128
|
+
- Divergent Change โ one class changes for many reasons โ split by reason.
|
|
129
|
+
- Speculative Generality โ flexibility nothing uses โ delete it.
|
|
130
|
+
- Message Chains โ callers wade through a.getB().getC() โ hide the walk behind one method.
|
|
131
|
+
- Middle Man โ class mostly delegates โ fold or inline the pass-through.
|
|
132
|
+
- Refused Bequest โ subclass inherits more than it wants โ replace with composition.
|
|
133
|
+
|
|
134
|
+
Three binding rules: repo-documented standards override the baseline โ a standards finding cites the standard's file + rule; anything tooling already enforces is skipped (existing `general` rule); smells are judgement calls โ a smell alone is never `must-fix`, and a LOW-confidence smell without evidence is not a finding (existing disqualify rule): it goes on `- unverified:` per the ยง Merge class rule, never `nit`; an **evidenced** judgement-call smell may surface as `nit` with the smell label. No new lens row: repo-guidance conformance stays the `general` lens's job.
|
|
135
|
+
|
|
136
|
+
**Selection by change shape** (UI / API / migration / refactor / doc / tiny mechanical). Default set = `general` + `technical-coverage` + `silent-failures`. Never spawn all lenses blindly; tiny mechanical diffs โ `general` only.
|
|
137
|
+
|
|
138
|
+
## Evidence rules
|
|
139
|
+
|
|
140
|
+
- Static findings cite exact file references (`path/file.ts:123`).
|
|
141
|
+
- Run the **smallest runtime check that changes the verdict** (targeted command, not the full suite).
|
|
142
|
+
- Mark unverified explicitly โ a claim without verification is a lead, not a finding.
|
|
143
|
+
- Mock-heavy tests around risky behavior = a finding (no real-surface proof), not proof of correctness.
|
|
144
|
+
- A "doesn't follow repo conventions / should use an existing abstraction" finding must cite the exemplar the diff should have followed (`file:line`); the simplest acceptable implementation is not a style finding (lint-covered cosmetics are already ignored by the `general` lens).
|
|
145
|
+
- **Scout / collector evidence = leads** โ collect-seat evidence files and unchecked domain-seat notes are **leads, not findings**; a domain seat's Stage 2 output **after it opened the cited code itself** (`file:line`) is a formal finding, and the main agent (Stage 3) may still reject it during vet. A finding that cites a collector's relay without its own self-check is disqualified (same discipline as full-audit "excerpts come from your own reads").
|
|
146
|
+
- What disqualifies a finding (no evidence, by-design, secret values, ungrounded suggestions) โ **`references/finding-format.md`** ยง What disqualifies a finding.
|
|
147
|
+
|
|
148
|
+
## Attack and vet
|
|
149
|
+
|
|
150
|
+
Before writing a finding, run the three-way attack from `mstar-audit`:
|
|
151
|
+
|
|
152
|
+
1. **Counter-example** โ find a boundary case that makes the claim not hold.
|
|
153
|
+
2. **Simpler explanation** โ does a simpler explanation cover the same evidence?
|
|
154
|
+
3. **Evidence verifiability** โ open the cited lines and check they actually support the claim.
|
|
155
|
+
|
|
156
|
+
Each **domain seat** runs the three-way attack on its own findings, opens the cited code itself, and disposes by-design / mis-attributed / duplicate before presenting.
|
|
157
|
+
|
|
158
|
+
The **main agent** is the final vet layer: at synthesis it dedupes **all** findings across domains (cross-domain duplicates, mis-attribution), applies the same by-design / duplicate disposition with the `cited code yourself` discipline, and records every rejection in the report's **Considered & rejected** section. Subagents over-report; vet before presenting.
|
|
159
|
+
|
|
160
|
+
## Verdict synthesis
|
|
161
|
+
|
|
162
|
+
- Order findings by impact-if-shipped; no padding, no invented requirements, no style grading.
|
|
163
|
+
- List **every** accepted finding โ `must-fix`, `should-fix`, and nits alike; nothing is truncated.
|
|
164
|
+
- The verdict is **derived from the tally, not chosen**: classify every accepted finding (ยง Merge class) โ apply leftover `unmet` AC increments if any (ยง Linked-issue hygiene) โ apply **Verdict-from-tally** (ยง Tally and derived score) โ emit that one token. The reviewer does not pick a verdict by vibe.
|
|
165
|
+
- Exactly one verdict:
|
|
166
|
+
- `ship it` โ evidence-backed, safe to ship.
|
|
167
|
+
- `needs fixes` โ issues found; address before merge.
|
|
168
|
+
- `blocked` โ a must-fix issue stands in the way of shipping.
|
|
169
|
+
|
|
170
|
+
## Merge class (PR findings only)
|
|
171
|
+
|
|
172
|
+
Classify each **accepted** finding (after three-way vet) as exactly one class. Do not invent a fourth class. Do not derive class from `Confidence`.
|
|
173
|
+
|
|
174
|
+
| Class | Use when | Verdict effect |
|
|
175
|
+
| --- | --- | --- |
|
|
176
|
+
| `must-fix` | Shipping this issue is unsafe: correctness bug, security hole, data loss, auth/authz bypass, or a broken public contract. Same meaning as today's `blocked` gloss ("a must-fix issue stands in the way of shipping"). | Any count โฅ 1 โ `blocked` |
|
|
177
|
+
| `should-fix` | A real issue that should be addressed before merge but is not itself a ship-stopper. Same meaning as today's middle gloss ("issues found; address before merge"). | Else if count โฅ 1 โ `needs fixes` |
|
|
178
|
+
| `nit` | Optional cleanup, naming, comment, or small suggestion that does **not** change merge-readiness. Lint-covered cosmetics stay ignored (existing lens rule) โ they are not findings. | Does not change verdict |
|
|
179
|
+
|
|
180
|
+
Tie-break: unsafe to ship โ `must-fix`; should be addressed before merge but ship-safe โ `should-fix`; otherwise `nit`. A LOW-confidence smell that fails evidence rules is **not** a finding (existing disqualify rules) โ put it on `- unverified:` if it must be mentioned.
|
|
181
|
+
|
|
182
|
+
Presumptive-structural classes: a refactor that relocates complexity instead of reducing it ยท a change pushing a file past the size boundary with no decomposition ยท feature logic added to a shared module ยท a near-duplicate of an existing canonical helper ยท a silent fallback hiding an unclear invariant โ default `should-fix`; downgrade to `nit` only with a stated reason; never `must-fix` on shape alone without correctness/security evidence.
|
|
183
|
+
|
|
184
|
+
Field placement: on each finding, `- **Merge class**: must-fix | should-fix | nit`, immediately after `Confidence` (before `Fix sketch`). The shared finding template (`references/finding-format.md`) is unchanged โ this field is PR-review-only.
|
|
185
|
+
|
|
186
|
+
> **Engine check (when available):** run `mstar lint <file.md>` with `--type finding` (add `--pr-variant` for the PR Merge-class contract) โ or `import { validateFindingDoc } from "@mstar-harness/engine"` in a host hook โ to machine-check a findings document: `### [CATEGORY-NN]` numbering, category / effort / risk / confidence enums, evidence `path:line` shape, and the Merge-class presence/enum/placement rule. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
187
|
+
|
|
188
|
+
## Tally and derived score
|
|
189
|
+
|
|
190
|
+
Verbatim, applied after the three-way vet to **accepted** findings, then leftover unmet ACs:
|
|
191
|
+
|
|
192
|
+
```
|
|
193
|
+
must_fix = count of accepted findings with Merge class: must-fix
|
|
194
|
+
should_fix = count of accepted findings with Merge class: should-fix
|
|
195
|
+
nit = count of accepted findings with Merge class: nit
|
|
196
|
+
unverified = count of residual items under `- unverified:` (0 when `none`)
|
|
197
|
+
|
|
198
|
+
# leftover unmet ACs (ยง Linked-issue hygiene) โ tally increment, not a fourth class, not a second finding:
|
|
199
|
+
for each leftover AC marked unmet (not met, not cut):
|
|
200
|
+
if that leftover is itself unsafe-to-ship / a broken public contract:
|
|
201
|
+
must_fix += 1
|
|
202
|
+
else:
|
|
203
|
+
should_fix += 1
|
|
204
|
+
|
|
205
|
+
if must_fix >= 1:
|
|
206
|
+
verdict = blocked
|
|
207
|
+
else if should_fix >= 1:
|
|
208
|
+
verdict = needs fixes
|
|
209
|
+
else:
|
|
210
|
+
verdict = ship it
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
`score_pct` โ integer arithmetic only. Floor at 0. No decimals. No second formula:
|
|
214
|
+
|
|
215
|
+
```
|
|
216
|
+
score_pct = max(0, 100 - 40*must_fix - 15*should_fix - 3*nit - 10*unverified)
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### Override invariant
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
Score never overrides verdict.
|
|
223
|
+
blocked + any score_pct โ not shippable
|
|
224
|
+
needs fixes + any score_pct โ still address findings before merge
|
|
225
|
+
ship it + score_pct < 100 โ allowed (nits and/or unverified deducted)
|
|
226
|
+
High score_pct never means APPROVE. Low score_pct never means REQUEST_CHANGES.
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
> **Engine check (when available):** the invariant is enforced structurally โ `computePrTally` derives the verdict from the tally before the score is computed, and `mstar pr-review validate-report` flags a `verdict` that does not follow from the report's own tally (`prreview.report.verdict-mismatch`, severity high). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
230
|
+
|
|
231
|
+
### Worked examples (check table)
|
|
232
|
+
|
|
233
|
+
| must / should / nit / unverified | score_pct | verdict | Display line |
|
|
234
|
+
| --- | --- | --- | --- |
|
|
235
|
+
| 0 / 0 / 0 / 0 + 1 leftover unmet AC | 85 | `needs fixes` | `needs fixes ยท 85%` |
|
|
236
|
+
| 0 / 0 / 0 / 0 + 1 leftover unmet AC (unsafe-to-ship) | 60 | `blocked` | `blocked ยท 60%` |
|
|
237
|
+
| 0 / 0 / 2 / 0 | 94 | `ship it` | `ship it ยท 94%` |
|
|
238
|
+
| 0 / 0 / 0 / 2 | 80 | `ship it` | `ship it ยท 80%` |
|
|
239
|
+
| 0 / 1 / 0 / 0 | 85 | `needs fixes` | `needs fixes ยท 85%` |
|
|
240
|
+
| 0 / 1 / 1 / 0 | 82 | `needs fixes` | `needs fixes ยท 82%` |
|
|
241
|
+
| 1 / 0 / 0 / 0 | 60 | `blocked` | `blocked ยท 60%` |
|
|
242
|
+
| 1 / 2 / 1 / 1 | 17 | `blocked` | `blocked ยท 17%` |
|
|
243
|
+
| 3 / 0 / 0 / 0 | 0 (floor) | `blocked` | `blocked ยท 0%` |
|
|
244
|
+
|
|
245
|
+
`blocked ยท 60%` is still not shippable. `needs fixes ยท 85%` still means address findings. This table is mirrored row-for-row as the engine test fixture (`packages/engine/test/prreview.test.ts`) โ the table text is kept here as the historical SSOT anchor.
|
|
246
|
+
|
|
247
|
+
> **Engine check (when available):** run `mstar pr-review tally --findings <file.json> [--unverified <n>] [--unmet-ac-unsafe <n>] [--unmet-ac-safe <n>]` (or `import { computePrTally } from "@mstar-harness/engine"` in a host hook) to compute this tally, verdict and score from the accepted findings JSON โ the check table above is the SSOT the engine fixture mirrors (`packages/engine/test/prreview.test.ts`); never hand-compute when the CLI is available. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
248
|
+
|
|
249
|
+
## Originating spec discovery
|
|
250
|
+
|
|
251
|
+
Find the originating spec โ the acceptance criteria live there, not in the diff:
|
|
252
|
+
|
|
253
|
+
- Issue references in the PR body / commit messages (`#123`, `Closes`, `Fixes`).
|
|
254
|
+
- A spec path the user named in the request.
|
|
255
|
+
- Repo candidates: `{SPECS_DIR}`, `docs/specs` / ADR directories, `STRATEGY.md` / `PRODUCT.md`, roadmap.
|
|
256
|
+
- None โ ask the user once; still none โ note "no spec available", score nothing, never invent requirements (existing rule).
|
|
257
|
+
|
|
258
|
+
## Linked-issue hygiene
|
|
259
|
+
|
|
260
|
+
When an originating spec exists (ยง Originating spec discovery โ a tracked issue, spec file, or ADR), score **every** acceptance criterion against the diff:
|
|
261
|
+
|
|
262
|
+
- Mark each: met / unmet / cut.
|
|
263
|
+
|
|
264
|
+
Leftover `unmet` criteria count against the verdict: they are **tally increments**, not extra findings (do not also emit a Merge-class finding for the same leftover โ that would double-count). Each leftover AC marked `unmet` (not `met`, not `cut`) increments `should_fix` by 1, or `must_fix` by 1 when that leftover is itself a broken public contract / unsafe-to-ship. The increment lives in the tally procedure (ยง Tally and derived score); apply Verdict-from-tally **after** it, so leftover `unmet` ACs cannot yield `ship it`. Score uses the existing formula only (`should_fix` deducts 15, `must_fix` deducts 40 โ no second formula, no new tally key). Leftovers are already mentioned in the review `body` (ยง Comment posting) โ no fourth merge class.
|
|
265
|
+
- Do not invent a follow-up when all criteria landed.
|
|
266
|
+
|
|
267
|
+
## CI attribution
|
|
268
|
+
|
|
269
|
+
Check base-vs-branch before blaming the diff for CI failures. A red build that predates the branch is not a finding against the PR.
|
|
270
|
+
|
|
271
|
+
## Comment triage
|
|
272
|
+
|
|
273
|
+
- Judge the validity of bot/peer review comments before acting on them.
|
|
274
|
+
- **Comment-triage replies are the main agent's job at Stage 3** โ seats never post or reply. For valid comments, the main agent folds the minimal fix suggestion into the finding/plan (plan output) for the Prepare โ Execute flow. For invalid comments, the main agent disagrees on the PR comment with clear reasoning. Never gold-plate.
|
|
275
|
+
|
|
276
|
+
## Batch sibling PRs
|
|
277
|
+
|
|
278
|
+
- **one session = one PR** (HARD): an `amazing-pr-review` session reviews exactly **one** PR. When multiple PRs are passed in, only the **first** โ the first PR in the caller's argument / mention order, never sorted by PR number or recency โ runs the review at its resolved tier (ยง Review depth (tiers) for tier resolution โ ยง Review pipeline for stage steps; `deep` = the full three-stage pipeline); the rest are **not** processed in this session.
|
|
279
|
+
- **Register the rest as audit todos** โ before the review starts, register every unprocessed PR in `{PROJECT_DIR}/<project-id>/residuals.json` (project-less reviews use `_default`) via the engine-backed CLI, one `--entry` per deferred PR:
|
|
280
|
+
```
|
|
281
|
+
mstar status backlog-register --project <project-id> --key <plan-key> --entry '<entry json>' ...
|
|
282
|
+
```
|
|
283
|
+
- `--project` defaults to `_default`; `--key` is the **base** batch key, `pr-deep-review-<YYYY-MM-DD>` for the first same-day session โ the CLI selects the first free same-day key (`pr-deep-review-<YYYY-MM-DD>`, then `-2`, `-3`, โฆ) inside the engine's status write lock and prints the key actually used; never compute the bumped key yourself.
|
|
284
|
+
- Each `--entry` is a JSON object with the nine residual fields for one deferred PR: `id` (unique within the batch, e.g. `pr-deep-review-<YYYY-MM-DD>-<n>`), `title: "pr-deep-review <owner>/<repo>#<n>"`, `severity: low`, `source: pr-deep-review batch input`, `scope: "deep review of <owner>/<repo>#<n> in a new amazing-pr-review session"`, `decision: defer`, `owner: project-manager`, `target: next session`, `tracking: pr-deep-review backlog`. The CLI fills the provenance fields (`source_plan` = the used key, `registered_at` = today).
|
|
285
|
+
- Entry-id uniqueness is **enforced in code** (B-9 โก): the engine rejects a duplicate `id` within the key โ fail-loud, register unchanged โ so ids only need to stay distinct within the batch.
|
|
286
|
+
- `<n>` is the GitHub PR number; `title`/`scope` carry the recoverable PR identity (`<owner>/<repo>#<n>` or the PR URL) so a later session can open the exact deferred PR from the register alone.
|
|
287
|
+
- **Concurrency/crash safety is engine-tested** (`packages/engine/test/backlog-register.test.ts`): registration runs inside `withStatusWriteLock` with atomic temp+rename writes โ never hand-edit the register with python/jq.
|
|
288
|
+
- Lock-semantics delta vs. the old hand-rolled protocol: `withStatusWriteLock` has **no stale-lockdir auto-reclamation** โ a crash-leaked lockdir โ 30s timeout โ `Blocked` with the `holder.pid` recovery hint (remove the lockdir only when no writer is alive).
|
|
289
|
+
- **Registration failure halts the session**: if the CLI exits non-zero (fail-loud validation, register unchanged), stop and report `Blocked` โ never start the first-PR review while deferred PRs are unregistered (they would be neither reviewed nor tracked).
|
|
290
|
+
- **Backlog close**: when a session completes review of a PR that was previously deferred โ at its resolved tier (`quick` / `default` / `deep` per ยง Review depth), it MUST look up the matching register entry (`tracking: pr-deep-review backlog`, identity `<owner>/<repo>#<n>` in `title`/`scope`) and close it in place at review completion:
|
|
291
|
+
```
|
|
292
|
+
mstar status backlog-close --project <project-id> --key <used-key> --id <entry-id>
|
|
293
|
+
```
|
|
294
|
+
(`--project` defaults to `_default`; `--key` is the key the entry was registered under โ the one `backlog-register` printed; `--id` is the entry id; `--note` is optional, default `"closed by backlog close"`) โ sets `lifecycle: resolved` + `closed_at: <YYYY-MM-DD>` + `closure_note` (no `closed` enum), per the register lifecycle contract in `mstar-project-governance`; never leave a stale open entry for a reviewed PR.
|
|
295
|
+
- **Suggest one session per PR**: the report's `- notes:` states that each remaining PR gets its own `amazing-pr-review` session and is tracked in the `_default` residuals backlog (`tracking: pr-deep-review backlog`).
|
|
296
|
+
- **Concurrency stays inside the single PR**: for the one PR under review, create the worktree first, then fan out per the resolved tier's seat plan (ยง Review depth (tiers)) โ `deep` fans out the Stage 1 collect seats in one batch (ยง Review pipeline); `default` folds collection into the two domain seats; `quick` is a single pass. Deferred PRs get **no** review worktree and **no** review seats โ backlog registration only. The old "all worktrees first, all reviewers in one batch" model no longer applies to N PRs.
|
|
297
|
+
- Sibling interactions are **noted, not fixed** โ interactions with deferred sibling PRs go to the report's `- notes:`, unless the ticket says so.
|
|
298
|
+
|
|
299
|
+
## Plan output๏ผhandoff to execution๏ผ
|
|
300
|
+
|
|
301
|
+
Review findings that need fixing can become plans for the normal Prepare โ Execute flow โ same contract as **`mstar-audit` SKILL.md** `## Plan output (all variants)`:
|
|
302
|
+
|
|
303
|
+
- Write the top findings as self-contained plans (numbered `001-<slug>.md` + `README.md` index โ top findings only; the verdict is presented separately).
|
|
304
|
+
- The review itself stays read-only: plans are written only when the user selects findings to pursue.
|
|
305
|
+
|
|
306
|
+
## Comment posting
|
|
307
|
+
|
|
308
|
+
Posting the GitHub Review is a **mandatory deliverable** of the `pr` variant โ chat-only output is incomplete when a PR exists. The main agent (the command's orchestrator) posts the review; review seats never post โ posting is Stage 3 only, by the main agent, and the seat-level carve-out is gone โ Audit Mode, Hard Rule 2, and Mode C are aligned.
|
|
309
|
+
|
|
310
|
+
- **Before anything else:** synthesize the verdict first, then post **before** worktree cleanup (see ยง Worktree isolation โ cleanup happens after the local report is saved).
|
|
311
|
+
- **No PR number** (bare branch / arbitrary diff): set `comments: n/a-no-pr` and skip the API. Chat output still required; this is not a Blocked review.
|
|
312
|
+
- **Auth / API failure:** deliver the chat verdict anyway; Completion Report status `Partial`/`Blocked` with the `gh` error. Do not claim `Done` โ comments are mandatory when a PR exists. **The local report is still saved** (ยง Local report archive โ posting failure does not skip archival).
|
|
313
|
+
|
|
314
|
+
### Procedure
|
|
315
|
+
|
|
316
|
+
Executed by the main agent at Stage 3 โ review seats never run this procedure. The following are the binding contracts, independent of who executes:
|
|
317
|
+
|
|
318
|
+
1. **Target resolution** โ the **base** repo is `owner/repo` parsed from the PR `url` (`https://github.com/{owner}/{repo}/pull/{n}`); `commit_id` is `headRefOid`. **Never** derive the repo from `headRepository` (the fork view) โ Reviews API paths are scoped to the repository that owns the PR number.
|
|
319
|
+
2. **Payload** โ `event` is the fixed literal `COMMENT` (**never** `APPROVE`, **never** `REQUEST_CHANGES`, never a merge โ the engine's literal type admits no other value); `body` follows **ยง Report template (below)**; `comments[]`: one entry per finding whose `path` + `line` sits in the three-dot diff, `side: RIGHT` โ finding body = title + evidence + impact + fix sketch, not the whole plan.
|
|
320
|
+
3. **Line fallback** โ if GitHub rejects some inline comments (e.g. 422 โ line outside the diff), retry the review **once**, without exactly the rejected entries and with them folded into the summary body; never loop a second time.
|
|
321
|
+
4. **Save the local report (ยง Local report archive) โ mandatory in all three branches**: POST succeeded (record `html_url` / review id for `comments:` first), POST failed, or `n/a-no-pr` (archive the chat display content). Only then clean up the worktree (ยง Worktree isolation); bare branch/diff reviews have no worktree, but the save still happens.
|
|
322
|
+
|
|
323
|
+
> **Engine check (when available):** run `mstar pr-review post --pr <n> --body-file <path> [--findings <file.json>]` (or `import { planReviewPost } from "@mstar-harness/engine"` in a host hook) to execute these contracts mechanically โ url-based repo resolution, the `COMMENT` literal, payload POST via stdin, and the at-most-once 422 fallback printing `review_url`; auth/API failure exits 1 (`comments: failed`). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
324
|
+
|
|
325
|
+
### Report template (GitHub Review `body`)
|
|
326
|
+
|
|
327
|
+
The posted review body is a three-section report. Section order fixed; omit a subsection only when its content is genuinely empty (write `none`, never delete the heading). The block below shows only **fill-in slots**: a `<...>` that wraps descriptive text (`<verdict>`, `<n>`, `<finding title>`, โฆ) is a slot โ replace the whole bracket pair with real content and never render those brackets. The literal HTML tags in the template (`<details>`, `<summary>`, `<br>`) are **structural** โ keep them verbatim so the collapsible block survives. The Slot rules below the template are guidance โ never copy them into the posted body.
|
|
328
|
+
|
|
329
|
+
**Section emoji map** โ verdict: `ship it` โ
ยท `needs fixes` โ ๏ธ ยท `blocked` โ. Finding classes: ๐ด must-fix ยท ๐ should-fix ยท ๐ต nit ยท โ unverified.
|
|
330
|
+
|
|
331
|
+
````markdown
|
|
332
|
+
## <verdict-emoji> Verdict: `<verdict>` ยท Confidence <score_pct>%
|
|
333
|
+
|
|
334
|
+
| Findings | Count |
|
|
335
|
+
| --- | --- |
|
|
336
|
+
| ๐ด must-fix | <n> |
|
|
337
|
+
| ๐ should-fix | <n> |
|
|
338
|
+
| ๐ต nit | <n> |
|
|
339
|
+
| โ unverified | <n> |
|
|
340
|
+
|
|
341
|
+
## ๐ Review
|
|
342
|
+
|
|
343
|
+
**What this PR does**: <2โ3 sentence summary of the diff's intent and surface>
|
|
344
|
+
|
|
345
|
+
### Findings
|
|
346
|
+
|
|
347
|
+
#### <class-emoji> <finding title>
|
|
348
|
+
|
|
349
|
+
- **Evidence**: `file:line` โ what the code does
|
|
350
|
+
- **Impact**: why it matters
|
|
351
|
+
- **Merge class**: must-fix | should-fix | nit
|
|
352
|
+
- **Confidence**: HIGH | MEDIUM | LOW
|
|
353
|
+
- **Fix sketch**: one-line suggestion
|
|
354
|
+
|
|
355
|
+
### Linked-issue AC
|
|
356
|
+
|
|
357
|
+
<per-criterion: met / unmet / cut โ one-line reasoning, or `none`>
|
|
358
|
+
|
|
359
|
+
### โ
Verified
|
|
360
|
+
|
|
361
|
+
- <check or command> โ <what it showed>
|
|
362
|
+
- โ <unverified lead, if any>
|
|
363
|
+
|
|
364
|
+
### ๐๏ธ Considered & rejected
|
|
365
|
+
|
|
366
|
+
- **<short finding title>**: rejected โ <one-line reason>
|
|
367
|
+
|
|
368
|
+
## ๐ ๏ธ Plan to fix
|
|
369
|
+
|
|
370
|
+
<details><summary>Expand fix plan</summary>
|
|
371
|
+
<br>
|
|
372
|
+
|
|
373
|
+
```md
|
|
374
|
+
<fix plan in markdown>
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
</details>
|
|
378
|
+
````
|
|
379
|
+
|
|
380
|
+
**Slot rules (guidance โ not part of the posted body):**
|
|
381
|
+
|
|
382
|
+
- **What this PR does**: from the PR description plus your own read of the changed files, not copied marketing text.
|
|
383
|
+
- **Findings**: ranked by impact-if-shipped (ยง Verdict synthesis); every accepted finding listed, nothing truncated; repeat the `#### <class-emoji> <title>` block per finding.
|
|
384
|
+
- **Linked-issue AC**: fill only when ยง Linked-issue hygiene applied; otherwise a bare `none`.
|
|
385
|
+
- **Verified**: the smallest runtime checks actually run and what they showed; unverified leads as `โ` lines here, never in the findings table.
|
|
386
|
+
- **Considered & rejected**: one bullet per rejected candidate from the three-way attack / vet pass (ยง Attack and vet), so the next reviewer does not re-chase it; bare `none` when nothing was rejected.
|
|
387
|
+
- **Plan to fix**: fix plan in markdown (ordered steps per finding, files touched, verification gates); follow-up plan index folds in above the ```md block (ยง Folding plans); when there is no fix plan, replace the whole `<details>` block with a single line `none`.
|
|
388
|
+
|
|
389
|
+
- The Verdict section replaces the old two-line tally header on GitHub: same facts (verdict token + `score_pct` as Confidence + four-class tally), structured. The chat display contract (ยง Display contract) is unchanged.
|
|
390
|
+
- When the fix plan itself contains fenced code blocks, open the outer fence with four backticks so the inner fences survive.
|
|
391
|
+
|
|
392
|
+
### Folding plans into the summary
|
|
393
|
+
|
|
394
|
+
Fold follow-up plans into the review body **only if** this review wrote them. Put a short index โ title, priority, effort, 1โ3 sentence sketch, plan path โ as the first content inside the ยง Report template **Plan to fix** `<details>` block, before the ```md fix-plan block:
|
|
395
|
+
|
|
396
|
+
```
|
|
397
|
+
- <plan title> โ P1 / S โ <1โ3 sentence sketch> (`{PLAN_DIR}/audit-<date>/NNN-<slug>.md`)
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
Never dump full plan files.
|
|
401
|
+
|
|
402
|
+
### Local report archive
|
|
403
|
+
|
|
404
|
+
The posted PR comment is the deliverable; the local report is the durable reference copy โ the PR thread may be buried, locked, or deleted, and bare-branch/diff reviews have no thread at all. The main agent saves **one markdown file per reviewed PR** (or branch/diff) at Stage 3 โ the report it published โ as part of the mandatory deliverable, before worktree cleanup:
|
|
405
|
+
|
|
406
|
+
- **Path**: `{PROJECT_DIR}/<project-id>/reports/pr-review/` โ `<project-id>` from the Assignment / project context, `_default` when the review runs outside any project flow (same id convention as `projects/<id>/residuals.json`). Gitignored local SSOT, same posture as residuals; a finding that must survive across clones gets promoted to tracked `{KNOWLEDGE_DIR}` / `{SPECS_DIR}`, not by tracking this directory.
|
|
407
|
+
- **Write via the primary checkout, never the worktree**: harness discovery must not start from the review worktree โ its root has no gitignored `.mstar/`, and anything written there is destroyed by `git worktree remove` (ยง Worktree isolation). Record the primary repository's absolute path **before** creating the worktree and write the report under it. Never create a `.mstar/` inside the review worktree to "host" the report.
|
|
408
|
+
- **Filename**: `<YYYY-MM-DD>-pr<N>.md`; bare branch โ `<YYYY-MM-DD>-<branch-slug>.md`; arbitrary diff โ `<YYYY-MM-DD>-diff-<short-head-sha>.md`, or `<YYYY-MM-DD>-diff.md` when no head SHA was provided with the changeset (never invent one). Same target twice in one day โ append `-r2`, `-r3`, โฆ (never overwrite a prior report).
|
|
409
|
+
- **Evidence files**: the **main agent** writes each seat's (Stage 1 / Stage 2) evidence file in the same `reports/pr-review/` directory โ `<YYYY-MM-DD>-pr<N>-stage1-<slug>.md` (Stage 1) / `<YYYY-MM-DD>-pr<N>-stage2-<slug>.md` (Stage 2 findings draft). Seats return evidence / findings in their result payload (contract โ `references/pr-review-seat-evidence.md` โ any seat may be **write-blocked**; seats are **never required to write**). Writable seats may **best-effort** write their evidence file directly; the contract does not depend on it. The **main agent writes / consolidates all evidence files** from the seat payloads. `<slug>` is **domain-derived and unique per seat** โ `<domain>-<seat>` โ and is mandated in the seat Assignment, so two seats in the same pipeline can never collide. Bare branch / diff mirror the main-report forms: `<YYYY-MM-DD>-<branch-slug>-stage{1,2}-<slug>.md`, `<YYYY-MM-DD>-diff-<short-head-sha>-stage{1,2}-<slug>.md`, or `-diff-` alone when no head SHA was provided (never invent one). Same target re-reviewed twice in one day โ append `-r2`, `-r3`, โฆ (never overwrite a prior evidence file). Same gitignored directory and same **write via primary checkout, never the worktree** discipline applies (an evidence file written in the review worktree is destroyed by `git worktree remove`, ยง Worktree isolation).
|
|
410
|
+
- **Frontmatter** (machine-readable metadata):
|
|
411
|
+
```yaml
|
|
412
|
+
---
|
|
413
|
+
type: pr-review
|
|
414
|
+
tier: quick | default | deep # optional โ absent = default semantics (ยง Review depth)
|
|
415
|
+
pr: <n> # omit for bare branch / diff
|
|
416
|
+
url: <pr url> # omit for bare branch / diff
|
|
417
|
+
head: <head sha>
|
|
418
|
+
base: <base ref>
|
|
419
|
+
verdict: ship it | needs fixes | blocked
|
|
420
|
+
score_pct: <n>
|
|
421
|
+
tally: { must-fix: <n>, should-fix: <n>, nit: <n>, unverified: <n> }
|
|
422
|
+
comments: posted | n/a-no-pr | failed # posting tri-state โ never collapse failed into n/a-no-pr ("yes" = posted alias)
|
|
423
|
+
review_url: <posted review html_url> # n/a-no-pr when skipped; failed: <gh error summary> when POST failed
|
|
424
|
+
generated_at: <YYYY-MM-DD>
|
|
425
|
+
pipeline: {stages: 3, seats: [<seat ids>]} # optional โ omit when the review did not run the three-stage pipeline
|
|
426
|
+
---
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
`head:` / `base:` are omitted when genuinely unknown (arbitrary diff without stated provenance) โ never fabricate identifiers.
|
|
430
|
+
|
|
431
|
+
**Posting failure does not skip archival.** The report is saved regardless of the POST outcome: on failure it archives the chat display content plus the `gh` error summary, so a failed POST still leaves the durable copy.
|
|
432
|
+
|
|
433
|
+
> **Engine check (when available):** run `mstar pr-review report-path --reports-dir <dir> --target pr:<n>|branch:<slug>|diff:<sha>|diff [--stage 1|2 --slug <domain-seat>] [--date <YYYY-MM-DD>]` (or `import { prReviewReportPath } from "@mstar-harness/engine"` in a host hook) to resolve the Filename / Evidence-file names above โ including the same-day `-r2`/`-r3` escalation, which the resolver scans for instead of the agent eyeballing the directory. Pure resolution: it never writes; the main agent still writes the file content. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
434
|
+
- **Body**: the exact text posted as the GitHub Review body โ verbatim, not a paraphrase. When `comments: n/a-no-pr` or posting failed, the body is the chat display content instead (ยง Display contract two lines + ranked findings + leftover AC), so the local copy is still complete.
|
|
435
|
+
- Fix plans referenced by the Plan-to-fix section keep living in `{PLAN_DIR}/audit-<date>/` when written โ the report links them, never duplicates them.
|
|
436
|
+
|
|
437
|
+
## Output shape
|
|
438
|
+
|
|
439
|
+
- `- findings:` โ list of evidence-backed findings (`none` when none). Each accepted finding includes **Merge class** (ยง Merge class).
|
|
440
|
+
- `- verdict:` โ exactly one of `ship it` / `needs fixes` / `blocked` (ยง Verdict synthesis).
|
|
441
|
+
- `- score_pct:` โ integer 0โ100 from the locked formula (ยง Tally and derived score).
|
|
442
|
+
- `- tally:`
|
|
443
|
+
- `- must-fix: <n>`
|
|
444
|
+
- `- should-fix: <n>`
|
|
445
|
+
- `- nit: <n>`
|
|
446
|
+
- `- unverified: <n>`
|
|
447
|
+
- `- evidence:` โ concise what-checks-proved summary.
|
|
448
|
+
- `- unverified:` โ residual unverified claims, or `none`.
|
|
449
|
+
- `- next:` โ one of `implementation` / `verify` / `docs`.
|
|
450
|
+
- `- notes:` โ only out-of-scope state the user must act on.
|
|
451
|
+
- `- comments:` โ GitHub Review posting status (see ยง Comment posting):
|
|
452
|
+
- `posted: yes` | `n/a-no-pr` | `failed` โ these three are distinct; a failed POST is **`failed`**, never `n/a-no-pr`
|
|
453
|
+
- `review_url: <url>` when `posted: yes`; `n/a` when `n/a-no-pr` or `failed`
|
|
454
|
+
- `inline: <N> posted / <M> attempted (<K> summary-only fallback)`
|
|
455
|
+
- `plans_folded: yes` | `no`
|
|
456
|
+
|
|
457
|
+
- `- report:` โ local archive path (ยง Local report archive), e.g. `{PROJECT_DIR}/<project-id>/reports/pr-review/2026-08-24-pr134.md` (`_default` when project-less); `n/a` only when the harness dir is undiscoverable.
|
|
458
|
+
|
|
459
|
+
> **Engine check (when available):** run `mstar pr-review validate-report <file.md>` (or `import { validatePrReviewReport } from "@mstar-harness/engine"` in a host hook) to machine-check a saved local report against the Frontmatter + Output-shape contract above โ verdict-from-tally consistency, the locked-formula `score_pct` recompute, the comments tri-state (a failed POST is `failed`, never `n/a-no-pr`), the required-field set (`type`, `verdict`, `score_pct`, `tally`, `comments`, `review_url`, `generated_at`) and `generated_at` format. Exit 1 with violations; run it before worktree cleanup. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
|
|
460
|
+
|
|
461
|
+
### Display contract (chat output)
|
|
462
|
+
|
|
463
|
+
Tone: matter-of-fact โ no praise-padding, no flattery; state each severity together with the conditions that enable it.
|
|
464
|
+
|
|
465
|
+
First two lines of the **chat** display โ verbatim:
|
|
466
|
+
|
|
467
|
+
```
|
|
468
|
+
{verdict} ยท {score_pct}%
|
|
469
|
+
must-fix=<n> should-fix=<n> nit=<n> unverified=<n>
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
Then ranked findings / leftover AC summary. Do not put `score_pct%` on the `- verdict:` token line.
|
|
473
|
+
|
|
474
|
+
The GitHub Review `body` no longer uses the two-line header โ it follows ยง Report template, whose Verdict section carries the same facts structured (verdict token + Confidence + four-class emoji tally table).
|
|
475
|
+
|