@acrasie/dev-flow 0.0.0-stage → 1.0.1

package/docs/adr/0010-choose-quick-or-plan-after-discovery.md

@@ -0,0 +1,161 @@
+# ADR 0010: Choose Quick or Plan After Discovery
+
+## Status
+
+Accepted for current runtime. Replacement target sequencing is defined by ADR 0030;
+ADR 0026 is superseded as target design.
+
+## Context
+
+The `quick`, `standard`, and `critical` mode set mixes preparation depth with risk.
+Requiring a mode argument also asks the user to choose before repository discovery can
+show whether detailed planning is useful.
+
+Quick currently bypasses operational SHAPE and GATE work. That creates a second
+workflow rather than a lower-cost execution of the same lifecycle, and lets BUILD own
+localization or design work that belongs to SHAPE.
+
+The user-facing distinction is simpler: after technical discovery, either project a
+compact execution contract or emit a durable detailed plan. Safety remains independent.
+
+## Decision
+
+The invocation has no mode argument:
+
+`$dev-flow <objective>`
+
+Every task traverses all five operational phases:
+
+`INTAKE -> SHAPE -> GATE -> BUILD -> ASSURE -> finished`
+
+SHAPE contains two strictly separated roles with one explicit profile choice between
+them:
+
+`Discovery -> Quick|Plan choice -> Planning`
+
+Discovery runs adaptively until `discovery_sufficient`. It then presents one structured,
+evidence-backed preparation choice:
+
+- **Quick:** project a compact canonical execution contract in workflow state.
+- **Plan:** project a detailed canonical contract and one repository-versioned Markdown
+  plan containing the spec, implementation plan, and any required implementation
+  guidance.
+
+The recommendation uses only fresh Discovery evidence. Quick is recommended for
+localized, linear work with obvious validation. Plan is recommended for material
+cross-surface dependencies, migration, non-obvious sequencing, coordination, or other
+evidence that a durable artifact will reduce implementation drift. Policy may require
+Plan and must explain the exact constraint rather than presenting a false choice.
+
+An explicit initial request for a durable plan resolves Plan without a redundant
+question. A policy lock resolves Plan with an explanation rather than a false choice.
+Otherwise the workflow enters stable `awaiting_profile_choice`, persists the exact
+Quick/Plan choice and evidence-backed recommendation, and requires an explicit user
+answer. Silence cannot select the recommendation. Crash/resume restores the same choice
+unless its Discovery inputs changed. Producing the choice uses the existing Discovery
+result and does not require another model call.
+
+The visible choice is a compact Discovery checkpoint, not an evidence dump. It states
+the change shape, relevant surface count or categories, material dependency/migration/
+validation facts, the recommendation, and one short evidence-backed reason. Full
+Discovery evidence remains in state and is shown only on request.
+
+The selected profile remains valid through later Planning-to-Discovery loops. New
+technical complexity does not automatically ask the user again. Quick may gain whatever
+internal contract detail correctness requires without becoming Plan, and Plan remains
+Plan if later evidence simplifies the work. Only a fresh policy that forbids the
+selection or an explicit user change invalidates the profile choice.
+
+The profile choice happens before Planning and GATE. Choosing after all of SHAPE would
+either make Quick pay for a detailed plan it discards or force Plan to reopen SHAPE.
+Planning consumes the chosen profile and fresh Discovery evidence; it never rereads the
+repository.
+
+Quick and Plan share the same adaptive minimum Discovery required for safe executable
+planning: relevant behavior, surfaces, dependencies, repository constraints, validation
+commands, and material risks. Quick never saves tokens by moving unresolved technical
+discovery into BUILD.
+
+Plan may cause later targeted Discovery only when detailed Planning exposes a missing
+fact needed by the durable contract. It cannot widen discovery merely to add explanatory
+prose. Any evidence required for correctness, safety, or risk controls belongs to the
+common minimum and is therefore required for Quick too.
+
+Preparation profile controls artifact depth only. Risk and policy independently control
+safeguards, approvals, worktree requirements, threat modeling, rollback planning,
+assurance lanes, and other safety controls. The old Critical mode disappears; critical
+remains a valid risk level.
+
+This redesign uses a hard schema break. Legacy `quick`, `standard`, and `critical` task
+states, invocations, approvals, artifacts, and receipts are not migrated or accepted as
+current workflow evidence. Implementation replaces old mode branches directly rather
+than carrying compatibility aliases or migration paths. Existing adaptive INTAKE
+semantics remain, but its contract stops owning mode and hands risk plus product context
+to SHAPE.
+
+Quick and Plan share one contract schema. Quick's compact completion profile requires
+Intake references, affected surfaces, testable acceptance criteria, ordered execution
+steps, criterion-linked validation, applicable risks, and explicit dependencies. It
+does not repeat Intake or Discovery prose.
+
+Quick omits the Markdown projection, long rationale, obvious non-goals, a detailed task
+DAG when linear order is sufficient, and implementation guidance without a material
+architectural constraint. The smallest valid contract may contain one criterion, one
+execution step, and one validation. Compactness cannot remove coverage, freshness, or
+risk-driven requirements.
+
+Plan uses the same logical structure at greater depth:
+
+- **Spec:** expected behavior, scope, non-goals, and acceptance criteria.
+- **Plan:** atomic tasks, dependencies, and verification mapping.
+- **Implementation Guide:** only evidence-backed architectural constraints, patterns,
+  migration rules, or sequencing details needed to prevent implementation drift.
+
+Planning creates an Implementation Guide only when evidence proves at least one material
+implementation constraint: an architectural boundary, compatible API/schema/data
+migration, non-obvious execution ordering, security/concurrency/performance invariant,
+mandatory repository pattern not inferable from tasks, or complex rollback/deployment.
+The contract records `guideRequiredBecause` references to supporting evidence or risks.
+Without an admissible linked reason, the section is absent rather than rendered as
+`N/A`.
+
+The structured contract in workflow state is canonical. Plan automatically projects it
+to one repository-versioned Markdown document. The projection is generated from
+canonical fields and is never an independently edited second source of truth. Its
+default location is `docs/dev-flow/YYYY-MM-DD-<slug>.md`; repository configuration or
+policy may select another native representation or location.
+
+Planning renders the document as `Proposed` before GATE. Approval binds the canonical
+logical digest, then projection status becomes `Approved` without changing contract
+content. A manual projection edit triggers explicit Planning reconciliation; the
+workflow neither imports nor overwrites it silently.
+
+GATE always executes and binds explicit user approval to canonical logical digest for
+both profiles. Its current contract is defined by ADR 0024.
+
+BUILD always consumes the exact current SHAPE contract and never performs hidden
+shaping. ADR 0029 reduces it to native Codex execution with no separate skill or
+validation loop. ASSURE scales by applicable risk rather than profile and reaches
+`finished` directly under ADR 0025.
+
+## Consequences
+
+- The common invocation is one short command with no mode vocabulary.
+- Recommendation quality improves because repository complexity is known before choice.
+- Explicit plan requests and policy locks avoid redundant questions; all other choices
+  remain user-authoritative and resumable.
+- Quick pays only for necessary discovery and compact planning while still traversing
+  every lifecycle phase.
+- Quick avoids hidden BUILD-time shaping; Plan spends extra Discovery tokens only on
+  evidence genuinely required by its durable contract.
+- Quick and Plan share contract parsing, BUILD approval/digest boundary, and ASSURE
+  completion guards.
+- Plan produces one predictable review artifact without splitting spec, plan, and
+  guidance into drift-prone files.
+- The state machine needs a stable SHAPE state for the explicit profile choice.
+- The state machine no longer needs Standard- or Critical-only mode paths, but retains
+  critical risk semantics.
+- Invocation parsing, configuration, schemas, migration, docs, tests, metrics, and
+  benchmarks must replace task mode with a post-Discovery preparation profile.
+- Existing in-progress state becomes intentionally incompatible; the new schema and
+  validators must fail it clearly instead of guessing a conversion.

