@dmsdc-ai/aigentry-deliberation 0.0.35 → 0.0.37

package/README.md

@@ -33,7 +33,7 @@ MCP Deliberation Server — Multi-session AI deliberation with smart speaker ord
 원클릭 설치 — 어떤 프로젝트 환경에서든 동작합니다:
 
 ```bash
-npx @dmsdc-ai/aigentry-deliberation install
+npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install
 ```
 
 이 명령은:
@@ -62,7 +62,7 @@ cd aigentry-deliberation && npm install && node install.js
 ### 제거
 
 ```bash
-npx @dmsdc-ai/aigentry-deliberation uninstall
+npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install --uninstall
 ```
 
 MCP 서버 등록 해제 + 설치 파일 삭제 + 스킬 파일 정리까지 자동 처리됩니다.
@@ -87,7 +87,7 @@ open demo/forum/index.html
 MCP 연결 문제 자동 진단:
 
 ```bash
-npx @dmsdc-ai/aigentry-deliberation doctor
+npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-doctor
 ```
 
 Claude Code, Codex CLI, Gemini CLI의 MCP 설정을 자동 점검하고 문제를 진단합니다.
@@ -101,6 +101,7 @@ Claude Code, Codex CLI, Gemini CLI의 MCP 설정을 자동 점검하고 문제
 | `deliberation_synthesize` | Generate synthesis report |
 | `deliberation_status` | Check session status |
 | `deliberation_context` | Load project context |
+| `deliberation_inject_context` | Inject structured context or external experiment history into an active session |
 | `deliberation_history` | View discussion history |
 | `deliberation_list_active` | List active sessions |
 | `deliberation_list` | List archived sessions |
@@ -137,6 +138,48 @@ Telepty-managed sessions are now routed through the telepty bus instead of raw P
 - `session_health` bus events are cached for operator visibility
 - `deliberation_synthesize` validates and emits typed `deliberation_completed` envelopes for downstream automation
 
+## Experiment Retrospectives
+
+For autoresearch-style keep/discard reviews, inject a compact experiment bundle after the session starts instead of bloating `topic`.
+
+Recommended rules:
+- keep the injected JSON around `1.5KB` to `2KB`
+- include only the last `3-5` relevant experiments
+- keep `key_changes` to at most `3` scalar before/after pairs
+- reference bulky artifacts (`results.tsv`, full `program.md`, JSONL logs) by path only
+
+Example:
+
+```text
+deliberation_start(...)
+deliberation_inject_context(
+  session_id: "experiment-review-123",
+  speaker: "dustcraw",
+  context: "{\"past_experiments\":[{\"experiment_id\":\"dg-20260310-001\",\"signal_kind\":\"INTEREST_DRIFT\",\"patch_summary\":\"Raised relevanceThreshold from 0.30 to 0.35\",\"patch_kind\":\"config\",\"key_changes\":{\"relevanceThreshold\":{\"before\":0.3,\"after\":0.35}},\"score\":0.08,\"score_label\":\"promotion_rate_delta\",\"metric_name\":\"promotion_rate_delta\",\"metric_delta\":0.08,\"verdict\":\"positive\",\"followup_action\":\"kept\",\"reasoning\":\"Threshold raise reduced noise; promotion quality improved 8%\"}],\"experiment_count\":1,\"success_rate\":1.0}"
+)
+```
+
+If your synthesis needs an explicit experiment verdict, `structured` can now include `experiment_outcome`:
+
+```json
+{
+  "summary": "Lower the blast radius and re-run with stricter constraints.",
+  "decisions": [
+    "Keep the experiment loop bounded to one editable file",
+    "Retry after restoring the failing test baseline"
+  ],
+  "actionable_tasks": [
+    { "id": 1, "task": "Tighten editable globs", "project": "aigentry-devkit", "priority": "high" }
+  ],
+  "experiment_outcome": {
+    "verdict": "modify",
+    "suggested_action": "iterate",
+    "confidence": 0.78,
+    "measurement_window_hours": 24
+  }
+}
+```
+
 ## Speaker Ordering Strategies
 
 | Strategy | Description |
