codetrap 0.1.5 → 0.1.6

package/README.md

@@ -56,6 +56,7 @@ codetrap show 1
 ## Features
 
 - **Structured trap recording** — title, category, context, mistake, fix, severity, tags, lifecycle, evidence, before/after code
+- **Session mode capture** — record implementation notes, promote explicit structured trap notes into candidates, and save only user-accepted lessons
 - **Dual scope** — project-scoped (`.codetrap/traps.db`) and global (`~/.codetrap/traps.db`)
 - **CLI-first agent API** — `search/show/list/stats/doctor --json` and stdin query support for shell-friendly automation
 - **Three search modes** — FTS (SQLite FTS5), semantic (Jina embeddings), hybrid (RRF fusion)
@@ -81,9 +82,17 @@ codetrap/
 │   │   ├── tools.ts          10 MCP tool definitions
 │   │   └── resources.ts      4 MCP resource URIs
 │   ├── domain/trap.ts        Trap types, builders, schemas
+│   ├── domain/session.ts     Session, note, and candidate trap types
 │   ├── lib/
 │   │   ├── store.ts          Project/global scope orchestration
 │   │   ├── trap-operations.ts Shared CLI/MCP operation semantics
+│   │   ├── session-operations.ts Session command semantics + accept/reject flow
+│   │   ├── session-store.ts  Session files, active state, index, recaps
+│   │   ├── session-codec.ts  Session JSON/Markdown/candidate file conversion
+│   │   ├── session-capture.ts Candidate trap extraction from explicit structured notes
+│   │   ├── session-conflicts.ts Candidate vs active-trap conflict checks
+│   │   ├── trap-quality.ts   Deterministic candidate quality scoring
+│   │   ├── command-requests.ts CLI/MCP request normalization helpers
 │   │   ├── output-json.ts    Shared CLI/MCP JSON presenters
 │   │   ├── scope-context.ts  cwd/project/global DB context + repo selection
 │   │   ├── scope-migration.ts Safe project trap scope repair/migration
@@ -115,6 +124,7 @@ codetrap/
 │   └── tests/
 │       ├── search-*.test.ts
 │       ├── trap-*.test.ts
+│       ├── session-cli.test.ts
 │       ├── mcp-tools.test.ts
 │       ├── scope.test.ts
 │       ├── scope-migration-cli.test.ts
@@ -150,8 +160,25 @@ codetrap/
 | `repair-scope` | Move legacy mis-scoped project traps into the current project (dry-run by default, `--apply` to mutate, `--json`) |
 | `migrate-project` | Move project traps between initialized projects (`--from-project-path`, `--to-project-path`, dry-run by default, `--apply`, `--json`) |
 | `embed` | Generate embeddings (requires JINA_API_KEY) |
+| `session` | Start a development session, append notes, promote explicit structured trap notes into candidates, and accept/reject candidates |
 | `serve` | Start MCP server |
 
+### Session Mode
+
+Session mode stores temporary working memory in `.codetrap/sessions/`. It does not add anything to `traps.db` until a candidate is explicitly accepted.
+
+```bash
+codetrap session start "implement agent harness" --spec docs/agent-harness-spec.md --module agent-runtime
+codetrap session note --kind decision --text "Defaulted tool calls to 30s because the spec does not define timeout behavior."
+codetrap session note --kind review --text $'Title: Do not parse nested tool calls with regex\nContext: When implementing parser logic for nested tool-call arguments.\nMistake: Using regex to split nested calls corrupts arguments.\nFix: Use a tokenizer/parser and add regression tests for nested calls.'
+codetrap session close --propose-traps
+codetrap session candidates
+codetrap session candidate cand-001
+codetrap session accept cand-001
+```
+
+`session accept` writes the confirmed lesson through `TrapOperations`, attaches session evidence, and checks similar active traps before saving. `--edit-json` is applied before the conflict check, so edits to scope/module/title/tags/path globs affect both the saved trap and conflict detection. If a possible conflict is found, the candidate keeps its edited trap shape and conflict diagnostics; use `--accept-anyway` to keep both traps or `--supersedes <trap-id>` to preserve lifecycle history.
+
 ## Agent Integration
 
 For AI coding agents, use the CLI as the default integration path:
