docs: add design proposal workflow

CONTRIBUTING.md

@@ -40,6 +40,33 @@ environment and do not install tools implicitly.
 - Follow the PR template (`.github/PULL_REQUEST_TEMPLATE.md`).
 - All checks (lint, tests) must pass before merge.
 
+## Design proposals
+
+Use the [`design-docs/`](design-docs/) process before implementation when a
+change affects a public API or persisted contract, crosses component ownership
+boundaries, introduces distributed failure or security semantics, adds an
+execution engine or extension point, or requires compatibility and migration
+decisions.
+
+Start with a feature issue that establishes the problem and use cases. Changes
+to the product boundary use a `[SCOPE]` issue as defined by
+[`docs/architecture/product-scope.md`](docs/architecture/product-scope.md).
+Then open a draft pull request containing only a proposal copied from
+[`design-docs/template.md`](design-docs/template.md) and any supporting images.
+Use line comments to review design details and keep unresolved decisions in the
+proposal's open-questions section.
+
+A maintainer must explicitly accept the design before its pull request merges.
+Implement the accepted design in a separate pull request and link both records.
+Acceptance approves the direction; it does not establish that a capability is
+implemented or supported. Update architecture, API, support, and user
+documentation when the behavior and its required evidence are delivered.
+
+A design proposal is normally unnecessary for a contract-preserving bug fix,
+local refactor, test addition, or documentation correction. See
+[`design-docs/README.md`](design-docs/README.md) for the complete lifecycle,
+status rules, review criteria, and document responsibilities.
+
 ## Code Style
 
 We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting. Run

design-docs/README.md

@@ -0,0 +1,90 @@
+# Design proposals
+
+This directory contains technical proposals for changes that need architectural
+review before implementation. It is part of the contributor workflow, not the
+user documentation or the source of truth for implemented capabilities.
+
+## Document responsibilities
+
+| Location | Responsibility |
+| --- | --- |
+| GitHub issues | Establish the problem, use cases, and whether Tributo should address it |
+| `design-docs/` | Compare options and review a proposed technical design |
+| `docs/adr/` | Record an accepted, durable architectural decision |
+| `docs/architecture/` | Describe the architecture implemented by the repository |
+| `docs/reference/support-matrix.md` | Record support claims backed by implementation, configuration, and tests |
+
+## When a proposal is required
+
+Write a design proposal before implementation when a change does one or more of
+the following:
+
+- adds or changes a public API, persisted configuration, Bundle Manifest,
+  storage schema, wire protocol, or extension contract;
+- changes an execution chain or ownership boundary across Tributo components;
+- introduces consistency, concurrency, retry, recovery, streaming-offset, or
+  credential-security semantics;
+- introduces an execution engine, runtime, extension point, or substantial
+  third-party dependency;
+- requires a compatibility, deprecation, or migration plan.
+
+A proposal is normally unnecessary for a contract-preserving bug fix, local
+refactor, test addition, or documentation correction. Maintainers may still
+request one when the architectural effect is unclear.
+
+## Proposal workflow
+
+1. Open a feature issue that states the problem, use cases, affected components,
+   and alternatives. Use a `[SCOPE]` issue when the proposal changes the product
+   boundary defined in
+   [`docs/architecture/product-scope.md`](../docs/architecture/product-scope.md).
+2. Copy [`template.md`](template.md) to
+   `YYYY-MM-DD-<descriptive-topic>.md` and open a draft pull request containing
+   the proposal and any supporting images. Do not include production code in
+   that pull request.
+3. Keep the proposal status `Draft` while reviewers discuss the design in pull
+   request comments. Resolve or explicitly defer every open question.
+4. A maintainer records the outcome. Change the status to `Accepted` only after
+   the maintainer explicitly approves the design. If the proposal establishes a
+   durable public contract or product boundary, add a concise ADR that links to
+   the detailed proposal before merging the design pull request.
+5. Close rejected or withdrawn proposal pull requests instead of merging their
+   draft documents. Record an important Go/No-Go outcome in
+   [`docs/architecture/decision-log.md`](../docs/architecture/decision-log.md)
+   when it governs future reconsideration.
+6. Implement an accepted design in a separate pull request. Link the accepted
+   proposal and update architecture, support, API, and user documentation only
+   when the corresponding behavior is implemented and verified.
+
+Acceptance authorizes the design direction. It does not mean the feature is
+implemented, available, or supported. The support matrix remains authoritative
+for capability claims.
+
+## Status values
+
+| Status | Meaning |
+| --- | --- |
+| `Draft` | Under review in an open draft pull request; must not be merged |
+| `Accepted` | Explicitly approved by a maintainer and eligible to merge |
+| `Superseded` | Replaced by a linked, accepted proposal |
+
+Rejected and withdrawn drafts remain discoverable through their closed pull
+requests and related issues. They do not enter the default branch.
+
+## Review and evolution
+
+Use pull request line comments for design details and the related issue for
+problem-scope discussion. The decider named in the proposal owns the final
+outcome. Acceptance requires concrete compatibility and verification criteria,
+not only agreement on the happy path.
+
+An accepted proposal is a historical design record. If implementation requires
+a material change to its public contracts, component boundaries, failure
+semantics, or acceptance criteria, update the proposal in a new design pull
+request and obtain approval before changing the implementation plan. Mark a
+replaced proposal `Superseded` and link its successor instead of rewriting the
+original rationale without explanation.
+
+All proposals use English, sentence-case headings without numeric prefixes, and
+credential-safe examples. Store images under `design-docs/images/<topic>/` to
+avoid filename collisions.

