diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..68a8ff8 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,30 @@ +# Advisory owner map for maintainer review routing. +# GitHub only enforces this if branch protection requires code-owner review. +# Initial handle was verified from repository owner/collaborator metadata on 2026-06-15. +# Maintainer must confirm or replace handles before enabling enforcement. + +* @jsugg + +# Repository governance, release, and CI policy +/.github/ @jsugg +/CONTRIBUTING.md @jsugg +/docs/adr/ @jsugg +/docs/architecture/ @jsugg +/docs/api-stability.md @jsugg +/docs/operations/release-process.md @jsugg +/package.json @jsugg +/package-lock.json @jsugg + +# Safety-first runtime areas +/src/pageObjects/ @jsugg +/src/framework/selfHealing/ @jsugg +/src/framework/observability/ @jsugg +/src/data/selectors/ @jsugg +/src/utils/redisClient.ts @jsugg +/src/utils/logger.ts @jsugg + +# Contracts, schemas, scripts, and reference observability assets +/tests/suites/contracts/ @jsugg +/schemas/ @jsugg +/scripts/ @jsugg +/observability/ @jsugg diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..27963a0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,95 @@ +# Contributing + +AuroraFlow keeps contribution process lightweight: small scoped changes, source-backed docs, and targeted validation. Use this guide for local setup, review expectations, and architecture-governance touchpoints. + +## Quick start + +1. Read the project overview in [`README.md`](README.md) and local workflow details in [`docs/development.md`](docs/development.md). +2. Install dependencies: + + ```bash + npm ci + npx playwright install --with-deps + ``` + +3. Create a focused branch: + + ```bash + git switch -c feature/ + ``` + +4. Make the smallest coherent change and run the relevant validation below. + +## Scope and review rules + +- Prefer one subsystem per pull request. +- Keep production behavior, docs, tests, and contracts aligned. +- Do not remove or rename public root exports without the API-tier process in [`docs/api-stability.md`](docs/api-stability.md). +- Do not add dependencies, generated files, lockfile changes, release credentials, or infrastructure ownership claims unless the active task explicitly requires them. +- Do not broaden self-healing, Redis, telemetry, privacy, or release behavior from "planned" to "implemented" in docs unless source and tests already support the claim. + +For architecture-roadmap tasks, update the implementation journal in [`docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md`](docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md) before work starts, after meaningful changes, after validation, and before handoff. + +## Validation matrix + +Run the narrowest useful gate first, then the broader gate that matches your change. + +| Change area | Minimum validation | +| --- | --- | +| Markdown/docs only | `npm run format:check` and `npm run test:integration -- --run tests/suites/contracts/docs/documentationSurface.contract.spec.ts` | +| TypeScript source | Targeted unit/integration tests, `npm run typecheck`, `npm run lint`, `npm run format:check` | +| Public API surface | Package-surface unit and contract tests plus `npm run typecheck` | +| JSON Schemas | `npm run schemas:check` and affected contract tests | +| Workflows | `npm run workflows:lint` and `npm run workflows:security` | +| Redis data paths | Store/unit tests plus Redis integration when Docker is available | +| Observability paths | Focused observability tests; use full-stack smoke only when the task requires it | +| Release process | Release workflow contracts, `npm run build`, and `npm run pack:dry-run` | + +Before merging broad changes, prefer `npm run verify` when local tooling and time permit. + +## Safety guardrails + +Self-healing changes must preserve the safety-first contract: + +- `SELF_HEAL_MODE=off` remains the default. +- Guarded mode remains policy-gated and dry-run validated. +- Any auto-apply path gets at most one guarded retry and must not hide the original failure if retry fails. +- Source-code rewrites and blind selector mutation remain out of scope. +- Shared selector promotion requires explicit policy and protected-review workflow before active selector mutation. + +Privacy-sensitive data includes screenshots, DOM text, URLs, selectors, logs, telemetry attributes, Redis records, trend files, and audit records. Keep artifact controls and retention guidance aligned with [`docs/operations/privacy-retention.md`](docs/operations/privacy-retention.md). + +## Ownership and advisory review + +The repository uses an advisory CODEOWNERS file at [`.github/CODEOWNERS`](.github/CODEOWNERS). It maps critical paths to the current maintainer handle (`@jsugg`) for review routing and bus-factor visibility. + +The map is advisory until branch protection explicitly requires code-owner review. Confirm or replace owner handles with the maintainer before enabling enforcement, and add team aliases where available. + +Critical areas that should receive owner review: + +- self-healing and promotion safety; +- API tiers and root exports; +- scoring/SLO policy; +- Redis selector registry and data retention; +- observability contracts and support boundaries; +- release workflow, SBOM, provenance, and rollback policy; +- privacy, secrets, and artifact retention. + +## Architecture decision records + +Use ADRs for durable decisions that change policy, compatibility, operational boundaries, or safety behavior. Do not use ADRs for routine implementation notes. + +Initial ADRs live in [`docs/adr/`](docs/adr/): + +- [ADR 0001: Safety-first self-healing](docs/adr/0001-safety-first-self-healing.md) +- [ADR 0002: API stability tiers](docs/adr/0002-api-stability-tiers.md) +- [ADR 0003: Scoring and SLO policy](docs/adr/0003-scoring-and-slo-policy.md) +- [ADR 0004: Redis strategy](docs/adr/0004-redis-strategy.md) +- [ADR 0005: Observability boundary](docs/adr/0005-observability-boundary.md) +- [ADR 0006: Release policy](docs/adr/0006-release-policy.md) + +Each ADR should state status, date, context, decision, consequences, related `AUR-ARCH-*` issues, and revisit triggers. + +## Security and disclosure + +Do not commit secrets, credentials, real user data, or production screenshots. Use synthetic fixtures in tests. If you suspect a secret or sensitive artifact was committed, stop normal work and coordinate private remediation with the maintainer before opening a public pull request. diff --git a/README.md b/README.md index 01775b2..abe1eb2 100644 --- a/README.md +++ b/README.md @@ -208,7 +208,9 @@ scripts/ Report generation, workflow linting, governance, and - [Writing tests](docs/writing-tests.md) - [Configuration](docs/configuration.md) - [API](docs/api.md) +- [Contributing](CONTRIBUTING.md) - [Development guide](docs/development.md) +- [Architecture decision records](docs/adr/README.md) - [Architecture decision log](docs/architecture/decision-log.md) - [Phase 0 validation baseline](docs/architecture/phase-0-validation-baseline.md) - [Self-healing foundation](docs/architecture/self-healing.md) diff --git a/docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md b/docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md index 43cdb8f..4a11a45 100644 --- a/docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md +++ b/docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md @@ -2274,13 +2274,13 @@ All 13 decision gates were resolved by operator decision on 2026-06-10. `AUR-IMP | Field | Value | | --- | --- | | Current phase | Phase 1 | -| Current task | `AUR-IMPL-014`, `015`, `018`, and `019` complete; PR-01F ready to publish | -| Branch | `feature/phase-1-quality-foundation` | -| Latest commit | PR-01F quality foundation pending commit | -| Working tree status | PR-01F changes validated and pending commit | +| Current task | `AUR-IMPL-016` contributor governance complete; PR-01G ready to publish | +| Branch | `feature/contributor-governance` | +| Latest commit | `AUR-IMPL-016` changes pending | +| Working tree status | Governance docs and docs contract validated; pending commit | | Blocked decision gates | None; `AUR-DEC-001`-`AUR-DEC-013` resolved by operator on 2026-06-10 | -| Last validation run | 2026-06-13 PR-01F: full `npm run verify` passed (40 unit files / 229 tests; 19 integration/contract files / 79 tests); critical coverage passed at 87.87% statements / 76.55% branches / 95.91% functions / 88.12% lines; 10 schemas compiled; workflow security had no findings | -| Next recommended action | Commit and open PR-01F, run the peer matrix on the branch, follow required CI to green, and merge | +| Last validation run | 2026-06-15 PR-01G: full `npm run verify` passed (format, lint, typecheck, unit 40 files / 229 tests, integration/contracts 19 files / 80 tests, shellcheck, workflow lint); targeted docs contract passed after ADR index fix | +| Next recommended action | Commit and open PR-01G, follow CI to green, merge, and sync `main` | ### 15.3 Task Progress Log @@ -2303,6 +2303,8 @@ All 13 decision gates were resolved by operator decision on 2026-06-10. `AUR-IMP | 2026-06-13 | Implementation agent | `AUR-IMPL-011`, `AUR-IMPL-012` | Documented screenshot, DOM text, failure-event, log, Redis, telemetry, trend, and audit data classes plus shortest-useful retention guidance and consumer ownership. Added an additive `ArtifactPrivacyPolicy` with compatible and sensitive presets, screenshot disable/mask hooks, DOM text capture/redact/keyed-hash/disable modes, in-browser omission for sensitive capture, and protected `PageObjectBase` override seam. Classified seven new root exports. Added synthetic-secret fixtures proving sensitive failure artifacts, logger output, and telemetry contain no fixture secret while the compatible default remains unchanged. Explicitly excluded regulated PII support | `docs/operations/privacy-retention.md`, privacy/config/schema/API/self-healing docs, `src/framework/selfHealing/{artifactPrivacy,domSnapshot,domCandidateExtraction,analyzer,failureCapture}.ts`, `src/pageObjects/pageObjectBase.ts`, `src/index.ts`, privacy/logger/page-object/analyzer/docs/package-surface tests, `docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md` | Test-first unit/docs runs; `rtk npm run typecheck`; `rtk npm run lint`; `rtk npm run test:unit`; `rtk npm run test:integration`; `rtk npm run schemas:check`; `rtk npm run verify`; `rtk npm run security:check` | Initial tests failed on missing policy/doc as expected; final verify passed with 40 unit files / 228 tests and 17 integration/contract files / 74 tests; 10 schemas compiled; zizmor had no findings; npm audit found 0 vulnerabilities | Commit, open PR-01C, follow CI to green, merge, then `AUR-IMPL-013` | | 2026-06-13 | Implementation agent | `AUR-IMPL-018` | Made trend JSONL reads tolerant by default with valid-point preservation, observable skipped-line warnings/counts, strict opt-in, script reporting, and cache durability documentation | `src/framework/observability/trends.ts`, report scripts, trend tests/docs | Targeted trend test; schemas; typecheck; full verification | Valid/malformed/valid history passed; strict diagnostics preserved; scripts report skipped count | Include in PR-01F | | 2026-06-13 | Implementation agent | `AUR-IMPL-014`, `015`, `019` | Added scheduled/release Playwright floor/current/latest matrix, critical-module V8 coverage gate without a property-test dependency, focused real-exporter OTLP receiver coverage, and scheduled full/remote observability lanes | workflows, Vitest/package config, OTLP/workflow contracts, release/observability/testing docs | Local floor `1.59.1` and latest `1.60.0` type/unit checks; `npm run verify`; `npm run test:coverage`; workflow lint/security; schemas | Verify passed 40 unit files / 229 tests and 19 integration/contract files / 79 tests; coverage 87.87/76.55/95.91/88.12; no workflow security findings; 10 schemas compiled | Publish PR-01F and run branch peer matrix | +| 2026-06-15 | Implementation agent | `AUR-IMPL-016` | Started PR-01G contributor governance; verified clean `main`, created `feature/contributor-governance`, inspected docs contract, development docs, decision log, API tiers, release, Redis, self-healing, observability, and SLO policy docs; inferred provisional advisory owner from repository owner/collaborator list | `docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md` | `rtk git fetch origin main --prune`; `rtk git pull --ff-only origin main`; `rtk git switch -c feature/contributor-governance`; `rtk gh repo view --json nameWithOwner,defaultBranchRef,owner`; `rtk gh api repos/jsugg/auroraflow/collaborators --paginate --jq '.[].login'`; docs/task inspection commands; Serena `get_symbols_overview` on docs contract | Branch created from up-to-date `main`; owner handle available as `@jsugg`; no existing `CONTRIBUTING.md`, `CODEOWNERS`, or ADR directory | Add governance files, update docs contract and links, then run docs validation | +| 2026-06-15 | Implementation agent | `AUR-IMPL-016`, `AUR-VAL-026` | Added lightweight contributor guidance, advisory CODEOWNERS, ADR index, six initial ADRs, README/development links, docs-surface contract coverage, and journal completion evidence | `CONTRIBUTING.md`, `.github/CODEOWNERS`, `docs/adr/**`, `README.md`, `docs/development.md`, `tests/suites/contracts/docs/documentationSurface.contract.spec.ts`, `docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md` | `rtk npm run format:check`; `rtk npx prettier --write ...`; `rtk npm run test:integration -- --run tests/suites/contracts/docs/documentationSurface.contract.spec.ts`; `rtk npm run verify` | Initial formatting warned on two files and first docs contract caught the ADR index missing the literal ADR label; fixes applied. Final docs contract passed 19 files / 80 tests; full verify passed format/lint/typecheck/unit/integration/shellcheck/workflow lint | Commit, open PR-01G, follow CI to green, merge, and sync `main` | ### 15.4 Command Log @@ -2362,6 +2364,10 @@ All 13 decision gates were resolved by operator decision on 2026-06-10. `AUR-IMP | 2026-06-13 | `rtk npm run security:check` | Privacy/security posture gate | Passed | zizmor 1.25.2 reported no findings; npm audit found 0 vulnerabilities | | 2026-06-13 | Local Playwright floor/latest installs, typecheck, focused page-object/factory tests | Validate matrix dependency alignment before CI | Passed | Floor `1.59.1`; latest resolved `1.60.0`; `playwright`, `playwright-core`, and `@playwright/test` aligned | | 2026-06-13 | `rtk npm run verify`; `rtk npm run test:coverage`; `rtk npm run workflows:security`; `rtk npm run schemas:check` | Final PR-01F quality gate | Passed | 40 unit files / 229 tests; 19 integration/contract files / 79 tests; coverage thresholds passed; no workflow security findings; 10 schemas compiled | +| 2026-06-15 | `rtk npm run format:check` | First PR-01G formatting gate | Failed, then fixed | Prettier warned on `docs/adr/README.md` and docs contract test; targeted Prettier write made files clean | +| 2026-06-15 | `rtk npm run test:integration -- --run tests/suites/contracts/docs/documentationSurface.contract.spec.ts` | `AUR-VAL-026` docs contract for contributor governance | Failed, then passed | First run caught ADR index missing literal `ADR 0001`; after index fix, 19 integration/contract files and 80 tests passed | +| 2026-06-15 | `rtk npm run verify` | Full PR-01G gate | Passed | Format, lint, typecheck, 40 unit files / 229 tests, 19 integration/contract files / 80 tests, shellcheck, and workflow lint clean | +| 2026-06-15 | `rtk npx prettier --write docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md`; `rtk npm run format:check`; `rtk npm run test:integration -- --run tests/suites/contracts/docs/documentationSurface.contract.spec.ts` | Post-journal docs gate | Passed | Formatter clean; docs contract rerun passed 19 files / 80 tests | ### 15.5 Decision Log @@ -2417,6 +2423,19 @@ Current handoff, 2026-06-10 Codex: - **Decision gates updated:** Repository decision log now records `AUR-DEC-001` through `AUR-DEC-013`. - **Journal entries added:** Current status snapshot, task progress, command log, and handoff notes updated for PR-00A. +Current handoff, 2026-06-15 Implementation agent: + +- **What was completed:** `AUR-IMPL-016` contributor governance: root `CONTRIBUTING.md`, advisory `.github/CODEOWNERS`, ADR index, six initial ADRs for self-healing safety, API tiers, scoring/SLO policy, Redis strategy, observability boundary, and release policy, plus README/development discoverability and docs-surface contract coverage. +- **What remains:** Publish PR-01G, follow CI to green, merge, follow any `main` jobs, and sync local `main`. +- **Current blockers:** None. Owner handle is `@jsugg`, verified from repository owner/collaborator metadata; CODEOWNERS stays advisory until maintainer confirms/replaces handles and branch protection enables enforcement. +- **Validation status:** Targeted docs contract passed with 19 files / 80 tests. Full `npm run verify` passed format, lint, typecheck, unit 40 files / 229 tests, integration/contracts 19 files / 80 tests, shellcheck, and workflow lint. +- **Files changed:** `CONTRIBUTING.md`, `.github/CODEOWNERS`, `docs/adr/**`, `README.md`, `docs/development.md`, `tests/suites/contracts/docs/documentationSurface.contract.spec.ts`, `docs/ARCHITECTURE_IMPLEMENTATION_PLAN.md`. +- **Important context:** Process remains lightweight; no runtime behavior, public API, workflow, schema, dependency, or lockfile changes. +- **Recommended next task:** After PR-01G merges, continue Phase 2 with `AUR-IMPL-020` when ready. +- **Rollback notes:** Revert the governance docs, CODEOWNERS, ADR links, docs contract additions, and this journal update; no runtime rollback needed. +- **Decision gates updated:** None; ADRs record the already-resolved `AUR-DEC-*` policies. +- **Journal entries added:** Current status snapshot, task progress, command log, and handoff notes updated for PR-01G. + ## 16. Backlog Grooming Rules - Split a task when it touches more than one subsystem with independent validation, or when one PR would mix docs/governance with runtime refactor. diff --git a/docs/adr/0001-safety-first-self-healing.md b/docs/adr/0001-safety-first-self-healing.md new file mode 100644 index 0000000..76ec96b --- /dev/null +++ b/docs/adr/0001-safety-first-self-healing.md @@ -0,0 +1,29 @@ +# ADR 0001: Safety-first self-healing + +- Status: Accepted +- Date: 2026-06-15 +- Related: `AUR-ARCH-001`, `AUR-ARCH-002`, `AUR-ARCH-040`, `AUR-DEC-002`, `AUR-IMPL-002`, `AUR-IMPL-003`, `AUR-IMPL-020`, `AUR-IMPL-024`, `AUR-IMPL-025` +- Owners: maintainer / self-healing owner + +## Context + +Self-healing can reduce locator maintenance cost, but unsafe automation can hide product regressions or mutate selectors without review. The architecture plan therefore treats safety-first behavior as a preservation guardrail. + +## Decision + +AuroraFlow self-healing remains opt-in and safety-first: + +- default mode is `off`; +- guarded behavior must be policy-gated, confidence-gated, and dry-run validated; +- the default confidence policy is registry-curated-first, not fresh-DOM auto-acceptance; +- supported auto-apply paths may retry once, and failed retries must preserve the original failure; +- source-code rewrites and blind selector mutation remain out of scope; +- registry promotion writes require review records now and protected/shared authorization before broader shared use. + +## Consequences + +This keeps failure evidence auditable and avoids surprising test mutations. It also means some valid DOM candidates remain suggestions until registry history, scoring evidence, and review policy justify acceptance. + +## Revisit triggers + +Revisit only if reachability fixtures prove a broader default is safe, promotion authorization is implemented for shared workflows, and the implementation plan updates `AUR-DEC-002`. diff --git a/docs/adr/0002-api-stability-tiers.md b/docs/adr/0002-api-stability-tiers.md new file mode 100644 index 0000000..691b05f --- /dev/null +++ b/docs/adr/0002-api-stability-tiers.md @@ -0,0 +1,30 @@ +# ADR 0002: API stability tiers + +- Status: Accepted +- Date: 2026-06-15 +- Related: `AUR-ARCH-008`, `AUR-ARCH-009`, `AUR-ARCH-031`, `AUR-DEC-001`, `AUR-DEC-012`, `AUR-IMPL-009`, `AUR-IMPL-010` +- Owners: maintainer / API governance + +## Context + +The root package exports stable page-object APIs alongside advanced stores, telemetry wiring, and experimental self-healing internals. Without tiers, internal seams become accidental semver commitments. + +## Decision + +Every root export is classified in [`docs/api-stability.md`](../api-stability.md) as stable, advanced, experimental, deprecated, or internal. Package-surface tests enforce zero unclassified or stale exports. + +Compatibility policy: + +- stable exports break only in a major release after the documented deprecation window; +- advanced exports are supported but may have a shorter deprecation window; +- experimental exports may change in minor releases with changelog notice; +- internal exports carry no compatibility promise; +- compatibility surfaces also include shipped schemas, metric names, documented environment variables, and repository CLI outputs. + +## Consequences + +Maintainers can evolve internal seams without promising every export is stable. Consumers get clear upgrade expectations before depending on lower-level integration surfaces. + +## Revisit triggers + +Revisit when adoption evidence justifies promoting an experimental or advanced surface, or when a major release proposal needs deprecations or removals. diff --git a/docs/adr/0003-scoring-and-slo-policy.md b/docs/adr/0003-scoring-and-slo-policy.md new file mode 100644 index 0000000..00e7904 --- /dev/null +++ b/docs/adr/0003-scoring-and-slo-policy.md @@ -0,0 +1,28 @@ +# ADR 0003: Scoring and SLO policy + +- Status: Accepted +- Date: 2026-06-15 +- Related: `AUR-ARCH-003`, `AUR-ARCH-038`, `AUR-ARCH-041`, `AUR-DEC-003`, `AUR-DEC-013`, `AUR-IMPL-004`, `AUR-IMPL-014`, `AUR-IMPL-032` +- Owners: QA/SRE / maintainer + +## Context + +Self-healing candidate scores, dashboard targets, alert policies, and Prometheus rules can drift if each file owns thresholds independently. Premature blocking SLO gates would also create noisy CI without operational baseline data. + +## Decision + +Scoring and SLO thresholds are QA/SRE-owned policy: + +- self-healing scoring weights and confidence thresholds must stay source-backed and contract-tested; +- SLO dashboard targets, alert policy JSON, and Prometheus rule thresholds must stay drift-tested; +- alert breaches warn by default; +- blocking SLO gates require an explicit policy update and evidence from measured CI/project behavior; +- failure-path latency and artifact-volume budgets start baseline-first and warning-only. + +## Consequences + +Threshold changes become intentional policy changes rather than incidental constants. CI remains informative without blocking on immature operational signals. + +## Revisit triggers + +Revisit when benchmark history, failure rates, user impact, or maintainer capacity supports stricter gates. diff --git a/docs/adr/0004-redis-strategy.md b/docs/adr/0004-redis-strategy.md new file mode 100644 index 0000000..d517869 --- /dev/null +++ b/docs/adr/0004-redis-strategy.md @@ -0,0 +1,30 @@ +# ADR 0004: Redis strategy + +- Status: Accepted +- Date: 2026-06-15 +- Related: `AUR-ARCH-004`, `AUR-ARCH-005`, `AUR-ARCH-016`, `AUR-ARCH-026`, `AUR-ARCH-029`, `AUR-ARCH-037`, `AUR-ARCH-042`, `AUR-DEC-005`, `AUR-DEC-006`, `AUR-DEC-007`, `AUR-IMPL-005`, `AUR-IMPL-006`, `AUR-IMPL-017`, `AUR-IMPL-025`, `AUR-IMPL-028` +- Owners: maintainer / data and SRE reviewers + +## Context + +AuroraFlow needs durable selector registry and candidate-history primitives, but it must not imply that the library operates consumer infrastructure. Redis prefixing improves namespace hygiene, not authorization. + +## Decision + +Redis remains optional and consumer/operator-owned: + +- local development and basic page-object use must not require Redis; +- Redis is the first durable selector-registry backend; +- the in-memory store is non-durable and appropriate for tests/local experiments only; +- candidate-history and selector writes use backend atomicity where required; +- retention defaults favor shortest useful duration and consumer-owned cleanup; +- key prefixes are not access control; +- shared registry and shared promotion workflows remain unsupported until policy, protected review, and tenancy rules exist. + +## Consequences + +The package can offer useful durable registry primitives without becoming a managed data service. Operators remain responsible for TLS, ACLs, backups, restore, eviction, capacity, retention, and incident response. + +## Revisit triggers + +Revisit if a shared-registry policy, operator owner, Redis runbook, and protected promotion workflow are approved. diff --git a/docs/adr/0005-observability-boundary.md b/docs/adr/0005-observability-boundary.md new file mode 100644 index 0000000..9e7d208 --- /dev/null +++ b/docs/adr/0005-observability-boundary.md @@ -0,0 +1,29 @@ +# ADR 0005: Observability boundary + +- Status: Accepted +- Date: 2026-06-15 +- Related: `AUR-ARCH-019`, `AUR-ARCH-021`, `AUR-ARCH-041`, `AUR-ARCH-042`, `AUR-DEC-008`, `AUR-IMPL-019`, `AUR-IMPL-031`, `AUR-IMPL-040` +- Owners: maintainer / observability reviewers + +## Context + +AuroraFlow produces deterministic JSON/Markdown evidence and can export OpenTelemetry signals, but the full local stack is too heavy to become a default or production-support promise. + +## Decision + +Observability remains artifact-first: + +- JSON/Markdown artifacts are the deterministic merge-gate evidence; +- live telemetry is opt-in and no-op by default; +- the full Collector/Prometheus/Grafana/Jaeger/ELK stack is local/reference only; +- observability-lite is best effort when added; +- production deployment requires environment-specific ownership for credentials, TLS, storage, retention, networking, capacity, and on-call support; +- raw selectors and sensitive data stay suppressed unless an explicit opt-in permits them. + +## Consequences + +Consumers can adopt the library without running observability infrastructure. Teams that want live telemetry have reference assets and contracts, but production ownership remains outside the package. + +## Revisit triggers + +Revisit if user demand and maintainer capacity justify a supported lite profile or separate observability asset lifecycle. diff --git a/docs/adr/0006-release-policy.md b/docs/adr/0006-release-policy.md new file mode 100644 index 0000000..6b78ddf --- /dev/null +++ b/docs/adr/0006-release-policy.md @@ -0,0 +1,30 @@ +# ADR 0006: Release policy + +- Status: Accepted +- Date: 2026-06-15 +- Related: `AUR-ARCH-009`, `AUR-ARCH-034`, `AUR-ARCH-035`, `AUR-DEC-001`, `AUR-DEC-012`, `AUR-IMPL-010`, `AUR-IMPL-016` +- Owners: maintainer / release and security reviewers + +## Context + +AuroraFlow targets public npm library distribution. Releases need supply-chain evidence and rollback policy, but real publishing must not be reachable from routine CI before maintainer readiness. + +## Decision + +Release governance follows [`docs/operations/release-process.md`](../operations/release-process.md): + +- releases follow SemVer against the API stability tiers; +- changelogs are curated from Conventional Commits and must call out compatibility changes; +- dry-run release evidence includes package contents, SBOMs, provenance-readiness checks, and a changelog draft; +- public publish path should use npm provenance and SBOMs; +- artifact signing is deferred until release readiness and key ownership exist; +- real publishing requires a future protected, maintainer-approved workflow; +- rollback prefers deprecating a bad npm version and publishing a fixed version rather than unpublishing by default. + +## Consequences + +The release path is auditable before first publish and avoids accidental package publication. Future publishing still needs maintainer readiness, credentials/OIDC setup, and protected-environment review. + +## Revisit triggers + +Revisit when the first real release is scheduled, when signing ownership exists, or when a supply-chain requirement changes. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..019be7e --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,48 @@ +# Architecture Decision Records + +This directory contains durable architecture decision records for AuroraFlow. Keep ADRs short, dated, and tied to the `AUR-ARCH-*` issue or `AUR-DEC-*` decision that made the policy necessary. + +## ADR index + +| ADR | Status | Decision area | +| --------------------------------------------- | -------- | ------------------------- | +| [ADR 0001](0001-safety-first-self-healing.md) | Accepted | Safety-first self-healing | +| [ADR 0002](0002-api-stability-tiers.md) | Accepted | API stability tiers | +| [ADR 0003](0003-scoring-and-slo-policy.md) | Accepted | Scoring and SLO policy | +| [ADR 0004](0004-redis-strategy.md) | Accepted | Redis strategy | +| [ADR 0005](0005-observability-boundary.md) | Accepted | Observability boundary | +| [ADR 0006](0006-release-policy.md) | Accepted | Release policy | + +## Lightweight process + +- Write an ADR when a change affects safety behavior, compatibility, release posture, data retention, support boundaries, or ownership. +- Prefer a concise ADR over a broad RFC. +- Link evidence and validation commands when a decision depends on tests or workflow behavior. +- Revisit an ADR only with new evidence, and record the successor ADR instead of silently editing history. + +## Template + +```markdown +# ADR NNNN: Title + +- Status: Proposed | Accepted | Superseded by ADR NNNN +- Date: YYYY-MM-DD +- Related: `AUR-ARCH-*`, `AUR-DEC-*`, `AUR-IMPL-*` +- Owners: maintainer / domain owner + +## Context + +What forced this decision? + +## Decision + +What policy do we now follow? + +## Consequences + +What becomes easier, harder, or explicitly out of scope? + +## Revisit triggers + +What evidence would justify changing the decision? +``` diff --git a/docs/development.md b/docs/development.md index 0360d8b..6e441cc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -184,6 +184,14 @@ Security workflows cover dependency review on pull requests, high-severity npm a Releases are governed by a manual, dry-run-only workflow (`.github/workflows/release.yml`) that produces auditable evidence — pack report, SPDX/CycloneDX SBOMs, provenance-readiness check, and a changelog draft — without publishing. Publishing is intentionally disabled behind a protected-environment placeholder. See [release-process.md](operations/release-process.md) for the changelog, rollback, provenance, and SBOM policy (`AUR-DEC-012`). +## Contribution governance + +Use [`../CONTRIBUTING.md`](../CONTRIBUTING.md) as the lightweight contributor entry point. It links the validation matrix, safety guardrails, advisory CODEOWNERS policy, and initial ADR set. + +Ownership is advisory by default: [`.github/CODEOWNERS`](../.github/CODEOWNERS) routes review to the current maintainer handle, but it becomes enforceable only if branch protection requires code-owner review. Confirm or replace owner handles with the maintainer before enabling that enforcement. + +Architecture decision records live in [`adr/`](adr/). Add or supersede an ADR when a change affects safety-first self-healing, API compatibility tiers, scoring/SLO policy, Redis ownership, observability support boundaries, release policy, or another durable architecture decision. + ## Documentation rules Documentation should remain precise and source-backed: diff --git a/tests/suites/contracts/docs/documentationSurface.contract.spec.ts b/tests/suites/contracts/docs/documentationSurface.contract.spec.ts index 910d94c..8f62834 100644 --- a/tests/suites/contracts/docs/documentationSurface.contract.spec.ts +++ b/tests/suites/contracts/docs/documentationSurface.contract.spec.ts @@ -9,10 +9,18 @@ function readRepoFile(relativePath: string): string { describe('documentation surface contract', () => { it('ships API-grade onboarding and reference docs', () => { const requiredDocs = [ + 'CONTRIBUTING.md', 'docs/getting-started.md', 'docs/writing-tests.md', 'docs/configuration.md', 'docs/api.md', + 'docs/adr/README.md', + 'docs/adr/0001-safety-first-self-healing.md', + 'docs/adr/0002-api-stability-tiers.md', + 'docs/adr/0003-scoring-and-slo-policy.md', + 'docs/adr/0004-redis-strategy.md', + 'docs/adr/0005-observability-boundary.md', + 'docs/adr/0006-release-policy.md', 'docs/architecture/self-healing.md', 'docs/operations/privacy-retention.md', 'docs/operations/observability-contract.md', @@ -64,4 +72,48 @@ describe('documentation surface contract', () => { 'reviewed approval/rejection/rollback flows and source-code rewrites remain out of scope', ); }); + + it('documents lightweight contribution governance and advisory ownership', () => { + const contributing = readRepoFile('CONTRIBUTING.md'); + const codeowners = readRepoFile('.github/CODEOWNERS'); + const adrIndex = readRepoFile('docs/adr/README.md'); + const adrDocs = [ + 'docs/adr/0001-safety-first-self-healing.md', + 'docs/adr/0002-api-stability-tiers.md', + 'docs/adr/0003-scoring-and-slo-policy.md', + 'docs/adr/0004-redis-strategy.md', + 'docs/adr/0005-observability-boundary.md', + 'docs/adr/0006-release-policy.md', + ] + .map(readRepoFile) + .join('\n'); + + expect(contributing).toContain('lightweight'); + expect(contributing).toContain('advisory CODEOWNERS'); + expect(contributing).toContain('Confirm or replace owner handles'); + expect(codeowners).toContain('Advisory owner map'); + expect(codeowners).toContain('@jsugg'); + expect(adrIndex).toContain('ADR 0001'); + + for (const topic of [ + 'Safety-first self-healing', + 'API stability tiers', + 'Scoring and SLO policy', + 'Redis strategy', + 'Observability boundary', + 'Release policy', + ]) { + expect(adrDocs).toContain(topic); + } + + for (const issueId of [ + 'AUR-ARCH-034', + 'AUR-ARCH-035', + 'AUR-ARCH-009', + 'AUR-ARCH-040', + 'AUR-ARCH-041', + ]) { + expect(adrDocs).toContain(issueId); + } + }); });