@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/standards/sdlc-compliance.md

@@ -0,0 +1,286 @@
+---
+tier: lite
+description: "Defines how gate evidence is captured, where it lives, and how it's queried."
+---
+
+# SDLC Compliance Tracking Standard
+
+Defines how gate evidence is captured, where it lives, and how it's queried.
+Replaces the previous trace-log approach (empty action/outcome columns,
+operational problems, now gitignored) with structured compliance data
+embedded in existing artifacts.
+
+---
+
+## Design Decision: Compliance in Chronicles, Not Separate Files
+
+Gate evidence lives **in the chronicle entry**, not in a separate compliance
+report. Rationale:
+
+1. Chronicles already capture what happened — compliance is "did the gates
+   fire during what happened?"
+2. A separate file creates drift — the chronicle says one thing, the
+   compliance report says another
+3. Chronicles are append-only and committed to git — they're auditable
+4. The previous trace-log approach failed because it was a parallel artifact
+   nobody maintained
+
+The trade-off: compliance data is less machine-queryable embedded in
+chronicles than in structured JSON. If machine querying becomes needed,
+extract it from chronicles rather than maintaining a parallel source of truth.
+
+---
+
+## Session Timing Fields
+
+Every chronicle entry includes timing metadata in the frontmatter.
+These fields close the feedback loop between time budget estimates and
+actual session duration, enabling calibration over time.
+
+### Frontmatter timing fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `started_at` | ISO 8601 datetime | SHOULD | Session start — derived from first commit timestamp or conversation start |
+| `ended_at` | ISO 8601 datetime | SHOULD | Session end — current time at chronicle write |
+| `duration_minutes` | integer | SHOULD | Approximate elapsed minutes (ended_at − started_at) |
+| `turns` | integer or `~N` | SHOULD | Approximate conversation turns this session |
+| `closes` | array of strings | MAY | Issues resolved this session, e.g., `["#37", "#42"]` |
+
+All timing fields are optional for backward compatibility — chronicles
+without them are valid historical records. Use `~` prefix for approximate
+values (e.g., `turns: ~40`).
+
+### Deriving timing data
+
+- `started_at`: First commit on the session's work, or conversation start
+  time if available. Approximate is fine — trend data, not billing.
+- `ended_at`: Current timestamp when the chronicle is written.
+- `duration_minutes`: Simple subtraction, rounded to nearest 5 minutes.
+- `turns`: Estimate from conversation length. Exact counting is fragile
+  and not worth the precision.
+
+---
+
+## Gate Evidence Format
+
+Every chronicle entry includes a **Gate Evidence** section after the
+narrative. This section records what gates fired and their outcomes.
+
+```markdown
+## Gate evidence
+
+| Gate | Fired | Evidence | Outcome |
+|------|-------|----------|---------|
+| Temperance | yes | Stated approach before first edit on feature/NNN | Proceeded — scope matched spec |
+| Diagnosis | n/a | Not a fix branch | — |
+| Pre-build spec check | yes | Spec at docs/specs/crm.md, referenced in iteration goal | Current |
+| Tests | yes | 12 unit, 3 integration, all pass | `npm test` exit 0 |
+| Visual review | yes | docs/visual-reviews/2026-04-07-deal-card.md | PASS WITH NOTES |
+| Verify | yes | Ran /verify after each task (3 tasks) | All passed |
+| Architect review | no — not due | Last review: 2026-04-05 (6 commits ago, threshold is 10) | — |
+
+### Gate skip justifications
+- Diagnosis skipped: feature branch, not fix branch (per sdlc-gates rule)
+```
+
+### Required fields
+
+| Field | Description |
+|-------|-------------|
+| Gate | Which gate (from `.claude/rules/sdlc-gates.md`) |
+| Fired | yes / no / n/a (with reason if no or n/a) |
+| Evidence | Where to find proof — file path, commit hash, or inline note |
+| Outcome | Result of the gate check |
+
+### Gate skip justifications
+
+If a gate was skipped, the reason must be stated. Valid reasons:
+
+- **n/a**: Gate doesn't apply (e.g., diagnosis on a feature branch)
+- **Degraded mode**: Infrastructure unavailable (e.g., Playwright MCP missing
+  for visual review) — must note what was done instead
+- **Assessed as trivial**: For diagnosis only — cause was immediately obvious
+  and reproducible. State the cause.
+
+Invalid reasons:
+- "Ran out of time" — gates are non-negotiable
+- "Will do later" — gates fire before commit, not after
+- No reason given — a bare "no" in the Fired column is a compliance failure
+
+---
+
+## Gates to Track
+
+These are the gates defined in `.claude/rules/sdlc-gates.md` and
+`strategy/agent-choreography.md` Section 9:
+
+### Pre-build gates (before writing code)
+
+| Gate | Trigger | Evidence format |
+|------|---------|----------------|
+| Temperance | First edit per branch | "Stated approach: [summary]" |
+| Diagnosis | All fix/ branches | "Is/Is Not completed, root cause: [summary]" or "Assessed as trivial: [cause]" |
+| Spec check | Before Construction | "Spec at [path], current as of [date]" |
+| Issue exists | Before branch creation | "Issue #NNN created/exists" |
+
+### Post-build gates (before committing)
+
+| Gate | Trigger | Evidence format |
+|------|---------|----------------|
+| Tests | Every commit with logic changes | "[N] unit, [M] integration, all pass" |
+| Verify | Every task completion | "Ran /verify — [outcome]" |
+| Visual review | Every UI change | "Report at [path] — [verdict]" |
+| Architect review | Every 10 commits or before launch | "Last review: [date], [N] commits ago" |
+
+### Session gates (phase/session boundaries)
+
+| Gate | Trigger | Evidence format |
+|------|---------|----------------|
+| Chronicle | Phase transition + session end | "Chronicle at [path]" |
+| Checkpoint | Exit conditions per graceful-exit.md | "Checkpoint at .claude/CHECKPOINT.md" |
+| LinkedIn draft | Notable decisions (SHOULD) | "Draft at [path]" or "No notable moments this session" |
+
+---
+
+## Iteration Goal Closeout
+
+When an iteration completes, append a **Closeout** section to the
+iteration goal file. This captures actuals vs time budget and gate compliance
+across the iteration's sessions — the feedback loop that calibrates
+future time budget estimates.
+
+### Closeout format
+
+```markdown
+## Closeout
+
+### Actuals vs appetite
+
+| Metric | Time budget | Actual | Delta |
+|--------|----------|--------|-------|
+| Turns | 40 | 52 | +30% |
+| Duration | ~1 session | 2 sessions (75m + 40m) | +1 session |
+| Issues closed | 3 | 2 | -1 (deferred #NNN) |
+
+### Gate compliance
+
+| Gate | Expected | Fired | Skipped | Notes |
+|------|----------|-------|---------|-------|
+| Temperance | 3 | 3 | 0 | — |
+| Diagnosis | 1 | 1 | 0 | fix branch |
+| Tests | 3 | 2 | 1 | 1 docs-only commit, n/a |
+| Verify | 3 | 3 | 0 | — |
+| Visual review | 0 | 0 | 0 | no UI changes |
+
+### Calibration notes
+
+[What was over/underscoped. Guidance for next similar iteration.
+Example: "Time budget was tight — the extraction script was underscoped.
+Next similar iteration: budget 50 turns."]
+```
+
+### When to write the closeout
+
+- When all acceptance criteria are met (or explicitly deferred)
+- Before writing the final chronicle for the iteration
+- The closeout data comes from the session chronicles' timing fields
+  and gate evidence tables — it's an aggregation, not a separate data source
+
+### Acceptance criteria for closeout
+
+The iteration goal's acceptance criteria checkboxes should be updated
+to reflect actual completion state. Deferred items get a note explaining
+why and a reference to the follow-up issue.
+
+---
+
+## Querying Compliance
+
+### Manual query (current approach)
+
+```bash
+# Find all chronicles with gate evidence
+grep -l "Gate evidence" chronicle/*.md
+
+# Find skipped gates
+grep -A 1 "no —\|no $" chronicle/*.md
+
+# Find visual review failures
+grep "FAIL" chronicle/*.md
+```
+
+### Architect review query
+
+During `/architect-review`, the Architect reads the last 5 chronicles
+and checks:
+
+1. Are all required gates present in each entry?
+2. Are there unexplained skips?
+3. Is there a pattern of degraded mode (infrastructure not available)?
+4. Are gate skip justifications valid?
+
+This is the primary compliance audit mechanism — it runs every 10 commits.
+
+### Future: structured extraction
+
+If machine-queryable compliance becomes needed:
+
+1. Extract gate evidence sections from chronicles into JSON
+2. Script: `scripts/extract-compliance.sh` → `docs/compliance/latest.json`
+3. Run on demand or as part of architect review
+4. The chronicle remains the source of truth; JSON is a derived view
+
+Do not build this until there's a real need. The architect review query
+is sufficient for current scale.
+
+---
+
+## Hook Integration
+
+### Existing hooks that produce gate evidence
+
+| Hook | What it captures | Where |
+|------|-----------------|-------|
+| `pre-build-gate.sh` | Temperance fired, diagnosis fired (fix branches) | Blocks the edit until gate clears |
+| `pre-commit` (if configured) | Tests pass, lint pass | Blocks the commit |
+| `session-end` / Stop hook | Chronicle written, checkpoint written | Fires at session end |
+
+### Agent responsibility
+
+Hooks capture mechanical gates (did the tool run?). The agent captures
+semantic gates (was the outcome meaningful?). Both are needed.
+
+The agent writes the gate evidence table in the chronicle. Hooks provide
+the enforcement that gates fire at all. Neither replaces the other.
+
+---
+
+## Compliance Failures
+
+A compliance failure is a chronicle entry where:
+
+1. A required gate shows "no" without a valid justification
+2. The gate evidence section is missing entirely
+3. Evidence references a file that doesn't exist
+
+### Response to compliance failures
+
+- **At architect review**: Flag the failure, check if it caused actual harm
+  (missed bug, broken deployment, etc.), recommend process fix
+- **At session start**: If the previous chronicle has a compliance failure,
+  note it in the current session's chronicle under "Entry state"
+- **Do NOT retroactively fix chronicles** — they're historical records.
+  Note the gap and prevent recurrence.
+
+---
+
+## Relationship to Other Standards
+
+| Standard | Relationship |
+|----------|-------------|
+| `.claude/rules/sdlc-gates.md` | Defines which gates exist; this standard defines how to track them |
+| `strategy/agent-choreography.md` | Section 9 defines MUST gates; this standard defines evidence format |
+| `standards/graceful-exit.md` | Checkpoint is a tracked gate at session boundaries |
+| `.claude/skills/chronicle/SKILL.md` | Chronicle skill should include gate evidence template |
+| `.claude/skills/architect-review/SKILL.md` | Architect review queries compliance from chronicles |

