@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/standards/vpc-fit-validation.md

@@ -0,0 +1,167 @@
+---
+tier: lite
+description: Rules for validating fit in a Value Proposition Canvas — every Pain Reliever MUST address a named Pain; every Gain Creator MUST produce a named Gain.
+---
+
+# VPC Fit Validation
+
+Rules for validating fit in a Value Proposition Canvas — every Pain
+Reliever MUST address a named Pain; every Gain Creator MUST produce a
+named Gain. Orphan entries (Relievers/Creators without a target) fail
+validation. Unaddressed Pains/Gains (coverage gaps) surface as WARN.
+
+Skill: `.claude/skills/value-prop-canvas/SKILL.md`.
+Template: `templates/value-prop-canvas.md`.
+Upstream primitive: `.claude/skills/personas/SKILL.md` +
+`standards/persona-schema.md`.
+
+## Why this standard exists
+
+VPC's whole purpose is making fit between Customer Profile and Value
+Map diagnostic instead of asserted. Without explicit fit rules, a Pain
+Reliever that doesn't address any named Pain slips into the Value Map
+unchallenged — the classic "feature looking for a problem" failure
+mode. One fit walk per canvas catches these before the canvas gets
+treated as product-market-fit evidence.
+
+This standard codifies the walk. Adjacent to
+`.claude/rules/artifact-ingestion.md` philosophy: cite before you
+claim. Same idea at a different level — for VPC, every claim about
+fit must cite the customer-side element it's addressing.
+
+## The fit rules
+
+### Rule 1 — Pain Reliever MUST name Pain(s) it addresses
+
+Every Pain Reliever entry MUST reference ≥1 Pain by ID (P1, P2) or by
+exact label. Orphan Pain Relievers (no Pain named) FAIL validation.
+
+**Acceptable:**
+```markdown
+### PR1 — Shared workspace
+**Addresses:** P1 (Chat history siloed), P2 (Can't share context)
+```
+
+**NOT acceptable:**
+```markdown
+### PR3 — AI-powered meeting notes
+Description: automatic meeting summaries with action items.
+```
+
+PR3 has no Pain referenced. Either:
+- Add a Pain to the Customer Profile (e.g., `P4: Meeting context lost between sessions`) and cite it in PR3, OR
+- Drop PR3 from the Value Map
+
+Silence is not deferral — the canvas fails validation until resolved.
+
+### Rule 2 — Gain Creator MUST name Gain(s) it produces
+
+Symmetric to Rule 1. Every Gain Creator references ≥1 Gain by ID or
+label. Orphans FAIL.
+
+### Rule 3 — Unaddressed Pains produce WARN (coverage gap)
+
+A Pain with no Pain Reliever is a coverage gap — the product, as
+scoped, doesn't address this pain. That's not a fit failure (the
+product may deliberately out-of-scope that pain for this iteration);
+it's a deliberate-scope signal for the operator.
+
+WARN format:
+```markdown
+- P3 (Monthly cost scales badly) — UNADDRESSED. Coverage gap: [reason — out of scope this iteration; deferred to pricing workstream].
+```
+
+If WARN count is high (>50% of Pains unaddressed), the canvas carries
+a scope-too-narrow signal: either the Customer Profile is listing
+pains not intended for this product, or the Value Map is incomplete.
+Operator decides which.
+
+### Rule 4 — Unaddressed Gains produce WARN (coverage gap)
+
+Symmetric to Rule 3.
+
+### Rule 5 — Every canvas is 1:1 with a persona
+
+A VPC covers exactly one persona. Canvases that merge multiple
+personas into a single Customer Profile FAIL validation — the fit
+signal is lost when customer segments are averaged.
+
+If the product legitimately serves multiple segments, produce one
+canvas per segment. `/value-prop-canvas` with no args produces N
+canvases for N personas.
+
+## Validation output format
+
+`/value-prop-canvas validate` walks every canvas under
+`docs/value-prop-canvas/*.md` and reports:
+
+```markdown
+## VPC validation
+
+**Canvases scanned**: N
+
+| File | Orphan PRs | Orphan GCs | Unaddressed Pains | Unaddressed Gains | Status |
+|------|-----------|-----------|-------------------|-------------------|--------|
+| couple-founders.md | 0 | 0 | 1 | 0 | PASS |
+| cofounder-pair.md | 1 | 0 | 0 | 0 | FAIL |
+| operator-advisor.md | 0 | 2 | 2 | 1 | FAIL |
+
+**Pass**: [N] | **Warn**: [M] | **Fail**: [K]
+```
+
+Orphans block validation (FAIL). Coverage gaps warn but do not block
+(PASS-WARN indicated via note rather than status change). Rule 5
+violations are FAIL.
+
+## Status semantics
+
+| Status | What it means | Action |
+|--------|--------------|--------|
+| **PASS** | No orphans, all Pains/Gains addressed | Canvas usable downstream |
+| **PASS-WARN** | No orphans, but coverage gaps | Canvas usable; gaps are scope signal |
+| **FAIL** | At least one orphan | Canvas NOT usable; resolve before downstream skills consume |
+
+Downstream skills (`/value-prop`, `/user-stories`, `/risk-test-synthetic`)
+SHOULD refuse to consume FAIL canvases. PASS-WARN is acceptable
+downstream — the operator has consciously chosen which pains/gains
+are in scope.
+
+## What this standard does NOT cover
+
+- **Whether a Pain is "real"** — that's upstream in `/personas`
+  evidence-traceability. If a Pain lacks a source trace, the
+  persona-level validation WARNs on orphan claim. VPC takes the
+  persona as given.
+- **Whether a Pain Reliever is "good"** — that's subjective product
+  judgment. VPC validates THAT a reliever addresses a pain, not HOW
+  WELL. For quality signal, run `/synthetic-user` Tier 3 or user
+  testing.
+- **Aggregation across canvases** — if three personas all have "P1:
+  cost" and each canvas's PR1 addresses it, there's no cross-canvas
+  fit metric. Aggregation is future work (quorum #55
+  `/risk-test-synthetic` touches this space).
+
+## Relationship to other standards
+
+| Standard / rule | Connection |
+|-----------------|-----------|
+| `standards/persona-schema.md` | Upstream — personas are the input; evidence-traceability at persona level feeds Pains used here |
+| `.claude/rules/artifact-ingestion.md` | Same philosophy: cite before you claim; at canvas-level rather than file-level |
+| `.claude/skills/value-prop/SKILL.md` | Adjacent skill; uses VPC as evidence when present |
+| `.claude/skills/jtbd-tasks/SKILL.md` | JTBD feeds Customer Jobs; functional jobs especially |
+
+## Future evolution
+
+When `/risk-test-synthetic` (quorum #55) promotes, it reads VPC per
+persona AND risk scores per persona-artifact pair. Rule extensions
+likely:
+- Risks per Pain (likelihood × severity from Maurya matrix)
+- Per-persona fit score (% Pains addressed weighted by severity)
+
+Those belong in the risk-test standard when that skill lands, not
+here. This standard stays focused on orphan/coverage validation.
+
+## Closes
+
+- bassclef #201 (companion to quorum #51)
+- Part of iteration `docs/iteration-bets/2026-04-19e-persona-vpc-promotions.md` Stack-2

package/dist/lite/templates/gallery-yml.md

@@ -0,0 +1,113 @@
+---
+tier: lite
+---
+
+# `gallery.yml` — Prototype Variant Metadata Template
+
+Per-variant metadata file read by `/prototype-gallery` to render the
+gallery index page. See `standards/prototype-gallery.md` for full
+schema semantics.
+
+Place at: `prototypes/<variant-slug>/gallery.yml`
+
+## Template
+
+```yaml
+# Variant title shown on the gallery card. Humanized slug + luminary
+# shorthand is the convention.
+title: "Variant A — Ive + HIG"
+
+# Two-line value proposition. Block-scalar (|) preserves newlines.
+# HARD LIMIT: 2 lines. Three or more triggers a warning; the skill
+# may truncate on render. The constraint is intentional — gallery
+# cards optimize for scan, not explanation.
+value_prop: |
+  Restrained surfaces. Operator reads the deal in under 3 seconds.
+  Strong typographic hierarchy; no decorative affordances.
+
+# Luminary names — render as tag pills. Shape matches the
+# primary_luminaries convention in iteration bets (see
+# standards/pluggable-luminaries.md). Primary first if multiple.
+luminaries:
+  - Jony Ive
+  - Apple HIG
+
+# Production date (ISO 8601). Controls default sort order in the
+# gallery (newest first).
+date: 2026-04-20
+
+# Lifecycle status:
+#   active      — shown in gallery (default)
+#   archived    — hidden; public/prototypes/<slug>/ preserved
+#   superseded  — hidden; rendered as link to successor in archived section
+status: active
+
+# OPTIONAL — only when status: superseded
+# superseded_by: variant-n-norman-prater
+
+# OPTIONAL — override default sort order (lower renders first)
+# sort_order: 1
+```
+
+## Worked example (non-quorum-specific)
+
+```yaml
+title: "Variant N — Norman + Prater"
+value_prop: |
+  Affordance-first surfaces with entity-derived navigation.
+  Every control answers "what can I do here?" before the operator asks.
+luminaries:
+  - Don Norman
+  - Sophia Prater
+date: 2026-04-19
+status: active
+```
+
+## Fallback: README frontmatter
+
+If `gallery.yml` is absent, `/prototype-gallery` reads the same schema
+from the variant's `README.md` frontmatter:
+
+```markdown
+---
+title: "Variant N — Norman + Prater"
+value_prop: |
+  Affordance-first surfaces with entity-derived navigation.
+  Every control answers "what can I do here?" before the operator asks.
+luminaries:
+  - Don Norman
+  - Sophia Prater
+date: 2026-04-19
+status: active
+---
+
+# Variant N
+
+(README body is ignored by the gallery skill; it's for humans reading
+the variant directly.)
+```
+
+Preferred form is `gallery.yml` — separates gallery metadata from
+README narrative and keeps the skill's read-path narrow.
+
+## Validation rules
+
+| Field | Required | Validation |
+|-------|----------|-----------|
+| `title` | Yes | Non-empty string |
+| `value_prop` | Yes | ≤ 2 newline-separated lines |
+| `luminaries` | Yes | Non-empty list of strings |
+| `date` | Yes | ISO 8601 date (YYYY-MM-DD) |
+| `status` | No | One of `active` (default), `archived`, `superseded` |
+| `superseded_by` | Conditional | Required when `status: superseded`; references another variant slug |
+| `sort_order` | No | Integer; lower sorts first |
+
+Variants missing any required field block the skill — see
+`.claude/skills/prototype-gallery/SKILL.md` "Rules" section. A gallery
+card without a value prop is worse than no card.
+
+## Relationship
+
+- Consumed by: `.claude/skills/prototype-gallery/SKILL.md`
+- Defined in: `standards/prototype-gallery.md`
+- Produced manually OR by `.claude/skills/prototype-variants/SKILL.md` (upstream producer — may emit `gallery.yml` as part of variant scaffold)

package/dist/lite/templates/product-canvas.md

@@ -0,0 +1,169 @@
+---
+tier: lite
+---
+
+# [Initiative Name] — Product Canvas
+
+## How to use this
+
+Start at Stage 1. Don't touch Stage 2 until Stage 1 is sharp. Don't touch Stage 2.5 (substrate sequence) until Stage 2 is sharp. Don't touch Stage 3 until you're ready to write a spec. Most ideas die at Stage 1 — that's the point.
+
+---
+
+## Stage 1: Thesis (5 minutes)
+
+### Value Proposition (one sentence)
+
+For [customers who ___], [initiative name] [does ___], yielding [___ benefits].
+
+### Audience Scope
+
+Tag one. This determines the conviction bar and investment level.
+
+| Scope | Definition | Example | Conviction test |
+|-------|-----------|---------|-----------------|
+| **Operator** | Just me / my family | POA-ops, TwoDo, PruneGuice | Would I use this *this week*? |
+| **Domain** | Me + others in the same game | OpenClaw, Deal Pipeline, ETA tooling | Can I describe the problem without referencing my situation and it still makes sense? |
+| **Product** | Public users, potential business | TwoDo (if graduated), deal-sourcing SaaS | Would a stranger pay for this or choose it over alternatives? |
+
+Scope: ___
+
+**Note:** Things can graduate. TwoDo starts as Operator, becomes Product when the
+value prop stands on its own. Tag what it is *now*, not what you hope it becomes.
+
+### The Problem (one paragraph)
+
+What pain exists? Who has it? How do they cope today? What does it cost them?
+
+### The Bet (one paragraph)
+
+Why do we believe this solution works? What's the insight others are missing?
+
+### Conviction check
+
+- **Operator scope:** Does this pass the "would I use it this week" test? → proceed to Stage 2 or kill it.
+- **Domain scope:** Can you state the problem generically? Has anyone else described this pain in a forum, podcast, or conversation? → proceed or park it.
+- **Product scope:** Write the value prop sentence above to a stranger. Does it land without explanation? → proceed or downgrade to Domain/Operator.
+
+---
+
+## Stage 2: Shape (30 minutes — only if Stage 1 passes conviction check)
+
+### One-Paragraph PR/FAQ
+
+Write one paragraph as if announcing this to the world today. If it doesn't excite you, stop here.
+
+*Operator scope: this can be informal — a sentence to yourself about what you're building and why.*
+*Domain/Product scope: write it like a stranger will read it.*
+
+### Users / Personas
+Who specifically benefits? (Name real types, not abstractions.)
+
+### Access Scope
+Who needs to reach this, and from where?
+- [ ] Operator only (Tailscale mesh)
+- [ ] Trusted circle (family, partners — Tailscale or authenticated public)
+- [ ] Public (anyone on the internet)
+
+### Surfaces affected
+
+Required whenever the bet touches existing operator surfaces. List every
+surface in scope, including ones you believe are unchanged — silence
+defaults existing surfaces into the background.
+
+| Surface | Current role | New role in this bet | Change type (shift / expand / unchanged) |
+|---------|--------------|----------------------|------------------------------------------|
+
+Canvas fails review if this table is missing OR if a surface is listed
+"unchanged" without rationale.
+
+### Integration surfaces
+
+Required for every external system (observability, messaging, payments,
+auth, analytics). Separate the **engine** (data flow) from the **UX
+surface** (where the operator touches it), and state depth.
+
+| System | Engine (data in/out) | UX surface (where operator touches it) | Depths (glance / study / explore) |
+|--------|---------------------|----------------------------------------|----------------------------------|
+
+Depth definitions:
+- **Glance** — visible in the primary surface, no extra click (e.g. confidence chip)
+- **Study** — one click, stays in app (e.g. inline panel)
+- **Explore** — one click out to the external tool (e.g. vendor dashboard URL)
+
+Canvas fails review if any external system is named without an integration-surface row.
+
+### Key Outcomes
+What changes in the world if this works?
+
+Every **numeric** outcome MUST carry a one-line instrumentation note:
+"measured via `{event | table | endpoint | query}`". Aspirational targets
+without measurement vehicles are canvas-review failures.
+
+- Outcome 1 (measurable) — measured via `…`
+- Outcome 2 (measurable) — measured via `…`
+
+---
+
+## Stage 2.5: Substrate Sequence (MUST — before any Build Sequence)
+
+Before scoping the build, enumerate the substrate the work will touch.
+This is the prefunk — a deliberate scan of which skills, rules, hooks,
+agents, and standards the work depends on or extends. Resolves #120
+(was: "new skill /substrate-plan") and #598 (was: "substrate-sequence
+prefunk as standard pre-build artifact for bets") as an artifact-only
+pattern, not a new skill.
+
+**Why**: builds that pattern-match on familiar skill names without
+checking the substrate consistently miss rules that would have gated
+the work, or duplicate skills that already exist. The substrate
+sequence is the antidote to "I thought there was a skill for that"
+and "I didn't realize that rule applied here."
+
+**Format** (one table, inline in the canvas or in a linked sibling doc):
+
+| Layer | Artifacts touched | Dependency type | Notes |
+|-------|------------------|-----------------|-------|
+| Skills | /canvas, /spec, /decompose | reads, extends | — |
+| Rules | artifact-ingestion, prototype-production-coupling | must-satisfy | tokens-first gate fires |
+| Hooks | pre-build-gate, artifact-ingestion-gate | must-satisfy | no changes |
+| Agents | Builder, Reviewer, Designer | invokes | sequential |
+| Standards | project-directory-layout, testing | must-satisfy | — |
+
+**Dependency types**:
+- **reads** — the work consumes this artifact as input
+- **extends** — the work modifies or adds to this artifact
+- **invokes** — the work runs this skill/agent as part of execution
+- **must-satisfy** — this rule/hook/standard gates the work
+- **creates** — the work introduces a new artifact of this kind
+
+**Checks before moving to Stage 3**:
+1. Is every skill this references still valid? (check `/skills` catalog)
+2. Does any "creates" row duplicate an existing skill or rule?
+3. Are there "must-satisfy" rows whose gates block the planned sequence?
+
+If a new skill or rule appears in "creates", run `/promote` or flag to
+operator — don't silently ship new substrate as a side-effect of
+feature work.
+
+---
+
+## Stage 3: Commit (scales with audience scope)
+
+**Operator scope:** Skip this stage. Go straight to a spec or just build it.
+
+**Domain scope:** Answer Risks & Assumptions. Write a spec. Build it.
+
+**Product scope:** Full treatment — risks, constraints, full PR/FAQ, spec with
+deployment questionnaire. This is where you decide on domain, auth, public access,
+and everything in the [spec template](spec-template.md).
+
+### Risks & Assumptions
+What must be true for this to work? What could kill it?
+
+### Constraints
+Budget, timeline, technical, regulatory.
+
+### Full PR/FAQ
+Expand the one-paragraph version into the [full PR/FAQ template](pr-faq.md)
+if this initiative spans multiple specs or involves external users.

package/dist/lite/templates/value-prop-canvas.md

@@ -0,0 +1,180 @@
+---
+tier: lite
+---
+
+# Value Proposition Canvas — [Persona Name]
+
+<!--
+  Bassclef VPC template. Strategyzer-shaped. Produced by
+  /value-prop-canvas skill. Validated by standards/vpc-fit-validation.md.
+
+  One canvas per persona. NEVER merge multiple personas into one canvas.
+
+  Delete this comment block after copy-paste.
+
+  Save location: docs/value-prop-canvas/{persona-slug}.md
+  (filename matches the persona's slug)
+-->
+
+**Persona:** [slug] ([path to persona file, e.g., `docs/personas/couple-founders.md`])
+**Iteration / feature:** [iteration-bet path, spec path, or feature name]
+**Generated:** [YYYY-MM-DD]
+**Fit validation:** PASS | WARN (coverage gaps, no orphans) | FAIL (orphans present)
+
+---
+
+## Customer Profile
+
+<!--
+  Derived from persona content. Do NOT invent — if the persona doesn't
+  have the data, leave the quadrant thin and let WARN surface the gap.
+
+  Three flavors of Customer Jobs per Strategyzer:
+    - Functional: the practical task they're trying to accomplish
+    - Social: how they want to be perceived while doing it
+    - Emotional: what feeling state they're trying to reach or avoid
+-->
+
+### Customer Jobs
+
+- **[J1]** Functional: [label] — [one line]
+- **[J2]** Social: [label] — [one line]
+- **[J3]** Emotional: [label] — [one line]
+- [Additional jobs as the persona supports]
+
+### Pains
+
+<!--
+  Pulled from persona's "Pain points" section, preserving source
+  traces where present. Each Pain gets an ID for Pain Reliever
+  referencing.
+-->
+
+- **[P1]** [label] — [one line; include *Source trace: [ref]* if persona had one]
+- **[P2]** [label] — [one line]
+- **[P3+]** as applicable
+
+### Gains
+
+<!--
+  Pulled from persona's Motivators / "What would make them switch" /
+  implicit gains inferable from the persona's goal. Avoid lazy
+  inversions (don't just flip each Pain into a "not-Pain" gain —
+  gains are desired outcomes often articulated independently).
+-->
+
+- **[G1]** [label] — [one line]
+- **[G2]** [label] — [one line]
+- **[G3+]** as applicable
+
+---
+
+## Value Map
+
+<!--
+  What we ship, and how each element addresses a specific Pain
+  or produces a specific Gain. This is the contract side of the fit.
+-->
+
+### Products / Services
+
+- [Feature or capability A]
+- [Feature or capability B]
+- [+ as applicable]
+
+### Pain Relievers
+
+<!--
+  Each MUST name the Pain(s) it addresses. Orphan relievers (no Pain
+  named) fail fit-validation — see standards/vpc-fit-validation.md.
+-->
+
+- **[PR1]** [label]
+  - **Addresses:** [P1], [P2]
+  - Description: [one or two lines on the specific product behavior]
+
+- **[PR2]** [label]
+  - **Addresses:** [P3]
+  - Description: [lines]
+
+- **[PR3+]** as applicable
+
+### Gain Creators
+
+<!--
+  Each MUST name the Gain(s) it produces. Orphan creators fail
+  fit-validation.
+-->
+
+- **[GC1]** [label]
+  - **Produces:** [G1], [G2]
+  - Description: [one or two lines]
+
+- **[GC2]** [label]
+  - **Produces:** [G3]
+  - Description: [lines]
+
+- **[GC3+]** as applicable
+
+---
+
+## Fit summary
+
+| Element | Count | Addressed | Unaddressed |
+|---------|-------|-----------|-------------|
+| Pains | [N] | [M] | [K] |
+| Gains | [N] | [M] | [K] |
+
+**Status:** [PASS | WARN | FAIL]
+
+---
+
+## Orphans surfaced
+
+<!--
+  List every Pain Reliever or Gain Creator without a named target.
+  Each orphan is a decision: either add the missing Pain/Gain to
+  the Customer Profile, or drop the entry from the Value Map.
+  Silence is not resolution — the operator must choose.
+
+  If no orphans: state "None."
+-->
+
+- **[Orphan entry]** — [why it's here without a target; proposed resolution: add [P_new] or drop entry]
+
+---
+
+## Coverage gaps
+
+<!--
+  Pains and Gains that have no Relievers/Creators. These are
+  deliberate-scope signals, not fit failures. Operator decides
+  whether to extend the Value Map or mark the gap as out-of-scope
+  for this iteration.
+
+  If no gaps: state "None."
+-->
+
+- **[P_N]** unaddressed — [reason: out of scope, deferred, future iteration]
+- **[G_N]** unaddressed — [reason]
+
+---
+
+## Notes
+
+<!--
+  Optional. Edge cases, deferred decisions, open questions for
+  the operator or downstream skills.
+-->
+
+- [Note 1]
+- [Note 2]
+
+---
+
+## Further reading
+
+- Osterwalder et al., *Value Proposition Design* (2014) — bassclef VPC source
+- IxDF — Value Proposition Canvas overview: https://ixdf.org/literature/topics/value-proposition-canvas
+- Strategyzer — VPC tool: https://www.strategyzer.com/library/the-value-proposition-canvas
+- Clayton Christensen, *Competing Against Luck* — JTBD → Customer Jobs mapping

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebassclef/lite",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Bassclef CLI — install and upgrade bassclef in your project with two commands.",
   "keywords": [
     "bassclef",
@@ -42,12 +42,12 @@
     "LICENSE"
   ],
   "bassclef": {
-    "upstream_tag": "v0.42.0",
+    "upstream_tag": "v0.45.0",
     "wiring_manifest_schema_major": 2,
     "bundle_paths": [
       "dist/lite/"
     ],
-    "phase_note": "cli 1.1.1 (goal 2026-09-17) — init reporting contract per ADR-010. Manifest names every file written; --json moves to stdout and names all catalog families."
+    "phase_note": "cli 1.2.0 (2026-09-18) — additive minor release. Adds the top-level `.version` field to `.bassclef/init.manifest.json` so v0.45.0's `91-npm-version-drift.sh` hook can compare installed vs npm-latest. Bundles bassclef v0.45.0 substrate (7 adopter cures + drift hook). Ships the stdout-blocking fix at cli entry (Node async-pipe-write dropped writes on process.exit under CI pipes). Rolls up 1.2.0-alpha.0 + alpha.1 which shipped as previews at @next. Per bassclef-upstream#1749; cli PRs #129, #131, #134."
   },
   "engines": {
     "node": ">=20"