package/docs/adr/0011-separate-fast-local-and-authoritative-ci-quality-gates.md

@@ -0,0 +1,49 @@
+# ADR 0011: Separate Fast Local and Authoritative CI Quality Gates
+
+## Status
+
+Accepted.
+
+## Context
+
+The plugin needs automated formatting, linting, type checking, building, and testing
+without making normal commits progressively slower as the repository grows.
+
+A Git hook is useful for immediate feedback but is local, optional, and bypassable. It
+cannot be the sole owner of release or merge correctness. Running every validation on
+every commit would also couple commit latency to the future size of the complete test
+suite.
+
+## Decision
+
+Use two quality gates with different latency and authority contracts:
+
+- The **Fast Gate** runs before a commit, checks only staged supported files, performs
+  formatting and linting checks, does not mutate files, and targets sub-two-second
+  feedback.
+- The **Full Gate** runs in CI over the complete repository and performs formatting,
+  linting, type checking, build validation, the complete automated test suite, and
+  distribution smoke checks.
+
+The Fast Gate is developer feedback, not authoritative proof. CI remains the required
+source of quality evidence even when the local hook succeeds or is bypassed.
+
+Both gates cover the repository as one quality scope. Formatting includes supported
+source, configuration, schema, workflow, and documentation files at the repository root
+and under the plugin package. Linting applies to supported JavaScript and TypeScript
+files across the same scope. Generated, vendored, cached, lock, and distribution files
+are excluded explicitly where the tool does not already exclude them safely.
+
+Package scripts own both gate commands. Any Git-hook tool is only an adapter that calls
+those scripts and contains no independent quality policy.
+
+## Consequences
+
+- Commit latency stays bounded as the full test suite grows.
+- Root documentation and configuration cannot drift from plugin formatting policy.
+- A commit may exist locally before all tests run; merge safety therefore depends on
+  required CI.
+- Staged-file selection must be path-safe and must not silently omit supported renamed
+  or copied files.
+- Developers need an explicit command to run the Full Gate before pushing when desired.
+- Hook installation or bypass behavior cannot change CI validation semantics.

package/docs/adr/0012-use-bun-test-and-require-node-24.md

@@ -0,0 +1,41 @@
+# ADR 0012: Use Bun Test and Require Node 24
+
+## Status
+
+Accepted.
+
+## Context
+
+The test suite currently mixes `node:test` for most tests with `bun:test` for release
+tests. Maintaining two runner APIs and two test commands adds complexity. The published
+CLI executes on Node.js, while Bun already serves as the repository package manager and
+script runner.
+
+Node.js 22 remains in Maintenance LTS until April 30, 2027, but retaining it expands the
+CI matrix and constrains use of newer runtime facilities. Node.js 24 has a longer support
+horizon and is sufficient for the plugin's intended users.
+
+## Decision
+
+Use `bun:test` as the sole automated test-suite runner and migrate existing `node:test`
+tests to its native API.
+
+Raise the published runtime floor from Node.js `>=22.18.0` to Node.js `>=24.0.0`. Remove
+Node.js 22 from the CI matrix and repository compatibility contract.
+
+The Full Gate supplements Bun test execution with a narrow Node.js 24 Runtime Smoke
+Suite. After building and packaging, that suite uses the real Node binary to import the
+bundle, execute the CLI, validate configuration, and execute the package-manager binary
+symlink. It tests the published runtime boundary without duplicating the complete Bun
+test suite.
+
+## Consequences
+
+- Test files may use Bun's native TypeScript, mocks, snapshots, watch mode, randomized
+  ordering, and coverage without another test framework.
+- The Full Gate needs one test command instead of separate Node and Bun suites.
+- Users on Node.js 22 must upgrade even though that release remains maintained upstream.
+- Bun test execution cannot, by itself, prove compatibility with the Node.js runtime;
+  the narrow Runtime Smoke Suite supplies that evidence at the distribution boundary.
+- The smoke suite must remain small and contract-focused. General behavior belongs in
+  the Bun test suite and is not duplicated under Node.js.

package/docs/adr/0013-layer-source-distribution-and-runtime-tests.md

@@ -0,0 +1,42 @@
+# ADR 0013: Layer Source, Distribution, and Runtime Tests
+
+## Status
+
+Accepted.
+
+## Context
+
+Twenty-six of the repository's twenty-seven JavaScript test files import the generated
+`dist/dev-flow.mjs` bundle. This gives broad distribution fidelity but couples nearly
+every failure to the build artifact, makes failures less local, and prevents useful
+source-oriented coverage.
+
+Testing only source modules would be faster but could miss bundling, packaging, binary,
+and Node.js compatibility regressions.
+
+## Decision
+
+Partition automated tests into three explicit layers:
+
+1. **Unit Test Layer:** `bun:test` files import `src/*.ts` directly and validate isolated
+   deterministic behavior, boundary conditions, and failure contracts.
+2. **Integration Test Layer:** `bun:test` files exercise the built bundle and complete
+   workflows where module composition or generated artifacts are material.
+3. **Runtime Smoke Suite:** a narrow Node.js 24 suite exercises the packed distribution
+   boundary as defined by ADR 0012.
+
+Move tests to the lowest layer that can prove their contract. Do not repeat the same
+behavior across layers merely to increase counts or coverage.
+
+No additional test framework, transpiler, or coverage service is introduced. Bun owns
+TypeScript test execution and the main test API.
+
+## Consequences
+
+- Most deterministic logic can run without rebuilding the distribution.
+- Failures identify source behavior or distribution composition more precisely.
+- Source coverage becomes meaningful.
+- Integration tests retain evidence for bundle exports and workflow composition.
+- Test naming and scripts must make layer ownership visible.
+- Refactoring the current suite requires classifying existing cases rather than
+  mechanically changing imports.

package/docs/adr/0014-ratchet-source-coverage-with-bun.md

@@ -0,0 +1,51 @@
+# ADR 0014: Ratchet Source Coverage with Bun
+
+## Status
+
+Accepted.
+
+## Context
+
+The existing bundle-first suite cannot provide representative TypeScript source
+coverage. Selecting a fixed percentage before migrating tests would create an arbitrary
+target and could reward low-value tests written only to satisfy the number.
+
+Coverage still provides useful regression evidence when its scope is stable and its
+floor cannot silently decrease.
+
+## Decision
+
+Use Bun's built-in coverage reporting and threshold enforcement. Do not add a hosted
+coverage service or third-party instrumentation dependency.
+
+After the layered test migration from ADR 0013:
+
+1. Measure lines, functions, and statements for maintained `src/**/*.ts` files.
+2. Exclude tests, generated output, distribution files, fixtures, and vendored files.
+3. Set the initial enforced thresholds from the measured baseline, rounded down only
+   enough to avoid nondeterministic decimal noise.
+4. Reject any later change that falls below an enforced threshold.
+5. Raise thresholds when durable new coverage permits it. Never lower them without an
+   explicit documented decision explaining lost executable behavior or a corrected
+   measurement scope.
+
+Coverage is a Full Gate signal. The Fast Gate does not collect it.
+
+## Consequences
+
+- Coverage cannot regress silently after the source-test migration.
+- Initial thresholds reflect repository reality rather than an arbitrary percentage.
+- CI stays self-contained and lightweight.
+- Coverage does not replace behavior contracts, boundary tests, integration tests, or
+  the Runtime Smoke Suite.
+- Test or source-scope changes that legitimately alter measurement require an explicit
+  baseline review.
+
+## Implementation note
+
+Bun 1.3.14 reports and enforces line and function coverage, but its installed text and
+LCOV reporters do not expose statement coverage and its documented statement threshold
+key does not affect the gate. PR2 therefore records statement coverage as unavailable
+rather than claiming a false signal. Per-file line and function floors are enforced and
+the measured aggregate is recorded. Statement enforcement remains required when Bun
+exposes a verifiable metric.

package/docs/adr/0015-split-fast-and-type-aware-linting.md

