bossbuild 0.97.0

package/stages/L0-quickstart/template/.claude/hooks/lib/yaml.js

@@ -0,0 +1,163 @@
+// Minimal YAML parser for the BOSS loop-runtime — zero deps.
+// Covers the subset used by loop specs and eval files:
+//   - top-level sequence (- item) or mapping
+//   - block mappings (key: value with indented children)
+//   - inline mappings ({k: v, k2: v2})
+//   - inline sequences ([a, b, c])
+//   - scalars: bare string, quoted string, int, true/false, null
+//   - comments (# ...) and blank lines
+// NOT supported: anchors, aliases, multi-line scalars, flow-style mixing.
+// Lifted from docs/architecture/conscience-evals/runner.js so the same parser
+// is available to the project-side hook.
+
+export function parseYaml(text) {
+  const tokens = tokenize(text);
+  if (tokens.length === 0) return null;
+  const baseIndent = tokens[0].indent;
+  const [result] = parseBlock(tokens, 0, baseIndent);
+  return result;
+}
+
+// Extract YAML frontmatter from a markdown file (between leading `---` and `---`).
+// Returns the parsed object, or null if no frontmatter is present.
+export function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) return null;
+  const end = text.indexOf('\n---\n', 4);
+  if (end < 0) return null;
+  return parseYaml(text.slice(4, end));
+}
+
+function parseScalar(s) {
+  s = s.trim();
+  if (s === '' || s === '~' || s === 'null') return null;
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+  if (/^-?\d+\.\d+$/.test(s)) return parseFloat(s);
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  if (s.startsWith('[') && s.endsWith(']')) {
+    const inner = s.slice(1, -1).trim();
+    if (!inner) return [];
+    return splitTopLevel(inner, ',').map((p) => parseScalar(p));
+  }
+  if (s.startsWith('{') && s.endsWith('}')) {
+    const inner = s.slice(1, -1).trim();
+    if (!inner) return {};
+    const obj = {};
+    for (const pair of splitTopLevel(inner, ',')) {
+      const colonIdx = findTopLevelChar(pair, ':');
+      if (colonIdx < 0) continue;
+      const k = pair.slice(0, colonIdx).trim();
+      const v = pair.slice(colonIdx + 1).trim();
+      obj[k] = parseScalar(v);
+    }
+    return obj;
+  }
+  return s;
+}
+
+function splitTopLevel(s, sep) {
+  const parts = [];
+  let depth = 0;
+  let inQuote = null;
+  let start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inQuote) { if (c === inQuote) inQuote = null; continue; }
+    if (c === '"' || c === "'") { inQuote = c; continue; }
+    if (c === '[' || c === '{') depth++;
+    else if (c === ']' || c === '}') depth--;
+    else if (c === sep && depth === 0) {
+      parts.push(s.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(s.slice(start));
+  return parts.map((p) => p.trim()).filter((p) => p.length > 0);
+}
+
+function findTopLevelChar(s, ch) {
+  let depth = 0;
+  let inQuote = null;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inQuote) { if (c === inQuote) inQuote = null; continue; }
+    if (c === '"' || c === "'") { inQuote = c; continue; }
+    if (c === '[' || c === '{') depth++;
+    else if (c === ']' || c === '}') depth--;
+    else if (c === ch && depth === 0) return i;
+  }
+  return -1;
+}
+
+function indentOf(line) {
+  let i = 0;
+  while (i < line.length && line[i] === ' ') i++;
+  return i;
+}
+
+function tokenize(text) {
+  return text.split('\n')
+    .map((line, i) => ({ raw: line, lineNum: i + 1 }))
+    .filter((t) => t.raw.trim().length > 0 && !t.raw.trim().startsWith('#'))
+    .map((t) => ({ ...t, indent: indentOf(t.raw), body: t.raw.trim() }));
+}
+
+function parseBlock(tokens, startIdx, indent) {
+  if (startIdx >= tokens.length) return [null, startIdx];
+  const first = tokens[startIdx];
+  if (first.indent < indent) return [null, startIdx];
+
+  if (first.body.startsWith('- ')) {
+    const arr = [];
+    let i = startIdx;
+    while (i < tokens.length && tokens[i].indent === indent && tokens[i].body.startsWith('- ')) {
+      const itemBody = tokens[i].body.slice(2);
+      const colonIdx = findTopLevelChar(itemBody, ':');
+      if (colonIdx >= 0 && !itemBody.startsWith('{') && !itemBody.startsWith('[')) {
+        const syntheticTokens = [...tokens];
+        const key = itemBody.slice(0, colonIdx).trim();
+        const val = itemBody.slice(colonIdx + 1).trim();
+        syntheticTokens[i] = { ...tokens[i], indent: indent + 2, body: `${key}: ${val}` };
+        const [obj, nextIdx] = parseMapping(syntheticTokens, i, indent + 2);
+        arr.push(obj);
+        i = nextIdx;
+      } else {
+        arr.push(parseScalar(itemBody));
+        i++;
+      }
+    }
+    return [arr, i];
+  }
+
+  return parseMapping(tokens, startIdx, indent);
+}
+
+function parseMapping(tokens, startIdx, indent) {
+  const obj = {};
+  let i = startIdx;
+  while (i < tokens.length && tokens[i].indent === indent && !tokens[i].body.startsWith('- ')) {
+    const line = tokens[i].body;
+    const colonIdx = findTopLevelChar(line, ':');
+    if (colonIdx < 0) { i++; continue; }
+    const key = line.slice(0, colonIdx).trim();
+    const valStr = line.slice(colonIdx + 1).trim();
+    if (valStr) {
+      obj[key] = parseScalar(valStr);
+      i++;
+    } else {
+      const childIndent = i + 1 < tokens.length ? tokens[i + 1].indent : indent;
+      if (childIndent > indent) {
+        const [child, next] = parseBlock(tokens, i + 1, childIndent);
+        obj[key] = child;
+        i = next;
+      } else {
+        obj[key] = null;
+        i++;
+      }
+    }
+  }
+  return [obj, i];
+}

