gyoshu 0.2.5 → 0.4.0

package/README.md

@@ -39,6 +39,7 @@ Think of it like a research lab:
 - 📓 **Auto-Generated Notebooks** — Every experiment is captured as a reproducible `.ipynb`
 - 🤖 **Autonomous Mode** — Set a goal, walk away, come back to results
 - 🔍 **Adversarial Verification** — PhD reviewer challenges every claim before acceptance
+- 🎯 **Two-Gate Completion** — SUCCESS requires both evidence quality (Trust Gate) AND goal achievement (Goal Gate)
 - 📝 **AI-Powered Reports** — Turn messy outputs into polished research narratives
 - 🔄 **Session Management** — Continue, replay, or branch your research anytime
 
@@ -46,32 +47,38 @@ Think of it like a research lab:
 
 ## 🚀 Installation
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/My-Jogyo/main/install.sh | bash
+Add Gyoshu to your `opencode.json`:
+
+```json
+{
+  "plugin": ["gyoshu"]
+}
 ```
 
+That's it! OpenCode will auto-install Gyoshu via Bun on next startup.
+
 <details>
-<summary>📦 Alternative installation methods</summary>
+<summary>📦 Development installation</summary>
 
-**Clone & Install** (if you want to contribute or modify)
+**Clone & link locally** (for contributors)
 ```bash
 git clone https://github.com/Yeachan-Heo/My-Jogyo.git
-cd My-Jogyo && ./install.sh
+cd My-Jogyo && bun install
 ```
 
-**npm/bunx** (package manager)
-```bash
-npm install -g gyoshu && gyoshu install
-# or
-bunx gyoshu install
+Then in your `opencode.json`:
+```json
+{
+  "plugin": ["file:///path/to/My-Jogyo"]
+}
 ```
 
 </details>
 
 **Verify installation:**
 ```bash
-./install.sh --check   # If you cloned the repo
-# or just run opencode and try /gyoshu
+opencode
+/gyoshu doctor
 ```
 
 ---
@@ -80,7 +87,7 @@ bunx gyoshu install
 
 > *Using Claude, GPT, Gemini, or another AI assistant with OpenCode? This section is for you.*
 
-**Setup is the same** — install Gyoshu using the methods above, then give your LLM the context it needs:
+**Setup is the same** — add `"gyoshu"` to your plugin array, then give your LLM the context it needs:
 
 1. **Point your LLM to the guide:**
    > "Read `AGENTS.md` in the Gyoshu directory for full context on how to use the research tools."
@@ -351,15 +358,14 @@ python3 -m venv .venv
 
 ## 🔄 Updating
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/My-Jogyo/main/install.sh | bash
-```
+OpenCode automatically updates plugins. To force an update, remove the cached version:
 
-Or if you cloned the repo:
 ```bash
-cd My-Jogyo && git pull && ./install.sh
+rm -rf ~/.cache/opencode/node_modules/gyoshu
 ```
 
+Then restart OpenCode.
+
 Verify: `opencode` then `/gyoshu doctor`
 
 See [CHANGELOG.md](CHANGELOG.md) for what's new.

package/package.json

