[ggallen]

Summary

Extend the NormalizedEvent v1 schema to support GitLab as a normative source system, implementing Phase 0 of the GitLab cron-polling implementation plan.

Related Issue

Closes #3309

Changes

• Add gitlab to source.system enum (non-breaking v1 change)
• Add merged to transition.kind enum (non-breaking v1 change)
• Relax repo_path pattern for GitLab nested group paths (non-breaking relaxation)
• Update README and schema descriptions for GitLab as normative v1 source
• Add gitlab-poll to the Adapters table
• Add merged to transition kind vocabulary
• Add GitLab event projection guidance
• Add cross-reference annotation to ADR 0061
• Replace illustrative "Future forges" section with normative "GitLab adapter notes"
• Add gitlab-mr-opened.json and gitlab-mr-merged.json example fixtures
• Add invalid-path-traversal.json contract test fixture
• Document adapter-level path traversal rejection for repo_path
• Mark Phase 0 schema changes as completed in the implementation plan

Testing

• All example fixtures validated against the JSON schema
• Pre-commit hooks pass (JSON validation, link checks, ADR lints)
• No Go code changes — schema is documentation-only until Phase 2

Checklist

• Non-breaking v1 changes per versioning policy
• Authorized by ADR 0067 and implementation plan
• Schema descriptions updated
• README scope, adapters, vocabulary updated
• Example fixtures added
• ADR cross-reference annotation added

[qodo-code-review]

PR Summary by Qodo

Extend NormalizedEvent v1 schema for GitLab support

✨ Enhancement 📝 Documentation 🕐 10-20 Minutes

AI Description

• Add "gitlab" as a supported NormalizedEvent v1 source system.
• Add "merged" transition kind to represent GitLab merge request merges.
• Relax repo_path validation to allow nested GitLab group/subgroup project paths.

Diagram

graph TD
  GH["GitHub adapter"] --> SCH["NormalizedEvent v1 schema"] --> DISP["Event dispatcher"] --> CONS["Downstream consumers"]
  GL["GitLab adapter"] --> SCH

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Introduce structured repo identifier fields

• ➕ Avoids regex complexity and edge cases around path parsing
• ➕ Supports host-specific semantics cleanly (namespace vs project name)
• ➖ Bigger v1 surface-area change; may require adapter and consumer updates
• ➖ Harder to keep strictly “non-breaking” if consumers assume repo_path only

2. Version-bump schema (v1.1 or v2) for GitLab additions

• ➕ Clearer contract evolution boundaries for consumers
• ➕ Allows more invasive modeling improvements without ambiguity
• ➖ More operational overhead (publishing, migration guidance, dual-support)
• ➖ Slows Phase 0 GitLab enablement when changes are additive/non-breaking

Recommendation: Current approach is appropriate for Phase 0: additive enum values plus a relaxed repo_path pattern are consistent with non-breaking v1 evolution. If repo identity requirements grow (e.g., needing separate namespace/project or URL normalization), consider a future versioned move to structured repo fields rather than further regex expansion.

Files changed (1) +4 / -3

Enhancement (1) +4 / -3

normalized-event.schema.jsonBroaden NormalizedEvent v1 schema for GitLab sources and paths +4/-3

Broaden NormalizedEvent v1 schema for GitLab sources and paths

• Expands source.system to include "gitlab" and transition.kind to include "merged" for MR merge detection. Relaxes repo_path validation to allow nested group/subgroup paths and updates the field description accordingly.

docs/normative/normalized-event/v1/normalized-event.schema.json

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 11:52 PM UTC · Completed 12:05 AM UTC
Commit: ace0f62 · View workflow run →

[github-actions]

Site preview

Preview: https://b62f4681-site.fullsend-ai.workers.dev

Commit: 64e6f2e4648001fa9bf6adea9ca552d26558b8a5

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Merged kind undocumented ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The schema adds transition.kind: "merged", but the v1 README’s transition vocabulary table does
not mention merged, so readers following the normative docs won’t know it is a valid/expected
transition kind.

Code

docs/normative/normalized-event/v1/normalized-event.schema.json[R156-160]

            "synchronized",
            "updated",
            "closed",
+            "merged",
            "marked_ready",

Relevance

⭐⭐⭐ High

Team previously accepted updating docs when transition kinds were missing/unclear (e.g., add or
document reopened).

PR-#2650

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The schema’s enum explicitly includes merged, while the README’s transition vocabulary table lists
kinds but omits merged, so the normative documentation is incomplete relative to the schema.

docs/normative/normalized-event/v1/normalized-event.schema.json[145-165]
docs/normative/normalized-event/v1/README.md[95-105]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`transition.kind` now includes `merged` in the JSON schema, but the v1 README transition vocabulary does not document it. This creates doc/schema drift and ambiguity for adapter implementations.

### Issue Context
The PR extends the enum for merge detection, but the README vocabulary table still lists the older set of kinds.

### Fix Focus Areas
- docs/normative/normalized-event/v1/normalized-event.schema.json[145-165]
- docs/normative/normalized-event/v1/README.md[95-105]

### What to change
- Add a `merged` row (or update the existing row grouping) in the README’s “Transition kind vocabulary” table.
- Optionally add a short note clarifying how `merged` relates to `closed` for forges that represent merge-as-close.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. GitLab scope mismatch ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The schema now allows source.system: "gitlab", but both the schema prose and the v1 README still
describe v1 as GitHub/Jira-only and list source.system values excluding gitlab, creating a
normative contract mismatch.

Code

docs/normative/normalized-event/v1/normalized-event.schema.json[R361-365]

        "system": {
          "type": "string",
-          "enum": ["github", "jira", "manual", "schedule"],
+          "enum": ["github", "gitlab", "jira", "manual", "schedule"],
          "description": "Event provenance. v1 adapters emit github (webhooks), jira (poll input), manual, or schedule."
        },

Relevance

⭐⭐⭐ High

Similar schema-vs-README GitLab scope mismatches were flagged and accepted (e.g., document GitLab
driver since source.system supports gitlab).

PR-#2650

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The schema now permits GitLab as a source.system, but both the schema’s own descriptions and the
v1 README still state GitLab is out of scope and exclude it from the allowed source.system list,
making the normative docs contradictory.

docs/normative/normalized-event/v1/normalized-event.schema.json[361-365]
docs/normative/normalized-event/v1/normalized-event.schema.json[1-6]
docs/normative/normalized-event/v1/README.md[6-31]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`NormalizedEvent v1` documentation and schema prose still claim GitHub/Jira-only scope even though the schema now allows `source.system: gitlab`. This creates confusion about what values are valid/expected and what is considered in-scope for v1.

### Issue Context
The PR adds `gitlab` to the `source.system` enum, but leaves behind older descriptive text and the README scope section that explicitly excludes GitLab.

### Fix Focus Areas
- docs/normative/normalized-event/v1/normalized-event.schema.json[5-6]
- docs/normative/normalized-event/v1/normalized-event.schema.json[361-365]
- docs/normative/normalized-event/v1/README.md[6-31]

### What to change
- Update the schema top-level `description` (and `source.system` field `description`) to include GitLab or reword to avoid claiming GitLab is future work.
- Update README “Scope (v1)” bullets to include `gitlab` in the `source.system` list and adjust the paragraph that says GitLab is not part of this normative version (or explicitly explain that the schema is forward-compatible while adapters may lag, if that is the intent).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[fullsend-ai-review]

Review

Delta since prior review (be6852a): The [missing-authorization] finding is resolved — the PR now links to issue #3309. The [input-validation] finding is carried forward unchanged. All prior medium-severity findings from earlier iterations have been addressed. The new example fixtures (gitlab-mr-opened.json, gitlab-mr-merged.json, invalid-path-traversal.json) are structurally consistent with existing examples and correctly use the proposed schema values.

No Go code, harness YAML, or workflow consumers of the source.system or transition.kind enums exist yet (the NormalizedEvent Go struct is planned for Phase 2), so no downstream handler updates are needed.

Findings

Low

• [input-validation] docs/normative/normalized-event/v1/normalized-event.schema.json:91 — The relaxed repo_path pattern ^[a-zA-Z0-9._-]+(/[a-zA-Z0-9._-]+)+$ accepts path-traversal sequences like foo/../bar because the character class includes .. The description correctly adds a normative MUST reject note for adapter implementers, but the regex itself does not enforce this. No runtime code currently loads this schema. Risk is mitigated by the normative note, the invalid-path-traversal.json test fixture documenting the rejection requirement, and the existing runtime validation script (scripts/validate-source-repo.sh) retaining the strict owner/repo pattern for GitHub.
  Remediation: Consider adding a negative lookahead to reject .. segments in the regex, or ensure future adapter implementations include explicit path-traversal rejection tests.