design-docs/template.md

@@ -0,0 +1,128 @@
+# Proposal title
+
+Replace every placeholder in this template before opening the proposal.
+
+| Attribute | Value |
+| --- | --- |
+| Status | Draft |
+| Authors | GitHub handles |
+| Decider | Maintainer GitHub handle |
+| Related issue | Issue link |
+| Supersedes | None |
+
+> An accepted proposal approves a design direction. It is not evidence that the
+> feature is implemented or supported. Link implemented capability evidence in
+> the implementation tracking section.
+
+## Summary
+
+Summarize the proposed change and its intended outcome.
+
+## Motivation and use cases
+
+Describe the concrete user problem, workload, environment, and scale. Explain
+why existing Tributo or Ray capabilities do not solve the problem.
+
+## Goals
+
+- Goal
+
+## Non-goals
+
+- Explicitly excluded behavior
+
+## Current behavior and evidence
+
+Describe the implemented call chain, public contracts, known limitations, and
+support evidence that form the baseline. Distinguish implemented behavior from
+prototypes, skeletons, and future plans.
+
+## Proposed design
+
+Describe the proposed components, control flow, data flow, state transitions,
+and ownership boundaries. Identify which work belongs to Tributo, Ray, an
+execution engine, or an optional integration package.
+
+## Public contracts and stability
+
+List affected public APIs, configuration models, persisted formats, plugin
+contracts, manifests, and user-visible errors. Assign an accurate Alpha, Beta,
+Stable, or future-planning classification. Explain versioning and compatibility
+rules.
+
+## Failure and security semantics
+
+Describe validation, fail-closed behavior, retries, idempotency, recovery,
+concurrency, resource cleanup, and observability. Explain how credentials and
+other sensitive values are resolved, isolated, redacted, and excluded from
+persisted identities, logs, representations, and errors.
+
+Write `Not applicable` with a reason when a concern in this section does not
+apply.
+
+## Compatibility, deprecation, and migration
+
+Explain compatibility with released APIs and persisted data. Define any
+deprecation window, migration mechanism, rollback boundary, and behavior for
+old readers, writers, clients, or plugins.
+
+## Alternatives considered
+
+For each credible alternative, describe its advantages, risks, and reason for
+acceptance or rejection. Include using an existing Ray or third-party feature
+and making no change.
+
+## Test plan and acceptance criteria
+
+Define independently verifiable acceptance criteria and the evidence required
+for each one. Identify unit, contract, conformance, integration, and end-to-end
+coverage. Name any required Ray cluster, database, object store, broker,
+container, or other real infrastructure gate without claiming it has already
+run.
+
+## Open questions
+
+- Question and owner
+
+All blocking questions must be resolved before the proposal becomes
+`Accepted`. Explicitly document any deferred question and the boundary that
+keeps it from affecting the accepted design.
+
+## Decision outcome
+
+Complete this section when the proposal leaves draft review. Record the
+decision, decider, rationale, and any follow-up condition. Link a corresponding
+ADR or architecture decision-log entry when required.
+
+## Implementation tracking
+
+Link implementation issues and pull requests. Link the architecture and support
+matrix updates that demonstrate the implemented capability. Do not use proposal
+acceptance as implementation evidence.
+
+## Review checklist
+
+- [ ] The proposal distinguishes implemented behavior from planned behavior.
+- [ ] Goals, non-goals, ownership boundaries, and stability are explicit.
+- [ ] Bounded ingestion and unbounded streaming lifecycles remain separate.
+- [ ] New bounded sources use Provider and Binding contracts without consumer
+      source branches.
+- [ ] New inference outputs use ResultSink and WriteGateway contracts without a
+      pipeline-owned data writer.
+- [ ] New algorithms declare their AlgorithmSpec, data-loading responsibility,
+      execution strategy, and Bundle output.
+- [ ] Model formats identify exporter, validator, flavor, and loader
+      responsibilities without format-string guessing.
+- [ ] Credential isolation and fail-closed behavior cover success and failure
+      paths.
+- [ ] Compatibility, migration, rollback, and required real-infrastructure
+      evidence are defined.
+- [ ] Support claims require an implementation, configuration entry point, and
+      corresponding tests.
+
+Keep unrelated checklist items and append `N/A` with a short reason. Do not
+delete them from the proposal.
+
+## References
+
+- Source or related design