voidlight00/fable-forge/fable-pipeline

fable-pipeline — Fable Forge 오케스트레이터

SSoT는 ~/fable-forge/REQUIREMENTS.md다. 모든 판정은 그 파일의 FR/FZ/FW 번호와 게이트 스크립트 exit code를 기준으로 한다. 가이드 근거가 필요하면 ~/fable-forge/knowledge/fable5-prompting.md(공식 원문)와 knowledge/ 스냅샷 7종을 읽는다.

실행 모드: subagent 모드 (단방향 파이프라인)

이 하네스는 팀(양방향 통신)이 아니라 subagent 단방향 파이프라인으로 실행한다. 이유: 각 에이전트는 입력을 받아 산출물을 파일로 쓰고 경로를 반환하면 역할이 끝난다. 에이전트 간 실시간 협상이 필요한 지점이 없고, 결과 전달은 파일 시스템과 RUN_MANIFEST.json으로 충분하다. 통신 인프라를 추가하면 비용만 늘고 신뢰성은 늘지 않는다.

독립적인 산출물(예: harness 모드의 agents/와 skills/)은 병렬로 디스패치하고, 한 서브에이전트의 결과를 기다리며 전체를 멈추지 않는다. 서브에이전트가 궤도를 벗어나거나 컨텍스트가 부족해 보이면 개입한다 [guide: Parallel subagents].

모든 Agent 호출에 model: "fable"을 명시한다. 이 하네스의 존재 이유가 Fable 5 단일 운용이므로, 오케스트레이터 자신이 작업을 다른 모델로 흘리면 목적 자체가 무너진다 (FR5).

모드 판정

판정이 애매하면 입력에 경로가 있는지 먼저 본다. 경로가 있으면 convert/audit 계열, 없으면 생성 계열이다. 그래도 애매하면 prompt로 진행한다 — 가장 안전한 기본값이고, 잘못 판정해도 Phase 1 인터뷰에서 교정된다.

Phase 0 — 컨텍스트 확인

1. date +%Y%m%d-%H%M%S를 실행해 현재 시각을 얻는다 (run_id와 매니페스트 타임스탬프에 사용 — 모델 추정 금지).
2. ~/fable-forge/runs/를 스캔한다 (ls -t 최근순).

2.5. ~/fable-forge/FAILURE_LOG.md의 결함 테이블에서 승격 여부가 - 또는 승격대상인 행을 읽는다 — 아직 게이트로 굳지 않은 교훈이므로 이번 실행에서 같은 실수를 반복하지 않도록 작업 체크 항목으로 삼는다 [guide: Construct a memory system].

1. 분기:

• 기존 run 존재 + 부분 수정 요청 ("아까 그 프롬프트 effort만 바꿔줘" 등) → 해당 run 디렉토리를 재사용하고 영향받는 Phase만 부분 재실행한다. 게이트는 전체 재실행한다 (부분 수정도 fallback 위험을 새로 만들 수 있다).
• 새 입력 → 새 run_id를 만든다. 형식: YYYYMMDD-HHMMSS-<slug> (slug는 입력에서 뽑은 2~4단어 영문 케밥케이스). mkdir -p ~/fable-forge/runs/<run_id> 후 RUN_MANIFEST.json 초기화.
• status → 해당 run의 RUN_MANIFEST.json을 읽고 phases[]/gates를 그대로 보고한다. run_id 미지정이면 최근 run.
• resume → RUN_MANIFEST.json에서 status != "done"인 첫 phase부터 재개한다. 매니페스트가 없거나 깨졌으면 새 run으로 처리하고 그 사실을 보고한다.

Phase 1 — 입력 정련 (FR11)

입력이 모호하면 AskUserQuestion으로 최대 3문항을 묻는다: ① 목적(이 산출물로 뭘 하려는지), ② 대상·사용자(누가 쓰는지), ③ 산출 형태(프롬프트 한 장인지, 하네스 전체인지).

인터뷰는 보강이지 차단이 아니다. 응답이 없거나 사용자가 건너뛰면 합리적 기본값으로 진행한다 — 추상 입력 그대로도 동작해야 한다는 것이 FR11의 핵심이다. 이미 충분히 구체적인 입력에는 묻지 않고 바로 행동한다 [guide: Longer turns by default].

정련 결과는 "의도/대상/형태" 3줄 요약으로 매니페스트 input_refined에 기록하고, 이후 모든 서브에이전트 프롬프트 머리에 넣는다 — Fable 5는 요청 뒤의 의도를 알 때 더 잘 작동한다 [guide: Give the reason, not only the request].

Phase 1.5 — 도메인 위험 체크 (FR13)

입력이 공격적 사이버보안(익스플로잇·공격 도구 제작류) 또는 생물학 실험 방법 도메인에 닿으면, 산출물이 Fable 5 cyber/bio classifier에 걸려 refusal → fallback이 날 수 있음을 사용자에게 먼저 경고한다.

