CLAUDE.md git:20260925.f43f46eA

Immutable. This exact content never changes and is served at /api/v1/blob/03a66ee8aaf53b13.

# agent-knowledge-cycle

AI エージェントが自分の経験を改善可能な skill に metabolize する **cycle (mechanism)** を 6 phase に operationalize した DOI-targeted research project。harness の上で動く知識 cycle であり、harness そのものではない。

> Project name: **Agent Knowledge Cycle (AKC)**。Concept DOI [`10.5281/zenodo.19200726`](https://doi.org/10.5281/zenodo.19200726) を canonical citation target とする。

## Three core themes (ADR-0012)

front-door documentation で必ず先に登場させる 3 つの load-bearing なテーマ。順序は固定:

1. **Human cognitive resource scarcity** (ADR-0010) — model でなく **human attention / judgment** が scale しない中心制約。他の framework は agent 側を最適化するが、AKC は逆問題を扱う
2. **Intent alignment, not correctness** — output ごとの正しさ (tests で検査可能) と、operator の進化する intent との alignment (検査不能) は別物。AKC は後者を sustain する
3. **The cycle changes the human too** — bidirectional growth loop。human が curate / promote するうちに、good agent behavior に対する judgment 自体が研がれる。一方向の最適化ループではない

## Reading order for AI agents

1. [`graph.jsonld`](graph.jsonld) — canonical concept-level map (machine-readable)
2. [`llms.txt`](llms.txt) — navigation index
3. [`llms-full.txt`](llms-full.txt) — consolidated Q&A + factual reference
4. [`README.md`](README.md) (or [`README.ja.md`](README.ja.md)) — three themes、全体像
5. [`docs/adr/`](docs/adr/) — judgment lineage (count の正本は llms-full.txt; gaps at 0001/0006/0007 are intentional)

## Sibling projects (context を失わない)

この repo は単独の artifact ではなく、2 つの sibling および下流 ecosystem との関係で意味を持つ。

### `contemplative-agent` — implementation substrate / running re-implementation

- https://github.com/shimo4228/contemplative-agent (concept DOI `10.5281/zenodo.19212118`)
- **上流方向**: AKC の ADR-0002 〜 ADR-0005 (immutable episode log、three-layer distillation、two-stage distill、human approval gate) はここから adapt された engineering substrate
- v2.0.0 で extract された security triplet (ADR-0001 / 0006 / 0007) の原典でもある
- **下流方向**: AKC 6 phase の autonomous-agent 文脈での operational な再実装。pipeline が 6 phase を code に写像し (distill=Extract / insight・rules-distill・amend-constitution=Curate / distill-identity=Promote / pivot snapshots=Measure)、fine-tuning なしで自己ログ上のサイクルを稼働中。every promotion が human approval gate を通る。実証は現在進行形

### `agent-attribution-practice` (AAP) — sibling genre library

- https://github.com/shimo4228/agent-attribution-practice (concept DOI `10.5281/zenodo.19652013`)
- v2.0.0 (2026-04-19) で AKC から extract された security triplet を harness-neutral に再表現 + 7 ADR 追加した sibling
- AKC = cycle (mechanism = knowledge をどう流すか)、AAP = practice (content = attribution をどう分配するか)。役割は相補的で独立

役割分担: **AKC = cycle (mechanism) / AAP = practice (content) / contemplative-agent = implementation substrate + running re-implementation**。3 つは別の問いに答える。混同せず議論ごとに primary 出口を選ぶ。

### Downstream ecosystem (cycle の結晶化物)

サイクルを回した日常運用から結晶化した下流 repo 群は README の "Related Work" 節末尾の compact list と graph.jsonld に記録されている — authorship-strategy / attention-not-self / doctrine-corpus / existence-proof (research lines・DOI 持ち) は README + graph + llms.txt、claude-harness / akc-mcp / daily-research / hub repo (配布・周辺層) は graph + llms-full.txt のみ。AKC 側に書くのは関係の事実 + DOI + インスタンスへの接地リンクのみ (ADR-0027 — 各 repo の本文は持ち込まない)。

## HF Datasets mirror

`graph.jsonld` は Hugging Face Datasets の mirror として publish されている (LLM training pipeline / knowledge-graph crawler の primary ingest source、Auto-converted to Parquet で `pandas` / `Polars` から直接 load 可能)。graph 更新時の同期手順は `~/.claude/skills/jsonld-knowledge-graph/SKILL.md` の "Mirror Sync to Hugging Face Datasets" section 参照。

Repo mapping:

| GitHub | HF dataset |
|---|---|
| `shimo4228/agent-knowledge-cycle` ← **this repo** | [`Shimo4228/agent-knowledge-cycle`](https://huggingface.co/datasets/Shimo4228/agent-knowledge-cycle) |
| `shimo4228/agent-attribution-practice` | [`Shimo4228/agent-attribution-practice`](https://huggingface.co/datasets/Shimo4228/agent-attribution-practice) |
| `shimo4228/contemplative-agent` (local clone: `contemplative-agent/`) | [`Shimo4228/contemplative-agent`](https://huggingface.co/datasets/Shimo4228/contemplative-agent) |
| `shimo4228/shimo4228` (hub repo) | [`Shimo4228/research-program-hub`](https://huggingface.co/datasets/Shimo4228/research-program-hub) |

HF 側の `README.md` (dataset card) は HF 用に customize されている (sibling dataset への link、mirror notice 等)。Graph 更新では同期しない。Dataset card を edit したい場合は手動で `hf upload Shimo4228/agent-knowledge-cycle README.md --repo-type dataset`。

## Using this repo as an agent navigator

この repo は Claude Code / Codex 等の agent に clone させ、CLAUDE.md を起点に「自分の harness に cycle を install して judgment を自走させる」use case を想定する。文献として読まれるのではなく、navigator として walk されることを意図する。

### 想定 use case

- 「自分の harness に AKC の cycle を install したい」
- 「skill / rule の棚卸し方法を ADR で確認したい」
- 「6 phase のどれが今欠けているか診断したい」

### Walk order

1. [`README.md`](README.md) → three themes と全体像
2. [`graph.jsonld`](graph.jsonld) → entity と relationship (6 phases、3 memory layers、4 patterns、bijective phase-to-skill bindings)
3. [`docs/akc-cycle.md`](docs/akc-cycle.md) → cycle 全体を **single rules file として install** できる単独リポ [`shimo4228/akc-cycle`](https://github.com/shimo4228/akc-cycle) への pointer (6 skill repos を導入しなくてよい。standalone repo 化済み 2026-06)
4. [`docs/skills/README.md`](docs/skills/README.md) → ADR と 1:1 で対応する design-pattern skill (when-code-when-llm / code-and-llm-collaboration / signal-first-research) への pointer 表。skill 本体は standalone repo 化済み (2026-06)
5. [`examples/minimal_harness/`](examples/minimal_harness/) → ~500 行の dependency-free Python reference。cycle が behavioral patterns に対して走る具体例

### Caveats

- **AKC は autonomous でない** — ADR-0005 Human Approval Gate。挙動を形成する artifact (skills / rules / identity) への変更はすべて名前付き human sign-off を要求する。Gate は structural
- **AKC は harness でない** — ADR-0009。harness の上で動く cycle であり、cycle は harness 間 portable、harness は cycle ではない
- **AKC は genre-neutral** — ADR-0011。behavioral patterns / domain expertise / constitutional values いずれにも適用可能。content には position を取らない
- **Skills は scaffold** — `docs/scaffold-dissolution.md` 参照。cycle を内在化したら external skill repo 群は drop してよい。Dissolution は intended end state、fallback ではない
- **「実装は溶ける、judgment は残る」** — model 進化で具体実装は時代依存、ADR の judgment 構造のみが時間軸で残る

## Core thesis

> 「judgment は残る、scaffold は溶ける」
> 「human attention is the scarce resource — not the model's compute, not the context window」

詳細は ADR-0009 / ADR-0010 / ADR-0012、および [`docs/scaffold-dissolution.md`](docs/scaffold-dissolution.md) (日本語版 [`scaffold-dissolution.ja.md`](docs/scaffold-dissolution.ja.md))。

## 書き方の規約

### 英語 primary / 日本語 subordinate

- README は **英語正本** + 日本語 (en / ja active)。多言語 mirror (es / pt-BR / zh-CN / zh-TW) は v2.1.0 後の commit `b858370` で retire
- ADR は英語正本
- llms.txt / llms-full.txt / graph.jsonld は英語のみ

### ADR format

`docs/adr/` 直下に番号付き markdown。必須 section: **Status / Date / Context / Decision / Alternatives Considered / Consequences / Relationship to other ADRs** (lineage を記録する section。header 名はこの表記で統一)。実験的判断は Status 欄に `**experimental**` と太字で付記。ADR-0024 以降は `## Review-when` (失効条件) を Decision の直後に置く — ADR は日付つき仮説であり、0023 以前は backfill しない (ADR-0026)。

### 「メンタルモデル」と「インスタンス」の区別 (ADR-0027。旧「mechanism/content」を supersede)

AKC core が**所有**するのは **メンタルモデル** (判断 = ADR / 概念 = graph.jsonld / cycle 構造) のみ。**インスタンス** (動いている skills / rules / hooks / gates / loops) の所有は downstream repo。ただしインスタンスは排除しない — **第一級のリンクで接地する**: 各 mechanism Concept は公開インスタンスが存在する限り graph の `implements` 辺と front-door のリンクを持つ (grounding expectation)。無ければ無いと書く。リンクは running state に従う — インスタンスが運用から退役したら日付つきでリンクを外す/注記する (先例: human-gate、2026-08-02 退役 → 2026-09-01 リンク除去)。

禁止が残るのは 2 つだけ: (1) インスタンス本文を core へ**複製**する (inlining)、(2) **domain genre** (どの behavioral pattern / value set / threat model が cycle を流れるか) に position を取る — これは ADR-0011 の genre-neutrality で不変。「content」という旧語彙はこの 2 つを混同していた。具体的 instance の in-repo 最小版は引き続き `examples/` に置く。

**Structural guard vs populated content の境界** (不変): empty-default で ship される parameterized check (structural guard / validation seam) は mechanism として core に属し、seam に投入される populated threat model (具体的 deny list 等) は downstream が持つ。v2.0.0 の security triplet extract の根拠。

### ADR 番号と gap

ADR 番号は permanent identifier。gap (0001 / 0006 / 0007) は v2.0.0 で AAP に extract された ADR を示す。番号は再利用しない。

## ディレクトリ

file-level の索引は持たない。構造は `git ls-files` と各 doc 自身（ADR の題名・llms.txt の一覧）から都度引く — 手保守の `docs/CODEMAPS/` は 2026-09-26 に削除した（harness ADR-0062 と同じ判断。経緯は [`docs/scaffold-dissolution.md`](docs/scaffold-dissolution.md) の 2026-09-05 項）。

concept-level の正本は [`graph.jsonld`](graph.jsonld)（「X とは何か、X と Y はどう関係するか」を JSON-LD triples で encode。AI search engine + LLM が entity を citation する時に読む）。新規 ADR / Concept / EcosystemRepo 追加時は graph.jsonld と llms.txt / llms-full.txt を更新する。

### 編集時の不変条件

- **Tagline**: *"A knowledge cycle for AI agents — agent behavior compounds, human judgment sharpens"* を README の en / ja 両方で保つ (ADR-0021)
- **README の en / ja 対応**: 両版の H2 / H3 構造を揃える。訳語の正本は [`docs/translation-glossary.md`](docs/translation-glossary.md)
- **4 パターンの正本は ADR-0008**: guard / filter / judge / orchestrator の定義が graph.jsonld・llms-full.txt と食い違ったら ADR-0008 が正で、他が drift