@sal-sovereign-ai-labs/whyline 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SAL Sovereign AI Labs
+
+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/README.md

@@ -0,0 +1,129 @@
+# Whyline
+
+`git blame` tells you who. Whyline tells you why.
+
+Every line an AI agent writes keeps the prompt that caused it, the session, the cost, the other files that task touched, whether a human edited it since, and whether it was meant to be temporary. Temporary code gets a lifecycle: it is recorded at birth, becomes due when its condition is met, and Bob removes it with evidence and your approval.
+
+Built for IBM Bob 2.0. Bob's free lifecycle hooks record every write; six skills turn the records into answers inside Bob; git notes store everything. Last year's winner, Pedigree, proved that a commit was AI-written, for auditors. Whyline keeps why each line exists and acts on it, for developers.
+
+Live demo report (the demo shop after the payments-v2 merge, rebuilt by CI): https://sal-sovereign-ai-labs.github.io/whyline/
+
+![Whyline architecture: Bob writes, hooks record, a commit seals a git note, commands answer, Bob acts](docs/architecture.svg)
+
+## Install in a repo
+
+```sh
+npm install -g @sal-sovereign-ai-labs/whyline
+cd your-repo
+whyline init                  # writes .bob/ (hooks and skills) and git hooks
+git add .bob && git commit -m "add whyline"
+```
+
+Then work in Bob as usual. Nothing new to type.
+
+## Ask
+
+```sh
+whyline why src/payments/checkout.py:12   # who wrote it, and why
+whyline check                             # temporary code and its lifecycle state
+whyline unreviewed                        # AI lines no human has edited since, with coverage if you have a report
+whyline keep flags.yaml "beta flag stays until Q1 review"     # name the file, a symbol, a kind, or the id
+whyline until legacy_export.py 2027-01-01
+whyline watch mock_gateway.py --symbol MockGateway            # fix the symbol the reference check looks for
+whyline seed --dry-run                    # existing repo: find temporary-looking code that predates whyline
+```
+
+Lifecycle of a temporary item:
+
+```
+active --(condition met: date passed, or no references left)--> due --(you decide)--> kept | removed
+```
+`active` and `due` are recomputed from the repo on every `check`, so they never go stale. `kept` and `removed` are recorded decisions. Bob never changes a state on its own.
+
+In Bob, in normal Agent mode: ask "why does this line exist?", say "remove the mock payment gateway", or "keep the beta flag until Q1". The installed skills run the right whyline command; removals end in Bob's own approval prompt.
+
+## How it works
+
+1. `UserPromptSubmit` and `PostToolUse` hooks record the prompt and the exact lines each write touched (`.git/whyline/session.jsonl`).
+2. On commit, a git hook compares what the agent wrote with what was committed: `ai`, `ai-edited`, or human. It attaches one JSON note to the commit on `refs/notes/whyline`. Nothing lands in your working tree.
+3. Writes that look temporary (mock, demo, flag, shim, fixture, "until ...") become items with a removal condition: a date, or "no references left".
+4. `whyline check` evaluates the conditions. Removal happens in Bob through the whyline-remove skill and Bob's normal approval prompt.
+
+Costs 0 Bobcoins. Hooks are deterministic; Bob is only used for removals. When a Bob task spans several commits, every commit keeps the same prompt.
+
+## Status
+
+Hackathon build (IBM Bob 2.0 Hackathon, 25 to 27 Sep 2026). See docs/ for the research, evidence and architecture.
+
+## CLI
+
+| Command | Purpose | Exit code |
+|---|---|---|
+| `whyline init` | install Bob and git hooks in the current repo | 0, 3 if not a git repo |
+| `whyline why <file>:<line> [--json]` | origin, prompt, session, cost, siblings, item | 0 |
+| `whyline check [--json] [--gate]` | temporary items with lifecycle state and evidence | 0; with `--gate`, 2 when any item is due |
+| `whyline unreviewed [--json]` | AI lines with no human edit since, per file, coverage from coverage.xml or lcov.info | 0 |
+| `whyline watch <item> --symbol Name` | change the symbol the reference check searches for | 0 |
+| `whyline removed <item>` | record a removal done by hand (a commit message naming the file or id records it automatically) | 0 |
+| `whyline seed [--dry-run] [--by-name]` | on an existing repo, record code carrying TODO remove, FIXME, HACK, temporary or until markers, with its age from git; `--by-name` also records mock_, compat_, examples/ and fixtures/ names | 0 |
+| `whyline keep <item> "<reason>"` | mark an item permanent; `<item>` is a file, symbol, kind or id | 0 |
+| `whyline until <item> <YYYY-MM-DD>` | set a date condition | 0 |
+| `whyline bom [A..B] [--json]` | AI bill of materials for a commit range: lines changed, AI lines by agent, reviewed, items shipped, cost | 0 |
+| `whyline report [--out file]` | one offline HTML page with every answer; regenerated after each commit | 0 |
+| `whyline capture`, `whyline session-start`, `whyline commit` | hook entry points, always exit 0 | 0 |
+
+`--json` prints machine-readable output with no ANSI codes. Environment: `WHYLINE_DEBUG=1` prints stack traces to stderr, `WHYLINE_BOB_DB` overrides the Bob database path.
+
+## Known limitations
+
+- When git metadata is stripped: a squash merge creates a new commit without the notes of the squashed ones, and a repo copied without `refs/notes/whyline` has no notes at all. The fix is to keep merge commits (or copy notes onto the squash commit with `git notes --ref whyline copy`), and to push and fetch the notes ref, which the installed pre-push and post-merge hooks do. Amend and rebase keep notes because init sets `notes.rewriteRef`.
+- The reference check is text search (git grep for the symbol and the module name). Code reached only through strings or reflection can look unreferenced, which is why removal always goes through Bob's evidence step and your approval.
+- "Unreviewed" means no human edit since the agent wrote the line. Review comments and PR approvals are not read yet.
+- Recording starts at `whyline init`. Code written before that has no note and shows as human. `whyline seed` recovers temporary-looking code from before that point, but not who wrote it or why beyond the comment.
+- Hook commands print their one status line to stderr so that stdout stays empty for the agent. `git commit` shows it; tooling that hides stderr will not.
+
+## Speed
+
+`npm run bench` builds the demo repo and times each command, median of 10. On a MacBook Pro with an Apple M1 Pro, Node 26: capture hook 165 ms (the only thing on Bob's write path), `why` 267 ms, `check` 344 ms, `bom` 560 ms, `unreviewed` 592 ms, session-start line 899 ms, `report` 2.0 s (runs in the background after a commit). Recording costs 0 Bobcoins.
+
+## Built with IBM Bob
+
+Bob is inside the product (three lifecycle hooks, six skills, the session-start line, removal through Bob's own approval prompt) and Bob built part of it: 16 Bob IDE tasks across two developers, 29 Bobcoins, task summaries in [bob_sessions/](bob_sessions/) with costs in [bob_sessions/costs.md](bob_sessions/costs.md). Bob also used Whyline on Whyline's own repository and reported five issues; three became fixes (docs/04, section 11). The rest of the code, tests and docs were written by the team with other tools.
+
+## Business model
+
+The CLI is free and MIT. Organisations pay for policy: enforced hooks rolled out to every developer (Bob's EnforcedHooks group policy) and the report as a compliance record per release.
+
+## Troubleshooting
+
+| Symptom | Do this |
+|---|---|
+| `whyline why` says "git blame failed" | The file is not tracked, or you are in the wrong repo. `git ls-files <file>`. |
+| `check` prints "no temporary items yet" | Nothing Bob wrote has been committed since install. Commit once, then `whyline check`. |
+| No note after a commit | `whyline` is not on the PATH for git hooks (`npm link`), or the hooks were not installed (`whyline init`). See `.git/whyline/hook.err`. |
+| Bob does not record anything | The workspace is not trusted (Bob skips workspace hooks in untrusted folders), or `.bob/settings.json` was not committed. `whyline init` again. |
+| Cost shows as null | Bob IDE stores task cost elsewhere than Bob Shell, or sqlite3 is missing. The note is still complete. |
+
+## Uninstall
+
+Delete `.bob/hooks/whyline.sh`, the whyline lines in `.bob/settings.json`, and `.git/hooks/post-commit`, `post-merge`, `pre-push`. Bob and git keep working; the notes stay in the repo under `refs/notes/whyline` until you delete that ref.
+
+## Requirements
+
+Node 20 or newer, git. Bob IDE 2.2 or Bob Shell 2.x for the hooks. macOS and Linux are tested in CI; Windows needs Git Bash for the shell hook and is untested.
+
+## Private by design
+
+Whyline itself makes no network calls. Prompts are stored verbatim in git notes in your own repository, and the installed git hooks push and fetch that notes ref together with your code, so prompts travel to wherever your code travels and nowhere else. Do not paste secrets into prompts; the generated report (`.whyline-report.html`) also embeds prompts and is excluded from commits by `whyline init` through `.git/info/exclude`.
+
+## Development
+
+```sh
+npm test            # tests on temp git repos
+npm run coverage
+npm run smoke
+```
+
+## License
+
+MIT

package/cli/index.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+'use strict';
+// whyline: provenance for AI-written code. Commands never throw at the agent: hook commands always exit 0.
+const fs = require('node:fs');
+
+const USAGE = `whyline <command> [--json]
+
+  init [--agent bob]        install the agent's hooks (.bob/) and git hooks in this repo
+  capture [--agent bob]     hook: read a hook payload on stdin, record the write (--dump or WHYLINE_DUMP=1 keeps raw payloads in .git/whyline/raw/)
+  session-start             hook: print a one-line summary for Bob's context
+  commit                    git post-commit: attach the provenance note to HEAD
+  why <file>:<line>         who wrote this line, and why
+  check [--json] [--gate]   temporary items and their lifecycle state (--gate: exit 2 when any is due, for hooks and CI)
+  unreviewed [--json]       AI lines no human has edited since, per file, with coverage if a report exists
+  bom [A..B] [--json]       AI bill of materials for a commit range (default: last tag..HEAD, else all)
+  report [--out file]       write the read-only HTML report (.whyline-report.html)
+  keep <item> "<reason>"    decision: keep permanently          (due -> kept)
+  until <item> <YYYY-MM-DD> change the condition to a date       (stays active)
+  watch <item> --symbol X   fix the symbol the reference check searches for
+  removed <item>            record a removal done by hand (a commit message naming the item does this automatically)
+  seed [--dry-run] [--by-name] first run on an existing repo: record code with TODO remove, FIXME, HACK, temporary or until markers; --by-name also records mock_, compat_, examples/, fixtures/ names
+
+  <item> is a file path (or its last part), a watched symbol, a kind (mock, demo, flag, shim, fixture) when unique,
+  or the id shown by check. People name files; ids are for notes and scripts.
+
+Lifecycle:  active --(condition met)--> due --(you decide)--> kept | removed
+            active and due are recomputed from the repo on every check; kept and removed are recorded.
+  --version, --help
+
+Exit codes: 0 ok, 1 usage or error, 2 only with check --gate when items are due, 3 not a git repository.
+Env: WHYLINE_DEBUG=1 prints stack traces to stderr. WHYLINE_BOB_DB overrides the Bob database path.
+`;
+
+function readStdin() {
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+const DEBUG = !!process.env.WHYLINE_DEBUG;
+function debug(area, msg) { if (DEBUG) process.stderr.write(`[whyline:${area}] ${msg}\n`); }
+
+function main(argv) {
+  try { return dispatch(argv); } catch (e) {
+    process.stderr.write(`whyline: ${e && e.message ? e.message : String(e)}\n`);
+    debug('main', e && e.stack ? e.stack : '');
+    return 1;
+  }
+}
+
+function dispatch(argv) {
+  const [cmd, ...rest] = argv;
+  const cwd = process.cwd();
+  const json = rest.includes('--json');
+  if (['why', 'check', 'unreviewed', 'bom', 'report', 'keep', 'until', 'watch', 'removed', 'seed'].includes(cmd) && !require('./lib/git').repoRoot(cwd)) {
+    process.stderr.write('not a git repository (run whyline inside a repo, or whyline init to set one up)\n'); return 3;
+  }
+  const agentIds = [];
+  const args = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--json') continue;
+    if (rest[i] === '--agent') { if (rest[i + 1]) agentIds.push(rest[++i]); continue; }
+    args.push(rest[i]);
+  }
+  switch (cmd) {
+    case '--version': case '-v':
+      console.log(require('../package.json').version);
+      return 0;
+    case '--help': case '-h': case 'help':
+      process.stdout.write(USAGE);
+      return 0;
+    case 'capture': {
+      const session = require('./lib/session');
+      try {
+        const raw = readStdin() || '{}';
+        if (args.includes('--dump') || process.env.WHYLINE_DUMP) dumpRaw(cwd, raw);
+        const payload = JSON.parse(raw);
+        require('./lib/capture').handle(payload, { cwd, agent: agentIds[0] });
+      } catch (e) { session.logError(cwd, `capture: ${e.message}`); debug('capture', e.stack || ''); }
+      return 0;
+    }
+    case 'session-start': {
+      // stdout is injected into Bob's context. One line, actionable, only when there is something to act on.
+      try {
+        const lenses = require('./lib/lenses');
+        const r = lenses.check(cwd);
+        const parts = [];
+        if (r.due.length) parts.push(`${r.due.length} temporary item(s) due for removal: ${r.due.map(i => `${i.file} (${i.id})`).join(', ')}. To act, say "remove ${r.due[0].file.split('/').pop()}" and the whyline-remove skill will guide the removal`);
+        const u = lenses.unreviewed(cwd);
+        if (u.totals.aiLines) parts.push(`${u.totals.aiLines} AI-written line(s) in ${u.totals.files} file(s) have had no human edit since (run: whyline unreviewed)`);
+        if (parts.length) process.stdout.write(`whyline: ${parts.join('. ')}\n`);
+      } catch { /* silent by design */ }
+      return 0;
+    }
+    case 'commit': {
+      try {
+        const r = require('./lib/commit').run(cwd);
+        if (r.removed && r.removed.length) process.stderr.write(`whyline: recorded removed: ${r.removed.join(', ')}\n`);
+        if (r.note) process.stderr.write(`whyline: note attached to ${r.commit.slice(0, 7)} (${r.note.ranges.length} range(s), ${r.note.items.length} item(s))\n`);
+      } catch (e) { require('./lib/session').logError(cwd, `commit: ${e.message}`); }
+      return 0;
+    }
+    case 'why': {
+      const m = (args[0] || '').match(/^(.+):(\d+)$/);
+      if (!m) { process.stderr.write('usage: whyline why <file>:<line>\n'); return 1; }
+      const r = require('./lib/lenses').why(cwd, m[1], +m[2]);
+      if (json) { console.log(JSON.stringify(r, null, 2)); return 0; }
+      printWhy(m[1], +m[2], r);
+      return 0;
+    }
+    case 'check': {
+      const gate = args.includes('--gate');
+      const r = require('./lib/lenses').check(cwd);
+      const exit = gate && r.due.length ? 2 : 0;
+      if (json) { console.log(JSON.stringify(r, null, 2)); return exit; }
+      if (!r.due.length && !r.active.length && !r.other.length) { console.log('no temporary items yet (commit something Bob wrote, then check again)'); return 0; }
+      printCheck(r);
+      return exit;
+    }
+    case 'unreviewed': {
+      const r = require('./lib/lenses').unreviewed(cwd);
+      if (json) { console.log(JSON.stringify(r, null, 2)); return 0; }
+      if (!r.files.length) { console.log('no AI-written lines recorded yet (commit something Bob wrote, then run again)'); return 0; }
+      console.log('file'.padEnd(44) + 'ai lines  edited ranges  coverage');
+      for (const f of r.files) console.log(`${f.file.padEnd(44)}${String(f.aiLines).padStart(8)}  ${String(f.editedRanges).padStart(13)}  ${f.coverage == null ? 'no data' : f.coverage + '%'}`);
+      console.log(`${r.totals.aiLines} unreviewed AI lines in ${r.totals.files} file(s)${r.totals.coverageSource ? `, coverage from ${r.totals.coverageSource}` : ', no coverage report found (coverage.xml or lcov.info)'}`);
+      return 0;
+    }
+    case 'bom': {
+      // Dev B's module: cli/lib/bom.js exporting bom(cwd, range) -> JSON per docs/10 and format(result) -> text
+      const mod = optional('./lib/bom');
+      if (!mod) { process.stderr.write('bom is not built yet (cli/lib/bom.js missing)\n'); return 1; }
+      const range = args[0] || defaultRange(cwd);
+      const r = (mod.bom || mod.run)(cwd, range);
+      console.log(json ? JSON.stringify(r, null, 2) : mod.format(r));
+      return 0;
+    }
+    case 'report': {
+      // Dev B's module: cli/lib/report.js exporting render(data) -> HTML string. The router gathers the data.
+      const mod = optional('./lib/report');
+      if (!mod) { process.stderr.write('report is not built yet (cli/lib/report.js missing)\n'); return 1; }
+      const lenses = require('./lib/lenses');
+      const git = require('./lib/git');
+      const root = git.repoRoot(cwd);
+      if (!root) { process.stderr.write('not a git repository\n'); return 3; }
+      const bomMod = optional('./lib/bom');
+      const range = defaultRange(cwd);
+      const idx = lenses.index(cwd);
+      const data = {
+        generatedAt: new Date().toISOString(),
+        repo: require('node:path').basename(root),
+        head: git.head(cwd),
+        check: lenses.check(cwd),
+        unreviewed: lenses.unreviewed(cwd),
+        bom: bomMod ? (bomMod.bom || bomMod.run)(cwd, range) : null,
+        why: mod.collect ? mod.collect(cwd, idx) : null,
+        sessions: [...idx.sessions.values()],
+        ranges: idx.ranges,
+        notes: idx.notes.length,
+      };
+      const outIdx = args.indexOf('--out');
+      const out = outIdx >= 0 && args[outIdx + 1] ? args[outIdx + 1] : require('node:path').join(root, '.whyline-report.html');
+      fs.writeFileSync(out, mod.render(data));
+      console.log(`report written: ${out} (${data.notes} note(s), ${data.ranges.length} range(s))`);
+      return 0;
+    }
+    case 'keep':
+    case 'until':
+    case 'watch':
+    case 'removed': {
+      const id = args[0], value = cmd === 'removed' ? (args[1] || 'removed by hand') : (args[1] === '--symbol' ? args[2] : args[1]);
+      const usage = { keep: '"<reason>"', until: '<YYYY-MM-DD>', watch: '--symbol <Name>', removed: '' }[cmd];
+      if (!id || !value) { process.stderr.write(`usage: whyline ${cmd} <file|symbol|kind|id> ${usage}\n`); return 1; }
+      if (cmd === 'until' && (!/^\d{4}-\d{2}-\d{2}$/.test(value) || isNaN(Date.parse(value + 'T00:00:00Z')) || new Date(value + 'T00:00:00Z').toISOString().slice(0, 10) !== value)) { process.stderr.write('until: date must be a real date in YYYY-MM-DD form\n'); return 1; }
+      const lenses = require('./lib/lenses');
+      const change = cmd === 'keep' ? { status: 'kept', reason: value }
+        : cmd === 'until' ? { status: 'active', condition: { type: 'date', on: value } }
+        : cmd === 'watch' ? { status: 'active', condition: { type: 'no_references', symbol: value } }
+        : { status: 'removed', reason: value };
+      const item = lenses.resolveItem(cwd, id);
+      const head = lenses.recordItemChange(cwd, item.id, change);
+      const said = { keep: 'kept permanently', until: `due on ${value}`, watch: `now watching symbol ${value}`, removed: 'recorded as removed' }[cmd];
+      console.log(`${item.file} (${item.id}): ${said} (recorded on ${head.slice(0, 7)})`);
+      return 0;
+    }
+    case 'seed': {
+      const r = require('./lib/seed').run(cwd, { dryRun: args.includes('--dry-run'), byName: args.includes('--by-name') });
+      if (r.error) { process.stderr.write(`seed: ${r.error}\n`); return 3; }
+      if (json) { console.log(JSON.stringify(r, null, 2)); return 0; }
+      for (const it of r.items) console.log(`  ${it.id}  ${it.kind.padEnd(8)} ${it.file.padEnd(40)} since ${it.created}  "${it.reason}"`);
+      if (r.items.length) console.log(`${r.items.length} item(s) ${args.includes('--dry-run') ? 'found (dry run, nothing recorded)' : 'recorded on ' + r.head.slice(0, 7)}. Next: whyline check`);
+      else console.log(`nothing new to seed from comment markers (${r.skipped} file(s) already tracked)`);
+      if (r.byNameOnly.length) console.log(`${r.byNameOnly.length} file(s) look temporary by name only (mock_, compat_, examples/, fixtures/): ${r.byNameOnly.slice(0, 5).join(', ')}${r.byNameOnly.length > 5 ? ', ...' : ''}. Add --by-name to record them.`);
+      return 0;
+    }
+    case 'init':
+      return require('./lib/init').run(cwd, { agentIds: agentIds.length ? agentIds : ['bob'] });
+    default:
+      if (!cmd) { process.stdout.write(USAGE); return 0; }
+      process.stderr.write(`Unknown command: ${cmd}\nRun whyline --help for usage.\n`);
+      return 1;
+  }
+}
+
+// Keep raw hook payloads for fixtures (one file per event). Never throws.
+function dumpRaw(cwd, raw) {
+  try {
+    const dir = require('./lib/session').dir(cwd);
+    if (!dir) return;
+    const d = require('node:path').join(dir, 'raw');
+    fs.mkdirSync(d, { recursive: true });
+    fs.writeFileSync(require('node:path').join(d, `${Date.now()}-${process.pid}.json`), raw);
+  } catch { /* fixtures are a convenience */ }
+}
+
+// Modules owned by the other developer may not exist yet on this branch.
+function optional(mod) { try { return require(mod); } catch (e) { if (e.code === 'MODULE_NOT_FOUND' && String(e.message).includes(mod.replace('./', ''))) return null; throw e; } }
+
+// Last tag to HEAD when a tag exists, else undefined, which bom.js treats as the whole history.
+function defaultRange(cwd) {
+  const git = require('./lib/git');
+  const tag = git.tryGit(['describe', '--tags', '--abbrev=0'], { cwd });
+  return tag ? `${tag}..HEAD` : undefined;
+}
+
+function printCheck(r) {
+  const col = (s, n) => String(s == null ? '' : s).padEnd(n).slice(0, n);
+  const row = it => `  ${col(it.id, 9)} ${col(it.kind, 8)} ${col(it.file, 38)} ${col(it.evidence ? it.evidence.summary : (it.reason || ''), 60)}`;
+  const section = (title, list) => { if (!list.length) return; console.log(`${title} (${list.length})`); console.log(`  ${col('id', 9)} ${col('kind', 8)} ${col('file', 38)} ${col('evidence', 60)}`); list.forEach(it => console.log(row(it))); };
+  section('DUE for removal', r.due);
+  section('ACTIVE', r.active);
+  section('DECIDED', r.other.map(it => ({ ...it, evidence: { summary: `${it.state}${it.reason ? ': ' + it.reason : ''}` } })));
+  const c = r.counts;
+  const next = r.due.length ? `Next: tell Bob "remove ${r.due[0].file.split('/').pop()}", or whyline keep <file> "<reason>", or whyline why <file>:<line>` : 'Nothing is due.';
+  console.log(`${c.active} active, ${c.due} due, ${c.kept} kept, ${c.removed} removed. ${next}`);
+}
+
+function printWhy(file, line, r) {
+  if (!r.found) { console.log(`${file}:${line}: ${r.reason}`); return; }
+  if (r.origin === 'human') { console.log(`${file}:${line}\norigin   human (${r.author || 'unknown'}, commit ${r.commit.slice(0, 7)})`); return; }
+  console.log(`${file}:${line}`);
+  console.log(`origin   ${r.origin} (${r.agent || 'agent'}) · session ${String(r.session).slice(0, 8)} · ${r.author || '?'} · ${r.ts ? r.ts.slice(0, 10) : '?'}${r.cost != null ? ` · ${r.cost} Bobcoin` : ''}`);
+  if (r.prompt) console.log(`prompt   "${r.prompt}"`);
+  if (r.siblings.length) console.log(`siblings ${r.siblings.join(' · ')}`);
+  if (r.item) console.log(`item     ${r.item.id} ${r.item.kind} · ${r.item.status} · ${JSON.stringify(r.item.condition)} · "${r.item.reason}"`);
+  console.log(`commit   ${r.commit.slice(0, 7)}`);
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+module.exports = { main };

package/cli/lib/agents/bob/assets/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "sh .bob/hooks/whyline.sh session-start --agent bob", "timeout": 5 }] }
+    ],
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "sh .bob/hooks/whyline.sh capture --agent bob", "timeout": 5 }] }
+    ],
+    "PostToolUse": [
+      { "matcher": "^(write_file|write_to_file|apply_diff|insert_content|search_and_replace)$",
+        "hooks": [{ "type": "command", "command": "sh .bob/hooks/whyline.sh capture --agent bob", "timeout": 5 }] }
+    ]
+  }
+}

