From e8a4a60aac747284e755981981528c902a252edd Mon Sep 17 00:00:00 2001 From: vib-tools Date: Thu, 23 Jul 2026 18:21:12 -0700 Subject: [PATCH 1/4] docs(baseline): prepare controlled baseline candidate --- BASELINE_MANIFEST.yml | 68 +++++++++------- CHANGELOG.md | 21 +++++ DEPENDENCIES.md | 30 +++++++ NEXT_ASSIGNMENT.md | 23 ++++-- PROJECT_STATUS.md | 47 ++++++----- README.md | 60 ++++++-------- docs/00-governance/RISK_REGISTER.md | 16 ++-- docs/01-product/ACCEPTANCE_METRICS.md | 14 ++-- docs/01-product/REQUIREMENTS.md | 29 ++++--- .../02-architecture/COMPONENT_ARCHITECTURE.md | 21 +++++ .../02-architecture/CONTAINER_ARCHITECTURE.md | 14 ++++ docs/02-architecture/DATA_ARCHITECTURE.md | 34 ++++++++ docs/02-architecture/EXECUTION_ENGINE.md | 19 +++++ docs/02-architecture/PROVIDER_PLATFORM.md | 20 +++++ docs/02-architecture/QUALITY_ATTRIBUTES.md | 14 ++-- docs/02-architecture/SECURITY_ARCHITECTURE.md | 21 +++++ docs/02-architecture/SYSTEM_CONTEXT.md | 15 ++++ docs/03-ux/ACCESSIBILITY.md | 5 ++ docs/03-ux/DESIGN_SYSTEM.md | 5 ++ docs/03-ux/ERROR_LANGUAGE.md | 11 +++ docs/03-ux/INFORMATION_ARCHITECTURE.md | 19 +++++ docs/03-ux/UX_PRINCIPLES.md | 10 +++ docs/04-engineering/CODING_STANDARDS.md | 5 ++ docs/04-engineering/DEPENDENCY_POLICY.md | 5 ++ docs/04-engineering/GIT_WORKFLOW.md | 5 ++ docs/04-engineering/PACKAGING_STRATEGY.md | 5 ++ docs/04-engineering/PROJECT_STRUCTURE.md | 24 ++++++ docs/04-engineering/RELEASE_STRATEGY.md | 5 ++ docs/04-engineering/TESTING_STRATEGY.md | 7 ++ docs/05-operations/BACKUP_AND_RECOVERY.md | 5 ++ docs/05-operations/DIAGNOSTICS.md | 5 ++ docs/05-operations/INCIDENT_RESPONSE.md | 5 ++ docs/05-operations/SUPPORT_RUNBOOK.md | 10 +++ docs/phase-0c/ADR_DISPOSITION_REGISTER.md | 79 +++++++++++++++++++ docs/phase-0c/BASELINE_APPROVAL_PACKET.md | 75 ++++++++++++++++++ .../DEPENDENCY_DISPOSITION_REGISTER.md | 21 +++++ docs/phase-0c/EVIDENCE_INVENTORY.md | 22 ++++++ docs/phase-0c/OPEN_DECISIONS.md | 14 ++++ docs/phase-0c/README.md | 41 ++++++++++ .../REQUIREMENTS_DISPOSITION_REGISTER.md | 25 ++++++ docs/phase-0c/TRACEABILITY_MATRIX.md | 43 ++++++++++ docs/reviews/PHASE_0B3_APPROVAL_RECORD.md | 23 ++++++ docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md | 36 +++++++++ 43 files changed, 854 insertions(+), 122 deletions(-) create mode 100644 DEPENDENCIES.md create mode 100644 docs/02-architecture/COMPONENT_ARCHITECTURE.md create mode 100644 docs/02-architecture/CONTAINER_ARCHITECTURE.md create mode 100644 docs/02-architecture/DATA_ARCHITECTURE.md create mode 100644 docs/02-architecture/EXECUTION_ENGINE.md create mode 100644 docs/02-architecture/PROVIDER_PLATFORM.md create mode 100644 docs/02-architecture/SECURITY_ARCHITECTURE.md create mode 100644 docs/02-architecture/SYSTEM_CONTEXT.md create mode 100644 docs/03-ux/ACCESSIBILITY.md create mode 100644 docs/03-ux/DESIGN_SYSTEM.md create mode 100644 docs/03-ux/ERROR_LANGUAGE.md create mode 100644 docs/03-ux/INFORMATION_ARCHITECTURE.md create mode 100644 docs/03-ux/UX_PRINCIPLES.md create mode 100644 docs/04-engineering/CODING_STANDARDS.md create mode 100644 docs/04-engineering/DEPENDENCY_POLICY.md create mode 100644 docs/04-engineering/GIT_WORKFLOW.md create mode 100644 docs/04-engineering/PACKAGING_STRATEGY.md create mode 100644 docs/04-engineering/PROJECT_STRUCTURE.md create mode 100644 docs/04-engineering/RELEASE_STRATEGY.md create mode 100644 docs/04-engineering/TESTING_STRATEGY.md create mode 100644 docs/05-operations/BACKUP_AND_RECOVERY.md create mode 100644 docs/05-operations/DIAGNOSTICS.md create mode 100644 docs/05-operations/INCIDENT_RESPONSE.md create mode 100644 docs/05-operations/SUPPORT_RUNBOOK.md create mode 100644 docs/phase-0c/ADR_DISPOSITION_REGISTER.md create mode 100644 docs/phase-0c/BASELINE_APPROVAL_PACKET.md create mode 100644 docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md create mode 100644 docs/phase-0c/EVIDENCE_INVENTORY.md create mode 100644 docs/phase-0c/OPEN_DECISIONS.md create mode 100644 docs/phase-0c/README.md create mode 100644 docs/phase-0c/REQUIREMENTS_DISPOSITION_REGISTER.md create mode 100644 docs/phase-0c/TRACEABILITY_MATRIX.md create mode 100644 docs/reviews/PHASE_0B3_APPROVAL_RECORD.md create mode 100644 docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md diff --git a/BASELINE_MANIFEST.yml b/BASELINE_MANIFEST.yml index b2af408..19af86d 100644 --- a/BASELINE_MANIFEST.yml +++ b/BASELINE_MANIFEST.yml @@ -1,41 +1,51 @@ project: name: OpenInvoice - status: windows_packaging_remediation + repository: vibtools/OpenInvoice + baseline: - version: 0.1.0-draft - status: draft - architecture_changes_require_acr: true - ai_can_approve_changes: false - direct_push_to_main: false -validation: - phase_0a_gate: approved - phase_0b_gate: approved_with_conditions - phase_0b1_gate: remediation_required - phase_0b2_gate: not_approved - phase_0b3_status: blocked - target_windows_validation_complete: false - current_phase: 0B.3 + version: 1.0.0-candidate.1 + status: candidate + prepared_from_commit: 4cfc3cb5de400d4459cc5fd691a208abc185018f + prepared_at: 2026-07-23 + human_approval_required: true + +phase_gates: + phase_0a: approved + phase_0b: approved_with_conditions + phase_0b1: remediation_required + phase_0b2: not_approved + phase_0b3: approved_by_human + phase_0c: ready_for_human_review + +evidence: + phase_0b3_source_integration: repository_verified + phase_0b3_windows_validation: human_attested + phase_0b3_independent_reexecution_in_phase_0c: false + architecture: - domain_model: [workspace, run, job, attempt] - workspace_isolation: required + domain_model: + - workspace + - run + - job + - attempt + workspace_isolation: hybrid_control_and_workspace_databases execution_model: global_bounded_engine queue_model: workspace_scoped_logical_queues - database_direction: hybrid_control_and_workspace provider_model: capability_based_adapter run_configuration: immutable_snapshot secrets: operating_system_credential_vault + scheduler_boundary: trigger_only + uncertain_outcomes: reconcile_before_retry + packaging: windows_onedir ui_pattern: workflow_oriented_progressive_disclosure + +governance: + architecture_changes_require_acr: true + ai_can_approve_changes: false + direct_push_to_main: false + baseline_tag_authorized: false + implementation: production_code_allowed: false - disposable_spike_code_allowed: true - dependency_adoption_allowed: false - candidate_runtime_dependencies: - tzdata: - status: proposed - purpose: reliable_iana_timezone_support_on_windows - production_adoption: pending_phase_0c_human_approval - current_phase: phase_0b3 -governance: - human_approval_required: true - architecture_change_implemented: false - phase_0b3_gate_recommendation: blocked_pending_target_windows_execution + next_phase_authorized: false + production_lockfile_allowed: false diff --git a/CHANGELOG.md b/CHANGELOG.md index ae8c482..ae9cc2b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,3 +35,24 @@ - Credential validation remains synthetic only and requires deletion plus secret scanning. - No real credentials, customer data, provider operations, executables, databases, build output, or virtual environments are included in the update package. + + +### Phase 0C candidate + +#### Added + +- Controlled architecture, UX, engineering, security, operations, evidence, dependency, and traceability documentation. +- Phase 0B.3 human approval record with explicit evidence classification. +- Baseline approval packet for candidate `1.0.0-candidate.1`. +- Phase 0C overview and exact evidence-taxonomy documentation. + +#### Changed + +- Reconciled preparation-state Phase 0B.3 status with the later Human Architecture Owner approval. +- Advanced project metadata to Phase 0C candidate status without authorizing production implementation. +- Reconciled the requirements catalog to Approved, Proposed, Deferred and Rejected statuses. +- Preserved historical Phase 0B.3 blocked reports while recording the later human approval separately. + +#### Security + +- Consolidated fail-closed credential storage, redaction, diagnostic minimization, plugin restriction, and uncertain-outcome rules. diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md new file mode 100644 index 0000000..b202268 --- /dev/null +++ b/DEPENDENCIES.md @@ -0,0 +1,30 @@ +# Dependency Candidate Summary + +This file summarizes Phase 0C dependency dispositions. It does not approve versions, create a lockfile or authorize production installation. + +## Candidate for next phase + +- PyInstaller — Windows `onedir` packaging tooling. +- pytest — development test runner. +- Ruff — lint/format tooling. +- uv — environment and future lock management. +- SQLAlchemy — persistence evaluation within infrastructure. +- Alembic — migration evaluation and ownership. +- HTTPX — provider transport evaluation behind adapters. + +## Conditional candidate + +- CustomTkinter — UI shell only; bounded data views and accessibility gates required. +- keyring — OS vault only; fail-closed source and packaged tests required. +- tzdata — Windows IANA timezone data; packaged resolution and update review required. +- APScheduler — schedule trigger only; never the durable invoice job engine. + +## Deferred + +- SQLModel — deferred until the SQLAlchemy persistence walking skeleton proves a concrete need; it may never become the domain model. + +## Spike/test only + +- psutil — retained for validation and diagnostics experiments only unless a future approved requirement justifies runtime use. + +Detailed license, boundary, evidence, security, packaging, upgrade and replacement information is in [Dependency Disposition Register](docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md). diff --git a/NEXT_ASSIGNMENT.md b/NEXT_ASSIGNMENT.md index 29acc44..9981a5e 100644 --- a/NEXT_ASSIGNMENT.md +++ b/NEXT_ASSIGNMENT.md @@ -1,13 +1,22 @@ # Next Assignment -## Phase 0B.3 remediation continuation - target-Windows execution +## Phase 1 — Repository Governance and CI Foundation -Phase 0C is not authorized. +**Status: Blocked until explicit Phase 0C baseline approval.** -Run from the authoritative OpenInvoice repository root: +After the Human Architecture Owner approves the Phase 0C candidate through a separate controlled action, Phase 1 may establish: -```powershell -powershell -ExecutionPolicy Bypass -File .\spikes\phase_0b1\run_windows_validation.ps1 -``` +- protected branch and repository rules; +- CODEOWNERS, pull-request and issue templates; +- CI bootstrap and deterministic documentation checks; +- secret scanning, dependency review, license checks, and SBOM direction; +- approved Python/build-tool baseline and lockfile workflow; +- architecture-fitness test scaffolding. -Review the packaging gate evidence and all `WIN-01` through `WIN-07` result files. Phase 0C may be proposed only when every mandatory track is `Completed` or `Completed with warnings`, packaged credential cleanup passes, packaged timezone resolution passes, scheduler restart deduplication passes, and the Human Architecture Owner approves the evidence gate. +Phase 1 must not begin merely because this candidate package was applied or merged. The approval action must separately: + +1. record accepted/revised/rejected ADR dispositions; +2. record dependency decisions; +3. change baseline status from `candidate` to `approved`; +4. authorize `baseline-v1.0.0`; +5. set `production_code_allowed` or next-phase authorization as explicitly approved. diff --git a/PROJECT_STATUS.md b/PROJECT_STATUS.md index e0d1423..8bdb89b 100644 --- a/PROJECT_STATUS.md +++ b/PROJECT_STATUS.md @@ -4,28 +4,37 @@ |---|---| | Project | OpenInvoice | | Repository | `vibtools/OpenInvoice` | -| Current phase | Phase 0B.3 - Windows Packaging Pipeline Remediation | -| Phase status | Blocked pending target-Windows execution | +| Source commit | `4cfc3cb5de400d4459cc5fd691a208abc185018f` | +| Current phase | Phase 0C — Controlled Baseline Candidate | | Phase 0A | Approved | | Phase 0B | Approved with conditions | | Phase 0B.1 | Remediation required | -| Phase 0B.2 | Not approved; package structure accepted | -| Complete baseline | Draft | -| Architecture change implemented | No | +| Phase 0B.2 | Not approved; remediation continued | +| Phase 0B.3 | Approved by Human Architecture Owner | +| Candidate baseline | `1.0.0-candidate.1` | +| Baseline status | Ready for Human Architecture Owner Review | | Production code | Not started | -| Candidate dependency | `tzdata` proposed; Phase 0C decision required | -| Next gate | Complete packaging gate and seven-track Windows regression | +| Baseline tag | Not created | +| Phase 1 | Not authorized | -## Phase 0B.3 preparation +## Evidence classification -- [x] Canonical GitHub repository verified. -- [x] Merged package baseline reconstructed. -- [x] Unique build-directory and copied-launch strategy implemented. -- [x] Deterministic process lifecycle checks implemented. -- [x] Minimal Tcl/Tk packaging diagnostic implemented. -- [x] Controlled Tcl/Tk fallback sequence implemented. -- [x] Packaged credential/timezone/scheduler probes implemented. -- [x] Static package validation completed. -- [ ] Target-Windows packaging gate executed. -- [ ] Full seven-track Windows regression completed. -- [ ] Human Architecture Owner review. +- Repository integration and merge commit: **Repository-verified**. +- Phase 0B.3 final Windows pass: **Human-attested** from a separate validation session. +- Spike outputs: **Machine-verified**, **Documentation-derived**, or **Partially reproducible** as recorded in EVID-001 through EVID-012. +- Preparation-state blocked reports remain historical records; current status is established by the separate approval record. +- Independent rerun of raw Windows evidence during Phase 0C: **Unverified / not claimed**. + +## Phase 0C checklist + +- [x] Phase 0B.3 approval record drafted. +- [x] Evidence inventory prepared. +- [x] Six proposed ADRs reviewed. +- [x] Architecture, UX, engineering, security, and operations candidate documentation consolidated. +- [x] Dependency dispositions prepared without inventing production versions. +- [x] Traceability matrix prepared. +- [x] Candidate manifest generated. +- [ ] Human Architecture Owner approves/revises ADR dispositions. +- [ ] Human Architecture Owner approves/rejects dependency directions. +- [ ] Human Architecture Owner approves/rejects baseline `1.0.0`. +- [ ] Separate approval action authorizes Phase 1 and baseline tag. diff --git a/README.md b/README.md index 3df5725..6b7c743 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,42 @@ # OpenInvoice -OpenInvoice is a planned desktop invoice-operations platform for preparing, validating, scheduling, sending, and reviewing invoice workloads across supported invoice services. +OpenInvoice is a planned Windows desktop invoice-operations platform for preparing, validating, scheduling, sending, and reviewing invoice workloads across supported invoice services. ## Current status -OpenInvoice is currently in **Phase 0A: Project Discovery and Governance**. +OpenInvoice is in **Phase 0C — Controlled Baseline Candidate**. -> No production invoice-processing implementation has been released. Production application code has not started. +> No production invoice-processing implementation has started. The candidate baseline requires explicit Human Architecture Owner approval before Phase 1 is authorized. -The current baseline is **Draft 0.1.0** and requires human Architecture Owner approval before it may be treated as approved. +- Candidate baseline: `1.0.0-candidate.1` +- Source commit: `4cfc3cb5de400d4459cc5fd691a208abc185018f` +- Canonical repository: `vibtools/OpenInvoice` +- Phase 0B.3: human-approved based on an external Windows validation session; repository integration is verified, while raw evidence availability is classified separately. -## Product principles +## Candidate architecture -- Beginner-oriented, workflow-first desktop experience. -- Strong isolation between invoice workspaces. -- Durable execution with explicit recovery and reconciliation. -- Capability-based provider adapters instead of provider-specific core logic. -- Secure operating-system credential storage; no plaintext secrets. -- Human-governed architecture and AI-assisted implementation. +- Isolated Workspaces with separate Run, Job, and Attempt lifecycles. +- `control.db` plus one isolated `workspace.db` per workspace. +- Workspace-scoped logical queues served by a global bounded engine. +- Capability-based provider adapters and operation-level retry safety. +- Immutable run snapshots, durable state, `UNKNOWN` outcomes, and reconciliation before retry. +- Workflow-oriented Standard experience with progressive Advanced controls and separate Diagnostics. +- Windows `onedir` packaging candidate with packaged credential and timezone validation gates. -## Planned high-level workflow +## Baseline review -1. Choose an invoice service. -2. Connect one or more accounts. -3. Add and validate customers. -4. Prepare invoice details and dynamic data. -5. Review and test. -6. Send immediately or schedule a run. -7. Review results and problems requiring attention. +- [Phase 0C Overview](docs/phase-0c/README.md) +- [Baseline Approval Packet](docs/phase-0c/BASELINE_APPROVAL_PACKET.md) +- [Evidence Inventory](docs/phase-0c/EVIDENCE_INVENTORY.md) +- [ADR Disposition Register](docs/phase-0c/ADR_DISPOSITION_REGISTER.md) +- [Dependency Disposition Register](docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md) +- [Traceability Matrix](docs/phase-0c/TRACEABILITY_MATRIX.md) +- [Phase 0C Review Checklist](docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md) -## Documentation +## Governance -- [Project Charter](docs/00-governance/PROJECT_CHARTER.md) -- [Project Constitution](docs/00-governance/PROJECT_CONSTITUTION.md) -- [Baseline Policy](docs/00-governance/BASELINE_POLICY.md) -- [AI Development Policy](docs/00-governance/AI_DEVELOPMENT_POLICY.md) -- [Product Vision](docs/01-product/PRODUCT_VISION.md) -- [Requirements](docs/01-product/REQUIREMENTS.md) -- [Architecture Principles](docs/02-architecture/ARCHITECTURE_PRINCIPLES.md) -- [Architecture Invariants](docs/02-architecture/ARCHITECTURE_INVARIANTS.md) -- [Phase 0A Review Checklist](docs/reviews/PHASE_0A_REVIEW_CHECKLIST.md) - -## Contribution status - -Implementation contributions are not yet open. Documentation changes must follow the governance baseline, use a reviewed branch, and receive human approval. +AI may prepare and recommend this candidate but may not approve the baseline, accept ADRs, create `baseline-v1.0.0`, or authorize implementation. Those actions require a separate explicit human decision. ## License status -A project license has not yet been approved. No licensing claim is made by this Phase 0A baseline. +A project license has not yet been approved. Dependency-license records are review data and do not establish the project license. diff --git a/docs/00-governance/RISK_REGISTER.md b/docs/00-governance/RISK_REGISTER.md index 352b46c..5b1d595 100644 --- a/docs/00-governance/RISK_REGISTER.md +++ b/docs/00-governance/RISK_REGISTER.md @@ -13,8 +13,8 @@ No mitigation is marked complete without evidence. |---|---|---:|---:|---:|---|---|---|---| | RISK-001 | The OpenInvoice name may conflict with an existing product, organization, domain, or trademark. | Medium | High | High | Perform naming, domain, repository, and legal review before public release or branding investment. | Documented search and qualified legal review where required. | Product Owner | Open | | RISK-002 | CustomTkinter may not provide responsive large-table behavior for large customer datasets. | High | High | High | Validate paging or virtualization options before UI baseline approval. | Phase 0B large-data UI spike with measured interaction behavior. | Architecture Owner | Open - Reduced Uncertainty | -| RISK-003 | Windows packaging may fail to preserve assets, configuration, secure storage, or expected startup behavior. | Medium | High | High | Test supported packaging layouts before release architecture is approved. | Phase 0B packaging spike on target Windows environment. | Project Engineer | Open | -| RISK-004 | A secure credential-vault backend may be unavailable or behave differently in a packaged application. | Medium | Critical | High | Require fail-closed behavior and explicit secure-backend verification. | Phase 0B packaged credential-vault spike. | Security Owner / Architecture Owner | Open | +| RISK-003 | Windows packaging may fail to preserve assets, configuration, secure storage, or expected startup behavior. | Medium | High | High | Keep `onedir` packaging, isolated build roots and packaged probes as mandatory engineering gates. | Human-attested Phase 0B.3 validation plus future repeatable packaging smoke tests. | Project Engineer | Open - Reduced Uncertainty | +| RISK-004 | A secure credential-vault backend may be unavailable or behave differently in a packaged application. | Medium | Critical | High | Require fail-closed behavior and explicit source and packaged secure-backend verification. | Human-attested Phase 0B.3 result plus future repeatable credential-vault tests. | Security Owner / Architecture Owner | Open - Reduced Uncertainty | | RISK-005 | SQLite write contention may reduce reliability under concurrent runs. | Medium | High | High | Validate WAL, busy timeout, bounded writers, and transaction patterns. | Phase 0B concurrency stress spike. | Architecture Owner | Mitigating | | RISK-006 | Coordination between `control.db` and workspace databases may leave inconsistent reservations or leases after a crash. | Medium | Critical | High | Use expiring reservations, idempotency, and reconciliation rather than assuming atomic dual writes. | Phase 0B hybrid-database crash-boundary spike. | Architecture Owner | Mitigating | | RISK-007 | Provider idempotency semantics differ or may be unavailable for some operations. | High | Critical | Critical | Model provider-specific capability declarations and reconciliation requirements. | Provider documentation review and Phase 0B uncertain-outcome spike. | Provider Owner | Mitigating | @@ -39,12 +39,16 @@ Every important unresolved TBD in Phase 0A must map to this register or to the o | Risk | Evidence impact | Remaining gap | |---|---|---| | RISK-002 | Headless measurements support bounded paging/windowing and reduce uncertainty about data strategy. | Actual CustomTkinter rendering and Windows interaction remain inconclusive. | -| RISK-003 | Platform preflight blocked safely. | Full Windows packaging execution is still required. | -| RISK-004 | Platform preflight stopped before secret generation. | Windows source and packaged credential-vault behavior remains required. | +| RISK-003 | Phase 0B.3 source integration is repository-verified and final Windows validation is human-attested. | Raw evidence was not independently rerun in Phase 0C; repeatable CI packaging remains required. | +| RISK-004 | Phase 0B.3 approval provides human-attested support for the secure-vault direction. | Source and packaged fail-closed tests remain mandatory in the engineering baseline. | | RISK-005 | WAL plus busy timeout and bounded writer completed 1,400 synthetic writes with zero errors and clean integrity checks. | Revalidate ceilings on Windows and representative disks. | | RISK-006 | Seven hybrid fault scenarios converged through reservation and reconciliation. | Production implementation and multi-workspace stress remain. | | RISK-007 | Official documentation and mock faults confirm operation-specific capability differences. | Sandbox validation remains provider- and operation-specific. | | RISK-008 | Official sources confirm 429 and provider-specific rate-limit signals, but exact quotas remain dynamic or unclear. | Sandbox and observed account behavior required. | | RISK-010 | Timeout-after-success was represented as `UNKNOWN` and reconciled without blind retry. | Real provider reconciliation must be validated. | -| RISK-011 | GUI/accessibility execution was blocked. | Keyboard, focus, contrast, DPI, and assistive technology remain open. | -| RISK-016 | SQLite, coordination, scheduling, and shutdown produced evidence; UI and packaging targets remain incomplete. | No numerical product target is approved yet. | +| RISK-011 | Bounded rendering and the Phase 0B.3 approval reduce uncertainty. | Full keyboard, focus, contrast, DPI and assistive-technology compliance remain open. | +| RISK-016 | SQLite, coordination, scheduling and shutdown have machine evidence; packaging has human-attested approval. | No numerical product target is approved yet; future repeatable performance and recovery tests remain required. | + +## Phase 0C evidence rule + +Human-attested Phase 0B.3 approval reduces uncertainty but does not close packaging, credential, accessibility or performance risks. Closing a risk requires repeatable evidence and an explicit human disposition. The product-name and trademark risk remains open. diff --git a/docs/01-product/ACCEPTANCE_METRICS.md b/docs/01-product/ACCEPTANCE_METRICS.md index f8bac2d..1be7832 100644 --- a/docs/01-product/ACCEPTANCE_METRICS.md +++ b/docs/01-product/ACCEPTANCE_METRICS.md @@ -1,6 +1,6 @@ # Acceptance Metrics -Phase 0A defines metric categories and evidence rules. Numerical targets that depend on technology validation remain unapproved until Phase 0B or later evidence exists. +The controlled-baseline candidate defines metric categories and evidence rules. Numerical targets remain unapproved until the Human Architecture Owner accepts them and repeatable engineering tests exist. ## Product and workflow metrics @@ -57,9 +57,9 @@ Phase 0A defines metric categories and evidence rules. Numerical targets that de A metric is not approved merely because it appears here. Numerical targets require human approval after evidence review. -## Phase 0B observations +## Phase 0B and Phase 0C evidence disposition -These are observations, not approved product targets. +These entries distinguish machine-verified, repository-verified and human-attested support. They are not approved numerical product targets. | Metric | Observation | Disposition | |---|---|---| @@ -67,8 +67,8 @@ These are observations, not approved product targets. | MET-007 | Timeout after mock external success became `UNKNOWN`; lookup either resolved success or remained unknown. | Supporting evidence. | | MET-008 | Forced termination before external start requeued; after external start became `UNKNOWN`. | Supporting evidence. | | MET-011 | Seven cross-database failure scenarios converged and orphaned reservations were detectable. | Supporting evidence. | -| MET-012 | 100,000-record headless strategy test completed, but no UI target can be approved. | Remains TBD. | -| MET-013 | Background event-gap probe completed; no actual Tk event-loop evidence. | Remains TBD. | -| MET-014 | Windows package was not built. | Remains TBD. | +| MET-012 | Headless bounded-rendering evidence exists; the final Phase 0B.3 Windows outcome is human-attested. | Numerical UI targets remain TBD and require repeatable Windows tests. | +| MET-013 | Background event-boundary direction is supported; no Phase 0C independent event-loop rerun is claimed. | Response targets remain TBD. | +| MET-014 | Phase 0B.3 packaging source is repository-verified and the final Windows validation is human-attested. | Startup targets and repeatable CI packaging remain future gates. | | MET-015 | WAL plus 1,000 ms busy timeout and bounded writer completed 1,400 writes without errors in Linux. | Record as environment-specific evidence, not a target. | -| MET-017 | Windows secure-backend test blocked before secret generation. | Remains TBD. | +| MET-017 | The Human Architecture Owner approved the Phase 0B.3 Windows result; Phase 0C did not independently rerun the raw vault test. | Fail-closed source and packaged vault tests remain mandatory release gates. | diff --git a/docs/01-product/REQUIREMENTS.md b/docs/01-product/REQUIREMENTS.md index 1de093a..9d2d323 100644 --- a/docs/01-product/REQUIREMENTS.md +++ b/docs/01-product/REQUIREMENTS.md @@ -4,7 +4,6 @@ - **Approved:** explicitly included in the provided architecture inputs for Phase 0A. - **Proposed:** product direction requiring human confirmation before implementation. -- **Needs Validation:** direction accepted for investigation but exact behavior or target requires evidence. - **Deferred:** not planned for the current approved scope. - **Rejected:** explicitly excluded. @@ -40,11 +39,11 @@ | NFR-001 | Approved | Workspace data isolation shall be a mandatory architecture guarantee. | Cross-workspace access tests fail closed. | | NFR-002 | Approved | Execution shall use bounded concurrency. | Global, provider, account, and operation caps are enforceable. | | NFR-003 | Approved | UI responsiveness shall not depend on executing provider operations on the UI thread. | Long-running operations do not block normal UI interaction. | -| NFR-004 | Needs Validation | The UI shall remain usable with large customer datasets. | Numerical dataset and response targets are TBD - requires Phase 0B spike. | +| NFR-004 | Proposed | The UI shall remain usable with large customer datasets. | Numerical dataset and response targets are TBD - requires Phase 0B spike. | | NFR-005 | Approved | Execution state and audit history shall survive normal application restart. | Recovery tests reconstruct authoritative states. | | NFR-006 | Approved | Logs and diagnostics shall be redacted and must not expose secret values. | Secret-scanning tests detect prohibited values in outputs. | | NFR-007 | Proposed | The architecture shall remain maintainable through explicit layer and provider boundaries. | Architecture fitness tests detect prohibited imports and cycles. | -| NFR-008 | Needs Validation | Windows packaging shall preserve required assets and secure-storage behavior. | Exact packaging approach is TBD - requires Phase 0B spike. | +| NFR-008 | Proposed | Windows packaging shall preserve required assets and secure-storage behavior. | Exact packaging approach is TBD - requires Phase 0B spike. | | NFR-009 | Proposed | The product shall provide structured operational observability and immutable business audit events. | Diagnostics and audit streams remain distinct and traceable. | | NFR-010 | Proposed | Data corruption or partial coordination shall be detectable and recoverable. | Integrity and reconciliation checks identify incomplete reservations, leases, and migrations. | @@ -69,7 +68,7 @@ | UX-004 | Approved | The normal experience shall not be labeled “Beginner Mode.” | User-facing modes use Standard, Advanced, and Diagnostics terminology as applicable. | | UX-005 | Proposed | Error and status language shall be plain, actionable, and consequence-aware. | Representative users can identify the next safe action. | | UX-006 | Proposed | Irreversible sending shall require preflight review and explicit confirmation. | Confirmation includes scope, accounts, problems, and expected operation count. | -| UX-007 | Needs Validation | Keyboard, scaling, contrast, and assistive-technology behavior shall meet approved accessibility targets. | Exact targets are TBD - requires Phase 0B spike and later user testing. | +| UX-007 | Proposed | Keyboard, scaling, contrast, and assistive-technology behavior shall meet approved accessibility targets. | Exact targets are TBD - requires Phase 0B spike and later user testing. | ## Operational requirements @@ -98,11 +97,11 @@ | ID | Status | Assumption | |---|---|---| -| ASM-001 | Needs Validation | Representative users prefer a guided desktop workflow over provider-specific scripts. | -| ASM-002 | Needs Validation | SQLite can satisfy local durability and concurrency needs when used with controlled writers and WAL. | -| ASM-003 | Needs Validation | CustomTkinter can support the approved workflow with acceptable performance and accessibility. | -| ASM-004 | Needs Validation | Provider APIs expose sufficient idempotency or lookup capabilities for safe reconciliation. | -| ASM-005 | Needs Validation | The operating system offers an available secure credential backend in supported installations. | +| ASM-001 | Proposed | Representative users prefer a guided desktop workflow over provider-specific scripts. | +| ASM-002 | Proposed | SQLite can satisfy local durability and concurrency needs when used with controlled writers and WAL. | +| ASM-003 | Proposed | CustomTkinter can support the approved workflow with acceptable performance and accessibility. | +| ASM-004 | Proposed | Provider APIs expose sufficient idempotency or lookup capabilities for safe reconciliation. | +| ASM-005 | Proposed | The operating system offers an available secure credential backend in supported installations. | ## Open questions @@ -119,16 +118,20 @@ ## Phase 0B evidence recommendations -No Approved requirement changed status in Phase 0B. +No previously Approved requirement is downgraded by the Phase 0C candidate. Evidence-sensitive items remain Proposed until explicit human approval. | Requirement | Evidence | Phase 0C recommendation | |---|---|---| | FR-007 | Provider research confirms capabilities vary by operation, not only by provider. | Retain Approved; define operation-level declarations in the architecture baseline. | | FR-010 | Hybrid and provider fault tests represented timeout-after-success as `UNKNOWN` and reconciled before retry. | Retain Approved. | -| NFR-004 | Headless data benchmarks completed, but actual GUI interaction was unavailable. | Keep Needs Validation. | -| NFR-008 | Windows packaging could not run in Linux. | Keep Needs Validation. | +| NFR-004 | Bounded rendering is supported by machine evidence; final usability and accessibility targets remain open. | Retain Proposed and require future measured Windows UI tests. | +| NFR-008 | Source integration is repository-verified; final Windows validation is human-attested. | Retain Proposed until repeatable packaging smoke tests exist in the approved engineering pipeline. | | NFR-010 | Seven hybrid fault scenarios converged. | Consider approving after ADR-0003 review. | | SEC-002 | Direction remains valid, but Windows backend evidence is blocked. | Retain Approved direction; keep implementation gate open. | -| UX-007 | No target-platform accessibility evidence. | Keep Needs Validation. | +| UX-007 | Phase 0B.3 is human-approved, but no full accessibility-compliance claim is supported. | Retain Proposed and require keyboard, scaling, contrast and assistive-technology validation. | | OPS-004 | Bounded shutdown model passed all synthetic criteria. | Consider approving after ADR-0005 review. | | OPS-005 | Durable occurrence and missed-run model passed synthetic criteria. | Consider approving after ADR-0004 review. | + +## Phase 0C status rule + +Requirement statuses in the controlled-baseline candidate are limited to **Approved**, **Proposed**, **Deferred**, and **Rejected**. A Proposed status may still carry a mandatory validation condition; evidence maturity is tracked separately in the Phase 0C evidence inventory and traceability matrix. diff --git a/docs/02-architecture/COMPONENT_ARCHITECTURE.md b/docs/02-architecture/COMPONENT_ARCHITECTURE.md new file mode 100644 index 0000000..0a0fa17 --- /dev/null +++ b/docs/02-architecture/COMPONENT_ARCHITECTURE.md @@ -0,0 +1,21 @@ +# Component Architecture + +## Presentation + +`View → ViewModel/Controller → Application Service`. Tk widgets are updated only on the UI thread from a bounded event queue. + +## Workspace services + +Create/open/archive workspaces, manage customers and invoice definitions, assign accounts, perform preflight, create immutable run snapshots, and query results. + +## Execution services + +A global dispatcher fairly selects from workspace-scoped logical queues. Provider executors are bounded. Job leases, heartbeats, retry classification, account capacity, and shutdown state are explicit. + +## Persistence services + +The control repository stores global references and capacity state. Workspace repositories store workspace payloads and execution history. Cross-database coordination uses reservations and reconciliation rather than assumed atomicity. + +## Provider services + +Each operation declares capabilities and safe behavior. Unsupported or unknown capabilities fail conservatively. diff --git a/docs/02-architecture/CONTAINER_ARCHITECTURE.md b/docs/02-architecture/CONTAINER_ARCHITECTURE.md new file mode 100644 index 0000000..b96dbc4 --- /dev/null +++ b/docs/02-architecture/CONTAINER_ARCHITECTURE.md @@ -0,0 +1,14 @@ +# Container Architecture + +| Container | Responsibility | Data ownership | +|---|---|---| +| Desktop Presentation | Workflow shell, views, ViewModels/controllers, UI event consumption | No authoritative business state | +| Application Services | Commands, queries, preflight, run creation, reports, recovery orchestration | Coordinates transactions and policies | +| Domain | Workspace, Run, Job, Attempt, policies, state transitions, domain events | Technology-independent rules | +| Execution Control Plane | Dispatcher, leases, retries, rate limits, fairness, reconciliation | Durable state through repositories | +| Provider Adapters | Capability declaration, validation, provider calls, error classification, status lookup | Provider references only | +| Persistence | `control.db`, workspace databases, migrations, repositories | Authoritative local state | +| Credential Adapter | OS-vault store/retrieve/delete and fail-closed checks | Secret material outside SQLite | +| Scheduler Adapter | Emits due occurrence signals | Not authoritative for jobs or Runs | + +Dependencies point inward toward application/domain contracts. UI and providers do not directly access each other. diff --git a/docs/02-architecture/DATA_ARCHITECTURE.md b/docs/02-architecture/DATA_ARCHITECTURE.md new file mode 100644 index 0000000..202bf10 --- /dev/null +++ b/docs/02-architecture/DATA_ARCHITECTURE.md @@ -0,0 +1,34 @@ +# Data Architecture + +## Ownership + +### Global control data + +Workspace registry, physical account metadata, credential references, workspace-account assignments, provider registry/health, global rate limits, execution capacity, schedule registry, application settings, plugin metadata, and global audit references. + +### Workspace data + +Customers, custom fields, invoice definitions, template versions, dynamic data, delivery policy, immutable run snapshots, jobs, attempts, recipients, retry history, reports, statistics, audit events, and workspace files. + +## Physical layout + +```text +data/ +├── control.db +└── workspaces// + ├── workspace.db + ├── imports/ + ├── exports/ + ├── attachments/ + └── backups/ +``` + +Paths use internal identifiers, never unsanitized user names. + +## Coordination + +Reserve capacity in `control.db`, claim a job in the workspace database, execute with stable idempotency context, persist the attempt, settle the reservation, and reconcile expired/orphaned states. Reconciliation is idempotent and convergent. + +## SQLite direction + +WAL, foreign keys, explicit busy timeout, short transactions, bounded writers, integrity checks, and application-owned checkpoint behavior are candidate rules. Migrations are versioned and tested against prior schemas. diff --git a/docs/02-architecture/EXECUTION_ENGINE.md b/docs/02-architecture/EXECUTION_ENGINE.md new file mode 100644 index 0000000..70577bb --- /dev/null +++ b/docs/02-architecture/EXECUTION_ENGINE.md @@ -0,0 +1,19 @@ +# Execution Engine + +## State model + +`DRAFT → QUEUED → CLAIMED → RUNNING → SUCCEEDED | RETRY_WAIT | FAILED | CANCELLED | UNKNOWN`. + +`UNKNOWN` means an external outcome cannot be proven and blocks blind retry. + +## Scheduling and fairness + +Workspaces own logical queues. A global bounded dispatcher allocates capacity fairly, while provider/account/operation limiters enforce physical constraints. Capacity-aware weighted deficit round robin is the default candidate for balanced account distribution. + +## Leases and shutdown + +Claims have leases and heartbeats. Shutdown stops new claims, requests cooperative cancellation, waits a bounded grace period, persists known outcomes, requeues only work that did not cross the external boundary, and marks post-boundary uncertainty `UNKNOWN`. + +## Scheduler boundary + +A scheduler signals a due occurrence. Application storage owns schedule definitions, unique occurrence keys, missed-run disposition, and durable Run creation. UTC instants and the user's IANA timezone identifier are persisted separately. diff --git a/docs/02-architecture/PROVIDER_PLATFORM.md b/docs/02-architecture/PROVIDER_PLATFORM.md new file mode 100644 index 0000000..a31b38d --- /dev/null +++ b/docs/02-architecture/PROVIDER_PLATFORM.md @@ -0,0 +1,20 @@ +# Provider Platform + +## Minimum operation contract + +- capability declaration; +- account and payload validation; +- invoice create/send/finalize operations as supported; +- stable idempotency context and scope/retention metadata where known; +- provider/request correlation identifiers; +- error classification and rate-limit signals; +- status lookup and reconciliation behavior; +- conservative behavior when capability data is missing. + +## Safety rules + +A universal retry policy is prohibited. Retry eligibility is provider-operation-specific. Authentication and validation failures require user correction; rate limits and eligible transient failures may back off; uncertain outcomes enter `UNKNOWN` until reconciled. + +## Plugin boundary + +Version 1 uses approved built-in providers only. Unrestricted third-party Python plugins are excluded. Future plugin support requires manifest/versioning, explicit permissions, compatibility checks, and preferably process isolation. diff --git a/docs/02-architecture/QUALITY_ATTRIBUTES.md b/docs/02-architecture/QUALITY_ATTRIBUTES.md index 8b6f3c7..dd86c84 100644 --- a/docs/02-architecture/QUALITY_ATTRIBUTES.md +++ b/docs/02-architecture/QUALITY_ATTRIBUTES.md @@ -1,6 +1,6 @@ # Quality Attributes -Exact numerical targets are not invented in Phase 0A. Items depending on technology evidence are marked for Phase 0B validation. +Exact numerical targets are not invented by the Phase 0C candidate. Evidence supports architecture direction, while target values require explicit human approval and repeatable engineering tests. ## QA-001 - Reliability @@ -98,13 +98,13 @@ Exact numerical targets are not invented in Phase 0A. Items depending on technol **Target:** Detailed compatibility window will be defined in a later engineering baseline. -## Phase 0B evidence summary +## Phase 0B and Phase 0C evidence summary - **Reliability and recoverability:** Hybrid reconciliation, lease recovery, scheduler occurrence uniqueness, and bounded shutdown were supported by synthetic fault evidence. -- **Security:** No real secret was used. Windows secure-backend behavior remains unvalidated. -- **Performance:** SQLite strategy evidence is usable for architecture direction; UI and packaged-startup targets remain unapproved. -- **Accessibility:** Inconclusive because the GUI target was unavailable. +- **Security:** Secure-vault behavior is human-attested through Phase 0B.3 approval; Phase 0C did not independently rerun raw Windows evidence. Fail-closed tests remain release gates. +- **Performance:** SQLite and bounded-list strategy evidence supports the candidate direction; numerical UI and startup targets remain unapproved. +- **Accessibility:** No full compliance claim is made. Keyboard, scaling, focus, contrast and assistive-technology validation remain open. - **Data integrity:** SQLite integrity checks returned `ok`; uncommitted crash work rolled back; hybrid repair converged. -- **Portability:** Windows-specific packaging and credential evidence remains blocked. +- **Portability:** Phase 0B.3 source integration is repository-verified and final Windows validation is human-attested. Repeatable supported-version packaging tests remain required. -No quality target becomes approved solely from these observations. +No quality target becomes approved solely from these observations or from a human-attested phase gate; target approval remains a separate Human Architecture Owner decision. diff --git a/docs/02-architecture/SECURITY_ARCHITECTURE.md b/docs/02-architecture/SECURITY_ARCHITECTURE.md new file mode 100644 index 0000000..12d5728 --- /dev/null +++ b/docs/02-architecture/SECURITY_ARCHITECTURE.md @@ -0,0 +1,21 @@ +# Security Architecture + +## Secrets + +API secrets are stored only through Windows Credential Manager or another explicitly approved OS vault. Databases and configuration contain credential references, never secret values. Missing or insecure backends fail closed. + +## Data minimization + +Provider requests contain only required fields. Operational logs exclude authorization headers, tokens, customer-sensitive payloads, and secret-shaped values. Business audit events contain non-secret references. + +## Isolation + +Workspace data and files are scoped by immutable workspace identifiers. `control.db` cannot contain workspace customer or invoice payloads. Cross-workspace access fails closed. + +## External-operation safety + +Idempotency and reconciliation are required where supported. Unknown outcomes are not blindly retried. Immutable run snapshots prevent mid-run configuration mutation. + +## Packaging and supply chain + +Windows `onedir` builds use clean isolated roots. Packaged credential and timezone tests, secret scans, dependency audits, license checks, and SBOM generation are release gates. No Windows security exclusion is permitted as a packaging workaround. diff --git a/docs/02-architecture/SYSTEM_CONTEXT.md b/docs/02-architecture/SYSTEM_CONTEXT.md new file mode 100644 index 0000000..3ff0207 --- /dev/null +++ b/docs/02-architecture/SYSTEM_CONTEXT.md @@ -0,0 +1,15 @@ +# System Context + +OpenInvoice is a single-user Windows desktop operations console that coordinates invoice workloads with external invoice-service providers. + +## Actors and systems + +- **Operator:** creates invoice projects, imports customers, reviews, tests, sends, schedules, and handles problems. +- **Invoice providers:** external systems with provider- and operation-specific capabilities. +- **Windows Credential Manager or approved OS vault:** stores secrets; OpenInvoice stores references only. +- **Local filesystem and SQLite:** durable control and workspace state. +- **Windows packaging/runtime:** supplies the desktop application environment. + +## Trust boundaries + +Customer and invoice data remain local except for the minimum payload required by a selected provider operation. Credentials cross only the credential adapter/provider boundary. Diagnostics and support exports are redacted. Unrestricted third-party plugins are outside Version 1. diff --git a/docs/03-ux/ACCESSIBILITY.md b/docs/03-ux/ACCESSIBILITY.md new file mode 100644 index 0000000..1e66fe1 --- /dev/null +++ b/docs/03-ux/ACCESSIBILITY.md @@ -0,0 +1,5 @@ +# Accessibility + +Core workflows require keyboard navigation, logical tab order, visible focus, scalable text, sufficient contrast, non-colour status cues, accessible labels, and understandable errors. Windows scaling at 100–200% is a supported validation range. + +CustomTkinter/Tkinter accessibility remains a monitored risk. No claim of full screen-reader compliance is made without assistive-technology testing. Accessibility acceptance targets require later user and platform testing. diff --git a/docs/03-ux/DESIGN_SYSTEM.md b/docs/03-ux/DESIGN_SYSTEM.md new file mode 100644 index 0000000..1e8f6f5 --- /dev/null +++ b/docs/03-ux/DESIGN_SYSTEM.md @@ -0,0 +1,5 @@ +# Design System + +Use clear hierarchy, large primary actions, consistent spacing, readable typography, visible focus, and predictable status language. Primary actions use verbs. Destructive or financially consequential actions require explicit confirmation. + +Components must support disabled, loading, empty, warning, error, success, and partial-completion states. Tables use bounded pages and preserve selection by stable record identity. Progress reports counts and meaningful phases rather than indeterminate activity alone. diff --git a/docs/03-ux/ERROR_LANGUAGE.md b/docs/03-ux/ERROR_LANGUAGE.md new file mode 100644 index 0000000..123b749 --- /dev/null +++ b/docs/03-ux/ERROR_LANGUAGE.md @@ -0,0 +1,11 @@ +# Error Language + +Errors state what happened, what was affected, whether anything may have been sent, and the next safe action. + +Examples: + +- “This account needs to be reconnected before sending can continue.” +- “The provider may have received this invoice. Open Problems to Review before trying again.” +- “13 customer rows need attention; the remaining 9,829 are ready.” + +Do not expose stack traces, HTTP codes, queue internals, or worker terminology in the Standard experience. Diagnostics may include redacted technical detail. diff --git a/docs/03-ux/INFORMATION_ARCHITECTURE.md b/docs/03-ux/INFORMATION_ARCHITECTURE.md new file mode 100644 index 0000000..0de0cd1 --- /dev/null +++ b/docs/03-ux/INFORMATION_ARCHITECTURE.md @@ -0,0 +1,19 @@ +# Information Architecture + +## Home + +Create Invoice Project, recent projects, status, and problems requiring attention. + +## Guided project flow + +`Choose service → Connect accounts → Add customers → Prepare invoice → Review and test → Send or schedule → Review results`. + +## Workspace navigation + +Overview, Customers, Invoice, Delivery, and Results. Retry internals and raw logs remain contextual or diagnostic. + +## Visibility + +- **Standard:** essential workflow and recommended defaults. +- **Advanced:** account weights, rate limits, concurrency, retry and scheduling details. +- **Diagnostics:** technical logs, provider request IDs, database integrity, migration state, and redacted support exports. diff --git a/docs/03-ux/UX_PRINCIPLES.md b/docs/03-ux/UX_PRINCIPLES.md new file mode 100644 index 0000000..95dff71 --- /dev/null +++ b/docs/03-ux/UX_PRINCIPLES.md @@ -0,0 +1,10 @@ +# UX Principles + +1. Lead with the user's invoice workflow, not technical subsystems. +2. Use plain, actionable, consequence-aware language. +3. Provide smart, visibly recommended defaults. +4. Reveal advanced controls progressively in context. +5. Require preflight review and a controlled test before irreversible sending. +6. Keep Problems to Review separate from raw Diagnostics. +7. Preserve visible pause, resume, stop, and background status. +8. Render large datasets through bounded paging/windowing, never one widget per record. diff --git a/docs/04-engineering/CODING_STANDARDS.md b/docs/04-engineering/CODING_STANDARDS.md new file mode 100644 index 0000000..8a80771 --- /dev/null +++ b/docs/04-engineering/CODING_STANDARDS.md @@ -0,0 +1,5 @@ +# Coding Standards + +Use supported Python type hints on public and internal service boundaries. Prefer immutable value objects for identities, snapshots, and provider capabilities. Errors are classified into domain/application/provider categories; do not use broad exception swallowing. + +Logs are structured and redacted. Functions and classes have one clear responsibility. Global mutable “current workspace” state is prohibited. Time and UUID generation are injectable where deterministic tests require them. Unsafe automatic lint fixes are not CI defaults. diff --git a/docs/04-engineering/DEPENDENCY_POLICY.md b/docs/04-engineering/DEPENDENCY_POLICY.md new file mode 100644 index 0000000..749bba1 --- /dev/null +++ b/docs/04-engineering/DEPENDENCY_POLICY.md @@ -0,0 +1,5 @@ +# Dependency Policy + +A dependency requires a documented need, boundary, alternatives, license, maintenance/security review, packaging evidence where applicable, replacement strategy, human disposition, and a pinned version in the later build-foundation phase. + +Spike installation is not production approval. Domain code cannot depend on infrastructure libraries. Production versions and lockfiles are not selected in Phase 0C. Vulnerability, license, and SBOM checks are mandatory release gates. diff --git a/docs/04-engineering/GIT_WORKFLOW.md b/docs/04-engineering/GIT_WORKFLOW.md new file mode 100644 index 0000000..fd0e622 --- /dev/null +++ b/docs/04-engineering/GIT_WORKFLOW.md @@ -0,0 +1,5 @@ +# Git Workflow + +Use protected `main` and short-lived `feature/*`, `fix/*`, `docs/*`, `test/*`, `spike/*`, or `chore/*` branches. No direct push, force push, destructive reset, or `git add .` in governed assignments. + +Every PR requires scoped changes, tests/evidence, documentation-impact assessment, security impact, migration impact, and human review. Baseline tags are created only by a separately authorized action after baseline approval. diff --git a/docs/04-engineering/PACKAGING_STRATEGY.md b/docs/04-engineering/PACKAGING_STRATEGY.md new file mode 100644 index 0000000..86e39b7 --- /dev/null +++ b/docs/04-engineering/PACKAGING_STRATEGY.md @@ -0,0 +1,5 @@ +# Packaging Strategy + +Windows PyInstaller `onedir` is the primary candidate. Builds use a supported interpreter, clean unique build roots, separate copied launch roots, deterministic process waits, and verified cleanup. Test normal Tcl/Tk hooks before controlled environment or spec fallbacks. + +Packaged gates include assets, writable user-data path, redacted logs, credential-vault lifecycle and cleanup, `UTC` plus IANA timezone resolution, scheduler occurrence deduplication across restart, path-with-spaces launch, and operation without an activated development environment. Onefile is optional comparison only. diff --git a/docs/04-engineering/PROJECT_STRUCTURE.md b/docs/04-engineering/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..4ae2865 --- /dev/null +++ b/docs/04-engineering/PROJECT_STRUCTURE.md @@ -0,0 +1,24 @@ +# Project Structure + +```text +src/openinvoice/ +├── presentation/ +├── application/ +├── domain/ +├── execution/ +├── providers/ +└── infrastructure/ +tests/ +├── unit/ +├── integration/ +├── contract/ +├── recovery/ +├── architecture/ +└── packaging/ +docs/ +resources/ +scripts/ +migrations/ +``` + +Phase 0C documents this layout only. Domain remains technology-independent. Infrastructure implements application/domain ports. Disposable spikes remain outside `src/openinvoice`. diff --git a/docs/04-engineering/RELEASE_STRATEGY.md b/docs/04-engineering/RELEASE_STRATEGY.md new file mode 100644 index 0000000..860b849 --- /dev/null +++ b/docs/04-engineering/RELEASE_STRATEGY.md @@ -0,0 +1,5 @@ +# Release Strategy + +A release candidate requires green deterministic tests, migrations, Windows packaging smoke tests, credential and timezone probes, recovery tests, secret/dependency/license scans, SBOM and third-party notices, upgrade/rollback instructions, and human approval. + +Features do not receive release tags individually. Approved baseline tags and product releases are separate governance events. Phase 0C creates neither. diff --git a/docs/04-engineering/TESTING_STRATEGY.md b/docs/04-engineering/TESTING_STRATEGY.md new file mode 100644 index 0000000..6499743 --- /dev/null +++ b/docs/04-engineering/TESTING_STRATEGY.md @@ -0,0 +1,7 @@ +# Testing Strategy + +Required categories: unit, integration, provider contract, migration, recovery, workspace isolation, architecture boundary, packaging smoke, credential-vault, scheduler restart, secret scan, dependency audit, license check, and SBOM generation. + +Architecture tests must enforce that domain does not import UI/SQLModel/HTTPX/CustomTkinter; UI does not access concrete databases or provider APIs; providers do not import UI; workers do not update Tk widgets; workspace repositories require scope; database models contain no secrets; provider calls carry idempotency context. + +No “all tests passed” claim is permitted when a required test was skipped, blocked, or human-attested only. diff --git a/docs/05-operations/BACKUP_AND_RECOVERY.md b/docs/05-operations/BACKUP_AND_RECOVERY.md new file mode 100644 index 0000000..58852ee --- /dev/null +++ b/docs/05-operations/BACKUP_AND_RECOVERY.md @@ -0,0 +1,5 @@ +# Backup and Recovery + +Backups capture a consistent control snapshot plus selected workspace databases/files. Secrets are not copied from the OS vault into backups. Restore validates schema versions, integrity, workspace ownership, reservations, leases, and pending `UNKNOWN` outcomes before execution resumes. + +Backup encryption, retention, and export policy remain open human decisions. Restore testing is required before release. diff --git a/docs/05-operations/DIAGNOSTICS.md b/docs/05-operations/DIAGNOSTICS.md new file mode 100644 index 0000000..58bc2c1 --- /dev/null +++ b/docs/05-operations/DIAGNOSTICS.md @@ -0,0 +1,5 @@ +# Diagnostics + +Operational diagnostics include redacted correlation IDs, provider request references, timing, state transitions, worker lifecycle, database integrity, migration state, and packaging/runtime metadata. Business audit events remain separate and immutable. + +Support bundles exclude secrets, authorization headers, full customer payloads, databases unless explicitly sanitized, and user-specific paths. Collection requires preview and user confirmation. diff --git a/docs/05-operations/INCIDENT_RESPONSE.md b/docs/05-operations/INCIDENT_RESPONSE.md new file mode 100644 index 0000000..05b67b9 --- /dev/null +++ b/docs/05-operations/INCIDENT_RESPONSE.md @@ -0,0 +1,5 @@ +# Incident Response + +Classify incidents as secret exposure, cross-workspace access, duplicate/uncertain provider operation, data corruption, packaging/runtime failure, or supply-chain compromise. Stop unsafe execution, preserve redacted evidence, avoid blind retries, rotate/revoke affected credentials through the provider/vault, and record immutable audit events. + +Security mitigations require explicit human authorization and retrospective ADR/ACR documentation when they affect the baseline. diff --git a/docs/05-operations/SUPPORT_RUNBOOK.md b/docs/05-operations/SUPPORT_RUNBOOK.md new file mode 100644 index 0000000..d7c29fb --- /dev/null +++ b/docs/05-operations/SUPPORT_RUNBOOK.md @@ -0,0 +1,10 @@ +# Support Runbook + +1. Confirm product/version, baseline, Windows build, and workspace ID without collecting customer payloads. +2. Pause new claims when duplicate or uncertain operations are suspected. +3. Run integrity and reconciliation checks. +4. Verify credential backend without displaying secrets. +5. Export a redacted diagnostic bundle. +6. Escalate cross-workspace, secret, corruption, or provider-duplication incidents immediately. + +Support must not advise deleting databases, bypassing Windows security controls, or blindly retrying `UNKNOWN` operations. diff --git a/docs/phase-0c/ADR_DISPOSITION_REGISTER.md b/docs/phase-0c/ADR_DISPOSITION_REGISTER.md new file mode 100644 index 0000000..8f7574b --- /dev/null +++ b/docs/phase-0c/ADR_DISPOSITION_REGISTER.md @@ -0,0 +1,79 @@ +# ADR Disposition Register + +No ADR is marked Accepted by this package. Every proposal remains `Proposed` and is a candidate for explicit human disposition. + +## ADR-0001 — Bounded Large-Data List Strategy + +- Current status: Proposed +- Candidate status: Candidate for Human Approval +- Evidence IDs: EVID-004, EVID-006 +- Risk impact: Reduces RISK-002; RISK-011 remains open. +- Security impact: Prevents uncontrolled memory/resource use; no direct secret impact. +- Dependency impact: CustomTkinter remains conditional; bounded ttk/paginated views are required. +- Remaining conditions: Repeatable Windows interaction, DPI, keyboard, focus, contrast and assistive-technology tests. +- AI recommendation: Recommend Accept with Conditions. +- Required human decision: Accept, revise, reject or defer. + +## ADR-0002 — SQLite WAL and Bounded Writer Model + +- Current status: Proposed +- Candidate status: Candidate for Human Approval +- Evidence IDs: EVID-007 +- Risk impact: Mitigates RISK-005 and supports RISK-016 recovery objectives. +- Security impact: Short transactions and controlled writers reduce integrity exposure; backup policy remains separate. +- Dependency impact: Compatible with `sqlite3`, SQLAlchemy and SQLModel persistence options. +- Remaining conditions: Migration tests, writer-failure tests, representative Windows storage and production ceilings. +- AI recommendation: Recommend Accept with Conditions. +- Required human decision: Accept, revise, reject or defer. + +## ADR-0003 — Hybrid Database Reservation and Reconciliation + +- Current status: Proposed +- Candidate status: Candidate for Human Approval +- Evidence IDs: EVID-008, EVID-012 +- Risk impact: Mitigates RISK-006 and RISK-010 while preserving workspace isolation. +- Security impact: Keeps customer/invoice payloads out of `control.db`; credentials remain references only. +- Dependency impact: Requires explicit repository and migration boundaries, independent of ORM choice. +- Remaining conditions: Production crash tests, migration tests, multi-workspace stress and backup/restore validation. +- AI recommendation: Recommend Accept with Conditions. +- Required human decision: Accept, revise, reject or defer. + +## ADR-0004 — Scheduler Trigger Boundary and Durable Occurrences + +- Current status: Proposed +- Candidate status: Candidate for Human Approval +- Evidence IDs: EVID-004, EVID-005, EVID-009 +- Risk impact: Reduces duplicate-run and timezone uncertainty under RISK-003 and RISK-016. +- Security impact: No scheduler may bypass durable Run creation or audit controls. +- Dependency impact: APScheduler is conditional and trigger-only; `tzdata` is a conditional Windows runtime candidate. +- Remaining conditions: Repeatable packaged timezone and restart-dedup tests in the approved build pipeline. +- AI recommendation: Recommend Accept with Conditions. +- Required human decision: Accept, revise, reject or defer; decide `tzdata` separately. + +## ADR-0005 — Bounded Worker Shutdown and Unknown Outcomes + +- Current status: Proposed +- Candidate status: Candidate for Human Approval +- Evidence IDs: EVID-004, EVID-010 +- Risk impact: Mitigates RISK-010 and RISK-016. +- Security impact: Prevents unsafe blind requeue after crossing the external-operation boundary. +- Dependency impact: Execution backends must support cooperative shutdown and durable lease markers. +- Remaining conditions: Real provider adapter, Windows shutdown-signal and restart integration tests. +- AI recommendation: Recommend Accept with Conditions. +- Required human decision: Accept, revise, reject or defer. + +## ADR-0006 — Operation-Level Provider Capability Contract + +- Current status: Proposed +- Candidate status: Candidate for Human Approval +- Evidence IDs: EVID-011, EVID-012 +- Risk impact: Mitigates RISK-007, RISK-008 and RISK-010. +- Security impact: Conservative failure behavior prevents unsafe retries and secret-bearing diagnostic leakage. +- Dependency impact: HTTP clients and provider SDKs remain behind adapters; no provider SDK is approved here. +- Remaining conditions: Provider-operation sandbox tests and periodic documentation review. +- AI recommendation: Recommend Accept with Conditions. +- Required human decision: Accept, revise, reject or defer. + +## ACR disposition + +Proposed ACRs: None. The candidate retains the protected architecture direction and does not weaken isolation, ownership, execution, security or reliability guarantees. diff --git a/docs/phase-0c/BASELINE_APPROVAL_PACKET.md b/docs/phase-0c/BASELINE_APPROVAL_PACKET.md new file mode 100644 index 0000000..e05f319 --- /dev/null +++ b/docs/phase-0c/BASELINE_APPROVAL_PACKET.md @@ -0,0 +1,75 @@ +# Baseline Approval Packet + +## Candidate identification + +- Product: OpenInvoice +- Repository: `vibtools/OpenInvoice` +- Source commit: `4cfc3cb5de400d4459cc5fd691a208abc185018f` +- Candidate baseline: `1.0.0-candidate.1` +- Prepared date: 2026-07-23 +- Status: Candidate — awaiting Human Architecture Owner approval + +## Phase-gate history + +- Phase 0A: Approved. +- Phase 0B: Approved with conditions. +- Phase 0B.1: Remediation required. +- Phase 0B.2: Not approved; remediation continued. +- Phase 0B.3: Approved by the Human Architecture Owner and Final Approver. +- Phase 0C: Authorized for candidate preparation only. + +## Evidence classification + +- PR #1 and source integration: Repository-verified. +- Phase 0B.3 final Windows outcome: Human-attested. +- Spike scripts and recorded machine results: Machine-verified where identified in the evidence inventory. +- Phase 0C independent Windows rerun: Not performed and not claimed. + +## Architecture candidate + +The candidate retains Workspace → Run → Job → Attempt, hybrid `control.db` plus isolated workspace databases, workspace-scoped logical queues, a global bounded engine, provider-specific executors, global physical-account limits, immutable run snapshots, durable leases, `UNKNOWN` reconciliation, trigger-only scheduling, capability-based providers, workflow-first UI separation and OS-vault secret handling. + +## ADR recommendations + +ADR-0001 through ADR-0006 are recommended for acceptance with explicit conditions. None is marked Accepted by this package. + +## Dependency recommendations + +Seven tools/libraries are candidates for the next engineering phase, four are conditional candidates, SQLModel is deferred, and psutil remains spike/test only. No version or lockfile is approved. + +## Guarantees retained + +### Security + +No plaintext secrets; reference-only credential persistence; fail-closed vault behavior; structured redaction; restricted plugins; isolated workspace paths; redacted diagnostics; distinct operational and immutable audit streams. + +### Reliability + +Durable explicit states; bounded execution; leases; idempotency context; `UNKNOWN` outcomes; reconciliation before unsafe retry; immutable snapshots; bounded shutdown. + +### UX + +Standard workflow with progressive Advanced controls and separate Diagnostics; preflight and test-send direction; bounded large-data rendering; no unsupported accessibility-compliance claim. + +## Scope exclusions + +The candidate does not authorize full accounting, tax filing, payment custody, banking, cloud multi-user SaaS, mobile applications, unrestricted plugins, remote administration or silent scope expansion. + +## Remaining risks and evidence limitations + +Trademark risk remains open. Packaging and credential evidence is human-attested rather than independently rerun in Phase 0C. Accessibility, provider sandboxes, numerical performance targets, backup policy and repeatable build/release gates remain open. + +## Human decisions required + +1. Disposition ADR-0001 through ADR-0006. +2. Disposition all dependency candidates. +3. Confirm Version 1 providers, fields, report formats, account-sharing policy, backup policy and accessibility targets. +4. Approve, revise or reject baseline `1.0.0-candidate.1`. +5. Separately authorize `baseline-v1.0.0` and Phase 1. + +## Proposed tag and next phase + +- Proposed tag after separate approval: `baseline-v1.0.0` +- Proposed next phase after separate approval: Phase 1 — Repository Governance and CI Foundation + +Neither action is authorized by applying or merging this package. diff --git a/docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md b/docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md new file mode 100644 index 0000000..8560b7f --- /dev/null +++ b/docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md @@ -0,0 +1,21 @@ +# Dependency Disposition Register + +Spike installation is evidence only. It is not production approval. Exact versions and lockfiles belong to the approved build-foundation phase. + +| Dependency | Purpose | Architecture boundary | License record | Evidence | Proposed disposition | Security concerns | Packaging concerns | Upgrade policy | Replacement strategy | Human decision required | +|---|---|---|---|---|---|---|---|---|---|---| +| CustomTkinter | Desktop presentation shell | UI only | MIT | EVID-004, EVID-006 | Conditional candidate | Accessibility and UI-thread discipline | Validate Tcl/Tk assets in `onedir` | Pin after Phase 1 evaluation; manual reviewed upgrades | Standard Tk/ttk or another approved shell | Approve, defer or reject | +| PyInstaller | Windows packaging | Build/release tooling | GPL-2.0-or-later with bootloader exception | EVID-004, EVID-005 | Candidate for next phase | Build provenance and artifact scanning | `onedir`, unique build roots, packaged probes | Pin in build foundation; upgrade only with smoke tests | Another approved Windows packager | Approve, defer or reject | +| keyring | OS credential-vault adapter | Infrastructure credentials | MIT | EVID-004 | Conditional candidate | Must fail closed; no plaintext fallback | Source and packaged backend tests | Pin after secure-backend validation | Direct approved Windows-vault adapter | Approve, defer or reject | +| tzdata | IANA timezone data on Windows | Runtime infrastructure | Apache-2.0 | EVID-009 | Conditional candidate | Supply-chain and update review | Verify bundled `UTC` and user IANA zones | Reviewed periodic update with DST tests | Approved bundled timezone dataset | Approve, defer or reject | +| pytest | Test runner | Development/test only | MIT | Documentation-derived | Candidate for next phase | Test plugins require review | Not shipped as runtime dependency | Pin in development group | `unittest` | Approve, defer or reject | +| Ruff | Lint and formatting | Development/CI only | MIT | Documentation-derived | Candidate for next phase | Unsafe fixes must not run automatically | Not shipped at runtime | Pin configuration and version in Phase 1 | Separate approved lint/format tools | Approve, defer or reject | +| uv | Environment and lock management | Build/CI tooling | Apache-2.0 OR MIT | Documentation-derived | Candidate for next phase | Lockfile and index policy required | Reproducible Windows sync required | Frozen lock workflow after approval | `pip`/`venv` plus approved lock tool | Approve, defer or reject | +| SQLAlchemy | Persistence mapping and transactions | Infrastructure persistence only | MIT | EVID-007, EVID-008 | Candidate for next phase | Queries must preserve workspace scope | Normal Python packaging | Pin after persistence walking skeleton | Standard-library `sqlite3` repositories | Approve evaluation, defer or reject | +| SQLModel | Optional persistence model convenience | Infrastructure persistence only; never domain | MIT | Documentation-derived | Deferred | Risk of coupling domain to ORM | Normal Python packaging | Reconsider only after SQLAlchemy baseline | SQLAlchemy mappings plus domain dataclasses | Confirm defer or authorize evaluation | +| Alembic | Schema migration | Infrastructure migration tooling | MIT | Documentation-derived | Candidate for next phase | Migration integrity and downgrade policy | Not a runtime UI concern | Pin with SQLAlchemy compatibility tests | Approved custom migration runner only by ADR | Approve evaluation, defer or reject | +| APScheduler | Schedule trigger adapter | Infrastructure scheduler; trigger-only | MIT | EVID-009 | Conditional candidate | Must not become durable job engine | Packaged restart and timezone tests | Pin after trigger-boundary prototype | Application-owned timer adapter | Approve boundary, defer or reject | +| HTTPX | Provider HTTP transport | Provider/infrastructure adapters only | BSD-3-Clause | EVID-011 | Candidate for next phase | TLS, timeout, proxy and redaction policy | Normal Python packaging | Pin after provider transport tests | Standard library or another approved client | Approve evaluation, defer or reject | +| psutil | Spike measurement/process diagnostics | Spike/test only | BSD-3-Clause | EVID-005 | Spike/test only | Avoid unnecessary production process inspection | Exclude from runtime unless justified | No production upgrade policy | Standard-library/platform probes | Confirm spike-only | + +No dependency is installed, locked or imported into production code by Phase 0C. diff --git a/docs/phase-0c/EVIDENCE_INVENTORY.md b/docs/phase-0c/EVIDENCE_INVENTORY.md new file mode 100644 index 0000000..1de0924 --- /dev/null +++ b/docs/phase-0c/EVIDENCE_INVENTORY.md @@ -0,0 +1,22 @@ +# Evidence Inventory + +## Classification rule + +Each entry uses exactly one approved classification. `Reproducible` is separately recorded as `Yes`, `No`, or `Partial`. + +| Evidence ID | Claim | Source | Classification | Reproducible | Related ADR | Related risk | Limitation | Disposition | +|---|---|---|---|---|---|---|---|---| +| EVID-001 | Phase 0A governance gate was approved. | Human decision and Phase 0A governance records | Human-attested | No | Not applicable | RISK-013, RISK-014 | Phase 0C did not replay the original human approval session. | Accepted | +| EVID-002 | Phase 0B spike source and proposed ADR-0001 through ADR-0006 are present in the repository history. | Repository tree and PR #1 merge | Repository-verified | Yes | ADR-0001..ADR-0006 | RISK-014 | Repository presence does not prove every external result. | Accepted | +| EVID-003 | PR #1 was merged into `main` at `4cfc3cb5de400d4459cc5fd691a208abc185018f`. | GitHub PR #1 and merge commit | Repository-verified | Yes | Not applicable | RISK-015 | Proves source integration, not final Windows outcomes. | Accepted | +| EVID-004 | Phase 0B.3 was approved by the Human Architecture Owner and Final Approver. | Human decision dated 2026-07-23 | Human-attested | No | ADR-0001, ADR-0004, ADR-0005 | RISK-002, RISK-003, RISK-004, RISK-011, RISK-016 | Raw Windows evidence was not independently rerun in Phase 0C. | Conditional | +| EVID-005 | Phase 0B.3 preparation assets, package structure and source integration are internally consistent. | Phase 0B.3 package validation and repository merge | Machine-verified | Yes | ADR-0004 | RISK-003, RISK-014 | Static/package-structure evidence is not a substitute for Windows runtime evidence. | Accepted | +| EVID-006 | Bounded or paginated list strategies avoid unbounded widget materialization. | Phase 0B large-data spike | Machine-verified | Partial | ADR-0001 | RISK-002, RISK-011 | Final Windows accessibility and usability targets remain open. | Conditional | +| EVID-007 | WAL, busy timeout, short transactions and a bounded writer reduce SQLite contention. | Phase 0B SQLite spike | Machine-verified | Yes | ADR-0002 | RISK-005 | Production ceilings, migrations and representative storage remain future tests. | Conditional | +| EVID-008 | Hybrid reservation, lease and reconciliation flows converge under injected failures. | Phase 0B hybrid-database spike | Machine-verified | Yes | ADR-0003 | RISK-006, RISK-010 | Production stress, migrations and multi-workspace scale remain future tests. | Conditional | +| EVID-009 | Trigger-only scheduling, UTC persistence and unique occurrence keys are supported; packaged restart outcome is human-attested. | Scheduler spikes, Phase 0B.3 approval and ADR-0004 | Partially reproducible | Partial | ADR-0004 | RISK-003, RISK-016 | Exact runtime versions and independent packaged rerun remain open. | Conditional | +| EVID-010 | Shutdown recovery must distinguish pre-external work from uncertain post-external work. | Worker-shutdown spikes and ADR-0005 | Machine-verified | Yes | ADR-0005 | RISK-010, RISK-016 | Real provider SDK cancellation and OS shutdown integration remain future tests. | Conditional | +| EVID-011 | Provider idempotency, rate limits and reconciliation differ by operation. | Provider documentation review and mock fault tests | Documentation-derived | Partial | ADR-0006 | RISK-007, RISK-008, RISK-010 | Provider documentation can change; sandbox tests remain mandatory. | Conditional | +| EVID-012 | No Phase 0 evidence requires changing the protected workspace-isolation or global bounded-engine direction. | Architecture review and ADR disposition analysis | Documentation-derived | Yes | ADR-0001..ADR-0006 | RISK-013, RISK-014 | Candidate decisions still require human approval. | Accepted | + +No missing log, screenshot, measurement or machine result is invented. diff --git a/docs/phase-0c/OPEN_DECISIONS.md b/docs/phase-0c/OPEN_DECISIONS.md new file mode 100644 index 0000000..4e310df --- /dev/null +++ b/docs/phase-0c/OPEN_DECISIONS.md @@ -0,0 +1,14 @@ +# Open Decisions + +Human decisions required before controlled-baseline approval: + +1. Accept, revise, reject or defer ADR-0001 through ADR-0006. +2. Approve, defer or reject each dependency disposition, including Windows `onedir`, `keyring`, `tzdata`, SQLAlchemy/Alembic, APScheduler and HTTPX directions. +3. Confirm that SQLModel remains deferred or authorize a later evaluation. +4. Confirm Version 1 providers, mandatory customer/invoice fields, report formats and physical-account sharing policy. +5. Define supported Windows/Python versions and repeatable packaging matrix. +6. Define measurable large-data, accessibility and recovery targets. +7. Define backup/export encryption, retention and restore policy. +8. Resolve the OpenInvoice product-name/trademark risk before public branding or release. +9. Approve, revise or reject baseline `1.0.0-candidate.1`. +10. Separately authorize or reject `baseline-v1.0.0` and Phase 1. diff --git a/docs/phase-0c/README.md b/docs/phase-0c/README.md new file mode 100644 index 0000000..0bbda96 --- /dev/null +++ b/docs/phase-0c/README.md @@ -0,0 +1,41 @@ +# Phase 0C — Controlled Baseline Candidate + +## Purpose + +This directory contains the review packet for OpenInvoice baseline `1.0.0-candidate.1`, prepared from repository commit `4cfc3cb5de400d4459cc5fd691a208abc185018f`. + +Phase 0C reconciles governance and evidence. It does not approve the baseline, accept ADRs, create a tag, authorize Phase 1, install production dependencies, or begin production implementation. + +## Evidence taxonomy + +Only these classifications are used: + +- Machine-verified +- Repository-verified +- Human-attested +- Documentation-derived +- Partially reproducible +- Unverified +- Not applicable + +The Phase 0B.3 merge is repository-verified. The final Windows validation is human-attested. Phase 0C does not claim an independent Windows rerun where raw evidence is unavailable. + +## Review documents + +- [Baseline Approval Packet](BASELINE_APPROVAL_PACKET.md) +- [Evidence Inventory](EVIDENCE_INVENTORY.md) +- [ADR Disposition Register](ADR_DISPOSITION_REGISTER.md) +- [Dependency Disposition Register](DEPENDENCY_DISPOSITION_REGISTER.md) +- [Requirements Disposition Register](REQUIREMENTS_DISPOSITION_REGISTER.md) +- [Traceability Matrix](TRACEABILITY_MATRIX.md) +- [Open Decisions](OPEN_DECISIONS.md) +- [Phase 0C Review Checklist](../reviews/PHASE_0C_REVIEW_CHECKLIST.md) +- [Phase 0B.3 Approval Record](../reviews/PHASE_0B3_APPROVAL_RECORD.md) + +## Candidate status + +- Candidate version: `1.0.0-candidate.1` +- Baseline status: Candidate — awaiting Human Architecture Owner approval +- Baseline tag authorized: No +- Production code authorized: No +- Phase 1 authorized: No diff --git a/docs/phase-0c/REQUIREMENTS_DISPOSITION_REGISTER.md b/docs/phase-0c/REQUIREMENTS_DISPOSITION_REGISTER.md new file mode 100644 index 0000000..15c99e0 --- /dev/null +++ b/docs/phase-0c/REQUIREMENTS_DISPOSITION_REGISTER.md @@ -0,0 +1,25 @@ +# Requirements Disposition Register + +The source requirements catalog is reconciled to the candidate's allowed statuses: **Approved**, **Proposed**, **Deferred**, and **Rejected**. Evidence maturity and mandatory validation conditions are tracked separately. + +| Requirement group | Candidate status | Architecture/ADR disposition | Evidence | Future validation | +|---|---|---|---|---| +| FR-001..FR-005 | Approved | Workspace ownership, immutable runs and hybrid data architecture; ADR-0003 | EVID-008, EVID-012 | Cross-workspace isolation, snapshot and account-coordination tests | +| FR-006..FR-007 | Approved | Capability-based provider platform; ADR-0006 | EVID-011, EVID-012 | Provider contract and sandbox tests | +| FR-008..FR-011 | Approved | Global bounded engine, durable states and reconciliation; ADR-0002/0003/0005/0006 | EVID-007, EVID-008, EVID-010, EVID-011 | Fairness, recovery and uncertain-outcome tests | +| FR-012..FR-020 | Proposed | Product workflow/application-service scope | Documentation-derived | Import, preview, test-send, schedule, reports and advanced-control acceptance tests | +| NFR-001..NFR-003 | Approved | Isolation, bounded execution and UI-thread separation | EVID-012 | Architecture and integration tests | +| NFR-004 | Proposed | Bounded-list direction; ADR-0001 | EVID-004, EVID-006 | Measured Windows UI and accessibility tests | +| NFR-005..NFR-006 | Approved | Durable recovery, audit history and redaction | EVID-008, EVID-010 | Restart, audit and secret-scan tests | +| NFR-007..NFR-010 | Proposed | Engineering fitness, packaging, observability and recoverability | EVID-004, EVID-005, EVID-007, EVID-008 | Architecture, packaging, integrity and observability tests | +| SEC-001..SEC-003 | Approved | OS vault, reference-only storage and package exclusions | EVID-004, EVID-005 | Source/packaged vault and artifact scans | +| SEC-004..SEC-006 | Proposed | Redaction, Version 1 plugin restriction and immutable audit events | Documentation-derived | Redaction, plugin-boundary and audit tests | +| UX-001..UX-004 | Approved | Workflow-first, progressive disclosure and separate Diagnostics | Documentation-derived | Navigation and representative-user review | +| UX-005..UX-007 | Proposed | Error language, preflight and accessibility baseline | EVID-004, EVID-006 | Usability, keyboard, scaling, contrast and assistive tests | +| OPS-001..OPS-003 | Approved | Durable store, scoped limits and UI event boundary | EVID-007, EVID-010, EVID-011 | Recovery, rate-limit and architecture tests | +| OPS-004..OPS-006 | Proposed | Shutdown, scheduler and backup/restore directions; ADR-0004/0005 | EVID-009, EVID-010 | Shutdown, restart, DST and restore tests | +| CON-001..CON-006 | Approved | Product/repository/governance constraints | EVID-001, EVID-003 | Package and PR governance checks | +| CON-007 | Proposed | Windows-first desktop direction | EVID-004 | Supported-version decision and packaging matrix | +| ASM-001..ASM-005 | Proposed | Assumptions remain non-guarantees | EVID-004, EVID-006..EVID-011 | User research and technical validation | + +No speculative Version 1 feature is promoted to Approved by this package. diff --git a/docs/phase-0c/TRACEABILITY_MATRIX.md b/docs/phase-0c/TRACEABILITY_MATRIX.md new file mode 100644 index 0000000..605c331 --- /dev/null +++ b/docs/phase-0c/TRACEABILITY_MATRIX.md @@ -0,0 +1,43 @@ +# Traceability Matrix + +| Requirement | Invariant | ADR | Evidence | Risk | Future validation | +|---|---|---|---|---|---| +| FR-001, FR-004, NFR-001 | ARCH-INV-005, 006, 017, 019 | ADR-0003 | EVID-008, EVID-012 | RISK-006 | Cross-workspace negative tests and schema ownership checks | +| FR-002 | ARCH-INV-007 | Baseline core | EVID-012 | RISK-014 | Domain and persistence structure tests | +| FR-003 | ARCH-INV-008 | Baseline core | Documentation-derived | RISK-010 | Snapshot mutation and historical-integrity tests | +| FR-005, FR-011 | ARCH-INV-013, 018 | ADR-0003 | EVID-008 | RISK-004, RISK-008 | Assignment isolation and global-account broker tests | +| FR-006, FR-007 | ARCH-INV-011, 012, 016, 028 | ADR-0006 | EVID-011 | RISK-007, RISK-008, RISK-010 | Provider contract and sandbox tests | +| FR-008, NFR-002 | ARCH-INV-014, 015 | ADR-0002, ADR-0005 | EVID-007, EVID-010 | RISK-005, RISK-016 | Fairness, concurrency, backpressure and shutdown tests | +| FR-009, FR-010, NFR-005 | ARCH-INV-009, 012, 019, 024, 027, 029 | ADR-0003, ADR-0005, ADR-0006 | EVID-008, EVID-010, EVID-011 | RISK-006, RISK-010 | Crash, lease and timeout-after-success tests | +| FR-012..FR-015 | UX/application boundaries | Candidate UX baseline | Documentation-derived | RISK-018 | Import, validation, preview and test-send acceptance tests | +| FR-016, OPS-005 | ARCH-INV-025, 026 | ADR-0004 | EVID-009 | RISK-003, RISK-016 | DST, missed-run and packaged restart-dedup tests | +| FR-017, OPS-004 | ARCH-INV-024, 027, 029 | ADR-0005 | EVID-010 | RISK-010, RISK-016 | Pause, cancellation, shutdown and restart tests | +| FR-018, FR-019, NFR-009 | ARCH-INV-020 | Candidate operations baseline | Documentation-derived | RISK-014, RISK-018 | Report, audit and Problems-to-Review tests | +| FR-020, OPS-002 | ARCH-INV-013, 014, 028 | ADR-0006 | EVID-011 | RISK-008 | Provider/account/operation rate-limit tests | +| NFR-003, OPS-003 | ARCH-INV-001..004 | ADR-0005 | EVID-010, EVID-012 | RISK-013 | Import-boundary and UI event-queue tests | +| NFR-004, UX-007 | Bounded rendering and accessibility rules | ADR-0001 | EVID-004, EVID-006 | RISK-002, RISK-011 | Windows GUI, DPI, keyboard and assistive tests | +| NFR-006, SEC-001..SEC-006 | ARCH-INV-010, 018, 020 | Security baseline | EVID-004, EVID-005 | RISK-004, RISK-009, RISK-012, RISK-017 | Vault, redaction, secret-scan, plugin and diagnostic tests | +| NFR-007 | ARCH-INV-001..029 | ADR-0001..0006 | EVID-012 | RISK-013, RISK-014 | Architecture fitness and cycle tests | +| NFR-008, CON-007 | Windows `onedir` packaging rules | ADR-0004 | EVID-004, EVID-005, EVID-009 | RISK-003, RISK-004 | Supported-version packaging matrix | +| NFR-010, OPS-006 | ARCH-INV-019, 024 | ADR-0003, ADR-0005 | EVID-008, EVID-010 | RISK-006, RISK-017 | Integrity, backup and restore tests | +| UX-001..UX-006 | Workflow-first progressive disclosure | Candidate UX baseline | Documentation-derived | RISK-018 | Moderated usability and preflight tests | +| CON-001..CON-006 | ARCH-INV-021..023 | Governance baseline | EVID-001, EVID-003 | RISK-013, RISK-014, RISK-015 | Package, dependency and PR policy checks | +| ASM-001..ASM-005 | Not guarantees; validation required | Relevant ADRs | EVID-004, EVID-006..EVID-011 | RISK-002..RISK-011 | User research and technical validation | + +## Constitutional coverage + +| Constitutional rules | Architecture or testing disposition | +|---|---| +| CONST-001 | Repository/product identity checks in manifest, package and PR review | +| CONST-002..CONST-005 | Workspace scoping, isolated data ownership, separate domain concepts and immutable-snapshot tests | +| CONST-006..CONST-010 | Durable state, explicit transitions, reconciliation, bounded execution and global-account tests | +| CONST-011 | OS vault, fail-closed behavior, secret scans and artifact exclusions | +| CONST-012 | UI/database/provider import boundaries and UI-event-queue tests | +| CONST-013 | Provider capability and operation-level contract tests | +| CONST-014 | Workflow-first UX and moderated usability tests | +| CONST-015 | Immutable audit-event and redacted observability tests | +| CONST-016 | Pull-request documentation-impact gate | +| CONST-017 | Evidence taxonomy and no-false-PASS validation | +| CONST-018 | Required static, test, migration, security and human-review gates | +| CONST-019..CONST-021 | AI authority, human approval, ADR/ACR workflow and protected-document controls | +| CONST-022 | Manifest-only update package, previous/new hashes and prohibited-artifact checks | diff --git a/docs/reviews/PHASE_0B3_APPROVAL_RECORD.md b/docs/reviews/PHASE_0B3_APPROVAL_RECORD.md new file mode 100644 index 0000000..f4c6465 --- /dev/null +++ b/docs/reviews/PHASE_0B3_APPROVAL_RECORD.md @@ -0,0 +1,23 @@ +# Phase 0B.3 Approval Record + +- Product: OpenInvoice +- Phase: 0B.3 +- Decision: Approved +- Approval authority: Human Architecture Owner and Final Approver +- Approval date: 2026-07-23 +- Canonical merge commit: `4cfc3cb5de400d4459cc5fd691a208abc185018f` +- Pull request: #1 +- Architecture change implemented: No +- ACR required: No +- Next phase: Phase 0C authorized for controlled-baseline candidate preparation + +## Evidence classification + +- Repository source integration: Repository-verified +- Final Windows validation: Human-attested +- Package structure: Machine-verified during previous review +- Independent reproduction by this Phase 0C assignment: Unverified unless supported by an explicitly listed machine result + +## Historical disclosure + +The Phase 0B.3 update ZIP and committed preparation reports recorded blocked or incomplete Windows states before the separate final validation session. Those historical records are preserved. This approval record establishes the later human gate decision without rewriting the original failures, remediation history or preparation-state evidence. diff --git a/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md b/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md new file mode 100644 index 0000000..d31f5f8 --- /dev/null +++ b/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md @@ -0,0 +1,36 @@ +# Phase 0C Review Checklist + +## Repository and source + +- [ ] Confirm repository `vibtools/OpenInvoice`. +- [ ] Confirm source commit `4cfc3cb5de400d4459cc5fd691a208abc185018f` or a documented descendant with unchanged target files. +- [ ] Confirm PR #1 merge and Phase 0B.3 approval record. +- [ ] Confirm the local working tree was clean before package application. + +## Evidence + +- [ ] Review EVID-001 through EVID-012. +- [ ] Accept the distinction among machine-verified, repository-verified, human-attested, documentation-derived, partially reproducible, unverified and not applicable evidence. +- [ ] Confirm no independent Windows rerun is claimed without raw evidence. + +## Architecture and requirements + +- [ ] Disposition ADR-0001 through ADR-0006. +- [ ] Confirm all requirement statuses are Approved, Proposed, Deferred or Rejected. +- [ ] Confirm no architecture invariant or constitutional rule was silently removed. +- [ ] Confirm proposed ACRs: None. + +## Dependencies, security and operations + +- [ ] Review all 13 dependency dispositions. +- [ ] Confirm no version, production installation or lockfile is approved. +- [ ] Review vault, redaction, plugin, diagnostics, UNKNOWN and backup directions. + +## Final gate + +- [ ] Approve, revise or reject `1.0.0-candidate.1`. +- [ ] Record ADR and dependency decisions through a separate controlled action. +- [ ] Decide whether to authorize `baseline-v1.0.0`. +- [ ] Decide whether to authorize Phase 1. + +Applying, committing or merging this candidate does not itself approve any final-gate item. From 7e6921768869e4a0993a2e9b71ca820dcd5d23d4 Mon Sep 17 00:00:00 2001 From: vib-tools Date: Fri, 24 Jul 2026 06:22:36 -0700 Subject: [PATCH 2/4] docs(audit): correct Phase 0C evidence traceability --- BASELINE_MANIFEST.yml | 1 + PROJECT_STATUS.md | 2 +- docs/phase-0c/EVIDENCE_INVENTORY.md | 1 + docs/phase-0c/REQUIREMENTS_DISPOSITION_REGISTER.md | 14 +++++++------- docs/phase-0c/TRACEABILITY_MATRIX.md | 12 ++++++------ docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md | 13 ++++++++++++- 6 files changed, 28 insertions(+), 15 deletions(-) diff --git a/BASELINE_MANIFEST.yml b/BASELINE_MANIFEST.yml index 19af86d..b176df6 100644 --- a/BASELINE_MANIFEST.yml +++ b/BASELINE_MANIFEST.yml @@ -41,6 +41,7 @@ architecture: governance: architecture_changes_require_acr: true + architecture_change_implemented: false ai_can_approve_changes: false direct_push_to_main: false baseline_tag_authorized: false diff --git a/PROJECT_STATUS.md b/PROJECT_STATUS.md index 8bdb89b..51c13e9 100644 --- a/PROJECT_STATUS.md +++ b/PROJECT_STATUS.md @@ -21,7 +21,7 @@ - Repository integration and merge commit: **Repository-verified**. - Phase 0B.3 final Windows pass: **Human-attested** from a separate validation session. -- Spike outputs: **Machine-verified**, **Documentation-derived**, or **Partially reproducible** as recorded in EVID-001 through EVID-012. +- Spike outputs and candidate directions are classified in EVID-001 through EVID-013. - Preparation-state blocked reports remain historical records; current status is established by the separate approval record. - Independent rerun of raw Windows evidence during Phase 0C: **Unverified / not claimed**. diff --git a/docs/phase-0c/EVIDENCE_INVENTORY.md b/docs/phase-0c/EVIDENCE_INVENTORY.md index 1de0924..6862ab8 100644 --- a/docs/phase-0c/EVIDENCE_INVENTORY.md +++ b/docs/phase-0c/EVIDENCE_INVENTORY.md @@ -18,5 +18,6 @@ Each entry uses exactly one approved classification. `Reproducible` is separatel | EVID-010 | Shutdown recovery must distinguish pre-external work from uncertain post-external work. | Worker-shutdown spikes and ADR-0005 | Machine-verified | Yes | ADR-0005 | RISK-010, RISK-016 | Real provider SDK cancellation and OS shutdown integration remain future tests. | Conditional | | EVID-011 | Provider idempotency, rate limits and reconciliation differ by operation. | Provider documentation review and mock fault tests | Documentation-derived | Partial | ADR-0006 | RISK-007, RISK-008, RISK-010 | Provider documentation can change; sandbox tests remain mandatory. | Conditional | | EVID-012 | No Phase 0 evidence requires changing the protected workspace-isolation or global bounded-engine direction. | Architecture review and ADR disposition analysis | Documentation-derived | Yes | ADR-0001..ADR-0006 | RISK-013, RISK-014 | Candidate decisions still require human approval. | Accepted | +| EVID-013 | The Phase 0C candidate documents record proposed application, UX, security, operations and governance directions without claiming implemented behavior or final approval. | Phase 0C candidate documents on Draft PR #3 | Documentation-derived | Yes | ADR-0001..ADR-0006 | Documentation establishes candidate intent only; implementation and acceptance evidence remain future gates. | Conditional | No missing log, screenshot, measurement or machine result is invented. diff --git a/docs/phase-0c/REQUIREMENTS_DISPOSITION_REGISTER.md b/docs/phase-0c/REQUIREMENTS_DISPOSITION_REGISTER.md index 15c99e0..b026f00 100644 --- a/docs/phase-0c/REQUIREMENTS_DISPOSITION_REGISTER.md +++ b/docs/phase-0c/REQUIREMENTS_DISPOSITION_REGISTER.md @@ -7,19 +7,19 @@ The source requirements catalog is reconciled to the candidate's allowed statuse | FR-001..FR-005 | Approved | Workspace ownership, immutable runs and hybrid data architecture; ADR-0003 | EVID-008, EVID-012 | Cross-workspace isolation, snapshot and account-coordination tests | | FR-006..FR-007 | Approved | Capability-based provider platform; ADR-0006 | EVID-011, EVID-012 | Provider contract and sandbox tests | | FR-008..FR-011 | Approved | Global bounded engine, durable states and reconciliation; ADR-0002/0003/0005/0006 | EVID-007, EVID-008, EVID-010, EVID-011 | Fairness, recovery and uncertain-outcome tests | -| FR-012..FR-020 | Proposed | Product workflow/application-service scope | Documentation-derived | Import, preview, test-send, schedule, reports and advanced-control acceptance tests | +| FR-012..FR-020 | Proposed | Product workflow/application-service scope | EVID-013 | Import, preview, test-send, schedule, reports and advanced-control acceptance tests | | NFR-001..NFR-003 | Approved | Isolation, bounded execution and UI-thread separation | EVID-012 | Architecture and integration tests | | NFR-004 | Proposed | Bounded-list direction; ADR-0001 | EVID-004, EVID-006 | Measured Windows UI and accessibility tests | | NFR-005..NFR-006 | Approved | Durable recovery, audit history and redaction | EVID-008, EVID-010 | Restart, audit and secret-scan tests | -| NFR-007..NFR-010 | Proposed | Engineering fitness, packaging, observability and recoverability | EVID-004, EVID-005, EVID-007, EVID-008 | Architecture, packaging, integrity and observability tests | +| NFR-007..NFR-010 | Proposed | Engineering fitness, packaging, observability and recoverability | EVID-004, EVID-005, EVID-007, EVID-008, EVID-013 | Architecture, packaging, integrity and observability tests | | SEC-001..SEC-003 | Approved | OS vault, reference-only storage and package exclusions | EVID-004, EVID-005 | Source/packaged vault and artifact scans | -| SEC-004..SEC-006 | Proposed | Redaction, Version 1 plugin restriction and immutable audit events | Documentation-derived | Redaction, plugin-boundary and audit tests | -| UX-001..UX-004 | Approved | Workflow-first, progressive disclosure and separate Diagnostics | Documentation-derived | Navigation and representative-user review | -| UX-005..UX-007 | Proposed | Error language, preflight and accessibility baseline | EVID-004, EVID-006 | Usability, keyboard, scaling, contrast and assistive tests | +| SEC-004..SEC-006 | Proposed | Redaction, Version 1 plugin restriction and immutable audit events | EVID-013 | Redaction, plugin-boundary and audit tests | +| UX-001..UX-004 | Approved | Workflow-first, progressive disclosure and separate Diagnostics | EVID-013 | Navigation and representative-user review | +| UX-005..UX-007 | Proposed | Error language, preflight and accessibility baseline | EVID-004, EVID-006, EVID-013 | Usability, keyboard, scaling, contrast and assistive tests | | OPS-001..OPS-003 | Approved | Durable store, scoped limits and UI event boundary | EVID-007, EVID-010, EVID-011 | Recovery, rate-limit and architecture tests | -| OPS-004..OPS-006 | Proposed | Shutdown, scheduler and backup/restore directions; ADR-0004/0005 | EVID-009, EVID-010 | Shutdown, restart, DST and restore tests | +| OPS-004..OPS-006 | Proposed | Shutdown, scheduler and backup/restore directions; ADR-0004/0005 | EVID-009, EVID-010, EVID-013 | Shutdown, restart, DST and restore tests | | CON-001..CON-006 | Approved | Product/repository/governance constraints | EVID-001, EVID-003 | Package and PR governance checks | -| CON-007 | Proposed | Windows-first desktop direction | EVID-004 | Supported-version decision and packaging matrix | +| CON-007 | Proposed | Windows-first desktop direction | EVID-004, EVID-013 | Supported-version decision and packaging matrix | | ASM-001..ASM-005 | Proposed | Assumptions remain non-guarantees | EVID-004, EVID-006..EVID-011 | User research and technical validation | No speculative Version 1 feature is promoted to Approved by this package. diff --git a/docs/phase-0c/TRACEABILITY_MATRIX.md b/docs/phase-0c/TRACEABILITY_MATRIX.md index 605c331..153c1f0 100644 --- a/docs/phase-0c/TRACEABILITY_MATRIX.md +++ b/docs/phase-0c/TRACEABILITY_MATRIX.md @@ -4,23 +4,23 @@ |---|---|---|---|---|---| | FR-001, FR-004, NFR-001 | ARCH-INV-005, 006, 017, 019 | ADR-0003 | EVID-008, EVID-012 | RISK-006 | Cross-workspace negative tests and schema ownership checks | | FR-002 | ARCH-INV-007 | Baseline core | EVID-012 | RISK-014 | Domain and persistence structure tests | -| FR-003 | ARCH-INV-008 | Baseline core | Documentation-derived | RISK-010 | Snapshot mutation and historical-integrity tests | +| FR-003 | ARCH-INV-008 | Baseline core | EVID-013 | RISK-010 | Snapshot mutation and historical-integrity tests | | FR-005, FR-011 | ARCH-INV-013, 018 | ADR-0003 | EVID-008 | RISK-004, RISK-008 | Assignment isolation and global-account broker tests | | FR-006, FR-007 | ARCH-INV-011, 012, 016, 028 | ADR-0006 | EVID-011 | RISK-007, RISK-008, RISK-010 | Provider contract and sandbox tests | | FR-008, NFR-002 | ARCH-INV-014, 015 | ADR-0002, ADR-0005 | EVID-007, EVID-010 | RISK-005, RISK-016 | Fairness, concurrency, backpressure and shutdown tests | | FR-009, FR-010, NFR-005 | ARCH-INV-009, 012, 019, 024, 027, 029 | ADR-0003, ADR-0005, ADR-0006 | EVID-008, EVID-010, EVID-011 | RISK-006, RISK-010 | Crash, lease and timeout-after-success tests | -| FR-012..FR-015 | UX/application boundaries | Candidate UX baseline | Documentation-derived | RISK-018 | Import, validation, preview and test-send acceptance tests | +| FR-012..FR-015 | UX/application boundaries | Candidate UX baseline | EVID-013 | RISK-018 | Import, validation, preview and test-send acceptance tests | | FR-016, OPS-005 | ARCH-INV-025, 026 | ADR-0004 | EVID-009 | RISK-003, RISK-016 | DST, missed-run and packaged restart-dedup tests | | FR-017, OPS-004 | ARCH-INV-024, 027, 029 | ADR-0005 | EVID-010 | RISK-010, RISK-016 | Pause, cancellation, shutdown and restart tests | -| FR-018, FR-019, NFR-009 | ARCH-INV-020 | Candidate operations baseline | Documentation-derived | RISK-014, RISK-018 | Report, audit and Problems-to-Review tests | +| FR-018, FR-019, NFR-009 | ARCH-INV-020 | Candidate operations baseline | EVID-013 | RISK-014, RISK-018 | Report, audit and Problems-to-Review tests | | FR-020, OPS-002 | ARCH-INV-013, 014, 028 | ADR-0006 | EVID-011 | RISK-008 | Provider/account/operation rate-limit tests | | NFR-003, OPS-003 | ARCH-INV-001..004 | ADR-0005 | EVID-010, EVID-012 | RISK-013 | Import-boundary and UI event-queue tests | | NFR-004, UX-007 | Bounded rendering and accessibility rules | ADR-0001 | EVID-004, EVID-006 | RISK-002, RISK-011 | Windows GUI, DPI, keyboard and assistive tests | -| NFR-006, SEC-001..SEC-006 | ARCH-INV-010, 018, 020 | Security baseline | EVID-004, EVID-005 | RISK-004, RISK-009, RISK-012, RISK-017 | Vault, redaction, secret-scan, plugin and diagnostic tests | +| NFR-006, SEC-001..SEC-006 | ARCH-INV-010, 018, 020 | Security baseline | EVID-004, EVID-005, EVID-013 | RISK-004, RISK-009, RISK-012, RISK-017 | Vault, redaction, secret-scan, plugin and diagnostic tests | | NFR-007 | ARCH-INV-001..029 | ADR-0001..0006 | EVID-012 | RISK-013, RISK-014 | Architecture fitness and cycle tests | -| NFR-008, CON-007 | Windows `onedir` packaging rules | ADR-0004 | EVID-004, EVID-005, EVID-009 | RISK-003, RISK-004 | Supported-version packaging matrix | +| NFR-008, CON-007 | Windows `onedir` packaging rules | Packaging baseline; ADR-0004 for timezone/restart semantics only | EVID-004, EVID-005, EVID-009, EVID-013 | RISK-003, RISK-004 | Supported-version packaging matrix | | NFR-010, OPS-006 | ARCH-INV-019, 024 | ADR-0003, ADR-0005 | EVID-008, EVID-010 | RISK-006, RISK-017 | Integrity, backup and restore tests | -| UX-001..UX-006 | Workflow-first progressive disclosure | Candidate UX baseline | Documentation-derived | RISK-018 | Moderated usability and preflight tests | +| UX-001..UX-006 | Workflow-first progressive disclosure | Candidate UX baseline | EVID-013 | RISK-018 | Moderated usability and preflight tests | | CON-001..CON-006 | ARCH-INV-021..023 | Governance baseline | EVID-001, EVID-003 | RISK-013, RISK-014, RISK-015 | Package, dependency and PR policy checks | | ASM-001..ASM-005 | Not guarantees; validation required | Relevant ADRs | EVID-004, EVID-006..EVID-011 | RISK-002..RISK-011 | User research and technical validation | diff --git a/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md b/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md index d31f5f8..cd3ff6b 100644 --- a/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md +++ b/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md @@ -4,19 +4,22 @@ - [ ] Confirm repository `vibtools/OpenInvoice`. - [ ] Confirm source commit `4cfc3cb5de400d4459cc5fd691a208abc185018f` or a documented descendant with unchanged target files. +- [ ] Confirm Draft PR #3 remains based on `main` and contains only Phase 0C candidate/audit changes. - [ ] Confirm PR #1 merge and Phase 0B.3 approval record. - [ ] Confirm the local working tree was clean before package application. ## Evidence -- [ ] Review EVID-001 through EVID-012. +- [ ] Review EVID-001 through EVID-013. - [ ] Accept the distinction among machine-verified, repository-verified, human-attested, documentation-derived, partially reproducible, unverified and not applicable evidence. +- [ ] Confirm traceability evidence columns use stable `EVID-*` references rather than classification text. - [ ] Confirm no independent Windows rerun is claimed without raw evidence. ## Architecture and requirements - [ ] Disposition ADR-0001 through ADR-0006. - [ ] Confirm all requirement statuses are Approved, Proposed, Deferred or Rejected. +- [ ] Confirm ADR-0004 is limited to scheduler/timezone/durable-occurrence semantics and is not treated as the general packaging ADR. - [ ] Confirm no architecture invariant or constitutional rule was silently removed. - [ ] Confirm proposed ACRs: None. @@ -26,6 +29,14 @@ - [ ] Confirm no version, production installation or lockfile is approved. - [ ] Review vault, redaction, plugin, diagnostics, UNKNOWN and backup directions. +## PR validation + +- [ ] Record the current PR head SHA. +- [ ] Record combined status checks and GitHub Actions runs. +- [ ] Do not claim a green CI gate when no checks or workflows ran. +- [ ] Keep the PR in Draft until audit corrections and human baseline decisions are complete. +- [ ] Confirm `git diff --check`, YAML parsing, Markdown-link validation and prohibited-artifact checks were executed locally or explicitly recorded as unavailable. + ## Final gate - [ ] Approve, revise or reject `1.0.0-candidate.1`. From 81d393c494557d7240e43bf17f8ca4ebe8b105c3 Mon Sep 17 00:00:00 2001 From: vib-tools Date: Fri, 24 Jul 2026 06:38:55 -0700 Subject: [PATCH 3/4] chore(repo): remove tracked Python bytecode --- .gitignore | 8 ++++++++ .../common/__pycache__/__init__.cpython-312.pyc | Bin 275 -> 0 bytes .../common/__pycache__/evidence.cpython-312.pyc | Bin 5172 -> 0 bytes .../__pycache__/windows_env.cpython-312.pyc | Bin 1920 -> 0 bytes 4 files changed, 8 insertions(+) create mode 100644 .gitignore delete mode 100644 spikes/phase_0b1/common/__pycache__/__init__.cpython-312.pyc delete mode 100644 spikes/phase_0b1/common/__pycache__/evidence.cpython-312.pyc delete mode 100644 spikes/phase_0b1/common/__pycache__/windows_env.cpython-312.pyc diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9a4d6a4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +# Generated Python, environment, test and build artifacts +__pycache__/ +*.py[cod] +.pytest_cache/ +.venv/ +venv/ +build/ +dist/ diff --git a/spikes/phase_0b1/common/__pycache__/__init__.cpython-312.pyc b/spikes/phase_0b1/common/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index c93f37f3a7adb249d9390f3745b680fd754fbedd..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 275 zcmX@j%ge<81Xm^{WmyC1#~=<2FhUuhIe?7m3@Hpz43&(UOjRZ>p1}eB!H!Not_qGp z&K{m2uFfH$L9PnH0iNEj3c3n@{viqhLH;hG&LN)uehSY1F0OihnvA#DL#=s)pzaTX)J~+R$2*?GoJ@d-)GlA^% z%#w`Kr1+xLoYcf(RH@>E%&ryk0@&Ee@O9 g{FKt1RJ$TJp#32K6@&ctftit!@fL$s5etw504D5DlK=n! diff --git a/spikes/phase_0b1/common/__pycache__/evidence.cpython-312.pyc b/spikes/phase_0b1/common/__pycache__/evidence.cpython-312.pyc deleted file mode 100644 index a27765428c7b57e52189701b42f384398b0bc43b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 5172 zcmbUlOKcm*b(Xta{zaJ-Wl6LeMvi2&j^s~d*HH}DvLwTbV%m_D#9?eNR@{}i6qn1) zF7*SA$Up#FZ2-qjTg#{cyQesC4hc}SKJ?HJP!#Az44sf&GiZVIlAB#6NZ?c7>~cw3 zpc9}&aOTa-n>UZ|Km3Q!=SI-(|6(Tfi3g!C$;4{32~eAV1mHRnP#g)AU`tc7EpDR- zOsDBMZH!FZZj5Z4HAY9=VT{hW(->WGmod8IZe#SsJuot9uk4L`WnbK9(6gsoWPjXm zz-+oz-WJ~mup=H2{DSixCLR=81s9BM!ZyJTV@L=H9vIt&px}jZyU-?t1m8RMcn3i3 zLJL5h%XD=6%HZhu)S1&$!^dA4iwsYWoE)DX8<~D}ax5}+W_)5S(jSSPo{pTEJU#mA z$n^N>SY+h%=-9wlL;z7r_wbpFqVbxfWYk#HraJ{*6E#T|btmapl#B>i%o$!w!blHi zmRDZ*KkiGI@-}-SeE3qE0sz;MMp>IFn+4TJjj`YqYeDt#ZuM-+RbR89yH#KceMrTk zc1#HAbVgakb_2?33Ed^B%B+HAUi%Pj68y)?=+L>>q?u_&NvquJ3Z7T9d_p|8?=W{d zD`vPUC5K^3;PK3YA^|)nY02CShsCtWt50sJS!rHW&t;Ra!R?#be=ecOvXVI`E=Yoy zNr(g4W!(XMaD=N?xIPG9^+(XHqKYSY^~lK=;R39x)EW6aYt-Tb{>Xv3< z3)D^T6pGqnQLpY#@L4T~MSafnN?@KYZ=*`$Io}yVBKD>gq3a^%uMLKI-&&*@wtyXHEaB#Vufr*skG!zcc)A z4qc@3XcV3QH9{9{E~LS>*_wG@s^*&(7D9QOWkVO~Je49LYfH=9et@cD%K@0yspjcs zF;k$dTc5ID-1iho z36SEA&lC5(f!-}Fq9ytbv`9tSnC_U$$uf^2CcgrKJ)?>%u9J!^_GkGyam8~6D=F}i z{#PeoiQ080!^@)K7P>>Vj-}0Gx+@9CIC3n?LXMHM3f9unjP8_0jfV`&>nxvz6e5@e zXmAC+?F^rohZ8YHJE7z zIVrOMjsw1o4+73^_^N+{ZWWbx|9ExuL2Kv=^U&sYWvEJUM=97_2=A^A!2-o@gfQ;$4sXUjK;_4yw<(6;u69mw0dI`Q4tcGTKg@;_Vf zKU?x2D)J!2Dz$6X`MFA*8{w7X%>IPG4>;sT7;kV2BP2t_k1sY)wG$I zZo@N)MzSR00ISqy9{|6iuA?=SY7}7=xBk!NCbDw?qs3Xx>`;zL#FksLzRC8dKu&}i?%Np?TpgyuS7*tb(271IrwlslWffXwn zgAv=B8L?I~xKxu$EDsMK;KBY8dzT0tn&2Q*1?NYuI#(LW@krFMJVVwH8(peErI2kqk9p9)p44* zr0Gmbg}TZvJIt~1(#MNqXx=M#oz;W0ZhOasc z9Yklwd3oZ}M2QI%n9#a#XL^GP-DeJz-7O_|SHa!2K6vY;8!z2yFNF6N-TPKY%8cW3 z>{1MBm7!}x>vMPbdxL)$?+2$hUVpO?d~;(~UX9&nG8Kls{PLxjuc+^he#Uf~g-ca6 za4SN@)eKV;0BDSqd5DHu%_u>sHmz2KSP`in3-dH2e27bPH3Q1q1lss8H{A{Dv>S=` zIB`r-(3z9cT=GQJt=lyW=}%`N{mv8TR^d&WgAy~LWM<8`l2Hii-ddiMAStpCeTXi) z7D4xrA3;B088eEoTrGFuif4EXwXp`7n^;03$!F$74pMSjB;_R_c=-f|*V|h;D1ik$ z4q}KhhHiBB)bQlQ*rai@kxOCY0_^LolGCy|4JTlNXP~pfOEnuijKBlbAYh`CWd9g+ z5LuX(D+}dq?Ug`BIS?+l@2G6=dH-Uigc@OR5+rx17@4fW9LrdU^w zP4gIPl>X{GVix}J@`y-kMCLOPh@sqwz$+!9C1GiSPfM^y5DdKzfM?Vn6htVnKqQGt z$TcPSgq!%Q`rxXH#c9Ah3tx2?bRbBF|MJ_H-Yz;i*2h0}^j7@s@8#BKH~NwrsfD6{ zal^S-_V^8XLF51{0o`YC4;+o!unfcF7C}mAZ$kQdJ_7$~oCn1ofaMie8bS+MK5w9{ zgpGL}7j`1~NDTfJIZw_IZ#N$|gs6D|+ptPF#u?I)eVri(u?xVc+x+>2B~u1Om8Lxz zYcnu?+*;$NdZ|f0~GSaT$XNH#;8s7R4bRLlvA(s}9;zc-1stlDd1EnBE{Sys+fqK3~Ee}xV1LS#t zTn~`{0hzi1_!rvs1?u<$wg207bd}v?DeAzcvxQ-^>iW9HNBO>q K&{V5oEdK*d*=u?L diff --git a/spikes/phase_0b1/common/__pycache__/windows_env.cpython-312.pyc b/spikes/phase_0b1/common/__pycache__/windows_env.cpython-312.pyc deleted file mode 100644 index 5e00034c15f8034b8ed6bd88152ce6d274220c90..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1920 zcma)7|8EpU6ra5>yZ4nVTxl?evJ^{l!9oGQ5FjMjtJ)}SzVns!yP0yp;ZNBJkcY>9<*AQY#E5hTUeF4?9P~PI< zikjT#iE+2P*HwiFm6qmO<_RaM+wlzD&Zl)eALW)_1 z9r|zag$PbBL~f(6BX_&!FQZ~+OlXs~hv{X1J`H6Zyxf@xt>Mji^s+avd32Cb%0-e9 zmp095hlu!$eT875N)3mpg&B2)#!MI6{#;RGa)WhQgY`gyTR`j3XlPy5bX^59AGatb zgT=H+)E$%0Q05BNZ~2_KOnO2z;!~$dglc-$EM-Eqc&ko)p~@5;M9*g(RKYFRysNLo;_Wm)bWi;%I5sK zX_2X+6UKO*ct)8v7)+%+>NTki@+F(kHl__m9Af(aHTiXWj`&mcSuhww(?_Q)>blgM z>Xy?WUh{ChB~nR&TKE8JS+KRU4*61(Vz*=r^JDppK-OPNR zxv^ulXJEN!U?qKUvDD7&`t01N=TDtL_?4!HCP+1!Dn)P~h38bvVLvp|;i&N?Sb43`g&1 z0EpO_$ik%^KV}eY%Qt4eJXU$5tdlEsVsV0X=v3XImg(pL2=w4aPw7p7c}zg+L-#XVfCTPnluShR2IZ)(hT33!?&zf^HQWw5G{9V*@hU-p!B^>WidRZ*SAocAAb`(74cVOG%7XkS%>F^zRznBr4VPI+*hDaI4Oaqn@!(bBp zY>y;|CF#^kz7dW+-FbIZ0H^I;V)CU5iXI&II}{|;sYv3qOL4;?XBd1ckSvw|B9O;X kMNxi5Cm*8zM=1LMB_E*NL$v21>f2DWO8;MaQt2G)U)Ms)&j0`b From 61ab3f42c48571881d5ac43d53e12816b53b35ae Mon Sep 17 00:00:00 2001 From: vib-tools Date: Fri, 24 Jul 2026 10:05:58 -0700 Subject: [PATCH 4/4] docs(approval): record Phase 0C baseline decision --- BASELINE_MANIFEST.yml | 17 ++-- CHANGELOG.md | 24 ++++- DEPENDENCIES.md | 32 +++---- NEXT_ASSIGNMENT.md | 31 ++++--- PROJECT_STATUS.md | 48 +++++----- README.md | 28 +++--- ...R-0001-bounded-large-data-list-strategy.md | 16 ++-- ...002-sqlite-wal-and-bounded-writer-model.md | 16 ++-- ...database-reservation-and-reconciliation.md | 16 ++-- ...rigger-boundary-and-durable-occurrences.md | 22 +++-- ...ed-worker-shutdown-and-unknown-outcomes.md | 16 ++-- ...tion-level-provider-capability-contract.md | 16 ++-- docs/phase-0c/ADR_DISPOSITION_REGISTER.md | 46 ++++------ docs/phase-0c/BASELINE_APPROVAL_PACKET.md | 50 ++++++----- .../DEPENDENCY_DISPOSITION_REGISTER.md | 32 +++---- docs/phase-0c/OPEN_DECISIONS.md | 33 ++++--- docs/phase-0c/README.md | 25 +++--- docs/reviews/PHASE_0C_APPROVAL_RECORD.md | 87 +++++++++++++++++++ docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md | 70 ++++++++------- 19 files changed, 408 insertions(+), 217 deletions(-) create mode 100644 docs/reviews/PHASE_0C_APPROVAL_RECORD.md diff --git a/BASELINE_MANIFEST.yml b/BASELINE_MANIFEST.yml index b176df6..3313e3e 100644 --- a/BASELINE_MANIFEST.yml +++ b/BASELINE_MANIFEST.yml @@ -3,10 +3,14 @@ project: repository: vibtools/OpenInvoice baseline: - version: 1.0.0-candidate.1 - status: candidate + version: 1.0.0 + status: approved + candidate_version: 1.0.0-candidate.1 prepared_from_commit: 4cfc3cb5de400d4459cc5fd691a208abc185018f + candidate_head_sha: 81d393c494557d7240e43bf17f8ca4ebe8b105c3 prepared_at: 2026-07-23 + approved_at: 2026-07-24 + approval_record: docs/reviews/PHASE_0C_APPROVAL_RECORD.md human_approval_required: true phase_gates: @@ -15,12 +19,14 @@ phase_gates: phase_0b1: remediation_required phase_0b2: not_approved phase_0b3: approved_by_human - phase_0c: ready_for_human_review + phase_0c: approved_by_human evidence: phase_0b3_source_integration: repository_verified phase_0b3_windows_validation: human_attested phase_0b3_independent_reexecution_in_phase_0c: false + phase_0c_technical_validation: human_attested_from_recorded_local_execution + phase_0c_github_state: repository_verified architecture: domain_model: @@ -44,9 +50,10 @@ governance: architecture_change_implemented: false ai_can_approve_changes: false direct_push_to_main: false - baseline_tag_authorized: false + baseline_tag_authorized: true + baseline_tag_created: false implementation: production_code_allowed: false - next_phase_authorized: false + next_phase_authorized: true production_lockfile_allowed: false diff --git a/CHANGELOG.md b/CHANGELOG.md index ae9cc2b..6a71a59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,13 +2,34 @@ ## Unreleased +### Phase 0C approval + +#### Added + +- Human Architecture Owner and Final Approver record for baseline `1.0.0`. +- Final dispositions for ADR-0001 through ADR-0006 and all 13 dependency directions. + +#### Changed + +- Approved candidate `1.0.0-candidate.1` as controlled baseline `1.0.0`. +- Authorized `baseline-v1.0.0` creation after reviewed merge and authorized Phase 1 repository-governance/CI work after baseline finalization. +- Retained all ADR validation conditions and unresolved product, performance, accessibility, backup, provider and trademark decisions. + +#### Fixed + +- Removed tracked Python bytecode and added repository ignore rules for generated Python, environment, test and build artifacts. + +#### Security + +- Production feature code, production dependency versions, production installation and production lockfile remain unauthorized. +- No architecture change was implemented and no ACR was required. + ### Phase 0B.3 - Added deterministic PyInstaller/Tcl-Tk packaging diagnostics and isolated build roots. - Added packaged credential, timezone, and scheduler restart validation gates. - No production dependency or architecture change was approved. - ### Added - Phase 0B.2 remediation report and human-review checklist. @@ -36,7 +57,6 @@ - Credential validation remains synthetic only and requires deletion plus secret scanning. - No real credentials, customer data, provider operations, executables, databases, build output, or virtual environments are included in the update package. - ### Phase 0C candidate #### Added diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md index b202268..20a0538 100644 --- a/DEPENDENCIES.md +++ b/DEPENDENCIES.md @@ -1,30 +1,30 @@ -# Dependency Candidate Summary +# Dependency Direction Summary -This file summarizes Phase 0C dependency dispositions. It does not approve versions, create a lockfile or authorize production installation. +The Human Architecture Owner approved the following Phase 0C directions on 2026-07-24. These decisions approve boundaries and Phase 1 evaluation scope only. They do not approve exact versions, create a lockfile, authorize production installation or permit unrestricted production imports. -## Candidate for next phase +## Approved for Phase 1 evaluation or development tooling - PyInstaller — Windows `onedir` packaging tooling. -- pytest — development test runner. -- Ruff — lint/format tooling. -- uv — environment and future lock management. -- SQLAlchemy — persistence evaluation within infrastructure. -- Alembic — migration evaluation and ownership. +- pytest — development/test runner only. +- Ruff — development/CI lint and formatting only. +- uv — build/CI and lock-management evaluation. +- SQLAlchemy — infrastructure persistence evaluation; never the domain model. +- Alembic — infrastructure migration evaluation. - HTTPX — provider transport evaluation behind adapters. -## Conditional candidate +## Approved conditional candidates -- CustomTkinter — UI shell only; bounded data views and accessibility gates required. -- keyring — OS vault only; fail-closed source and packaged tests required. -- tzdata — Windows IANA timezone data; packaged resolution and update review required. -- APScheduler — schedule trigger only; never the durable invoice job engine. +- CustomTkinter — presentation shell only; bounded data views, UI-thread discipline and accessibility gates remain mandatory. +- keyring — OS vault adapter only; fail-closed source and packaged validation remains mandatory. +- tzdata — Windows IANA timezone direction; packaged zone resolution, supply-chain review and DST tests remain mandatory. +- APScheduler — trigger-only scheduler adapter; it must never become the durable invoice job engine. ## Deferred -- SQLModel — deferred until the SQLAlchemy persistence walking skeleton proves a concrete need; it may never become the domain model. +- SQLModel — deferred until an approved SQLAlchemy walking skeleton proves a concrete need; it may never become the domain model. ## Spike/test only -- psutil — retained for validation and diagnostics experiments only unless a future approved requirement justifies runtime use. +- psutil — retained for spike/test measurement and diagnostics only; runtime use requires a future explicit decision. -Detailed license, boundary, evidence, security, packaging, upgrade and replacement information is in [Dependency Disposition Register](docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md). +Detailed license, boundary, evidence, security, packaging, upgrade and replacement information is in the [Dependency Disposition Register](docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md). diff --git a/NEXT_ASSIGNMENT.md b/NEXT_ASSIGNMENT.md index 9981a5e..2424401 100644 --- a/NEXT_ASSIGNMENT.md +++ b/NEXT_ASSIGNMENT.md @@ -2,21 +2,32 @@ ## Phase 1 — Repository Governance and CI Foundation -**Status: Blocked until explicit Phase 0C baseline approval.** +**Authorization: Approved by the Human Architecture Owner and Final Approver on 2026-07-24.** -After the Human Architecture Owner approves the Phase 0C candidate through a separate controlled action, Phase 1 may establish: +**Activation status: Pending Phase 0C repository finalization.** Phase 1 begins only after all of these actions complete: + +1. Commit and push the Phase 0C Final Approval Patch to `docs/phase-0c-controlled-baseline`. +2. Revalidate Draft PR #3 at the resulting approval-record head. +3. Mark PR #3 ready only after final verification. +4. Merge PR #3 into `main` through the reviewed workflow. +5. Create and verify `baseline-v1.0.0` from the merged `main` commit. + +## Authorized Phase 1 scope + +Phase 1 may establish: - protected branch and repository rules; - CODEOWNERS, pull-request and issue templates; - CI bootstrap and deterministic documentation checks; -- secret scanning, dependency review, license checks, and SBOM direction; -- approved Python/build-tool baseline and lockfile workflow; +- secret scanning, dependency review, license checks and SBOM direction; +- approved Python/build-tool evaluation and proposed lockfile workflow; - architecture-fitness test scaffolding. -Phase 1 must not begin merely because this candidate package was applied or merged. The approval action must separately: +## Restrictions retained -1. record accepted/revised/rejected ADR dispositions; -2. record dependency decisions; -3. change baseline status from `candidate` to `approved`; -4. authorize `baseline-v1.0.0`; -5. set `production_code_allowed` or next-phase authorization as explicitly approved. +- Production invoice feature code is not authorized. +- A production dependency lockfile is not authorized by Phase 0C. +- Exact dependency versions remain unapproved until the Phase 1 dependency/build gate. +- Dependency installation or import into production code is not implied by a direction approval. +- Database schema, provider integration, execution-engine, scheduler and UI implementation remain outside this assignment. +- Direct push to `main`, force push and destructive Git operations remain prohibited. diff --git a/PROJECT_STATUS.md b/PROJECT_STATUS.md index 51c13e9..79fa627 100644 --- a/PROJECT_STATUS.md +++ b/PROJECT_STATUS.md @@ -5,36 +5,42 @@ | Project | OpenInvoice | | Repository | `vibtools/OpenInvoice` | | Source commit | `4cfc3cb5de400d4459cc5fd691a208abc185018f` | -| Current phase | Phase 0C — Controlled Baseline Candidate | +| Human-reviewed candidate head | `81d393c494557d7240e43bf17f8ca4ebe8b105c3` | +| Current phase | Phase 0C — Human-approved; repository finalization pending | | Phase 0A | Approved | | Phase 0B | Approved with conditions | | Phase 0B.1 | Remediation required | | Phase 0B.2 | Not approved; remediation continued | | Phase 0B.3 | Approved by Human Architecture Owner | -| Candidate baseline | `1.0.0-candidate.1` | -| Baseline status | Ready for Human Architecture Owner Review | -| Production code | Not started | -| Baseline tag | Not created | -| Phase 1 | Not authorized | +| Phase 0C | Approved by Human Architecture Owner and Final Approver | +| Approved baseline | `1.0.0` | +| Baseline tag | `baseline-v1.0.0` authorized; not yet created | +| Phase 1 | Authorized after baseline merge/tag finalization; not started | +| Production code | Not authorized | +| Production lockfile | Not authorized | ## Evidence classification -- Repository integration and merge commit: **Repository-verified**. +- Repository integration and PR state: **Repository-verified**. - Phase 0B.3 final Windows pass: **Human-attested** from a separate validation session. -- Spike outputs and candidate directions are classified in EVID-001 through EVID-013. -- Preparation-state blocked reports remain historical records; current status is established by the separate approval record. +- Phase 0C local technical validation: **Human-attested** from recorded PowerShell execution against candidate head `81d393c494557d7240e43bf17f8ca4ebe8b105c3`. +- Spike outputs and candidate directions remain classified in EVID-001 through EVID-013. - Independent rerun of raw Windows evidence during Phase 0C: **Unverified / not claimed**. +- No GitHub Actions workflow or combined status check is represented as green when none ran. -## Phase 0C checklist +## Phase 0C disposition -- [x] Phase 0B.3 approval record drafted. -- [x] Evidence inventory prepared. -- [x] Six proposed ADRs reviewed. -- [x] Architecture, UX, engineering, security, and operations candidate documentation consolidated. -- [x] Dependency dispositions prepared without inventing production versions. -- [x] Traceability matrix prepared. -- [x] Candidate manifest generated. -- [ ] Human Architecture Owner approves/revises ADR dispositions. -- [ ] Human Architecture Owner approves/rejects dependency directions. -- [ ] Human Architecture Owner approves/rejects baseline `1.0.0`. -- [ ] Separate approval action authorizes Phase 1 and baseline tag. +- [x] Technical validation completed. +- [x] Six ADRs accepted with conditions by the Human Architecture Owner. +- [x] All 13 dependency directions dispositioned. +- [x] Baseline `1.0.0-candidate.1` approved as baseline `1.0.0`. +- [x] `baseline-v1.0.0` authorized. +- [x] Phase 1 — Repository Governance and CI Foundation authorized. +- [x] Production feature code remains prohibited. +- [x] Production lockfile remains prohibited. +- [x] Architecture change implemented: No. +- [x] ACR required: No. +- [ ] Final Approval Patch committed and pushed. +- [ ] PR #3 final verification completed after the approval commit. +- [ ] PR #3 merged into `main`. +- [ ] Authorized baseline tag created from the verified merged `main` commit. diff --git a/README.md b/README.md index 6b7c743..84e663e 100644 --- a/README.md +++ b/README.md @@ -4,28 +4,34 @@ OpenInvoice is a planned Windows desktop invoice-operations platform for prepari ## Current status -OpenInvoice is in **Phase 0C — Controlled Baseline Candidate**. +OpenInvoice has a **human-approved controlled baseline `1.0.0`**. Phase 0C repository finalization is pending the reviewed merge of PR #3 and creation of the authorized baseline tag. -> No production invoice-processing implementation has started. The candidate baseline requires explicit Human Architecture Owner approval before Phase 1 is authorized. +> No production invoice-processing implementation has started. Phase 1 is limited to repository governance and CI foundation work after baseline finalization. -- Candidate baseline: `1.0.0-candidate.1` -- Source commit: `4cfc3cb5de400d4459cc5fd691a208abc185018f` +- Approved baseline: `1.0.0` +- Approved from candidate: `1.0.0-candidate.1` +- Human-reviewed candidate head: `81d393c494557d7240e43bf17f8ca4ebe8b105c3` - Canonical repository: `vibtools/OpenInvoice` -- Phase 0B.3: human-approved based on an external Windows validation session; repository integration is verified, while raw evidence availability is classified separately. +- Authorized tag: `baseline-v1.0.0` — not yet created +- Phase 1: authorized after merge/tag finalization; not started +- Production code: not authorized +- Production lockfile: not authorized -## Candidate architecture +## Approved architecture direction -- Isolated Workspaces with separate Run, Job, and Attempt lifecycles. +- Isolated Workspaces with separate Run, Job and Attempt lifecycles. - `control.db` plus one isolated `workspace.db` per workspace. - Workspace-scoped logical queues served by a global bounded engine. - Capability-based provider adapters and operation-level retry safety. -- Immutable run snapshots, durable state, `UNKNOWN` outcomes, and reconciliation before retry. +- Immutable run snapshots, durable state, `UNKNOWN` outcomes and reconciliation before retry. +- Trigger-only scheduling with durable occurrence identity. - Workflow-oriented Standard experience with progressive Advanced controls and separate Diagnostics. -- Windows `onedir` packaging candidate with packaged credential and timezone validation gates. +- Windows `onedir` packaging direction with packaged credential and timezone validation gates. -## Baseline review +## Baseline records - [Phase 0C Overview](docs/phase-0c/README.md) +- [Phase 0C Approval Record](docs/reviews/PHASE_0C_APPROVAL_RECORD.md) - [Baseline Approval Packet](docs/phase-0c/BASELINE_APPROVAL_PACKET.md) - [Evidence Inventory](docs/phase-0c/EVIDENCE_INVENTORY.md) - [ADR Disposition Register](docs/phase-0c/ADR_DISPOSITION_REGISTER.md) @@ -35,7 +41,7 @@ OpenInvoice is in **Phase 0C — Controlled Baseline Candidate**. ## Governance -AI may prepare and recommend this candidate but may not approve the baseline, accept ADRs, create `baseline-v1.0.0`, or authorize implementation. Those actions require a separate explicit human decision. +The Human Architecture Owner and Final Approver approved the baseline and authorized Phase 1. AI did not approve the baseline, ADRs, tag or implementation. Direct push to `main` remains prohibited. ## License status diff --git a/docs/adr/proposed/ADR-0001-bounded-large-data-list-strategy.md b/docs/adr/proposed/ADR-0001-bounded-large-data-list-strategy.md index 5db8c1b..f9022da 100644 --- a/docs/adr/proposed/ADR-0001-bounded-large-data-list-strategy.md +++ b/docs/adr/proposed/ADR-0001-bounded-large-data-list-strategy.md @@ -1,14 +1,15 @@ # ADR-0001 - Bounded Large-Data List Strategy -- Status: Proposed +- Status: Accepted - Date: 2026-07-23 -- Decision authority: Human Architecture Owner +- Decision date: 2026-07-24 +- Decision authority: Human Architecture Owner and Final Approver ## Context Large customer datasets can impose memory and interaction costs. Actual CustomTkinter rendering remains unvalidated, but bounded paging/windowing had stable headless costs while full materialization scaled with dataset size. -## Proposed decision +## Decision All production large-list views shall use pagination or a windowed/virtualized data source. CustomTkinter may remain a shell candidate but is not approved by this ADR. @@ -36,8 +37,13 @@ NFR-004, UX-007, ARCH-INV-001, ARCH-INV-004 ## Human disposition -- [ ] Accepted +- [x] Accepted - [ ] Rejected - [ ] Revision required +- Decision: Accepted with Conditions +- Approver: Human Architecture Owner and Final Approver +- Date: 2026-07-24 +- Approval record: [`PHASE_0C_APPROVAL_RECORD.md`](../../reviews/PHASE_0C_APPROVAL_RECORD.md) +- Conditions: Repeatable Windows interaction, DPI, keyboard, focus, contrast and assistive-technology tests remain mandatory. -AI has not approved this ADR. +AI did not approve this ADR; the human decision is recorded above. diff --git a/docs/adr/proposed/ADR-0002-sqlite-wal-and-bounded-writer-model.md b/docs/adr/proposed/ADR-0002-sqlite-wal-and-bounded-writer-model.md index cef6bc8..62e76ed 100644 --- a/docs/adr/proposed/ADR-0002-sqlite-wal-and-bounded-writer-model.md +++ b/docs/adr/proposed/ADR-0002-sqlite-wal-and-bounded-writer-model.md @@ -1,14 +1,15 @@ # ADR-0002 - SQLite WAL and Bounded Writer Model -- Status: Proposed +- Status: Accepted - Date: 2026-07-23 -- Decision authority: Human Architecture Owner +- Decision date: 2026-07-24 +- Decision authority: Human Architecture Owner and Final Approver ## Context Uncontrolled concurrent writers produced lock failures. WAL with busy timeout and especially a queued dedicated writer completed all synthetic writes with clean integrity checks. -## Proposed decision +## Decision Use WAL mode, short transactions, explicit busy timeout, bounded write commands, and application-owned checkpoint policy. A dedicated writer service is the default write model for each active database. @@ -36,8 +37,13 @@ NFR-005, NFR-010, OPS-001, ARCH-INV-009 ## Human disposition -- [ ] Accepted +- [x] Accepted - [ ] Rejected - [ ] Revision required +- Decision: Accepted with Conditions +- Approver: Human Architecture Owner and Final Approver +- Date: 2026-07-24 +- Approval record: [`PHASE_0C_APPROVAL_RECORD.md`](../../reviews/PHASE_0C_APPROVAL_RECORD.md) +- Conditions: Migration tests, writer-failure tests, representative Windows storage tests and production ceilings remain mandatory. -AI has not approved this ADR. +AI did not approve this ADR; the human decision is recorded above. diff --git a/docs/adr/proposed/ADR-0003-hybrid-database-reservation-and-reconciliation.md b/docs/adr/proposed/ADR-0003-hybrid-database-reservation-and-reconciliation.md index 386c18f..89ade63 100644 --- a/docs/adr/proposed/ADR-0003-hybrid-database-reservation-and-reconciliation.md +++ b/docs/adr/proposed/ADR-0003-hybrid-database-reservation-and-reconciliation.md @@ -1,14 +1,15 @@ # ADR-0003 - Hybrid Database Reservation and Reconciliation -- Status: Proposed +- Status: Accepted - Date: 2026-07-23 -- Decision authority: Human Architecture Owner +- Decision date: 2026-07-24 +- Decision authority: Human Architecture Owner and Final Approver ## Context The hybrid direction cannot rely on atomic cross-database transactions. Fault injection demonstrated convergence when reservation, lease, provider idempotency, and reconciliation were explicit. -## Proposed decision +## Decision Keep `control.db` and isolated workspace databases. Coordinate through expiring reservations and leases. Persist stable idempotency context. Reconciliation must be repeatable and convergent. @@ -36,8 +37,13 @@ FR-001, FR-010, NFR-010, ARCH-INV-017, ARCH-INV-019 ## Human disposition -- [ ] Accepted +- [x] Accepted - [ ] Rejected - [ ] Revision required +- Decision: Accepted with Conditions +- Approver: Human Architecture Owner and Final Approver +- Date: 2026-07-24 +- Approval record: [`PHASE_0C_APPROVAL_RECORD.md`](../../reviews/PHASE_0C_APPROVAL_RECORD.md) +- Conditions: Production crash tests, migration tests, multi-workspace stress and backup/restore validation remain mandatory. -AI has not approved this ADR. +AI did not approve this ADR; the human decision is recorded above. diff --git a/docs/adr/proposed/ADR-0004-scheduler-trigger-boundary-and-durable-occurrences.md b/docs/adr/proposed/ADR-0004-scheduler-trigger-boundary-and-durable-occurrences.md index 2fbbcdb..6e145ed 100644 --- a/docs/adr/proposed/ADR-0004-scheduler-trigger-boundary-and-durable-occurrences.md +++ b/docs/adr/proposed/ADR-0004-scheduler-trigger-boundary-and-durable-occurrences.md @@ -1,14 +1,15 @@ # ADR-0004 - Scheduler Trigger Boundary and Durable Occurrences -- Status: Proposed +- Status: Accepted - Date: 2026-07-23 -- Decision authority: Human Architecture Owner +- Decision date: 2026-07-24 +- Decision authority: Human Architecture Owner and Final Approver ## Context Scheduling must not become the invoice job engine. Restart behavior, missed occurrences, local-time ambiguity, and packaged Windows execution require application-owned identity and explicit timezone data. -## Proposed decision +## Decision The scheduler announces due occurrences only. Application storage owns schedule definitions, unique occurrence keys, durable Run creation, cancellation, review items, and missed-run disposition. @@ -18,7 +19,7 @@ Persist: - The user's IANA timezone identifier separately. - A deterministic unique occurrence key that prevents duplicate durable Runs across repeated startup. -For Windows builds requiring IANA timezone behavior, `tzdata` is a proposed runtime dependency. The packaged application must demonstrate resolution of `UTC` and `America/New_York`; PyInstaller collection rules must be explicit when default hooks do not include the data. +For Windows builds requiring IANA timezone behavior, `tzdata` is an approved conditional runtime direction. The packaged application must demonstrate resolution of `UTC` and `America/New_York`; PyInstaller collection rules must be explicit when default hooks do not include the data. Exact versions and production adoption remain future controlled decisions. ## Alternatives considered @@ -34,7 +35,7 @@ Ambiguous and nonexistent local times require explicit resolution. Packaging tes ## Risks and limitations -Target-Windows source and packaged evidence remains pending after remediation. `tzdata` production adoption requires Phase 0C human approval. +Phase 0C did not independently rerun the Windows package. Repeatable packaged timezone and restart-dedup tests remain mandatory in the approved build pipeline. ## Evidence @@ -48,12 +49,17 @@ FR-016, OPS-005, ARCH-INV-008, ARCH-INV-009 ## Human disposition -- [ ] Accepted +- [x] Accepted - [ ] Rejected - [ ] Revision required +- Decision: Accepted with Conditions +- Approver: Human Architecture Owner and Final Approver +- Date: 2026-07-24 +- Approval record: [`PHASE_0C_APPROVAL_RECORD.md`](../../reviews/PHASE_0C_APPROVAL_RECORD.md) +- Conditions: Repeatable packaged timezone resolution, DST handling and restart deduplication tests remain mandatory; exact `tzdata` and APScheduler versions remain unapproved. -AI has not approved this ADR. +AI did not approve this ADR; the human decision is recorded above. ## Phase 0B.3 packaging amendment -Packaged validation must resolve the stored IANA timezone and must use a durable unique occurrence key across process restarts. The first packaged launch must create one occurrence and the second launch must observe the existing occurrence without creating a duplicate. `tzdata` remains a proposed candidate dependency pending Phase 0C approval. +Packaged validation must resolve the stored IANA timezone and must use a durable unique occurrence key across process restarts. The first packaged launch must create one occurrence and the second launch must observe the existing occurrence without creating a duplicate. The `tzdata` direction is conditionally approved; production adoption remains gated by version, supply-chain and packaged-test review. diff --git a/docs/adr/proposed/ADR-0005-bounded-worker-shutdown-and-unknown-outcomes.md b/docs/adr/proposed/ADR-0005-bounded-worker-shutdown-and-unknown-outcomes.md index 0446de5..2cdc33e 100644 --- a/docs/adr/proposed/ADR-0005-bounded-worker-shutdown-and-unknown-outcomes.md +++ b/docs/adr/proposed/ADR-0005-bounded-worker-shutdown-and-unknown-outcomes.md @@ -1,14 +1,15 @@ # ADR-0005 - Bounded Worker Shutdown and Unknown Outcomes -- Status: Proposed +- Status: Accepted - Date: 2026-07-23 -- Decision authority: Human Architecture Owner +- Decision date: 2026-07-24 +- Decision authority: Human Architecture Owner and Final Approver ## Context Workers cannot guarantee interruption of an external operation. Shutdown must distinguish work that never crossed the external boundary from work with an uncertain outcome. -## Proposed decision +## Decision Shutdown shall stop new claims, request cooperative cancellation, wait a bounded grace period, persist known results, expire leases, and mark externally uncertain work `UNKNOWN` for reconciliation after restart. @@ -36,8 +37,13 @@ FR-017, OPS-003, OPS-004, ARCH-INV-004, ARCH-INV-024 ## Human disposition -- [ ] Accepted +- [x] Accepted - [ ] Rejected - [ ] Revision required +- Decision: Accepted with Conditions +- Approver: Human Architecture Owner and Final Approver +- Date: 2026-07-24 +- Approval record: [`PHASE_0C_APPROVAL_RECORD.md`](../../reviews/PHASE_0C_APPROVAL_RECORD.md) +- Conditions: Real provider-adapter cancellation, Windows shutdown-signal and restart integration tests remain mandatory. -AI has not approved this ADR. +AI did not approve this ADR; the human decision is recorded above. diff --git a/docs/adr/proposed/ADR-0006-operation-level-provider-capability-contract.md b/docs/adr/proposed/ADR-0006-operation-level-provider-capability-contract.md index 2d83384..96fa6b3 100644 --- a/docs/adr/proposed/ADR-0006-operation-level-provider-capability-contract.md +++ b/docs/adr/proposed/ADR-0006-operation-level-provider-capability-contract.md @@ -1,14 +1,15 @@ # ADR-0006 - Operation-Level Provider Capability Contract -- Status: Proposed +- Status: Accepted - Date: 2026-07-23 -- Decision authority: Human Architecture Owner +- Decision date: 2026-07-24 +- Decision authority: Human Architecture Owner and Final Approver ## Context Official provider documentation shows different idempotency scopes, retention descriptions, request identifiers, rate-limit details, and reconciliation options. One universal retry policy would be unsafe. -## Proposed decision +## Decision Each provider operation shall declare idempotency support, key scope/retention where known, status lookup, correlation identifier, safe retry classes, rate-limit signals, and reconciliation behavior. `UNKNOWN` blocks blind retry. @@ -36,8 +37,13 @@ FR-006, FR-007, FR-010, OPS-002, ARCH-INV-011, ARCH-INV-012, ARCH-INV-016 ## Human disposition -- [ ] Accepted +- [x] Accepted - [ ] Rejected - [ ] Revision required +- Decision: Accepted with Conditions +- Approver: Human Architecture Owner and Final Approver +- Date: 2026-07-24 +- Approval record: [`PHASE_0C_APPROVAL_RECORD.md`](../../reviews/PHASE_0C_APPROVAL_RECORD.md) +- Conditions: Provider-operation sandbox tests, capability-contract tests and periodic official-documentation review remain mandatory. -AI has not approved this ADR. +AI did not approve this ADR; the human decision is recorded above. diff --git a/docs/phase-0c/ADR_DISPOSITION_REGISTER.md b/docs/phase-0c/ADR_DISPOSITION_REGISTER.md index 8f7574b..720548d 100644 --- a/docs/phase-0c/ADR_DISPOSITION_REGISTER.md +++ b/docs/phase-0c/ADR_DISPOSITION_REGISTER.md @@ -1,79 +1,67 @@ # ADR Disposition Register -No ADR is marked Accepted by this package. Every proposal remains `Proposed` and is a candidate for explicit human disposition. +The Human Architecture Owner and Final Approver accepted ADR-0001 through ADR-0006 with conditions on 2026-07-24. Each ADR file records the authoritative `Accepted` status and human disposition. Conditions remain mandatory future gates and are not represented as completed evidence. ## ADR-0001 — Bounded Large-Data List Strategy -- Current status: Proposed -- Candidate status: Candidate for Human Approval +- Final status: Accepted +- Human disposition: Accepted with Conditions - Evidence IDs: EVID-004, EVID-006 - Risk impact: Reduces RISK-002; RISK-011 remains open. - Security impact: Prevents uncontrolled memory/resource use; no direct secret impact. - Dependency impact: CustomTkinter remains conditional; bounded ttk/paginated views are required. - Remaining conditions: Repeatable Windows interaction, DPI, keyboard, focus, contrast and assistive-technology tests. -- AI recommendation: Recommend Accept with Conditions. -- Required human decision: Accept, revise, reject or defer. ## ADR-0002 — SQLite WAL and Bounded Writer Model -- Current status: Proposed -- Candidate status: Candidate for Human Approval +- Final status: Accepted +- Human disposition: Accepted with Conditions - Evidence IDs: EVID-007 - Risk impact: Mitigates RISK-005 and supports RISK-016 recovery objectives. - Security impact: Short transactions and controlled writers reduce integrity exposure; backup policy remains separate. -- Dependency impact: Compatible with `sqlite3`, SQLAlchemy and SQLModel persistence options. +- Dependency impact: Compatible with `sqlite3` and approved persistence-evaluation boundaries; SQLModel remains deferred. - Remaining conditions: Migration tests, writer-failure tests, representative Windows storage and production ceilings. -- AI recommendation: Recommend Accept with Conditions. -- Required human decision: Accept, revise, reject or defer. ## ADR-0003 — Hybrid Database Reservation and Reconciliation -- Current status: Proposed -- Candidate status: Candidate for Human Approval +- Final status: Accepted +- Human disposition: Accepted with Conditions - Evidence IDs: EVID-008, EVID-012 - Risk impact: Mitigates RISK-006 and RISK-010 while preserving workspace isolation. - Security impact: Keeps customer/invoice payloads out of `control.db`; credentials remain references only. - Dependency impact: Requires explicit repository and migration boundaries, independent of ORM choice. - Remaining conditions: Production crash tests, migration tests, multi-workspace stress and backup/restore validation. -- AI recommendation: Recommend Accept with Conditions. -- Required human decision: Accept, revise, reject or defer. ## ADR-0004 — Scheduler Trigger Boundary and Durable Occurrences -- Current status: Proposed -- Candidate status: Candidate for Human Approval +- Final status: Accepted +- Human disposition: Accepted with Conditions - Evidence IDs: EVID-004, EVID-005, EVID-009 - Risk impact: Reduces duplicate-run and timezone uncertainty under RISK-003 and RISK-016. - Security impact: No scheduler may bypass durable Run creation or audit controls. -- Dependency impact: APScheduler is conditional and trigger-only; `tzdata` is a conditional Windows runtime candidate. -- Remaining conditions: Repeatable packaged timezone and restart-dedup tests in the approved build pipeline. -- AI recommendation: Recommend Accept with Conditions. -- Required human decision: Accept, revise, reject or defer; decide `tzdata` separately. +- Dependency impact: APScheduler is approved conditionally and trigger-only; `tzdata` is an approved conditional Windows runtime direction. +- Remaining conditions: Repeatable packaged timezone and restart-dedup tests in the approved build pipeline; exact versions and production adoption remain future gates. ## ADR-0005 — Bounded Worker Shutdown and Unknown Outcomes -- Current status: Proposed -- Candidate status: Candidate for Human Approval +- Final status: Accepted +- Human disposition: Accepted with Conditions - Evidence IDs: EVID-004, EVID-010 - Risk impact: Mitigates RISK-010 and RISK-016. - Security impact: Prevents unsafe blind requeue after crossing the external-operation boundary. - Dependency impact: Execution backends must support cooperative shutdown and durable lease markers. - Remaining conditions: Real provider adapter, Windows shutdown-signal and restart integration tests. -- AI recommendation: Recommend Accept with Conditions. -- Required human decision: Accept, revise, reject or defer. ## ADR-0006 — Operation-Level Provider Capability Contract -- Current status: Proposed -- Candidate status: Candidate for Human Approval +- Final status: Accepted +- Human disposition: Accepted with Conditions - Evidence IDs: EVID-011, EVID-012 - Risk impact: Mitigates RISK-007, RISK-008 and RISK-010. - Security impact: Conservative failure behavior prevents unsafe retries and secret-bearing diagnostic leakage. - Dependency impact: HTTP clients and provider SDKs remain behind adapters; no provider SDK is approved here. - Remaining conditions: Provider-operation sandbox tests and periodic documentation review. -- AI recommendation: Recommend Accept with Conditions. -- Required human decision: Accept, revise, reject or defer. ## ACR disposition -Proposed ACRs: None. The candidate retains the protected architecture direction and does not weaken isolation, ownership, execution, security or reliability guarantees. +Proposed ACRs: None. Phase 0C implemented no architecture change and did not weaken isolation, ownership, execution, security or reliability guarantees. diff --git a/docs/phase-0c/BASELINE_APPROVAL_PACKET.md b/docs/phase-0c/BASELINE_APPROVAL_PACKET.md index e05f319..400b7e3 100644 --- a/docs/phase-0c/BASELINE_APPROVAL_PACKET.md +++ b/docs/phase-0c/BASELINE_APPROVAL_PACKET.md @@ -1,13 +1,17 @@ # Baseline Approval Packet -## Candidate identification +## Approved baseline identification - Product: OpenInvoice - Repository: `vibtools/OpenInvoice` - Source commit: `4cfc3cb5de400d4459cc5fd691a208abc185018f` +- Human-reviewed candidate head: `81d393c494557d7240e43bf17f8ca4ebe8b105c3` - Candidate baseline: `1.0.0-candidate.1` -- Prepared date: 2026-07-23 -- Status: Candidate — awaiting Human Architecture Owner approval +- Approved baseline: `1.0.0` +- Candidate prepared date: 2026-07-23 +- Approval date: 2026-07-24 +- Status: Approved by the Human Architecture Owner and Final Approver +- Approval record: [PHASE_0C_APPROVAL_RECORD.md](../reviews/PHASE_0C_APPROVAL_RECORD.md) ## Phase-gate history @@ -16,26 +20,29 @@ - Phase 0B.1: Remediation required. - Phase 0B.2: Not approved; remediation continued. - Phase 0B.3: Approved by the Human Architecture Owner and Final Approver. -- Phase 0C: Authorized for candidate preparation only. +- Phase 0C: Approved by the Human Architecture Owner and Final Approver. ## Evidence classification - PR #1 and source integration: Repository-verified. - Phase 0B.3 final Windows outcome: Human-attested. - Spike scripts and recorded machine results: Machine-verified where identified in the evidence inventory. +- Phase 0C local technical validation: Human-attested from recorded PowerShell execution. +- Phase 0C PR/head state: Repository-verified. - Phase 0C independent Windows rerun: Not performed and not claimed. +- GitHub Actions/status posture: no green CI claim when no workflow or status check ran. -## Architecture candidate +## Approved architecture baseline -The candidate retains Workspace → Run → Job → Attempt, hybrid `control.db` plus isolated workspace databases, workspace-scoped logical queues, a global bounded engine, provider-specific executors, global physical-account limits, immutable run snapshots, durable leases, `UNKNOWN` reconciliation, trigger-only scheduling, capability-based providers, workflow-first UI separation and OS-vault secret handling. +The baseline retains Workspace → Run → Job → Attempt, hybrid `control.db` plus isolated workspace databases, workspace-scoped logical queues, a global bounded engine, provider-specific executors, global physical-account limits, immutable run snapshots, durable leases, `UNKNOWN` reconciliation, trigger-only scheduling, capability-based providers, workflow-first UI separation and OS-vault secret handling. -## ADR recommendations +## ADR decisions -ADR-0001 through ADR-0006 are recommended for acceptance with explicit conditions. None is marked Accepted by this package. +ADR-0001 through ADR-0006 are Accepted with Conditions. Every recorded condition and future validation requirement remains mandatory. The approval does not claim those future tests have executed. -## Dependency recommendations +## Dependency decisions -Seven tools/libraries are candidates for the next engineering phase, four are conditional candidates, SQLModel is deferred, and psutil remains spike/test only. No version or lockfile is approved. +Seven tools/libraries are approved for Phase 1 evaluation or development/build scope, four are approved conditional candidates, SQLModel remains deferred and psutil remains spike/test only. No exact version, production installation or production lockfile is approved. ## Guarantees retained @@ -53,23 +60,20 @@ Standard workflow with progressive Advanced controls and separate Diagnostics; p ## Scope exclusions -The candidate does not authorize full accounting, tax filing, payment custody, banking, cloud multi-user SaaS, mobile applications, unrestricted plugins, remote administration or silent scope expansion. +The approved baseline does not authorize full accounting, tax filing, payment custody, banking, cloud multi-user SaaS, mobile applications, unrestricted plugins, remote administration or silent scope expansion. ## Remaining risks and evidence limitations Trademark risk remains open. Packaging and credential evidence is human-attested rather than independently rerun in Phase 0C. Accessibility, provider sandboxes, numerical performance targets, backup policy and repeatable build/release gates remain open. -## Human decisions required +## Separate authorizations and restrictions -1. Disposition ADR-0001 through ADR-0006. -2. Disposition all dependency candidates. -3. Confirm Version 1 providers, fields, report formats, account-sharing policy, backup policy and accessibility targets. -4. Approve, revise or reject baseline `1.0.0-candidate.1`. -5. Separately authorize `baseline-v1.0.0` and Phase 1. +- Authorized future tag after reviewed merge: `baseline-v1.0.0`. +- Authorized next phase after repository finalization: Phase 1 — Repository Governance and CI Foundation. +- Production feature code: Not authorized. +- Production lockfile: Not authorized. +- Direct push to `main`: Not authorized. +- Architecture change implemented: No. +- ACR required: No. -## Proposed tag and next phase - -- Proposed tag after separate approval: `baseline-v1.0.0` -- Proposed next phase after separate approval: Phase 1 — Repository Governance and CI Foundation - -Neither action is authorized by applying or merging this package. +Applying this patch records the human decision. It does not itself merge PR #3 or create the authorized tag. diff --git a/docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md b/docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md index 8560b7f..1a0c89b 100644 --- a/docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md +++ b/docs/phase-0c/DEPENDENCY_DISPOSITION_REGISTER.md @@ -1,21 +1,21 @@ # Dependency Disposition Register -Spike installation is evidence only. It is not production approval. Exact versions and lockfiles belong to the approved build-foundation phase. +The Human Architecture Owner and Final Approver dispositioned all 13 dependency directions on 2026-07-24. Spike installation remains evidence only. Exact versions, production adoption, installation and lockfiles require later controlled gates. -| Dependency | Purpose | Architecture boundary | License record | Evidence | Proposed disposition | Security concerns | Packaging concerns | Upgrade policy | Replacement strategy | Human decision required | +| Dependency | Purpose | Architecture boundary | License record | Evidence | Human-approved disposition | Security concerns | Packaging concerns | Upgrade policy | Replacement strategy | Approval constraints | |---|---|---|---|---|---|---|---|---|---|---| -| CustomTkinter | Desktop presentation shell | UI only | MIT | EVID-004, EVID-006 | Conditional candidate | Accessibility and UI-thread discipline | Validate Tcl/Tk assets in `onedir` | Pin after Phase 1 evaluation; manual reviewed upgrades | Standard Tk/ttk or another approved shell | Approve, defer or reject | -| PyInstaller | Windows packaging | Build/release tooling | GPL-2.0-or-later with bootloader exception | EVID-004, EVID-005 | Candidate for next phase | Build provenance and artifact scanning | `onedir`, unique build roots, packaged probes | Pin in build foundation; upgrade only with smoke tests | Another approved Windows packager | Approve, defer or reject | -| keyring | OS credential-vault adapter | Infrastructure credentials | MIT | EVID-004 | Conditional candidate | Must fail closed; no plaintext fallback | Source and packaged backend tests | Pin after secure-backend validation | Direct approved Windows-vault adapter | Approve, defer or reject | -| tzdata | IANA timezone data on Windows | Runtime infrastructure | Apache-2.0 | EVID-009 | Conditional candidate | Supply-chain and update review | Verify bundled `UTC` and user IANA zones | Reviewed periodic update with DST tests | Approved bundled timezone dataset | Approve, defer or reject | -| pytest | Test runner | Development/test only | MIT | Documentation-derived | Candidate for next phase | Test plugins require review | Not shipped as runtime dependency | Pin in development group | `unittest` | Approve, defer or reject | -| Ruff | Lint and formatting | Development/CI only | MIT | Documentation-derived | Candidate for next phase | Unsafe fixes must not run automatically | Not shipped at runtime | Pin configuration and version in Phase 1 | Separate approved lint/format tools | Approve, defer or reject | -| uv | Environment and lock management | Build/CI tooling | Apache-2.0 OR MIT | Documentation-derived | Candidate for next phase | Lockfile and index policy required | Reproducible Windows sync required | Frozen lock workflow after approval | `pip`/`venv` plus approved lock tool | Approve, defer or reject | -| SQLAlchemy | Persistence mapping and transactions | Infrastructure persistence only | MIT | EVID-007, EVID-008 | Candidate for next phase | Queries must preserve workspace scope | Normal Python packaging | Pin after persistence walking skeleton | Standard-library `sqlite3` repositories | Approve evaluation, defer or reject | -| SQLModel | Optional persistence model convenience | Infrastructure persistence only; never domain | MIT | Documentation-derived | Deferred | Risk of coupling domain to ORM | Normal Python packaging | Reconsider only after SQLAlchemy baseline | SQLAlchemy mappings plus domain dataclasses | Confirm defer or authorize evaluation | -| Alembic | Schema migration | Infrastructure migration tooling | MIT | Documentation-derived | Candidate for next phase | Migration integrity and downgrade policy | Not a runtime UI concern | Pin with SQLAlchemy compatibility tests | Approved custom migration runner only by ADR | Approve evaluation, defer or reject | -| APScheduler | Schedule trigger adapter | Infrastructure scheduler; trigger-only | MIT | EVID-009 | Conditional candidate | Must not become durable job engine | Packaged restart and timezone tests | Pin after trigger-boundary prototype | Application-owned timer adapter | Approve boundary, defer or reject | -| HTTPX | Provider HTTP transport | Provider/infrastructure adapters only | BSD-3-Clause | EVID-011 | Candidate for next phase | TLS, timeout, proxy and redaction policy | Normal Python packaging | Pin after provider transport tests | Standard library or another approved client | Approve evaluation, defer or reject | -| psutil | Spike measurement/process diagnostics | Spike/test only | BSD-3-Clause | EVID-005 | Spike/test only | Avoid unnecessary production process inspection | Exclude from runtime unless justified | No production upgrade policy | Standard-library/platform probes | Confirm spike-only | +| CustomTkinter | Desktop presentation shell | UI only | MIT | EVID-004, EVID-006 | Approved conditional candidate | Accessibility and UI-thread discipline | Validate Tcl/Tk assets in `onedir` | Pin only after Phase 1 evaluation; manually reviewed upgrades | Standard Tk/ttk or another approved shell | No production adoption until bounded-view and accessibility gates pass | +| PyInstaller | Windows packaging | Build/release tooling | GPL-2.0-or-later with bootloader exception | EVID-004, EVID-005 | Approved for Phase 1 evaluation | Build provenance and artifact scanning | `onedir`, unique build roots, packaged probes | Pin only through the build-foundation gate; upgrade with smoke tests | Another approved Windows packager | Tool direction only; no version approved | +| keyring | OS credential-vault adapter | Infrastructure credentials | MIT | EVID-004 | Approved conditional candidate | Must fail closed; no plaintext fallback | Source and packaged backend tests | Pin only after secure-backend validation | Direct approved Windows-vault adapter | No production adoption until fail-closed packaged validation passes | +| tzdata | IANA timezone data on Windows | Runtime infrastructure | Apache-2.0 | EVID-009 | Approved conditional candidate | Supply-chain and update review | Verify bundled `UTC` and user IANA zones | Reviewed periodic update with DST tests | Approved bundled timezone dataset | Direction approved; exact version and production adoption remain gated | +| pytest | Test runner | Development/test only | MIT | Documentation-derived | Approved for development/test | Test plugins require review | Not shipped as runtime dependency | Pin in a future approved development group | `unittest` | Development/test scope only; no runtime import | +| Ruff | Lint and formatting | Development/CI only | MIT | Documentation-derived | Approved for development/CI | Unsafe fixes must not run automatically | Not shipped at runtime | Pin configuration/version through Phase 1 review | Separate approved lint/format tools | Development/CI scope only | +| uv | Environment and lock management | Build/CI tooling | Apache-2.0 OR MIT | Documentation-derived | Approved for Phase 1 build/CI evaluation | Lockfile and index policy required | Reproducible Windows sync required | Frozen lock workflow only after explicit approval | `pip`/`venv` plus approved lock tool | Evaluation approved; production lockfile remains prohibited | +| SQLAlchemy | Persistence mapping and transactions | Infrastructure persistence only | MIT | EVID-007, EVID-008 | Approved for evaluation | Queries must preserve workspace scope | Normal Python packaging | Pin only after persistence walking skeleton | Standard-library `sqlite3` repositories | Evaluation only; never the domain model | +| SQLModel | Optional persistence model convenience | Infrastructure persistence only; never domain | MIT | Documentation-derived | Deferred | Risk of coupling domain to ORM | Normal Python packaging | Reconsider only after SQLAlchemy baseline | SQLAlchemy mappings plus domain dataclasses | No evaluation or adoption authorized in Phase 1 without a new decision | +| Alembic | Schema migration | Infrastructure migration tooling | MIT | Documentation-derived | Approved for evaluation | Migration integrity and downgrade policy | Not a runtime UI concern | Pin with SQLAlchemy compatibility tests after approval | Approved custom migration runner only by ADR | Evaluation only; no production migration baseline yet | +| APScheduler | Schedule trigger adapter | Infrastructure scheduler; trigger-only | MIT | EVID-009 | Approved conditional trigger-only candidate | Must not become durable job engine | Packaged restart and timezone tests | Pin only after trigger-boundary prototype | Application-owned timer adapter | Trigger-only boundary is mandatory; no durable job ownership | +| HTTPX | Provider HTTP transport | Provider/infrastructure adapters only | BSD-3-Clause | EVID-011 | Approved for evaluation | TLS, timeout, proxy and redaction policy | Normal Python packaging | Pin only after provider transport tests | Standard library or another approved client | Evaluation behind adapters only; no provider SDK approved | +| psutil | Spike measurement/process diagnostics | Spike/test only | BSD-3-Clause | EVID-005 | Confirmed spike/test only | Avoid unnecessary production process inspection | Exclude from runtime unless justified | No production upgrade policy | Standard-library/platform probes | Runtime use requires a future explicit decision | -No dependency is installed, locked or imported into production code by Phase 0C. +No exact dependency version is approved, and no dependency is installed, locked or imported into production code by Phase 0C. diff --git a/docs/phase-0c/OPEN_DECISIONS.md b/docs/phase-0c/OPEN_DECISIONS.md index 4e310df..ef04b14 100644 --- a/docs/phase-0c/OPEN_DECISIONS.md +++ b/docs/phase-0c/OPEN_DECISIONS.md @@ -1,14 +1,23 @@ # Open Decisions -Human decisions required before controlled-baseline approval: - -1. Accept, revise, reject or defer ADR-0001 through ADR-0006. -2. Approve, defer or reject each dependency disposition, including Windows `onedir`, `keyring`, `tzdata`, SQLAlchemy/Alembic, APScheduler and HTTPX directions. -3. Confirm that SQLModel remains deferred or authorize a later evaluation. -4. Confirm Version 1 providers, mandatory customer/invoice fields, report formats and physical-account sharing policy. -5. Define supported Windows/Python versions and repeatable packaging matrix. -6. Define measurable large-data, accessibility and recovery targets. -7. Define backup/export encryption, retention and restore policy. -8. Resolve the OpenInvoice product-name/trademark risk before public branding or release. -9. Approve, revise or reject baseline `1.0.0-candidate.1`. -10. Separately authorize or reject `baseline-v1.0.0` and Phase 1. +## Resolved by Phase 0C human approval + +1. ADR-0001 through ADR-0006: Accepted with Conditions. +2. All 13 dependency directions: dispositioned in the Dependency Disposition Register. +3. SQLModel: Deferred. +4. Baseline `1.0.0-candidate.1`: Approved as baseline `1.0.0`. +5. `baseline-v1.0.0`: Authorized for creation after reviewed merge. +6. Phase 1 — Repository Governance and CI Foundation: Authorized after baseline merge/tag finalization. +7. Production feature code and production lockfile: Not authorized. + +## Remaining open decisions + +1. Confirm Version 1 providers, mandatory customer/invoice fields, report formats and physical-account sharing policy. +2. Define supported Windows/Python versions and a repeatable packaging matrix. +3. Define measurable large-data, accessibility and recovery targets. +4. Define backup/export encryption, retention and restore policy. +5. Complete provider-operation sandbox policies and validation targets. +6. Resolve the OpenInvoice product-name/trademark risk before public branding or release. +7. Approve exact dependency versions and any future lockfile through the Phase 1 controlled build/dependency gate. + +Phase 0C approval does not silently resolve these remaining decisions or represent their evidence as complete. diff --git a/docs/phase-0c/README.md b/docs/phase-0c/README.md index 0bbda96..bb714d0 100644 --- a/docs/phase-0c/README.md +++ b/docs/phase-0c/README.md @@ -1,10 +1,10 @@ -# Phase 0C — Controlled Baseline Candidate +# Phase 0C — Controlled Baseline Approval ## Purpose -This directory contains the review packet for OpenInvoice baseline `1.0.0-candidate.1`, prepared from repository commit `4cfc3cb5de400d4459cc5fd691a208abc185018f`. +This directory contains the review and approval records for OpenInvoice baseline `1.0.0`, approved from candidate `1.0.0-candidate.1` after technical validation of candidate head `81d393c494557d7240e43bf17f8ca4ebe8b105c3`. -Phase 0C reconciles governance and evidence. It does not approve the baseline, accept ADRs, create a tag, authorize Phase 1, install production dependencies, or begin production implementation. +Phase 0C reconciles governance and evidence, records six ADR decisions, dispositions all 13 dependency directions, approves the controlled baseline, authorizes the future baseline tag and authorizes Phase 1 repository-governance/CI foundation work. It does not install dependencies, create a lockfile or begin production feature implementation. ## Evidence taxonomy @@ -18,10 +18,11 @@ Only these classifications are used: - Unverified - Not applicable -The Phase 0B.3 merge is repository-verified. The final Windows validation is human-attested. Phase 0C does not claim an independent Windows rerun where raw evidence is unavailable. +The Phase 0B.3 merge is repository-verified. The final Windows validation and Phase 0C local command execution are human-attested. Phase 0C does not claim an independent Windows rerun where raw evidence is unavailable, and it does not claim green CI when no GitHub Actions workflow or status check ran. -## Review documents +## Review and approval documents +- [Phase 0C Approval Record](../reviews/PHASE_0C_APPROVAL_RECORD.md) - [Baseline Approval Packet](BASELINE_APPROVAL_PACKET.md) - [Evidence Inventory](EVIDENCE_INVENTORY.md) - [ADR Disposition Register](ADR_DISPOSITION_REGISTER.md) @@ -32,10 +33,14 @@ The Phase 0B.3 merge is repository-verified. The final Windows validation is hum - [Phase 0C Review Checklist](../reviews/PHASE_0C_REVIEW_CHECKLIST.md) - [Phase 0B.3 Approval Record](../reviews/PHASE_0B3_APPROVAL_RECORD.md) -## Candidate status +## Approval status -- Candidate version: `1.0.0-candidate.1` -- Baseline status: Candidate — awaiting Human Architecture Owner approval -- Baseline tag authorized: No +- Approved baseline: `1.0.0` +- Approved from candidate: `1.0.0-candidate.1` +- Approval date: 2026-07-24 +- Architecture change implemented: No +- ACR required: No +- `baseline-v1.0.0` authorized: Yes; not yet created +- Phase 1 authorized: Yes; activation pending merge/tag finalization - Production code authorized: No -- Phase 1 authorized: No +- Production lockfile authorized: No diff --git a/docs/reviews/PHASE_0C_APPROVAL_RECORD.md b/docs/reviews/PHASE_0C_APPROVAL_RECORD.md new file mode 100644 index 0000000..518954e --- /dev/null +++ b/docs/reviews/PHASE_0C_APPROVAL_RECORD.md @@ -0,0 +1,87 @@ +# Phase 0C Approval Record + +## Decision identity + +| Field | Value | +|---|---| +| Project | OpenInvoice | +| Repository | `vibtools/OpenInvoice` | +| Draft PR | `#3` | +| Base branch | `main` | +| Base SHA | `4cfc3cb5de400d4459cc5fd691a208abc185018f` | +| Human-reviewed candidate head | `81d393c494557d7240e43bf17f8ca4ebe8b105c3` | +| Candidate | `1.0.0-candidate.1` | +| Approved baseline | `1.0.0` | +| Decision date | 2026-07-24 | +| Decision authority | Human Architecture Owner and Final Approver | + +## Evidence posture at decision time + +- Candidate/audit/hygiene branch was synchronized locally and remotely at the reviewed head. +- Working tree, tracked-generated-artifact scan and prohibited working-tree artifact scan passed through recorded PowerShell execution. +- YAML parsing and all candidate safeguards passed. +- Six ADR files remained Proposed before the human decision; none was silently accepted. +- Markdown relative-link validation and `git diff --check` passed before the decision. +- PR #3 was repository-verified as open, Draft, unmerged and mergeable at the reviewed head. +- No GitHub Actions workflow run or combined status check was reported for the reviewed head; no green-CI claim is made. +- Phase 0B.3 Windows execution remains human-attested; Phase 0C did not independently rerun it. + +## Architecture decisions + +| ADR | Decision | +|---|---| +| ADR-0001 — Bounded Large-Data List Strategy | Accepted with Conditions | +| ADR-0002 — SQLite WAL and Bounded Writer Model | Accepted with Conditions | +| ADR-0003 — Hybrid Database Reservation and Reconciliation | Accepted with Conditions | +| ADR-0004 — Scheduler Trigger Boundary and Durable Occurrences | Accepted with Conditions | +| ADR-0005 — Bounded Worker Shutdown and Unknown Outcomes | Accepted with Conditions | +| ADR-0006 — Operation-Level Provider Capability Contract | Accepted with Conditions | + +All conditions and future validation requirements recorded in the ADRs remain mandatory. Acceptance does not claim those future tests have passed. + +## Dependency decisions + +| Dependency | Decision | +|---|---| +| CustomTkinter | Approved as Conditional Candidate | +| PyInstaller | Approved for Phase 1 Evaluation | +| keyring | Approved as Conditional Candidate | +| tzdata | Approved as Conditional Candidate | +| pytest | Approved for Development/Test | +| Ruff | Approved for Development/CI | +| uv | Approved for Phase 1 Build/CI Evaluation | +| SQLAlchemy | Approved for Evaluation | +| SQLModel | Deferred | +| Alembic | Approved for Evaluation | +| APScheduler | Approved as Conditional Trigger-Only Candidate | +| HTTPX | Approved for Evaluation | +| psutil | Confirmed Spike/Test Only | + +These decisions approve directions and boundaries only. No exact dependency version, production installation, production import or production lockfile is approved. + +## Baseline and phase decisions + +- Baseline `1.0.0-candidate.1`: Approved as controlled baseline `1.0.0`. +- `baseline-v1.0.0`: Authorized for creation only after PR #3 is finally verified and merged into `main`. +- Phase 1 — Repository Governance and CI Foundation: Authorized after baseline merge/tag finalization. +- Production feature code: Not authorized. +- Production lockfile: Not authorized. +- Direct push to `main`: Not authorized. + +## Architecture-change determination + +- Architecture change implemented during Phase 0C: No. +- ACR required: No. +- Proposed ACRs: None. + +## Remaining actions + +1. Apply and validate the Phase 0C Final Approval Patch. +2. Commit and push the approval record to the existing review branch. +3. Reverify PR #3 at the resulting head and preserve the no-false-green CI posture. +4. Mark the PR ready for review only after final verification. +5. Merge through the reviewed workflow. +6. Create and verify `baseline-v1.0.0` from the merged `main` commit. +7. Begin Phase 1 only after those finalization actions complete. + +The human decision is authoritative. AI prepared the record but did not approve the baseline, ADRs, dependencies, tag or phase. diff --git a/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md b/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md index cd3ff6b..0e70104 100644 --- a/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md +++ b/docs/reviews/PHASE_0C_REVIEW_CHECKLIST.md @@ -2,46 +2,58 @@ ## Repository and source -- [ ] Confirm repository `vibtools/OpenInvoice`. -- [ ] Confirm source commit `4cfc3cb5de400d4459cc5fd691a208abc185018f` or a documented descendant with unchanged target files. -- [ ] Confirm Draft PR #3 remains based on `main` and contains only Phase 0C candidate/audit changes. -- [ ] Confirm PR #1 merge and Phase 0B.3 approval record. -- [ ] Confirm the local working tree was clean before package application. +- [x] Confirm repository `vibtools/OpenInvoice`. +- [x] Confirm source commit `4cfc3cb5de400d4459cc5fd691a208abc185018f` and candidate head `81d393c494557d7240e43bf17f8ca4ebe8b105c3`. +- [x] Confirm Draft PR #3 remains based on `main` and contains only Phase 0C candidate/audit/hygiene changes. +- [x] Confirm PR #1 merge and Phase 0B.3 approval record. +- [x] Confirm the local working tree was clean before final technical validation. ## Evidence -- [ ] Review EVID-001 through EVID-013. -- [ ] Accept the distinction among machine-verified, repository-verified, human-attested, documentation-derived, partially reproducible, unverified and not applicable evidence. -- [ ] Confirm traceability evidence columns use stable `EVID-*` references rather than classification text. -- [ ] Confirm no independent Windows rerun is claimed without raw evidence. +- [x] Review EVID-001 through EVID-013. +- [x] Accept the distinction among machine-verified, repository-verified, human-attested, documentation-derived, partially reproducible, unverified and not applicable evidence. +- [x] Confirm traceability evidence columns use stable `EVID-*` references rather than classification text. +- [x] Confirm no independent Windows rerun is claimed without raw evidence. ## Architecture and requirements -- [ ] Disposition ADR-0001 through ADR-0006. -- [ ] Confirm all requirement statuses are Approved, Proposed, Deferred or Rejected. -- [ ] Confirm ADR-0004 is limited to scheduler/timezone/durable-occurrence semantics and is not treated as the general packaging ADR. -- [ ] Confirm no architecture invariant or constitutional rule was silently removed. -- [ ] Confirm proposed ACRs: None. +- [x] Disposition ADR-0001 through ADR-0006: Accepted with Conditions. +- [x] Confirm all requirement statuses remain Approved, Proposed, Deferred or Rejected. +- [x] Confirm ADR-0004 is limited to scheduler/timezone/durable-occurrence semantics and is not treated as the general packaging ADR. +- [x] Confirm no architecture invariant or constitutional rule was silently removed. +- [x] Confirm proposed ACRs: None. ## Dependencies, security and operations -- [ ] Review all 13 dependency dispositions. -- [ ] Confirm no version, production installation or lockfile is approved. -- [ ] Review vault, redaction, plugin, diagnostics, UNKNOWN and backup directions. +- [x] Review and disposition all 13 dependency directions. +- [x] Confirm no exact version, production installation or production lockfile is approved. +- [x] Review vault, redaction, plugin, diagnostics, `UNKNOWN` and backup directions. -## PR validation +## PR and local validation -- [ ] Record the current PR head SHA. -- [ ] Record combined status checks and GitHub Actions runs. -- [ ] Do not claim a green CI gate when no checks or workflows ran. -- [ ] Keep the PR in Draft until audit corrections and human baseline decisions are complete. -- [ ] Confirm `git diff --check`, YAML parsing, Markdown-link validation and prohibited-artifact checks were executed locally or explicitly recorded as unavailable. +- [x] Record the human-reviewed PR head SHA: `81d393c494557d7240e43bf17f8ca4ebe8b105c3`. +- [x] Record combined status checks and GitHub Actions runs: none reported for that head. +- [x] Do not claim a green CI gate when no checks or workflows ran. +- [x] Keep PR #3 in Draft through candidate audit and human decision capture. +- [x] Confirm `git diff --check`, YAML parsing, Markdown-link validation, prohibited-artifact checks, tracked-artifact checks and local/remote synchronization passed through recorded local execution. -## Final gate +## Human final gate -- [ ] Approve, revise or reject `1.0.0-candidate.1`. -- [ ] Record ADR and dependency decisions through a separate controlled action. -- [ ] Decide whether to authorize `baseline-v1.0.0`. -- [ ] Decide whether to authorize Phase 1. +- [x] Approve baseline `1.0.0-candidate.1` as controlled baseline `1.0.0`. +- [x] Record ADR and dependency decisions through this controlled approval action. +- [x] Authorize `baseline-v1.0.0` after reviewed merge. +- [x] Authorize Phase 1 after baseline merge/tag finalization. +- [x] Keep production feature code unauthorized. +- [x] Keep production lockfile unauthorized. +- [x] Confirm architecture change implemented: No. +- [x] Confirm ACR required: No. -Applying, committing or merging this candidate does not itself approve any final-gate item. +## Repository finalization still required + +- [ ] Apply, validate, commit and push the Phase 0C Final Approval Patch. +- [ ] Reverify PR #3 at the resulting approval-record head. +- [ ] Mark PR #3 ready for review after final verification. +- [ ] Merge PR #3 through the reviewed workflow. +- [ ] Create and verify `baseline-v1.0.0` from the merged `main` commit. + +Applying or committing this patch records the approved decisions. It does not itself merge the PR or create the tag.