chore(review): repo-owned Greptile policy and merge-policy documentation for integrations

[qmarcelle]

Closes the policy half of META-322. Calibration evidence follows on a separate disposable canary PR; this PR does not change branch protection.

What this is

workspacejson/integrations has had no repository-owned review policy, so reviewer behavior here has never been governed by this repository's own failure classes. This adds:

Path	Purpose
.greptile/config.json	14 structured rules, scoped and severity-tagged
.greptile/rules.md	prose reasoning, the verified failure class behind each rule, and the rules deliberately not carried over
.greptile/files.json	orientation files the reviewer reads first
.sourcery.yaml	path scoping only — no semantic authority
docs/review/merge-policy.md	measured merge eligibility, reviewer roles, conversation-resolution protocol
docs/review/calibration-2026-08.md	the calibration evidence record (results section is explicitly not yet measured)
config/repository-structure.json	allowlist entries for the two new root paths

Rules are derived, not copied

Every Integrations-specific rule names a surface or defect in this repository:

• proven-root-path-identity, ported-copies-must-not-diverge — META-291 / PR fix(path-identity): resolve absolute queries against a proven root, drop suffix fallback #8 removed a suffix fallback that matched a stored src/a.ts against /elsewhere/unrelated-repo/src/a.ts. src/path-match.ts records that a second, drifted matcher is how a deny silently became a warn. extension/src/pathMatch.ts is still a hand-synced port with no build-time import.
• unavailable-is-not-approval — hooks/pre-edit-check.mjs routes every failure through emitUnavailable; its no-history branch exits silently "never an approval message". src/reviewer.ts keeps UNAVAILABLE distinct from PASS. The smoke suite exercises malformed, wrong-shaped, and missing artifacts.
• reader-tolerance-is-not-repair — normalizeWorkspace degrades to empty and never fabricates; no read path anywhere holds a write to the artifact.
• packed-artifact-must-be-measured — dist/ is gitignored but shipped, and the hook resolves ../dist/* at runtime, so source-only tests do not prove what a consumer receives.
• probes-must-not-be-destructive — META-285 records --help running a destructive install into the source repo; the surrounding installer surface genuinely installs, uninstalls, and removes a managed root.
• host-contract-claims-need-a-watched-version — the Codex output contract is recorded as watched on 0.144.1 (2026-07-13), with emitDecision() as the single adapter point.
• Plus clean-room-public-boundary, consume-standard-do-not-vendor, and the four ecosystem evidence rules.

Not carried over, with reasons recorded in .greptile/rules.md: standard's four-stable-read-paths rule (this repository consumes them, it does not own them), single-defect negative fixtures (no such corpus here), derived-probability emission (no producer here), and CLI producer/commit-history rules (no equivalent verified failure mode).

Sourcery

Stays defense-in-depth. .sourcery.yaml is ignore paths only and grants no rule authority; a success Sourcery check is explicitly not evidence of semantic approval.

Evidence

config/repository-structure.json enforces a root allowlist as part of the required build-and-smoke contexts. Watched red before the amendment, on this exact tree:

$ node scripts/check-repo-structure.mjs
  - Unexpected root directory: .greptile/ ...
  - Unexpected root file: .sourcery.yaml ...
2 violation(s). EXIT=1

then green after. The checker script itself is untouched — the policy file documents that adding an entry there is the sanctioned path.

Local gates on this head: 147/147 vitest tests across 14/14 files, 43 PASS / 0 FAIL smoke, structure + generator-version + typecheck + lint + build all pass.

Scope

No product behavior change. No published package bytes, exports, files, bin, or metadata change — and this repository has no .changeset/, so no changeset applies. scripts/migration/** is untouched (META-285 owns it) and docs/migration/** is untouched (PR #6 owns it).

Summary by Sourcery

Add repository-owned semantic review policy and merge-contract documentation for workspacejson/integrations, including configuration of automated reviewers and alignment of repo structure allowlists.

Enhancements:

• Introduce Greptile review rules and configuration as a repo-owned semantic policy for this integration.
• Document measured merge eligibility, reviewer roles, and conversation-resolution protocol for merges into main.
• Add a calibration record outlining the protocol and evidence requirements for making Greptile Review a required merge gate.
• Configure Sourcery as a scoped, defense-in-depth reviewer without semantic authority.
• Update repository structure allowlist to account for new policy and configuration directories.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[sourcery-ai]

Reviewer's Guide

Introduces repo-owned semantic review policy and merge-policy documentation for workspacejson/integrations, wires them into Greptile/Sourcery config, and updates the repository-structure allowlist so the new root-level policy directories are treated as first-class, without changing product behavior or CI logic.

File-Level Changes

Change	Details	Files
Add explicit, evidence-backed Greptile review rules and orientation config for this repository.	Create .greptile/rules.md documenting verified failure classes, integrator-specific rules, and rules deliberately not carried over from other repos. Add .greptile/config.json defining 14 structured review rules with scopes and severities. Add .greptile/files.json listing orientation files to bias reviewer attention on first read.	.greptile/rules.md .greptile/config.json .greptile/files.json
Document repository-owned merge policy and Greptile calibration protocol, focusing on measured branch protection and reviewer roles.	Add docs/review/merge-policy.md describing current branch protection settings, required checks, reviewer authority boundaries, and conditions for making Greptile a required gate. Add docs/review/calibration-2026-08.md capturing baseline measurements and the planned canary protocol to test Greptile behavior on a known defect. Clarify that current CI required contexts remain unchanged and that calibration, not installation, governs future branch-protection changes.	docs/review/merge-policy.md docs/review/calibration-2026-08.md
Configure Sourcery as a scoped, non-authoritative secondary review layer and align repository-structure allowlist with new policy paths.	Introduce .sourcery.yaml that scopes Sourcery to exclude build output and vendored trees while explicitly denying it semantic rule authority. Update config/repository-structure.json to allow .greptile/ and .sourcery.yaml as valid repository root entries so structure checks pass with the new policy files.	.sourcery.yaml config/repository-structure.json

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• The rule scopes described in .greptile/rules.md (e.g., for path-match, reader tolerance, host adaptation) should be checked against .greptile/config.json to ensure the structured rule targeting matches the prose and doesn’t drift over time.
• Since docs/review/merge-policy.md encodes specific branch protection and required check settings read from the GitHub API, consider adding an explicit note or lightweight process hook for updating this document when those settings change so it doesn’t become misleading or stale.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The rule scopes described in `.greptile/rules.md` (e.g., for `path-match`, `reader tolerance`, host adaptation) should be checked against `.greptile/config.json` to ensure the structured rule targeting matches the prose and doesn’t drift over time.
- Since `docs/review/merge-policy.md` encodes specific branch protection and required check settings read from the GitHub API, consider adding an explicit note or lightweight process hook for updating this document when those settings change so it doesn’t become misleading or stale.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[greptile-apps]

Greptile Summary

This PR establishes repository-owned semantic review policy and documents the measured calibration and merge-eligibility contract for workspacejson/integrations.

• Adds scoped Greptile rules, reviewer orientation metadata, and defense-in-depth Sourcery exclusions.
• Records the completed canary calibration, including current-head behavior and the limits of successful check states and conversation resolution.
• Documents reviewer roles and current branch-protection requirements without changing branch protection.
• Extends the repository-structure allowlist for the new root-level policy configuration.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
.greptile/config.json	Adds fourteen structured, repository-specific review rules with explicit scopes and severity metadata.
.greptile/rules.md	Documents the repository-specific failure classes, rule rationale, ownership boundaries, and deliberately omitted rules.
docs/review/calibration-2026-08.md	Records measured canary results and correctly distinguishes existing matcher coverage from a test suite excluded from deterministic gates.
docs/review/merge-policy.md	Defines measured merge eligibility, reviewer authority, conversation-reconciliation requirements, and the limits of review check states.
config/repository-structure.json	Allows the new .greptile directory and .sourcery.yaml file through the existing root-structure check.

_{Reviews (2): Last reviewed commit: "docs(review): record calibration results..." | Re-trigger Greptile}

[qmarcelle]

Reconciling Sourcery finding 1 of 2 — rule-scope drift between rules.md and config.json

Audited rather than assumed. All nine scoped rules match exactly today, and the five ecosystem-wide rules correctly carry neither a scope key nor a Scope: line:

Rule id	config.json scope	rules.md Scope:
consume-standard-do-not-vendor	src/**, extension/src/**, hooks/**, scripts/**	identical
reader-tolerance-is-not-repair	src/services/**, src/tools/**, src/evidence.ts, hooks/**, extension/src/**	identical
proven-root-path-identity	src/path-match.ts, src/services/**, src/tools/**, src/evidence.ts, extension/src/pathMatch.ts, extension/src/**, hooks/**	identical
ported-copies-must-not-diverge	src/path-match.ts, extension/src/pathMatch.ts, src/**, extension/src/**	identical
unavailable-is-not-approval	hooks/**, src/reviewer.ts, src/tools/**, src/services/**, src/evidence.ts, extension/src/reviewerVerdict.ts, extension/src/**	identical
host-adaptation-stays-descriptive	src/**, extension/src/**, hooks/**, docs/**, README.md	identical
packed-artifact-must-be-measured	package.json, extension/package.json, scripts/install.mjs, hooks/**, .github/workflows/**, tests/**	identical
probes-must-not-be-destructive	scripts/**, hooks/**, .github/workflows/**	identical
host-contract-claims-need-a-watched-version	hooks/**, scripts/install.mjs, extension/src/**, src/index.ts, docs/**	identical

So this is a drift risk over time, not a present defect — worth being precise about, since "should be checked" and "is wrong" are different claims.

Applied: rules.md now states that config.json is authoritative for scope, that the prose restates it and can drift, and which file is the one to correct when they disagree. That gives a drift a defined resolution direction instead of a stalemate.

Deliberately not applied: an executable parity check between the two files. It would be the stronger fix and it is the honest reading of this repository's own evidence must be load-bearing rule — but it adds test machinery outside META-322's declared write-set, and a check that parses prose to compare against JSON has its own vacuity risk. Recorded as a named follow-up rather than smuggled in here; scoping it is the owner's call, not this PR's.

[qmarcelle]

Reconciling Sourcery finding 2 of 2 — merge-policy.md encodes settings that can drift

Accepted. The branch-protection and required-check tables are transcriptions of live GitHub state that can be changed from outside this repository, which makes them the most perishable content in the document — and a stale merge-eligibility claim is worse than no claim, because it will be believed.

Applied in docs/review/merge-policy.md §2, a "Refreshing this section" block that:

• gives the two exact commands that re-derive the tables (gh api .../branches/main/protection, .../rulesets);
• states the precedence explicitly — if the API disagrees, the API is right and the document is the defect;
• makes correcting it the job of the PR that notices the drift;
• stamps the measurement date and the commit it was read against (2026-08-12, main @ a31242b).

A process hook stronger than that — a scheduled job asserting protection settings against the document — was considered and not added: it would be new CI surface outside this issue's write-set, and this document's whole posture is that a required check should be introduced only after its behavior has been measured, which applies to a check that guards this file too.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud