Skip to content

Commit 85ceb32

Browse files
committed
docs(phase-6): add scope alignment review and implementation scope gates
Add scope-alignment-review-notes.md documenting the review of all 8 research plans against jahow's actual PR #136 acceptance requirements. The review confirms research scope is appropriate (broad research informs good design choices) while adding implementation scope gates to prevent research findings from expanding work beyond jahow's requirements. Changes: - New: scope-alignment-review-notes.md (two-part assessment) - Plan 06: Added 'Implementation Scope Gate' section and success criterion - Plan 08: Added 'Implementation Scope Gate' section and success criterion - research-strategy.md: Added 'Implementation Scope Principle' section Key principle: Research broadly, implement minimally.
1 parent 4e057ea commit 85ceb32

File tree

4 files changed

+257
-0
lines changed

4 files changed

+257
-0
lines changed

docs/research/phase-6/research-plans/06-endpoint-decoupling-architecture.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,24 @@ This is the critical synthesis plan. It cannot begin until Plans 02–05 are com
6464
4. **One-way dependency (Constraint 4):** After refactoring, removing the entire `src/ogc-api/csapi/` directory must leave core fully functional — zero type errors, zero test failures, zero import resolution errors. This is the litmus test for every design choice.
6565
5. **CI compliance:** Prettier, TypeScript typecheck, ESLint, browser tests, and Node.js tests must all pass.
6666

67+
### Implementation Scope Gate
68+
69+
> **Research broadly, implement minimally.**
70+
>
71+
> Plans 04 and 05 provide industry best practices and architectural theory to *inform* design decisions. However, every design decision produced by this plan must pass the **minimum-change test:**
72+
>
73+
> **"Does this change directly serve jahow's two requirements (CSAPI out of root index.ts, non-CSAPI code stops importing CSAPI), or are we adding work he didn't request?"**
74+
>
75+
> If a design choice is informed by industry best practice but increases the implementation scope beyond what jahow requires, prefer the simpler approach that still satisfies all boundary conditions. Use the industry research to *validate* that the simpler approach is sound — not to justify a more complex one.
76+
>
77+
> Specifically:
78+
> - Do NOT introduce adapter interfaces, factory patterns, or data record types unless they are strictly necessary to satisfy the boundary conditions. If the existing code can be relocated without restructuring, that is preferred.
79+
> - Do NOT refactor `CSAPIQueryBuilder`'s constructor signature unless the current signature violates a boundary condition.
80+
> - Do NOT suggest changes to EDR or other upstream modules — that is not our scope.
81+
> - If a design decision is a close call, document both options and flag it for jahow's input rather than over-engineering a solution.
82+
>
83+
> See: [Scope Alignment Review Notes](scope-alignment-review-notes.md)
84+
6785
### Excluded From Scope
6886

6987
- **Plugin registration, mixin injection, decorator patterns:** Excluded — these require core to reference the sub-module (violates constraints 3 and 4).
@@ -368,6 +386,7 @@ This research is complete when:
368386
- [ ] Post-refactoring verification checklist is complete
369387
- [ ] The "litmus test" is explicitly verified: removing `src/ogc-api/csapi/` leaves core functional
370388
- [ ] Deliverable document is complete and follows the findings report template
389+
- [ ] **Implementation scope gate applied:** Every design decision passes the minimum-change test — no changes beyond what jahow's requirements demand
371390
- [ ] Findings are cross-referenced with Plan 08 and provide everything Plan 08 needs to produce the changelist
372391

373392
---

docs/research/phase-6/research-plans/08-file-level-changelist-and-commit-strategy.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,27 @@ This plan is also uniquely positioned: it must account for the *existing* 13-com
6464
5. **CI compliance (Constraint 5):** Every commit in the final sequence must individually pass all 5 CI checks: `npm run format:check`, `npm run typecheck`, `npm run lint`, `npm run test:browser`, `npm run test:node`. If this is impractical for intermediate commits, the plan must document which commits are allowed to be squashed.
6565
6. **PR #136 compatibility:** The changelist must be applicable to the `clean-pr` branch, which has 13 commits above `upstream/main` (`53a6449`). The strategy must define how refactoring changes integrate with those 13 commits — amend, rebase, or extend.
6666

67+
### Implementation Scope Gate
68+
69+
> **Research broadly, implement minimally.**
70+
>
71+
> This plan translates research findings into the concrete changelist. Every file operation in the changelist must pass the **minimum-change test:**
72+
>
73+
> **"Does this file change directly serve jahow's two requirements (CSAPI out of root index.ts, non-CSAPI code stops importing CSAPI), or are we adding work he didn't request?"**
74+
>
75+
> The changelist must contain ONLY:
76+
> - Changes required to satisfy jahow's two bullet points
77+
> - Changes that are direct consequences of those requirements (e.g., moving a method because its imports violate the constraints)
78+
> - Changes required to pass CI (formatting, linting)
79+
>
80+
> The changelist must NOT contain:
81+
> - "While we're at it" improvements (refactoring code that isn't affected by the boundary conditions)
82+
> - New abstractions or patterns inspired by research but not required by the constraints
83+
> - Changes to modules outside our scope (EDR, other upstream code)
84+
> - Documentation files beyond what's needed for the PR
85+
>
86+
> See: [Scope Alignment Review Notes](scope-alignment-review-notes.md)
87+
6788
### Excluded From Scope
6889

6990
- **Architectural decision-making:** All architectural decisions are made in Plans 01–06. Plan 08 does not revisit them — it translates them into file operations. If a decision is ambiguous, this plan flags it as an open question for Plan 06 rather than resolving it.
@@ -313,6 +334,7 @@ This research is complete when:
313334
- [ ] The changelist accounts for formatting (Plan 07's output) and places it correctly in the commit sequence
314335
- [ ] No file affected by the refactoring is missing from the changelist (completeness verified by walking through constraints)
315336
- [ ] A developer can execute the spec mechanically — zero ambiguities, zero decisions left to make
337+
- [ ] **Implementation scope gate applied:** Every file operation passes the minimum-change test — no changes beyond what jahow's requirements demand
316338
- [ ] Deliverable document is complete and follows the findings report template
317339
- [ ] The deliverable document IS the implementation spec — it bridges research and action
318340

0 commit comments

Comments
 (0)