@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/standards/composer-prerequisites.md

@@ -1,155 +0,0 @@
----
-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/deferred-actions-schema.md

@@ -1,204 +0,0 @@
----
-tier: lite
-description: Standard for docs/deferred-actions/*.md entries — the capability-routed handoff primitive that carries deferred work across session modalities.
----
-
-# Deferred Actions Schema
-
-Standard for `docs/deferred-actions/*.md` entries — the capability-routed
-handoff primitive that carries deferred work across session modalities.
-
-Any session whose capabilities don't satisfy a pending action writes an
-entry. Any capable future session picks it up at session-start via
-`.claude/hooks/session-reflection.d/60-deferred-actions.sh`.
-
-## Why this exists
-
-Sessions have different capability surfaces (desktop, mobile-ephemeral,
-cloud-web, CI). Work produced in one environment may not be deliverable
-from that environment — a mobile session can compose a release-notes
-addendum but cannot push it to Google Docs (no service-account key);
-an abruptly-stopped session has pending artifacts but no chance to
-push them.
-
-Without this handoff, that work silently drops. With it, the next
-capable session sees a `BLOCKED:` entry and resolves it inline with
-the existing blocked-items protocol.
-
-## File location
-
-```
-docs/deferred-actions/
-├── README.md
-├── <ISO-ts>-<slug>.md          # pending entries
-└── completed/
-    └── <ISO-ts>-<slug>.md      # git mv'd here on resolution (audit trail)
-```
-
-Entries live flat under `docs/deferred-actions/`. On completion, the
-session that resolves the entry runs `git mv` to `completed/` as the
-audit record. The file name never changes, so history tracks the same
-file across the move.
-
-## Frontmatter schema
-
-Every entry starts with YAML frontmatter. Required fields are enforced
-by the scan hook; missing required fields cause the entry to surface as
-`MALFORMED:` with a pointer to this standard.
-
-```yaml
----
-id: <ISO-ts>-<slug>
-created_by_session: <chronicle-slug-or-session-id>
-created_in: desktop | ephemeral-mobile | ephemeral-ci | cloud-web
-created_at: <ISO-8601 timestamp, UTC>
-pending_action: <slug describing the action>
-requires_capability: [<cap>, <cap>, ...]
-priority: high | medium | low
-origin_skill: /<skill-name>
-resolves_when: |
-  <multi-line description of what "done" looks like>
----
-```
-
-### Field reference
-
-| Field | Required | Notes |
-|-------|----------|-------|
-| `id` | yes | Human-readable slug matching the filename (without `.md`). Pattern: `YYYY-MM-DDTHH-MM-SSZ-<slug>`. Dashes in the timestamp portion to keep it filesystem-safe. |
-| `created_by_session` | yes | Chronicle filename (without `.md`) when available; otherwise a session identifier that future readers can trace. |
-| `created_in` | yes | Modality vocabulary — one of `desktop`, `ephemeral-mobile`, `ephemeral-ci`, `cloud-web`. Extend vocabulary by adding rows to the modality table below, not by inventing values inline. |
-| `created_at` | yes | ISO-8601 UTC timestamp. Used by the scan hook to sort entries by age for surfacing. |
-| `pending_action` | yes | Slug describing what needs to happen. Not free-form prose — a reviewable verb phrase. Examples: `push-release-notes-to-gdoc`, `write-retroactive-version-tag`, `apply-memory-proposal`. |
-| `requires_capability` | yes | List of capability tokens (vocabulary below). Session-start hook compares to current modality's capabilities; match → `BLOCKED:`, miss → `INFORM:`. |
-| `priority` | yes | `high` / `medium` / `low`. Surfaces sort order + operator attention. Reserve `high` for integrity-critical (missing chronicle, lost memory proposal). |
-| `origin_skill` | yes | Slash-command name of the skill that created the entry (e.g., `/release-notes`). Lets the session resuming the work re-enter the same skill with context. |
-| `resolves_when` | yes | Plain-language description of the end state. Not a checklist — one or two sentences the resolver can match against. |
-
-## Capability vocabulary
-
-Stable set. Extend via this standard, not by inventing tokens inline.
-
-| Capability | Meaning |
-|------------|---------|
-| `gcloud-auth` | Session can authenticate to Google Cloud (SA key at `~/.config/gcloud/sunjay-google-ops.json`). Needed for Google Docs push. |
-| `google-docs-write` | Session has network + credentials to write to Google Docs. Composite — requires `gcloud-auth` + `network`. |
-| `gh-auth` | `gh` CLI installed + authenticated in this session. |
-| `git-push` | Session can push commits to remote (SSH keys or HTTPS PAT present). |
-| `git-tag` | Session can create + push annotated tags. Superset of `git-push`. |
-| `network` | Session has outbound internet access. Ephemeral sandboxes may not. |
-| `memory-write` | Session can write to `~/.claude/projects/.../memory/`. Ephemeral sandboxes cannot. |
-| `npm-install` | Session has npm + network to install packages. |
-| `playwright-mcp` | Playwright MCP server configured in settings — visual review possible. |
-| `docker-socket` | Session can run Docker (some CI runners + most desktops). |
-
-New capabilities require a row here. The scan hook uses this table to
-match entries to sessions — an entry requiring `rhyming-slang-decoder`
-would never resolve because no modality advertises that capability.
-
-## Modality → capability table (reference)
-
-Session-start hook detects modality and synthesizes the capability set.
-Not all modalities are static — a desktop session without `gcloud` auth
-is missing `gcloud-auth` even if its modality generally has it. The
-hook's detection logic (at `60-deferred-actions.sh`) is the source of
-truth; this table is human reference.
-
-| Modality | Typical capabilities |
-|----------|---------------------|
-| `desktop` | `gcloud-auth`, `gh-auth`, `git-push`, `git-tag`, `network`, `memory-write`, `npm-install`, `playwright-mcp` |
-| `ephemeral-mobile` | `gh-auth`, `git-push`, `network` (fine-grained PAT only; no `gcloud`, no `memory-write`) |
-| `ephemeral-ci` | `gh-auth`, `git-push`, `network`, workflow-secret-scoped (may include `google-docs-write` via SA key stored in GH secrets) |
-| `cloud-web` | `network` (limited — no shell, no git, no auth) |
-
-## Priority ladder
-
-| Priority | When to use |
-|----------|-------------|
-| `high` | Integrity-critical: missing chronicle, orphaned memory proposal, data that will be lost if the next session doesn't pick it up. |
-| `medium` | Delivery gaps with a real downstream cost: release notes not pushed to Google Doc (weekly changelog goes stale), LinkedIn draft not published. |
-| `low` | Nice-to-have: metrics refresh, backfill of an ancillary artifact, retroactive tagging. |
-
-Default `medium` if uncertain. Escalate to `high` only when silent drop
-costs more than the cognitive load on the resolver.
-
-## Body sections (in order)
-
-Below the frontmatter, the body uses four sections. Session-reflection
-surfaces frontmatter only; the body is for the resolving session.
-
-```markdown
-## Context
-
-Why the work was deferred (one paragraph). Enough for a resolver who
-wasn't in the original session to understand what's pending and why it
-matters.
-
-## Command to execute
-
-Exact command, env vars, or agent instruction the resolver runs to
-complete the work. Copy-pasteable. If the resolution is multi-step, a
-small checklist. If it requires operator judgment (merge proposal,
-edit memory file), state "operator action" and describe it.
-
-## On completion
-
-What the resolver does after the action succeeds — usually `git mv`
-to `completed/` and any side-effect artifacts (e.g., "commit the push
-log as chronicle footnote").
-
-## Cross-refs
-
-Related PRs, issues, chronicles, memory entries, or other deferred
-actions. Makes the audit trail trivially traceable.
-```
-
-## Lifecycle
-
-1. **Create**: skill or hook detects it can't complete an action, writes
-   the entry using `templates/deferred-action-template.md`,
-   commits it as part of the session's normal artifact flow.
-2. **Surface**: next session-start, `60-deferred-actions.sh` scans
-   `docs/deferred-actions/*.md`, detects current capabilities, and emits
-   `BLOCKED:` (resolvable here) or `INFORM:` (visible, not actionable).
-3. **Resolve**: resolving session follows the entry's "Command to
-   execute" section, verifies "On completion" state.
-4. **Archive**: `git mv docs/deferred-actions/<id>.md docs/deferred-actions/completed/<id>.md`.
-   Commit the move with message `chore: resolve deferred action <id>`.
-
-## Relationship to other rules + standards
-
-- `.claude/rules/deferred-actions.md` — rule governing session-start
-  surfacing + resolution behavior
-- `.claude/rules/blocked-items.md` — generic BLOCKED protocol; deferred
-  actions route through the same "resolve or explicitly defer" path
-- `.claude/rules/mobile-ephemeral-session.md` — modality detection
-  primitives; the scan hook reuses its `$CLAUDE_EPHEMERAL` + heuristic
-  logic
-- `.claude/rules/session-artifacts.md` — chronicle + LinkedIn tier
-  obligations; WS-3's session-rescue writes a deferred-action entry
-  when the Stop hook can't complete these
-- `standards/mobile-ephemeral-session.md` — full standard, informs
-  modality classifications in the capability table
-
-## Extension
-
-- To add a capability: add a row to the capability vocabulary table +
-  update the detection logic in `60-deferred-actions.sh`.
-- To add a modality: add a row to the modality→capability table +
-  update `created_in` vocabulary in the schema.
-- To add a new pending_action type: no schema change needed; the field
-  is free-form slug. If the same action type recurs, update the
-  originating skill's SKILL.md to standardize the slug.
-
-## What this standard is NOT
-
-- Not a task tracker. GitHub issues remain the bassclef task system.
-  Deferred actions are session-to-session handoffs of *already-produced*
-  work that couldn't land.
-- Not an audit log. The `completed/` subdirectory is retention for
-  traceability, not compliance evidence.
-- Not a substitute for `#221`'s workflow-secret SA key path. Once
-  workflow-delivery lands, Google-Doc-push deferrals become rarer.
-  Deferred actions still cover memory proposals, session-rescue, and
-  any future credential-bound action without a workflow fallback.

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

@@ -1,39 +0,0 @@
----
-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

@@ -1,43 +0,0 @@
----
-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

@@ -1,41 +0,0 @@
----
-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

@@ -1,42 +0,0 @@
----
-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

@@ -1,42 +0,0 @@
----
-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.