package/cli/lib/agents/bob/assets/skills/whyline-check/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: whyline-check
+description: List temporary code that whyline says is due for removal
+metadata:
+  user-invocable: true
+  disable-model-invocation: true
+---
+
+Run `whyline check` with execute_command (exit code 0 is normal) and show its output as is. Do not edit anything. If items are due, tell the user they can say "remove <file name>" with the whyline-remove skill.

package/cli/lib/agents/bob/assets/skills/whyline-decide/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: whyline-decide
+description: "When the user wants to keep a temporary item permanently, move its due date, or fix the symbol whyline watches for, look the item up with whyline check --json and run the right whyline command (keep, until, or watch)."
+---
+## When to use
+Trigger phrases: "keep this item", "keep it permanently", "it's not temporary", "we're keeping this", "change the due date", "move the deadline", "due on", "extend the date", "it's due on", "watch for a different symbol", "fix the symbol", "wrong symbol", "watch symbol".
+
+## Workflow
+
+### Step 1 -- identify the item
+Run `whyline check --json` with execute_command. Parse the result.
+
+The result has three arrays: `due` (items whose condition is already met), `active` (items still waiting), and `other` (kept or removed). Each item carries:
+- `id` -- the stable identifier (e.g. `L-3f9a2c`)
+- `kind` -- `mock`, `demo`, `fixture`, `shim`, `flag`, or similar
+- `file` -- the source file
+- `lines` -- `[[start, end], ...]`
+- `reason` -- the original reason the item was created
+- `condition` -- `{ type: "date", on: "YYYY-MM-DD" }` or `{ type: "no_references", symbol: "Name" }`
+- `evidence` -- what the last evaluation found (e.g. "2 reference(s): ...")
+
+If the user named a specific item (by id, file, kind, or a description matching the reason), find it in the output. If the name is ambiguous or matches more than one item, show the candidates as a short table (id, kind, file, reason) and ask the user to choose. Never guess.
+
+If there are no items at all, tell the user and stop.
+
+### Step 2 -- confirm the action
+Show the chosen item:
+
+```
+id       <id>
+kind     <kind>
+file     <file>
+reason   "<reason>"
+condition  <current condition>
+```
+
+Then state the exact command you are about to run and ask for confirmation:
+- **keep**: `whyline keep <id> "<reason the user gave>"`
+- **until**: `whyline until <id> <YYYY-MM-DD>`
+- **watch**: `whyline watch <id> --symbol <Name>`
+
+For **keep**, ask the user for a short reason if they have not given one.
+For **until**, ask for the date in YYYY-MM-DD format if they have not given one. Reject any other format and ask again.
+For **watch**, ask for the symbol name if they have not given one.
+
+Do not run the command until the user says yes (or equivalent).
+
+### Step 3 -- run the command
+Run the confirmed command with execute_command and show its output verbatim.
+
+If the CLI exits non-zero (its exit code is 0 for normal answers, including a due list), stop and show its stderr as-is.
+
+### Step 4 -- confirm the change
+Run `whyline check --json` again and find the item. Show its new condition and state.
+
+## Rules
+- Never invent or guess an item id. Always read it from `whyline check --json`.
+- Never skip the confirmation step.
+- Dates must be YYYY-MM-DD; reject any other format.
+- Show null values as "no data", never as 0.
+- Trust the CLI output over any note in context.
+- These commands change recorded state in git notes. They are not reversible with a simple undo. Say so in the confirmation prompt.
+- Do not use this skill to remove items; that is handled by the whyline-remove skill.