@@ -0,0 +1,41 @@
+# ADR 0015: Split Fast and Type-Aware Linting
+
+## Status
+
+Accepted.
+
+## Context
+
+The pre-commit gate needs consistently low latency. The Full Gate also needs semantic
+TypeScript lint rules, such as unhandled-promise checks, that syntax-only linting and the
+TypeScript compiler do not provide alone.
+
+Oxlint type-aware linting requires the additional `oxlint-tsgolint` development package
+and remains an evolving feature. Oxlint's integrated type checking is experimental and
+is not yet a sufficient replacement for the repository's TypeScript compiler contract.
+
+## Decision
+
+Use two Oxlint execution profiles:
+
+- The Fast Gate runs native Oxlint rules without type-aware analysis over staged
+  JavaScript and TypeScript files.
+- The Full Gate runs Oxlint with type-aware rules over the repository and separately
+  runs `tsc --noEmit`.
+
+Install `oxlint-tsgolint` only as a development dependency. Do not enable Oxlint's
+experimental `--type-check` mode and do not remove TypeScript compiler validation.
+
+Both profiles consume one versioned Oxlint configuration. Differences in analysis mode
+belong in repository scripts, not duplicated rule configurations.
+
+## Consequences
+
+- Commit feedback avoids type-program construction cost.
+- CI detects semantic lint failures that syntax-only rules and `tsc` may miss.
+- The development installation gains one native tooling dependency, but the published
+  package remains unchanged.
+- Full linting and type checking intentionally overlap where independent tools can catch
+  different defects.
+- Upgrades to evolving type-aware rules require reviewing new diagnostics rather than
+  silently weakening the configured rules.

package/docs/adr/0016-use-husky-with-a-tested-bun-staged-file-adapter.md

@@ -0,0 +1,45 @@
+# ADR 0016: Use Husky with a Tested Bun Staged-File Adapter
+
+## Status
+
+Accepted.
+
+## Context
+
+The Fast Gate needs the exact set of staged, supported files. Husky installs and invokes
+Git hooks but does not own robust staged-file discovery. Shell word splitting is unsafe
+for valid paths containing whitespace or newline characters.
+
+`lint-staged` supplies mature file selection and argument handling, but its mutation,
+backup, and restoration features are unnecessary for a check-only gate. Adding it would
+also add another dependency and configuration surface.
+
+## Decision
+
+Install Husky at the Git repository root as the pre-commit hook adapter. The hook
+contains only a call to the root `check:staged` package script.
+
+Implement `check:staged` as a small tested Bun script that:
+
+1. obtains added, copied, modified, and renamed staged paths from Git with NUL-delimited
+   output;
+2. excludes deletions and configured generated, vendored, cached, lock, and distribution
+   paths;
+3. classifies supported formatter files separately from JavaScript and TypeScript lint
+   files;
+4. invokes Oxfmt in check mode and native Oxlint without shell interpolation;
+5. batches arguments or falls back safely before platform argument limits;
+6. preserves tool exit status; and
+7. never edits a file or the Git index.
+
+Do not add `lint-staged`. Test path parsing, classification, batching, empty sets,
+renames, unusual valid path characters, and failing child-process status.
+
+## Consequences
+
+- The Fast Gate adds Husky but no staged-file orchestration dependency.
+- Repository code owns a small security- and correctness-sensitive adapter and must test
+  it as production-quality tooling.
+- Hook behavior remains a thin projection of package scripts and cannot diverge into a
+  second quality policy.
+- Check-only behavior avoids partial-staging backup and restoration complexity.

package/docs/adr/0017-format-conservatively-with-oxfmt.md