• [adr-amendment-scope] docs/ADRs/0061-harness-cel-dispatch.md:73 — The parenthetical annotation noting scope extension by ADR 0067 and ADR 0063 is within the range of permitted cross-reference annotations for accepted ADRs per AGENTS.md. The original decision text is preserved verbatim; the addition is a forward-reference note, not a rewrite. However, the inline placement within the decision section makes the surrounding sentence more complex to parse than a standalone annotation would.

Previous run

Review

This PR implements Phase 0 schema preparation from the GitLab cron-polling implementation plan, authorized by ADR 0067. The three schema changes (enum additions for source.system and transition.kind, pattern relaxation for repo_path) are non-breaking per the v1 versioning policy. All six changed files are under docs/.

Delta since prior review (9abd1e1): The [stale-implementation-status] finding is resolved — the plan document now acknowledges completion. All prior medium-severity findings from earlier iterations (missing GitLab examples, missing gitlab-poll adapter table row, stale scope assertions) have been addressed. Two low-severity findings are carried forward unchanged.

The new GitLab example fixtures (gitlab-mr-opened.json, gitlab-mr-merged.json) are structurally consistent with existing examples, correctly use the proposed schema values (source.system: "gitlab", transition.kind: "merged", multi-segment repo path), and comply with the schema's conditional transition sub-object rules. The ADR 0061 cross-reference annotation is a permitted minor annotation on an Accepted ADR per AGENTS.md.

No Go code, harness YAML, or workflow consumers of the source.system or transition.kind enums exist yet (the NormalizedEvent Go struct is planned for Phase 2), so no downstream handler updates are needed.

Findings

Low

• [input-validation] docs/normative/normalized-event/v1/normalized-event.schema.json:91 — The relaxed repo_path pattern ^[a-zA-Z0-9._-]+(/[a-zA-Z0-9._-]+)+$ accepts path-traversal sequences like foo/../bar because the character class includes .. The description correctly adds a normative MUST reject note for adapter implementers, but the regex itself does not enforce this. No runtime code currently loads this schema. Risk is mitigated by the normative note and the existing runtime validation script (scripts/validate-source-repo.sh) retaining the strict owner/repo pattern for GitHub.
  Remediation: Consider adding a test fixture demonstrating .. rejection as a contract test for future adapters, or tighten the regex with a negative lookahead if JSON Schema validators support it.

• [missing-authorization] N/A — This PR introduces non-trivial changes (schema extensions, new examples, normative scope expansion) without a linked GitHub issue. ADR 0067 (accepted) and the implementation plan provide implicit authorization for Phase 0 work.
  Remediation: Create a GitHub issue that authorizes this work and link it to the PR.

---

Labels: PR modifies the NormalizedEvent dispatch schema and normative documentation for GitLab support.

Previous run (2)

Review

Findings

Low

• [missing-authorization] N/A — This PR introduces non-trivial changes (schema extensions, new examples, normative scope expansion) without a linked GitHub issue. ADR 0067 (accepted) and the implementation plan provide implicit authorization for Phase 0 work, but a linked issue is good practice for traceability.
  Remediation: Create a GitHub issue that authorizes this work and link it to the PR.

• [scope-creep-beyond-authorization] docs/normative/normalized-event/v1/README.md:30 — The PR converts README language from illustrative "Future forges" notes to normative "GitLab adapter notes", broadening v1 normative scope from GitHub+Jira to GitHub+GitLab+Jira. This is authorized by ADR 0067 and the v1 versioning policy permits enum additions as non-breaking changes.
  Remediation: Verify that this scope expansion is intentional per ADR 0067.

• [input-validation] docs/normative/normalized-event/v1/normalized-event.schema.json:91 — The relaxed repo_path pattern ^[a-zA-Z0-9._-]+(/[a-zA-Z0-9._-]+)+$ accepts path-traversal sequences like foo/../bar because the character class includes .. While currently documentation-only (no runtime code loads this schema), future adapters implementing this spec should reject .. segments independently.
  Remediation: Consider tightening the pattern to exclude consecutive dots, or document that adapters MUST reject .. segments.

