Wave 39: centralize contributor and agent governance

.github/CODEOWNERS

@@ -17,10 +17,17 @@ conformance/                                    @sirdeggen @ty-everett @BraydenL
 
 # CI, release, dependency, and analysis controls require redundant ownership.
 .github/                                        @sirdeggen @ty-everett
+/AGENTS.md                                      @sirdeggen @ty-everett
+/CLAUDE.md                                      @sirdeggen @ty-everett
+/CODE_OF_CONDUCT.md                             @sirdeggen @ty-everett
+/CONTRIBUTING.md                                @sirdeggen @ty-everett
 /package.json                                   @sirdeggen @ty-everett
 /pnpm-lock.yaml                                 @sirdeggen @ty-everett
 /pnpm-workspace.yaml                            @sirdeggen @ty-everett
+/governance/contributor-policy.json             @sirdeggen @ty-everett
 /governance/repository-health/                  @sirdeggen @ty-everett
+/scripts/contributor-policy.mjs                 @sirdeggen @ty-everett
+/scripts/contributor-policy.test.mjs            @sirdeggen @ty-everett
 /scripts/repository-health.mjs                  @sirdeggen @ty-everett
 /scripts/repository-health.test.mjs             @sirdeggen @ty-everett
 /sonar-project.properties                       @sirdeggen @ty-everett

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,81 @@
+name: Bug report
+description: Report a reproducible defect in a ts-stack package, service, specification, or tool.
+title: 'fix: '
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a defect. Do not disclose vulnerabilities or secrets here; use the private security policy instead.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Select the closest affected area.
+      options:
+        - SDK or VeriFast
+        - Wallet
+        - Overlays
+        - Messaging
+        - Middleware
+        - Network
+        - Helpers
+        - Infrastructure or containers
+        - Conformance or specifications
+        - Documentation
+        - CI, dependencies, or release tooling
+        - Cross-stack or unsure
+    validations:
+      required: true
+  - type: input
+    id: packages
+    attributes:
+      label: Affected package or service and version
+      description: Include every known package/service and the installed, source, image, or deployment version.
+      placeholder: '@bsv/sdk 2.x; Node 24.x; browser/runtime details'
+    validations:
+      required: true
+  - type: textarea
+    id: summary
+    attributes:
+      label: Defect
+      description: Describe the observable problem, its impact, and whether it is a regression.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Provide deterministic steps or a small repository/code sample. Remove credentials and private data.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Cite a public API, specification, conformance vector, or prior compatible behavior when applicable.
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior and evidence
+      description: Include complete errors, logs, or screenshots after redacting secrets.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Node, package manager, browser/mobile runtime, database, image digest, and relevant configuration.
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Safety checks
+      options:
+        - label: I searched for an existing issue or pull request describing this defect.
+          required: true
+        - label: This report contains no secret, private key, token, production data, or uncoordinated vulnerability detail.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Private security report
+    url: https://github.com/bsv-blockchain/ts-stack/security/advisories/new
+    about: Report vulnerabilities privately. Do not open a public security issue.

.github/ISSUE_TEMPLATE/proposal.yml

@@ -0,0 +1,59 @@
+name: Change proposal
+description: Propose a capability, specification, public API, package, migration, or cross-stack improvement.
+title: 'proposal: '
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Substantial changes should establish compatibility, specification, security, and migration intent before implementation.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem and users
+      description: What concrete problem exists, who encounters it, and why current behavior is insufficient?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed end state
+      description: Describe behavior and acceptance criteria, not only an implementation.
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Affected packages, services, and implementations
+      description: Include TypeScript projects, public services, specifications, conformance vectors, and other implementations.
+    validations:
+      required: true
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: Compatibility and migration
+      description: Explain public API, wire, persistence, runtime, browser/mobile, deployment, and cross-implementation effects.
+    validations:
+      required: true
+  - type: textarea
+    id: security
+    attributes:
+      label: Security and operational impact
+      description: Identify changed trust boundaries, abuse cases, CORS/CSP behavior, dependencies, rollout, and rollback.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Validation plan
+      description: List tests, conformance, consumer, performance, documentation, and release evidence required.
+    validations:
+      required: true
+  - type: checkboxes
+    id: commitments
+    attributes:
+      label: Proposal checks
+      options:
+        - label: I searched for overlapping issues, pull requests, specifications, and planning records.
+          required: true
+        - label: I have not assumed that a breaking change is acceptable merely because it simplifies implementation.
+          required: true

.github/SECURITY.md

@@ -92,7 +92,7 @@ Pull requests and releases enforce, as applicable:
 
 Coverage-guided fuzzing, remaining manual/browser/performance review, and the
 final QA hardening campaign are deliberately tracked as unfinished in