package/cli/lib/agents/bob/assets/skills/whyline-remove/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: whyline-remove
+description: "When the user asks to remove, delete or clean up temporary code that whyline tracks (a mock, stub, demo, flag, shim or fixture, named in plain words, by file, or by id), remove it with evidence, tests and the user's approval. Works in Agent mode."
+---
+## When to use
+Trigger phrases: "remove the mock payment gateway", "remove mock_gateway.py", "delete the demo script", "clean up what whyline says is due", "remove L-12d3fa".
+
+## Workflow
+1. Find the item. Run `whyline check --json` with execute_command (exit code 0 is normal; the JSON is the answer). Match the user's words against `due` items by file name, symbol, kind or reason. If only an `active` item matches, say it is not due yet and why (its `evidence.summary`), then stop. If two items match, show both (file and id) and ask which one. Never guess.
+2. References. Quote the item's `evidence.summary`. Then run `git grep -n -w <symbol>` for every symbol defined in the item's lines. There must be no hits outside the item's file, its own tests, and documentation.
+3. Plan. List the exact files and line ranges to delete. If a test file only tests the item, include it. Nothing else.
+4. Dry run. Remove the ranges, run the project's test command (package.json scripts.test, Makefile test target, or pytest), record the pass and fail counts. If tests fail, put the files back and report.
+5. Present an evidence table (condition, references, tests, files, lines removed) and ask for approval. Do not edit anything before the user approves.
+6. After approval: keep the edit and commit with the message `remove <file name>: <reason>`. The git hook records the item as removed. Run `whyline check` and confirm it is listed under DECIDED as removed. Suggest /create-pr as the next step.
+
+## Rules
+- Evidence before edits. Every claim cites a command and its output.
+- Never widen scope: only the item's files, plus a test file that tests nothing else.
+- If the CLI exits non-zero (its exit code is 0 for normal answers, including a due list), stop and show its stderr as-is.
+- Never run git push. Never delete before approval.
+
+## Output template
+Evidence table, then "Proposed change:" with the files and lines, then the approval question. After approval: the commit id and the line from `whyline check` showing the item as removed.