• [stale-implementation-status] docs/plans/gitlab-cron-polling-implementation.md:139 — Phase 0 schema preparation section describes three schema changes as "required before the gitlab-poll input driver can emit valid NormalizedEvent values." This PR implements those changes, but the plan document does not acknowledge completion.
  Remediation: Add a status note indicating these schema changes were completed.

Previous run (3)

Review

Findings

Medium

• [missing-examples] docs/normative/normalized-event/v1/README.md:21 — The Scope section states that v1 adapters and examples target GitLab cron-poll input, but there are no GitLab example fixtures in the examples/ directory. Only GitHub and Jira examples exist. The normative spec claims GitLab is a v1 source system with production status, but provides no example NormalizedEvent fixture demonstrating the gitlab-poll adapter output.
  Remediation: Add at least one GitLab example fixture (e.g., examples/gitlab-mr-opened.json) demonstrating the gitlab-poll adapter's NormalizedEvent output with source.system: "gitlab", nested repo path, and transition.kind: "merged". Alternatively, clarify that GitLab examples are forthcoming by changing the Scope wording to specify which examples currently exist.

Low

• [internal-consistency] docs/normative/normalized-event/v1/README.md:186 — The Execution ref projection table describes event_type as sourced from source.raw_type with the parenthetical "(GitHub Actions event name; see note below)". Now that GitLab is a normative v1 source system, this description is GitHub-specific. The new "GitLab event projection" paragraph added below the table partially mitigates this, but the table cell itself still uses GitHub-only terminology.
  Remediation: Update the table cell description to forge-neutral wording, e.g., source.raw_type (native event name from the source forge; see notes below).

Previous run (4)

Review

Findings

Medium

• [internal-consistency] docs/normative/normalized-event/v1/README.md:49 — The Adapters table lists only gha-event, jira-poll, and json as v1 input drivers, but the updated Scope section now identifies gitlab-poll as a normative production adapter and the GitLab adapter notes section also describes gitlab-poll as a production input driver. The Adapters table is the primary reference for implementers checking which drivers exist; omitting gitlab-poll creates an internal contradiction within the document.
  Remediation: Add a row to the Adapters table: | gitlab-poll | GitLab CI event payload (cron-polled; ADR 0067) | Production (poll) |

Low

• [documentation-consistency] docs/normative/normalized-event/v1/README.md:104 — The merged transition kind vocabulary entry includes GitLab-specific implementation detail ("primary path for retro-stage dispatch on GitLab where merge and close are distinct events"). The table already contains forge-specific context in other entries (e.g., synchronized references "GitHub synchronize"), so this is not a strict pattern violation but is more verbose than peer entries.
  Remediation: Consider shortening to | merged | Change proposal merged into target branch | and moving the GitLab dispatch context to the GitLab adapter notes section.

• [documentation-staleness] docs/ADRs/0061-harness-cel-dispatch.md:71 — ADR 0061 states "v1 normative scope is GitHub Actions" which is now superseded by ADR 0067's expansion to GitLab. ADRs are point-in-time records per the project's own conventions; a cross-reference annotation is appropriate but rewriting the scope statement is not.
  Remediation: Add a brief annotation below line 72 such as: "(Scope extended to GitLab cron-poll and Jira poll input by ADR 0067 and ADR 0063.)"

• [internal-consistency] docs/normative/normalized-event/v1/README.md:186 — The Execution ref projection table describes event_type as "GitHub Actions event name" and event_payload.pull_request as "GitHub-shaped". Now that GitLab is a normative v1 source system, the section gives no guidance on how GitLab raw_type values map or what shape the projected payload takes for MR events.
  Remediation: Add a note or subsection clarifying GitLab event projection.

Previous run (5)

Review

Findings

High

• [stale-reference] docs/normative/normalized-event/v1/README.md:24 — Normative scope section lists only github, jira, manual, or schedule as valid source.system values, but the schema now includes gitlab. This contradicts the schema change and will mislead implementers about what values are valid in v1.
  Remediation: Update to include gitlab in the source.system enumeration.

• [stale-reference] docs/normative/normalized-event/v1/README.md:265 — The "Future forges" section explicitly states that gitlab is "not yet in the v1 schema; requires the Phase 0 schema change," but this PR is that Phase 0 schema change. Line 266 similarly marks the wider repo_path pattern as "not yet in the v1 schema." These parentheticals directly contradict the change being made.
  Remediation: Remove the "not yet in the v1 schema" markers and update the language to reflect that GitLab is now part of the normative v1 scope.

