claudeos-core 2.4.0 → 2.4.1

package/README.ja.md

@@ -7,7 +7,11 @@
 [![license](https://img.shields.io/npm/l/claudeos-core.svg?color=blue)](LICENSE)
 [![downloads](https://img.shields.io/npm/dm/claudeos-core.svg?logo=npm&color=blue&label=downloads)](https://www.npmjs.com/package/claudeos-core)
 
-**実際のソースコードから Claude Code 用ドキュメントを自動生成します。** プロジェクトを静的に解析したうえで 4-pass の Claude パイプラインを実行し、`.claude/rules/`、standards、skills、guides を生成する CLI ツールです。その結果、Claude Code は一般的なコンベンションではなく **あなたのプロジェクト固有のコンベンション** に従います。
+**Claude Code が初回の試行から _あなたのプロジェクトの_ コンベンションに従うようにします — generic な既定値ではなく。**
+
+deterministic な Node.js scanner がコードを先に読み、4-pass の Claude パイプラインが抽出された事実を基に完全なドキュメントセットを書き込みます — `CLAUDE.md` + 自動ロードされる `.claude/rules/` + standards + skills + L4 memory。10 種の出力言語、5 つの post-generation validator、LLM がコードに存在しないファイルや framework をでっち上げないようにする明示的な path allowlist。
+
+[**12 stacks**](#supported-stacks) で即座に動作 (monorepo 含む) — `npx` コマンド一つ、設定不要、中断時 resume-safe、再実行 idempotent。
 
 ```bash
 npx claudeos-core init
@@ -19,25 +23,35 @@ npx claudeos-core init
 
 ## このツールは何ですか？
 
-あなたは Claude Code を使っています。賢いツールですが、**あなたのプロジェクトのコンベンション** までは知りません:
-- チームでは MyBatis を使っているのに、Claude は JPA のコードを生成する。
-- ラッパーは `ApiResponse.ok()` なのに、Claude は `ResponseEntity.success()` と書く。
-- パッケージは `controller/order/` なのに、Claude は `order/controller/` を作る。
+あなたは Claude Code を使っています。強力なツールですが、毎セッションが新しく始まります — _あなたの_ プロジェクトがどう構成されているかの記憶がありません。そのため、チームが実際に行っているパターンとほとんどマッチしない「generally good」な既定値に fallback します:
+
+- チームでは **MyBatis** を使っているのに、Claude は JPA repository を生成する。
+- 応答 wrapper は `ApiResponse.ok()` なのに、Claude は `ResponseEntity.success()` と書く。
+- パッケージは layer-first (`controller/order/`) なのに、Claude は domain-first (`order/controller/`) を作る。
+- エラーは centralized middleware を通すのに、Claude はあらゆる endpoint に `try/catch` を撒き散らす。
+
+プロジェクトごとに `.claude/rules/` セットがあれば良いのですが — Claude Code が毎セッション自動ロードしてくれる — 新しい repo ごとに手で書くのは何時間もかかり、コードが進化するにつれ drift していきます。
+
+**ClaudeOS-Core は実際のソースコードからそれをあなたの代わりに書きます。** deterministic な Node.js scanner がプロジェクトを先に読み (スタック、ORM、パッケージ layout、コンベンション、ファイルパス)、4-pass の Claude パイプラインが抽出された事実を完全なドキュメントセットに変換します:
 
-そのため、生成されたファイルを修正することにかなりの時間を費やすことになります。
+- **`CLAUDE.md`** — Claude が毎セッション最初に読むプロジェクトインデックス
+- **`.claude/rules/`** — カテゴリごとに自動ロードされる rules (`00.core` / `10.backend` / `20.frontend` / `30.security-db` / `40.infra` / `60.memory` / `70.domains` / `80.verification`)
+- **`claudeos-core/standard/`** — 参照ドキュメント (各 rule の「なぜ」)
+- **`claudeos-core/skills/`** — 再利用可能なパターン (CRUD scaffolding、ページテンプレート)
+- **`claudeos-core/memory/`** — プロジェクトと共に成長する decision log + failure pattern
 
-**ClaudeOS-Core はこの問題を解決します。** 実際のソースコードをスキャンしてコンベンションを把握し、Claude Code が自動で読み込むディレクトリ `.claude/rules/` に完全なルールセットを書き込みます。次に *「order の CRUD を作って」* と頼めば、Claude は最初の試行であなたのコンベンションに従います。
+scanner が Claude に明示的な path allowlist を渡すため、LLM は **コードに存在しないファイルや framework をでっち上げることができません**。5 つの post-generation validator (`claude-md-validator`, `content-validator`, `pass-json-validator`, `plan-validator`, `sync-checker`) が出力を ship 前に検証します — language-invariant なので、英語で生成しても、日本語で生成しても、他の 8 言語のいずれで生成しても同じルールが適用されます。
 
 ```
-Before:  あなた → Claude Code → 「概ね良い」コード → 手作業で修正
-After:   あなた → Claude Code → プロジェクトに一致するコード → そのまま使える
+Before:  あなた → Claude Code → 「概ね良い」コード → 毎回手作業で修正
+After:   あなた → Claude Code → あなたのプロジェクトに一致するコード → そのまま使える
 ```
 
 ---
 
 ## 実際のプロジェクトでのデモ
 
-[`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app) で実行 — Java 11 · Spring Boot 2.6 · MyBatis · SQLite · 187 source files. 結果: **75 generated files**、合計時間 **53 分**、すべての validator ✅。
+[`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app) で実行 — Java 11 · Spring Boot 2.6 · MyBatis · SQLite · 187 source files。結果: **75 generated files**、合計時間 **53 分**、すべての validator ✅。
 
 <p align="center">
   <img src="docs/assets/spring-boot-realworld-demo.gif" alt="ClaudeOS-Core init running on spring-boot-realworld-example-app — stack detection, 4-pass pipeline, validators, completion summary" width="769">
@@ -119,37 +133,45 @@ After:   あなた → Claude Code → プロジェクトに一致するコー
 </details>
 
 <details>
-<summary><strong>📄 生成された <code>CLAUDE.md</code> の抜粋 (実際の出力)</strong></summary>
+<summary><strong>📄 生成された <code>CLAUDE.md</code> の抜粋 (実際の出力 — Section 1 + 2)</strong></summary>
 
 ```markdown
-## 4. Core Architecture
-
-### Core Patterns
-
-- **Hexagonal ports & adapters**: domain ports live in `io.spring.core.{aggregate}`
-  and are implemented by `io.spring.infrastructure.repository.MyBatis{Aggregate}Repository`.
-  The domain layer has zero MyBatis imports.
-- **CQRS-lite read/write split (same DB)**: write side goes through repository ports
-  + entities; read side is a separate `readservice` package whose `@Mapper`
-  interfaces return `*Data` DTOs directly (no entity hydration).
-- **No aggregator/orchestrator layer**: multi-source orchestration happens inside
-  application services (e.g., `ArticleQueryService`); there is no `*Aggregator`
-  class in the codebase.
-- **Application-supplied UUIDs**: entity constructors assign their own UUID; PK is
-  passed via `#{user.id}` on INSERT. The global
-  `mybatis.configuration.use-generated-keys=true` flag is dead config
-  (auto-increment is unused).
-- **JWT HS512 authentication**: `io.spring.infrastructure.service.DefaultJwtService`
-  is the sole token subject in/out; `io.spring.api.security.JwtTokenFilter`
-  extracts the token at the servlet layer.
+# CLAUDE.md — spring-boot-realworld-example-app
+
+> Reference implementation of the RealWorld backend specification on
+> Java 11 + Spring Boot 2.6, exposing both REST and GraphQL endpoints
+> over a hexagonal MyBatis persistence layer.
+
+## 1. Role Definition
+
+As the senior developer for this repository, you are responsible for
+writing, modifying, and reviewing code. Responses must be written in English.
+A Java Spring Boot REST + GraphQL API server organized around a hexagonal
+(ports & adapters) architecture, with a CQRS-lite read/write split inside
+an XML-driven MyBatis persistence layer and JWT-based authentication.
+
+## 2. Project Overview
+
+| Item | Value |
+|---|---|
+| Language | Java 11 |
+| Framework | Spring Boot 2.6.3 |
+| Build Tool | Gradle (Groovy DSL) |
+| Persistence | MyBatis 3 via `mybatis-spring-boot-starter:2.2.2` (no JPA) |
+| Database | SQLite (`org.xerial:sqlite-jdbc:3.36.0.3`) — `dev.db` (default), `:memory:` (test) |
+| Migration | Flyway — single baseline `V1__create_tables.sql` |
+| API Style | REST (`io.spring.api.*`) + GraphQL via Netflix DGS `:4.9.21` |
+| Authentication | JWT HS512 (`jjwt-api:0.11.2`) + Spring Security `PasswordEncoder` |
+| Server Port | 8080 (default) |
+| Test Stack | JUnit Jupiter 5, Mockito, AssertJ, rest-assured, spring-mock-mvc |
 ```
 
-注: 上記の主張はすべて実際のソースに基づいています — クラス名、パッケージパス、設定キー、dead-config フラグまで、すべて Claude がファイルを書く前に scanner が抽出したものです。
+上の値はすべて — 正確な依存関係の coordinates、`dev.db` のファイル名、`V1__create_tables.sql` のマイグレーション名、「no JPA」まで — Claude がファイルを書く前に scanner が `build.gradle` / `application.properties` / ソースツリーから抽出したものです。何一つ推測されていません。
 
 </details>
 
 <details>
-<summary><strong>🛡️ 自動ロードされる実際のルール (<code>.claude/rules/10.backend/03.data-access-rules.md</code>)</strong></summary>
+<summary><strong>🛡️ 自動ロードされる実際の rule ファイル (<code>.claude/rules/10.backend/01.controller-rules.md</code>)</strong></summary>
 
 ````markdown
 ---
@@ -157,42 +179,56 @@ paths:
   - "**/*"
 ---
 
-# Data Access Rules
+# Controller Rules
+
+## REST (`io.spring.api.*`)
 
-## XML-only SQL
-- Every SQL statement lives in `src/main/resources/mapper/*.xml`.
-  NO `@Select` / `@Insert` / `@Update` / `@Delete` annotations on `@Mapper` methods.
-- Each `@Mapper` interface has exactly one XML file at
-  `src/main/resources/mapper/{InterfaceName}.xml`.
-- `<mapper namespace="...">` MUST be the fully qualified Java interface name.
-  The single existing exception is `TransferData.xml` (free-form `transfer.data`).
+- Controllers are the SOLE response wrapper for HTTP — no aggregator/facade above them.
+  Return `ResponseEntity<?>` or a body Spring serializes via `JacksonCustomizations`.
+- Each controller method calls exactly ONE application service method. Multi-source
+  composition lives in the application service.
+- Controllers MUST NOT import `io.spring.infrastructure.*`. No direct `@Mapper` access.
+- Validate command-param arguments with `@Valid`. Custom JSR-303 constraints live under
+  `io.spring.application.{aggregate}.*`.
+- Resolve the current user via `@AuthenticationPrincipal User`.
+- Let exceptions propagate to `io.spring.api.exception.CustomizeExceptionHandler`
+  (`@ControllerAdvice`). Do NOT `try/catch` business exceptions inside the controller.
 
-## Dynamic SQL
-- `<if>` predicates MUST guard both null and empty:
-  `<if test="X != null and X != ''">`. Empty-only is the existing HIGH-severity bug pattern.
-- Prefer `LIMIT n OFFSET m` over MySQL-style `LIMIT m, n`.
+## GraphQL (`io.spring.graphql.*`)
+
+- DGS components (`@DgsComponent`) are the sole GraphQL response wrappers.
+  Use `@DgsQuery` / `@DgsData` / `@DgsMutation`.
+- Resolve the current user via `io.spring.graphql.SecurityUtil.getCurrentUser()`.
 
 ## Examples
 
 ✅ Correct:
-```xml
-<update id="update">
-  UPDATE articles
-  <set>
-    <if test="article.title != null and article.title != ''">title = #{article.title},</if>
-    updated_at = #{article.updatedAt}
-  </set>
-  WHERE id = #{article.id}
-</update>
+```java
+@PostMapping
+public ResponseEntity<?> createArticle(@AuthenticationPrincipal User user,
+                                       @Valid @RequestBody NewArticleParam param) {
+    Article article = articleCommandService.createArticle(param, user);
+    ArticleData data = articleQueryService.findById(article.getId(), user)
+        .orElseThrow(ResourceNotFoundException::new);
+    return ResponseEntity.ok(Map.of("article", data));
+}
 ```
 
 ❌ Incorrect:
-```xml
-<mapper namespace="article.mapper">          <!-- NO — namespace MUST be FQCN -->
+```java
+@PostMapping
+public ResponseEntity<?> create(@RequestBody NewArticleParam p) {
+    try {
+        articleCommandService.createArticle(p, currentUser);
+    } catch (Exception e) {                                      // NO — let CustomizeExceptionHandler handle it
+        return ResponseEntity.status(500).body(e.getMessage());  // NO — leaks raw message
+    }
+    return ResponseEntity.ok().build();
+}
 ```
 ````
 
-`paths: ["**/*"]` の glob は、プロジェクト内のいずれかのファイルを編集すると Claude Code がこのルールを自動ロードすることを意味します。✅/❌ の例は、このコードベースの実際のコンベンションと既存のバグパターンから直接抽出されています。
+`paths: ["**/*"]` の glob は、プロジェクト内のいずれかのファイルを編集するたびに Claude Code がこの rule を自動ロードすることを意味します。rule 内のクラス名、パッケージパス、exception handler はすべて scan されたソースから直接抽出されています — プロジェクトの実際の `CustomizeExceptionHandler` と `JacksonCustomizations` を含めて。
 
 </details>
 
@@ -200,25 +236,26 @@ paths:
 <summary><strong>🧠 自動生成された <code>decision-log.md</code> シード (実際の出力)</strong></summary>
 
 ```markdown
-## 2026-04-26 — CQRS-lite read/write split inside the persistence layer
-
-- **Context:** Writes go through `core.*Repository` port → `MyBatis*Repository`
-  adapter → `io.spring.infrastructure.mybatis.mapper.{Aggregate}Mapper`.
-  Reads bypass the domain port: application service →
-  `io.spring.infrastructure.mybatis.readservice.{Concept}ReadService` directly,
-  returning flat `*Data` DTOs from `io.spring.application.data.*`.
-- **Options considered:** Single repository surface returning hydrated entities
-  for both reads and writes.
-- **Decision:** Same database, two `@Mapper` packages — `mapper/` (write side,
-  operates on core entities) and `readservice/` (read side, returns `*Data` DTOs).
-  Read DTOs avoid entity hydration overhead.
-- **Consequences:** Reads are NOT routed through the domain port — this is
-  intentional, not a bug. Application services may inject both a `*Repository`
-  (writes) and one or more `*ReadService` interfaces (reads) at the same time.
-  Do NOT add hydrate-then-map glue in the read path.
+## 2026-04-26 — Hexagonal ports & adapters with MyBatis-only persistence
+
+- **Context:** `io.spring.core.*` exposes `*Repository` ports (e.g.,
+  `io.spring.core.article.ArticleRepository`) implemented by
+  `io.spring.infrastructure.repository.MyBatis*Repository` adapters.
+  The domain layer has zero `org.springframework.*` /
+  `org.apache.ibatis.*` / `io.spring.infrastructure.*` imports.
+- **Options considered:** JPA/Hibernate, Spring Data, MyBatis-Plus
+  `BaseMapper`. None adopted.
+- **Decision:** MyBatis 3 (`mybatis-spring-boot-starter:2.2.2`) with
+  hand-written XML statements under `src/main/resources/mapper/*.xml`.
+  Hexagonal port/adapter wiring keeps the domain framework-free.
+- **Consequences:** Every SQL lives in XML — `@Select`/`@Insert`/`@Update`/`@Delete`
+  annotations are forbidden. New aggregates require both a
+  `core.{aggregate}.{Aggregate}Repository` port AND a
+  `MyBatis{Aggregate}Repository` adapter; introducing a JPA repository would
+  split the persistence model.
 ```
 
-Pass 4 は `pass2-merged.json` から抽出したアーキテクチャ上の決定事項で `decision-log.md` を seed します — そのため、その後のセッションでもコードベースが _このように見える_ という事実だけでなく、_なぜ_ そう見えるのかも記憶できます。
+Pass 4 は `pass2-merged.json` から抽出したアーキテクチャ上の決定事項で `decision-log.md` を seed します — その後のセッションでもコードベースが _このように見える_ という事実だけでなく、_なぜ_ そう見えるのかも記憶できるように。すべての選択肢 (「JPA/Hibernate」「MyBatis-Plus」) と帰結は実際の `build.gradle` の dependency ブロックに基づいています。
 
 </details>
 
@@ -246,7 +283,7 @@ your-project/
 │   └── rules/                    ← Claude Code が自動ロード
 │       ├── 00.core/              (共通ルール — 命名、アーキテクチャ)
 │       ├── 10.backend/           (バックエンドスタックのルール、該当する場合)
-│       ├── 20.frontend/          (フロントエンドスタックのルール、該当する場合)
+│       ├── 20.frontend/           (フロントエンドスタックのルール、該当する場合)
 │       ├── 30.security-db/       (セキュリティ & DB のコンベンション)
 │       ├── 40.infra/             (env、ロギング、CI/CD)
 │       ├── 50.sync/              (ドキュメント同期のリマインダ — rules only)
@@ -277,13 +314,17 @@ your-project/
 
 ## 誰のためのツールですか？
 
-| あなたが... | このツールが助けるのは... |
+| あなたが... | このツールが取り除く pain |
 |---|---|
-| **Claude Code で新規プロジェクトを始めるソロ開発者** | 「Claude にコンベンションを教える」フェーズを丸ごとスキップ |
-| **共有標準を維持するチームリード** | `.claude/rules/` を最新に保つ手間を自動化 |
-| **既に Claude Code を使っているが生成コードの修正に疲れた人** | Claude が「概ね良い」パターンではなく、_あなたの_ パターンに従うようにする |
+| **Claude Code で新規プロジェクトを始めるソロ開発者** | 「毎セッション Claude にコンベンションを教える」が消える。`CLAUDE.md` + 8 カテゴリの `.claude/rules/` が一回の pass で生成される。 |
+| **複数 repo にまたがる共有標準を維持するチームリード** | パッケージ名変更、ORM 切り替え、response wrapper 変更で `.claude/rules/` が drift。ClaudeOS-Core は deterministic に再同期 — 同じ入力 → byte-identical な出力、diff noise なし。 |
+| **既に Claude Code を使っているが生成コードの修正に疲れた人** | 間違った response wrapper、間違ったパッケージ layout、MyBatis を使っているのに JPA、centralized middleware なのに `try/catch` 撒き散らし。scanner が本物のコンベンションを抽出し、すべての Claude pass が明示的な path allowlist に対して走ります。 |
+| **新しい repo への onboarding** (既存プロジェクト、チームに参加) | repo で `init` を実行するだけで、生きた architecture map が手に入る: CLAUDE.md のスタック表、レイヤごとのルール (✅/❌ 例つき)、主要な選択 ("なぜ") を seed した decision log (JPA vs MyBatis、REST vs GraphQL など)。5 ファイルを読む方が 5,000 ソースファイルを読むより速い。 |
+| **日本語 / 韓国語 / 中国語 / 他 7 言語で作業** | 大半の Claude Code rule generator は英語のみ。ClaudeOS-Core は **10 言語** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) で完全なセットを書き、**byte-identical な構造検証** — 出力言語に関係なく同じ `claude-md-validator` の verdict。 |
+| **monorepo で作業** (Turborepo、pnpm/yarn workspaces、Lerna) | 1 回の実行で backend + frontend のドメインが個別 prompt で解析される。`apps/*/` と `packages/*/` は自動的に walk され、スタック別のルールが `70.domains/{type}/` 配下に emit される。 |
+| **OSS 貢献または実験** | 出力は gitignore-friendly — `claudeos-core/` はローカル作業ディレクトリ、ship が必要なのは `CLAUDE.md` + `.claude/` のみ。中断時 resume-safe、再実行 idempotent (`--force` なしなら手動編集は保持される)。 |
 
-**適していないケース:** スキャン手順なしで初日から動く agents/skills/rules の one-size-fits-all なプリセットバンドルが欲しい場合 (どのツールがどこに合うかは [docs/comparison.md](docs/ja/comparison.md) を参照)、もしくはプロジェクトが [サポート対象スタック](#supported-stacks) に該当しない場合。
+**適していないケース:** scan 段階を経ずに day-one から動く agents/skills/rules の one-size-fits-all なプリセットバンドルが欲しい場合 (どのツールがどこに適しているかは [docs/comparison.md](docs/ja/comparison.md) を参照)、もしくはプロジェクトが [サポート対象スタック](#supported-stacks) のいずれにもまだ該当しない場合、または単一の `CLAUDE.md` だけ欲しい場合 (ビルトインの `claude /init` で十分 — 別ツールを入れる必要はありません)。
 
 ---
 
@@ -296,9 +337,28 @@ ClaudeOS-Core は通常の Claude Code ワークフローを反転させます:
 このツール: コードがスタックを読む → コードが確定した事実を Claude に渡す → Claude が事実から docs を作成
 ```
 
-ポイント: **Node.js scanner が先にソースコードを読み** (deterministic、AI なし)、その後 4-pass の Claude パイプラインが scanner で見つけた事実に制約された形でドキュメントを書きます。Claude はコードに実在しないパスやフレームワークをでっち上げることができません。
+パイプラインは **3 段階** で実行され、LLM 呼び出しの両側にコードがあります:
+
+**1. Step A — Scanner (deterministic、LLM なし)。** Node.js scanner がプロジェクトルートを walk し、`package.json` / `build.gradle` / `pom.xml` / `pyproject.toml` を読み、`.env*` ファイルをパースし (`PASSWORD/SECRET/TOKEN/JWT_SECRET/...` のような sensitive な変数は redaction)、architecture pattern を分類し (Java の 5 パターン A/B/C/D/E、Kotlin CQRS / multi-module、Next.js App vs Pages Router、FSD、components-pattern)、ドメインを発見し、存在するすべてのソースファイルパスの明示的 allowlist を構築します。出力: `project-analysis.json` — 以降のすべての段階の単一の source of truth です。
+
+**2. Step B — 4-Pass Claude パイプライン (Step A の事実によって制約される)。**
+- **Pass 1** はドメイングループごとに代表ファイルを読み、ドメインあたり ~50–100 のコンベンションを抽出します — response wrapper、logging library、error handling、naming convention、test pattern。ドメイングループごとに 1 回実行される (`max 4 domains, 40 files per group`) ため context が overflow しません。
+- **Pass 2** はドメインごとの解析をすべてプロジェクト全体の像にマージし、ドメイン間で意見が割れたときは支配的なコンベンションを選びます。
+- **Pass 3** は `CLAUDE.md` + `.claude/rules/` + `claudeos-core/standard/` + skills + guides を書きます — stage に分割 (`3a` facts → `3b-core/3b-N` rules+standards → `3c-core/3c-N` skills+guides → `3d-aux` database+mcp-guide) されるため、`pass2-merged.json` が大きい場合でも各 stage の prompt が LLM の context window に収まります。≥16 ドメインのプロジェクトでは 3b/3c を ≤15 ドメインの batch に sub-divide します。
+- **Pass 4** は L4 memory layer (`decision-log.md`、`failure-patterns.md`、`compaction.md`、`auto-rule-update.md`) を seed し、universal な scaffold rules を追加します。Pass 4 は **`CLAUDE.md` の修正を禁止** されています — Pass 3 の Section 8 が authoritative です。
+
+**3. Step C — Verification (deterministic、LLM なし)。** 5 つの validator が出力を検査します:
+- `claude-md-validator` — `CLAUDE.md` に対する 25 個の構造チェック (8 sections、H3/H4 count、memory file uniqueness、T1 canonical heading invariant)。Language-invariant: `--lang` に関係なく同じ verdict。
+- `content-validator` — 10 個の content チェック。path-claim 検証 (`STALE_PATH` が捏造された `src/...` 参照を検出) と MANIFEST drift 検出を含む。
+- `pass-json-validator` — Pass 1/2/3/4 JSON well-formedness + stack-aware section count。
+- `plan-validator` — plan ↔ disk の整合性 (legacy、v2.1.0 以降ほぼ no-op)。
+- `sync-checker` — 7 個の追跡対象ディレクトリにわたる disk ↔ `sync-map.json` 登録の整合性。
+
+3-tier severity (`fail` / `warn` / `advisory`) なので、ユーザが手動で直せる LLM hallucination について warning が CI を deadlock させることはありません。
+
+すべてを結びつける invariant: **Claude はコードに実在するパスしか引用できない** — Step A が finite な allowlist を渡しているからです。それでも LLM が何かをでっち上げようとしたら (まれですが特定の seed で起きます)、Step C が docs を ship する前に捕まえます。
 
-アーキテクチャ全体は [docs/ja/architecture.md](docs/ja/architecture.md) を参照。
+per-pass の詳細、marker ベースの resume、Claude Code の `.claude/` sensitive-path block を回避する staged-rules の仕組み、stack 検出の internals は [docs/architecture.md](docs/ja/architecture.md) を参照。
 
 ---