@thebassclef/lite 0.1.0 → 0.1.3

package/substrate/standards/code-safety-principles.md

@@ -0,0 +1,176 @@
+---
+tier: lite
+description: "This standard codifies language-agnostic principles for writing safer code across bassclef's supported stacks (TypeScript, Python, Ruby, Java, Go, bash)."
+---
+
+# Code Safety Principles — Language-Agnostic
+
+This standard codifies language-agnostic principles for writing safer code across bassclef's supported stacks (TypeScript, Python, Ruby, Java, Go, bash). It is the substrate-internal companion to the Saltzer & Schroeder luminary — the luminary names WHY each principle matters at the protection-mechanism design level; this standard names WHAT the principle looks like in source code.
+
+## Why this standard exists
+
+Bassclef's `.claude/rules/security.md` is scoped to web-application source files (`.ts`, `.tsx`, `.json`, `.env`, `Dockerfile`). It catches the OWASP-top-10 surface for the web layer. It does not cover:
+
+- Bash hooks (bassclef's own implementation language for `.claude/hooks/*.sh`)
+- Backend daemons (Python, Go, Java, Ruby — any language an adopter ships)
+- Code review of cross-cutting concerns (default-behavior choices, scope choices, override-path design)
+
+The principles in this standard apply to ALL six languages because they are about the *shape* of code, not language-specific syntax. The downstream stack-specific guides (Phase X-3 `bash-hook-safety.md`; Phase Y reference configs per stack) instantiate these principles in the language idiom of the day.
+
+## Anchor luminary
+
+`@luminary saltzer-schroeder` is the authority. Their 1975 paper articulated the 8 principles for protection-mechanism design that this standard implements at the source-code level.
+
+INSTEAD of inventing bassclef-specific principles: this standard maps Saltzer & Schroeder's 8 principles into 6 source-code disciplines that any language can express. The 1975 framing predates every modern attack class and still holds.
+
+## The six source-code disciplines
+
+### 1. Validate at boundaries
+
+Every value entering the system from an external source must be validated at the boundary. After validation, internal code treats the value as trusted.
+
+INSTEAD of validating at every call site: validate once at the entry boundary; pass typed values to internal code that trusts them.
+
+**Boundaries to validate at:**
+
+- HTTP request handlers (parse + validate body, query, headers, path params before any business logic)
+- CLI argument parsers (validate flag values before dispatch)
+- File parsers (validate schema/structure before consuming content)
+- Foreign-key dereferences across service boundaries (validate the referenced object's shape before use)
+- Environment variable reads at process startup (validate types + ranges before runtime use)
+
+**Per language idiom:**
+
+| Stack | Validation primitive |
+|---|---|
+| TypeScript | Zod / Yup / io-ts schema at handler entry |
+| Python | Pydantic model at handler entry; argparse with custom types for CLI |
+| Ruby | dry-validation or ActiveModel validation at controller boundary |
+| Java | Jakarta Bean Validation (JSR 380) annotations; manual validators for non-bean inputs |
+| Go | github.com/go-playground/validator at handler entry; validate.Var for ad-hoc |
+| Bash | argparse-style validation in helper functions; `[[ -n "${var:?}" ]]` for required values |
+
+### 2. Fail-safe defaults
+
+Default behavior denies / refuses / rejects unless an explicit signal permits. The author of a new code path is forced to make the permission decision visible.
+
+INSTEAD of "permit by default, deny on exclusion list": deny by default, permit on explicit allowlist. The allowlist makes new permissions visible; the exclusion list makes new denials invisible.
+
+**Examples by domain:**
+
+- **HTTP routes** — middleware denies all paths by default; routes opt in via explicit definitions. Catch-all 404 vs catch-all 200.
+- **Feature flags** — new flag defaults to OFF; opt-in turns on. INSTEAD of new flag default ON (silently activating in every environment).
+- **CORS** — empty origin list rejects; explicit origins permit. INSTEAD of `*` wildcard.
+- **DB row visibility** — multi-tenant query starts with tenant filter; opt in to cross-tenant only with explicit annotation. INSTEAD of unfiltered base query + per-call tenant filter (easy to forget).
+- **Bash auto-save** — refuse all branches; allowlist enables. INSTEAD of allow all branches; refuse list excludes (PR #1058 anti-pattern).
+
+### 3. Least privilege
+
+Each operation runs with the minimum privileges needed to complete its job. Tokens, credentials, file modes, network access, database permissions — all scoped to the narrowest grant.
+
+INSTEAD of granting broad permissions because tightening is annoying: grant narrow permissions at creation; broaden only with explicit justification.
+
+**Per language idiom:**
+
+| Stack | Least-privilege primitive |
+|---|---|
+| TypeScript | scoped Prisma client / scoped fetch credentials / scoped GitHub PAT |
+| Python | scoped boto3 IAM roles; scoped requests session with restricted cookies |
+| Ruby | scoped ActiveRecord connection pool per concern; scoped Net::HTTP credentials |
+| Java | scoped JDBC connection with role-based grants; scoped HttpClient TLS config |
+| Go | scoped HTTP client; scoped database/sql DSN per role |
+| Bash | `--scope=<minimum>` flags on every CLI; `sudo` disallowed by default; file modes 644/755 by default |
+
+Token discipline (per memory `feedback_never_paste_tokens_in_chat`) is least privilege applied to authentication.
+INSTEAD of broad-org admin tokens: fine-grained PATs scoped to a single target repo + minimum permission set. INSTEAD of pasting credential values into any chat / log / commit: reference credentials by environment-variable name only.
+
+### 4. Complete mediation
+
+Every access to every protected resource passes through the protection mechanism. There are no "trusted" internal paths that skip the check.
+
+INSTEAD of checking authorization at the boundary and trusting internal callers: check at every access point. The cost of one extra check is small; the cost of one missed check can be the whole system.
+
+**Examples by domain:**
+
+- **DB queries** — Row-level security at the database is complete mediation; ORM-side filters are bypass-able if a caller uses raw SQL
+- **HTTP middleware** — Apply auth middleware to a route group; selective-skip is a security bug.
+  INSTEAD of allowing per-route opt-out: route groups are the granularity; new routes inherit the middleware.
+- **Tenant filtering** — Filter at the query builder layer (every query inherits); not at the controller layer (controllers can forget).
+  INSTEAD of controller-layer filtering: query-builder-layer filtering so the tenant context is structurally inseparable from every query.
+- **File access** — Mediate via accessor functions that include the check; raw file handles bypass the check.
+  INSTEAD of granting raw handles for performance: accessor functions own the read/write surface; performance optimization lives inside the accessor.
+- **Bash hook PreToolUse** — Hook fires on every matching tool call, not "first call per session"
+
+### 5. Defense in depth
+
+Multiple independent layers protect the same resource. A single compromise of one layer leaves the resource still protected by the others.
+
+INSTEAD of relying on one strong layer: stack multiple layers, each cheap, with no single layer load-bearing.
+
+**Example stack for bassclef production deploys:**
+
+1. GitHub Environment with `required_reviewers` (separation of privilege)
+2. `deploy-guard.sh` hook BLOCKs without explicit `DEPLOY_PROD=1` env var
+3. `gh pr merge` requires operator account (not agent token)
+4. CI passing gate (test + build + lint + security scan)
+5. Manual smoke-test acknowledgement before traffic shift
+
+Five layers. Compromise of any one (e.g., agent token leaked) still leaves four layers protecting the deploy.
+
+INSTEAD of "we have CI, that's enough": every layer is cheap; every layer catches a different failure class.
+
+### 6. Audit at every layer
+
+Every state-modifying action emits an audit record. The record names: who, what, when, from where, with what authority.
+
+INSTEAD of audit-only-on-failure: audit on every state change so post-incident reconstruction has the data it needs.
+
+**Per language idiom:**
+
+| Stack | Audit primitive |
+|---|---|
+| TypeScript | structured logger (pino, winston) + trace ID at handler entry |
+| Python | structlog or loguru + trace ID; opentelemetry for cross-service |
+| Ruby | structured Rails logger + Lograge; trace ID via request middleware |
+| Java | SLF4J + Logback structured layout; OpenTelemetry tracer |
+| Go | zap or zerolog + trace context; OpenTelemetry SDK |
+| Bash | `trace-helper.sh` writes JSONL to `.claude/state/traces/<session>.jsonl` |
+
+Bassclef's `lib/trace-helper.sh` is the substrate's audit primitive for bash. Every hook fires `trace_record <hook> <verb> <context>` before exit. Override usage (e.g., `SKIP_*=1`) is logged automatically.
+
+## What this standard does NOT do
+
+- **Does not specify cryptographic primitives** — algorithm choice, key length, library selection are out of scope. Use the language's standard library + vetted cryptography library (e.g., libsodium binding, Bouncy Castle).
+- **Does not catalog OWASP top-10 mitigations** — `.claude/rules/security.md` covers the web layer; this standard covers the substrate-internal layer that the web layer rests on.
+- **Does not replace `/security-review`** — that skill applies these principles to a specific PR. This standard is the reference the skill cites.
+- **Does not specify threat models** — Schneier-anchored threat-thinking is a separate luminary candidate (deferred per Phase X+Y+Z bet's Out of scope).
+
+## When this standard fires
+
+| Surface | What to check |
+|---|---|
+| New HTTP handler / route | Boundary validation present? Default behavior fail-safe? |
+| New bash hook | All 8 principles via stack-translation table in `saltzer-schroeder.md` |
+| New CLI tool | Argument validation? Least-privilege credential scope? |
+| New cross-service call | Validation on the response? Audit emit at call site? |
+| Schema migration | Defense in depth via review + dry-run + rollback? |
+| Code review | All 6 disciplines applied? |
+
+## Refs
+
+- `@luminary saltzer-schroeder` — anchor; 8 principles for protection-mechanism design
+- `.claude/rules/security.md` — web-layer rule (`.ts/.tsx/.json/.env/Dockerfile` scope)
+- `.claude/rules/destructive-operations.md` — agent self-assessment companion
+- `standards/bash-hook-safety.md` (Phase X-3) — bash-specific instantiation of these principles
+- `docs/iteration-bets/2026-06-17a-secure-coding-foundations-longrun.md` — goal authoring this standard
+- bassclef#1058 — concrete failure (auto-save scope hole) that motivated this standard
+
+## Composes with
+
+- `standards/destructive-operations.md` style → `.claude/rules/destructive-operations.md` (agent self-assessment)
+- `standards/bassclef-configs-schema.md` § Security scanning (Phase Y-2) — adopter-facing scanner-adapter config
+- `standards/security-scanner-adapter.md` (Phase Y-1) — adapter pattern that uses scanner outputs to enforce these disciplines
+
+## Retirement
+
+This standard retires only if Saltzer & Schroeder's principles are superseded by a fundamentally different protection-mechanism framework. The 8 principles have held for 50 years; retirement is not a near-term concern. The stack-translation tables evolve as bassclef adds support for new languages.

package/substrate/standards/composer-prerequisites.md

@@ -0,0 +1,155 @@
+---
+tier: lite
+description: Composer skills (/preview-build, /build, /shape full, future multi-skill chains) require certain prerequisites to dispatch safely.
+---
+
+# Composer Prerequisites
+
+Composer skills (`/preview-build`, `/build`, `/shape full`, future
+multi-skill chains) require certain prerequisites to dispatch safely.
+This standard documents the **6 bassclef pre-flight checks**, the
+**auto-prep policy**, and the **signal-and-offer pattern** for
+operator-decisions.
+
+Implementation: `lib/composer-preflight.sh`. Per bassclef#408 (scaffold) + bassclef#449/#450 (deploy-host check).
+
+## Why this exists
+
+Before this standard: composer skills dispatched optimistically and
+failed LATE inside their procedure when prerequisites weren't met.
+Operator typed the dispatch, watched 5+ sequential errors surface,
+manually prepped each, re-dispatched. Friction tax × 5.
+
+After this standard: one Phase -1 pre-flight surface lists all
+prerequisites at once. Auto-prep where mechanical and safe.
+Signal-and-offer where operator-decisions. Refuses (with clear
+instruction) where blocking.
+
+## The 6 checks
+
+| # | Check | Pass condition | Failure handling |
+|---|-------|---------------|-------------------|
+| 1 | **feature-branch** | repo on `feature/*` (or `fix/*`, `spike/*`) branch | refuses on main/master; instructs `git checkout -b feature/<slug>` |
+| 2 | **state-spine** | `lib/state.sh` present in repo | auto-prep available from `$BASSCLEF_DIR/lib/state.sh`; falls back to refuse + /onboard-repo recommendation |
+| 3 | **personas** | ≥1 persona at `docs/personas/*.md` | warn + offer `/personas` dispatch; composers may proceed with operator-as-persona |
+| 4 | **budget** | `iteration_ceiling` (from `substrate.config.md`) ≥ estimated `turns × $0.10` | warn + offer ceiling bump in `substrate.config.md`; sequential mode ($0 burst) passes silently |
+| 5 | **skill-registry** | dispatching skill resolves at `~/.claude/skills/<name>/SKILL.md` (user-level symlink) | warn if only at repo-level (bassclef#271 race); refuse if missing entirely |
+| 6 | **deploy-host** | `hosting_platform` set in `substrate.config.md` AND adapter shipped | refuses on missing/unset; refuses on `none` unless `--no-launch` flag passed; warn on in-enum-but-adapter-not-shipped (vercel/netlify/cf-pages) — closes preview→production gap (bassclef#449/#450) |
+
+### Check 6 — `--no-launch` mode
+
+Composers receive an optional `--no-launch` flag. When passed, Check 6
+short-circuits to pass with message "variants-only run" — used when the
+dispatch is purely for design exploration (e.g., `/preview light` or
+`/preview-build` invoked without `/launch-preview` chaining). Default is
+full chain (deploy-host required). The flag is logged in pre-flight
+output for audit.
+
+## Auto-prep policy
+
+**Auto-prep is allowed ONLY when ALL of:**
+
+1. The action is mechanical (no operator-judgment input needed)
+2. The action is safe (no destructive side-effects, no hidden state changes)
+3. The action is reversible (operator can `git diff` to see exactly what changed)
+4. The action is documented in this standard (no hidden auto-prep paths)
+
+**Today the only auto-prep path is `lib/state.sh` bootstrap from
+bassclef** (mechanical: `cp $BASSCLEF_DIR/lib/state.sh
+$REPO/lib/state.sh`; safe: read-only template; reversible: standard
+git diff).
+
+**Forbidden auto-prep** (always operator-decision):
+
+- Auto-branch creation (operator chooses naming + scope)
+- Auto-budget changes (operator-economic decision)
+- Auto-persona seeding (operator describes WHO; substrate fills shape)
+- Auto-skill-registry recovery (operator reviews bassclef-sync output)
+
+## Signal-and-offer pattern
+
+For operator-decisions where the prerequisite isn't met, the composer:
+
+1. **Signals** the gap clearly in the pre-flight surface
+2. **Offers** a one-line action the operator can take
+3. **Continues** if the operator confirms proceed (warn-tier) OR refuses if the gap is hard-block (fail-tier)
+
+Example surface:
+
+```
+⚠️  budget   iteration_ceiling $5 < estimated $8 (80 turns)
+    └─ recommendation: Bump iteration_ceiling in substrate.config.md OR reduce composer tier
+```
+
+Operator decides:
+- Bump ceiling → re-dispatch
+- Use lower tier (`/preview-build medium` instead of `full`) → re-dispatch
+- Proceed anyway (operator accepts overage risk) → composer proceeds with explicit acknowledgment
+
+## When pre-flight fires
+
+Phase -1 of the composer's procedure, BEFORE Phase 0:
+
+```
+PHASE -1: Pre-flight check (NEW, per bassclef#408)
+  source $BASSCLEF_DIR/lib/composer-preflight.sh
+  composer_preflight_check <skill> <estimated_turns> | composer_preflight_render <skill>
+
+PHASE 0: Existing composer setup
+  ...
+```
+
+If pre-flight returns `0` (all pass) → continue to Phase 0.
+If pre-flight returns `1` (warnings) → composer surfaces warnings + asks operator proceed/abort.
+If pre-flight returns `2` (failures) → composer refuses dispatch + exits.
+
+## Override
+
+Per-call: `SKIP_COMPOSER_PREFLIGHT=1 <command>` (logged via trace-helper).
+
+Use sparingly. Override defeats the purpose; intended only for:
+- Substrate-defect rescue (preflight itself broken)
+- Operator-explicit "I know what I'm doing this once"
+- Migration scripts that bootstrap state in odd shapes
+
+NOT for:
+- Routine work that fails preflight ("I'll fix the ceiling later")
+- Automated CI dispatches (those should pre-prep, not bypass)
+
+## Composer integration checklist
+
+When adding pre-flight to a new composer skill:
+
+1. Add Phase -1 to skill's procedure (before Phase 0)
+2. Source the helper: `source $BASSCLEF_DIR/lib/composer-preflight.sh`
+3. Call `composer_preflight_check <skill_name> <estimated_turns>`
+4. Pipe through `composer_preflight_render` for operator surface
+5. Branch on exit code (0 / 1 / 2) per the table above
+6. Document `--skip-preflight` in skill's args reference
+7. Test the integration (positive + negative cases)
+
+## Composes with
+
+- `lib/composer-preflight.sh` — implementation
+- `.claude/rules/sdlc-gates.md` — pre-build gates (existing)
+- `.claude/rules/blocked-items.md` — refuse + signal pattern (existing)
+- `.claude/rules/destructive-operations.md` — auto-prep safety pattern
+- bassclef#271 — skill-registry race (detected by check 5)
+- bassclef#382 — substrate-clarity-gate (sibling write-time gate)
+- bassclef#400 — friction-check (sibling post-skill gate)
+
+## What this standard does NOT cover
+
+- Pre-flight for `/longrun prep` (already exists in skill itself; this standard doesn't extend)
+- Pre-flight for single-skill dispatches (`/value-prop`, `/kiss`, `/verify`) — overhead exceeds value
+- Mid-composer prerequisites (e.g., spec validation between skills) — different surface; covered by composer's internal Phase 0+ logic
+- Production deploy gates (`/deploy-prod` has its own approval surface)
+
+## Sources
+
+- bassclef#408 — the bassclef-evolution proposal this standard closes
+- bassclef#400 scenario test (TwoDo /preview-build full surfaced 5 unmet prereqs)
+- bassclef#271 — skill-registry race (check 5 detects)
+- `lib/composer-preflight.sh` — the implementation
+- `.claude/skills/longrun/SKILL.md` — existing pre-flight pattern (mirrors)
+- `.claude/skills/autonomous/SKILL.md` — existing pre-flight pattern (mirrors)

package/substrate/standards/dependency-discipline/cargo.md

@@ -0,0 +1,39 @@
+---
+tier: lite
+description: The Rust package-manager sibling of .claude/rules/new-dependency-check.md.
+---
+
+# cargo — dependency discipline
+
+The Rust package-manager sibling of `.claude/rules/new-dependency-check.md`. Loads when adopter's `tech_stack.pkg_manager` is `cargo`.
+
+## Per-PM checks (beyond the universal concerns)
+
+1. **MSRV (Minimum Supported Rust Version)** — does the package's MSRV align with the adopter's Rust version? Bumping Rust to take a new crate is a real cost; check `rust-version` in the crate's Cargo.toml.
+2. **`no_std` compatibility** — for embedded / WASM / kernel use cases, does the crate work without the standard library? Check for `#![no_std]` support in the crate's docs.
+3. **Feature flags** — Rust crates often ship optional features. Default features may pull in heavy transitive deps (e.g., `tokio` with full features). Audit `default-features` and explicitly select features you need.
+4. **Unsafe code surface** — does the crate use `unsafe`? For security-critical paths, prefer crates audited by `cargo-audit` or that publish via `cargo-geiger` reports.
+5. **Compile time** — Rust compile is slow; popular crates with heavy macros (serde, diesel) compound. Check existing Cargo.lock for already-pulled-in deps before adding a new heavyweight.
+
+## Lockfile + reproducibility
+
+- **Cargo.lock** — always check in for binaries; library crates traditionally don't, though modern practice is moving toward checking in for libraries too (reproducible builds).
+
+## Approved Dependencies list location
+
+Each adopter repo maintains its own. Typical locations:
+- `CLAUDE.md` § "Approved Dependencies"
+- `standards/approved-dependencies.md`
+- `Cargo.toml` `[dependencies]` (Rust adopters; the manifest IS the approved list)
+
+## Process specifics
+
+1. State the package name and why.
+2. Run the 5 universal concerns from `new-dependency-check.md`.
+3. Run the 5 per-PM checks above.
+4. Run `cargo add <pkg>` (or `cargo add <pkg> --no-default-features --features ...` for feature selection).
+5. Use `[dev-dependencies]` for build-time-only deps (testing, benchmarking).
+
+## Sources
+
+- Adapted from operator's npm-rule shape; Rust ecosystem specifics from cargo book + RustSec + cargo-audit.

package/substrate/standards/dependency-discipline/gem.md

@@ -0,0 +1,43 @@
+---
+tier: lite
+description: The Ruby package-manager sibling of .claude/rules/new-dependency-check.md.
+---
+
+# gem (Bundler) — dependency discipline
+
+The Ruby package-manager sibling of `.claude/rules/new-dependency-check.md`. Loads when adopter's `tech_stack.pkg_manager` is `gem`.
+
+## Per-PM checks (beyond the universal concerns)
+
+1. **Ruby-version compatibility** — does the gem support the adopter's Ruby version? Check `required_ruby_version` in the gem's gemspec.
+2. **Rails-version compatibility** (if applicable) — does the gem support the adopter's Rails major.minor? Gems that lag behind Rails majors are maintenance debt; gems that lead may break.
+3. **C extension** — does the gem include native code (e.g., `nokogiri`, `pg`)? Installation requires platform-specific build tools; multi-platform deployments need precompiled gems or build-env parity.
+4. **Test-mode side effects** — some gems modify global state on require (e.g., monkey-patching standard library, registering autoloaders). Audit for surprise behavior in test isolation.
+5. **License compatibility** — Ruby gems are heterogeneous on license (MIT / Apache / BSD / GPL / proprietary). Audit for compatibility with the adopter's license posture.
+
+## Lockfile + reproducibility
+
+- **Gemfile.lock** — always check in. Bundler resolves deterministically from the lockfile.
+- **Gemfile** — production vs development vs test groups must be explicit; ungrouped gems install in every environment.
+
+## Approved Dependencies list location
+
+Each adopter repo maintains its own. Typical locations:
+- `CLAUDE.md` § "Approved Dependencies"
+- `standards/approved-dependencies.md`
+- `Gemfile` (Ruby adopters; the manifest IS the approved list, grouped by environment)
+
+## Process specifics
+
+1. State the gem name and why.
+2. Run the 5 universal concerns from `new-dependency-check.md`.
+3. Run the 5 per-PM checks above.
+4. Add to `Gemfile`:
+   - `gem '<name>'` for production
+   - `gem '<name>', group: :development` for dev-only
+   - `gem '<name>', group: :test` for test-only
+5. Run `bundle install` to resolve + update Gemfile.lock.
+
+## Sources
+
+- Adapted from operator's npm-rule shape; Ruby ecosystem specifics from Bundler docs + rubygems.org.

package/substrate/standards/dependency-discipline/go-mod.md

@@ -0,0 +1,41 @@
+---
+tier: lite
+description: The Go package-manager sibling of .claude/rules/new-dependency-check.md.
+---
+
+# go-mod — dependency discipline
+
+The Go package-manager sibling of `.claude/rules/new-dependency-check.md`. Loads when adopter's `tech_stack.pkg_manager` is `go-mod`.
+
+## Per-PM checks (beyond the universal concerns)
+
+1. **Go-version compatibility** — does the module's `go.mod` require a newer Go than the adopter? Bumping Go is a real cost; check `go` directive in the module's go.mod.
+2. **Module path stability** — has the module gone through v2+ migrations (the `/v2`, `/v3` suffix dance)? Lock to a stable major; pre-1.0 modules can break minor-version contracts.
+3. **Standard library coverage** — Go's stdlib is rich. Many "obvious" dependency candidates (JSON, HTTP server, logging, crypto, file I/O) are already in stdlib. Check before adding.
+4. **Vendor vs proxy** — `vendor/` directory pins sources in the repo (fully reproducible, large repo); `GOPROXY` relies on external availability. Adopter picks; sibling notes the trade-off.
+5. **CGo usage** — does the module call C code? CGo breaks cross-compilation and complicates Docker multi-stage builds. Pure-Go alternatives often exist; prefer them.
+
+## Lockfile + reproducibility
+
+- **go.sum** — checksums for every module + dependency. Always check in.
+- **go.mod** — explicit declaration of direct dependencies; transitive deps live in go.sum.
+
+## Approved Dependencies list location
+
+Each adopter repo maintains its own. Typical locations:
+- `CLAUDE.md` § "Approved Dependencies"
+- `standards/approved-dependencies.md`
+- `go.mod` `require` block (Go adopters; the manifest IS the approved list)
+
+## Process specifics
+
+1. State the module path and why.
+2. Run the 5 universal concerns from `new-dependency-check.md`.
+3. Run the 5 per-PM checks above.
+4. Run `go get <module>@<version>` to add + pin.
+5. Run `go mod tidy` to clean up unused deps + update go.sum.
+6. Test deps go in `_test.go` files via `import` — no separate dev-dep grouping in Go.
+
+## Sources
+
+- Adapted from operator's npm-rule shape; Go ecosystem specifics from Go modules reference + golang.org/ref/mod.

package/substrate/standards/dependency-discipline/npm.md

@@ -0,0 +1,42 @@
+---
+tier: lite
+description: The Node.js package-manager sibling of .claude/rules/new-dependency-check.md.
+---
+
+# npm / pnpm / yarn — dependency discipline
+
+The Node.js package-manager sibling of `.claude/rules/new-dependency-check.md`. Loads when adopter's `tech_stack.pkg_manager` is `npm`, `pnpm`, or `yarn`.
+
+## Per-PM checks (beyond the universal concerns)
+
+1. **Stack compatibility** — does it work with the adopter's framework (Next.js / Vite / Remix / SvelteKit / etc.), TypeScript strict mode, and container build?
+2. **Bundle impact** — check [bundlephobia.com](https://bundlephobia.com) for client-side packages. Anything over 50KB minified+gzipped warrants justification. Server-only packages bypass this check.
+3. **SSR compatibility** — does the package use `window`, `document`, `localStorage`, or other browser-only APIs? Client-only libraries need `"use client"` directive (Next.js App Router) plus lazy loading via `next/dynamic` or equivalent. Server components silently fail when client-only APIs leak through.
+4. **Type definitions** — does the package ship its own TypeScript types? If not, is there a `@types/*` package? Untyped JS dependencies degrade TS strict-mode value.
+5. **Lockfile alignment** — adopter using pnpm? Use `pnpm add`, not `npm install`. Mixed package managers corrupt lockfiles and produce non-reproducible installs.
+
+## Approved Dependencies list location
+
+Each adopter repo maintains its own. Typical locations:
+- `CLAUDE.md` § "Approved Dependencies"
+- `standards/approved-dependencies.md`
+- `docs/dependencies.md`
+
+After installing a new package, add it to the list with a one-line rationale.
+
+## Process specifics
+
+1. State the package name and why.
+2. Run the 5 universal concerns from `new-dependency-check.md`.
+3. Run the 5 per-PM checks above.
+4. Run the appropriate install:
+   - `npm install <pkg>` (npm)
+   - `pnpm add <pkg>` (pnpm)
+   - `yarn add <pkg>` (yarn)
+5. Use `--save-dev` (npm/yarn) or `-D` (pnpm) for build-time-only dependencies (testing, linting, types).
+6. Add to the Approved Dependencies list.
+
+## Sources
+
+- Original `new-dependency-check.md` content authored against npm (operator stack).
+- This sibling preserves the npm-specific specifics that don't apply to other ecosystems (bundlephobia, SSR, "use client", @types/*).

package/substrate/standards/dependency-discipline/pip.md

@@ -0,0 +1,42 @@
+---
+tier: lite
+description: The Python package-manager sibling of .claude/rules/new-dependency-check.md.
+---
+
+# pip / poetry — dependency discipline
+
+The Python package-manager sibling of `.claude/rules/new-dependency-check.md`. Loads when adopter's `tech_stack.pkg_manager` is `pip` or `poetry`.
+
+## Per-PM checks (beyond the universal concerns)
+
+1. **Python-version compatibility** — does the package support the adopter's Python version? Many packages drop old Pythons quickly; some require minimum versions (e.g., 3.10+ for newer typing features).
+2. **C extension / binary wheels** — does the package include native code? If yes, what platforms ship wheels (manylinux, macOS arm64, Windows)? Source-only installs fail without build tools.
+3. **Dependency tree depth** — a dependency that pulls in 50 transitive deps is a maintenance liability. Inspect with `pip show <pkg>` or `poetry show --tree <pkg>`.
+4. **Async / sync model** — does the package match the adopter's runtime model? Sync packages in an async app block the event loop; async packages in a sync app force conversion ceremony.
+5. **Type stubs** — does the package ship `py.typed` marker (PEP 561)? If not, is there a `types-*` stub on PyPI? Untyped deps degrade mypy / pyright strict-mode value.
+
+## Lockfile + reproducibility
+
+- **pip** — `requirements.txt` + `pip freeze` is brittle; consider `pip-tools` (`pip-compile`) to pin transitive deps deterministically.
+- **poetry** — `poetry.lock` is the bassclef lockfile; check it into version control.
+
+## Approved Dependencies list location
+
+Each adopter repo maintains its own. Typical locations:
+- `CLAUDE.md` § "Approved Dependencies"
+- `standards/approved-dependencies.md`
+- `pyproject.toml` (poetry adopters; the dependencies list IS the approved list)
+
+## Process specifics
+
+1. State the package name and why.
+2. Run the 5 universal concerns from `new-dependency-check.md`.
+3. Run the 5 per-PM checks above.
+4. Run the appropriate install:
+   - `pip install <pkg>` + update `requirements.txt`
+   - `poetry add <pkg>`
+5. Use `--dev` (poetry) or a separate `requirements-dev.txt` (pip) for build-time-only dependencies (testing, linting, stubs).
+
+## Sources
+
+- Adapted from operator's npm-rule shape; Python ecosystem specifics from PyPA + PEP 561 + poetry docs.