Medium

• [internal-consistency] docs/normative/normalized-event/v1/normalized-event.schema.json:363 — The source.system description still reads "v1 adapters emit github (webhooks), jira (poll input), manual, or schedule" but omits gitlab, which is now in the enum. Internal inconsistency within the same property definition.
  Remediation: Update the description to include gitlab, e.g.: "Event provenance. v1 adapters emit github (webhooks), gitlab (cron-poll input), jira (poll input), manual, or schedule."

• [missing-documentation] docs/normative/normalized-event/v1/README.md:104 — The transition kind vocabulary table does not document the new merged transition kind. Implementers will not know when to use this value or what it means.
  Remediation: Add a row to the transition kind vocabulary table for merged (e.g., "Change proposal merged into target branch; primary path for retro-stage dispatch on GitLab").

Low

• [documentation-staleness] docs/normative/normalized-event/v1/normalized-event.schema.json:5 — Top-level schema description states "other forges remain future work," but this PR adds GitLab to the schema.

• [scope-inconsistency] docs/normative/normalized-event/v1/README.md:30 — Section states "Other forges (e.g. GitLab) are not part of this normative version" but the schema now includes GitLab as a valid source system.

Previous run (6)

Review

Findings

Low

• [missing-authorization] N/A — This PR introduces non-trivial changes (schema extensions, new examples, normative scope expansion) without a linked GitHub issue. ADR 0067 (accepted) and the implementation plan provide implicit authorization for Phase 0 work, but a linked issue is good practice for traceability.
  Remediation: Create a GitHub issue that authorizes this work and link it to the PR.

• [scope-creep-beyond-authorization] docs/normative/normalized-event/v1/README.md:30 — The PR converts README language from illustrative "Future forges" notes to normative "GitLab adapter notes", broadening v1 normative scope from GitHub+Jira to GitHub+GitLab+Jira. This is authorized by ADR 0067 and the v1 versioning policy permits enum additions as non-breaking changes.
  Remediation: Verify that this scope expansion is intentional per ADR 0067.

• [input-validation] docs/normative/normalized-event/v1/normalized-event.schema.json:91 — The relaxed repo_path pattern ^[a-zA-Z0-9._-]+(/[a-zA-Z0-9._-]+)+$ accepts path-traversal sequences like foo/../bar because the character class includes .. While currently documentation-only (no runtime code loads this schema), future adapters implementing this spec should reject .. segments independently.
  Remediation: Consider tightening the pattern to exclude consecutive dots, or document that adapters MUST reject .. segments.

• [stale-implementation-status] docs/plans/gitlab-cron-polling-implementation.md:139 — Phase 0 schema preparation section describes three schema changes as "required before the gitlab-poll input driver can emit valid NormalizedEvent values." This PR implements those changes, but the plan document does not acknowledge completion.
  Remediation: Add a status note indicating these schema changes were completed.

---

Labels: PR modifies the NormalizedEvent dispatch schema and normative documentation for GitLab support.

Previous run (7)

Review

Findings

Medium

• [missing-examples] docs/normative/normalized-event/v1/README.md:21 — The Scope section states that v1 adapters and examples target GitLab cron-poll input, but there are no GitLab example fixtures in the examples/ directory. Only GitHub and Jira examples exist. The normative spec claims GitLab is a v1 source system with production status, but provides no example NormalizedEvent fixture demonstrating the gitlab-poll adapter output.
  Remediation: Add at least one GitLab example fixture (e.g., examples/gitlab-mr-opened.json) demonstrating the gitlab-poll adapter's NormalizedEvent output with source.system: "gitlab", nested repo path, and transition.kind: "merged". Alternatively, clarify that GitLab examples are forthcoming by changing the Scope wording to specify which examples currently exist.

Low

• [internal-consistency] docs/normative/normalized-event/v1/README.md:186 — The Execution ref projection table describes event_type as sourced from source.raw_type with the parenthetical "(GitHub Actions event name; see note below)". Now that GitLab is a normative v1 source system, this description is GitHub-specific. The new "GitLab event projection" paragraph added below the table partially mitigates this, but the table cell itself still uses GitHub-only terminology.
  Remediation: Update the table cell description to forge-neutral wording, e.g., source.raw_type (native event name from the source forge; see notes below).

