diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..a123b80 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,68 @@ +name: Bug report +description: Report a reproducible HOWEDO defect +title: "bug: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for helping improve HOWEDO. Do not include secrets or security-sensitive exploit details here; follow SECURITY.md for vulnerabilities. + - type: input + id: version + attributes: + label: HOWEDO version or commit + placeholder: tag, package version, or git SHA + validations: + required: true + - type: dropdown + id: surface + attributes: + label: Affected surface + options: + - Continuity kernel + - API / cockpit + - PostgreSQL adapter + - LangGraph adapter + - Temporal adapter + - Trust / attestation + - Packaging / container + - Documentation + - Other + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal reproduction + description: Include deterministic steps, commands, and sanitized evidence. + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + placeholder: OS, Python version, runtime/integration versions + - type: checkboxes + id: checks + attributes: + label: Preflight + options: + - label: I searched existing issues. + required: true + - label: I removed credentials, tokens, private keys, and sensitive data. + required: true + - label: This is not a vulnerability disclosure. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..7cfad63 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/eimyroot/HOWEDO/blob/main/SECURITY.md + about: Do not disclose vulnerabilities in public issues. Follow the security policy. + - name: Support policy + url: https://github.com/eimyroot/HOWEDO/blob/main/SUPPORT.md + about: Read the supported public issue scope before filing. diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..0d21b0f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,40 @@ +name: Feature request +description: Propose a bounded capability or integration +title: "feat: " +labels: + - enhancement +body: + - type: textarea + id: problem + attributes: + label: Problem / operational need + description: Describe the continuity or integration problem, not only the desired implementation. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed capability + validations: + required: true + - type: textarea + id: invariants + attributes: + label: Trust and continuity invariants + description: Which fail-closed, evidence, protocol, or adapter boundaries must remain unchanged? + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Acceptance evidence + description: State the tests, conformance evidence, or observable behavior that would prove completion. + validations: + required: true + - type: checkboxes + id: checks + attributes: + label: Preflight + options: + - label: I searched existing issues and ADRs for this capability. + required: true diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5ea6507 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,36 @@ +# Changelog + +All notable changes to HOWEDO are documented here. + +The format follows Keep a Changelog principles. HOWEDO is currently pre-1.0; release-readiness claims remain bounded by `docs/RELEASE_READINESS.md`. + +## Unreleased + +### Repository presentation +- Professional public-repository scaffold and community health surface. +- Canonical support, governance, issue forms, and release presentation. + +## R16.3 — 2026-09-01 + +### Added +- Operator cockpit served by the HOWEDO FastAPI process. +- English-first repository presentation and architecture documentation. +- Repository hygiene and closure milestone. + +### Security and governance +- Preserved fail-closed continuity semantics and evidence-first change control. +- Kept production trust-root activation, public package publication, external security review, and production deployment authority as separate gates. + +## R16.2 — 2026-08-31 + +### Added +- Hardened container runtime and immutable GHCR publication path. +- Provenance and release-readiness controls. +- Current `eimyroot/HOWEDO` trust identity with preserved legacy evidence. + +### Changed +- Hardened GitHub Actions pinning and repository governance. +- Strengthened API recovery boundaries and continuity validation. + +### Fixed +- Fail-closed resource, SEMLOCK, compatibility, and superseded-resource behavior. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..94f91fa --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,25 @@ +# Governance + +HOWEDO uses an evidence-first, protected-main development model. + +## Canonical branch + +`main` is the canonical integration branch. Changes are expected to arrive through pull requests and satisfy the repository ruleset and required status checks before merge. + +## Decision authority + +The maintainer owns product direction, release decisions, repository policy, and acceptance of changes. Architecture changes that alter continuity semantics, trust boundaries, protocol identity, evidence formats, or adapter contracts should be documented with an ADR under `docs/adr/`. + +## Change principles + +- Fail closed when continuity or trust cannot be established. +- Preserve historical signed evidence rather than rewriting cryptographic identity. +- Keep presentation and adapters outside the continuity kernel's semantic authority. +- Prefer deterministic, reproducible verification over narrative claims. +- Do not weaken required checks to make a change mergeable; fix the implementation or the declared contract. + +## Releases + +A Git tag, GitHub Release, package publication, container publication, trust-root ceremony, and production deployment are distinct events. A successful engineering release candidate does not automatically assert completion of external assurance gates. + +See `docs/RELEASE_READINESS.md` for the authoritative boundary. diff --git a/README.md b/README.md index 49c8530..2f0a84f 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,10 @@ [![CI](https://github.com/eimyroot/HOWEDO/actions/workflows/ci.yml/badge.svg)](https://github.com/eimyroot/HOWEDO/actions/workflows/ci.yml) [![Container](https://github.com/eimyroot/HOWEDO/actions/workflows/container.yml/badge.svg)](https://github.com/eimyroot/HOWEDO/actions/workflows/container.yml) +[![Conformance](https://github.com/eimyroot/HOWEDO/actions/workflows/consolidation.yml/badge.svg)](https://github.com/eimyroot/HOWEDO/actions/workflows/consolidation.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-78ffd6)](LICENSE) +[![Python](https://img.shields.io/badge/Python-3.12%20%7C%203.13-78ffd6)](pyproject.toml) +[![Status](https://img.shields.io/badge/status-pre--1.0%20engineering%20RC-f4b860)](docs/RELEASE_READINESS.md) HOWEDO answers one operational question: @@ -15,6 +18,8 @@ HOWEDO answers one operational question: Persistence can restore what an agent knew. HOWEDO evaluates whether that state, its dependencies, its semantic assumptions, concurrent-write fences, and recovery binding are still valid **now**. +**Start here:** [Architecture](docs/ARCHITECTURE.md) · [Release readiness](docs/RELEASE_READINESS.md) · [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Governance](GOVERNANCE.md) · [Changelog](CHANGELOG.md) · [Support](SUPPORT.md) + ## Operator cockpit HOWEDO ships a lightweight cockpit in the same FastAPI process as the service API. @@ -33,11 +38,7 @@ or runtime control. It calls the same public API that external consumers use. docker compose up --build ``` -Then open: - -```text -http://127.0.0.1:8000/ -``` +Then open `http://127.0.0.1:8000/`. ### Run from Python @@ -54,7 +55,7 @@ Use a non-loopback bind only when you intentionally want to expose the service: howedo-cockpit --host 0.0.0.0 --port 8000 ``` -Health and API documentation: +Health and API surface: ```text GET /health @@ -106,9 +107,7 @@ Every continuity evaluation resolves to one of five actions: ``` The architecture rule is strict: **adapters and presentation may invoke HOWEDO semantics; they do -not redefine them.** - -Detailed scaffold and dependency-direction rules are in +not redefine them.** Detailed scaffold and dependency-direction rules are in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). ## Core subsystems @@ -238,12 +237,13 @@ The canonical repository uses: - protected `main` and pull-request-based change flow; - CODEOWNERS and an evidence-first PR template; +- structured bug/feature issue intake; - Python 3.12/3.13 CI; - Ruff and pytest; - release-candidate wheel/sdist verification; - container build, smoke, provenance, and SBOM workflows; - deterministic repository-hygiene checks; -- explicit [`SECURITY.md`](SECURITY.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md). +- explicit security, support, governance, contribution, and change-history contracts. Run the local baseline: @@ -267,12 +267,19 @@ See [`docs/RELEASE_READINESS.md`](docs/RELEASE_READINESS.md). ## Documentation map -- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — scaffold, layers, dependency direction. -- [`docs/RELEASE_READINESS.md`](docs/RELEASE_READINESS.md) — implemented vs. outstanding gates. -- [`docs/CONSTITUTION.md`](docs/CONSTITUTION.md) — continuity principles and invariants. -- [`docs/adr/`](docs/adr/) — architecture decision records. -- [`docs/operations/`](docs/operations/) — operational trust procedures. -- [`examples/`](examples/) — integration examples. +| Area | Canonical document | +| --- | --- | +| Architecture | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | +| Release truth | [`docs/RELEASE_READINESS.md`](docs/RELEASE_READINESS.md) | +| Continuity principles | [`docs/CONSTITUTION.md`](docs/CONSTITUTION.md) | +| Architecture decisions | [`docs/adr/`](docs/adr/) | +| Operations | [`docs/operations/`](docs/operations/) | +| Integration examples | [`examples/`](examples/) | +| Security | [`SECURITY.md`](SECURITY.md) | +| Contribution workflow | [`CONTRIBUTING.md`](CONTRIBUTING.md) | +| Governance | [`GOVERNANCE.md`](GOVERNANCE.md) | +| Support | [`SUPPORT.md`](SUPPORT.md) | +| Change history | [`CHANGELOG.md`](CHANGELOG.md) | ## Canonical invariant diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..2daa0bd --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,20 @@ +# Support + +## Project support + +HOWEDO is pre-1.0 engineering infrastructure. Public support is provided through GitHub Issues for reproducible defects, integration problems, documentation gaps, and bounded feature requests. + +Before opening an issue: + +1. Read `README.md` and `docs/RELEASE_READINESS.md`. +2. Search existing issues. +3. Reproduce against the current supported branch or release candidate. +4. Remove credentials, tokens, private keys, customer data, and other secrets from all evidence. + +## Security reports + +Do **not** disclose exploitable vulnerabilities in a public issue. Follow `SECURITY.md` and use the private reporting route described there. + +## What support does not imply + +Repository support is not a production SLA, certification, warranty, or authorization to treat HOWEDO as independently audited production trust infrastructure. Production assurance remains subject to the explicit gates in `docs/RELEASE_READINESS.md`.