@@ -0,0 +1,45 @@
+# ADR 0017: Format Conservatively with Oxfmt
+
+## Status
+
+Accepted.
+
+## Context
+
+Repository-wide formatting should remove presentation drift without introducing
+unrelated ordering changes or rewriting documentation prose. Oxfmt enables package JSON
+sorting by default and offers optional import sorting, but either behavior expands the
+initial migration and can obscure review of the formatting adoption.
+
+Import order can also be observable for modules with side effects. Formatting does not
+need to own that policy.
+
+## Decision
+
+Commit one explicit JSON Oxfmt configuration at the repository root with conservative,
+stable choices:
+
+- `printWidth: 100`
+- `semi: true`
+- `singleQuote: false`
+- `trailingComma: "all"`
+- `proseWrap: "preserve"`
+- `sortImports: false`
+- `sortPackageJson: false`
+
+Use the same configuration in editors, the Fast Gate, and the Full Gate. Apply the
+initial repository-wide formatting change in a dedicated commit so later functional
+diffs are not mixed with formatter churn.
+
+Import and manifest ordering remain outside formatter ownership unless a later decision
+adds them with dedicated compatibility evidence.
+
+## Consequences
+
+- Source, configuration, schema, workflow, and documentation layout becomes
+  deterministic without broad ordering churn.
+- Markdown prose retains author-selected wrapping where possible.
+- Package manifests keep their intentional field order.
+- Imports with side effects retain their authored order.
+- More configuration is explicit, reducing reliance on tool defaults that may differ
+  from Prettier or change across tooling generations.

package/docs/adr/0018-use-a-high-signal-oxlint-policy.md

@@ -0,0 +1,53 @@
+# ADR 0018: Use a High-Signal Oxlint Policy
+
+## Status
+
+Accepted.
+
+## Context
+
+Oxlint's default correctness category is intentionally small. Enabling every available
+category would increase noise, style debate, and false-positive pressure. The repository
+needs defects and likely defects to block changes without turning linting into a broad
+code-style policy already owned by Oxfmt.
+
+Oxlint may add diagnostics in minor releases without treating them as breaking changes.
+Unpinned upgrades could therefore change the gate unexpectedly.
+
+## Decision
+
+Configure one high-signal repository-wide policy:
+
+- `correctness`, `suspicious`, and `perf` diagnostics are blocking;
+- `pedantic`, `style`, `restriction`, and `nursery` categories are disabled initially;
+- unused Oxlint disable directives are blocking;
+- the gate permits zero warnings; and
+- Oxlint and `oxlint-tsgolint` use exact versions recorded in the lockfile.
+
+Tool upgrades are explicit review events. Review newly activated diagnostics and fix or
+document specific rule exceptions; never weaken a whole high-signal category merely to
+complete an upgrade.
+
+Oxfmt owns formatting. Oxlint style rules remain disabled unless a later behavior-driven
+decision establishes value not already supplied by deterministic formatting.
+
+Initial compatibility exceptions stay narrow and documented in `.oxlintrc.json`:
+
+- `typescript/no-unsafe-type-assertion` is disabled because validated runtime boundaries
+  intentionally narrow unknown data after deterministic schema checks;
+- `eslint/no-await-in-loop` is disabled only in files whose prompts, filesystem changes,
+  or release operations must remain sequential; and
+- `typescript/no-floating-promises` is disabled only for test files, where test
+  registration calls intentionally return promises that the runner owns.
+
+These exceptions do not disable their parent high-signal categories. Revisit them when
+the affected APIs or Oxlint analysis improve.
+
+## Consequences
+
+- Likely defects and performance footguns fail both applicable gates.
+- Style and experimental diagnostics do not create routine noise.
+- Exact versioning keeps local and CI results reproducible.
+- Dependency upgrades may require intentional code fixes or narrow documented rule
+  exceptions.
+- The repository must review the rule configuration as Oxlint's stable coverage grows.

package/docs/adr/0019-gate-deterministic-size-and-observe-timing.md