• 정당한 방어·교육·연구 목적이 확인되면, 산출 프롬프트에 의도 명시 문구를 주입한다 (예: "본인 소유 시스템의 방어 점검 목적", "학부 교육용 개념 설명 수준"). 이것은 정상·정당한 작업임이 분류기에 드러나도록 의도를 명시하는 것이다 — 가이드도 benign 작업이 오탐될 수 있다고 명시한다 [guide: Capability improvements].
• 권한·소유 맥락이 전혀 없으면 진행 전에 확인을 받는다. 이 한 가지는 사용자만 줄 수 있는 입력이므로 멈추는 것이 옳다 [guide: Strong instruction following].

Phase 2 — 모드별 디스패치

모든 호출에 model: "fable" 명시. 각 서브에이전트에게 run_dir 절대경로, 정련된 입력, 모드별 필수 산출물 목록(REQUIREMENTS.md 모드 정의 표)을 전달한다.

‖ 표시는 병렬 디스패치를 뜻한다. convert/audit에서 auditor의 lint 실행 결과는 참고 정보일 뿐이고, 공식 판정은 Phase 3에서 오케스트레이터가 직접 실행한 게이트 exit code다 (NFR3 — 자가보고 금지).

프롬프트 생성물에는 FR1 4요소(의도/이유 프레이밍, effort 권고, 경계 선언, 자율 실행 지시)와 ## 사용법(FR12), [guide:] 태그(FR14)가 들어가야 한다. effort 권고는 기본 high, 최고 민감 작업만 xhigh, 루틴·서브에이전트는 medium/low다 — Opus 4.8 시절의 xhigh 기본 관행을 복사하지 않는다 [guide: Consider all effort levels].

Phase 3 — 게이트 (fail-closed, 수정 루프 최대 3회)

게이트 통과 여부는 스크립트 exit code로만 판정한다. 에이전트의 "통과했다"는 보고는 증거가 아니다 (NFR3).

# ① Fallback-Zero HARD 게이트
bash ~/fable-forge/gates/fable_lint.sh <산출물 경로>
# exit 0 → ②로. exit 2 → HARD 위반: 위반 룰ID/파일/라인을 fable-fallback-auditor에
#          반송해 수정시키고 재lint (루프 카운트 +1).
# exit 3 → 게이트 자체 오류(usage/스캔 실패): 수정 루프가 아니라 즉시 중단 보고 (fail-closed).
 
# ② 매니페스트에 lint 결과 기록 (completeness_gate가 이 기록을 검사한다 — 순서 고정)
#    RUN_MANIFEST.json gates.lint = "PASS", gates.lint_exit = 0
 
# ③ 완전성 게이트
bash ~/fable-forge/gates/completeness_gate.sh ~/fable-forge/runs/<run_id> <mode>
# exit 0 → Phase 4로. exit 3 → [MISSING] 항목을 담당 에이전트(생성 계열은 converter/
#          context-engineer, prompt는 prompt-architect)에 반송해 보완 후 ①부터 재실행.
#          단, 출력이 "unknown mode"/usage 오류면 반송이 아니라 즉시 중단 보고.

수정 루프는 ①~③ 전체 기준 최대 3회. 3회째에도 실패하면 조용히 통과시키지 말고: 매니페스트 gates에 FAIL과 exit code를 기록하고, 미해결 룰ID/[MISSING] 항목을 그대로 사용자에게 보고한 뒤 종료한다.

# ④ (opt-in, FR15) 라이브 스모크 — 사용자가 --live를 명시했을 때만 실행
bash ~/fable-forge/gates/live_smoke.sh <prompt 파일>
# 생성 프롬프트를 claude-fable-5 헤드리스에 1회 보내 (본 작업 수행 금지 probe 부착)
# 실제 safety classifier 통과를 실측한다. 정적 lint가 패턴을 막고 이 게이트가 실행을 증명한다.
# exit 2 → 실제 refusal 증거: Phase 1.5 의도 명시 문구를 보강해 재생성 후 재실행.
# exit 3 → infra 오류(claude CLI 부재 등): 게이트 실패가 아니라 환경 문제로 보고.

게이트 통과 후 여유가 있으면 fable-qa-verifier(model: "fable", 신선한 컨텍스트)를 띄워 산출물을 REQUIREMENTS.md 대비 교차 검증한다 — 작업 컨텍스트를 공유하지 않는 검증자가 자기비평보다 잘 잡는다 [guide: Recommended scaffolding changes].

Phase 4 — 보고

결과 먼저, 상세는 뒤에. 보고서 첫 문장은 "무엇이 만들어졌고 게이트가 통과했는가"다 [guide: Readability when communicating with the user]. 포함 항목:

1. 산출물 절대경로 목록.
2. 게이트 exit code 실측값 (실행한 명령과 함께). 모든 주장은 이 세션의 도구 결과에 근거를 둔다 — 미검증이면 미검증이라고 쓴다 [guide: Ground progress claims during long runs].
3. 산출물에 적용된 패턴의 [guide:] 태그 목록 (FR14).
4. 미해결 사항 (있으면 — 숨기지 않는다).