-[issue #324](https://github.com/bsv-blockchain/ts-stack/issues/324). They must
+[issue #400](https://github.com/bsv-blockchain/ts-stack/issues/400). They must
 not be described as complete until their preserved branch is finished,
 reviewed, merged, and validated.
 

.github/dependabot.yml

@@ -108,7 +108,7 @@ updates:
       - dependency-name: node
       # Database majors require backup/restore, upgrade-path, rollback, and
       # application compatibility validation. Patch and minor refreshes remain
-      # automated; major migrations are tracked explicitly in issue #324.
+      # automated; each major migration requires its own reviewed issue.
       - dependency-name: mysql
         update-types:
           - version-update:semver-major

.github/pull_request_template.md

@@ -1,9 +1,14 @@
+> Keep this pull request in draft until local validation is complete. After
+> every push, wait for all applicable checks on the exact head to finish and
+> fix every failure before requesting review or calling the work complete.
+
 ## Program and scope
 
 - Tracker or issue:
 - Program gate(s) advanced:
 - Why this change is needed:
 - Explicitly out of scope:
+- Exact head SHA reviewed:
 
 ## Impact
 
@@ -26,13 +31,18 @@ through the release workflow after approval):
 - Lint/typecheck delta:
 - Browser/mobile/packed-consumer evidence:
 - Performance or bundle-size delta:
+- [ ] I self-reviewed the complete diff for correctness, security,
+      compatibility, public API, artifacts, dependencies, docs, and operations
+- [ ] All applicable checks are terminal and successful on the exact head; any
+      scope-based skip is expected and validated by the merge gate
 
 ## Security and dependencies
 
 - [ ] No dependency or lockfile change
 - [ ] Changelog, runtime relevance, peer compatibility, transitive graph, and
       audit results were reviewed
 - [ ] CodeQL/negative tests cover any changed trust boundary
+- [ ] The exact-head CodeQL analysis has no new alert
 - [ ] The exact-head repository quality gate reports zero new Sonar findings
       (including accepted or false-positive issue states) and zero unreviewed hotspots;
       Sonar's aggregate `Quality Gate passed` verdict alone is not merge evidence
@@ -68,5 +78,9 @@ changes. Use “Not applicable — <reason>” only when the reason is concrete.
 - [ ] The linked tracker is updated only for work fully proved by merged code,
       passing checks, resolved alerts, measurements, or an approved exception
 - [ ] Review conversations are resolved
+- [ ] Documentation, changelog, migration notes, release notes, and operator
+      guidance are current or concretely not applicable
+- [ ] No pending, failed, stale, cancelled, or unexpectedly skipped check is
+      being handed to another contributor as “complete”
 - [ ] One qualified maintainer approval is sufficient; no last-pusher
       restriction is assumed

.github/workflows/ci.yml

@@ -32,6 +32,9 @@ jobs:
       - name: Test repository health controls
         run: node --test scripts/*.test.mjs
 
+      - name: Enforce uniform contributor and agent policy
+        run: node scripts/contributor-policy.mjs
+
       - name: Enforce the TypeScript compiler and tooling-API boundary
         run: node scripts/typescript-toolchain.mjs
 

AGENTS.md

@@ -0,0 +1,139 @@
+# ts-stack agent instructions
+
+These instructions apply to every file in this repository. They are the only
+repository contribution instructions for AI agents. A package-level
+`AGENTS.md` is a pointer to this file, not a place to define different rules.
+
+## Read before changing anything
+
+1. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md), the relevant package or service
+   README, and any applicable material under `docs/`, `specs/`, and
+   `governance/`.
+2. Read [`.github/SECURITY.md`](./.github/SECURITY.md) before touching a trust
+   boundary, dependency, workflow, release, credential, public service, or
+   persistence behavior.
+3. Establish the current `main` state, inspect existing changes, and identify
+   the governed project profile and criticality in
+   `governance/repository-health/projects.json`. Infrastructure service
+   contracts live in `governance/service-operations.json`.
+4. Keep work narrowly scoped. Do not overwrite unrelated changes or
+   regenerate unrelated artifacts.
+
+Do not create package-local contribution rules, agent instructions, pull
+request templates, issue templates, Dependabot files, or workflows. Propose
+shared policy at the repository root. Package-specific technical information
+belongs in its README, `docs/`, `specs/`, or an operator guide.
+
+## Preserve contracts first
+
+- Specifications, conformance vectors, public declarations, documented
+  behavior, and established cross-implementation behavior are contracts.
+- Prefer additive and backward-compatible changes. Do not rename or remove
+  exports, narrow accepted input, change defaults, alter wire encodings,
+  serialization, persisted schemas, error identities, runtime targets, or
+  browser/mobile behavior without an explicitly approved migration.
+- A generic cleanup, analyzer suggestion, dependency upgrade, or refactor is
+  never sufficient reason for a breaking change.
+- When behavior is portable across BSV implementations, update or add shared
+  conformance evidence and consider compatibility with implementations outside
+  this repository.
+- Tier 0 projects (`@bsv/sdk`, `@bsv/verifast`, and
+  `@bsv/wallet-toolbox`) require the highest review bar. Treat cryptography,
+  Script/consensus logic, transaction encoding, WASM/worker boundaries, wallet
+  storage, signing, and remotely exposed trust boundaries as security- and
+  compatibility-critical.
+
+For public services, preserve credential-free public cross-domain access by
+default where it is already part of the service contract. Overlay, Wallet
+Storage, WAB, Message Box, relay, browser, mobile, and unknown-domain clients
+must not be silently blocked by CORS, CSP, hosting URLs, or origin checks.
+Allowlist modes are opt-in deployment policy; authentication, authorization,
+signatures, validation, rate limits, and request bounds provide security.
+
+## Implementation discipline
+
+- Understand the root cause and deployed impact before editing.
+- Prefer the smallest clear solution that removes the cause without hiding a
+  finding or weakening a check.
+- Keep authored code warning-free, strictly typed, formatted, and
+  understandable. Do not use generated output, suppression, exclusions,
+  accepted findings, false-positive status, skipped tests, or baselines to
+  conceal new debt.
+- Add tests that fail on the old behavior when practical. Cover negative,
+  boundary, interoperability, and compatibility cases appropriate to the
+  change.
+- Review the complete diff as a maintainer would: correctness, security,
+  compatibility, public API, package artifacts, performance, documentation,
+  migration, release, and operational impact.
+- Update documentation in the same change. Documentation, examples, manifests,
+  generated facts, release notes, and code must never intentionally drift.
+
+## Dependencies and generated files
+
+- Treat Dependabot and other automation as proposals, not approvals. Review
+  upstream release notes, necessity, runtime and peer compatibility,
+  transitive changes, lockfile deduplication, advisories, CodeQL impact,
+  package consumers, and bundle/performance effects.
+- First-party `@bsv/*` versions are coordinated by the repository release
+  process, not generic dependency automation.
+- Never hand-edit owned generated files. Change their source or generator and
+  run the documented deterministic generation check.
+- Do not add an override, quality exception, advisory dismissal, or dependency
+  hold unless no safe remediation exists and the governed registry records an
+  owner, evidence, review date, removal condition, and compatibility rationale.
+
+## Validation
+
+Use Node and pnpm versions from the root `package.json`. Run the strictest
+relevant local checks before spending hosted CI resources. At minimum, every
+change must pass:
+
+```sh
+pnpm health:check
+pnpm lint
+pnpm format:check
+pnpm typecheck
+```
+
+Run build and tests for every affected package and dependent behavior. Add the
+applicable conformance, coverage, packed-consumer, browser, mobile, property,
+mutation, documentation, security-audit, infrastructure, container, or
+performance checks described in [`CONTRIBUTING.md`](./CONTRIBUTING.md). A local
+shortcut may speed iteration but cannot replace the remote merge gate.
+
+## Pull requests and completion
+
+- Fill in the root pull request template with commands and concrete evidence;
+  do not check a box that has not been proved.
+- Open unfinished work as a draft. After each push, monitor the exact head
+  until every applicable check reaches a terminal successful state. An
+  expected scope-based skip is acceptable only when the repository merge gate
+  validates it; a missing, cancelled, stale, or unexpectedly skipped check is
+  not success.
+- A PR is not ready for handoff, review, merge, or a claim of completion while
+  CI is pending or failing, review threads are open, or Sonar/CodeQL has a new
+  finding. Continue working through failures; do not leave them for another
+  contributor without an explicit handoff request.
+- “Quality gate passed” means the complete repository gate passed for the
+  exact head. SonarCloud’s aggregate badge alone is not evidence. New Sonar
+  issues—including accepted or false-positive classifications—new unreviewed
+  hotspots, and new CodeQL alerts must be resolved before review.
+- One qualified maintainer approval is sufficient. Maintainers and
+  administrators may facilitate a merge after required checks and review
+  threads are complete; no independent last-pusher rule is assumed.
+- Re-read the final diff and verify the head SHA before review or merge. After
+  merge, verify `main` when the change affects shared controls, releases, or
+  deployed behavior.
+
+## Versions, notes, and releases
+
+Follow `docs/about/versioning.md` and the protected release workflows.
+Published-byte or manifest changes require the correct affected-package SemVer
+decision, an updated `governance/package-release-notes.json` entry, current
+package documentation, and migration guidance—even when the migration is
+“none.” Update a package-local changelog when that package already maintains
+one.
+
+Never publish npm packages or container images, create release tags, or deploy
+from a workstation unless an operator explicitly authorizes that separate
+action. Merging source is not publication, and publication is not deployment.