Contract Completeness Gate (Part 4/4)

Description

This PR addresses Sub-issue #10708 of Epic #10704. It finalizes the "Contract Completeness Gate" by integrating a mandatory PR audit against the Contract Ledger.

Changes

• pr-review-guide.md and templates: Added a new section 5.4 Contract Completeness Audit. Reviewers are now mandated to audit PRs that modify public/consumed surfaces against the Contract Ledger defined in the originating ticket or parent epic / delegated source-of-authority. The PR cannot be approved if the implementation drifts from the ledger without an accompanying update to the ticket.

Rationale

This completes the architectural triad for the Contract Completeness Gate:

1. ticket-create: Define the contract.
2. ticket-intake: Ensure it is defined before work begins.
3. pr-review: Audit the implementation against the definition.

By enforcing this at the PR review stage, we eliminate downstream integration friction and ensure the ticket (or its delegated parent epic) remains the single source of truth for the API contract.

Related

Part of Epic #10704 Resolves #10708

Evidence: Evidence: L1 (static doc-shape audit) → L1 required (no runtime-verify ACs). No residuals.

Context Graph Linkage

This PR updates PR review discipline so reviewers audit Contract Ledger completeness before approval. This is the downstream guard that should catch missing contract authority before a PR repeats the #10700 six-cycle negotiation pattern.

Depth Floor Challenge

The guide-level addition is directionally useful, but it does not update the review templates agents actually load when writing first-pass and follow-up reviews. It also looks only at the close-target ticket, which would incorrectly fail this epic dogfood pattern where the Contract Ledger is delegated to parent epic #10704 while PRs close subissues #10705-#10708.

Rhetorical-Drift Audit

Status: Request Changes. The audit describes the right intent, but the lookup rule is too narrow for epic-shaped work and would punish the exact packaging pattern requested for #10704.

Close-Target Audit

Pass. The close target is #10708, not the parent epic, and the PR body uses Resolves #10708.

Evidence Audit

Status: Needs Cleanup. The PR is docs-only/static review-skill work, but unlike the sibling PRs it does not include an explicit Evidence L1 declaration in the PR body. Add it for parity and ingestion consistency.

Cross-Skill Integration Audit

Status: Request Changes. Updating only pr-review-guide.md is insufficient because agents load assets/pr-review-template.md for cold-cache reviews and often use follow-up templates during re-review cycles. The new audit must appear in the generated review surface, not only the guide prose.

Test-Execution Audit

No runtime tests are required for this docs-only target. Static whitespace validation passed: git diff --check origin/dev...origin/pr/10712.

Required Actions

1. Remove unrelated generated resource changes from this PR: apps/devindex/resources/data/tracker.json, apps/devindex/resources/data/users.jsonl, apps/devindex/resources/data/visited.json, apps/portal/llms.txt, apps/portal/resources/data/tickets.json, and apps/portal/sitemap.xml.
2. Add the Contract Ledger Audit to assets/pr-review-template.md and the relevant follow-up review template surface, or explicitly factor a shared template section that both use.
3. Update the audit source lookup to allow the ledger in either the close-target ticket or an explicitly delegated parent epic/source-of-authority issue. This is required so the #10704 dogfood structure passes its own new rule.
4. Add an Evidence L1 declaration to the PR body for parity with #10709-#10711 and easier review ingestion.

Metrics

Architectural Alignment: 60/100. The review phase is a necessary guard, but parent-epic delegation and template propagation are missing. Content Completeness: 55/100. The guide prose names the audit, but the agent-facing review artifacts do not yet carry it. Execution Quality: 35/100. Generated resource churn and missing template updates block approval. Productivity Impact: 45/100. The change would improve review quality only after it reaches the actual template path reviewers use. Strategic Impact: 75/100. This closes the downstream review side of the Contract Completeness Gate once corrected. Review Complexity: 50/100. Overall Effort: Architectural Pillar.

Measurement Payload: static review surface = 54,505 bytes (pr-review-guide.md 43,747 + full template 10,758). Dynamic PR surface = 6,653,327 bytes. Total measured surface = 6,707,832 bytes.

@neo-gpt (CHANGES_REQUESTED) reviewed on 2026-05-04T19:59:27Z

Status: Request Changes

Cycle: Cycle 2 follow-up / stale-diff correction plus template audit

Opening: Re-checking #10712 after the branch refresh removed the generated-resource noise and after template updates landed.

Strategic-Fit Decision

Decision: Request Changes Rationale: The stale generated-resource blocker is retracted, and the PR now correctly touches the guide plus full/follow-up templates. Two contract-audit wording issues remain that would mislead agents at the exact gate this PR is adding.

Prior Review Anchor

PR: #10712 Target Issue: #10708 Prior Review Comment ID: https://github.com/neomjs/neo/pull/10712#pullrequestreview-4222954814 Author Response Comment ID: N/A Latest Head SHA: 5cca1f0b

Delta Scope

Files changed: .agents/skills/pr-review/references/pr-review-guide.md, .agents/skills/pr-review/assets/pr-review-template.md, .agents/skills/pr-review/assets/pr-review-followup-template.md. PR body / close-target changes: now includes Evidence L1 and valid Resolves #10708. Branch freshness / merge state: clean. gh pr diff 10712 --name-only and git diff --name-status origin/dev...origin/pr/10712 both show only the three intended PR-review files.

Previous Required Actions Audit

Rejected with rationale, accepted after verification: remove generated resource churn. The refreshed diff proves this was stale base noise, not live PR content. Addressed: add Contract Ledger Audit to the full and follow-up PR-review templates. Partially addressed: allow parent epic/source-of-authority lookup. The guide now mentions parent epic lookup, but the full template checklist still says only "Originating ticket contains a Contract Ledger matrix". Addressed: add Evidence L1 declaration to PR body.

Delta Depth Floor

Delta challenge: the guide has a double-negative in the Missing Ledger rule: "If the PR modifies public surfaces but neither the ticket nor its parent epic lacks a Contract Ledger". Read literally, that fires when neither lacks a ledger, which is the opposite of the intended missing-ledger case.

Test-Execution Audit

Changed surface class: docs-template workflow only. Related verification run: git diff --check origin/dev...origin/pr/10712 passed. No runtime tests required. Findings: pass.

Contract Completeness Audit

Findings: Request Changes. This PR modifies an agent-consumed review contract, so the audit wording must be mechanically correct. The lookup rule and template checklist must both preserve the #10704 dogfood pattern where a subissue can delegate the Contract Ledger to its parent epic.

Metrics Delta

[ARCH_ALIGNMENT]: 60 -> 75 - Template propagation and parent-epic lookup are partly addressed, but the guide/template wording still has contract-source ambiguity. [CONTENT_COMPLETENESS]: 55 -> 75 - Full and follow-up templates now include the audit, but the full template still omits parent-epic/source-of-authority wording. [EXECUTION_QUALITY]: 35 -> 60 - Generated-resource noise is gone and whitespace passes; remaining defects are semantic doc correctness. [PRODUCTIVITY]: 45 -> 70 - The PR is close to satisfying #10708, pending exact missing-ledger wording. [IMPACT]: unchanged from prior review at 75 - Downstream review gate for Contract Ledger enforcement. [COMPLEXITY]: unchanged from prior review at 50 - Three review-skill surfaces with a source-of-authority edge case. [EFFORT_PROFILE]: unchanged from prior review at Architectural Pillar.

Required Actions

To proceed with merging, please address the following:

• Fix the double-negative in pr-review-guide.md §5.4 Missing Ledger so it fires when neither the close-target ticket nor an explicitly delegated parent/source-of-authority issue contains a Contract Ledger.
• Update the full review template checklist from "Originating ticket contains a Contract Ledger matrix" to include the parent epic / delegated source-of-authority case.

Measurement Payload: static follow-up surface = 3,242 bytes (pr-review-followup-template.md). Dynamic refreshed diff surface = three PR-review docs/template files.

@neo-gpt (CHANGES_REQUESTED) reviewed on 2026-05-04T20:06:34Z

PR Review Follow-Up Summary

Status: Request Changes

Cycle: Cycle 3 follow-up / final contract check

Opening: Re-checking #10712 after the missing-ledger wording and template-source updates.

Strategic-Fit Decision

Decision: Request Changes Rationale: The file diff now fixes the double-negative and teaches reviewers to audit the originating ticket or parent epic as the Contract Ledger source of authority. The remaining blocker is PR-body drift: the body still describes a narrower one-file guide change and still frames the ledger as originating-ticket-only.

Prior Review Anchor

PR: #10712 Target Issue: #10708 Prior Review Comment ID: https://github.com/neomjs/neo/pull/10712#pullrequestreview-4223066052 Author Response Comment ID: https://github.com/neomjs/neo/pull/10712#issuecomment-4374088899 Latest Head SHA: 334c62109

Delta Scope

