Merge remote-tracking branch 'origin/next' into docs/1216-trunk-parameterization
This commit is contained in:
fred
@@ -16,8 +16,91 @@ Merge strategy enforcement (HARD RULE):
|
||||
- Merge to the integration trunk MUST be squash-only.
|
||||
- Use `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}` (or PowerShell equivalent).
|
||||
|
||||
An estate MAY carry a documented exception for a repository whose gates are commit hooks rather
|
||||
than review. Such an exception belongs in that estate's own working copy of this guide, is
|
||||
scoped to the named repository, and is never precedent for a second one.
|
||||
|
||||
**Do not use `pr-review.sh` or `issue-comment.sh` to post a verdict** (mosaicstack#1280). Post
|
||||
through a direct authenticated API call as your own seat, or hand the verdict to the requesting
|
||||
seat. Handing it over is a legitimate delivery path, not a fallback.
|
||||
|
||||
## Evidence Discipline (applies to every finding)
|
||||
|
||||
The checklist below says what to look at. This section says when you are allowed to believe what
|
||||
you saw. Every rule here was earned by a wrong conclusion that reached a report.
|
||||
|
||||
1. **A finding is a claim about behavior.** State the failing input, the path taken, and the
|
||||
wrong result. "This looks fragile" is not a finding.
|
||||
2. **A green check is not a result until you have shown it could go red.** Run the control. A
|
||||
`0`, an empty result, or a column of identical values with no failing counterpart is a
|
||||
non-result.
|
||||
3. **Measurement and explanation are separate sentences.** Report the command and its output,
|
||||
then, as its own sentence, what you think it means.
|
||||
4. **Never widen the case you measured.** If you checked one path, the finding covers one path.
|
||||
5. **Reproduce a reported failure before recording it, and say which tree you measured.** Two
|
||||
correct measurements of two different trees disagree without either being wrong.
|
||||
6. **Verify by content on the ref that ships**, never by ancestry of a local sha. A rebase mints
|
||||
new shas; a commit being an ancestor of something local proves nothing about the remote.
|
||||
Compare by digest against `origin/<branch>`.
|
||||
7. **Confidence is part of the finding.** "I could not reproduce this" is a usable review
|
||||
comment. A confident guess is not.
|
||||
8. **Author is not reviewer** (Gate-16). Do not review your own work, or work you shaped closely
|
||||
enough to be a co-author of. Say so and hand it back.
|
||||
|
||||
### Measuring a shell suite
|
||||
|
||||
Each of these produced a wrong conclusion before it was written down.
|
||||
|
||||
9. **`cmd | tail; echo rc=$?` reports `tail`'s exit code, not `cmd`'s.** It reads as a pass when
|
||||
the command failed. Redirect to a file and check `rc` directly, or use `${PIPESTATUS[0]}`.
|
||||
10. **Under `set -o pipefail`, a missed glob makes `ls` exit 2**, the pipeline inherits it, and
|
||||
`set -e` kills the run. Iterate a glob with a `for` loop and an `-e` test instead of piping
|
||||
`ls`.
|
||||
11. **A suite that exits nonzero with ZERO output is an environment question, not a defect in
|
||||
the code under review.** The usual cause is a sourced dependency that is absent, so `set -e`
|
||||
kills the first case before anything prints. Extract whole tool trees — `tools/git` alone is
|
||||
missing `tools/_lib/credentials.sh`. Isolate the variable and prove it by adding only that
|
||||
back.
|
||||
12. **`git -C <dir>` in a directory that is not itself a repo answers from the enclosing repo.**
|
||||
A scratch tree under `~/.mosaic` reports `~/.mosaic`'s HEAD, not the PR's, and every
|
||||
conclusion drawn from it describes the wrong tree. Confirm `git rev-parse --show-toplevel`
|
||||
is the tree you think it is before trusting any git output.
|
||||
|
||||
13. **Run the repository's PINNED tool version.** `npx <tool>` resolves a local `node_modules`
|
||||
install when one is present and fetches the latest release when one is not, so the same
|
||||
command answers differently depending on where it ran. A reviewer measuring in a fresh clone
|
||||
or a detached worktree — which is exactly where reviewers measure — has no `node_modules` and
|
||||
silently gets the latest release instead of the pinned one. Measured on mosaicstack#1313: the
|
||||
lockfile pins prettier 3.8.1, under which three guides pass; a version-less `npx` in a
|
||||
worktree resolved 3.9.6, under which the same three fail; and 3.0.0, the floor of the declared
|
||||
`^3.0.0` range, fails a different one. Three versions, three verdicts, identical bytes. Use
|
||||
`node_modules/.bin/<tool>`, or name the version the lockfile pins.
|
||||
14. **A formatter or linter declared as a range is a dated verdict, not a fact.** If a lockfile
|
||||
pins it, the gate is reproducible today and will disagree with itself the day the pin moves.
|
||||
Report a formatting failure with the version that produced it, always.
|
||||
|
||||
### Feedback Categories
|
||||
|
||||
- **Blocker**: must fix before merge (security, bugs, test failures)
|
||||
- **Should Fix**: important but not blocking (code quality, minor issues)
|
||||
- **Suggestion**: optional improvement (style preference, nice-to-have)
|
||||
- **Question**: seeking clarification
|
||||
|
||||
## Review Checklist
|
||||
|
||||
Reviewer seats split this checklist by class rather than duplicating it. A seat reviews its own
|
||||
sections in full and may raise anything it notices outside them as a Suggestion, never as a
|
||||
Blocker on someone else's ground.
|
||||
|
||||
| Reviewer class | Owns |
|
||||
| ---------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| `rev-code-*` | 1 Correctness, 3 Testing, 4 Code Quality, 4a TypeScript, 5 Documentation, 6 Performance, 7 Dependencies |
|
||||
| `rev-security-*` | 2 Security, 2a OWASP |
|
||||
|
||||
Where two seats of the same class review the same change, they review independently and compare
|
||||
after. A second seat that reads the first seat's findings before measuring is a proofreader, not
|
||||
a second opinion.
|
||||
|
||||
### 1. Correctness
|
||||
|
||||
- [ ] Code does what the issue/PR description says
|
||||
@@ -54,7 +137,7 @@ Merge strategy enforcement (HARD RULE):
|
||||
- [ ] Tests cover happy path AND error cases
|
||||
- [ ] Situational tests cover all impacted change surfaces (primary gate)
|
||||
- [ ] Tests validate required behavior/outcomes, not only internal implementation details
|
||||
- [ ] TDD was applied when required by `~/.config/mosaic/guides/QA-TESTING.md`
|
||||
- [ ] TDD was applied when required by `guides/QA-TESTING.md`
|
||||
- [ ] Coverage meets 85% minimum
|
||||
- [ ] Tests are readable and maintainable
|
||||
- [ ] No flaky tests introduced
|
||||
@@ -83,7 +166,7 @@ Merge strategy enforcement (HARD RULE):
|
||||
### 5. Documentation
|
||||
|
||||
- [ ] Complex logic has explanatory comments
|
||||
- [ ] Required docs updated per `~/.config/mosaic/guides/DOCUMENTATION.md`
|
||||
- [ ] Required docs updated per `guides/DOCUMENTATION.md`
|
||||
- [ ] Public APIs are documented
|
||||
- [ ] Private/internal APIs are documented
|
||||
- [ ] API input/output schemas are documented
|
||||
@@ -127,13 +210,6 @@ git diff {integration_trunk}...HEAD
|
||||
- Distinguish between blocking issues and suggestions
|
||||
- Be constructive, not critical of the person
|
||||
|
||||
### Feedback Categories
|
||||
|
||||
- **Blocker**: Must fix before merge (security, bugs, test failures)
|
||||
- **Should Fix**: Important but not blocking (code quality, minor issues)
|
||||
- **Suggestion**: Optional improvements (style preferences, nice-to-haves)
|
||||
- **Question**: Seeking clarification
|
||||
|
||||
### Review Comment Format
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user