Migrate Graphify harness to a raw source corpus

.agents/skills/doc-manager/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Doc Manager"
   short_description: "Alias for the repository docs and harness sync workflow"
-  default_prompt: "Use $doc-manager to run the repository docs-manager workflow for README.md, AGENTS.md, .github/copilot-instructions.md, .harness/reference/local-adaptation.md, docs/sources, and docs/wiki."
+  default_prompt: "Use $doc-manager to run the repository docs-manager workflow for README.md, AGENTS.md, .github/copilot-instructions.md, .harness/reference/local-adaptation.md, and the `raw/` Graphify source corpus."

.agents/skills/docs-manager/SKILL.md

@@ -1,127 +1,96 @@
 ---
 name: docs-manager
-description: "Manage the repository documentation system end-to-end. Use when: ingest new source, query wiki, lint wiki, add wiki page, update INDEX.md, create ADR, sync README.md, sync AGENTS.md, sync .github/copilot-instructions.md, sync .harness/reference/local-adaptation.md, or run a full docs/harness sync after code changes."
-argument-hint: "ingest, query, lint, update, or sync — describe what you want to do"
+description: "Manage the repository documentation and Graphify source corpus end-to-end. Use when: maintain raw/, review Graphify artifacts, update README.md, sync AGENTS.md, sync .github/copilot-instructions.md, sync .harness/reference/local-adaptation.md, or run a full docs/harness sync after code changes."
+argument-hint: "raw sync, graph review, ADR update, or docs sync"
 ---
 
 # docs-manager
 