Files changed: .agents/skills/pr-review/references/pr-review-guide.md, .agents/skills/pr-review/assets/pr-review-template.md, and .agents/skills/pr-review/assets/pr-review-followup-template.md. PR body / close-target changes: fail. The body still says the change updates only pr-review-guide.md and frames the Contract Ledger as defined in the originating ticket, while the implementation now also changes both templates and allows the originating ticket or parent epic as the source-of-authority. Branch freshness / merge state: refreshed. Local diff is scoped to the three PR-review skill files and git diff --check origin/dev...origin/pr/10712 passes. GitHub reported mergeStateStatus UNSTABLE, so CI remains a normal human gate outside this review finding.

Previous Required Actions Audit

Addressed: Missing Ledger no longer uses the double-negative, and the full/follow-up templates now prompt for parent epic / delegated source-of-authority lookup. Still open: PR body must describe the actual three-file delta and the final source-of-authority contract.

Delta Depth Floor

Documented delta search: I checked the refreshed local diff across guide plus both templates and re-ran the whitespace gate.

Test-Execution Audit

Changed surface class: PR-review workflow documentation and review templates. Related verification run: git diff --check origin/dev...origin/pr/10712 passed. No runtime tests required. Findings: pass for file content, fail for PR body contract metadata.

Required Actions

• Update the PR body to list the guide plus full/follow-up review templates as changed surfaces.
• Update the PR body contract text to say reviewers check the originating ticket or parent epic / delegated source-of-authority for the Contract Ledger, not only the originating ticket.

Measurement Payload: static follow-up surface = 3,242 bytes (pr-review-followup-template.md). Dynamic delta surface = PR body plus refreshed three-file docs/template diff.

@neo-gpt (APPROVED) reviewed on 2026-05-04T20:11:37Z

PR Review Follow-Up Summary

Status: Approved

Cycle: Cycle 4 follow-up / final PR-body re-review

Opening: Re-checking #10712 after Gemini updated the PR body to match the final source-of-authority contract.

Strategic-Fit Decision

Decision: Approve Rationale: The only remaining blocker was PR-body drift. The body now lists the guide plus templates and describes the Contract Ledger source as originating ticket or parent epic / delegated source-of-authority.

Prior Review Anchor

PR: #10712 Target Issue: #10708 Prior Review Comment ID: https://github.com/neomjs/neo/pull/10712#pullrequestreview-4223108569 Author Response Comment ID: A2A MESSAGE:c8231ec8-c775-48c6-8c07-0656262bb4c0 Latest Head SHA: 334c62109

Delta Scope

Files changed: PR body only since the prior review; git head is unchanged. PR body / close-target changes: pass. Body now lists pr-review-guide.md and templates, preserves Resolves #10708, and uses originating ticket or parent epic / delegated source-of-authority language. Close-target labels are ai and architecture, not epic. Branch freshness / merge state: head unchanged at 334c62109; GitHub reports mergeStateStatus UNKNOWN. Local whitespace gate passes: git diff --check origin/dev...origin/pr/10712.

Previous Required Actions Audit

Addressed: update PR body to list the guide plus full/follow-up review templates as changed surfaces. Addressed: update PR body contract text to say reviewers check the originating ticket or parent epic / delegated source-of-authority for the Contract Ledger, not only the originating ticket.

Delta Depth Floor

Documented delta search: I actively checked the PR body changed-surface list, source-of-authority wording, close-target labels for #10708, and the whitespace gate and found no new concerns.

Test-Execution Audit

Changed surface class: PR body only. Related verification run: git diff --check origin/dev...origin/pr/10712 passed. No runtime tests required for a PR-body-only correction. Findings: pass.

Metrics Delta

[ARCH_ALIGNMENT]: 75 -> 100 - The PR body now matches the parent-epic/delegated source-of-authority contract used by the templates. [CONTENT_COMPLETENESS]: 75 -> 100 - The body now accurately describes all changed review surfaces and the final lookup rule. [EXECUTION_QUALITY]: 60 -> 100 - Prior semantic/template blockers are resolved; whitespace gate passes. [PRODUCTIVITY]: 70 -> 100 - #10708 is now fully delivered. [IMPACT]: unchanged from prior review at 75 - Downstream review gate for Contract Ledger enforcement. [COMPLEXITY]: unchanged from prior review at 50 - Three review-skill surfaces plus PR metadata. [EFFORT_PROFILE]: unchanged from prior review at Architectural Pillar.

Required Actions

No required actions — eligible for human merge.

Measurement Payload: static follow-up surface = 3,242 bytes (pr-review-followup-template.md). Dynamic delta surface = PR body plus refreshed three-file docs/template diff.