Previous run

Review

Findings

Medium

• [internal-consistency] docs/normative/normalized-event/v1/README.md:49 — The Adapters table lists only gha-event, jira-poll, and json as v1 input drivers, but the updated Scope section now identifies gitlab-poll as a normative production adapter and the GitLab adapter notes section also describes gitlab-poll as a production input driver. The Adapters table is the primary reference for implementers checking which drivers exist; omitting gitlab-poll creates an internal contradiction within the document.
  Remediation: Add a row to the Adapters table: | gitlab-poll | GitLab CI event payload (cron-polled; ADR 0067) | Production (poll) |

Low

• [documentation-consistency] docs/normative/normalized-event/v1/README.md:104 — The merged transition kind vocabulary entry includes GitLab-specific implementation detail ("primary path for retro-stage dispatch on GitLab where merge and close are distinct events"). The table already contains forge-specific context in other entries (e.g., synchronized references "GitHub synchronize"), so this is not a strict pattern violation but is more verbose than peer entries.
  Remediation: Consider shortening to | merged | Change proposal merged into target branch | and moving the GitLab dispatch context to the GitLab adapter notes section.

• [documentation-staleness] docs/ADRs/0061-harness-cel-dispatch.md:71 — ADR 0061 states "v1 normative scope is GitHub Actions" which is now superseded by ADR 0067's expansion to GitLab. ADRs are point-in-time records per the project's own conventions; a cross-reference annotation is appropriate but rewriting the scope statement is not.
  Remediation: Add a brief annotation below line 72 such as: "(Scope extended to GitLab cron-poll and Jira poll input by ADR 0067 and ADR 0063.)"

• [internal-consistency] docs/normative/normalized-event/v1/README.md:186 — The Execution ref projection table describes event_type as "GitHub Actions event name" and event_payload.pull_request as "GitHub-shaped". Now that GitLab is a normative v1 source system, the section gives no guidance on how GitLab raw_type values map or what shape the projected payload takes for MR events.
  Remediation: Add a note or subsection clarifying GitLab event projection.

Previous run (8)

Review

Findings

High

• [stale-reference] docs/normative/normalized-event/v1/README.md:24 — Normative scope section lists only github, jira, manual, or schedule as valid source.system values, but the schema now includes gitlab. This contradicts the schema change and will mislead implementers about what values are valid in v1.
  Remediation: Update to include gitlab in the source.system enumeration.

• [stale-reference] docs/normative/normalized-event/v1/README.md:265 — The "Future forges" section explicitly states that gitlab is "not yet in the v1 schema; requires the Phase 0 schema change," but this PR is that Phase 0 schema change. Line 266 similarly marks the wider repo_path pattern as "not yet in the v1 schema." These parentheticals directly contradict the change being made.
  Remediation: Remove the "not yet in the v1 schema" markers and update the language to reflect that GitLab is now part of the normative v1 scope.

Medium

• [internal-consistency] docs/normative/normalized-event/v1/normalized-event.schema.json:363 — The source.system description still reads "v1 adapters emit github (webhooks), jira (poll input), manual, or schedule" but omits gitlab, which is now in the enum. Internal inconsistency within the same property definition.
  Remediation: Update the description to include gitlab, e.g.: "Event provenance. v1 adapters emit github (webhooks), gitlab (cron-poll input), jira (poll input), manual, or schedule."

• [missing-documentation] docs/normative/normalized-event/v1/README.md:104 — The transition kind vocabulary table does not document the new merged transition kind. Implementers will not know when to use this value or what it means.
  Remediation: Add a row to the transition kind vocabulary table for merged (e.g., "Change proposal merged into target branch; primary path for retro-stage dispatch on GitLab").

Low

• [documentation-staleness] docs/normative/normalized-event/v1/normalized-event.schema.json:5 — Top-level schema description states "other forges remain future work," but this PR adds GitLab to the schema.

• [scope-inconsistency] docs/normative/normalized-event/v1/README.md:30 — Section states "Other forges (e.g. GitLab) are not part of this normative version" but the schema now includes GitLab as a valid source system.

Previous run (9)

Review

Findings

Medium