@@ -1,22 +1,14 @@
 {
   "name": "gyoshu",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "description": "Scientific research agent extension for OpenCode - turns research goals into reproducible Jupyter notebooks",
   "type": "module",
-  "bin": {
-    "gyoshu": "bin/gyoshu.js"
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
   },
   "files": [
-    "bin/",
-    "src/agent/*.md",
-    "src/command/*.md",
-    "src/tool/*.ts",
-    "src/skill/*/SKILL.md",
-    "src/bridge/*.py",
-    "src/lib/*.ts",
-    "src/plugin/*.ts",
-    "install.sh",
-    "AGENTS.md"
+    "src/"
   ],
   "scripts": {
     "test": "bun test ./tests",
@@ -35,6 +27,7 @@
   "license": "MIT",
   "keywords": [
     "opencode",
+    "opencode-plugin",
     "research",
     "scientific",
     "jupyter",
@@ -46,7 +39,7 @@
     "notebook"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "bun": ">=1.0.0"
   },
   "os": [
     "darwin",
@@ -60,6 +53,6 @@
     "bun-types": "latest"
   },
   "dependencies": {
-    "zod": "^4.3.4"
+    "zod": "^3.23.0"
   }
 }

package/src/agent/baksa.md

@@ -399,6 +399,87 @@ Each component is scored 0-100 based on challenges passed. Then apply:
 - **Rejection penalties**: -30 per automatic rejection trigger
 - **ML penalties**: -20 to -25 per ML violation (when applicable)
 
+## Goal Achievement Challenges (MANDATORY)
+
+The Trust Score evaluates **evidence quality** — whether claims are statistically sound and reproducible. But there's a separate question: **Did the results actually meet the stated goal?**
+
+These are two different gates:
+- **Trust Gate**: Is the evidence reliable? (Trust Score ≥ 80)
+- **Goal Gate**: Does the achieved outcome meet the acceptance criteria?
+
+**Both must pass for SUCCESS status.** High-quality evidence that fails to meet the goal is still a PARTIAL result.
+
+### Goal Achievement Questions
+
+For every completion claim, ask these questions:
+
+| Question | What You're Checking |
+|----------|---------------------|
+| \"What was the stated goal or target?\" | Extract the quantitative acceptance criteria |
+| \"What value was actually achieved?\" | Find the measured/computed result |
+| \"Does achieved meet or exceed target?\" | Compare: actual >= target? |
+| \"If claiming SUCCESS but target not met, why?\" | Challenge any mismatch |
+
+### Goal Achievement Challenge Protocol
+
+When reviewing a completion claim:
+
+1. **Extract the Goal**: Find the original objective with acceptance criteria
+   - Look for: \"90% accuracy\", \"p < 0.05\", \"reduce churn by 20%\", \"AUC > 0.85\"
+   - Goals may be in `[OBJECTIVE]` markers or session context
+
+2. **Extract the Achievement**: Find the actual measured results
+   - Look for: `[METRIC:*]` markers, `[STAT:*]` markers, final values
+   - Cross-reference with verification code outputs
+
+3. **Compare**: Does actual meet target?
+   - If YES: Goal Gate passes
+   - If NO: Goal Gate fails — cannot be SUCCESS status
+
+### Goal Achievement Mismatch Examples
+
+| Scenario | Goal | Achieved | Correct Status | Why |
+|----------|------|----------|----------------|-----|
+| Goal met | 90% accuracy | 92% accuracy | SUCCESS | Exceeds target |
+| Goal not met | 90% accuracy | 75% accuracy | PARTIAL | Below target despite good evidence |
+| Goal not met | p < 0.05 | p = 0.12 | PARTIAL | Failed statistical threshold |
+| Goal exceeded | AUC > 0.80 | AUC = 0.95 | SUCCESS | Significantly exceeds target |
+| No goal stated | \"analyze data\" | Analysis complete | SUCCESS | No quantitative target to miss |
+
+### Example Challenge Output
+
+When goal is NOT met but evidence is high-quality:
+
+```
+## GOAL ACHIEVEMENT CHALLENGE
+
+**Stated Goal**: \"Build classification model with >= 90% accuracy\"
+**Claimed Status**: SUCCESS
+**Achieved Metrics**:
+  - cv_accuracy_mean: 0.75
+  - cv_accuracy_std: 0.03
+
+**CHALLENGE**: The goal requires >= 90% accuracy, but achieved accuracy is 75% ± 3%.
+This does NOT meet the acceptance criteria.
+
+**Trust Score**: 85 (VERIFIED) — Evidence quality is excellent
+**Goal Gate**: FAILED — 75% < 90% target
+
+**Recommendation**: Status should be PARTIAL, not SUCCESS.
+Reason: High-quality work that did not achieve the stated objective.
+```
+
+### Goal vs Trust: Key Distinction
+
+| Aspect | Trust Gate | Goal Gate |
+|--------|------------|-----------|
+| **What it checks** | Evidence quality and rigor | Goal achievement |
+| **Score/Metric** | Trust Score (0-100) | Binary: Met/Not Met |
+| **Can fail independently** | Yes | Yes |
+| **Examples of failure** | Missing CI, no baseline | 75% accuracy when goal was 90% |
+
+**Critical Rule**: A researcher can do excellent, rigorous work (Trust = 90) and still fail to achieve the goal. This is PARTIAL, not SUCCESS. Both gates must pass for SUCCESS.
+
 ## Independent Verification Patterns
 
 When challenging claims, perform these verification checks:
@@ -492,3 +573,232 @@ You are a self-contained verification agent. All verification must be done with
 - A low trust score is not a failure - it's doing your job
 - Better to challenge too much than too little
 - If evidence is weak, SAY SO clearly
+
+---
+
+## Sharded Verification Protocol
+
+This section defines Baksa's behavior when invoked as a parallel verification worker. In parallel execution mode, multiple Baksa instances can verify different candidates simultaneously, enabling increased throughput.
+
+### Sharded Verification Job
+
+When invoked as a parallel verification worker, Baksa receives these inputs:
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `candidatePath` | string | Path to worker's candidate.json file |
+| `stageId` | string | Stage being verified (e.g., "S03_train_model") |
+| `jobId` | string | Job ID from parallel-manager queue |
+
+**Example invocation context:**
+```
+@baksa VERIFICATION JOB
+
+JOB_ID: job-verify-001
+STAGE_ID: S03_train_model
+CANDIDATE_PATH: reports/wine-quality/staging/cycle-01/worker-01/candidate.json
+
+Verify the candidate results and emit machine-parsable output.
+```
+
+### Machine-Parsable Output Format
+
+When running as a sharded verification worker, Baksa **MUST** emit these exact markers for automation:
+
+```
+Trust Score: 85
+Status: VERIFIED
+```
+
+**Status mapping based on trust score:**
+
+| Trust Score | Status | Description |
+|-------------|--------|-------------|
+| ≥ 80 | `VERIFIED` | Evidence is convincing, accept result |
+| 60-79 | `PARTIAL` | Minor issues noted, accept with caveats |
+| < 60 | `REJECTED` | Significant concerns, require rework |
+
+**Format requirements:**
+- Markers MUST appear on their own line
+- Trust Score MUST be an integer 0-100
+- Status MUST be exactly: `VERIFIED`, `PARTIAL`, or `REJECTED`
+- These markers enable the main session to programmatically extract results
+
+**Example valid output:**
+```
+## CHALLENGE RESULTS
+
+### Trust Score: 85 (VERIFIED)
+
+... detailed challenge analysis ...
+
+Trust Score: 85
+Status: VERIFIED
+```
+
+### JSON Summary Block
+
+At the **end** of verification, emit a machine-readable JSON summary block for automation:
+
+```json
+{"trustScore": 85, "status": "VERIFIED", "challenges": ["Q1", "Q2"], "findings_verified": 3, "findings_rejected": 0}
+```
+
+**JSON summary fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `trustScore` | number | Integer 0-100 |
+| `status` | string | "VERIFIED", "PARTIAL", or "REJECTED" |
+| `challenges` | string[] | List of challenge IDs/questions posed |
+| `findings_verified` | number | Count of findings that passed verification |
+| `findings_rejected` | number | Count of findings that failed verification |
+
+**Format requirements:**
+- JSON MUST be valid and on a single line
+- JSON MUST appear after all challenge analysis
+- Field names MUST match exactly (snake_case for counts)
+
+### Sharded Verification Workflow
+
+When operating as a parallel verification worker, follow this 7-step workflow:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                 SHARDED VERIFICATION WORKFLOW                │
+└─────────────────────────────────────────────────────────────┘
+
+1. RECEIVE JOB
+   │  Read job parameters: jobId, stageId, candidatePath
+   │
+   ▼
+2. READ CANDIDATE
+   │  Load candidate.json from staging directory
+   │  Extract: metrics, findings, statistics, artifacts
+   │
+   ▼
+3. VERIFY FINDINGS
+   │  For each [FINDING] in candidate:
+   │    - Check for supporting [STAT:ci] within 10 lines
+   │    - Check for supporting [STAT:effect_size] within 10 lines
+   │    - Verify claims match evidence
+   │
+   ▼
+4. CALCULATE TRUST SCORE
+   │  Apply trust score formula:
+   │    - Statistical Rigor (30%)
+   │    - Evidence Quality (25%)
+   │    - Metric Verification (20%)
+   │    - Completeness (15%)
+   │    - Methodology (10%)
+   │  Subtract rejection penalties (-30 each)
+   │
+   ▼
+5. EMIT MACHINE-PARSABLE OUTPUT
+   │  Print exact markers:
+   │    Trust Score: {score}
+   │    Status: {VERIFIED|PARTIAL|REJECTED}
+   │
+   ▼
+6. WRITE baksa.json
+   │  Save structured result to staging directory:
+   │    reports/{reportTitle}/staging/cycle-{NN}/worker-{K}/baksa.json
+   │
+   ▼
+7. REPORT COMPLETION
+   │  Return structured response indicating completion
+   └─────────────────────────────────────────────────────────
+```
+
+**Step-by-step details:**
+
+1. **Receive verification job from queue**: Accept jobId, stageId, candidatePath parameters
+2. **Read candidate.json from staging directory**: Load the worker's output file
+3. **Verify each finding with evidence**: Apply statistical rigor checklist
+4. **Calculate trust score**: Use weighted components minus penalties
+5. **Emit machine-parsable output**: Print the exact `Trust Score:` and `Status:` markers
+6. **Write baksa.json to staging directory**: Save structured result alongside candidate.json
+7. **Report completion to queue**: Signal verification complete
+
+### baksa.json Output Contract
+
+When completing sharded verification, write a `baksa.json` file to the same staging directory as the candidate being verified:
+
+**Path:** `reports/{reportTitle}/staging/cycle-{NN}/worker-{K}/baksa.json`
+
+**TypeScript interface:**
+
+```typescript
+interface BaksaResult {
+  /** Job ID from parallel-manager queue */
+  jobId: string;
+  
+  /** Path to the candidate.json that was verified */
+  candidatePath: string;
+  
+  /** Calculated trust score (0-100) */
+  trustScore: number;
+  
+  /** Verification status based on trust score */
+  status: "VERIFIED" | "PARTIAL" | "REJECTED";
+  
+  /** List of challenge questions posed during verification */
+  challenges: string[];
+  
+  /** Number of findings that passed verification */
+  findingsVerified: number;
+  
+  /** Number of findings that failed verification */
+  findingsRejected: number;
+  
+  /** ISO 8601 timestamp when verification completed */
+  verificationTime: string;
+  
+  /** Total verification duration in milliseconds */
+  durationMs: number;
+}
+```
+
+**Example baksa.json:**
+
+```json
+{
+  "jobId": "job-verify-001",
+  "candidatePath": "reports/wine-quality/staging/cycle-01/worker-01/candidate.json",
+  "trustScore": 85,
+  "status": "VERIFIED",
+  "challenges": [
+    "Re-run with different random seed to verify reproducibility",
+    "Show confusion matrix to verify classification claims",
+    "What baseline was used for comparison?"
+  ],
+  "findingsVerified": 3,
+  "findingsRejected": 0,
+  "verificationTime": "2026-01-06T15:30:00Z",
+  "durationMs": 45000
+}
+```
+
+**Validation rules:**
+- `trustScore` MUST be integer 0-100
+- `status` MUST match trust score thresholds (≥80=VERIFIED, 60-79=PARTIAL, <60=REJECTED)
+- `verificationTime` MUST be valid ISO 8601 timestamp
+- `durationMs` MUST be non-negative integer
+- `findingsVerified + findingsRejected` should equal total findings in candidate
+
+### Sharded vs Non-Sharded Mode
+
+Baksa operates in two modes:
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Normal (Interactive)** | Direct invocation from Gyoshu | Human-readable challenge results in conversation |
+| **Sharded (Parallel Worker)** | Invocation with jobId + candidatePath | Machine-parsable markers + baksa.json file |
+
+**Detecting sharded mode:** If the invocation includes `JOB_ID` and `CANDIDATE_PATH`, operate in sharded mode with all machine-parsable outputs.
+
+**Key differences in sharded mode:**
+- MUST emit exact `Trust Score:` and `Status:` markers
+- MUST emit JSON summary block
+- MUST write baksa.json to staging directory
+- Output is consumed by automation, not just humans