Phase 0 WP-0.10–0.12: Host skeleton, options classes, sample configs, and execution framework
- WP-0.10: Role-based Host startup (Central=WebApplication, Site=generic Host), 15 component AddXxx() extension methods, MapCentralUI/MapInboundAPI stubs - WP-0.11: 12 per-component options classes with config binding - WP-0.12: Sample appsettings for central and site topologies - Add execution procedure and checklist template to generate_plans.md - Add phase-0-checklist.md for execution tracking - Resolve all 21 open questions from plan generation - Update IDataConnection with batch ops and IAsyncDisposable 57 tests pass, zero warnings.
This commit is contained in:
Joseph Doherty
@@ -530,21 +530,206 @@ Ask Codex: *"Review this implementation plan against the provided requirements,
|
||||
|
||||
---
|
||||
|
||||
## Phase Execution Procedure
|
||||
|
||||
This section governs how implementation plans are executed. The goal is autonomous execution with built-in compliance checks — no user input required between starting a phase and completing it.
|
||||
|
||||
### Principles
|
||||
|
||||
1. **Work packages are executed in dependency order** — respect `blockedBy` relationships within the phase. Independent WPs may be parallelized.
|
||||
2. **Each WP is self-verifying** — acceptance criteria are checked before moving on. A WP is not complete until all its criteria pass.
|
||||
3. **Tests are written alongside code, not after** — unit tests for a WP are part of that WP, not a separate step.
|
||||
4. **Commit at WP boundaries** — each completed WP (or logical group of small WPs) gets its own commit with a message referencing the WP number and phase.
|
||||
5. **Questions are logged, not blocking** — if an ambiguity is discovered during implementation, log it to `questions.md`, make the best judgment, and continue. Do not stop for user input.
|
||||
6. **Codex MCP is best-effort** — if unavailable during verification steps, note the skip and continue.
|
||||
|
||||
### Per-Work-Package Execution
|
||||
|
||||
For each work package, follow this sequence:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ 1. READ the WP description and acceptance criteria │
|
||||
│ 2. READ all traced requirements (HLR bullets, KDD, │
|
||||
│ CD constraints) to understand intent │
|
||||
│ 3. IMPLEMENT the WP │
|
||||
│ - Write code │
|
||||
│ - Write unit tests for acceptance criteria │
|
||||
│ - Write negative tests for prohibition criteria │
|
||||
│ 4. VERIFY acceptance criteria │
|
||||
│ - Run tests: all must pass │
|
||||
│ - Walk each acceptance criterion line by line │
|
||||
│ - If a criterion cannot be verified yet (depends │
|
||||
│ on a later WP), note it as "deferred to WP-N" │
|
||||
│ 5. UPDATE the phase execution checklist │
|
||||
│ - Mark WP as complete with date │
|
||||
│ - Note any deferred criteria │
|
||||
│ - Note any questions logged │
|
||||
│ 6. COMMIT with message: "Phase N WP-M: <summary>" │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Mid-Phase Compliance Check
|
||||
|
||||
After completing approximately half of a phase's work packages (or at any natural milestone), perform a lightweight compliance check:
|
||||
|
||||
1. **Build check**: The solution compiles with zero warnings (treat warnings as errors).
|
||||
2. **Test check**: All tests written so far pass.
|
||||
3. **Deferred criteria review**: Check if any previously deferred acceptance criteria can now be verified. If so, verify them and update the checklist.
|
||||
4. **Traceability spot-check**: Pick 3 random requirements from the Requirements Checklist. Verify they have corresponding code and tests.
|
||||
|
||||
If any check fails, fix the issue before proceeding to the next WP.
|
||||
|
||||
### Phase Completion Gate
|
||||
|
||||
After all work packages are complete, execute the verification gate from the plan document:
|
||||
|
||||
1. **Run the full test suite** — all unit, integration, negative, and failover tests must pass.
|
||||
2. **Walk the verification gate checklist** — each item in the plan's "Verification Gate" section must pass. Record pass/fail per item.
|
||||
3. **Walk the Requirements Checklist** — confirm every bullet has been implemented and tested. Check off each item.
|
||||
4. **Walk the Design Constraints Checklist** — confirm every constraint has been respected. Check off each item.
|
||||
5. **Check deferred criteria** — all previously deferred acceptance criteria must now be resolvable. Verify them.
|
||||
6. **Run the phase execution checklist** — all WPs must be marked complete with no open items.
|
||||
|
||||
### Post-Phase Codex MCP Review
|
||||
|
||||
After the completion gate passes, submit the implementation for external review:
|
||||
|
||||
**Step 1 — Implementation vs. Plan review**: Submit to Codex (model: `gpt-5.4`):
|
||||
- The phase plan document
|
||||
- A summary of what was implemented (file list, key decisions made)
|
||||
- The phase execution checklist (showing all WPs complete)
|
||||
- Any test output or coverage summary
|
||||
|
||||
Ask Codex: *"Review this implementation against the plan. For each work package, verify that the acceptance criteria described in the plan are reflected in the implementation summary. Identify: (1) any acceptance criterion that appears unimplemented, (2) any implementation that contradicts the plan, (3) any requirement from the plan's Requirements Checklist that lacks corresponding code or tests. List each finding with the specific plan text and what is missing."*
|
||||
|
||||
**Step 2 — Code quality review**: Ask Codex: *"Review the implementation for: (1) security vulnerabilities (OWASP top 10), (2) race conditions or thread safety issues, (3) missing error handling at system boundaries, (4) violations of the project's architectural constraints (no business logic in Commons, no EF in consuming components, Tell for hot-path/Ask for boundaries). List each finding with file and line reference."*
|
||||
|
||||
**Handling findings**: Fix valid findings. Dismiss false positives with rationale. Record the review outcome in the execution checklist.
|
||||
|
||||
### Final Steps
|
||||
|
||||
1. **Commit** any fixes from the post-phase review.
|
||||
2. **Update `requirements-traceability.md`** — change status from "Plan generated" to "Implemented" for all sections, REQ-* IDs, and KDD/CD constraints covered by this phase.
|
||||
3. **Push** to remote.
|
||||
4. **Report** — output a summary of what was implemented, tests passing, and any questions logged.
|
||||
|
||||
---
|
||||
|
||||
## Phase Execution Checklist Template
|
||||
|
||||
Each phase creates a checklist file at `docs/plans/phase-N-checklist.md` when execution begins. This file tracks compliance as work packages are completed.
|
||||
|
||||
```markdown
|
||||
# Phase N Execution Checklist
|
||||
|
||||
**Phase**: [phase name]
|
||||
**Started**: [date]
|
||||
**Completed**: [date or "in progress"]
|
||||
|
||||
---
|
||||
|
||||
## Work Package Status
|
||||
|
||||
| WP | Description | Status | Date | Deferred Criteria | Notes |
|
||||
|----|-------------|--------|------|-------------------|-------|
|
||||
| WP-1 | [description] | [ ] Pending | | | |
|
||||
| WP-2 | [description] | [ ] Pending | | | |
|
||||
| ... | | | | | |
|
||||
|
||||
## Mid-Phase Compliance Checks
|
||||
|
||||
| Check | Date | Result | Notes |
|
||||
|-------|------|--------|-------|
|
||||
| Build (zero warnings) | | [ ] Pass / [ ] Fail | |
|
||||
| All tests pass | | [ ] Pass / [ ] Fail | |
|
||||
| Deferred criteria review | | [ ] Pass / [ ] N/A | |
|
||||
| Traceability spot-check (3 random) | | [ ] Pass / [ ] Fail | |
|
||||
|
||||
## Verification Gate
|
||||
|
||||
| # | Gate Criterion | Pass | Notes |
|
||||
|---|---------------|------|-------|
|
||||
| 1 | [from plan] | [ ] | |
|
||||
| 2 | [from plan] | [ ] | |
|
||||
| ... | | | |
|
||||
|
||||
## Requirements Checklist Verification
|
||||
|
||||
| ID | Requirement | Implemented | Tested | Notes |
|
||||
|----|------------|-------------|--------|-------|
|
||||
| [3.1-1] | [requirement text] | [ ] | [ ] | |
|
||||
| [3.1-2] | [requirement text] | [ ] | [ ] | |
|
||||
| ... | | | | |
|
||||
|
||||
## Design Constraints Checklist Verification
|
||||
|
||||
| ID | Constraint | Respected | Notes |
|
||||
|----|-----------|-----------|-------|
|
||||
| KDD-xxx-N | [constraint] | [ ] | |
|
||||
| CD-xxx-N | [constraint] | [ ] | |
|
||||
| ... | | | |
|
||||
|
||||
## Post-Phase Review
|
||||
|
||||
| Review Step | Date | Result | Findings |
|
||||
|------------|------|--------|----------|
|
||||
| Codex: Implementation vs. Plan | | [ ] Pass / [ ] Pass with corrections / [ ] Skipped | |
|
||||
| Codex: Code quality | | [ ] Pass / [ ] Pass with corrections / [ ] Skipped | |
|
||||
|
||||
## Questions Logged During Execution
|
||||
|
||||
| # | Question | Logged to questions.md | Resolution |
|
||||
|---|----------|----------------------|------------|
|
||||
| | | | |
|
||||
|
||||
## Summary
|
||||
|
||||
- **Total WPs**: N
|
||||
- **Tests written**: N unit, N integration, N negative
|
||||
- **Tests passing**: N/N
|
||||
- **Requirements verified**: N/N
|
||||
- **Design constraints verified**: N/N
|
||||
- **Questions logged**: N
|
||||
- **Codex review**: [outcome]
|
||||
```
|
||||
|
||||
When starting a phase, the executor:
|
||||
1. Creates the checklist file from this template, populated with the phase's actual WPs, gate criteria, requirements, and constraints.
|
||||
2. Updates the checklist as each WP is completed.
|
||||
3. Fills in the verification sections during the completion gate.
|
||||
4. Commits the final checklist alongside the last phase commit.
|
||||
|
||||
---
|
||||
|
||||
## File Index
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `docs/plans/generate_plans.md` | This document — master plan for generating implementation plans |
|
||||
| `docs/plans/generate_plans.md` | This document — master plan, generation procedure, and execution procedure |
|
||||
| `docs/plans/requirements-traceability.md` | Matrix linking every requirement to its implementation phase |
|
||||
| `docs/plans/questions.md` | Questions requiring follow-up before or during implementation |
|
||||
| `docs/plans/phase-0-solution-skeleton.md` | (To be generated) |
|
||||
| `docs/plans/phase-1-central-foundations.md` | (To be generated) |
|
||||
| `docs/plans/phase-2-modeling-validation.md` | (To be generated) |
|
||||
| `docs/plans/phase-3a-runtime-foundation.md` | (To be generated) |
|
||||
| `docs/plans/phase-3b-site-io-observability.md` | (To be generated) |
|
||||
| `docs/plans/phase-3c-deployment-store-forward.md` | (To be generated) |
|
||||
| `docs/plans/phase-4-operator-ui.md` | (To be generated) |
|
||||
| `docs/plans/phase-5-authoring-ui.md` | (To be generated) |
|
||||
| `docs/plans/phase-6-deployment-ops-ui.md` | (To be generated) |
|
||||
| `docs/plans/phase-7-integrations.md` | (To be generated) |
|
||||
| `docs/plans/phase-8-production-readiness.md` | (To be generated) |
|
||||
| **Implementation Plans** | |
|
||||
| `docs/plans/phase-0-solution-skeleton.md` | Generated |
|
||||
| `docs/plans/phase-1-central-foundations.md` | Generated |
|
||||
| `docs/plans/phase-2-modeling-validation.md` | Generated |
|
||||
| `docs/plans/phase-3a-runtime-foundation.md` | Generated |
|
||||
| `docs/plans/phase-3b-site-io-observability.md` | Generated |
|
||||
| `docs/plans/phase-3c-deployment-store-forward.md` | Generated |
|
||||
| `docs/plans/phase-4-operator-ui.md` | Generated |
|
||||
| `docs/plans/phase-5-authoring-ui.md` | Generated |
|
||||
| `docs/plans/phase-6-deployment-ops-ui.md` | Generated |
|
||||
| `docs/plans/phase-7-integrations.md` | Generated |
|
||||
| `docs/plans/phase-8-production-readiness.md` | Generated |
|
||||
| **Execution Checklists** (created when each phase begins) | |
|
||||
| `docs/plans/phase-0-checklist.md` | Phase 0 execution tracking |
|
||||
| `docs/plans/phase-1-checklist.md` | Phase 1 execution tracking |
|
||||
| `docs/plans/phase-2-checklist.md` | Phase 2 execution tracking |
|
||||
| `docs/plans/phase-3a-checklist.md` | Phase 3A execution tracking |
|
||||
| `docs/plans/phase-3b-checklist.md` | Phase 3B execution tracking |
|
||||
| `docs/plans/phase-3c-checklist.md` | Phase 3C execution tracking |
|
||||
| `docs/plans/phase-4-checklist.md` | Phase 4 execution tracking |
|
||||
| `docs/plans/phase-5-checklist.md` | Phase 5 execution tracking |
|
||||
| `docs/plans/phase-6-checklist.md` | Phase 6 execution tracking |
|
||||
| `docs/plans/phase-7-checklist.md` | Phase 7 execution tracking |
|
||||
| `docs/plans/phase-8-checklist.md` | Phase 8 execution tracking |
|
||||
|
||||
Reference in New Issue
Block a user