@@ -0,0 +1,44 @@
+# ADR 0019: Gate Deterministic Size and Observe Timing
+
+## Status
+
+Accepted.
+
+## Context
+
+The plugin aims to remain performant and lightweight. Artifact size is deterministic
+enough for a blocking CI contract, while wall-clock measurements on shared CI runners
+vary with host load and can make an otherwise correct gate flaky.
+
+The current bundle is 805,435 bytes and the pre-migration Full Gate completes in about
+1.54 seconds on one maintainer machine. These are observations, not yet portable
+thresholds.
+
+## Decision
+
+After the quality-toolchain migration, measure and commit baselines for:
+
+- uncompressed `dist/dev-flow.mjs` bytes;
+- packed npm tarball bytes; and
+- unpacked npm package bytes.
+
+Create deterministic blocking budgets from those baselines with explicit headroom
+recorded alongside each value. A change may update a size budget only with a reviewed
+explanation of the user-visible capability or required asset responsible for the growth.
+
+Record Fast Gate, Full Gate, and cold CLI-start timing observations. Do not make timing
+blocking until repeated CI data establishes a stable measurement method and a threshold
+with enough tolerance to avoid runner-noise failures.
+
+Do not combine timing and size into one score. A deterministic size regression remains
+blocking even when execution happens to become faster.
+
+## Consequences
+
+- Artifact growth becomes visible and reviewable.
+- Shared-runner timing noise cannot fail otherwise correct changes initially.
+- Performance timing remains observable and can become a ratcheted gate after a stable
+  baseline exists.
+- Size-budget updates require explicit review rather than an unexplained baseline reset.
+- The implementation must define reproducible pack inputs before capturing package
+  budgets.

package/docs/adr/0020-support-linux-and-macos-with-targeted-ci.md

@@ -0,0 +1,41 @@
+# ADR 0020: Support Linux and macOS with Targeted CI
+
+## Status
+
+Accepted.
+
+## Context
+
+The plugin describes itself as portable. Existing release policy guarantees the
+maintainer workflow on macOS, treats Linux as best-effort, and explicitly does not claim
+Windows support. Running the complete quality toolchain on every operating system would
+increase CI cost without equal value for platform-independent checks.
+
+Ubuntu-only CI would leave the existing macOS release guarantee dependent on manual
+maintainer testing.
+
+## Decision
+
+Define Linux and macOS as the supported platform contract. Windows remains explicitly
+unsupported until a later decision supplies compatible behavior and CI evidence.
+
+Use targeted GitHub Actions jobs:
+
+- run the complete Bun Full Gate, coverage, lint, typecheck, build, size, and package
+  checks on Ubuntu;
+- run the Node.js 24 Runtime Smoke Suite on Ubuntu and macOS; and
+- run maintainer-release integration tests on macOS in addition to their primary Bun
+  execution on Ubuntu.
+
+Do not duplicate platform-independent formatting, linting, type checking, coverage, or
+unit tests across operating systems.
+
+## Consequences
+
+- Published runtime and maintainer release behavior gain automated Linux/macOS evidence.
+- CI cost stays below a full operating-system matrix.
+- Platform-specific failures are localized to narrow jobs.
+- Windows users receive no compatibility guarantee and documentation must say so
+  directly.
+- Adding Windows later requires path, process, symlink, permission, and release-contract
+  evidence before changing the support claim.

package/docs/adr/0021-randomize-tests-without-retries.md

@@ -0,0 +1,35 @@
+# ADR 0021: Randomize Tests Without Retries
+
+## Status
+
+Accepted.
+
+## Context
+
+Bun executes the test suite in one process. Fixed discovery order can hide shared-state,
+fixture, environment, or cleanup dependencies between tests. Automatic retries make CI
+appear stable while masking those defects.
+
+Bun reports the seed used for randomized test order and accepts that seed for exact
+reproduction.
+
+## Decision
+
+Run the Bun test suite in CI with randomized ordering and preserve the reported seed in
+job logs. Do not enable global or per-test automatic retries as a normal gate policy.
+
+Every randomized failure is a real failure. Reproduce it with the emitted seed, remove
+the order dependency or leaked state, and add a regression test where useful.
+
+Use repeated execution only in an explicit periodic stress job or during diagnosis. A
+passing retry cannot replace the original failing Full Gate result.
+
+## Consequences
+
+- CI continually probes order independence at negligible dependency cost.
+- A failure remains reproducible through its recorded seed.
+- Tests must isolate temporary files, processes, environment variables, clocks, and
+  global state.
+- Intermittent failures cannot be hidden by retry-until-green behavior.
+- Periodic repeated execution can detect low-probability failures without making every
+  pull request pay the same cost.