Scenario
For a feature deliberately split across multiple PRs, the first PR committed an auxiliary documentation file (a standards/reference doc) plus example snippets that described the full multi-PR feature — including endpoints, helpers, and metrics that only ship in later PRs.
alignment-check traces design requirements ↔ plan tasks, and scope-lock guards the task/PR manifest, but neither inspects the prose/example content of committed docs against the current scope manifest. So the forward-referencing documentation passed every pipeline gate and was only caught at code review — producing a cluster of "this references something not in this PR" comments and a doc-only fixup commit. In one feature, the majority of review comments were doc-scope issues of exactly this kind.
Impact
- Documentation routinely ships describing not-yet-existing behavior in split-PR features.
- The human reviewer — not the pipeline — becomes the scope gate for docs, which is precisely what
scope-lock exists to prevent for code.
Recommendation
- Extend
alignment-check (or add a scope-lock verification step) to scan documentation and example artifacts committed in the PR for references to identifiers/behaviors absent from the current scope manifest, and flag them as scope drift.
- At minimum, prompt the agent to explicitly label deferred items in committed docs (e.g. "Planned — later PR"), so forward references are intentional and marked rather than implicit.
Scenario
For a feature deliberately split across multiple PRs, the first PR committed an auxiliary documentation file (a standards/reference doc) plus example snippets that described the full multi-PR feature — including endpoints, helpers, and metrics that only ship in later PRs.
alignment-checktraces design requirements ↔ plan tasks, andscope-lockguards the task/PR manifest, but neither inspects the prose/example content of committed docs against the current scope manifest. So the forward-referencing documentation passed every pipeline gate and was only caught at code review — producing a cluster of "this references something not in this PR" comments and a doc-only fixup commit. In one feature, the majority of review comments were doc-scope issues of exactly this kind.Impact
scope-lockexists to prevent for code.Recommendation
alignment-check(or add ascope-lockverification step) to scan documentation and example artifacts committed in the PR for references to identifiers/behaviors absent from the current scope manifest, and flag them as scope drift.