• [missing-examples] docs/normative/normalized-event/v1/README.md:21 — The Scope section states that v1 adapters and examples target GitLab cron-poll input, but there are no GitLab example fixtures in the examples/ directory. Only GitHub and Jira examples exist. The normative spec claims GitLab is a v1 source system with production status, but provides no example NormalizedEvent fixture demonstrating the gitlab-poll adapter output.
  Remediation: Add at least one GitLab example fixture (e.g., examples/gitlab-mr-opened.json) demonstrating the gitlab-poll adapter's NormalizedEvent output with source.system: "gitlab", nested repo path, and transition.kind: "merged". Alternatively, clarify that GitLab examples are forthcoming by changing the Scope wording to specify which examples currently exist.

Low

• [internal-consistency] docs/normative/normalized-event/v1/README.md:186 — The Execution ref projection table describes event_type as sourced from source.raw_type with the parenthetical "(GitHub Actions event name; see note below)". Now that GitLab is a normative v1 source system, this description is GitHub-specific. The new "GitLab event projection" paragraph added below the table partially mitigates this, but the table cell itself still uses GitHub-only terminology.
  Remediation: Update the table cell description to forge-neutral wording, e.g., source.raw_type (native event name from the source forge; see notes below).

Previous run (10)

Review

Findings

Medium

• [internal-consistency] docs/normative/normalized-event/v1/README.md:49 — The Adapters table lists only gha-event, jira-poll, and json as v1 input drivers, but the updated Scope section now identifies gitlab-poll as a normative production adapter and the GitLab adapter notes section also describes gitlab-poll as a production input driver. The Adapters table is the primary reference for implementers checking which drivers exist; omitting gitlab-poll creates an internal contradiction within the document.
  Remediation: Add a row to the Adapters table: | gitlab-poll | GitLab CI event payload (cron-polled; ADR 0067) | Production (poll) |

Low

• [documentation-consistency] docs/normative/normalized-event/v1/README.md:104 — The merged transition kind vocabulary entry includes GitLab-specific implementation detail ("primary path for retro-stage dispatch on GitLab where merge and close are distinct events"). The table already contains forge-specific context in other entries (e.g., synchronized references "GitHub synchronize"), so this is not a strict pattern violation but is more verbose than peer entries.
  Remediation: Consider shortening to | merged | Change proposal merged into target branch | and moving the GitLab dispatch context to the GitLab adapter notes section.

• [documentation-staleness] docs/ADRs/0061-harness-cel-dispatch.md:71 — ADR 0061 states "v1 normative scope is GitHub Actions" which is now superseded by ADR 0067's expansion to GitLab. ADRs are point-in-time records per the project's own conventions; a cross-reference annotation is appropriate but rewriting the scope statement is not.
  Remediation: Add a brief annotation below line 72 such as: "(Scope extended to GitLab cron-poll and Jira poll input by ADR 0067 and ADR 0063.)"

• [internal-consistency] docs/normative/normalized-event/v1/README.md:186 — The Execution ref projection table describes event_type as "GitHub Actions event name" and event_payload.pull_request as "GitHub-shaped". Now that GitLab is a normative v1 source system, the section gives no guidance on how GitLab raw_type values map or what shape the projected payload takes for MR events.
  Remediation: Add a note or subsection clarifying GitLab event projection.

Previous run (11)

Review

Findings

High

• [stale-reference] docs/normative/normalized-event/v1/README.md:24 — Normative scope section lists only github, jira, manual, or schedule as valid source.system values, but the schema now includes gitlab. This contradicts the schema change and will mislead implementers about what values are valid in v1.
  Remediation: Update to include gitlab in the source.system enumeration.

• [stale-reference] docs/normative/normalized-event/v1/README.md:265 — The "Future forges" section explicitly states that gitlab is "not yet in the v1 schema; requires the Phase 0 schema change," but this PR is that Phase 0 schema change. Line 266 similarly marks the wider repo_path pattern as "not yet in the v1 schema." These parentheticals directly contradict the change being made.
  Remediation: Remove the "not yet in the v1 schema" markers and update the language to reflect that GitLab is now part of the normative v1 scope.

Medium

• [internal-consistency] docs/normative/normalized-event/v1/normalized-event.schema.json:363 — The source.system description still reads "v1 adapters emit github (webhooks), jira (poll input), manual, or schedule" but omits gitlab, which is now in the enum. Internal inconsistency within the same property definition.
  Remediation: Update the description to include gitlab, e.g.: "Event provenance. v1 adapters emit github (webhooks), gitlab (cron-poll input), jira (poll input), manual, or schedule."