package/cli/lib/agents/bob/assets/skills/whyline-setup/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: whyline-setup
+description: Install and enable whyline provenance tracking in the current repository when the user asks Bob to set it up
+metadata:
+  user-invocable: true
+  disable-model-invocation: true
+---
+
+## Step 1 -- check the whyline binary
+
+Run `command -v whyline` with execute_command.
+
+- **If it exits non-zero** (command not found): tell the user whyline is not installed and show the install command:
+  ```
+  npm install -g @sal-sovereign-ai-labs/whyline
+  ```
+  Then stop. Do not run any further steps until the user confirms the binary is available.
+
+- **If it exits 0**: continue to Step 2.
+
+## Step 2 -- run init
+
+Run `whyline init --agent bob` with execute_command in the repository root.
+
+- If the command exits non-zero or prints to stderr, stop and show its stderr as-is.
+- If it exits 0, show its stdout verbatim.
+
+## Step 3 -- tell the user what to commit
+
+After a successful init, tell the user:
+
+> Whyline is set up. Commit the `.bob` folder so your team gets the hooks:
+>
+> ```
+> git add .bob && git commit -m "chore: add whyline provenance hooks"
+> ```
+>
+> After that, every Bob session records the prompt that caused each write. Run `whyline check` at any time to see temporary items, or ask Bob "why does this line exist?" to trace any line.
+
+Do not edit any files. Do not run git commands yourself.

