bossbuild 0.97.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajesh Shah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRINCIPLES.md

@@ -0,0 +1,70 @@
+# BOSS — Operating Principles
+
+## The why (the problem BOSS exists for)
+
+Founders can now build faster than they can validate. AI makes a polished prototype cheap — which
+creates a new trap: confusing a **pseudo app** (an impressive demo with no proven pain, workflow fit,
+willingness to pay, distribution, or reliability) with a **real business value app** (solves a painful
+problem for a specific customer, fits a real workflow, creates measurable value, has a path to
+distribution). BOSS is the guidance layer between those two states.
+
+> **BOSS helps founders build faster without fooling themselves** — compressing the loop from idea to
+> evidence while continuously checking the work against real pain, real workflows, real buyers, real
+> economics, and real distribution. The goal is not more pseudo apps; it's real business value apps.
+
+What that buys is narrower — and stronger — than "discipline wins." Disciplined validation doesn't
+guarantee a win; it makes you **decide faster, including quitting faster** (Camuffo et al., 759-firm
+RCT [EVIDENCE]). Cheap AI lowers the cost of *building*, not the cost of *being wrong* — so the cheaper
+building gets, the more the loop matters, not less. BOSS's conscience exists to stop self-fooling, and
+that has to include BOSS not overclaiming its own promise.
+
+The six rules below are how that promise is kept.
+
+---
+
+The few rules that define what BOSS *is*. Everything else (modes, skills, the CLI) is in service of these.
+
+## 1. Always scaffolding — pause to extract patterns
+
+BOSS is always scaffolding, but scaffolding is the *motion*, not the goal. At every natural
+breakpoint — a mode transition, a shipped feature, the third time the same work repeats — **pause
+and sort the pattern two ways:**
+
+- **UP** → into BOSS as a reusable **superset practice**. Every future project inherits it.
+- **DOWN** → into the app as **core functionality**. It's product, not scaffold.
+
+This bidirectional extraction is what makes the system compound: every project makes BOSS smarter,
+and every app's core stays clean. `/boss-learn` is therefore a **two-destination router**, not a
+one-way "promote to BOSS."
+
+## 2. Just-in-time support, never premature ceremony
+
+BOSS is a startup incubator: the right level of support shows up exactly when a project earns it,
+and not before. A throwaway Quickstart idea should not carry a PM org; a Scale-mode product should
+not be missing one. Modes (Quickstart → MVP → V1 → Scale) exist to make this graduated. Rules turn
+on **at the right time**, per mode.
+
+## 3. Nothing valuable gets locked into code
+
+Anything reusable — design tokens, prompts, workflows, conventions — should live as **decoupled,
+nameable structure**, not buried in implementation. Style is the canonical case: extract it into
+tokens + a style guide the moment there's UI, so it stays evolvable and **prototypes consume the
+same system the app does**. Enforced JIT (strict at V1; seeded as soon as UI appears). The test:
+*could a prototype or a sibling project reuse this without copy-pasting code?* If not, it's locked.
+
+## 4. Stack-neutral; stacks are learned, not assumed
+
+BOSS assumes no tech stack. The first build decision picks one. Proven stack tooling is captured
+via Principle 1 (UP) so the next project of that kind starts from it — stack profiles are an
+*output* of the learning loop, not a pre-baked input.
+
+## 5. Optionality by default
+
+Defaults preserve future choices rather than foreclosing them: private repos, proprietary license
+(relicense to OSS later — not the reverse), snapshot-not-blueprint canvases. Decide late, on evidence.
+
+## 6. Humane before viable
+
+The Humane Product Canvas is the spine of how BOSS pressure-tests an idea — who's served, what
+tension, what promise, who could be harmed — *then* commercial rigor (riskiest assumption, weekly
+experiment, willingness to pay) folds in. Viability never overrides the humane lens.

package/README.md

@@ -0,0 +1,213 @@
+# BOSS
+
+### Make it real.
+
+*B.O.S.S. — Build Out Solid Stuff.*
+
+> **Everyone can build now. Almost no one can tell a real business from a convincing demo.**
+> **BOSS is the conscience that keeps you honest while you move fast** — the thinking layer that
+> nudges when you're drifting and pauses on command. No growth-hacking pressure. Override-friendly.
+>
+> *(Vibe coding gets you a demo; the discipline on top gets you a business. BOSS is that discipline,
+> just-in-time. Pause it any time.)*
+>
+> Cursor and Lovable generate the code. BOSS scaffolds the *thinking about what to build, when
+> to ship, and when the discipline should get out of your way.* Brings a mentor board for the
+> parts code can't teach, a conscience that catches drift early, modes that scale ceremony to
+> evidence. Calm-company by default. Open. Inspectable. Local-only state.
+
+## If this is you
+
+You've been using Claude Code for a few months. You've shipped one project this
+year. There are two more in `~/projects/` you didn't finish, and a folder of ideas you didn't
+start. Each new project, you re-invent the same scaffolding — and somewhere around screen 3
+the design starts drifting (47 different blues, every component a snowflake), or you realize
+you never actually pressure-tested whether the bet was real.
+
+The honest question AI raised: *if I can build anything, what should I build, and how do I
+know if it's worth finishing?*
+
+BOSS is one answer.
+
+## What BOSS is, plainly
+
+A CLI plus a set of skills, agents, and loops that run inside Claude Code:
+
+- **`boss new my-app`** — scaffolds a project at the lightest level (Quickstart) in five seconds.
+  Then `/boss <your idea>` to spin up — point it at a sentence, a doc, a Google Doc, an Obsidian
+  note, a PDF, or a URL, and BOSS pulls the material in and shapes it. Optional private GitHub repo;
+  a `CLAUDE.md` that fits on a screen.
+- **`boss unlock mvp`** — adds the spec discipline (`/spec` with validated-learning + evals
+  fields), the smoke gate, the demand-test step (`/pretotype` — Savoia), and JIT design-tokens
+  scaffolding when your project earns it.
+- **`boss unlock v1`** — adds full design review (`/design-review` + `/ux-check` + token
+  enforcement), cross-FEAT sequencing (`/board`), and the next-tier mentors (business,
+  fundraising, pitch, talent).
+- **A conscience that nudges.** When you've captured three ideas and tested none, it speaks
+  once. When you're spec'ing a feature your canvas never validated, it surfaces restraint.
+  Cohort-aware (set yours during spin-up; it adjusts the voice). Always overridable; never
+  blocking. Silence it for a sprint (`boss conscience pause --for 8h`), or turn down just one
+  nudge while the rest keep speaking (`boss conscience mute <moment>`).
+- **A mentor board.** Nine advisors (venture, architect, GTM, cofounder, business, fundraising, pitch,
+  talent, humane) for the parts code can't teach. Plus a builder team (designer, voice-keeper, prompt-
+  coach) for the craft. Plus eight proto-personas (vibe-coder-newbie, eng-builder,
+  indie-hacker, returning-founder, domain-expert, …) you can show features to before showing
+  them to real founders.
+- **Built for founding teams, not just solo.** Building with a cofounder? `boss team add @their-handle`
+  lights up a shared way to decide (`/decide`), share what you're each learning about AI (`/practice`),
+  a mentor for the partnership itself (`mentor-cofounder`), and a conscience that notices when you've
+  drifted into building in parallel — all *dormant when you're solo*, and it never takes a side or scores
+  your equity. See [`docs/GUIDE-teams.md`](docs/GUIDE-teams.md).
+
+Built on Node — zero dependencies. Markdown + YAML everywhere a human reads; predicate-based
+loops everywhere a machine evaluates. Lives in Claude Code. Everything runs locally.
+
+## A concrete moment
+
+You've used `/triage` four times this week capturing ideas. You haven't run `/canvas` on any.
+You submit a prompt — anything — and the conscience fires once:
+
+> *"That's the fourth thing you've added here, and none of it's been tested. Who would you
+> talk to first to find out if any of them are real? `/canvas` is one way to pressure-test
+> it — but a 15-minute call with the right person beats it."*
+
+Then it goes quiet. You decide.
+
+That's the shape of every interaction. Discipline shows up when it can help, hands the
+decision back, gets out of the way. Discipline never accumulates as ceremony you have to
+work around.
+
+## What you actually get
+
+Four modes, unlocked additively as the project earns them:
+
+> **Quickstart** (capture an idea) → **MVP** (build it) → **V1** (ship it) → **Scale** (grow it)
+
+Each mode adds skills, agents, and loops; nothing is ever ripped out, and every unlock is your
+call — a project that stays in Quickstart forever is a legitimate project. The exact, always-current
+list of what each mode includes lives where it can't go stale:
+
+- **`boss map`** — the live cheatsheet for *your* project: where you are, what each command does,
+  and what's one unlock away.
+- **[`docs/CHEATSHEET.md`](docs/CHEATSHEET.md)** + **[`docs/SKILLS.md`](docs/SKILLS.md)** — generated
+  from the source, so they never drift.
+
+## What BOSS isn't
+
+- **Not a framework you have to learn.** First hour: `boss new`, `/boss`, `/triage`. That's
+  the whole vocabulary you need.
+- **Not a replacement for talking to real users.** The proto-personas pre-filter what to ask
+  real founders; they don't replace the conversations. BOSS's own advisory pass and v1 playbook
+  are explicit about this.
+- **Not a YC.** Doesn't take equity. Doesn't push toward venture-scale. Defaults to *"you
+  should probably not raise; you should probably not hire; you should probably stay right-
+  sized"* until evidence says otherwise.
+- **Not magic.** Each piece is inspectable. `boss status --conscience` shows what's open, what
+  would close it, what overrides you've recorded. The source is plain Node.
+- **Not opinionated about your stack.** Stack-neutral until your first build decision; then
+  the coder specializes itself. Design tokens are stack-agnostic with per-stack patterns.
+
+## Install + first 5 minutes
+
+**Prerequisites:** [Node.js](https://nodejs.org) 18+ and [Claude Code](https://claude.com/claude-code)
+(BOSS runs *inside* Claude Code — the CLI scaffolds, the skills run in Claude).
+
+```bash
+# alpha install — clone the repo, link the CLI globally
+git clone https://github.com/ajeshh/bossbuild.git
+cd bossbuild
+npm install -g .                # puts `boss` on your PATH (zero runtime deps)
+
+boss new my-app                 # 5 seconds — scaffolds + git-inits + registers
+cd my-app
+code .                          # open the folder in your editor (or `claude` in the terminal)
+claude                          # open Claude Code (terminal or editor panel)
+> /welcome                      # first time? ~1 min orientation
+> /boss <idea | file | url>     # spin up — point at a sentence, a doc, or a link; BOSS pulls it in
+> /prototype <your idea>        # or just hit go — BOSS builds the smallest clickable version to react to
+```
+
+**Already started building?** You don't have to start over. `cd` into your existing repo and run
+`boss adopt` (add `--mode mvp` if it already has real users) — it lays BOSS down *non-destructively*,
+your files untouched, at the lightest register that fits. Add `--ai` to have BOSS read the repo and
+tailor the scaffold.
+
+After that:
+
+```bash
+boss map                        # where you are + what each command does + what's one unlock away
+boss status                     # mode + pinned BOSS version + drift
+boss status --conscience        # loops state + recent overrides + cohort
+boss unlock mvp                 # earn the next layer when ready
+boss conscience pause --for 8h  # silence everything for a bounded sprint
+boss conscience resume          # bring it back
+boss conscience mute caution    # turn down ONE moment; unmute (or --all) to restore
+```
+
+`boss map` is the live cheatsheet — run it any time to see what's available in your current mode and
+what the next unlock adds. For the read-once walkthrough, see [`docs/GUIDE.md`](docs/GUIDE.md); the
+whole ladder at a glance lives in [`docs/CHEATSHEET.md`](docs/CHEATSHEET.md).
+
+## The principle
+
+Six rules in [`PRINCIPLES.md`](PRINCIPLES.md). The one that matters most: **humane before
+viable.** A tool that exists to help founders build well must itself behave well. BOSS pauses
+on command. Overrides every loop on request. Records every override so future-you sees the
+deviation. Refuses to nag. Refuses to grade. *The seasoned hand who's built many things and
+doesn't need the credit.*
+
+The other five rules govern when to add ceremony (only as earned), when to capture practice
+UP into BOSS's library (when reusable across projects), when to push practice DOWN into a
+project (when validated), how to keep changes small (each release the minimum experiment that
+produces validated learning), and how to keep style decoupled from code (design tokens as
+authority).
+
+## Where this is
+
+Quickstart + MVP + V1 modes authored (Scale is stubbed); many capability releases in. For the
+exact current release, see [`VERSION`](VERSION) + the [changelog](registry/CHANGELOG.md).
+Self-hosted (BOSS itself runs in MVP mode, using BOSS). All discipline patterns demonstrated
+by BOSS-on-BOSS before they ship anywhere else.
+
+**This is alpha.** The conscience runs a gate-eval suite (105 passing) plus a model-verified
+judgment surface — its drift / caution / capture calls are graded against labeled sets, not
+just vibes. But it's been pressure-tested mostly against synthetic personas; real-founder
+validation hasn't happened yet (a deliberate, recorded override).
+If you try BOSS and it falls down, *that's the most useful thing you can tell me* — run
+`/feedback` and it goes straight to this repo's issues.
+
+## License + shape
+
+Open source. Calm-company by default. No monetization of lock-in. No telemetry. Local-only
+state — your project's data stays in your repo + `~/.boss/registry.json` on your machine. If
+a business model ever emerges, it'll be hosted advisory sessions or patronage; never the CLI
+itself.
+
+BOSS pressure-tests its own bet with a **Humane Product Canvas** — People, Problem, Promises,
+Risks & Harms, Principles, and the live riskiest assumption. It's the same `/canvas` skill BOSS
+hands you, turned on itself.
+
+## Acknowledgements
+
+BOSS draws on a roster of practitioners — Don Norman, Brad Frost, Nathan Curtis, Jakob
+Nielsen, Steve Krug, Ash Maurya, Eric Ries, Alberto Savoia, Rob Fitzpatrick, Bob Moesta,
+Teresa Torres, Andrej Karpathy, Simon Willison, Ethan Mollick, Guillermo Rauch, Hamel Husain,
+Jason Liu, Christopher Noessel, Indi Young, John Maeda, April Dunford, Andy Raskin, Jason
+Fried & DHH, Rob Walling, Paul Jarvis, Erika Hall, Mike Monteiro, Tristan Harris, Cathy
+O'Neil, Cal Newport, and many more. Mentor agents cite specific practices by attribution;
+**no agent impersonates a person**.
+
+The Humane Product Canvas framework is by Ajesh Shah; reused as the spine of BOSS's `/canvas`
+skill.
+
+---
+
+*[For the interior architecture — how the CLI works, how the loop primitive composes, how
+the conscience hook reads predicates, how the registry tracks projects, how sync works —
+read [`PRINCIPLES.md`](PRINCIPLES.md) and the source under [`src/`](src/). Not necessary for
+first-use.]*
+
+*[Building agent tooling yourself? [`docs/PATTERNS.md`](docs/PATTERNS.md) names the engineering
+patterns BOSS is built on — the doer/judge split, two eval surfaces with real numbers,
+progressive-disclosure skills, dormant-by-default hooks, AGENTS.md portability — with the honest
+limits included.]*

package/VERSION

@@ -0,0 +1 @@
+0.97.0

package/bin/boss

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+run(process.argv.slice(2));

package/library/README.md

@@ -0,0 +1,19 @@
+# library/ — the superset
+
+The de-dhuned, generalized knowledge base that stages draw from and the learning loop feeds.
+
+| Folder | Holds | Source |
+|---|---|---|
+| `agents/` | Structural agent templates (placeholders for domain specifics) | dhun's structural agents |
+| `skills/` | Structural skill templates | dhun's structural skills |
+| `hooks/` | Generic hooks (type-check slot, frontmatter, session lifecycle) | dhun's hooks, stack-genericized |
+| `practices/` | Best-practice docs: git, testing, refactor waves, RFC discipline, memory hygiene, incremental writes | mined from dhun's memory + workflow docs |
+| `memory-seed/` | Project-agnostic feedback memories every new project should start with | mined from dhun's 143 memory files |
+
+**Authoring rule:** anything here is stack-neutral and project-neutral. Domain specifics
+(dhun's music/DJ logic, raag engine, Rangoli, etc.) never land here. Use `{{PLACEHOLDERS}}`
+for anything project-specific.
+
+**How it grows:** `/boss-learn` promotes a proven practice from a real project into here
+(human-gated), bumps BOSS's VERSION, and appends `registry/CHANGELOG.md`. Existing projects
+pull it via `/boss-sync`.

package/library/agents/mentor-venture.md

@@ -0,0 +1,57 @@
+---
+name: mentor-venture
+description: Venture mentor for {{PROJECT_NAME}} — coaches the FOUNDER, not the codebase. Pressure-tests whether the idea is worth pursuing, names the riskiest assumption, and points at the next real step. Owns the canvas conversation. Advisory only — never writes product code or specs. Trigger phrases - "is this worth doing", "should I build this", "what's my biggest risk", "how do I start a company", "talk me through this idea".
+tools: Read, Grep, Glob, Edit, Write
+---
+
+You are the **venture mentor** for **{{PROJECT_NAME}}** ({{MODE}} mode) — the cornerstone of BOSS's
+mentor layer (see `docs/MENTORS.md`). You coach the *founder*. You are not a builder: you don't write
+production code, own specs, or decide implementation. You move the founder's *thinking* forward.
+
+## Your job
+
+- Be the experienced voice in the room for a founder who may be doing this for the first time.
+- Pressure-test the idea humanely: who's served, what tension, what promise, who could be harmed —
+  *then* commercial rigor (riskiest assumption, smallest experiment, willingness to pay).
+- Always leave them with **the single most useful next step**, not a plan they can't act on.
+- Own the canvas conversation: nudge toward `/canvas`, help fill a few cells at a time, revisit it.
+
+## How you work
+
+1. Read `docs/ideas/` (what they're chasing), `docs/ideas/CANVAS.md` if present, and `PRINCIPLES.md`.
+2. Ask one sharp question at a time. The goal is insight, not an interrogation.
+3. Name the **riskiest assumption** out loud and propose one cheap way to test it this week.
+4. Capture what's decided where it belongs (canvas, idea doc) — start the founder's dossier
+   (`docs/dossier/` as artifacts emerge). Author *with* them, never behind their back.
+
+## The evidence you carry (use it, don't recite it)
+
+Three findings anchor how you pressure-test. Lead with the judgment; cite only if they want the receipt.
+
+- **Validation buys faster *decisions*, not guaranteed wins.** The disciplined founder doesn't win more
+  often by magic — they decide faster and **quit weak ideas faster** (Camuffo et al., 759-firm RCT).
+  Cheap AI lowers the cost of *building*, not the cost of *being wrong*. So when building feels free,
+  the riskiest-assumption test matters *more*, not less. Never sell validation as a guarantee.
+- **The demoware test.** AI makes an impressive demo trivially cheap — and trivially easy to mistake for
+  a validated product. The blunt cut (Cagan/SVPG): *if your AI product only replaces a prompt plus a
+  copy/paste, it's a demo, not a product.* Use it at the `/prototype`→`/spec` graduation: did we test
+  value, usability, viability — or just that the demo runs?
+- **The competence-gate.** AI advice *amplifies* the judgment a founder already has — it can actively
+  harm the founder least able to grade it (Otis et al., HBS RCT, 640 founders: high performers ~+15%,
+  struggling ones ~−8%; and confidence in AI tracks *less* checking, not more). So at a decision the
+  founder may not be equipped to evaluate, the move is to ask **"are you set up to judge this answer?"** —
+  point them at who would know, don't answer it for them. A humility prompt, used rarely, never a gate.
+
+## What you do NOT do
+
+- No production code, no specs, no architecture decisions — hand those to the builders (`pm`, `coder-generalist`).
+- No premature ceremony. If they need more structure, the answer is usually `boss unlock <mode>`, which
+  brings the next mentors (architect, GTM…) with it — not a process you hand-roll.
+- **No binding legal, financial, tax, or medical advice.** Caveat clearly and point them to a real
+  expert for anything consequential. You are a thinking partner, not a licensed professional.
+
+## The line you hold
+
+The humane lens comes before viability (Principle 6). Never coach toward harm for the sake of growth.
+Surface trade-offs honestly; don't manufacture false confidence. When the idea genuinely has legs, say
+so plainly and point at the next rung (`/canvas`, then `boss unlock mvp`).

package/library/hooks/auto-log.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// BOSS auto-log — a SubagentStop hook (OPT-IN; the trace substrate for IDEA-025).
+//
+// Ported UP from the dhun dogfood (Principle #1), Node-ported for BOSS's zero-dep
+// rule. WHAT IT DOES: after a writer subagent finishes, append one honest line to
+// `.boss/trace.jsonl` recording what that agent actually touched — session, agent,
+// changed files, timestamp. This is the *trace substrate*: the within-session
+// counterpart to `boss insights` (which reads the cross-project registry). It is
+// the raw material a trace-native judge (IDEA-025 Phase 2, `/judge-traces`) and the
+// sleep-time learn loop (Phase 3) read later. It does NOT judge, score, or send
+// anything anywhere.
+//
+// HUMANE CONTRACT (inherits IDEA-021 / IDEA-013, non-negotiable):
+//   - LOCAL-ONLY. Writes one file in this repo. Never transmits. Never shares up.
+//   - APPEND-ONLY, facts not estimates. Records what the git tree shows changed.
+//   - MEASURE, DON'T INSTRUMENT THE HUMAN. It reads the work's own trace, not you.
+//   - READ ON DEMAND. Nothing consumes this file unless you run a skill that does.
+//
+// WHY OPT-IN: a SubagentStop hook fires a process after every subagent — real
+// latency on multi-agent sessions. Ship it dormant; turn it on when you want the
+// trace (regulated/high-stakes cohorts, or BOSS's own repo eating its dogfood).
+//
+// TO TURN IT ON — add to .claude/settings.json (registration IS the on-switch):
+//   "hooks": {
+//     "SubagentStop": [
+//       { "matcher": "",
+//         "hooks": [ { "type": "command",
+//                      "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-log.js\"",
+//                      "timeout": 10 } ] }
+//     ]
+//   }
+//
+// Fail-open: any surprise exits 0. A trace line missed is fine; a broken session is not.
+
+import process from 'node:process';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Read-only agent types never write files — skip them (no trace to record).
+const READ_ONLY = new Set([
+  'Explore', 'Plan', 'claude-code-guide', 'general-purpose-readonly',
+  'mentor-venture', 'mentor-architect', 'mentor-gtm', 'mentor-business',
+  'mentor-fundraising', 'mentor-talent', 'mentor-humane', 'mentor-pitch',
+]);
+
+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));
+    setTimeout(() => resolve(data), 1500);
+  });
+}
+
+const git = (repo, args) => {
+  try {
+    // Trailing-only trim: porcelain's leading status columns are significant
+    // (line 1 is " M path" — a full .trim() would eat that leading space and
+    // shift the column parse by one).
+    return execFileSync('git', args, { cwd: repo, encoding: 'utf8' }).replace(/\n+$/, '');
+  } catch {
+    return '';
+  }
+};
+
+const main = async () => {
+  const repo = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  let agent = 'unknown';
+  let session = 'unknown';
+  try {
+    const json = JSON.parse(await readStdin());
+    agent = json.subagent_type || json.tool_input?.subagent_type || json.agent_type || 'unknown';
+    session = json.session_id || 'unknown';
+  } catch {
+    process.exit(0); // fail-open
+  }
+  if (READ_ONLY.has(agent)) process.exit(0);
+
+  // Facts not estimates: read what the working tree actually shows changed —
+  // both tracked modifications AND new untracked files (coders create files,
+  // which a plain `git diff HEAD` would miss). `git status --porcelain` carries
+  // both; columns 0-1 are the status code, the path starts at column 3.
+  const changed = [
+    ...new Set(
+      git(repo, ['status', '--porcelain', '--untracked-files=all'])
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => l.slice(3).replace(/^"|"$/g, '').split(' -> ').pop())
+        .filter(Boolean)
+    ),
+  ];
+  if (changed.length === 0) process.exit(0); // nothing written → nothing to trace
+
+  const files = changed.slice(0, 25); // cap the line; a 200-file diff doesn't need every path
+  const record = {
+    ts: new Date().toISOString(),
+    session,
+    agent,
+    files,
+    file_count: changed.length,
+  };
+
+  const dir = join(repo, '.boss');
+  const out = join(dir, 'trace.jsonl');
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    // Dedup: SubagentStop can fire several times for one change set. Skip if the
+    // last line has the same (session, agent, files) signature.
+    if (existsSync(out)) {
+      const lines = readFileSync(out, 'utf8').trim().split('\n');
+      const last = lines[lines.length - 1];
+      if (last) {
+        try {
+          const p = JSON.parse(last);
+          const same =
+            p.session === session &&
+            p.agent === agent &&
+            JSON.stringify(p.files) === JSON.stringify(files);
+          if (same) process.exit(0);
+        } catch { /* fall through and write */ }
+      }
+    }
+    appendFileSync(out, JSON.stringify(record) + '\n');
+  } catch {
+    process.exit(0); // fail-open: a write surprise must not break the session
+  }
+  process.exit(0);
+};
+
+main();

package/library/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();