package/stages/L0-quickstart/template/.claude/hooks/memory-cue.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// BOSS memory-cue — a UserPromptSubmit hook (OPT-IN; zero-cost when silent).
+//
+// Ported UP from the dhun dogfood (Principle #1). dhun's was bash+jq; BOSS is
+// zero-dependency (Node built-ins only), so this is the Node port.
+//
+// WHAT IT DOES: scans the founder's prompt for a *feedback signal* — durable
+// guidance worth remembering across sessions — and NUDGES the model to save it
+// to the project's memory. It never writes the memory itself: choosing the right
+// wording (and whether it's durable vs. ephemeral) needs reasoning, so the cue
+// hands that judgment back to the model. Silent on no match → zero token cost.
+//
+//   directive    "from now on", "always", "never", "stop doing", "going forward"
+//   corrective   "no, don't", "that's wrong", "that's not right"
+//   confirmation "perfect, keep doing", "yes exactly", "nailed it"
+//
+// WHY OPT-IN (read before registering): a UserPromptSubmit hook fires a process
+// on EVERY prompt. It's cheap (silent unless a pattern matches) but it is still
+// machinery — ship it dormant, let the founder turn it on when they want BOSS to
+// help build durable memory. (PRINCIPLE #2 / R&H #1 cost discipline.)
+//
+// TO TURN IT ON — add a UserPromptSubmit hook entry in .claude/settings.json
+// (the registration IS the on-switch; an unregistered script costs nothing).
+// It coexists with the conscience hook on the same event:
+//   "hooks": {
+//     "UserPromptSubmit": [
+//       { "matcher": "",
+//         "hooks": [ { "type": "command",
+//                      "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/memory-cue.js\"",
+//                      "timeout": 5 } ] }
+//     ]
+//   }
+//
+// Output contract (Claude Code UserPromptSubmit): text on stdout is added to the
+// session context. Fail-open: any parse/runtime surprise exits 0 silently — a
+// hook that breaks the session is worse than one that occasionally misses a cue.
+
+import process from 'node:process';
+
+const DIRECTIVE = /\b(from now on|going forward|always|never|stop doing|don'?t ever|remember (that|this)|every time|whenever|in (the )?future)\b/i;
+const CORRECTIVE = /\bno,? (don'?t|stop|never|wrong)\b|\bthat'?s (not right|wrong)\b|\bdon'?t do that\b/i;
+const CONFIRM = /\bperfect,? keep\b|\byes,? exactly\b|\bexactly,? that\b|\bthat'?s right,? keep\b|\bnailed it\b/i;
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    // If nothing is piped in, don't hang the session.
+    setTimeout(() => resolve(data), 1000);
+  });
+}
+
+const main = async () => {
+  let prompt = '';
+  try {
+    const raw = await readStdin();
+    const json = JSON.parse(raw);
+    prompt = json.prompt || json.user_prompt || '';
+  } catch {
+    process.exit(0); // fail-open
+  }
+  if (!prompt) process.exit(0);
+
+  let cue = '';
+  if (DIRECTIVE.test(prompt)) cue = 'directive';
+  else if (CORRECTIVE.test(prompt)) cue = 'corrective';
+  else if (CONFIRM.test(prompt)) cue = 'confirmation';
+  if (!cue) process.exit(0);
+
+  process.stdout.write(
+    `[memory-cue:${cue}] The founder's message carries a feedback signal. If this is ` +
+      `durable guidance (not ephemeral or one-off), save it as a feedback memory in the ` +
+      `project's auto-memory using the standard format (frontmatter + **Why:** + **How to ` +
+      `apply:**), and link it from MEMORY.md. If it's context-specific, ignore this. Do not ` +
+      `mention this hook in your reply.\n`
+  );
+  process.exit(0);
+};
+
+main();

package/stages/L0-quickstart/template/.claude/hooks/secrets-guard.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// BOSS secrets-guard — a PreToolUse hook (OPT-IN; high-stakes ceiling, NOT a universal default).
+//
+// WHY OPT-IN (read before registering): a PreToolUse hook fires a process on EVERY tool call —
+// real per-call latency. The universal, zero-cost floor is the `permissions.deny` block in
+// settings.json (ships with every BOSS project). This hook is the *ceiling*: broader coverage
+// (Bash bypasses beyond `cat`, MCP tools, skills added later) for contexts where the stakes justify
+// the cost — regulated / PHI / `domain-expert` cohort work. Registering it everywhere by default
+// would be the always-on machinery BOSS warns founders against (PRINCIPLE #2 / R&H #1). See
+// library/practices/context-discipline.md.
+//
+// TO TURN IT ON — add this to .claude/settings.json (the registration IS the on-switch; an
+// unregistered script costs nothing):
+//   "hooks": {
+//     "PreToolUse": [
+//       { "matcher": "",
+//         "hooks": [ { "type": "command",
+//                      "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/secrets-guard.js\"",
+//                      "timeout": 5 } ] }
+//     ]
+//   }
+//
+// WHAT IT DOES: never let a tool read secret CONTENTS into the model's context (the leak).
+//   - Read / Edit / NotebookEdit of a secrets file  -> DENY (no reason to load a secret into context).
+//   - Bash command referencing a secrets path        -> ASK  (don't hard-block legit `.env` *creation*;
+//                                                             surface it to the human instead).
+//   - MCP tool call whose input references a secret   -> ASK  (unknown semantics; let the human judge).
+//   - everything else                                  -> ALLOW.
+// Fail-open: any parse/runtime surprise exits 0 (allow). A guard that breaks the session is worse
+// than one that occasionally misses — the deny-list floor still hard-blocks the common vectors.
+//
+// Output contract (Claude Code PreToolUse): JSON on stdout with a permissionDecision, exit 0.
+
+import fs from 'node:fs';
+
+// A path is "secret" if its basename is .env / .env.<suffix>, or it sits under a secrets/ segment.
+const SECRET_RE = /(^|[\/\s'"=:])\.env(\.[\w.-]+)?($|[\/\s'"])|(^|[\/\s'"=:])secrets\//i;
+
+const touchesSecret = (s) => typeof s === 'string' && SECRET_RE.test(s);
+
+const decide = (decision, reason) => {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: decision,           // "deny" | "ask"
+      permissionDecisionReason: reason,
+    },
+  }));
+  process.exit(0);
+};
+
+let event;
+try {
+  event = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+} catch {
+  process.exit(0); // fail-open: unreadable/!JSON input -> allow
+}
+
+const tool = event.tool_name || '';
+const input = event.tool_input || {};
+
+try {
+  if (/^(Read|Edit|NotebookEdit)$/.test(tool)) {
+    const p = input.file_path || input.notebook_path || '';
+    if (touchesSecret(p)) {
+      decide('deny',
+        `secrets-guard: refusing to ${tool} a secrets file (${p}). Reading secret contents into ` +
+        `context risks leakage. Read secrets from the environment at runtime, or use a secret manager.`);
+    }
+  } else if (tool === 'Bash') {
+    if (touchesSecret(input.command || '')) {
+      decide('ask',
+        `secrets-guard: this Bash command references a secrets path. Approve only if it does NOT ` +
+        `read secret contents into the session (e.g. creating/appending a .env is fine; cat/grep is not).`);
+    }
+  } else if (tool.startsWith('mcp__')) {
+    if (touchesSecret(JSON.stringify(input))) {
+      decide('ask',
+        `secrets-guard: this MCP tool call references a secrets path. Approve only if it will not ` +
+        `expose secret contents to the session.`);
+    }
+  }
+} catch {
+  process.exit(0); // fail-open on any matching error
+}
+
+process.exit(0); // allow everything else

package/stages/L0-quickstart/template/.claude/rules/your-app-code.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "src/**"
+---
+
+<!-- This file loads into context ONLY when Claude opens a file under src/ — never at session start.
+     That's the whole point: keep app-code conventions here (just-in-time), keep CLAUDE.md for what's
+     true all the time. Rescope the paths: glob above to wherever your code actually lives — or delete
+     this file if you don't need it yet. A rule with no paths: would load every session, like CLAUDE.md. -->
+
+# Working context — {{PROJECT_NAME}} app code
+
+_Conventions that only matter while writing the app. Replace the examples with your real ones, or
+delete what you don't need._
+
+- (example) One responsibility per file; split a module before it grows a second reason to change.
+- (example) Validate input at the boundary, not deep in the call stack.

package/stages/L0-quickstart/template/.claude/settings.json

@@ -0,0 +1,36 @@
+{
+  "permissions": {
+    "defaultMode": "auto",
+    "allow": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash",
+      "Agent",
+      "TodoWrite"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)",
+      "Bash(cat ./.env*)",
+      "Bash(cat ./secrets/*)"
+    ]
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/conscience.js\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/stages/L0-quickstart/template/.claude/skills/boss/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: boss
+description: Spin up a freshly-scaffolded project from a rough idea or PRD. Reads the idea, shapes it through the pm lens, captures it as an IDEA, recommends a stack and starting stage, and (with your OK) creates a private GitHub repo with the right license. Run this right after `boss new`. Usage - /boss [path-to-PRD | rough idea text]
+---
+
+# /boss — project spin-up
+
+You are the spin-up conductor for a project scaffolded by BlueprintOS. Turn a rough idea or PRD
+into a shaped, captured, optionally-published starting point. Move fast, ask little, keep scope small.
+
+## 0. Orient (silent)
+
+Read, in order:
+- `.boss/manifest.json` — current stage + installed agents/skills.
+- `.boss/config.json` — user defaults (`github`, `visibility`, `license`).
+- `CLAUDE.md` — the project's working rules.
+- `docs/ideas/INDEX.md` and `docs/IDS.md` — where ideas land + the next free `IDEA-NNN`.
+
+Don't announce these reads. Just orient.
+
+## 1. Get the idea (bring-your-own-material)
+
+The idea may already exist somewhere — a Word doc, a Google Doc, an Obsidian note, a PDF, a slide
+deck, a URL — not just a tidy PRD. **Pull it in; don't make the founder retype it.**
+
+- **One-or-more sources.** Accept anything the founder points at, in any mix:
+  - **Local files** — `.md`, `.txt`, `.pdf` (read it), `.docx` (extract the text), Obsidian notes,
+    slide decks. Read each directly.
+  - **URLs** — a Google Doc share link, a published doc, an online reference. Fetch each.
+  - **Pasted/typed text** — use as-is.
+  - **Nothing given** — ask **one** open question: *"What are you building? Point me at it — a
+    sentence, a file path, a URL, or a few of them (a doc, a deck, a link). I'll pull them in."*
+- **Snapshot what you read (the "create a dupe" step).** For each file or URL you ingest, write a
+  durable copy into `docs/source/` (create it if absent) — e.g. `docs/source/<original-name>` for a
+  file, or `docs/source/<slug>.md` capturing fetched text with the URL noted at the top. The project
+  should **own** the material so the idea survives if the original moves or changes. Mention briefly
+  what you pulled in (e.g. *"Pulled in 2 sources → docs/source/."*). Don't snapshot pasted one-liners.
+- **Synthesize across all of them.** If several sources were given, read them all before shaping —
+  they're facets of one idea, not separate ideas. Treat a one-liner as complete; ask a clarifying
+  question only if genuinely blocked.
+
+> If the founder is mid-flow and wants to *add* material to an already-captured idea later, that's
+> `/import` — same ingest, pointed at an existing `IDEA-NNN`.
+
+## 2. Shape it (pm lens)
+
+In 3-5 lines back to the user, reflect:
+- **What** it is, in plain language.
+- **Who** it's for.
+- **The smallest version that proves it** (the L0/L1 target — not the full vision).
+- If the idea clearly spans multiple features, name them but don't over-plan.
+
+## 3. Capture it
+
+Append an entry to `docs/ideas/INDEX.md` and create `docs/ideas/IDEA-001-<slug>.md` with frontmatter
+(`id`, `type: idea`, `owner: pm`, `status: ready`). Record what/why/scope/next-step. This is the
+"idea is shared" moment that gates GitHub creation (step 5).
+
+## 4. Stack + stage
+
+- **Stack:** If the idea implies a stack (web app, CLI, mobile, backend service), propose it in one
+  line and, on agreement, record the decision in the IDEA doc and specialize
+  `.claude/agents/coder-generalist.md` (fill in its build/test/run commands). If unclear, stay
+  stack-neutral and say the decision is pending the first build step. Never silently assume a stack.
+- **Mode:** Default is Quickstart (L0). If the PRD is rich and clearly a real product to build now,
+  *recommend* `boss unlock mvp` (specs + `/smoke` gate) — but don't run it for them; suggest the command.
+- **AI-native check (v0.26.0+):** If the idea names the model as load-bearing (the product
+  doesn't work without it — a chatbot, a copilot, an LLM-pipeline, a generation tool, a
+  RAG-mediated product), name it explicitly back to the founder: *"This sounds AI-native —
+  the model is doing the work, not just polishing it."* Then **recommend the AI-first sequence**:
+  *"After `boss unlock mvp`, run `/ai-first-init` — it bakes in cost discipline, eval discipline,
+  structured outputs, and failure-state design from day one. Cheaper to declare upfront than
+  to retrofit after the first bill, the first hallucination, or the first refusal in front of
+  a user."* Don't run anything for them; the recommendation is the artifact.
+
+## 5. GitHub repo (the gated step)
+
+Read `github` from `.boss/config.json`:
+- `never` → skip.
+- `ask` (default) → prompt: *"Spin up a **private** GitHub repo for this? I'll add a LICENSE —
+  default is **proprietary / All Rights Reserved** so you keep both paid and open-source options open
+  (you can relicense later). Say 'open source' if you'd rather pick MIT / Apache-2.0 / AGPL-3.0 now."*
+- `always` → proceed with the configured `visibility` + `license` without asking.
+
+On a yes, do this **in order**:
+
+1. **Write the LICENSE file locally** (must exist before push — `gh` won't add it to an existing repo):
+   - `proprietary` (default): write the All-Rights-Reserved text from the appendix below, filling the year and the user's name.
+   - `MIT` / `Apache-2.0` / `AGPL-3.0`: fetch canonical text with
+     `gh api /licenses/<key> --jq .body` (keys: `mit`, `apache-2.0`, `agpl-3.0`) and fill placeholders.
+2. **Prevent the email-privacy block (GH007).** Derive the user's GitHub noreply address and set it
+   **repo-locally only** (global config untouched), then tell the user you did so:
+   ```bash
+   NR=$(gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"')
+   git -C . config user.email "$NR"
+   ```
+3. **Commit** the scaffold (include LICENSE) if there are uncommitted files.
+4. **Create + push** as a private repo from the existing local repo:
+   ```bash
+   gh repo create <project-name> --private --source . --remote origin --push
+   ```
+   (`--source .` publishes the local history; do NOT pass `--license`/`--gitignore` here — those only
+   apply to empty repos created server-side, which would conflict with the local history.)
+5. Confirm the repo URL back to the user.
+
+If `gh` isn't authenticated (`gh auth status` fails), don't guess — tell the user to run `gh auth login`
+and offer to retry.
+
+## 6. Cohort (optional, low-friction — v0.20.0+)
+
+Read `cohort` from `.boss/config.json`. If `null` (the default), ask ONE open question:
+
+> *"Quick optional thing — which of these sounds most like where you're starting from? It lets BOSS's
+> conscience tune its voice for you. If none fit, skip:*
+> - *`vibe-coder-newbie` — picked up Cursor/Claude Code recently, no eng/startup background*
+> - *`eng-builder` — strong eng background, first-time founder*
+> - *`non-tech-founder` — domain expertise, no coding background, AI is the bridge*
+> - *`first-product` — absolute first product ever, learning everything as you go*
+> - *`vibe-virtuoso` — ships a lot of projects, harder time sustaining one*
+> - *`indie-hacker` — building right-sized; calm-company, not venture*
+> - *`returning-founder` — shipped before; want depth, not 101*
+> - *`domain-expert` — deep expertise in a high-stakes domain (medical/legal/financial)*
+> - *skip — leave it generic"*
+
+On answer, write the value to `.boss/config.json` (don't disturb other fields). If they skip, leave `null`.
+Either way, move on. Don't argue with their choice; they can edit the file later.
+
+**Voice note:** these are *beginner personas* (per IDEA-009). The cohort declaration sharpens BOSS for
+this founder *as evidence comes in over time* — not the other way around. If the user mishears their own
+cohort, real use will reveal it; the file is editable.
+
+## 7. Wrap up
+
+Give a tight summary: what the idea is, where it's captured (`IDEA-001`), the stack decision (or that
+it's pending), the mode, the cohort (if set), and the repo URL if created. Then the single best next step
+(usually: start building the smallest version, or `boss unlock mvp` if it's clearly a real build).
+
+## Rules
+
+- Capture before code. Don't start implementing inside `/boss` — this is spin-up only.
+- Never create a public repo by default. Never publish a permissive license by default.
+- Never touch global git config. Repo-local email only, and say so.
+- Prefer one well-placed question over an interrogation.
+
+---
+
+## Appendix — proprietary LICENSE template
+
+```
+Copyright (c) {{YEAR}} {{OWNER}}. All Rights Reserved.
+
+This software and its source code are proprietary and confidential. No license,
+express or implied, is granted to any person to use, copy, modify, merge, publish,
+distribute, sublicense, or sell copies of this software, in whole or in part,
+without the prior written permission of the copyright holder.
+
+This default is intentional: it preserves the option to later release this project
+under an open-source license (e.g. MIT, Apache-2.0, AGPL-3.0) OR to commercialize it.
+A permissive open-source grant, once published, cannot be revoked — so the path is
+kept open until deliberately chosen.
+```

package/stages/L0-quickstart/template/.claude/skills/boss-learn/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: boss-learn
+description: Route a proven pattern two ways — UP into the BOSS library as a reusable superset practice, or DOWN into this app as hardened core functionality. The judgment layer over `boss learn`. Usage - /boss-learn [what to promote]
+---
+
+# /boss-learn — the two-destination router
+
+PRINCIPLES #1: BOSS is always scaffolding, but at every natural breakpoint (a mode transition, a
+shipped feature, the third time the same work repeats) you **pause and sort the pattern two ways.**
+This skill is that router. It is **not** a one-way "promote to BOSS" — deciding UP vs DOWN *is* the
+work.
+
+## 0. Orient (silent)
+
+- Read `PRINCIPLES.md` (#1 especially) and `.boss/manifest.json` (which project/mode you're in).
+- Identify the concrete pattern: the file(s), prompt, workflow, convention, or token set in question.
+
+## 1. Decide the destination
+
+Ask one question if it's genuinely unclear; otherwise call it and say why.
+
+- **UP → BOSS library** when the pattern is *project-neutral and reusable*: a workflow, an agent or
+  skill shape, a hook, a best-practice doc, a memory seed. The test (PRINCIPLES #3): *could a sibling
+  project reuse this without copy-pasting code?* If yes, it's superset.
+- **DOWN → app core** when the pattern is *this product's actual functionality* that happens to be
+  living as scaffold/ad-hoc. It belongs in the app's own modules, with the app's own tests — not in BOSS.
+
+A pattern can route **both**: the generalized shape goes UP, the concrete implementation hardens DOWN.
+
+## 2a. Route UP
+
+1. **Generalize first.** Strip project specifics; replace them with `{{PLACEHOLDERS}}`. Domain logic
+   never lands in `library/` (PRINCIPLES: stack- and project-neutral only). Write/clean the file.
+2. **Pick a category:** `agents` · `skills` · `hooks` · `practices` · `memory-seed`.
+3. **Promote it:**
+   ```
+   boss learn <path-to-generalized-file-or-dir> --as <category> --note "<one line: what & why>"
+   ```
+   This copies it into `library/<category>/`, bumps `VERSION` + `package.json` (minor by default;
+   `--patch`/`--major`/`--version X.Y.Z` to override), and prepends a `registry/CHANGELOG.md` entry.
+4. **Sharpen the CHANGELOG prose** by hand — the auto entry is a stub. The CHANGELOG is what every
+   project reads via `/boss-sync`, so make it say what's new and why it matters.
+5. Tell the user: connected projects pull this via `boss sync` / `/boss-sync`.
+
+## 2b. Route DOWN
+
+No BOSS version change. This is product, not scaffold. Give concrete guidance (or do it, if asked):
+- Move the pattern from ad-hoc/scaffold into a **named, owned module/config** in the app.
+- Add the app's own tests around it; wire it into the app's real flow.
+- If a *generalizable shape* remains, note it for a follow-up UP — don't lock value into code (PRINCIPLES #3).
+
+## 3. Close the loop
+
+- Update `docs/RESUME.md` if this was a breakpoint worth recording.
+- One-line summary: what moved, which direction, the new BOSS version (if UP), the next step.
+
+## Rules
+
+- Deciding the direction is the point — never default to UP. Most app code routes DOWN.
+- Never put domain specifics in `library/`. Generalize or don't promote.
+- `boss learn` edits the BOSS **source** repo (found via the registry's self-hosted entry, or
+  `$BOSS_SRC`). Review its diff and commit deliberately — don't auto-commit BOSS.
+- One pattern per run. If the user names several, take the clearest first.

package/stages/L0-quickstart/template/.claude/skills/boss-sync/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: boss-sync
+description: Pull current BOSS practices into this project — bring the installed modes' skills/agents up to the latest version as a reviewed, narrated diff, then bump the project's BOSS pin. The judgment layer over `boss sync`. Usage - /boss-sync
+---
+
+# /boss-sync — bring this project current
+
+The distribution half of the learning loop (PRINCIPLES #1): improvements promoted UP into the BOSS
+library flow back DOWN into every connected project. This skill brings *this* project's BOSS-managed
+files (the skills, agents, and hooks of its installed modes) up to the current version — reviewed, not
+blind. Hook *registrations* are merged into `.claude/settings.json` additively, never clobbering your
+own permissions or hooks.
+
+## 0. Orient (silent)
+
+- `boss status` — current mode, the project's BOSS pin, and whether newer practices exist.
+- Read `registry/CHANGELOG.md` from the BOSS source repo for **what changed since this project's pin** —
+  this is the narration you'll give the user (not just a file list).
+
+## 1. Preview
+
+Run `boss sync` (no flags). It lists each BOSS-managed file (skills, agents, hooks) as `new`,
+`changed (N lines)`, or up to date, across all installed modes; flags a `~ merge settings/hooks` line if
+hook registrations need adding to `.claude/settings.json`; and reconciles any stale mode label (e.g. an
+old `L0-sketch` pin → `L0-quickstart`).
+
+## 2. Review (the judgment)
+
+Before applying, for each **changed** file:
+- Read the project's current copy and the incoming version. Summarize what actually changes.
+- **Flag conflicts:** if the project edited a BOSS-managed file locally, a sync overwrites it. Call this
+  out by name and ask before clobbering. (v1 syncs BOSS-managed skills/agents only — see scope below.)
+- Tie changes back to the CHANGELOG entries so the user understands *why*, not just *what*.
+
+## 3. Apply
+
+- `boss sync --apply` — writes the new/changed files and bumps the project's `.boss` pin to current.
+- Then show `git diff` and let the user review and commit. The project is the source of truth for its
+  own history; BOSS just proposes the update.
+
+## Scope
+
+- Syncs **BOSS-managed skills, agents, and hook scripts** for installed modes.
+- **Merges hook registrations into `.claude/settings.json`** additively — adds the `UserPromptSubmit`
+  (etc.) entries BOSS ships, matched by command so it's idempotent, and **preserves your permissions and
+  any hooks you added.** This is the one user-editable file sync touches, and only the `hooks` block.
+- Does **not** auto-merge `CLAUDE.md` or other `settings.json` keys. If the CHANGELOG implies those should
+  change, surface it and let the user merge by hand.
+- New skills/agents/hooks added to a mode since the pin are pulled in; nothing is removed.
+
+## Rules
+
+- Review before `--apply`. Never overwrite a locally-edited managed file without flagging it first.
+- Narrate from the CHANGELOG — the user should learn what's new, not just see files move.
+- Don't commit for the user; hand them a clean `git diff` to review.