package/cli/lib/agents/bob/assets/skills/whyline-status/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: whyline-status
+description: "When the user asks what AI code is unreviewed, how much of a release or branch is AI-written, what an AI bill of materials says, or for the Whyline report, run whyline unreviewed, whyline bom or whyline report."
+---
+## When to use
+Trigger phrases: "what AI code is unreviewed", "what did the AI write in this release", "AI bill of materials", "how much of this is AI", "open the report".
+
+## Workflow
+- Unreviewed questions: run `whyline unreviewed --json` with execute_command.
+- Release or range questions: run `whyline bom <range> --json` where `<range>` is exactly what the user named (a tag pair like `v1.0..HEAD`, a branch pair like `main..HEAD`, or a single tag). Omit the range entirely to let whyline pick the last tag or the whole history.
+- Report requests: run `whyline report` and give the user the file path it prints.
+
+## Rules
+- Never invent a range, tag or item id; ask the user if it is unclear.
+- Show null values as "no data", never as 0.
+- Trust the CLI output over any note in context.
+- If the CLI exits non-zero (its exit code is 0 for normal answers, including a due list), stop and show its stderr as-is.
+- Read-only: never edit files or notes.
+
+## Output template
+For **unreviewed**: a table of file, AI lines, coverage (worst first), then the totals line.
+For **bom**: one table with rows: lines changed, AI lines (with % of lines changed), by agent, reviewed (with % of AI lines), tested, active items, due items, removed items, cost ("n of m sessions"); then list any missing data fields.
+End with one next command: `whyline why <file>:<line>` to trace a specific line, or tell the user to say "remove `<id>`" with the whyline-remove skill when any items are due.