package/substrate/standards/secrets-lifecycle.md

@@ -0,0 +1,210 @@
+---
+tier: lite
+description: substrate.secrets.md is the single declarative source for secrets/token lifecycle in any bassclef-substrate repo.
+---
+
+# Secrets Lifecycle
+
+`substrate.secrets.md` is the single declarative source for secrets/token
+lifecycle in any bassclef-substrate repo. Schema:
+`standards/state-spine/schemas/substrate-secrets.schema.json`.
+
+## Why this exists
+
+Before this standard: tokens silently expired mid-session. The operator
+hit a 401, then grepped historical chronicles to remember which token,
+where it lives, how to rotate it. Every consumer team reinvented the
+tracking — file in 1Password, sticky note, calendar reminder, none of
+the above.
+
+After this standard: every secret has a tracked expiry, a documented
+rotation procedure, and a session-start hook that surfaces the warning
+weeks before expiry. Friction removed; operational story declarative.
+
+## Why a separate file from `substrate.config.md`
+
+`substrate.config.md` holds external resource *references* (doc IDs,
+URLs, repo refs). `substrate.secrets.md` holds secret *lifecycle*
+(expiry, rotation, health checks). Two different concerns:
+
+- **Privacy posture**: secrets references are sensitive metadata
+  (storage location, expiry windows leak operational structure);
+  config references are public.
+- **Audit lifecycle**: `last_rotated` + `expires_at` need date discipline;
+  config rarely changes.
+- **Read-time consumers**: `scripts/secrets-status.sh` parses secrets;
+  `substrate.config.md` is read by skills/hooks for resource lookup.
+
+Cross-reference: `substrate.config.md` carries a one-line pointer
+("secrets tracked in `substrate.secrets.md`"); `substrate.secrets.md`
+carries a one-line back-pointer.
+
+## File shape
+
+`substrate.secrets.md` uses Shape B (YAML frontmatter + markdown body):
+
+```markdown
+---
+schema_version: v0
+secrets:
+  - name: SLACK_WEBHOOK
+    purpose: posting to bassclef-activity channel
+    storage:
+      type: github_actions_secret
+      reference: SLACK_WEBHOOK
+    rotation_cadence: 1y
+    expires_at: 2026-09-15
+    rotation_procedure: docs/runbooks/rotate-slack-webhook.md
+    alert_threshold_days: 30
+    owner: operator
+    last_rotated: 2025-09-15
+    health_check_command: ""
+---
+
+# Secrets — <repo name>
+
+Lifecycle tracking for external integration credentials.
+See `standards/secrets-lifecycle.md`.
+
+[Optional human-readable notes per secret in body sections.]
+```
+
+## Field reference
+
+| Field | Required | Type | Notes |
+|-------|----------|------|-------|
+| `name` | yes | string | UPPER_SNAKE_CASE. Logical name (env-var convention). NEVER the value. |
+| `purpose` | yes | string | One-line: what does this secret allow? |
+| `storage.type` | yes | enum | `1password \| env \| file \| github_actions_secret \| aws_secrets_manager \| custom` |
+| `storage.reference` | yes | string | How to fetch the value at runtime (shape per type — see below). |
+| `rotation_cadence` | yes | duration \| enum | `1y`, `6mo`, `90d`, `30d` OR `manual` / `on-leak` / `never` |
+| `expires_at` | yes | date \| `never` | ISO 8601 (YYYY-MM-DD) OR `never` (lifetime credential) |
+| `rotation_procedure` | yes | path | Path to runbook (`docs/runbooks/rotate-<name>.md`). Empty string when cadence=`never`. |
+| `alert_threshold_days` | yes | integer \| `n/a` | Days-before-expiry to start surfacing BLOCKED. Use `n/a` for `never`. |
+| `owner` | yes | string | Who rotates. `operator` for solo; team/handle for multi-operator. |
+| `last_rotated` | yes | date \| `unknown` | ISO 8601 OR `unknown` if pre-tracking. |
+| `health_check_command` | no | string | Optional shell command verifying secret is live. Empty string skips. |
+
+## Storage type vocabulary (v0)
+
+Closed enum in v0; extensible via `custom` per consumer.
+
+| Type | Reference shape | Example |
+|------|----------------|---------|
+| `1password` | vault path | `vault://bassclef/anthropic-api-key` |
+| `env` | env var name | `CLOUDFLARE_API_TOKEN` |
+| `file` | absolute path | `~/.poa-gauth.json` |
+| `github_actions_secret` | secret name | `SLACK_WEBHOOK` |
+| `aws_secrets_manager` | ARN or secret id | `arn:aws:secretsmanager:us-east-1:...:secret:my-secret-AbCdEf` |
+| `custom` | free-form (document inline in body) | per-consumer |
+
+## Rotation cadence
+
+ISO 8601 duration OR controlled enum:
+
+- **Duration shorthand**: `1y`, `6mo`, `90d`, `30d`, `1w` (bassclef's friendly form)
+- **Full ISO 8601**: `P1Y`, `P6M`, `P90D` (also accepted)
+- **`manual`**: rotate when notified (e.g., compromise, vendor migration)
+- **`on-leak`**: rotate only on incident; otherwise lifetime
+- **`never`**: lifetime credential (rare; flag for review)
+
+## Expiry tracking
+
+`expires_at` is the hard date the credential becomes invalid. The
+session-start hook (`90-secrets-expiry.sh`) compares `expires_at` to
+today's date and surfaces BLOCKED when within `alert_threshold_days`.
+
+When `expires_at: never` the entry is never alerted; `alert_threshold_days`
+must be `n/a` and `rotation_procedure` may be empty.
+
+After rotation: update both `last_rotated` (to today) AND `expires_at`
+(to the new expiry). The runbook should remind the operator.
+
+## Health checks
+
+`health_check_command` is optional. When set, it's a shell command that
+returns exit code 0 when the secret is live. Used by `secrets-status.sh
+--health-check`. Should reference the env var (not hardcoded value):
+
+```yaml
+health_check_command: "curl -s -H 'x-api-key: $ANTHROPIC_API_KEY' https://api.anthropic.com/v1/models | jq -e '.data'"
+```
+
+For `manual` / `on-leak` / `never` cadences, health checks are still
+useful (verify the credential hasn't been revoked).
+
+## Hard rules
+
+1. **NO secret VALUES.** Only references, expiry dates, rotation procedures,
+   and health-check commands. Values stay in their authoritative storage
+   (1Password / GitHub Actions Secrets / .env / AWS Secrets Manager).
+2. **NO commits of `.env` files**. Use `storage.type=env` with the
+   reference being the env var name; the value lives in a gitignored
+   `.env` consumed at runtime.
+3. **`substrate.secrets.md` is git-tracked.** Its content is
+   non-sensitive metadata. If your storage references leak operational
+   structure (e.g., AWS account IDs you'd rather not publish), use
+   `custom` type with a private reference shape.
+4. **Rotation updates BOTH `last_rotated` AND `expires_at`.** The runbook
+   reminds the operator.
+5. **`alert_threshold_days` matches risk profile.** Webhooks: 30 days.
+   API keys with manual rotation: longer. OAuth refresh tokens: shorter
+   if vendor revokes proactively.
+6. **`~/.config/bassclef/secrets.env` lines MUST use `export VAR=value`
+   format.** When the env adapter writes to that file, plain `VAR=value`
+   sets a shell variable only — bash subprocesses (including every
+   bassclef hook + helper) don't inherit it. `export VAR=value` enters
+   the environment proper and is inherited by every subprocess the
+   shell launches. The env adapter (`scripts/adapters/secrets/env.sh`)
+   enforces this format on writes; `/secrets-bootstrap --repair`
+   retroactively fixes legacy files that lack the prefix
+   (bassclef#976).
+
+## Tooling
+
+| Tool | Purpose |
+|------|---------|
+| `scripts/secrets-status.sh` | Parses `substrate.secrets.md`, prints traffic-light status table, optional `--health-check` flag |
+| `scripts/secrets-bootstrap.sh --repair` | Adds missing `export ` prefix to assignment lines in `~/.config/bassclef/secrets.env`. Creates dated backup. Required when subprocess inheritance breaks (bassclef#976) |
+| `.claude/hooks/session-reflection.d/90-secrets-expiry.sh` | Session-start BLOCKED surface for any secret within `alert_threshold_days` |
+| `templates/secret-rotation-template.md` | Runbook template for new secret rotation procedures |
+
+## Override paths
+
+- **`SKIP_SECRETS_EXPIRY_CHECK=1`**: bypass the session-start hook for
+  one command. Logged to stderr per bassclef idiom.
+- **No `substrate.secrets.md`**: hook is silent (graceful in repos
+  without secrets).
+
+## Migration
+
+For repos adopting this standard:
+
+1. Copy `presence/install/substrate-secrets-template.md` to repo root
+   as `substrate.secrets.md`
+2. Populate one entry per tracked secret (start with the most painful —
+   typically the one that last expired)
+3. Add cross-reference in `substrate.config.md`
+4. Run `bash scripts/secrets-status.sh` to verify schema parses
+5. Commit; the session-start hook activates immediately
+
+## Out of scope (v1+)
+
+- Slack/email cron alerts (v0 surfaces at session start only)
+- AWS Secrets Manager / 1Password programmatic retrieval (v0 uses
+  per-secret `health_check_command`)
+- Storage-type validators (vs per-secret command) — would require
+  bassclef-side implementations per type
+- SOC 2 / ISO 27001 audit-trail integration — rotation log feeding
+  external audit systems
+
+## Composes with
+
+- `standards/substrate-config-schema.md` — sibling standard for
+  references (non-secret)
+- `.claude/rules/substrate-config-schema.md` — agent behavior rule;
+  references-only-by-name discipline applies to secrets too
+- `.claude/rules/manual-prod-approval.md` — sibling
+  infrastructure-rail pattern
+- `.claude/rules/context-engineering.md` — same just-in-time
+  context-surface discipline applied to operator runbook

package/substrate/standards/security-scanner-adapter.md

@@ -0,0 +1,145 @@
+---
+tier: lite
+description: "The adapter pattern that turns bassclef's per-language security defaults into adopter-runnable CI."
+---
+
+# Security Scanner Adapter Standard
+
+The adapter pattern that turns bassclef's per-language security defaults into adopter-runnable CI. This standard is the reference; per-stack reference workflows ship under `config/security-scanners/` (Phase Y-3); `/onboard-repo` writes the stack choice to `.claude/bassclef-configs.jsonc` (Phase Y-4).
+
+## Why this exists
+
+Adopter repos run bassclef's substrate as their development methodology. The substrate has security disciplines (`standards/code-safety-principles.md`, `.claude/rules/security.md`, `standards/bash-hook-safety.md`) but the disciplines need *scanners* to enforce them in adopter CI.
+
+Today's gap: every adopter chooses, installs, and configures their own security scanners. Bassclef has no opinion on which scanners fire for which language. New adopters who do not know the security tool landscape ship with no scanners; experienced adopters duplicate effort across repos.
+
+INSTEAD of per-adopter scanner choice from scratch: bassclef ships per-stack defaults. Adopters declare their stack at onboard time; bassclef wires the default scanners + ships a reference workflow they copy + customize.
+
+## Anchor
+
+`@luminary saltzer-schroeder` — the eight protection-mechanism principles. Scanners are the mechanical enforcement layer for the source-code disciplines.
+
+This standard composes with:
+
+- `standards/code-safety-principles.md` — language-agnostic principles the scanners check
+- `standards/bash-hook-safety.md` — bash-specific discipline; shellcheck is the scanner
+- `standards/bassclef-configs-schema.md` § Security scanning (Phase Y-2) — adopter config surface
+- `standards/deployment-topology.md` — sibling adapter pattern; same shape
+
+## The adapter shape
+
+```
+adopter declares stack → bassclef-configs reads stack → workflow template fires per-stack scanners → scanner output meets discipline gates
+```
+
+Same shape as the deploy-host adapter. Adopter declares the runtime; bassclef ships defaults; adopter customizes per-need.
+
+Three pieces:
+
+1. **Stack declaration** — `.claude/bassclef-configs.jsonc` `security_scanning.stack` field
+2. **Reference workflow** — `config/security-scanners/<stack>.yml` (template the adopter copies)
+3. **Per-stack defaults** — listed in this standard's matrix below
+
+## Stack reference matrix
+
+Six stack values. Six default scanner sets. Adopter copies the reference workflow + adjusts.
+
+| Stack | Default scanners | What they catch |
+|---|---|---|
+| `node-typescript` | eslint-plugin-security + audit-ci + gitleaks | Source: XSS / SQL injection / unsafe regex / weak crypto. Deps: known CVEs. Secrets: leaked tokens. |
+| `python` | bandit + safety + gitleaks | Source: SQL injection / weak crypto / unsafe pickle / shell injection. Deps: known CVEs. Secrets: leaked tokens. |
+| `ruby` | brakeman + bundler-audit + gitleaks | Source: Rails-specific findings (mass-assignment / unsafe redirects / SQL injection). Deps: known CVEs. Secrets: leaked tokens. |
+| `java` | spotbugs-security + dependency-check + gitleaks | Source: deserialization / XXE / unsafe reflection. Deps: known CVEs (OWASP DC). Secrets: leaked tokens. |
+| `go` | gosec + govulncheck + gitleaks | Source: weak crypto / unsafe error handling / SQL injection. Deps: known CVEs. Secrets: leaked tokens. |
+| `custom` | adopter-supplied list | Adopter responsible for choice + coverage |
+
+`gitleaks` appears in every default set because secret detection is stack-agnostic.
+
+`custom` is for adopters with a stack not in the bassclef defaults OR with specific scanner requirements (e.g., commercial Snyk / Veracode / Checkmarx). The adapter pattern allows opt-out without losing the schema discipline.
+
+## Reference workflows
+
+Phase Y-3 ships the first two reference workflows: `config/security-scanners/node-typescript.yml` + `config/security-scanners/python.yml`. Ruby + Java + Go follow per adopter demand.
+
+Each reference workflow:
+
+- Triggers on PR + push to main (matches bassclef-pr-ci.yml pattern)
+- Installs scanners
+- Runs each scanner
+- Outputs findings as PR comments (advisory) AND as workflow status (potential BLOCK)
+- Uses `block_on_high_severity` field from bassclef-configs to decide BLOCK vs advisory
+
+Adopters copy the template to `.github/workflows/security-scan.yml` in their consumer repo + customize.
+
+## How the adopter configures
+
+`.claude/bassclef-configs.jsonc` `security_scanning` block (Phase Y-2):
+
+```jsonc
+{
+  "security_scanning": {
+    // Stack name from the matrix above OR "custom".
+    // null = OFF (no security scanning configured).
+    "stack": "node-typescript",
+
+    // Optional additional scanners (e.g., commercial tools).
+    // Names are advisory; adopter writes their own workflow steps.
+    "additional_scanners": [],
+
+    // Block CI on high-severity findings; advisory-only otherwise.
+    // Recommended: true for production-bound work; false for early
+    // exploratory adopters.
+    "block_on_high_severity": true
+  }
+}
+```
+
+`null` stack means the adopter has not yet configured scanners; `/onboard-repo` will prompt at the next session. After choice, the field stays static — adopter edits it manually OR re-runs `/onboard-repo --reconfigure-security`.
+
+## Stack auto-detection
+
+Phase Y-4 extends `/onboard-repo` with stack auto-detection. Heuristics:
+
+| Signal | Hint |
+|---|---|
+| `package.json` exists + `typescript` or `@types/*` in deps | node-typescript |
+| `package.json` exists + JavaScript only | node-typescript (with TS opt-out) |
+| `requirements.txt` OR `pyproject.toml` OR `setup.py` | python |
+| `Gemfile` OR `*.gemspec` | ruby |
+| `pom.xml` OR `build.gradle` OR `*.java` | java |
+| `go.mod` OR `*.go` | go |
+| Multiple signals OR none | prompt operator + offer `custom` |
+
+INSTEAD of asking the operator to remember the stack name: auto-detect from build files + confirm. The operator overrides if the detection is wrong.
+
+## What this adapter does NOT do
+
+- Does not install scanners on the adopter machine — only generates the CI workflow that installs them per-run
+- Does not maintain the scanner lists (adopters update reference workflows when new tool versions ship)
+- Does not unify scanner output formats — each scanner outputs its native format; the workflow presents per-scanner sections
+- Does not configure scanner-specific rules — adopters edit the reference workflow for per-org tuning
+- Does not replace SAST / DAST commercial tools — the defaults are open-source baselines; adopters add commercial tools via `additional_scanners`
+
+## When this adapter fires
+
+| Surface | Action |
+|---|---|
+| New adopter onboarding | `/onboard-repo` auto-detects stack + asks for confirmation + writes config |
+| Existing adopter without security_scanning block | `/onboard-repo --reconfigure-security` (Phase Y-4) |
+| Per PR in adopter repo | Adopter's copy of reference workflow fires |
+| Reference workflow update in bassclef | Adopter notices via bassclef-sync; opts in to refresh their workflow |
+
+## Refs
+
+- `standards/code-safety-principles.md` — language-agnostic principles the scanners check
+- `standards/bash-hook-safety.md` — bash-specific discipline (shellcheck is the bash scanner)
+- `standards/bassclef-configs-schema.md` § Security scanning (Phase Y-2; this PR's sibling)
+- `standards/deployment-topology.md` — sibling adapter pattern
+- `.claude/skills/onboard-repo/SKILL.md` (Phase Y-4) — onboarding integration
+- `@luminary saltzer-schroeder` — anchor; mechanical enforcement of protection principles
+- bassclef#1058 — failure-as-evidence for why adopters need substrate-supplied defaults
+- docs/iteration-bets/2026-06-17a-secure-coding-foundations-longrun.md — Phase Y-1
+
+## Retirement
+
+This standard retires when scanner choice converges (one bassclef scanner per stack) OR when a different security-enforcement model replaces per-stack scanner-based CI (e.g., universal SAST API). The adapter shape persists; the matrix entries evolve.