diff --git a/docs/ver1/ver1-step1-2-carry-forward-checklist.md b/docs/ver1/ver1-step1-2-carry-forward-checklist.md new file mode 100644 index 0000000..0a7567b --- /dev/null +++ b/docs/ver1/ver1-step1-2-carry-forward-checklist.md @@ -0,0 +1,73 @@ +# Ver1 Step 1/2 Carry-Forward Checklist + +## Purpose + +Track open Step 1 and Step 2 follow-ups through later V1 steps, with lightweight verification evidence and requirement traceability. + +This artifact implements the carry-forward approach defined in: +- `docs/ver1/ver1-step1-2_revised.md` + +Historical records remain unchanged: +- `docs/ver1/ver1-step1.md` +- `docs/ver1/ver1-step1-results.md` +- `docs/ver1/ver1-step2.md` +- `docs/ver1/ver1-step2-results.md` + +--- + +## Status Legend + +- `not started` +- `in progress` +- `done` +- `deferred` + +--- + +## Carry-Forward Mapping Matrix + +| ID | Carry-Forward Task | Source | Related REQ | Owning V1 Step(s) | Validation Method | Status | Evidence Link/Note | +| --- | --- | --- | --- | --- | --- | --- | --- | +| CF-A1 | Confirm remaining implicit/global runtime ownership and lift only high-impact resources to lifespan ownership | Step 1 residual follow-up | REQ-7 | Step 3, Step 9 | Inspection + test | not started | | +| CF-A2 | Finalize migration + rollback runbook usage and rehearse on representative local data | Step 1 residual follow-up | REQ-10 | Step 4, Step 9 | Demonstration + test | not started | | +| CF-A3 | Maintain lightweight boundary enforcement (review checklist and/or simple import checks) | Step 1 residual follow-up | REQ-7, REQ-11 | Step 3, Step 7 | Inspection | not started | | +| CF-B1 | Build compact error-path inventory for major failure paths and category mapping | Step 2 governance follow-up | REQ-2, REQ-3, REQ-4, REQ-5 | Step 6, Step 7 | Inspection | not started | Use `docs/ver1/ver1-step2-error-path-inventory.md` | +| CF-B2 | Standardize required logging fields at critical boundary handoffs | Step 2 residual follow-up | REQ-3, REQ-4, REQ-8 | Step 6 | Inspection + test | not started | | +| CF-B3 | Revisit retry backoff strategy only if observed runtime behavior justifies extra complexity | Step 2 residual follow-up | REQ-2, REQ-6 | Step 6, Step 8 | Analysis + test | deferred | Keep fixed backoff unless evidence suggests change | +| CF-C1 | Integrate Step 1/2 completed outcomes and open follow-ups into V1 traceability tracking | Revision-plan workstream | REQ-0..REQ-12 (traceability) | Step 3, Step 10 | Inspection | in progress | This checklist is the initial integration artifact | +| CF-C2 | Keep carry-forward routing aligned with revised V1 plan (architecture via 3/4/9, reliability via 6/7) | Revision-plan workstream | REQ-0..REQ-12 (execution alignment) | Step 3+ | Inspection | in progress | Routing established in this matrix | + +--- + +## Execution Notes + +### Step 3 (Functional Completion) +- Use CF-A1 and CF-A3 during requirement-slice implementation reviews. +- Record any discovered boundary/runtime ownership gaps in this checklist. + +### Step 4 (Data Model and Migration Safety) +- Execute CF-A2 rehearsal and link evidence (commands, runbook notes, outcomes). + +### Step 6 (Minimal Observability & Operability) +- Execute CF-B1 and CF-B2 with focused artifacts and log-field verification. + +### Step 7 (Test Coverage and Practical Quality Gates) +- Add/verify tests supporting CF-A3 and CF-B1/B2 where meaningful. + +### Step 8 (Performance Validation) +- Reassess CF-B3 only if retries/backoff are observed to cause practical issues. + +### Step 9 (Release Readiness) +- Reconfirm CF-A1/A2 readiness in release checklist and rollback drill. + +### Step 10 (Documentation Completion) +- Ensure final V1 docs reference outcomes from this checklist where relevant. + +--- + +## Acceptance Check for Carry-Forward Completion + +- [ ] Historical Step 1/2 documents remain unchanged. +- [ ] Every open Step 1/2 follow-up has an owning V1 step and validation method. +- [ ] Evidence links are recorded for each completed carry-forward item. +- [ ] No carry-forward item introduces unnecessary complexity for personal-scale operation. diff --git a/docs/ver1/ver1-step1-2_revised.md b/docs/ver1/ver1-step1-2_revised.md new file mode 100644 index 0000000..9c350e3 --- /dev/null +++ b/docs/ver1/ver1-step1-2_revised.md @@ -0,0 +1,166 @@ +# 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. \ No newline at end of file diff --git a/docs/ver1/ver1-step2-error-path-inventory.md b/docs/ver1/ver1-step2-error-path-inventory.md new file mode 100644 index 0000000..aff39fc --- /dev/null +++ b/docs/ver1/ver1-step2-error-path-inventory.md @@ -0,0 +1,42 @@ +# Ver1 Step 2 Error-Path Inventory (Carry-Forward) + +## Purpose + +Provide a compact inventory of major failure paths with taxonomy mapping and retry behavior, aligned with: +- `docs/error_handling.md` +- `docs/ver1/ver1-step2-results.md` +- `docs/ver1/ver1-step1-2-carry-forward-checklist.md` (CF-B1) + +This is a lightweight operational artifact for Step 6/7 follow-through. + +--- + +## Inventory Table + +| Path ID | Boundary/Operation | Typical Failure Source | Category | Retriable | Surface Behavior | Current Coverage | Notes | +| --- | --- | --- | --- | --- | --- | --- | --- | +| EP-API-001 | API upload request validation | invalid payload / empty file metadata | `validation_error` | no | structured API error envelope (400) | partial | confirm all upload variants | +| EP-API-002 | API resource lookup | missing job/document | `not_found_error` | no | structured API error envelope (404) | partial | verify consistency for all lookup routes | +| EP-SVC-001 | Service provider-call mapping | provider SDK/HTTP failure | `external_provider_error` | sometimes | normalized AppError and safe message | partial | ensure consistent mapping in service boundary tests | +| EP-WKR-001 | Worker provider timeout | timeout/unavailable upstream | `external_provider_error` or `infrastructure_transient_error` | yes | retry or terminal failed with persisted reason | partial | validate category mapping remains deterministic | +| EP-WKR-002 | Worker non-retriable domain/input failure | deterministic invalid input/state | `user_input_error` or `conflict_error` | no | immediate terminal failed with persisted reason | partial | ensure no retry on non-retriable categories | +| EP-WKR-003 | Worker retry exhaustion | repeated retriable failure | category from source; terminal state | capped then no | explicit failed status + error detail | met | implemented in Step 2; keep regression coverage | +| EP-UI-001 | UI upload action failure | surfaced AppError or fallback exception | category-based safe user message | category-driven | title + message + suggestion + error id | partial | verify consistency on all primary UI actions | +| EP-LOG-001 | Cross-boundary error logging | missing/uneven fields | n/a | n/a | logs include `error_id`, `category`, `operation`, ids when available | partial | complete in Step 6 (CF-B2) | + +--- + +## Verification Targets (Step 6/7) + +1. Every critical path has category + retriable policy defined. +2. API/UI behavior remains safe and actionable. +3. Worker terminal failures are explicit and persisted. +4. Logging fields are consistent at critical handoffs. + +--- + +## Evidence Links + +- Step 2 implementation results: `docs/ver1/ver1-step2-results.md` +- Carry-forward tracking: `docs/ver1/ver1-step1-2-carry-forward-checklist.md` +- Canonical contract: `docs/error_handling.md` diff --git a/docs/ver1/ver1.md b/docs/ver1/ver1.md index 0f754a4..d60f578 100644 --- a/docs/ver1/ver1.md +++ b/docs/ver1/ver1.md @@ -23,7 +23,9 @@ The objective is to deliver the full scoped product with readiness for reliable ### Deliverables - `docs/ver1/ver1.md` (this plan) -- V1 traceability artifact (linked from here when created) +- V1 traceability artifact: + - `docs/ver1/ver1-step1-2-carry-forward-checklist.md` + - `docs/ver1/ver1-step2-error-path-inventory.md` (supporting artifact) ### Exit Criteria - Every in-scope requirement has explicit status and validation evidence.