@zuzuucodes/cli 1.2.0 → 1.2.2

package/README.md

@@ -40,7 +40,7 @@ zuzuu doctor      # health + lost-session reconciliation
 
 ¹ **Codex is interactive-only** — `codex exec` (headless) fires no hooks (verified, v0.138.0), so live capture + gate work when you run Codex interactively; headless Codex still gets post-hoc `zuzuu capture`.
 
-All five verified against **real sessions** — never fixtures; every host's live capture + gate was wired from **real captured hook payloads** and dogfooded end-to-end ([`experiments/LOG.md`](experiments/LOG.md) exp-11 Gemini/Codex, exp-12 OpenCode/pi). Gate semantics are host-honest: deny hard-blocks everywhere; `ask` maps to a native prompt on Claude, defers to the host elsewhere.
+All five verified against **real sessions** — never fixtures; every host's live capture + gate was wired from **real captured hook payloads** and dogfooded end-to-end ([`docs/LOG.md`](docs/LOG.md) exp-11 Gemini/Codex, exp-12 OpenCode/pi). Gate semantics are host-honest: deny hard-blocks everywhere; `ask` maps to a native prompt on Claude, defers to the host elsewhere.
 
 **Prerequisites:** Node ≥ 22 — that's it. You need at least one supported agent you've already used, so a session exists to capture. (Hacking on zuzuu itself? `git clone https://github.com/h1902y/zuzuu && cd zuzuu && npm link`.)
 
@@ -77,15 +77,14 @@ All five verified against **real sessions** — never fixtures; every host's liv
 
 | Path | What |
 |---|---|
-| [`zuzuu/`](zuzuu/) + `bin/zuzuu.mjs` | the CLI — capture, live lifecycle, faculty home (product surface) |
-| [`experiments/`](experiments/) | spike code + [`LOG.md`](experiments/LOG.md) — the build journal (hypothesis → real-data proof → conclusions per experiment) |
-| [`app/`](app/) | the durable application skeleton (be / run / evolve) — proven code harvests here |
+| [`zuzuu/`](zuzuu/) + `bin/zuzuu.mjs` | the CLI — capture pipeline (`zuzuu/capture/`), live lifecycle, faculty home (product surface) |
+| [`web/`](web/) | the visual workbench — nested project (daemon + React SPA), ships bundled inside the npm package |
 | [`tests/`](tests/) | hermetic unit + regression (`npm test`) + real-data smoke playgrounds (`npm run playground`) |
-| [`docs/`](docs/) | [`DESIGN.md`](docs/DESIGN.md) (the canon) + [`inspiration/`](docs/inspiration/) (the research shelf: 100-project survey + 5 audits) |
+| [`docs/`](docs/) | [`DESIGN.md`](docs/DESIGN.md) (the canon) + [`LOG.md`](docs/LOG.md) (the build journal) + [`inspiration/`](docs/inspiration/) (the research shelf) |
 
 ## How this is built (the method)
 
-**Experiment → prove on real data → conclude → harvest.** Every capability starts as a numbered experiment with a hypothesis; it must be verified against *real* sessions/wire data (never invented fixtures) before it counts; lessons land in the experiment’s Conclusions section; proven parts graduate into `app/`. Built in public — day-by-day on X ([@h1902y](https://x.com/h1902y)).
+**Prove on real data, record in the journal.** Every capability is verified against *real* sessions/wire data (never invented fixtures) before it counts; the record lives in [`docs/LOG.md`](docs/LOG.md) (append-only). Live experimentation happens in disposable project directories outside the repo, keeping the codebase clean. Built in public — day-by-day on X ([@h1902y](https://x.com/h1902y)).
 
 ## License & status
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuzuucodes/cli",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -42,15 +42,13 @@
     "bin/",
     "zuzuu/",
     "web-app/",
-    "experiments/experiment-1-trace-capture/core/",
-    "experiments/experiment-1-trace-capture/adapters/",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
     "zuzuu": "node bin/zuzuu.mjs",
-    "capture": "node experiments/experiment-1-trace-capture/bin/capture.mjs",
-    "inspect": "node experiments/experiment-1-trace-capture/bin/inspect-trace.mjs",
+    "capture": "node zuzuu/capture/bin/capture.mjs",
+    "inspect": "node zuzuu/capture/bin/inspect-trace.mjs",
     "test": "node --test 'tests/**/*.test.mjs'",
     "playground": "node tests/playground/run.mjs",
     "prepublishOnly": "npm test",

package/zuzuu/capture/bin/capture.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// capture — read a host's session log, normalize it, write an OTLP/JSON trace.
+//
+//   node bin/capture.mjs [--host NAME] [--project STR] [--session ID] [--file PATH] [--out PATH]
+//   node bin/capture.mjs --list                 # show detected hosts + sessions
+//
+// With no --host, picks the first detected host (transcript-present). Pure file
+// parsing — no host needs to be running.
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { ADAPTERS, byName, detected } from '../adapters/registry.mjs';
+import { eventsToSpans } from '../core/spans.mjs';
+import { toExportRequest, writeNdjson } from '../core/otlp.mjs';
+import { EventKind } from '../core/event.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_OUT_DIR = join(HERE, '..', 'out');
+
+function parseArgs(argv) {
+  const a = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === '--list') a.list = true;
+    else if (t === '-h' || t === '--help') a.help = true;
+    else if (t.startsWith('--')) a[t.slice(2)] = argv[++i];
+    else a._.push(t);
+  }
+  return a;
+}
+
+function printList() {
+  const hosts = detected();
+  if (!hosts.length) {
+    console.log('No hosts detected on this machine.');
+    return;
+  }
+  for (const adapter of hosts) {
+    const sessions = adapter.listSessions({ cwd: process.cwd() });
+    console.log(`\n● ${adapter.name} — ${sessions.length} session(s)`);
+    for (const s of sessions.slice(0, 8)) {
+      console.log(`    ${s.sessionId}  ${s.label ?? ''}`);
+    }
+    if (sessions.length > 8) console.log(`    … and ${sessions.length - 8} more`);
+  }
+  console.log();
+}
+
+function chooseRef(adapter, args) {
+  if (args.file) return args.file; // explicit transcript path (claude-code)
+  const sessions = adapter.listSessions({ cwd: process.cwd(), project: args.project });
+  let pool = sessions;
+  if (args.project) pool = pool.filter((s) => (s.label ?? '').includes(args.project));
+  if (args.session) pool = pool.filter((s) => s.sessionId === args.session || s.sessionId.includes(args.session));
+  if (!pool.length) throw new Error(`no matching session for ${adapter.name} (sessions found: ${sessions.length})`);
+  return pool[0].ref;
+}
+
+function summarize(trace) {
+  const counts = {};
+  for (const e of trace.events) counts[e.kind] = (counts[e.kind] || 0) + 1;
+  return counts;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log('usage: capture.mjs [--host NAME] [--project STR] [--session ID] [--file PATH] [--out PATH] | --list');
+    console.log('hosts:', ADAPTERS.map((a) => a.name).join(', '));
+    return;
+  }
+  if (args.list) return printList();
+
+  const adapter = args.host ? byName(args.host) : detected()[0];
+  if (!adapter) {
+    console.error(args.host ? `unknown host: ${args.host}` : 'no host detected (try --list)');
+    process.exit(1);
+  }
+
+  const ref = chooseRef(adapter, args);
+  const trace = adapter.parse(ref);
+  const { traceId, spans } = eventsToSpans(trace);
+  const request = toExportRequest({ traceId, spans }, { host: trace.host, sessionId: trace.sessionId });
+
+  const outPath = args.out || join(DEFAULT_OUT_DIR, `${trace.host}-${trace.sessionId}.otlp.jsonl`);
+  writeNdjson(outPath, [request]);
+
+  const counts = summarize(trace);
+  const root = trace.events.find((e) => e.kind === EventKind.SESSION) || trace.events[0];
+  const durSec = root ? ((root.endMs - root.startMs) / 1000).toFixed(1) : '?';
+  console.log(`captured ${trace.host} session ${trace.sessionId}`);
+  console.log(`  trace_id : ${traceId}`);
+  console.log(`  events   : ${spans.length}  (${Object.entries(counts).map(([k, v]) => `${k}:${v}`).join(', ')})`);
+  console.log(`  duration : ${durSec}s`);
+  console.log(`  written  : ${outPath}`);
+  console.log(`  inspect  : node ${join('zuzuu', 'capture', 'bin', 'inspect-trace.mjs')} "${outPath}"`);
+}
+
+main();

package/zuzuu/capture/bin/inspect-trace.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// inspect-trace — pretty-print the span tree of an OTLP/JSON NDJSON trace file.
+//
+//   node bin/inspect-trace.mjs out/claude-code-<id>.otlp.jsonl
+
+import { loadSpans, renderTree } from '../core/render.mjs';
+
+const file = process.argv[2];
+if (!file) {
+  console.error('usage: inspect-trace.mjs <trace.otlp.jsonl>');
+  process.exit(1);
+}
+console.log(renderTree(loadSpans(file)));

package/zuzuu/capture-core.mjs

@@ -3,9 +3,9 @@
 // (`hook`/`reconcile`, statuses active/completed/abandoned). One proven path —
 // Design B: the hook never builds spans, it re-runs THIS.
 
-import { eventsToSpans } from '../experiments/experiment-1-trace-capture/core/spans.mjs';
-import { toExportRequest } from '../experiments/experiment-1-trace-capture/core/otlp.mjs';
-import { EventKind, Status } from '../experiments/experiment-1-trace-capture/core/event.mjs';
+import { eventsToSpans } from './capture/core/spans.mjs';
+import { toExportRequest } from './capture/core/otlp.mjs';
+import { EventKind, Status } from './capture/core/event.mjs';
 import { makeSession, SessionState } from './session.mjs';
 import { writeTrace, upsertSession, gitInfo } from './store.mjs';
 

package/zuzuu/commands/capture.mjs

@@ -1,6 +1,6 @@
 // `zuzuu capture` — post-hoc: parse a host transcript into a git-native trace + record.
 
-import { ADAPTERS, byName, detected } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { ADAPTERS, byName, detected } from '../capture/adapters/registry.mjs';
 import { captureTrace } from '../capture-core.mjs';
 import { paths } from '../store.mjs';
 

package/zuzuu/commands/distill.mjs

@@ -40,7 +40,10 @@ export function distill(args) {
   }
 
   const r = distillSessions(agentDir, pairs);
-  console.log(`distilled ${r.sessionsMined} session(s) → ${r.proposals.length} proposal(s)${r.registryProposals.length ? ` (+${r.registryProposals.length} registry)` : ''}`);
+  const skips = r.archivedSkips ?? [];
+  console.log(`distilled ${r.sessionsMined} session(s) → ${r.proposals.length} proposal(s)${r.registryProposals.length ? ` (+${r.registryProposals.length} registry)` : ''}${skips.length ? ` (${skips.length} archived-skip)` : ''}`);
   for (const p of r.proposals) console.log(`  ${p.er.verdict.padEnd(9)} ${p.id}`);
+  // already resolved (rejected/approved) in proposals/archive/ — not re-filed
+  for (const p of skips) console.log(`  archived-skip ${p.id} (${p.archived})`);
   if (r.proposals.length) console.log('next: zuzuu review');
 }

package/zuzuu/commands/doctor.mjs

@@ -2,7 +2,7 @@
 // real problems (warnings don't fail). Phase 2 will also reconcile lost sessions.
 
 import { mkdirSync, accessSync, constants } from 'node:fs';
-import { detected } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { detected } from '../capture/adapters/registry.mjs';
 import { paths, gitInfo } from '../store.mjs';
 import { listLive } from '../live/live-store.mjs';
 import { reconcile } from '../live/reconcile.mjs';

package/zuzuu/commands/hook.mjs

@@ -13,7 +13,7 @@
 
 import { readFileSync, writeFileSync, appendFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { byName } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { byName } from '../capture/adapters/registry.mjs';
 import { captureTrace } from '../capture-core.mjs';
 import { SessionState } from '../session.mjs';
 import { openLive, touchLive, closeLive } from '../live/live-store.mjs';

package/zuzuu/commands/init.mjs

@@ -14,7 +14,7 @@ import { join, basename } from 'node:path';
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { applyScaffold, ensureGitignore, homeExists } from '../scaffold.mjs';
 import { injectBlock, facultiesBlock, hasBlock, BLOCK_VERSION } from '../inject.mjs';
-import { detected } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { detected } from '../capture/adapters/registry.mjs';
 import { repoRoot } from '../store.mjs';
 import { migrateHome } from './migrate.mjs';
 

package/zuzuu/commands/status.mjs

@@ -1,7 +1,7 @@
 // `zuzuu status` — detected hosts + recorded sessions (the git-native index).
 
 import { existsSync } from 'node:fs';
-import { detected } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { detected } from '../capture/adapters/registry.mjs';
 import { readIndex, paths } from '../store.mjs';
 import { FACULTIES } from '../faculty/contract.mjs';
 import { listProposals } from '../faculty/proposal.mjs';

package/zuzuu/commands/trace.mjs

@@ -1,7 +1,7 @@
 // `zuzuu trace [--last | <file>]` — print the span tree of a captured trace.
 
 import { existsSync } from 'node:fs';
-import { loadSpans, renderTree } from '../../experiments/experiment-1-trace-capture/core/render.mjs';
+import { loadSpans, renderTree } from '../capture/core/render.mjs';
 import { lastTrace } from '../store.mjs';
 
 export function trace(args) {

package/zuzuu/faculty/proposal.mjs

@@ -96,6 +96,32 @@ export function readProposal(agentDir, faculty, id) {
   }
 }
 
+/**
+ * Read and normalise a resolved proposal from the faculty's archive.
+ * Returns null if no archive record exists or it is unreadable (never throws).
+ */
+export function readArchived(agentDir, faculty, id) {
+  const path = join(archiveDir(agentDir, faculty), `${id}.json`);
+  if (!existsSync(path)) return null;
+  try {
+    return normalise(JSON.parse(readFileSync(path, 'utf8')), faculty);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when an id is already resolved in the archive (rejected OR approved).
+ * Policy: a rejection is remembered — filing layers must skip these ids so a
+ * re-distill over the same sessions never resurrects a resolved proposal.
+ * (Approved ids are skipped too: the work is done; ER handles enrichment.)
+ * Gate at the CALLERS — writeProposal stays a dumb writer.
+ */
+export function isArchivedResolved(agentDir, faculty, id) {
+  const rec = readArchived(agentDir, faculty, id);
+  return !!rec && (rec.status === 'rejected' || rec.status === 'approved');
+}
+
 /**
  * List all pending proposals for a faculty (files in proposals/ not in archive/).
  * Normalises each record. Skips unreadable files (fail-soft).

package/zuzuu/knowledge/distill.mjs

@@ -12,7 +12,7 @@
 //   failures  — tools failing ≥3× → `fact` candidates (worth knowing!)
 
 import { readFileSync } from 'node:fs';
-import * as registry from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import * as registry from '../capture/adapters/registry.mjs';
 import { slugify } from './items.mjs';
 import { createProposal, fileRegistryProposals } from './proposals.mjs';
 
@@ -204,13 +204,17 @@ export function mineHostSession({ host, ref, sessionId }) {
   }
 }
 
-/** Run the full distill: mine sessions (all hosts) → candidates → ER → proposals. */
+/** Run the full distill: mine sessions (all hosts) → candidates → ER → proposals.
+ *  Candidates whose id is already resolved in proposals/archive/ are NOT
+ *  re-filed (a rejection is remembered) — they come back as `archivedSkips`. */
 export function distillSessions(agentDir, pairs) {
   const mined = pairs.map(mineHostSession).filter(Boolean);
   const candidates = aggregate(mined);
-  const proposals = candidates.map((c) => createProposal(agentDir, { candidate: c.candidate, source: 'distill', evidence: c.evidence }));
+  const results = candidates.map((c) => createProposal(agentDir, { candidate: c.candidate, source: 'distill', evidence: c.evidence }));
+  const proposals = results.filter((p) => p.status !== 'archived-skip');
+  const archivedSkips = results.filter((p) => p.status === 'archived-skip');
   const registryProposals = fileRegistryProposals(agentDir);
-  return { sessionsMined: mined.length, proposals, registryProposals };
+  return { sessionsMined: mined.length, proposals, registryProposals, archivedSkips };
 }
 
 /**

package/zuzuu/knowledge/proposals.mjs

@@ -15,6 +15,7 @@ import { allItems, readItem, writeItem, slugify } from './items.mjs';
 import { upsertItem } from './index.mjs';
 import { resolve as erResolve, merge } from './er.mjs';
 import { mechanicalScore } from '../eval/score.mjs';
+import { readArchived } from '../faculty/proposal.mjs';
 
 export const proposalsDir = (agentDir) => join(agentDir, 'knowledge', 'proposals');
 const archiveDir = (agentDir) => join(proposalsDir(agentDir), 'archive');
@@ -27,12 +28,20 @@ function writeProposal(agentDir, p) {
   return p;
 }
 
-/** Run ER for a candidate and file a pending proposal (deduped per candidate). */
+/** Run ER for a candidate and file a pending proposal (deduped per candidate).
+ *  A rejection is remembered: if the derived id is already RESOLVED in
+ *  proposals/archive/ (rejected or approved), nothing is filed — the call
+ *  returns `{ id, status: 'archived-skip', archived: <resolved status> }` so
+ *  callers can count/report the skip instead of resurrecting the proposal. */
 export function createProposal(agentDir, { candidate, source, evidence = {} }) {
   const { items } = allItems(agentDir);
   candidate.id = candidate.id || slugify(candidate.body);
   const er = erResolve(candidate, items);
   const id = `${candidate.id}-${shortHash(candidate.id + source)}`;
+  const archived = readArchived(agentDir, 'knowledge', id);
+  if (archived && (archived.status === 'rejected' || archived.status === 'approved')) {
+    return { id, status: 'archived-skip', archived: archived.status };
+  }
   const existing = join(proposalsDir(agentDir), `${id}.json`);
   if (existsSync(existing)) {
     // refresh evidence on the pending proposal instead of duplicating it

package/zuzuu/live/reconcile.mjs

@@ -4,7 +4,7 @@
 // correct capture of the abandoned session before closing it. Nothing is lost.
 
 import { listLive, isStale, closeLive } from './live-store.mjs';
-import { byName } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { byName } from '../capture/adapters/registry.mjs';
 import { captureTrace } from '../capture-core.mjs';
 import { SessionState } from '../session.mjs';
 

package/zuzuu/miners/guardrails.mjs

@@ -18,7 +18,7 @@
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { slugify } from '../knowledge/items.mjs';
-import { makeProposal, writeProposal, listProposals } from '../faculty/proposal.mjs';
+import { makeProposal, writeProposal, listProposals, isArchivedResolved } from '../faculty/proposal.mjs';
 import { register } from './registry.mjs';
 
 // ---------------------------------------------------------------------------
@@ -127,6 +127,8 @@ export function aggregate(sessions, { minFailures = 3, minSessions = 2 } = {}) {
  * Idempotent:
  *   - skips if a guardrails proposal with the same payload.id already exists
  *   - skips if rules.json already has a rule with that id
+ *   - skips if the id is already resolved in proposals/archive/ — a rejection
+ *     is remembered; re-distilling never resurrects it
  *
  * The proposals flow through `zuzuu review` → guardrails adapter on approval.
  *
@@ -159,6 +161,9 @@ export function propose(agentDir, aggregated) {
       evidence,
     });
 
+    // A rejection is remembered: never resurrect an archive-resolved id.
+    if (isArchivedResolved(agentDir, 'guardrails', proposal.id)) continue;
+
     writeProposal(agentDir, proposal);
     count++;
   }

package/zuzuu/miners/instructions.mjs

@@ -11,7 +11,7 @@
 
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
-import { makeProposal, writeProposal, listProposals } from '../faculty/proposal.mjs';
+import { makeProposal, writeProposal, listProposals, isArchivedResolved } from '../faculty/proposal.mjs';
 import { register } from './registry.mjs';
 
 // ---------------------------------------------------------------------------
@@ -103,6 +103,8 @@ export function aggregate(sessions, { minSessions = 2 } = {}) {
  * Idempotent:
  *   - skips if an instructions proposal with the same derived id already exists
  *   - skips if the text is already present in project.md
+ *   - skips if the id is already resolved in proposals/archive/ — a rejection
+ *     is remembered; re-distilling never resurrects it
  *
  * @param {string} agentDir
  * @param {ReturnType<typeof aggregate>} aggregated
@@ -137,6 +139,9 @@ export function propose(agentDir, aggregated) {
       evidence,
     });
 
+    // A rejection is remembered: never resurrect an archive-resolved id.
+    if (isArchivedResolved(agentDir, 'instructions', proposal.id)) continue;
+
     writeProposal(agentDir, proposal);
     count++;
   }

package/zuzuu/miners/knowledge.mjs

@@ -7,12 +7,15 @@ import { aggregate } from '../knowledge/distill.mjs';
 import { createProposal } from '../knowledge/proposals.mjs';
 import { register } from './registry.mjs';
 
-/** File one knowledge proposal per aggregated candidate; return the count. */
+/** File one knowledge proposal per aggregated candidate; return the count of
+ *  actually-filed proposals (archive-resolved ids are skipped, not re-filed). */
 export function propose(agentDir, aggregated) {
+  let count = 0;
   for (const c of aggregated) {
-    createProposal(agentDir, { candidate: c.candidate, source: 'distill', evidence: c.evidence });
+    const p = createProposal(agentDir, { candidate: c.candidate, source: 'distill', evidence: c.evidence });
+    if (p && p.status !== 'archived-skip') count++;
   }
-  return aggregated.length;
+  return count;
 }
 
 export const miner = { faculty: 'knowledge', aggregate, propose };

package/zuzuu/store.mjs

@@ -11,7 +11,7 @@
 import { join, relative, resolve, isAbsolute } from 'node:path';
 import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { writeNdjson } from '../experiments/experiment-1-trace-capture/core/otlp.mjs';
+import { writeNdjson } from './capture/core/otlp.mjs';
 
 const INDEX_VERSION = 1;