From dc610e97d375492d23a7cf0da5a12cad260f92f0 Mon Sep 17 00:00:00 2001
From: Andrew Walsh <awalsh128@gmail.com>
Date: Sat, 4 Jul 2026 11:21:26 -0700
Subject: [PATCH] docs: add contribution boilerplate with documentation
 standards

---
 CONTRIBUTIONS.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 CONTRIBUTIONS.md

diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md
new file mode 100644
index 0000000..36e6caf
--- /dev/null
+++ b/CONTRIBUTIONS.md
@@ -0,0 +1,71 @@
+# Contributions
+
+Thank you for contributing to this project.
+
+## Scope
+
+This document defines contribution expectations for code quality, testing, and documentation.
+
+## Quick Start
+
+1. Fork and create a feature branch from `v2-ts`.
+2. Make focused, minimal, reversible changes.
+3. Run relevant checks before opening a PR.
+4. Open a PR with a clear summary and validation notes.
+
+## Development Standards
+
+1. Preserve existing architecture unless a change is explicitly requested.
+2. Keep naming consistent for semantically identical constructs.
+3. Prefer explicit failures with actionable errors.
+4. Avoid changing public API or externally observable behavior unless requested.
+
+## Documentation Standards
+
+Apply these standards to all exported/public APIs in `src/`:
+
+1. Use TSDoc blocks (`/** ... */`) with concise behavior-focused summaries.
+2. Include explicit `@param` tags for each input parameter.
+3. Include explicit `@returns` tags for return values (or `Nothing` for `void`).
+4. Include `@throws` when the function intentionally throws validation/runtime errors.
+5. Prefer documenting behavior and constraints over implementation detail.
+6. Keep comments synchronized with current behavior; update docs in the same change as code.
+
+## Testing Standards
+
+1. Test naming format: `<method> <conditions> <expected>`.
+2. Test behavior, not implementation detail.
+3. Keep setup focused on the tested condition.
+4. Avoid control-flow logic (`if`, loops) in test bodies.
+5. Add or update tests for any behavior change in the same PR.
+
+## Verification Before PR
+
+Run the smallest relevant checks first, then broader checks as needed:
+
+```bash
+npm run typecheck
+npm exec vitest run test/action.test.ts test/action-runner.test.ts test/manifest.test.ts test/io.test.ts
+```
+
+When changing scripts under `scripts/dev/` or `scripts/ops/`, also run:
+
+```bash
+npm exec vitest run test/dev_scripts.test.ts
+```
+
+## Pull Request Checklist
+
+1. Change scope is clear and minimal.
+2. Documentation updated for exported/public API changes.
+3. Tests added/updated for behavior changes.
+4. Verification commands listed with pass/fail status.
+5. No secrets or credentials are included.
+
+## Commit Message Guidance
+
+Use concise, imperative messages, for example:
+
+- `docs: standardize TSDoc across src APIs`
+- `test: add coverage for ActionRunner cache-hit branch`
+- `refactor: move reusable script library to repository root`