• [missing-documentation] docs/normative/normalized-event/v1/README.md:104 — The transition kind vocabulary table does not document the new merged transition kind. Implementers will not know when to use this value or what it means.
  Remediation: Add a row to the transition kind vocabulary table for merged (e.g., "Change proposal merged into target branch; primary path for retro-stage dispatch on GitLab").

Low

• [documentation-staleness] docs/normative/normalized-event/v1/normalized-event.schema.json:5 — Top-level schema description states "other forges remain future work," but this PR adds GitLab to the schema.

• [scope-inconsistency] docs/normative/normalized-event/v1/README.md:30 — Section states "Other forges (e.g. GitLab) are not part of this normative version" but the schema now includes GitLab as a valid source system.

[ifireball]

Approved. But please fix the little nits Qodo found

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 11:25 AM UTC · Completed 11:42 AM UTC
Commit: 9f39104 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 11:46 AM UTC · Completed 12:02 PM UTC
Commit: c54e72c · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:05 PM UTC · Completed 12:23 PM UTC
Commit: 9abd1e1 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:29 PM UTC · Completed 12:44 PM UTC
Commit: be6852a · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:49 PM UTC · Completed 1:09 PM UTC
Commit: 64e6f2e · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 1:24 PM UTC · Completed 1:36 PM UTC
Commit: 64e6f2e · View workflow run →

[fullsend-ai-retro]

Retro: PR #3191 — feat(dispatch): extend NormalizedEvent v1 schema for GitLab support

Workflow summary: This was a human-authored PR by @ggallen that extended the NormalizedEvent v1 schema to support GitLab as a normative source system (7 files, +136/-34 lines, all under docs/). The PR went through 6 review agent runs across ~13.5 hours (overnight gap + 2.5 hours of active iteration). The review agent caught genuine high-severity internal consistency issues (stale scope assertions, missing documentation updates) that the human reviewer did not catch — the human approved unconditionally while the review bot had CHANGES_REQUESTED active.

Review agent quality was high. The agent correctly identified and prioritized cross-file consistency issues: stale README scope sections contradicting the schema, missing adapter table entries, and missing example fixtures. It drove the author to create tracking issue #3309, add a path-traversal test fixture, and update the implementation plan. All findings were actionable with zero false positives.

The main inefficiency was 6 review iterations for a 7-file docs PR. Three of the six runs found new medium-severity issues that were arguably discoverable on the first pass (missing adapters table row, missing example fixtures, stale implementation plan status). The review agent found them incrementally across runs 1-4 rather than comprehensively in run 1.

Existing issues cover most identified patterns:

• Retro agent sandbox lacks GitHub API read access needed for analysis #3259 (open): Retro agent sandbox lacks GitHub API read access — I encountered this initially but gh CLI works through the proxy; curl does not. This is working as designed per policies/retro.yaml binary allowlisting.
• Improve docs-staleness scanning to find all instances in one pass #1061 (open): Review should find all docs-staleness instances in one pass — directly relevant, new evidence filed below.
• Add per-PR review budget to cap runaway review dispatches #2599 (open): Per-PR review budget to cap runaway dispatches.
• Cap stacked historical iterations in consolidated review comment #2358 (open): Cap stacked historical iterations in review comment — the PR's final review comment accumulated 11 Previous run sections for 6 actual runs due to nested history duplication.
• Review orchestrator: add fast path for trivial docs/prompt-only changes #1900 (open): Fast path for trivial docs/prompt-only changes.
• Review agent: incorporate existing human and third-party bot reviews into assessment #664 (open): Incorporate third-party reviews — Qodo and fullsend-review found overlapping issues (scope mismatch, missing merged documentation).

Autonomy readiness: The review agent outperformed the human reviewer on this documentation PR. The human approved without catching any of the 2 high + 2 medium severity findings. The review agent correctly blocked merge until all medium+ issues were resolved. For docs-only PRs that don't modify code, workflows, or security-sensitive files, the review agent could be granted higher autonomy (e.g., auto-merge on approval for docs-only PRs from trusted authors).

Proposals filed

• Evidence for #1061: review found consistency issues incrementally across 3 runs on schema extension PR (in fullsend-ai/fullsend)