Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "harnish",
"version": "0.0.4",
"version": "0.0.5",
"description": "자율 구현 엔진. PRD 생성(drafti) → 자율 구현(harnish) → 점검(ralphi).",
"author": {
"name": "jazz1x",
Expand Down
7 changes: 1 addition & 6 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ jobs:
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest]
os: [macos-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
Expand All @@ -20,12 +20,7 @@ jobs:
with:
python-version: "3.12"

- name: Install bats + jq (ubuntu)
if: matrix.os == 'ubuntu-latest'
run: sudo apt-get update && sudo apt-get install -y bats jq

- name: Install bats + jq (macos)
if: matrix.os == 'macos-latest'
run: brew install bats-core jq

- name: Run test suite
Expand Down
39 changes: 37 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [0.0.5] - 2026-04-28

This release combines the asset-store identity correction with the production pipeline closure originally drafted as 0.0.6. Both ship together as 0.0.5.

### Fixed (CRITICAL — closed loop restored)
- **Trigger→Record pipeline closure**: hook이 `/tmp/harnish-pending-*.jsonl`에 적재한 실패 컨텍스트가 세션 종료 시 삭제만 되고 자산으로 영속화되지 않던 버그를 수정. `Stop` 이벤트가 새 `promote-pending.sh`를 호출하여 자동 dedup + `record-asset.sh` 호출 + 영속화. README의 "failures become guardrails" 약속이 처음으로 실제 동작.

### Changed
- **BREAKING (file rename, auto-migrated)**: Asset store renamed `.harnish/harnish-rag.jsonl` → `.harnish/harnish-assets.jsonl`. `init-assets.sh` performs an idempotent atomic `mv` on first run if the legacy file is present and the new file is absent. No data loss.
- Archive file renamed: `harnish-rag-archive.jsonl` → `harnish-assets-archive.jsonl` (`purge-assets.sh --execute` output)
- L0 Contract (`schema.json`) field rename: `rag_record` → `asset_record`, `storage.rag_file` → `storage.asset_file`
- 14 scripts: `RAG_FILE` / `RAG` shell variables → `ASSET_FILE` / `ASSETS`; `harnish-rag.jsonl` literals replaced
- `common.sh`: `resolve_rag_file()` kept as deprecated alias of `resolve_asset_file()`; new `resolve_legacy_asset_file()` for migration paths
- `scripts/skillify.sh` production-grade 업그레이드:
- description에 `Triggers: ...` 자동 생성 (자산 title에서 빈도 기반 5개 후보 추출)
- body 구조화: §1 가이드라인 (LLM finalize) / §2 타입별 자산 섹션 (Failures/Patterns/Guardrails/Decisions/Snippets) / §3 메타데이터
- `references/source-assets.jsonl` 트레이서빌리티 보존
- 자산 메타 필드 노출: level / confidence / stability / resolved
- `scripts/query-assets.sh --format inject` 출력에 RCA 컨텍스트 포함:
- guardrail은 `[guardrail/soft]`, decision은 `[decision/medium]`, pattern은 `[pattern/s1]`로 type 머리에 메타 노출
- 각 자산에 `context:` 라인 추가, failure는 `resolved:` 표시

### Added
- `scripts/promote-pending.sh` — pending JSONL을 `(tool, first_error_line)` 키로 deduplicate 후 자동으로 `failure` 자산 등록. 태그: `auto`, `tool:<name>`, `session:<short>`. context에 occurrences 카운트.
- `tests/e2e_pipeline.bats` — 4개 production E2E (trigger→record, dedup, skillify quality, inject 풍부화).
- `tests/scripts_advanced.bats` +2: legacy `harnish-rag.jsonl` → `harnish-assets.jsonl` migration regression + idempotency test
- README "Memory Model" section: documents the two-tier model (Tier 1 Asset Store + Tier 2 Skills) and clarifies that only `query-assets.sh --format inject` is strict RAG

### Documentation
- README "ralph loop"의 잘못된 약자 풀이 (`Read → Act → Log → Progress`) 제거. 이름은 심슨의 Ralph Wiggum에서 유래한 것이며 약자가 아님을 명시.
- Honest framing of `skillify.sh`: it is a draft generator (asset bundling + TODO scaffold), **not** autonomous skill graduation. Future feature flagged on roadmap.
- README/SKILL.md/thresholds.md path references updated to `harnish-assets.jsonl`

## [0.0.4] - 2026-04-27

### Fixed
Expand Down Expand Up @@ -72,7 +105,7 @@ First public release. 5 skills + shared script suite + asset infrastructure + au
#### impl `0.0.1` (the "harnish" engine)
- 자율 구현 엔진 (시딩 + ralph 루프 + 앵커링 + 경험 축적)
- 모드 A: PRD → 원자적 태스크 분해 → `harnish-current-work.json` 생성
- 모드 B: ralph 루프 (Read → Act → Log → Progress → repeat)
- 모드 B: ralph 루프 (한 태스크씩 자동 실행 → 결과 기록 → 진행률 갱신 반복)
- 모드 C: 세션 복원 (앵커링) + 자산 감지/기록/압축/스킬화
- §B.9 acceptance_criteria 실행: bash/조건/혼합/없음 4가지 분기
- 다언어 타입 체커 (Python/TS/Go/Java/Rust)
Expand Down Expand Up @@ -119,7 +152,9 @@ First public release. 5 skills + shared script suite + asset infrastructure + au
- README 구조 정리 (galmuri 동일 톤): badges, install steps, quickstart, usage, hooks, assets, worktrees, fork & customize, naming, triad
- VERSIONING.md, references/* 가이드

[Unreleased]: https://github.com/jazz1x/harnish/compare/v0.0.3...HEAD
[Unreleased]: https://github.com/jazz1x/harnish/compare/v0.0.5...HEAD
[0.0.5]: https://github.com/jazz1x/harnish/compare/v0.0.4...v0.0.5
[0.0.4]: https://github.com/jazz1x/harnish/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/jazz1x/harnish/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/jazz1x/harnish/compare/v0.0.1...v0.0.2
[0.0.1]: https://github.com/jazz1x/harnish/releases/tag/v0.0.1
78 changes: 50 additions & 28 deletions README.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

> Claude Code 플러그인 — 자율 구현 엔진

![version](https://img.shields.io/badge/version-0.0.4-blue)
![version](https://img.shields.io/badge/version-0.0.5-blue)
![license](https://img.shields.io/badge/license-MIT-green)
![claude-code](https://img.shields.io/badge/claude--code-plugin-purple)
![tests](https://img.shields.io/badge/tests-74%20passing-brightgreen)
![tests](https://img.shields.io/badge/tests-80%20passing-brightgreen)

**harnish** (harness + ish) = "대충 하네스 비스무리한 것" — 작업할수록 똑똑해지는 구현 환경. 실패가 가드레일이 되고, 패턴이 축적되며, 세션과 워크트리가 바뀌어도 맥락이 유실되지 않는다.

Expand All @@ -16,8 +16,8 @@
| Skill | Command | Role |
|-------|---------|------|
| **forki** | `/harnish:forki` | 의사결정 강제 (2지선택 + D/E/V/R + trade-off, HITL 전용) |
| **drafti-architect** | `/harnish:drafti-architect` | 기술 주도 설계 PRD 생성 |
| **drafti-feature** | `/harnish:drafti-feature` | 기획 기반 구현 명세 PRD 생성 |
| **drafti-architect** | `/harnish:drafti-architect` | 기술 주도 설계 PRD 생성 |
| **impl** | `/harnish:impl` | 자율 구현 엔진 — "harnish" 엔진 (시딩 + ralph 루프 + 앵커링 + 경험축적) |
| **ralphi** | `/harnish:ralphi` | 점검 (HITL 보고 또는 자율 수정) |

Expand Down Expand Up @@ -59,7 +59,7 @@ Claude Code 세션 안에서 실행:
예상 출력:

```
✓ Installed harnish@0.0.4 — 5 skills registered (forki, drafti-architect, drafti-feature, impl, ralphi)
✓ Installed harnish@0.0.5 — 5 skills registered (forki, drafti-feature, drafti-architect, impl, ralphi)
```

### 3. 확인
Expand All @@ -72,8 +72,8 @@ Claude Code 세션 안에서 실행:

```
/harnish:forki
/harnish:drafti-architect
/harnish:drafti-feature
/harnish:drafti-architect
/harnish:impl
/harnish:ralphi
```
Expand Down Expand Up @@ -102,21 +102,14 @@ harnish 의 훅은 `hooks/hooks.json` 에 정의되어 있고, 플러그인 로
/harnish:impl
```

예시 흐름 (단순화):
예시 흐름:

```
user > /harnish:impl docs/prd-redis-cache.md

step 1 > PRD 읽기 → 3 phase, 12개 원자적 태스크 식별
step 2 > 시딩 → .harnish/harnish-current-work.json 생성
step 3 > "Phase 1 Task 1.1 준비됨. 'loop' 입력 시 ralph 루프 시작"
user > loop

step 4 > [READ] task 1.1 → [ACT] 코드 작성 → [LOG] 결과 → [PROGRESS] 1/12
step 5 > Pass → 자산 기록 (pattern: connection-pool-init)
step 6 > 자동 진행 → task 1.2 …
step N > Phase 1 완료 → 마일스톤 보고 → Phase 2 계속? (y/n)
user > /harnish:impl docs/prd-redis-cache.md
→ 3 phase, 12개 원자적 태스크가 .harnish/harnish-current-work.json 에 시딩됨
user > loop
→ task 1.1 → 코드 → 기록 → 자산 등록 → 1.2 자동 진행 → … → Phase 1 완료
→ 마일스톤 보고 → Phase 2 계속? (y/n)
```

PRD 경로나 작업 설명 없이 호출하면 harnish 가 먼저 묻는다:
Expand Down Expand Up @@ -145,13 +138,13 @@ PRD 경로나 작업 설명 없이 호출하면 harnish 가 먼저 묻는다:
### 1. PRD 생성 (설계)

```
사용자: "Redis 캐시 레이어 설계해줘"
→ drafti-architect가 설계 대안 2~3개 탐색, 트레이드오프 분석
→ docs/prd-redis-cache.md 생성

사용자: "이 기획서로 PRD 만들어" (기획 문서 첨부)
→ drafti-feature가 구현 명세 PRD 생성 (피쳐플래그는 필요 시만)
→ docs/prd-user-profile-edit.md 생성

사용자: "Redis 캐시 레이어 설계해줘"
→ drafti-architect가 설계 대안 2~3개 탐색, 트레이드오프 분석
→ docs/prd-redis-cache.md 생성
```

### 2. 자율 구현 (harnish)
Expand All @@ -165,7 +158,8 @@ PRD 경로나 작업 설명 없이 호출하면 harnish 가 먼저 묻는다:
→ "Phase 3개, Task 12개 시딩 완료 — 확인 후 '루프 돌려'"

사용자: "루프 돌려"
→ ralph 루프 자동 실행 (Read → Act → Log → Progress → repeat)
→ ralph 루프가 한 태스크씩 자동 실행 (Phase 끝까지 반복)
("ralph"는 심슨의 랄프 위검에서 따온 이름 — 약자 풀이 아님)
→ 매 3액션마다 harnish-current-work.json 갱신, Phase 완료 시 마일스톤 보고

사용자: (새 세션에서) "이어서 진행"
Expand Down Expand Up @@ -193,7 +187,9 @@ PRD 경로나 작업 설명 없이 호출하면 harnish 가 먼저 묻는다:
→ 축적된 failure/pattern/guardrail/snippet/decision 현황 조회

사용자: "스킬로 만들어"
→ 압축된 자산에서 재사용 가능한 SKILL.md 초안 생성
→ 압축된 자산을 SKILL.md scaffold로 묶음 (원본 자산 본문 + TODO 마커).
본문은 LLM이 마무리해야 함 — draft generator일 뿐 자율 graduating은
아니다. 진짜 자율 승격은 향후 기능.
```

## Hooks
Expand All @@ -208,9 +204,35 @@ harnish 의 훅은 `hooks/hooks.json` 으로 설치 시 자동 등록된다. 별

실패는 신호/노이즈로 분류된다 — 단순 에러(`No such file`, `permission denied`, `command not found` 등)는 필터되고 의미 있는 실패만 자산이 된다.

## Memory Model

harnish는 **2단 기억 구조** (two-tier memory)로 동작한다. 각 tier의 역할이 다르며, 둘을 잇는 다리는 현재 반자동 상태.

| Tier | 저장 위치 | 수명 | 역할 | 로딩 방식 |
|------|----------|------|------|----------|
| **Tier 1 — Asset Store** (episodic) | `.harnish/harnish-assets.jsonl` | 프로젝트별, 세션 간 누적, TTL purge | 일어난 일을 기록 (failure, pattern, guardrail, snippet, decision) | `query-assets.sh --format inject` 로 컨텍스트 주입 (실제 RAG 경로) |
| **Tier 2 — Skills** (procedural) | `skills/*/SKILL.md` | 영구 (소스 트리 버전 관리) | 안정화된 행동 양식 | Claude Code가 자동 로드, 트리거 시 발동 |

`skillify.sh`가 그 다리 — 압축된 Tier-1 자산을 Tier-2 SKILL.md scaffold로 묶는다. v0.0.5부터 scaffold는 **production-grade**:

- frontmatter `Triggers:` 가 자산 title에서 자동 추출됨
- body는 자산 타입별 섹션 + 메타 (level / confidence / stability / resolved)
- `references/source-assets.jsonl` 로 원본 트레이서빌리티 보존
- §1은 여전히 LLM finalize 필요 (1-3개 가이드라인 도출) — draft generator일 뿐, 자율 graduating 아님

**Trigger → Record → Skillify 파이프라인 (v0.0.5에서 닫힘):**

```
PostToolUseFailure → detect-asset.sh (노이즈 필터) → /tmp/harnish-pending-*.jsonl
Stop → promote-pending.sh (dedup) → harnish-assets.jsonl
"스킬로 만들어" → skillify.sh → SKILL.md draft + references/
```

> **왜 "RAG"가 아니라 "assets"인가?** 엄밀한 의미의 RAG는 `query-assets.sh --format inject` 한 경로뿐. 나머지는 캡처 / 요약 / 노화 / 스킬 초안 공급 — 즉 자산 CRUD + 라이프사이클.

## Assets

모든 학습 결과는 `.harnish/harnish-rag.jsonl` 에 한 줄당 한 JSON 객체로 기록된다. 6가지 자산 타입:
모든 학습 결과는 `.harnish/harnish-assets.jsonl` 에 한 줄당 한 JSON 객체로 기록된다. 6가지 자산 타입:

| Type | 기록 시점 |
|------|---------|
Expand All @@ -232,7 +254,7 @@ bash scripts/purge-assets.sh # dry-run purge (-
bash scripts/migrate.sh # 스키마 최신 버전으로 백필
```

`.harnish/` 는 프로젝트 CWD 안에 위치하며 세션 간 유지된다. `impl`, `drafti-architect`, `drafti-feature` 가 각 스킬의 Step 2에서 태그 기반으로 관련 자산을 자동 참조한다.
`.harnish/` 는 프로젝트 CWD 안에 위치하며 세션 간 유지된다. `impl`, `drafti-feature`, `drafti-architect` 가 각 스킬의 Step 2에서 태그 기반으로 관련 자산을 자동 참조한다.

## 워크트리

Expand All @@ -255,7 +277,7 @@ mkdir -p .claude/skills
cp -r /path/to/harnish/skills/forki .claude/skills/
```

해당 스킬이 `forki` 로 호출 가능 (플러그인 네임스페이스 없음). `forki` 대신 `impl`, `ralphi`, `drafti-architect`, `drafti-feature` 중 어느 것도 가능.
해당 스킬이 `forki` 로 호출 가능 (플러그인 네임스페이스 없음). `forki` 대신 `impl`, `ralphi`, `drafti-feature`, `drafti-architect` 중 어느 것도 가능.

### B. 자체 플러그인 마켓으로 포크

Expand Down Expand Up @@ -283,7 +305,7 @@ git -C /path/to/harnish pull # 업데이트
- **harnish** = harness + ish (자율 구현 엔진)
- **ralphi** = ralph + i (점검)
- 유래: 심슨 가족의 캐릭터 '랄프 위검'처럼 포기하지 않고 끈질기게 시도한다는 의미
- **drafti** = draft + i (PRD 생성 — drafti-architect + drafti-feature)
- **drafti** = draft + i (PRD 생성 — drafti-feature + drafti-architect)
- **forki** = fork + i (의사결정 강제 — 2지선택 + D/E/V/R + trade-off, HITL 전용)

## Triad
Expand Down
Loading
Loading