diff --git a/README.md b/README.md index 3bb0864..39a0358 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,11 @@ Auditable public carbon emission factor ingestion and validation for climate-tech data infrastructure. -![Status](https://img.shields.io/badge/status-documentation%20baseline-2f6f88) +![Status](https://img.shields.io/badge/status-narrow%20production--ready-2f6f88) ![Phase](https://img.shields.io/badge/phase-Phase%201%20ingestion-4f7cac) -![Python](https://img.shields.io/badge/Python-Phase%201-3776ab) -![.NET](https://img.shields.io/badge/.NET-contracts-512bd4) -![PostgreSQL](https://img.shields.io/badge/PostgreSQL-Phase%201-336791) -![Docs](https://img.shields.io/badge/docs-in%20progress-5c7cfa) +![Python](https://img.shields.io/badge/Python-operator%20path-3776ab) +![.NET](https://img.shields.io/badge/.NET-parity%20evidence-512bd4) +![PostgreSQL](https://img.shields.io/badge/PostgreSQL-source--specific%20persistence-336791) ![Release](https://img.shields.io/badge/release-not%20published%20yet-lightgrey) [![Release validation](https://github.com/ktalpay/CarbonOps-Parser/actions/workflows/release-validation.yml/badge.svg)](https://github.com/ktalpay/CarbonOps-Parser/actions/workflows/release-validation.yml) ![Package](https://img.shields.io/badge/package-not%20published%20yet-lightgrey) @@ -26,6 +25,9 @@ The project is independent from `carbonops-assistant`. It is not a continuation, - [Production parity contract](docs/production-parity-contract.md) - Python production path and .NET parity evidence. - [Python runtime docs](docs/python-ingestion-local-runbook.md) - local Docker PostgreSQL ingestion runbook for the packaged Python path. - [.NET runtime docs](src/dotnet/README.md) - .NET Worker Service path and parity-oriented runtime notes. +- [Database model](docs/database-model.md) and [PostgreSQL startup](docs/database-startup.md) - shared metadata plus source-specific table groups. +- [Documentation index](docs/index.md) - curated documentation map for operators, contributors, and reviewers. +- [Maintainer release/sync checklist](docs/maintainer-release-checklist.md) - develop-to-main, stale PR/issue cleanup, and first alpha/review readiness. - [Contribution guide](CONTRIBUTING.md) - issues, features, forks, branches, pull requests, validation, secrets, artifacts, and maintainer-only merge policy. - [Issue templates](.github/ISSUE_TEMPLATE) - bug reports, feature requests, documentation requests, and production-readiness questions. - [Pull request guide](.github/pull_request_template.md) - PR checklist for scope, validation, runtime impact, PostgreSQL impact, docs, secrets, artifacts, and production-ready claims. @@ -36,7 +38,17 @@ Public carbon emissions workflows often depend on emission factor spreadsheets, ## Current Status -CarbonOps-Parser is in Phase 1. The repository contains Python implementation slices, .NET parity slices, PostgreSQL schema/runtime boundaries, deterministic examples, local dry-run validation, and a documented Python operator path. It is project-level production-ready only in the narrow scope documented in [Final Project Production-Ready Verdict](docs/final-project-production-ready-verdict.md). It is not a published package release. +CarbonOps-Parser is in Phase 1 and has a narrow project-level production-ready status for the documented operator path. The repository contains an active Python ingestion runtime, .NET parity evidence, PostgreSQL schema/runtime boundaries, deterministic examples, local dry-run validation, and production operator documentation. The production-ready claim applies only to the scope documented in [Final Project Production-Ready Verdict](docs/final-project-production-ready-verdict.md) and [Production Parity Contract](docs/production-parity-contract.md). It is not a published package release. + +### Explicit Non-Claims + +CarbonOps-Parser does not claim to be: + +- A production carbon-accounting calculator or emissions reporting engine. +- Legal, compliance, audit, or regulatory advice. +- A source-owner correctness guarantee for GHG Protocol, DEFRA/DESNZ, IPCC EFDB, or any source document. +- A universal carbon factor model across all source families. +- A published package, unless release/package files and repository releases prove otherwise. | Area | Phase 1 completed capabilities | Phase 2 roadmap | | --- | --- | --- | @@ -420,7 +432,7 @@ Each Phase 1 source family will have its own schedule, source version/hash check | Source family | Phase 1 role | Table group | | --- | --- | --- | | GHG Protocol | Source-specific parser and workbook/tool mapping | `ghg_*` | -| DEFRA/DESNZ | First planned ingestion slice after discovery | `defra_*` | +| DEFRA/DESNZ | Active checked-in fixture and source-specific ingestion slice | `defra_*` | | IPCC EFDB | Heterogeneous source discovery and parser mapping | `ipcc_*` | See [docs/source-support.md](docs/source-support.md) and [docs/source-discovery.md](docs/source-discovery.md). @@ -468,6 +480,7 @@ ingestion instead of claiming one universal carbon accounting factor model. - [Codex-Assisted Runs](docs/codex-runs/README.md) - [Engineering Standards](docs/engineering-standards.md) - [Production Packaging And Operator Runbook](docs/production-packaging-operator-runbook.md) +- [Maintainer Release/Sync Checklist](docs/maintainer-release-checklist.md) - [Production Parity Contract](docs/production-parity-contract.md) - [Final Project Production-Ready Verdict](docs/final-project-production-ready-verdict.md) - [Legacy Linux Service Planning - not supported production scheduling](docs/linux-service-setup.md) diff --git a/docs/engineering-standards.md b/docs/engineering-standards.md index 7c431d3..429efa7 100644 --- a/docs/engineering-standards.md +++ b/docs/engineering-standards.md @@ -32,7 +32,7 @@ Phase 1 should remain focused on scheduled source ingestion, raw file archiving, Changes should be small enough to review in one pass. -Each change should have a clear purpose, such as documentation baseline work, schema documentation, source discovery, parser mapping, validation behavior, or implementation-specific service wiring. +Each change should have a clear purpose, such as repository documentation, schema documentation, source discovery, parser mapping, validation behavior, or implementation-specific service wiring. Contributors should avoid combining unrelated work in one change. Documentation updates, schema changes, parser behavior, and service runtime changes should be split when practical. diff --git a/docs/index.md b/docs/index.md index ebfd0f9..a04bae1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,18 +4,39 @@ CarbonOps-Parser is a public climate-tech data infrastructure project for audita ## Start Here -- [README](../README.md) - project positioning, safe quickstart, supported sources, status, and roadmap summary. -- [Examples](../examples/README.md) - deterministic local examples and fixture entry points. -- [Architecture](architecture.md) - Python, .NET, PostgreSQL, validation, diagnostics, and dry-run boundaries. +- [README](../README.md) - project positioning, safe quickstart, supported source families, status, and roadmap summary. - [Final Project Production-Ready Verdict](final-project-production-ready-verdict.md) - narrow project-level production-ready verdict and explicit non-claims. -- [Production Packaging And Operator Runbook](production-packaging-operator-runbook.md) - supported Python operator path, PostgreSQL readiness, cron scheduling, verification, and troubleshooting. -- [PostgreSQL Runtime Readiness Checklist](postgresql-runtime-readiness-checklist.md) - database readiness checks for the supported PostgreSQL boundary. - [Production Parity Contract](production-parity-contract.md) - Python production path and .NET parity evidence. -- [Contribution Guide](../CONTRIBUTING.md) - issues, features, forks, branches, pull requests, validation, secrets, artifacts, and maintainer-only merge policy. -- [Python Runtime Docs](python-ingestion-local-runbook.md) - local Docker PostgreSQL ingestion runbook for the packaged Python path. +- [Production Packaging And Operator Runbook](production-packaging-operator-runbook.md) - supported Python operator path, PostgreSQL readiness, cron scheduling, verification, and troubleshooting. + +## Runtime Runbooks + +- [Python Ingestion Local Runbook](python-ingestion-local-runbook.md) - local Docker PostgreSQL ingestion runbook for the packaged Python path. - [.NET Runtime Docs](../src/dotnet/README.md) - .NET Worker Service path and parity-oriented runtime notes. +- [Architecture](architecture.md) - Python, .NET, PostgreSQL, validation, diagnostics, and dry-run boundaries. +- [Examples](../examples/README.md) - deterministic local examples and fixture entry points. + +## Database Model And PostgreSQL Startup + +- [Database Model](database-model.md) - shared ingestion metadata and source-specific table groups for GHG Protocol, DEFRA/DESNZ, and IPCC EFDB. +- [Database Startup](database-startup.md) - PostgreSQL startup expectations and local database notes. +- [PostgreSQL Runtime Readiness Checklist](postgresql-runtime-readiness-checklist.md) - database readiness checks for the supported PostgreSQL boundary. +- [PostgreSQL Phase 1 Schema Contract](postgresql-phase1-schema-contract.md) - Phase 1 schema contract details. + +## Phase 2 Roadmap And Review Gate + - [Phase 2 Roadmap And Execution Boundary](phase2-roadmap.md) - next-stage roadmap and safety gates. +- [Phase 2 Runtime And Source Expansion Review Gate](phase2-review-gate.md) - review gate before runtime or source-family expansion. - [Release Notes Draft](release-notes-draft.md) - draft notes for a first public alpha/review release. +- [Maintainer Release And Sync Checklist](maintainer-release-checklist.md) - develop-to-main alignment, stale PR/issue cleanup, and alpha/review tag readiness. + +## Contribution, Support, And Security + +- [Contribution Guide](../CONTRIBUTING.md) - issues, features, forks, branches, pull requests, validation, secrets, artifacts, and maintainer-only merge policy. +- [Support Policy](../SUPPORT.md) - support boundaries and safe information-sharing guidance. +- [Security Policy](../SECURITY.md) - responsible disclosure and no-secret expectations. +- [Issue Templates](../.github/ISSUE_TEMPLATE) - bug reports, feature requests, documentation requests, and production-readiness questions. +- [Pull Request Template](../.github/pull_request_template.md) - PR checklist for scope, validation, runtime impact, PostgreSQL impact, docs, secrets, artifacts, and production-ready claims. ## Public Discoverability diff --git a/docs/ingestion-metadata-model.md b/docs/ingestion-metadata-model.md index 2ff3834..fc12ba1 100644 --- a/docs/ingestion-metadata-model.md +++ b/docs/ingestion-metadata-model.md @@ -138,9 +138,9 @@ The intended architecture is shared ingestion metadata plus source-specific stor ## Python And .NET Implementation Expectations -Python is expected to implement the first ingestion metadata behavior because it is planned first for source discovery, file handling, and parser experimentation. +Python implements the first ingestion metadata behavior because it is the active runtime path for source discovery, file handling, parser experimentation, and the current operator-run ingestion workflow. -The .NET implementation should aim for conceptual parity later. It should use language-appropriate structure while preserving the same metadata concepts and source traceability expectations. +The .NET implementation should preserve conceptual parity within the reviewed scope and track future parity changes through explicit review tasks. It should use language-appropriate structure while preserving the same metadata concepts and source traceability expectations. The two implementation paths should remain independent and should not share runtime code. diff --git a/docs/limitations.md b/docs/limitations.md index 31954f3..40f18e2 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -19,10 +19,10 @@ CarbonOps-Parser does not: Phase 1 is limited to: - PostgreSQL as the implemented database provider. -- GHG Protocol, DEFRA/DESNZ, and IPCC EFDB as the planned source families. +- GHG Protocol, DEFRA/DESNZ, and IPCC EFDB as the supported Phase 1 source families. - Shared ingestion metadata tables. - Source-specific master/detail tables. -- Documentation, schema, discovery, and early ingestion slices. +- Documentation, schema, discovery, operator-run ingestion, and bounded source-family ingestion slices. The conceptual configuration model includes `mysql` and `mssql`, but those providers are not implemented in Phase 1. diff --git a/docs/maintainer-release-checklist.md b/docs/maintainer-release-checklist.md new file mode 100644 index 0000000..bd0a41e --- /dev/null +++ b/docs/maintainer-release-checklist.md @@ -0,0 +1,35 @@ +# Maintainer Release And Sync Checklist + +This checklist is for maintainers preparing CarbonOps-Parser branch synchronization, public repository cleanup, or a first alpha/review tag. It does not authorize automatic release creation, issue closure, or branch merges. + +## Branch State + +- Verify `develop` contains the current accepted project state for the Python operator path, PostgreSQL-backed source-specific persistence, supported Phase 1 source families, and .NET parity evidence. +- Confirm the working tree is clean before any branch sync, release tag, or public handoff. +- Merge or sync `develop` to `main` only after review approval and repository state confirmation. +- Confirm the README on the default branch no longer contains stale baseline-status wording that contradicts the accepted project state. + +## Pull Requests And Issues + +- Review open pull requests for stale duplicates, especially duplicate documentation polish or baseline-cleanup PRs that are superseded by the accepted branch state. +- Close or supersede stale duplicate PRs only after confirming their useful changes are already represented or intentionally rejected. +- Review open issues whose GitHub state and labels disagree, such as issues that remain open while carrying a `status:merged` label. +- Update issue labels or close issues only through the normal maintainer workflow; do not use this checklist as automatic closure authority. + +## Release Readiness + +- Create a first alpha/review tag only after branch state, duplicate PRs, issue labels, README status, and validation evidence are clean. +- Confirm release notes describe the narrow project-level production-ready scope without expanding into carbon-accounting, legal, compliance, source-owner, or package-publication claims. +- Confirm package publication status is accurate before mentioning any install channel beyond repository-local or editable installs. +- Confirm release validation references exact commands and does not rely on private infrastructure. + +## Repository Hygiene + +- Confirm no secrets, DSNs, API keys, local database credentials, private source files, or environment-specific values are committed. +- Confirm no generated artifacts, caches, `.venv`, `__pycache__`, `.pytest_cache`, coverage outputs, screenshots, binaries, database dumps, or downloaded source files are committed. +- Confirm docs and templates still require scoped PRs, validation evidence, no production credentials, no generated artifacts, and no production-ready claim expansion without an explicit review task. +- Confirm public examples remain deterministic and local-only unless a reviewed task explicitly changes that boundary. + +## Handoff Notes + +Record the final branch, commit, validation commands, skipped checks with reasons, open maintainer follow-ups, and tag decision in the release or sync handoff. diff --git a/docs/production-readiness-gap-analysis.md b/docs/production-readiness-gap-analysis.md index 9c80b27..6e17967 100644 --- a/docs/production-readiness-gap-analysis.md +++ b/docs/production-readiness-gap-analysis.md @@ -56,7 +56,7 @@ Python production hardening should remain deferred until boundary documents and ## .NET Production Readiness Gaps -The .NET path is currently a planned implementation option rather than a parity implementation. +The .NET path now has parity evidence for the reviewed production scope; remaining gaps should be tracked as explicit parity or runtime-promotion review items. The .NET path still needs explicitly scoped future work for: diff --git a/docs/roadmap.md b/docs/roadmap.md index 216c121..8e3d6b0 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,8 +1,8 @@ # Roadmap -This roadmap organizes the path from the documentation baseline to a `v0.1.0` reference release. +This roadmap organizes the path from the current Phase 1 ingestion foundation to a `v0.1.0` reference release. -## Sprint 1: Documentation Baseline +## Sprint 1: Documentation Foundation - Add public project positioning. - Document architecture, configuration, database model, background job model, and source support. diff --git a/docs/source-acquisition-boundary.md b/docs/source-acquisition-boundary.md index e818726..e462d17 100644 --- a/docs/source-acquisition-boundary.md +++ b/docs/source-acquisition-boundary.md @@ -10,7 +10,7 @@ Source acquisition is the future boundary responsible for obtaining or locating The current repository has local and artificial examples that help demonstrate contract shape and deterministic workflows. Existing local/artificial examples do not imply production source acquisition coverage, real source coverage, parser correctness for real external sources, normalization correctness, factor correctness, legal/compliance interpretation, official carbon accounting correctness, or readiness for production use. -This document records the concepts that future tasks should define before implementation begins. +This document records the concepts that source-acquisition tasks should preserve or refine as implementation evolves. ## Current Baseline diff --git a/docs/source-ingestion-boundaries.md b/docs/source-ingestion-boundaries.md index 5e0d799..a4997fe 100644 --- a/docs/source-ingestion-boundaries.md +++ b/docs/source-ingestion-boundaries.md @@ -119,9 +119,9 @@ Metadata should support idempotency, traceability, and operational review. It sh The Python and .NET implementations are independent implementation options for the same conceptual workflow. -Python is planned first because it is better suited for early source discovery, file handling, spreadsheet inspection, and parser experimentation. +Python is the active first runtime path because it is well suited for source discovery, file handling, spreadsheet inspection, parser experimentation, and the current operator-run ingestion workflow. -The .NET implementation should aim for conceptual parity later. It should not define a different product scope, source boundary, or assurance model. +The .NET implementation should preserve conceptual parity within the reviewed scope and track future parity changes through explicit review tasks. It should not define a different product scope, source boundary, or assurance model. Shared documentation should describe common concepts. Implementation-specific details should stay within `src/python` or `src/dotnet`. diff --git a/docs/task-breakdown.md b/docs/task-breakdown.md index 87634f2..ed8b98f 100644 --- a/docs/task-breakdown.md +++ b/docs/task-breakdown.md @@ -2,9 +2,9 @@ This task list tracks the documentation and implementation path from CO-001 through CO-033. -## Sprint 1: Documentation Baseline +## Sprint 1: Documentation Foundation -- CO-001: Add project documentation baseline. +- CO-001: Add initial project documentation foundation. - CO-002: Review public wording and README navigation. - CO-003: Add initial release note skeleton. - CO-004: Add examples directory notes for future service files.