실행 중 발견한 결함(게이트 누락 패턴, 에이전트 반복 실수 등)은 ~/fable-forge/FAILURE_LOG.md에 한 건당 한 항목으로 누적 기록한다 (FR9). 같은 결함이 2회 이상 반복되면 lint 룰 승격을 제안한다 — 교훈을 기록하고 다음 실행이 참조하게 하는 것이 메모리 시스템의 목적이다 [guide: Construct a memory system].

RUN_MANIFEST.json 스키마 (FR8)

created/updated는 date +%Y-%m-%dT%H:%M:%S%z 실행 결과를 기록한다. 각 Phase 완료 시 즉시 갱신한다 (중간 크래시에도 resume 가능해야 한다).

{
  "run_id": "20260610-153000-lecture-prompt",
  "mode": "prompt",
  "input": "강의 자료 만들어줘",
  "input_refined": "의도: 병원 직원 대상 AI 교육 / 대상: 비개발자 / 형태: 재사용 프롬프트 1장",
  "phases": [
    { "phase": "0-context", "status": "done" },
    { "phase": "1-refine", "status": "done", "questions_asked": 2 },
    { "phase": "1.5-domain", "status": "done", "risk": "none" },
    { "phase": "2-dispatch", "status": "done", "agents": ["fable-prompt-architect"] },
    { "phase": "3-gates", "status": "done", "fix_loops": 1 },
    { "phase": "4-report", "status": "done" }
  ],
  "gates": {
    "lint": "PASS",
    "lint_exit": 0,
    "completeness": "PASS",
    "completeness_exit": 0
  },
  "artifacts": ["prompt.md"],
  "created": "2026-06-10T15:30:00+0900",
  "updated": "2026-06-10T15:42:11+0900"
}

에러 핸들링

• 서브에이전트 실패 (빈 산출물, 도구 오류): 실패 내용을 프롬프트에 추가해 1회 재시도한다. 재시도도 실패하면 해당 phase를 "status": "failed"로 기록하고 사용자에게 보고한다.
• 게이트 스크립트 자체 오류 (lint exit 3, completeness usage 오류): 수정 루프 대상이 아니다. 즉시 중단하고 stderr를 첨부해 보고한다 (fail-closed — 게이트가 깨진 채 통과 판정을 내리는 것이 최악의 결과다).
• 게이트 스크립트 변경이 필요해 보이면: 직접 고치기 전에 bash ~/fable-forge/gates/selftest.sh로 현재 동작을 확인하고, 변경 후에도 selftest exit 0을 확인한다.
• 사용자에게 멈춰 묻는 것은 파괴적 작업, 실제 범위 변경, 사용자만 줄 수 있는 입력(FR13 권한 맥락 등)일 때만이다. 원 요청에서 따라 나오는 가역적 작업은 묻지 않고 진행한다 [guide: Rare cases of early stopping].

테스트 시나리오

시나리오 1 — 정상 흐름 (prompt 모드, 추상 입력)

1. 입력: /fable "강의 자료 만들어줘" → 모드 키워드 없음 → prompt 판정.
2. Phase 0: 신규 run_id 20260610-HHMMSS-lecture-material 생성, 매니페스트 초기화.
3. Phase 1: 목적/대상/형태 3문항 → 무응답 시 기본값("일반 교육용, 비개발자, 프롬프트 1장")으로 진행.
4. Phase 1.5: cyber/bio 해당 없음 → "risk": "none".
5. Phase 2: fable-prompt-architect(model: "fable")가 runs/<id>/prompt.md 생성 — 4요소+effort 권고+## 사용법+[guide:] 태그 포함.
6. Phase 3: lint exit 0 → 매니페스트 "lint": "PASS" → completeness exit 0.
7. 검증 (실측): grep -c '\[guide:' runs/<id>/prompt.md ≥ 1, 두 게이트 exit code 0, ## 사용법 grep 히트.

시나리오 2 — 에러 흐름 (convert 모드, FZ1 잔존)

1. 입력: /fable convert <구형 스킬 경로> — 대상 파일에 reasoning-echo 지시(FZ1 위반)가 남아 있는 경우. 재현 fixture: ~/fable-forge/gates/fixtures/bad.md.
2. Phase 2: converter가 1차 변환본을 runs/<id>/converted/에 생성했으나 FZ1 라인을 놓침.
3. Phase 3 ①: fable_lint.sh runs/<id>/converted/ → [HARD FZ1] 출력, exit 2.
4. 반송: 위반 파일·라인을 fable-fallback-auditor에 전달해 제거/재서술 (fix_loops=1).
5. 재lint → exit 0 → 매니페스트 "lint": "PASS" 갱신 → completeness exit 0 → conversion-report.md에 FZ1 제거 사유를 [guide: Recommended scaffolding changes] 태그와 함께 기록.
6. 만약 3회 루프에도 exit 2가 반복되면: gates.lint = "FAIL", 잔존 룰ID와 라인을 사용자에게 명시 보고하고 종료 (조용한 통과 금지).