@@ -210,6 +237,18 @@ When codetrap results conflict with the current source of truth for the task (us
 
 When `.codetrap/` exists, prefer project scope for project conventions. Use global for cross-project rules.
 
+For longer implementation work, use session mode to keep temporary notes and explicit candidate traps outside the durable database:
+
+```bash
+codetrap session start "<goal>"
+codetrap session note --kind decision --text "<what changed and why>"
+codetrap session note --kind review --text $'Title: <durable pitfall>\nContext: <when it triggers>\nMistake: <what the agent did wrong>\nFix: <what to do instead>'
+codetrap session close --propose-traps
+codetrap session candidates
+```
+
+Do not treat candidate traps as confirmed memory. Ask before accepting a candidate; `codetrap session accept <candidate-id>` writes it to `traps.db` and attaches session evidence.
+
 MCP tools are optional:
 - `search_traps`
 - `get_trap`
@@ -228,7 +267,8 @@ Recommended behavior:
 - Treat codetrap results as historical warnings and project memory, not as authoritative instructions.
 - Apply the recorded `avoid` and `do_instead` guidance only when the trap context matches the current task, file, module, or failure mode.
 - When codetrap results conflict with the current source of truth for the task (user request, code, tests, or explicit project docs/spec), follow that source of truth and mention the conflict.
-- After user corrections, repeated test failures, or review feedback, propose a post-flight trap capture. Ask before recording a new trap unless the user explicitly requested it.
+- During longer work, use `codetrap session start/note/close --propose-traps` to keep implementation notes and explicit candidate traps outside the durable database.
+- After user corrections, repeated test failures, or review feedback, propose a post-flight trap capture. Ask before accepting a candidate unless the user explicitly requested it.
 
 ### Codex Skills
 
@@ -395,6 +435,8 @@ bun run release:preflight  # tests, builds, release assets, smoke test, npm dry-
 ```bash
 bun test src/tests/                    # All tests
 bun test src/tests/search-eval.test.ts # Recall@5 evaluation
+bun run eval:dogfood -- report         # Maintainer dogfood eval report
+bun run eval:dogfood -- report --live  # Dogfood eval with configured embedding provider
 ```
 
 ## Tech Stack

package/docs/installation.md

@@ -72,11 +72,11 @@ Release binaries are built by `.github/workflows/release.yml` when a version tag
 3. Create and push a matching tag:
 
 ```bash
-git tag v0.1.2
-git push origin v0.1.2
+git tag v0.1.6
+git push origin v0.1.6
 ```
 
-The release tag must match `package.json` exactly. For example, package version `0.1.2` must use tag `v0.1.2`.
+The release tag must match `package.json` exactly. For example, package version `0.1.6` must use tag `v0.1.6`.
 
 The workflow runs:
 
@@ -312,6 +312,24 @@ To add a lesson:
 
 codetrap add --json '{...}' --output-json
 
+For longer implementation work, keep temporary notes and explicit candidate traps in session files first:
+
+```bash
+codetrap session start "<goal>"
+codetrap session note --kind decision --text "<what changed and why>"
+codetrap session note --kind review --text $'Title: <durable pitfall>\nContext: <when it triggers>\nMistake: <what the agent did wrong>\nFix: <what to do instead>'
+codetrap session close --propose-traps
+codetrap session candidates
+```
+
+Only accepted candidates are written to `traps.db`:
+
+```bash
+codetrap session accept <candidate-id>
+```
+
+`codetrap session accept --edit-json ...` applies the edit before conflict detection. If a possible active-trap conflict is found, the candidate remains proposed and records conflict diagnostics until you choose `--accept-anyway`, `--supersedes <trap-id>`, or reject it.
+
 To save a lesson from an external article or reference, let the agent read the source and attach the URL as evidence after the user confirms the trap:
 
 codetrap add_trap_evidence <id> --scope global --source_type article --source_ref "https://example.com/post" --output-json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codetrap",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Capture and retrieve coding pitfalls so AI doesn't repeat mistakes",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "src/domain",
     "src/lib",
     "src/mcp",
+    "src/web",
     "src/index.ts",
     "src/mcp-server.ts",
     "skills",
@@ -50,6 +51,7 @@
     "build:release": "bun run scripts/build-release.ts",
     "release:preflight": "bun run scripts/release-preflight.ts",
     "check:release-version": "bun run scripts/check-release-version.ts",
+    "eval:dogfood": "bun run scripts/dogfood-eval.ts",
     "build": "bun build ./src/index.ts --compile --outfile dist/codetrap && bun build ./src/mcp-server.ts --compile --outfile dist/codetrap-serve",
     "build:cli": "bun build ./src/index.ts --compile --outfile dist/codetrap",
     "build:serve": "bun build ./src/mcp-server.ts --compile --outfile dist/codetrap-serve"

package/scripts/dogfood-eval.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env bun
+
+import {
+  DEFAULT_SEARCH_EVAL_FIXTURE,
+  formatSearchEvalReport,
+  recordDogfoodCase,
+  reportDogfood,
+} from "../src/lib/search-eval";
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args.positionals[0];
+  const fixturePath = args.opts.fixture ?? DEFAULT_SEARCH_EVAL_FIXTURE;
+
+  try {
+    if (command === "record") {
+      console.log(JSON.stringify(recordDogfoodCase(fixturePath, args.opts.json), null, 2));
+      return;
+    }
+
+    if (command === "report") {
+      const result = await reportDogfood(fixturePath, args.opts.live === "true");
+      console.log(args.opts.json === "true" ? JSON.stringify(result, null, 2) : formatSearchEvalReport(result));
+      return;
+    }
+
+    throw new Error([
+      "Usage:",
+      "  bun run eval:dogfood -- report [--live] [--json] [--fixture path]",
+      "  bun run eval:dogfood -- record --json '<record>' [--fixture path]",
+    ].join("\n"));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+function parseArgs(args: string[]): { opts: Record<string, string>; positionals: string[] } {
+  const opts: Record<string, string> = {};
+  const positionals: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      opts[key] = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "true";
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { opts, positionals };
+}
+
+await main();

package/src/commands/workflow.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { TrapStore } from "../lib/store";
 import { formatTrapShort, formatTrapDetails, formatTrapActionCard } from "../lib/format";
 import type { Trap } from "../domain/trap";
+import type { SessionMetadata } from "../domain/session";
 import {
   formatScopeMigrationText,
   runScopeMigration,
@@ -10,6 +11,15 @@ import {
 import { TrapOperations } from "../lib/trap-operations";
 import { buildDoctorReport, formatDoctorText } from "../lib/doctor";
 import { searchDefaultsFromConfig } from "../lib/config";
+import { SessionStore } from "../lib/session-store";
+import { SessionOperations, type SessionConflictResult } from "../lib/session-operations";
+import {
+  CANDIDATES_FILE,
+  NOTES_FILE,
+  RECAP_FILE,
+  sessionRelativeDir,
+  sessionRelativeFile,
+} from "../lib/session-codec";
 import {
   toCliSearchJson,
   toListJson,
@@ -28,6 +38,15 @@ import {
   evidenceRequestFromArgs,
   listRequestFromArgs,
   searchRequestFromArgs,
+  sessionAcceptRequestFromArgs,
+  sessionCandidateRequestFromArgs,
+  sessionCloseRequestFromArgs,
+  sessionIdRequestFromArgs,
+  sessionListRequestFromArgs,
+  sessionNoteRequestFromArgs,
+  sessionRejectRequestFromArgs,
+  sessionShowRequestFromArgs,
+  sessionStartRequestFromArgs,
   statsRequestFromArgs,
 } from "../lib/command-requests";
 
@@ -80,10 +99,12 @@ export async function executeCommand(strip: string[], store: TrapStore): Promise
       return cmdScopeMigration("migrate-project", args, operations);
     case "embed":
       return cmdEmbed(args, store);
+    case "session":
+      return cmdSession(args, store, operations);
     default:
       return errorResult([
         `Unknown command: ${sub}`,
-        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, repair-scope, migrate-project, embed",
+        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, repair-scope, migrate-project, embed, session",
       ].join("\n"));
   }
 }
@@ -370,6 +391,204 @@ async function cmdEmbed(args: string[], store: TrapStore): Promise<CommandResult
   }
 }
 
+async function cmdSession(args: string[], store: TrapStore, trapOperations: TrapOperations): Promise<CommandResult> {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const projectRoot = store.getProjectRoot();
+  if (!projectRoot) {
+    return errorResult("Not in a project. Run 'codetrap init' first.");
+  }
+
+  const sessions = new SessionOperations(new SessionStore(projectRoot), trapOperations);
+  try {
+    switch (sub) {
+      case "start":
+        return cmdSessionStart(rest, sessions);
+      case "note":
+        return cmdSessionNote(rest, sessions);
+      case "status":
+        return cmdSessionStatus(rest, sessions);
+      case "list":
+        return cmdSessionList(rest, sessions);
+      case "show":
+        return cmdSessionShow(rest, sessions);
+      case "notes":
+        return cmdSessionNotes(rest, sessions);
+      case "close":
+        return cmdSessionClose(rest, sessions);
+      case "candidates":
+        return cmdSessionCandidates(rest, sessions);
+      case "candidate":
+        return cmdSessionCandidate(rest, sessions);
+      case "accept":
+        return cmdSessionAccept(rest, sessions);
+      case "reject":
+        return cmdSessionReject(rest, sessions);
+      default:
+        return errorResult("Usage: codetrap session <start|note|status|list|show|notes|close|candidates|candidate|accept|reject>");
+    }
+  } catch (error) {
+    return errorFrom(error);
+  }
+}
+
+function cmdSessionStart(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const session = sessions.startSession(sessionStartRequestFromArgs(positionals, opts));
+  const payload = sessionPayload(session);
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult([
+    `Started session ${session.id}`,
+    `Notes: ${payload.notes_path}`,
+  ].join("\n"));
+}
+
+function cmdSessionNote(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const result = sessions.addNote(sessionNoteRequestFromArgs(positionals, opts, {
+    isTTY: process.stdin.isTTY === true,
+    read: () => readFileSync(0, "utf-8"),
+  }));
+  const payload = {
+    session_id: result.session.id,
+    kind: result.note.kind,
+    note: result.note,
+    notes_path: result.notes_path,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult([
+    `Added ${result.note.kind} note to session ${result.session.id}.`,
+    `Notes: ${result.notes_path}`,
+  ].join("\n"));
+}
+
+function cmdSessionStatus(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts } = parseArgs(args);
+  const status = sessions.status();
+  if (opts.json !== undefined) {
+    return jsonResult({
+      active_session_id: status.active_session_id,
+      session: status.session ? sessionPayload(status.session) : null,
+    });
+  }
+  if (!status.session) return textResult("No active session.");
+  return textResult([
+    `Active session ${status.session.id}`,
+    `Goal: ${status.session.goal}`,
+    `Notes: ${sessionRelativeFile(status.session.id, NOTES_FILE)}`,
+  ].join("\n"));
+}
+
+function cmdSessionList(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts } = parseArgs(args);
+  const entries = sessions.listSessions(sessionListRequestFromArgs(opts));
+  if (opts.json !== undefined) return jsonResult(entries);
+  if (entries.length === 0) return textResult("No sessions found.");
+  return textResult(entries.map((entry) => `${entry.id} [${entry.status}] ${entry.goal}`).join("\n"));
+}
+
+function cmdSessionShow(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionShowRequestFromArgs(positionals);
+  const shown = sessions.showSession(request.sessionId);
+  if (opts.json !== undefined) {
+    return jsonResult({
+      ...sessionPayload(shown.session),
+      session_dir: shown.session_dir,
+      recap: shown.recap,
+    });
+  }
+  if (shown.recap) return textResult(shown.recap.trimEnd());
+  return textResult([
+    `Session ${shown.session.id} [${shown.session.status}]`,
+    `Goal: ${shown.session.goal}`,
+    `Notes: ${shown.notes_path}`,
+  ].join("\n"));
+}
+
+function cmdSessionNotes(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionIdRequestFromArgs(positionals);
+  const summary = sessions.summarizeNotes(request.sessionId);
+  if (opts.json !== undefined) return jsonResult(summary);
+  return textResult(summary.content.trimEnd());
+}
+
+function cmdSessionClose(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionCloseRequestFromArgs(positionals, opts);
+  const result = sessions.closeSession(request.sessionId, request.proposeTraps);
+  const payload = {
+    ...sessionPayload(result.session),
+    recap_path: result.recap_path,
+    candidate_count: result.candidate_count,
+    traps_written: result.traps_written,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  const lines = [
+    `Closed session ${result.session.id}`,
+    `Generated ${RECAP_FILE}`,
+  ];
+  if (opts["propose-traps"] !== undefined) {
+    lines.push(`Proposed ${result.candidate_count} candidate traps`);
+    lines.push(`0 traps were written. Use \`codetrap session accept <candidate-id> --session ${result.session.id}\` to save one.`);
+  }
+  return textResult(lines.join("\n"));
+}
+
+function cmdSessionCandidates(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionIdRequestFromArgs(positionals);
+  const document = sessions.candidateDocument(request.sessionId);
+  if (opts.json !== undefined) return jsonResult(document);
+  if (document.candidates.length === 0) return textResult("No candidate traps found.");
+  return textResult(document.candidates.map((candidate) =>
+    `${candidate.id} [${candidate.status}] ${candidate.trap.title} (${candidate.quality_score.toFixed(2)})`
+  ).join("\n"));
+}
+
+function cmdSessionCandidate(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionCandidateRequestFromArgs(positionals, opts);
+  const result = sessions.getCandidate(request.candidateId, request.sessionId);
+  if (opts.json !== undefined) return jsonResult({ session_id: result.session.id, candidate: result.candidate });
+  return textResult(JSON.stringify(result.candidate, null, 2));
+}
+
+async function cmdSessionAccept(args: string[], sessions: SessionOperations): Promise<CommandResult> {
+  const { opts, positionals } = parseArgs(args);
+  const accepted = await sessions.acceptCandidate(sessionAcceptRequestFromArgs(positionals, opts));
+  if (!accepted.success) return possibleConflictResult(accepted, opts.json !== undefined);
+  const payload = {
+    success: true,
+    session_id: accepted.session.id,
+    candidate_id: accepted.candidate.id,
+    status: accepted.candidate.status,
+    trap_id: accepted.trap_id,
+    scope: accepted.scope,
+    evidence_id: accepted.evidence_id,
+    superseded_id: accepted.superseded_id,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  const lines = [`Accepted ${accepted.candidate.id}; wrote trap #${accepted.trap_id} to ${accepted.scope} scope.`];
+  if (accepted.superseded_id !== null) lines.push(`Superseded trap #${accepted.superseded_id}.`);
+  return textResult(lines.join("\n"));
+}
+
+function cmdSessionReject(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const rejected = sessions.rejectCandidate(sessionRejectRequestFromArgs(positionals, opts));
+  const payload = {
+    success: true,
+    session_id: rejected.session.id,
+    candidate_id: rejected.candidate.id,
+    status: rejected.candidate.status,
+    reason: rejected.candidate.rejection_reason ?? null,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult(`Rejected ${rejected.candidate.id}.`);
+}
+
 function formatStatsText(stats: ReturnType<TrapOperations["getStats"]>): string {
   const sections: string[] = [];
   if (stats.project) {
@@ -417,3 +636,43 @@ function errorFrom(error: unknown): CommandResult {
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+function sessionPayload(session: SessionMetadata) {
+  return {
+    ...session,
+    session_dir: sessionRelativeDir(session.id),
+    notes_path: sessionRelativeFile(session.id, NOTES_FILE),
+    recap_path: sessionRelativeFile(session.id, RECAP_FILE),
+    candidate_traps_path: sessionRelativeFile(session.id, CANDIDATES_FILE),
+  };
+}
+
+function possibleConflictResult(
+  result: SessionConflictResult,
+  asJson: boolean
+): CommandResult {
+  const payload = {
+    success: false,
+    error: "Possible active trap conflict found.",
+    session_id: result.session_id,
+    candidate_id: result.candidate_id,
+    possible_conflicts: result.possible_conflicts,
+    next_actions: [
+      `codetrap session accept ${result.candidate_id} --session ${result.session_id} --accept-anyway`,
+      `codetrap session accept ${result.candidate_id} --session ${result.session_id} --supersedes <trap-id>`,
+      `codetrap session reject ${result.candidate_id} --session ${result.session_id} --reason <reason>`,
+    ],
+  };
+  if (asJson) return jsonResult(payload, 1);
+
+  return errorResult([
+    "Possible active trap conflict found:",
+    ...result.possible_conflicts.map((conflict) => [
+      `#${conflict.trap_id} ${conflict.title}`,
+      `  reason: ${conflict.reason}`,
+      `  fix: ${conflict.fix}`,
+    ].join("\n")),
+    "",
+    `Use --accept-anyway to save as a new trap, or --supersedes <trap-id> to preserve lifecycle history.`,
+  ].join("\n"));
+}

package/src/db/connection.ts

@@ -29,8 +29,8 @@ export function openProject(root: string): Database {
 }
 
 function configureDatabase(db: Database): void {
+  db.exec("PRAGMA busy_timeout=5000");
   db.exec("PRAGMA journal_mode=WAL");
   db.exec("PRAGMA foreign_keys=ON");
-  db.exec("PRAGMA busy_timeout=5000");
   initSchema(db);
 }

package/src/domain/session.ts

@@ -0,0 +1,119 @@
+import type { TrapEvidenceInput, TrapInput } from "./trap";
+import type { Scope } from "../lib/constants";
+
+export const SESSION_VERSION = 1;
+
+export const SESSION_STATUSES = ["active", "closed"] as const;
+export type SessionStatus = (typeof SESSION_STATUSES)[number];
+
+export const SESSION_NOTE_KINDS = [
+  "decision",
+  "deviation",
+  "tradeoff",
+  "open_question",
+  "failure",
+  "test_failure",
+  "correction",
+  "review",
+  "observation",
+] as const;
+
+export type SessionNoteKind = (typeof SESSION_NOTE_KINDS)[number];
+
+export const CANDIDATE_STATUSES = ["proposed", "accepted", "rejected"] as const;
+export type CandidateStatus = (typeof CANDIDATE_STATUSES)[number];
+
+export interface SessionMetadata {
+  version: typeof SESSION_VERSION;
+  id: string;
+  goal: string;
+  status: SessionStatus;
+  created_at: string;
+  updated_at: string;
+  closed_at: string | null;
+  scope: Scope;
+  project_path: string;
+  module: string | null;
+  owner: string | null;
+  spec_ref: string | null;
+  notes_path: string;
+  recap_path: string;
+  candidate_traps_path: string;
+}
+
+export interface SessionNote {
+  created_at: string;
+  kind: SessionNoteKind;
+  text: string;
+  related_files: string[];
+  source_ref: string | null;
+}
+
+export type SessionNoteCounts = Partial<Record<SessionNoteKind, number>>;
+
+export interface SessionIndexEntry {
+  id: string;
+  goal: string;
+  status: SessionStatus;
+  created_at: string;
+  closed_at: string | null;
+  module: string | null;
+  owner: string | null;
+  note_counts: SessionNoteCounts;
+  candidate_count: number;
+  accepted_count: number;
+  summary: string | null;
+}
+
+export interface SessionIndexDocument {
+  version: typeof SESSION_VERSION;
+  sessions: SessionIndexEntry[];
+}
+
+export interface ActiveSessionDocument {
+  active_session_id: string | null;
+  updated_at: string;
+}
+
+export interface CandidateQuality {
+  has_clear_trigger: boolean;
+  has_clear_mistake: boolean;
+  has_actionable_fix: boolean;
+  not_too_broad: boolean;
+  future_reuse_likely: boolean;
+  proper_scope: boolean;
+  evidence_count: number;
+  conflict_checked: boolean;
+  conflict_status: "none" | "possible" | "confirmed";
+  staleness_risk: "low" | "medium" | "high";
+  suggested_action: "accept" | "edit" | "supersede" | "archive_old" | "reject";
+  warnings: string[];
+}
+
+export interface CandidateTrap {
+  id: string;
+  status: CandidateStatus;
+  quality_score: number;
+  quality: CandidateQuality;
+  trap: TrapInput;
+  evidence: TrapEvidenceInput[];
+  accepted_trap_id?: number;
+  accepted_scope?: Scope;
+  accepted_at?: string;
+  rejected_at?: string;
+  rejection_reason?: string;
+}
+
+export interface CandidateTrapDocument {
+  version: typeof SESSION_VERSION;
+  session_id: string;
+  candidates: CandidateTrap[];
+}
+
+export function parseSessionNoteKind(value: string | undefined): SessionNoteKind {
+  const normalized = value ?? "observation";
+  if ((SESSION_NOTE_KINDS as readonly string[]).includes(normalized)) {
+    return normalized as SessionNoteKind;
+  }
+  throw new Error(`Invalid session note kind: ${normalized}. Expected one of: ${SESSION_NOTE_KINDS.join(", ")}`);
+}

package/src/index.ts

@@ -14,6 +14,9 @@ if (args.length === 0) {
   showHelp();
 } else if (args[0] === "serve") {
   import("./mcp/server").then((m) => m.start());
+} else if (args[0] === "web") {
+  const { startWebServerFromArgs } = await import("./web/server");
+  await startWebServerFromArgs(args.slice(1));
 } else if (args[0] === "init") {
   const cwd = process.cwd();
   if (findProjectRoot(cwd)) {
@@ -43,6 +46,8 @@ function showHelp(): void {
   console.log("  archive_trap          Archive a trap");
   console.log("  supersede_trap        Mark one trap as superseded by another");
   console.log("  embed                 Generate embeddings for semantic search");
+  console.log("  session               Record implementation notes and capture candidate traps");
+  console.log("  web                   Start local candidate review console");
   console.log("  export                Export traps as JSON");
   console.log("  import <file.json>    Import traps from JSON");
   console.log("  stats                 Show statistics");
@@ -63,6 +68,9 @@ function showHelp(): void {
   console.log("  --no-rerank             Disable query-aware search reranking");
   console.log("  --ranking-signals       Include search ranking diagnostics in JSON cards");
   console.log("  --batch-size <n>        Embedding generation batch size");
+  console.log("  --project <path>        Project path for web review console");
+  console.log("  --host <host>           Host for web review console (default 127.0.0.1)");
+  console.log("  --port <n>              Port for web review console (default 4737)");
   console.log("  --json                  JSON output for search/show/list/stats/doctor; JSON input for add/edit");
   console.log("  --output-json           JSON output for add/edit when --json is used as input");
   console.log("  --from-project-path <path>  Source project path for scope repair/migration");