refactor(autoresearch): follow upstream structure, keep the ledger reliable

[baleen37]

Summary

autoresearch 스킬을 karpathy/autoresearch 구조에 맞춰 단순화하고, 그 과정에서 e2e로 발견한 원장 누락 버그를 고칩니다. 순 -63줄.

Changes

1. 업스트림 구조 채택

	이전	지금
상태 파일	5개	3개 (autoresearch.md, run.sh, results.jsonl)
프로토콜 섹션	4개 (JSONL/실행/로깅/대시보드)	## The Loop 1개, 4단계
revert	git checkout -- . && git clean -fd	git reset --hard HEAD && git clean -fd
dashboard.md	매 실험 재생성	삭제 (JSONL이 source of truth, 파생물 비용이 실험 수에 선형)

업스트림의 simplicity principle("코드 삭제로 얻은 modest win이 복잡도 추가로 얻은 동일 win보다 낫다")과 program.md 대응 관계도 명시했습니다.

2. 원장 append 버그 수정 (핵심)

중간에 TSV로 옮겨봤다가 되돌렸는데, 그 과정에서 실제 버그를 잡았습니다. 포맷 예시만 있고 구체적인 append 명령이 없으면 단계가 조용히 스킵됩니다. resume 경로에는 헤더가 없어서 "append a row"의 대상이 존재하지 않기 때문입니다.

e2e 실측: 루프가 567ms → 29ms 최적화에 성공하고 커밋도 정확했는데, results.tsv를 아예 만들지 않았습니다. 자율 루프에서 원장 누락은 곧 작업 유실입니다 — 다음 에이전트가 같은 실험을 재시도합니다.

수정: results.jsonl 복원(echo 한 줄, 헤더 분기 불필요) + "모든 실험은 이 append로 끝난다, 예외 없음" 명문화. secondary metric은 "metrics":{} 객체라 중간 추가 시 기존 행 재작성이 필요 없습니다(TSV 칼럼 추가는 필요했음).

3. 셸 루프 실행 모드 문서화

컨텍스트 윈도우보다 긴 무인 실행용. 매 iteration이 fresh context를 받고, 기존 resume 경로가 상태를 복원합니다. 추가 파일 0개.

--plugin-dir 제안은 실측에서 스킬을 로드하지 못해 삭제했습니다. 실제로 동작하는 것은 이 스킬의 트리거와 맞는 프롬프트이며, 그대로 문서화했습니다.

4. 유지한 교정 3개 (업스트림에는 없음)

PIPESTATUS exit code 캡처, Goodhart 가드레일, 노이즈밴드 N≥3 판정. 훅과 커맨드의 구 파일명 참조도 함께 갱신했습니다.

Tests

e2e 시나리오 (실제 claude -p 루프 실행, 실제 최적화 대상 repo) — 7/7 PASS

{"commit":"bd94978","metric":351,"status":"keep","description":"baseline (median of 3: 344/353/351ms; ~300ms is the sleep 0.3)"}
{"commit":"96155fe","metric":32,"status":"keep","description":"drop no-op sleep 0.3 + closed-form sum instead of seq loop (median of 3)"}

results.jsonl 생성 / 전 행 유효 JSON(jq -e) / 필수 키 4개 / SKILL.md의 jq 조회 명령 실동작 / 구 파일 미생성 / 출력 계약 유지(sum=20100) / 원장 누락 재발 없음.

부수 확인 두 가지:

• 노이즈밴드 판정 작동 — 에이전트가 지시 없이 median of 3을 재고 range를 기록
• Goodhart 가드레일 자발 발동 — echo "sum=20100" 하드코딩 아이디어를 두고 "계산 자체를 없애는 거라 진짜 최적화인지 워크로드 삭제인지 애매하다"며 판단 보류

훅 e2e — 4/4 PASS (활성/비활성 분기, results.jsonl 언급, 구 파일명 미언급, off 센티널, 재활성)

정적 검증 — bats tests/ 70 passed 0 failed / shellcheck OK / SKILL.md markdownlint 위반 23 → 0

Notes

.autoresearch/autoresearch.jsonl을 쓰던 진행 중 세션이 있다면 파일명이 results.jsonl로 바뀌었습니다. 마이그레이션 경로는 넣지 않았습니다.

Summary by CodeRabbit

• Documentation
  • Updated experiment guidance with a simpler setup and execution workflow.
  • Standardized result logging in JSONL format, including optional secondary metrics.
  • Improved resume instructions to identify the baseline, best metric, and corresponding commit.
  • Clarified how to handle discarded or failed experiments by reverting changes.
  • Removed outdated requirements for worklogs, dashboards, and legacy experiment state formats.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 42693d8e-d019-40d6-b7e1-c3db338c0a10

📥 Commits

Reviewing files that changed from the base of the PR and between 88c68c7 and 938a174.

📒 Files selected for processing (3)

• plugins/autoresearch/commands/autoresearch.md
• plugins/autoresearch/hooks/autoresearch-context.sh
• plugins/autoresearch/skills/autoresearch/SKILL.md

---

📝 Walkthrough

Walkthrough

The autoresearch plugin now uses .autoresearch/results.jsonl for baseline and experiment records. Its skill defines benchmark execution, metric-based decisions, Git commit or reset handling, secondary metrics, resume behavior, unattended loops, and ideas tracking.

Changes

Autoresearch workflow

Layer / File(s)	Summary
Workflow setup and benchmark contract plugins/autoresearch/skills/autoresearch/SKILL.md	Setup now creates autoresearch.md and run.sh, logs the baseline, defines benchmark output, and tracks ideas in ideas.md.
Experiment execution and status decisions plugins/autoresearch/skills/autoresearch/SKILL.md, plugins/autoresearch/hooks/autoresearch-context.sh	The workflow captures METRIC output, checks exit codes, evaluates primary and secondary metrics, and requires JSONL logging with git reset for losing runs.
Keep, discard, and result recording plugins/autoresearch/skills/autoresearch/SKILL.md	Kept experiments commit changes and log hashes. Discarded or crashed experiments reset the working tree and append results to results.jsonl.
Resume and best-result guidance plugins/autoresearch/commands/autoresearch.md, plugins/autoresearch/skills/autoresearch/SKILL.md	Resume logic reads results.jsonl, identifies the baseline and best result, and reports the achieving commit and secondary metrics.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AutoresearchAgent
  participant run.sh
  participant Git
  participant results.jsonl
  AutoresearchAgent->>run.sh: Execute benchmark
  run.sh-->>AutoresearchAgent: Return METRIC output and exit code
  AutoresearchAgent->>Git: Commit kept changes or reset discarded changes
  AutoresearchAgent->>results.jsonl: Append one experiment result object

Loading

Possibly related PRs

• baleen37/bstack#582: Continues the autoresearch state protocol migration to .autoresearch/results.jsonl.
• baleen37/bstack#657: Updates the same autoresearch command, hook, and skill files.
• baleen37/bstack#668: Introduces the restored autoresearch plugin workflow updated by this change.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/autoresearch-shell-loop

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}