package/cli/lib/agents/bob/assets/skills/whyline-why/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: whyline-why
+description: "When the user asks why a line exists, who wrote it, what prompt caused it, or whether a line is AI-written, run whyline why <file>:<line> --json and explain the result."
+---
+## When to use
+Trigger phrases: "why does this line exist", "who wrote this line", "what prompt caused this", "is this line AI-written", "why is this here", "trace this line", "whyline why".
+
+## Input
+Ask for a file path and line number if the user has not given one. Accept `<file>:<line>` notation directly.
+
+## Workflow
+Run `whyline why <file>:<line> --json` with execute_command.
+
+## Rules
+- Never guess the file or line number; ask the user if either is missing.
+- Show null values as "no data", never as 0.
+- Trust the CLI output over any note in context.
+- If the CLI exits non-zero (its exit code is 0 for normal answers, including a due list), stop and show its stderr as-is.
+- Read-only: never edit files or notes.
+
+## Interpreting the result
+- `found: false` -- git blame could not locate the line (file not tracked or line out of range). Show the `reason` field.
+- `origin: "human"` -- a human wrote this line. Show the author and short commit hash.
+- `origin: "ai"` -- the agent wrote every part of this line. Show all fields below.
+- `origin: "ai-edited"` -- a human and an agent both touched this line. Show all fields below.
+
+## Output template (ai-written or ai-edited)
+```
+<file>:<line>
+origin   <origin> (<agent>) · session <first 8 chars of session> · <author> · <date> · <cost> Bobcoin
+prompt   "<prompt>"
+siblings <sibling ranges, or "none">
+item     <id> <kind> · <status> · <condition> · "<reason>"   (omit line if item is null)
+commit   <short hash>
+```
+- Omit the `item` line when `item` is null.
+- Omit the `cost` segment when cost is null.
+- Omit the `siblings` line when the siblings array is empty.
+- End with one next command: `whyline check` to see all temporary items, or tell the user to say "remove `<item.id>`" with the whyline-remove skill if the item status is `due`.