# 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.