-3-레이어 지식 저장소(원문 소스 / 위키 / 스키마)와
-저장소 루트 문서/하네스 진입점(`README.md`, `AGENTS.md`,
+Graphify-first 지식 레이어(`graphify-out/`)와 human-owned source corpus(`raw/`),
+그리고 저장소 루트 문서/하네스 진입점(`README.md`, `AGENTS.md`,
 `.github/copilot-instructions.md`, `.harness/reference/local-adaptation.md`)을 함께 관리하는 스킬이다.
-모든 작업은 프로젝트 루트의 `AGENTS.md` 스키마를 따른다.
 
 ## When to Use
 
-- 새 소스 문서를 `docs/sources/`에 추가하고 위키에 반영할 때 (인제스트)
-- 위키 지식을 기반으로 질문에 답변할 때 (쿼리)
-- 위키 상태를 점검하고 문제를 수정할 때 (린트)
-- 위키 페이지를 직접 생성/수정할 때
-- 코드/CLI/워크플로 변경 후 `README.md`와 하네스 문서를 자동 반영할 때
+- `raw/` 아래 설계 source, ADR, 외부 문서를 추가/정리할 때
+- `graphify-out/GRAPH_REPORT.md`를 검토해 하네스/README 반영이 필요한지 점검할 때
+- verified full refresh 결과를 루트 `graphify-out/`로 동기화할 때
+- 코드/CLI/워크플로 변경 후 사용자-facing 문서와 하네스 규칙을 한 번에 정리할 때
 
 ## Procedure
 
 ### Step 0: 스키마 로드
 
-**모든 오퍼레이션의 첫 단계로** 반드시 프로젝트 루트의 `AGENTS.md`를 읽는다.
-이 파일에 3-레이어 구조, 6종 페이지 타입별 프론트매터/본문 템플릿, 컨벤션, 워크플로가 정의되어 있다.
-스키마가 변경될 수 있으므로 **캐시하지 말고 매번 읽는다**.
+항상 프로젝트 루트의 `AGENTS.md`를 먼저 읽는다.
+`raw/` source corpus 모델, `graphify-out/` generated output, auto-refresh 규칙이 이 파일에 정의되어 있다.
 
-sync/update 계열 작업이라면 추가로 아래 파일도 함께 읽는다.
+sync/update 작업이라면 추가로 아래 파일을 함께 읽는다.
 
+- `raw/README.md`
+- `graphify-out/GRAPH_REPORT.md` (존재 시)
+- `graphify-out/graph.json` (존재 시)
 - `README.md`
 - `.github/copilot-instructions.md`
 - `.harness/reference/local-adaptation.md`
-- `docs/wiki/INDEX.md`
 
-### Operation: Ingest (인제스트)
+### Operation: Raw Source Maintenance
 
-새 소스를 원문 컬렉션에 추가하고 위키에 반영한다.
+`raw/`를 Graphify source corpus 관점에서 유지한다.
 
-1. **소스 확인** — 사용자가 지정한 `docs/sources/{category}/` 파일을 읽는다
-2. **요약 페이지 생성** — `docs/wiki/summaries/<slug>.md` 작성 (Summary 타입)
-3. **영향 분석** — `docs/wiki/INDEX.md`를 읽고 영향받는 기존 페이지를 식별한다
-4. **기존 페이지 업데이트** — 관련 페이지에 새 소스 내용 반영, `sources` 프론트매터에 경로 추가
-5. **신규 페이지 생성** — 새로운 엔티티/개념이 발견되면 해당 타입 페이지 생성
-6. **교차 참조 갱신** — 새 페이지 ↔ 기존 페이지 간 양방향 링크 추가
-7. **인덱스 업데이트** — `INDEX.md` + 관련 카테고리 `README.md` 동시 업데이트
-8. **인제스트 로그** — `docs/wiki/logs/ingest-YYYY-MM-DD-<slug>.md` 작성
+1. `raw/design/adr/`에 ADR을 추가하거나 갱신한다
+2. `raw/design/notes/`에 설계 노트/개요를 추가하거나 갱신한다
+3. `raw/external/`에 논문/데이터셋/모델/실험 자료를 정리한다
+4. `references/`는 Graphify source가 아니므로 source corpus와 섞지 않는다
 
-**주의**: 단일 소스가 10~15개 위키 페이지에 영향 가능. 중복 행 삽입에 주의한다.
+### Operation: Graph Sync
 
-### Operation: Query (쿼리)
+Graphify artifact를 재생성하고 committed knowledge layer를 갱신한다.
 
-위키를 대상으로 질문에 답변한다.
+1. code-only drift면 `scripts/graphify_code_refresh.sh`를 실행한다
+2. `raw/` source가 바뀌었거나 full refresh가 필요하면 아래 순서를 사용한다
+   - `scripts/graphify_prepare_corpus.sh`
+   - `scripts/graphify_full_refresh.py`
+   - `scripts/graphify_verify_full_refresh.py`
+   - `scripts/graphify_sync_staged.sh`
+3. `graphify-out/BUILD_INFO.json`의 `mode`와 `verified`를 확인한다
 
-1. **질문 분석** — 관련 키워드, 개념, 엔티티 식별
-2. **페이지 탐색** — `INDEX.md` 참조 → 관련 위키 페이지 읽기
-3. **답변 합성** — 관련 페이지를 인용하며 답변 구성 (`[페이지](경로)에 따르면 ...`)
-4. **출력 형태 선택** — 마크다운, 비교 표, Marp 슬라이드, matplotlib 차트 등
-5. **(선택) 위키 저장** — 사용자 승인 후 overview/comparison 등으로 저장
+### Operation: Graph Review
 
-### Operation: Lint (린트)
+Graphify 산출물을 사람이 읽는 문서와 하네스 규칙에 연결한다.
 
-위키 상태를 점검하고 문제를 보고한다.
-
-1. **페이지 목록 로드** — `INDEX.md`에서 전체 목록 파악
-2. **전수 스캔** — 모든 위키 페이지 읽기
-3. **체크리스트 점검**:
-   - `[HIGH]` 모순 검출 — 페이지 간 상충하는 주장
-   - `[HIGH]` 낡은 정보 — 최신 소스에 의해 대체된 주장
-   - `[MEDIUM]` 고아 페이지 — 인바운드 링크 없는 페이지
-   - `[MEDIUM]` 누락 개념 — 참조되지만 자체 페이지 없는 개념
-   - `[LOW]` 누락 교차 참조 — 관련 페이지 간 빠진 링크
-   - `[LOW]` 데이터 공백 — 추가 소스로 채울 수 있는 빈 영역
-4. **보고서 출력** — 심각도별 표 + 제안 조치
-5. **(선택) 자동 수정** — 사용자 승인 후 교차 참조, 인덱스 갱신 등 적용
+1. `graphify-out/GRAPH_REPORT.md`를 읽는다
+2. 새 핵심 노드, community, drift를 확인한다
+3. 아래 문서 반영이 필요한지 판단한다
+   - `README.md`
+   - `AGENTS.md`
+   - `.github/copilot-instructions.md`
+   - `.harness/reference/local-adaptation.md`
+   - `.github/pull_request_template.md`와 PR workflow 문구
 
-### Operation: Sync (동기화 루틴)
+### Operation: Sync
 
-코드/CLI/워크플로 변경 뒤, 사용자-facing 문서와 하네스 규칙 파일을 한 번에 동기화한다.
+코드/CLI/워크플로 변경 뒤 문서와 하네스 규칙을 한 번에 동기화한다.
 
-1. **변경 범위 파악** — 최근 diff나 변경 파일에서 사용자에게 보이는 워크플로 변화가 있는지 확인한다
-2. **README 반영** — quick start, validation, workflow, docs 링크 중 영향받는 섹션을 갱신한다
-3. **하네스 반영** — 아래 파일에 새 워크플로/명령/규칙을 반영한다
+1. 변경 범위를 파악한다
+2. `raw/`와 `graphify-out/GRAPH_REPORT.md` 사이 드리프트를 확인한다
+3. 아래 파일에 새 워크플로/명령/규칙을 반영한다
+   - `README.md`
    - `AGENTS.md`
    - `.github/copilot-instructions.md`
    - `.harness/reference/local-adaptation.md`
-4. **위키 영향 분석** — 새 엔티티/개념/ADR가 필요하면 `docs/wiki/`에 추가한다
-5. **위키 동기화** — `INDEX.md` + 관련 카테고리 `README.md` + 양방향 `## Related`를 함께 갱신한다
-6. **드리프트 점검** — README와 하네스 파일이 현재 구현 명령/경로/모듈 설명과 어긋나지 않는지 확인한다
-
-이 모드는 사실상 이 저장소의 **문서 자동 반영 루틴 기본값**이다.
-사용자가 `/docs-manager`만 입력해도 명시적인 다른 모드가 없다면 우선 sync 가능성을 먼저 점검한다.
+   - `.github/pull_request_template.md` 관련 운영 규칙
 
 ## Quality Checks
 
-모든 오퍼레이션 완료 후 아래를 확인한다:
-
-- [ ] 모든 위키 페이지에 YAML 프론트매터가 있는가? (title, date, type 필수)
-- [ ] `INDEX.md`에 등록된 페이지와 실제 파일이 1:1 매칭되는가?
-- [ ] 중복 행이 INDEX.md나 카테고리 README에 없는가?
-- [ ] 교차 참조가 양방향으로 설정되어 있는가?
-- [ ] `sources` 프론트매터에 올바른 소스 경로가 명시되어 있는가?
-- [ ] `README.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.harness/reference/local-adaptation.md`가 현재 구현과 일치하는가?
-- [ ] 새 CLI 명령이나 워크플로가 생겼다면 README와 하네스 둘 다 반영되었는가?
+- [ ] `raw/` 구조가 source corpus 역할에 맞게 유지되는가?
+- [ ] `graphify-out/graph.html`, `GRAPH_REPORT.md`, `graph.json`이 존재하는가?
+- [ ] `README.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.harness/reference/local-adaptation.md`가 `raw/` 모델과 일치하는가?
+- [ ] PR 생성 규칙이 `.github/pull_request_template.md` 기준과 일치하는가?
+- [ ] `references/`가 Graphify source처럼 취급되고 있지 않은가?
 
 ## Key Conventions
 
-- **파일명**: kebab-case (`adr-001-dev-environment.md`, `food-com-dataset.md`)
-- **교차 참조**: 상대 경로 마크다운 링크 (`[name](../entities/name.md)`)
-- **프론트매터**: 모든 위키 페이지에 필수 (YAML `---` 블록)
-- **인덱스 동기화**: 페이지 생성/삭제 시 `INDEX.md` + 카테고리 `README.md` 동시 업데이트
-- **사실 기반**: 소스에 있는 내용만 작성, 추측 금지
-- **한국어**: 문서는 한국어로 작성
-- **하네스 동기화**: 구현 흐름이 바뀌면 `README.md` + `AGENTS.md` + `.github/copilot-instructions.md` + `.harness/reference/local-adaptation.md`를 함께 점검
-
-## Operation: Backup (백업)
-
-위키 전체를 스냅샷으로 백업한다.
-
-1. **현재 상태 확인** — `docs/wiki/INDEX.md`에서 전체 페이지 목록 파악
-2. **백업 생성** — `docs/wiki/` 디렉터리 전체를 타임스탬프 기반 아카이브로 복사
-   ```bash
-   tar czf docs/wiki-backup-YYYY-MM-DD.tar.gz docs/wiki/
-   ```
-3. **검증** — 아카이브 내 파일 수가 INDEX.md 등록 수 + README/INDEX 파일 수와 일치하는지 확인
-4. **보고** — 백업 파일 경로, 포함된 페이지 수, 파일 크기 보고
+- **Source corpus**: `raw/`
+- **Generated graph**: `graphify-out/`
+- **Graph refresh entrypoint**: `scripts/graphify_code_refresh.sh`
+- **Full refresh flow**: `scripts/graphify_prepare_corpus.sh` -> `scripts/graphify_full_refresh.py` -> `scripts/graphify_verify_full_refresh.py` -> `scripts/graphify_sync_staged.sh`

.agents/skills/docs-manager/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Docs Manager"
   short_description: "Sync wiki, README, and harness documentation"
-  default_prompt: "Use $docs-manager to ingest sources, query or lint the wiki, create ADR pages, or run the repository docs/harness sync routine across README.md, AGENTS.md, .github/copilot-instructions.md, .harness/reference/local-adaptation.md, and docs/wiki/."
+  default_prompt: "Use $docs-manager to maintain the `raw/` Graphify source corpus, create ADR pages under `raw/design/adr/`, maintain design notes under `raw/design/notes/`, and run the repository docs/harness sync routine across README.md, AGENTS.md, .github/copilot-instructions.md, and .harness/reference/local-adaptation.md."

.agents/skills/documentation-and-adrs/SKILL.md

@@ -11,9 +11,10 @@ Document decisions, not just code. The most valuable documentation captures the
 
 ## Repository Notes
 
-- Wiki-owned documentation in this repository lives under `docs/wiki/` and follows `AGENTS.md`.
-- ADRs for this project belong in `docs/wiki/decisions/`, not `docs/decisions/`.
-- If the change is primarily a wiki/source/index maintenance task, use `docs-manager` first and apply this skill only as supporting guidance.
+- Source documentation in this repository lives under `raw/` and follows `AGENTS.md`.
+- ADRs for this project belong in `raw/design/adr/`.
+- Design notes belong in `raw/design/notes/`.
+- If the change is primarily a Graphify source-corpus or harness sync task, use `docs-manager` first and apply this skill only as supporting guidance.
 
 ## When to Use
 
@@ -41,7 +42,7 @@ ADRs capture the reasoning behind significant technical decisions. They're the h
 
 ### ADR Template
 
-Store ADRs in `docs/wiki/decisions/` with sequential numbering and keep `docs/wiki/INDEX.md` plus `docs/wiki/decisions/README.md` in sync:
+Store ADRs in `raw/design/adr/` with sequential numbering:
 
 ```markdown
 # ADR-001: Use PostgreSQL for primary database

.agents/skills/graphify-full/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: graphify-full
+description: Alias wrapper for graphify-manager. Use when the user explicitly wants the full Graphify refresh workflow, not the code-only bootstrap refresh.
+---
+
+# Graphify Full
+
+This is an alias for `graphify-manager`.
+Use it when you explicitly want to run or inspect the full staged producer path against `raw/`.
+
+## Procedure
+
+1. Read `AGENTS.md`.
+2. Use the `graphify-manager` workflow exactly.
+3. Treat this skill as the repo-local `/graphify-full` entrypoint.
+
+## Related
+
+- `graphify-manager`

.agents/skills/graphify-manager/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: graphify-manager
+description: "Run the repository's full Graphify refresh workflow against the staged corpus, verify that design/docs context made it into the graph, and optionally sync verified results into root graphify-out/."
+argument-hint: "full refresh, verify only, or sync verified results"
+---
+
+# Graphify Manager
+
+Run the repository's **full Graphify refresh automation**.
+This is separate from `scripts/graphify_code_refresh.sh`, which is code-only bootstrap.
+Hooks may now auto-refresh the graph after relevant local edits.
+Use this workflow when you want to run or inspect the full staged producer path explicitly.
+
+## When to Use
+
+- You need a full graph that includes code **and** docs/design context
+- You want to reflect the current `raw/` source corpus into `graphify-out/`
+- You want to refresh `.graphify-work/corpus/graphify-out/` and promote it into root `graphify-out/`
+
+## Workflow
+
+### 1. Prepare staged corpus
+
+Always start by preparing the deterministic staged corpus:
+
+```bash
+bash scripts/graphify_prepare_corpus.sh
+```
+
+This creates `.graphify-work/corpus/` with:
+
+- `src/`
+- `tests/`
+- `raw/`
+
+### 2. Run Graphify full pipeline on staged corpus
+
+Run the repo-local full refresh producer on `.graphify-work/corpus/`.
+The high-level order is fixed:
+
+1. detect
+2. AST extraction
+3. semantic extraction
+4. graph build / cluster / analysis
+5. report / json / html export
+6. verify gate
+7. optional sync
+
+```bash
+uv run --with graphifyy==0.4.23 python scripts/graphify_full_refresh.py .graphify-work/corpus
+```
+
+If the producer fails, stop there and report the exact failure.
+Do not claim success or run root sync in that case.
+
+### 3. Required semantic targets
+
+The full refresh is only useful if semantic extraction includes document context.
+At minimum, make sure the staged corpus graph captures nodes/relationships sourced from:
+
+- `raw/design/adr/**`
+- `raw/design/notes/**`
+- `raw/design/specs/**` when present
+- `raw/external/**` as source-file presence
+
+### 4. Verify staged output
+
+After Graphify writes `.graphify-work/corpus/graphify-out/`, run:
+
+```bash
+python3 scripts/graphify_verify_full_refresh.py .graphify-work/corpus/graphify-out
+```
+
+This must succeed before root sync.
+If `.graphify-work/corpus/graphify-out/BUILD_INFO.json` does not exist yet,
+report that no staged full refresh output was produced and stop there.
+Verification now requires more than source file presence:
+
+- required `raw/design/adr/**` and `raw/design/notes/**` files must exist as graph nodes
+- required raw design files must participate in non-trivial semantic links
+- `raw/design/specs/**` participates when present
+- `raw/external/**` and binary-like design assets must appear as source-file presence
+- semantic links must carry relation + confidence metadata
+
+### 5. Sync verified result (optional)
+
+Only after verification passes:
+
+```bash
+bash scripts/graphify_sync_staged.sh
+```
+
+This copies the verified staged artifacts into root `graphify-out/`.
+
+## Rules
+
+- CI may prepare a candidate note, but it does not run the producer, verify, or sync.
+- Hooks may auto-refresh after relevant local edits, so check `graphify-out/BUILD_INFO.json` before assuming the current graph state.
+- Do not overwrite root `graphify-out/` before the verify gate passes.
+- `raw/` is the only source corpus for full refresh.
+- Keep Graphify version pinned through the repository scripts and metadata.
+- If full refresh fails verification, report which required documentation sources were missing from the graph.
+
+## Related
+
+- `scripts/graphify_code_refresh.sh`
+- `scripts/graphify_prepare_corpus.sh`
+- `scripts/graphify_full_refresh.py`
+- `scripts/graphify_verify_full_refresh.py`
+- `scripts/graphify_sync_staged.sh`

.agents/skills/using-agent-skills/SKILL.md

@@ -14,7 +14,7 @@ Agent Skills is a collection of engineering workflow skills organized by develop
 In this repository, the imported skill pack runs with these local rules:
 
 - `AGENTS.md` is the top-level rules file and schema document.
-- Work on `docs/sources/`, `docs/wiki/`, ADR pages, cross-references, or wiki index sync must use `docs-manager` first.
+- Work on `raw/`, ADR pages, design notes, or Graphify source-corpus sync must use `docs-manager` first.
 - Repository-specific command substitutions live in `.harness/reference/local-adaptation.md`.
 - Primary verification commands are `uv run pytest`, `uv run ruff check .`, `uv run mypy src`, and `uv run sid-reco doctor`.
 - Shared checklists live in `references/`.
@@ -27,7 +27,7 @@ When a task arrives, identify the development phase and apply the corresponding
 ```
 Task arrives
     │
-    ├── Wiki/source/ADR/index work? ──→ docs-manager
+    ├── Raw/source/ADR/note work? ────→ docs-manager
     ├── Vague idea/need refinement? ──→ idea-refine
     ├── New project/feature/change? ──→ spec-driven-development
     ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown