generated from john/python-template
166 lines
6.3 KiB
Markdown
166 lines
6.3 KiB
Markdown
# Ver1 Step 1 & Step 2 Revision Plan (Additive)
|
|
|
|
## Purpose
|
|
|
|
Define a **targeted implementation follow-through plan** for Step 1 and Step 2 outcomes so remaining V1 work stays aligned with `docs/ver1/ver1.md`:
|
|
|
|
- personal-scale operation
|
|
- single operator
|
|
- private-network assumptions
|
|
- low operational overhead
|
|
- practical, testable controls
|
|
|
|
This document is additive and does **not** replace or revise historical Step 1/Step 2 records.
|
|
|
|
---
|
|
|
|
## Source Documents Reviewed
|
|
|
|
- `docs/ver1/ver1.md`
|
|
- `docs/ver1/ver1-step1.md`
|
|
- `docs/ver1/ver1-step1-results.md`
|
|
- `docs/ver1/ver1-step2.md`
|
|
- `docs/ver1/ver1-step2-results.md`
|
|
- `docs/architecture.md`
|
|
- `docs/error_handling.md`
|
|
- `docs/requirements.md`
|
|
- `docs/index.md`
|
|
- `docs/intent.md`
|
|
|
|
---
|
|
|
|
## Revision Goals
|
|
|
|
1. Preserve all completed Step 1/Step 2 technical hardening work.
|
|
2. Keep historical Step 1/Step 2 documents unchanged.
|
|
3. Convert residual risks/follow-ups into concrete implementation tasks for subsequent V1 steps.
|
|
4. Preserve traceability to requirements and implemented evidence.
|
|
5. Maintain alignment with personal-scale architecture and operating model.
|
|
|
|
---
|
|
|
|
## Scope
|
|
|
|
### In Scope
|
|
- Define carry-forward implementation tasks based on Step 1/2 residual risks and open items.
|
|
- Map carry-forward tasks to later V1 steps (especially Steps 3, 4, 6, 7, and 9).
|
|
- Define lightweight verification evidence expected for each carry-forward task.
|
|
- Update V1 traceability references to include completed Step 1/2 outcomes and deferred follow-ups.
|
|
|
|
### Out of Scope
|
|
- Simplifying tone/structure of existing Step 1/2 documents
|
|
- Clarifying or rewriting historical Step 1/2 plan/results content
|
|
- Editing `docs/ver1/ver1-step1.md`
|
|
- Editing `docs/ver1/ver1-step1-results.md`
|
|
- Editing `docs/ver1/ver1-step2.md`
|
|
- Editing `docs/ver1/ver1-step2-results.md`
|
|
- Re-implementing Step 1/2 code changes
|
|
- Rewriting `docs/ver1/ver1.md`
|
|
- Deleting historical sections/results
|
|
- Altering requirements IDs or architecture principles
|
|
|
|
---
|
|
|
|
## Carry-Forward Implementation Plan
|
|
|
|
## Workstream A — Close Step 1 follow-ups through later V1 steps
|
|
|
|
### A1) Runtime ownership completion (REQ-7 continuity)
|
|
- Confirm whether any remaining runtime resources still use implicit/global ownership.
|
|
- Move only high-impact remaining resources to explicit lifespan ownership when needed.
|
|
- Keep ownership model simple and documented.
|
|
|
|
### A2) Schema/migration operations readiness (REQ-10 continuity)
|
|
- Finalize practical migration + rollback runbook usage in Step 4 execution.
|
|
- Rehearse upgrade and rollback on representative local data.
|
|
- Keep production startup free from implicit schema mutation.
|
|
|
|
### A3) Boundary enforcement (lightweight only)
|
|
- Keep architecture boundary checks lightweight (review checklist and/or simple import checks).
|
|
- Avoid heavy governance tooling unless clear recurring drift appears.
|
|
|
|
### Expected Outcome
|
|
Step 1 architecture hardening remains intact and is completed pragmatically where open items remain.
|
|
|
|
---
|
|
|
|
## Workstream B — Close Step 2 follow-ups through later V1 steps
|
|
|
|
### B1) Error-path inventory and coverage visibility
|
|
- Create a compact error-path inventory artifact (or equivalent matrix section) covering major failure paths.
|
|
- Ensure each critical path maps to category, retriable policy, and surfaced behavior.
|
|
|
|
### B2) Logging field consistency at key boundaries
|
|
- Standardize required fields at critical failure handoffs (`error_id`, `category`, `operation`, identifiers when available).
|
|
- Prioritize worker/API/service boundaries first.
|
|
|
|
### B3) Retry policy refinement (only if needed)
|
|
- Keep current bounded retry baseline.
|
|
- Revisit richer backoff strategy only if observed behavior justifies added complexity.
|
|
|
|
### Expected Outcome
|
|
Step 2 reliability behavior stays stable, diagnosable, and right-sized for personal-scale operation.
|
|
|
|
---
|
|
|
|
## Workstream C — Integrate Step 1/2 outputs into ongoing V1 governance
|
|
|
|
### C1) Traceability integration
|
|
- Link completed Step 1/2 outcomes and deferred follow-ups to the V1 traceability matrix.
|
|
- Ensure open follow-ups have owning step and validation method.
|
|
|
|
### C2) Execution alignment with revised V1 plan
|
|
- Route architecture follow-ups primarily through Steps 3/4/9.
|
|
- Route reliability/diagnostics follow-ups primarily through Steps 6/7.
|
|
|
|
### Expected Outcome
|
|
Step 1/2 work is fully carried forward without revising historical documents.
|
|
|
|
## Deliverables
|
|
|
|
1. This document (`docs/ver1/ver1-step1-2_revised.md`) as the carry-forward implementation plan.
|
|
2. A compact Step 1/2 carry-forward checklist linked to V1 steps and validation methods.
|
|
3. Traceability updates showing where each open Step 1/2 follow-up will be closed.
|
|
4. Optional new artifact for error-path inventory (if created during Step 6/7 execution).
|
|
|
|
---
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Historical Step 1/Step 2 documents remain unchanged.
|
|
- Open Step 1/2 follow-ups are explicitly mapped to later V1 steps with validation expectations.
|
|
- No loss of core technical intent (REQ-7, REQ-10, error taxonomy, retry safety, traceability).
|
|
- No conflicts introduced with `docs/architecture.md`, `docs/error_handling.md`, or `docs/ver1/ver1.md`.
|
|
- Carry-forward tasks remain right-sized for personal-scale operation.
|
|
|
|
---
|
|
|
|
## Implementation Order
|
|
|
|
1. Keep existing Step 1/Step 2 docs unchanged as historical records.
|
|
2. Define carry-forward tasks and owning V1 steps in this document.
|
|
3. Create and maintain carry-forward traceability artifacts:
|
|
- `docs/ver1/ver1-step1-2-carry-forward-checklist.md`
|
|
- `docs/ver1/ver1-step2-error-path-inventory.md`
|
|
4. Execute carry-forward tasks during Steps 3+ and capture evidence in step results docs.
|
|
5. Perform final consistency pass across `docs/ver1/*` references.
|
|
|
|
---
|
|
|
|
## Risks and Mitigations
|
|
|
|
1. **Risk:** Open Step 1/2 items are forgotten as Step 3+ work proceeds.
|
|
**Mitigation:** Track each follow-up in the V1 traceability matrix with owning step and evidence expectation.
|
|
|
|
2. **Risk:** Carry-forward work expands beyond personal-scale needs.
|
|
**Mitigation:** Apply simplicity guardrails from `docs/architecture.md` before accepting additional hardening tasks.
|
|
|
|
3. **Risk:** Reliability follow-ups become fragmented across multiple steps.
|
|
**Mitigation:** Keep one consolidated carry-forward checklist and update it at milestone check-ins.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
This revision effort is scope-alignment and implementation-follow-through focused.
|
|
Historical Step 1/Step 2 documents are intentionally preserved as-is. |