@@ -196,7 +239,7 @@ Inserts multi-AI verification gates at key [superpowers](https://github.com/obra
 
 **Fallback:** MCP 미설치 시 self-criticism 기반 자가 검증으로 대체 (Silver 등급). MCP 설치 시 멀티-AI 토론 (Gold 등급).
 
-**Install:** `npx @dmsdc-ai/aigentry-deliberation install` 실행 시 자동 설치됩니다.
+**Install:** `npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install` 실행 시 자동 설치됩니다.
 
 수동 설치:
 ```bash
@@ -207,6 +250,12 @@ cp skills/deliberation-gate/SKILL.md ~/.claude/skills/deliberation-gate/SKILL.md
 
 ## What's New
 
+### v0.0.36
+- **README refresh**: clarified the mandatory TUI speaker-selection flow and the confirmed-token handoff before `deliberation_start`
+- **Telepty candidate docs**: documented active telepty session discovery with lightweight `session_id` + `host/pid` locators instead of heavy persisted process snapshots
+- **Cross-project delivery docs**: clarified that active session lookup now resolves across project state directories, which unblocks cross-project `deliberation_respond` flows
+- **Operator guidance**: documented telepty bus transport as the automation path and unmanaged/manual sessions as the fallback path
+
 ### v0.0.35
 - **Manual selection enforcement**: `deliberation_confirm_speakers` binds a fresh candidate snapshot to the exact user-picked speaker set before `deliberation_start`
 - **Telepty session candidates**: active telepty sessions appear in speaker discovery with lightweight host/pid locators

package/doctor.js

@@ -15,7 +15,7 @@
  *
  * Usage:
  *   node doctor.js
- *   npx @dmsdc-ai/aigentry-deliberation doctor
+ *   npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-doctor
  */
 
 import fs from "node:fs";
@@ -209,7 +209,7 @@ function suggestFix(serverName, server, issue) {
   switch (issue) {
     case "path_missing":
       if (serverName === "deliberation" || serverName === "mcp-deliberation") {
-        return `npx @dmsdc-ai/aigentry-deliberation install`;
+        return `npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install`;
       }
       if (serverName.includes("brain") || serverName.includes("aigentry-brain")) {
         return `npx @dmsdc-ai/aigentry-brain install`;
@@ -223,7 +223,7 @@ function suggestFix(serverName, server, issue) {
     case "temp_path": {
       const tempArg = (server.args || []).find((a) => isTempPath(a));
       if (serverName === "deliberation" || serverName === "mcp-deliberation") {
-        return `npx @dmsdc-ai/aigentry-deliberation install  # reinstall to permanent path`;
+        return `npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install  # reinstall to permanent path`;
       }
       if (serverName.includes("brain") || serverName.includes("aigentry-brain")) {
         return `npx @dmsdc-ai/aigentry-brain install  # reinstall to permanent path`;
@@ -357,7 +357,7 @@ function runDiagnostics() {
         if (mod.includes("aigentry-brain") || mod.includes("brain")) {
           fix = `npx @dmsdc-ai/aigentry-brain install  # temporary path → reinstall to permanent path`;
         } else if (mod.includes("deliberation") || mod.includes("mcp-deliberation")) {
-          fix = `npx @dmsdc-ai/aigentry-deliberation install  # temporary path → reinstall to permanent path`;
+          fix = `npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install  # temporary path -> reinstall to permanent path`;
         } else {
           fix = `# temporary path (${mod}) — change to permanent path in MCP config`;
         }
@@ -387,7 +387,7 @@ function runDiagnostics() {
   } else {
     totalIssues++;
     console.log(`   ❌ Server file not found: ${selfPath}`);
-    console.log(`      fix: npx @dmsdc-ai/aigentry-deliberation install`);
+    console.log(`      fix: npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install`);
   }
 
   // Check node_modules
@@ -407,7 +407,7 @@ function runDiagnostics() {
   } catch {
     totalIssues++;
     console.log(`   ❌ Syntax error detected`);
-    console.log(`      fix: npx @dmsdc-ai/aigentry-deliberation install`);
+    console.log(`      fix: npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install`);
   }
 
   // ── Summary ──

package/index.js

@@ -22,9 +22,10 @@ if (_cliArg === "--help" || _cliArg === "-h") {
 MCP Deliberation Server
 
 Usage:
-  npx @dmsdc-ai/aigentry-deliberation install     Install (register MCP server)
-  npx @dmsdc-ai/aigentry-deliberation uninstall    Uninstall
+  npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install     Install (preferred)
+  npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install --uninstall
   npx @dmsdc-ai/aigentry-deliberation              Run MCP server (stdio)
+  npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-doctor      Diagnose MCP wiring
 
 After installation, restart Claude Code to start using it.
 `);
@@ -143,10 +144,32 @@ const StructuredActionableTaskSchema = z.object({
   priority: z.enum(["high", "medium", "low"]).optional(),
 });
 
+const StructuredExperimentOutcomeSchema = z.object({
+  verdict: z.enum(["keep", "discard", "modify"]),
+  confidence: z.number().min(0).max(1).optional(),
+  measurement_window_hours: z.number().nonnegative().optional(),
+  patches: z.array(z.unknown()).optional(),
+  suggested_action: z.enum(["advance", "revert", "iterate"]).optional(),
+});
+
 const StructuredSynthesisSchema = z.object({
   summary: z.string(),
   decisions: z.array(z.string()),
   actionable_tasks: z.array(StructuredActionableTaskSchema),
+  experiment_outcome: StructuredExperimentOutcomeSchema.optional(),
+});
+
+const StructuredExecutionContractSchema = z.object({
+  version: z.literal("v1"),
+  source_session_id: z.string().min(1),
+  summary: z.string(),
+  tasks: z.array(StructuredActionableTaskSchema),
+  experiment_outcome: StructuredExperimentOutcomeSchema.nullable().optional(),
+  unresolved_questions: z.array(z.string()),
+  artifact_refs: z.array(z.string()),
+  generated_from: z.object({
+    structured_synthesis_hash: z.string().length(40),
+  }),
 });
 
 const TeleptyEnvelopeSchema = z.object({
@@ -179,6 +202,7 @@ const TeleptyDeliberationCompletedPayloadSchema = z.object({
   topic: z.string(),
   synthesis: z.string(),
   structured_synthesis: StructuredSynthesisSchema.nullable().optional(),
+  execution_contract: StructuredExecutionContractSchema.nullable().optional(),
 });
 
 const TELEPTY_ENVELOPE_PAYLOAD_SCHEMAS = {
@@ -500,6 +524,41 @@ function hashPromptText(value) {
   return createHash("sha1").update(String(value || "")).digest("hex");
 }
 
+function sortJsonValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue);
+  }
+  if (value && typeof value === "object") {
+    return Object.keys(value)
+      .sort()
+      .reduce((acc, key) => {
+        acc[key] = sortJsonValue(value[key]);
+        return acc;
+      }, {});
+  }
+  return value;
+}
+
+function hashStructuredSynthesis(structured) {
+  return hashPromptText(JSON.stringify(sortJsonValue(structured || null)));
+}
+
+function buildExecutionContract({ state, structured }) {
+  if (!structured) return null;
+  return {
+    version: "v1",
+    source_session_id: state.id,
+    summary: structured.summary || "",
+    tasks: structured.actionable_tasks || [],
+    experiment_outcome: structured.experiment_outcome || null,
+    unresolved_questions: [],
+    artifact_refs: [],
+    generated_from: {
+      structured_synthesis_hash: hashStructuredSynthesis(structured),
+    },
+  };
+}
+
 function createEnvelopeId(prefix = "env") {
   return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -560,7 +619,11 @@ function buildTeleptyTurnRequestEnvelope({ state, speaker, turnId, turnPrompt, i
   });
 }
 
-function buildTeleptySynthesisEnvelope({ state, synthesis, structured }) {
+function buildTeleptySynthesisEnvelope({ state, synthesis, structured, executionContract }) {
+  const derivedExecutionContract =
+    executionContract !== undefined
+      ? executionContract
+      : (structured ? buildExecutionContract({ state, structured }) : (state.execution_contract || null));
   return buildTeleptyEnvelope({
     session_id: state.id,
     project: state.project || getProjectSlug(),
@@ -576,6 +639,7 @@ function buildTeleptySynthesisEnvelope({ state, synthesis, structured }) {
       topic: state.topic,
       synthesis,
       structured_synthesis: structured || null,
+      execution_contract: derivedExecutionContract || null,
     },
   });
 }
@@ -2547,6 +2611,14 @@ tags: [deliberation]
     md += `## Synthesis\n\n${s.synthesis}\n\n---\n\n`;
   }
 
+  if (s.structured_synthesis) {
+    md += `## Structured Synthesis\n\n\`\`\`json\n${JSON.stringify(s.structured_synthesis, null, 2)}\n\`\`\`\n\n---\n\n`;
+  }
+
+  if (s.execution_contract) {
+    md += `## Execution Contract\n\n\`\`\`json\n${JSON.stringify(s.execution_contract, null, 2)}\n\`\`\`\n\n---\n\n`;
+  }
+
   md += `## Debate Log\n\n`;
   for (const entry of s.log) {
     md += `### ${entry.speaker} — Round ${entry.round}\n\n`;
@@ -4470,6 +4542,7 @@ async function runAutoHandoff(sessionId) {
       if (!loaded) return;
       loaded.synthesis = markdownSynthesis;
       loaded.structured_synthesis = structured;
+      loaded.execution_contract = buildExecutionContract({ state: loaded, structured });
       loaded.status = "completed";
       loaded.current_speaker = "none";
       saveSession(loaded);
@@ -5012,6 +5085,7 @@ server.tool(
 
       loaded.synthesis = synthesis;
       loaded.structured_synthesis = structured || null;
+      loaded.execution_contract = buildExecutionContract({ state: loaded, structured: structured || null });
       loaded.status = "completed";
       loaded.current_speaker = "none";
       saveSession(loaded);
@@ -5033,6 +5107,7 @@ server.tool(
       state,
       synthesis,
       structured,
+      executionContract: state.execution_contract || null,
     });
 
     // Immediately force-close monitor terminal (including physical Terminal) on deliberation end

package/install.js

@@ -4,7 +4,7 @@
  * Deliberation MCP Server — One-click installer
  *
  * Usage:
- *   npx @dmsdc-ai/aigentry-deliberation install
+ *   npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install
  *   node install.js
  *
  * What it does:
@@ -261,7 +261,7 @@ if (args.includes("--help") || args.includes("-h")) {
 Deliberation MCP Server Installer
 
 Usage:
-  npx @dmsdc-ai/aigentry-deliberation install
+  npx --yes --package @dmsdc-ai/aigentry-deliberation deliberation-install
   node install.js
 
 Options:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-deliberation",
-  "version": "0.0.35",
+  "version": "0.0.37",
   "description": "MCP Deliberation Server — Multi-session AI deliberation with smart speaker ordering and persona roles",
   "type": "module",
   "license": "MIT",

package/skills/deliberation/SKILL.md

@@ -27,6 +27,7 @@ Claude/Codex를 포함해 MCP를 지원하는 임의 CLI들이 구조화된 토
 | `deliberation_speaker_candidates` | 참가 가능한 speaker 후보 목록 조회 | 불필요 |
 | `deliberation_list_active` | 진행 중인 모든 세션 목록 | 불필요 |
 | `deliberation_status` | 토론 상태 조회 | 선택적* |
+| `deliberation_inject_context` | 외부 실험 결과/추가 컨텍스트 주입 | 선택적 |
 | `deliberation_context` | 프로젝트 컨텍스트 로드 | 불필요 |
 | `deliberation_browser_llm_tabs` | 브라우저 LLM 탭 목록 (웹 기반 LLM 참여용) | 불필요 |
 | `deliberation_route_turn` | 현재 차례 speaker의 transport(CLI/browser_auto/manual)를 자동 라우팅 | 선택적* |
@@ -106,7 +107,57 @@ Claude/Codex를 포함해 MCP를 지원하는 임의 CLI들이 구조화된 토
 4. 각 세션을 `session_id`로 명시해 독립 진행
 5. 각각 `deliberation_synthesize`로 개별 종료
 
-### C. 자동 진행 (스크립트)
+### C. 실험 회고 / keep-discard review
+autoresearch 스타일 실험 루프를 검토할 때는 긴 컨텍스트를 `topic`에 섞지 말고, 시작 후 `deliberation_inject_context`로 compact bundle을 넣습니다.
+
+권장 규칙:
+- inject payload는 `1.5KB ~ 2KB` 목표
+- 최근 `3~5`개 실험만 포함
+- `key_changes`는 최대 `3`개 scalar before/after만 유지
+- 전체 `results.tsv` / 전체 `program.md`는 넣지 말고 artifact path만 남김
+
+예:
+```text
+1. deliberation_start(topic: "experiment retrospective / keep-discard review", ...)
+2. deliberation_inject_context(
+     session_id: "<session_id>",
+     speaker: "dustcraw",
+     context: JSON.stringify({
+       past_experiments: [{
+         experiment_id: "dg-20260310-001",
+         signal_kind: "INTEREST_DRIFT",
+         patch_summary: "Raised relevanceThreshold from 0.30 to 0.35",
+         patch_kind: "config",
+         key_changes: {
+           relevanceThreshold: { before: 0.30, after: 0.35 }
+         },
+         score: 0.08,
+         score_label: "promotion_rate_delta",
+         metric_name: "promotion_rate_delta",
+         metric_delta: 0.08,
+         verdict: "positive",
+         followup_action: "kept",
+         reasoning: "Threshold raise reduced noise; promotion quality improved 8%"
+       }],
+       experiment_count: 1,
+       success_rate: 1.0
+     })
+   )
+3. deliberation_route_turn(...) 반복
+4. deliberation_synthesize(..., structured: {
+     summary: "...",
+     decisions: ["..."],
+     actionable_tasks: [...],
+     experiment_outcome: {
+       verdict: "modify",
+       suggested_action: "iterate",
+       confidence: 0.78,
+       measurement_window_hours: 24
+     }
+   })
+```
+
+### D. 자동 진행 (스크립트)
 ```bash
 # 새 토론
 bash auto-deliberate.sh "저장소 전략"
@@ -118,7 +169,7 @@ bash auto-deliberate.sh "API 설계" 5
 bash auto-deliberate.sh --resume <session_id>
 ```
 
-### D. 모니터링
+### E. 모니터링
 ```bash
 # 모든 활성 세션 모니터링
 bash deliberation-monitor.sh
@@ -130,14 +181,14 @@ bash deliberation-monitor.sh <session_id>
 bash deliberation-monitor.sh --tmux
 ```
 
-### E. 브라우저 LLM 자동 연결 (CDP Auto-Activation)
+### F. 브라우저 LLM 자동 연결 (CDP Auto-Activation)
 - 브라우저 LLM speaker가 선택되면 CDP(Chrome DevTools Protocol)가 자동으로 활성화됩니다.
 - macOS에서는 Chrome이 실행되지 않은 경우 `--remote-debugging-port=9222`로 자동 실행을 시도합니다.
 - **Chrome이 이미 CDP 없이 실행 중인 경우**: Chrome을 완전히 종료한 후 다시 시도해야 합니다. (최초 1회만 필요)
 - CDP 연결 성공 시 모든 브라우저 speaker는 ⚡자동 모드로 동작합니다.
 - Windows/Linux에서는 사용자가 직접 Chrome을 `--remote-debugging-port=9222`로 실행해야 합니다.
 
-### F. Chrome 확장 프로그램 사이드패널 지원
+### G. Chrome 확장 프로그램 사이드패널 지원
 - **Chrome 확장 프로그램 사이드패널 (chrome-extension:// URL)은 지원됩니다.**
 - Claude, ChatGPT, Gemini 등의 Chrome 확장 사이드패널도 CDP를 통해 deliberation 참가자로 사용 가능합니다.
 - 사이드패널은 title 기반 매칭으로 감지됩니다 (extension ID가 아닌 탭 제목으로 식별).