git:20260906.4a80b62 to git:20260911.74f1350

1 added, 1 removed. Audit A to A.

# LLM Wiki Newsroom

This wiki is an English-native knowledge base maintained by Claude Code; the example corpus shipped here maps the debate over what "open source" means for AI, but the framework is domain-agnostic. It requires no external API keys — the Python scripts under `tools/` run entirely locally. When the user makes a request in natural language or runs a slash command, these instructions route the work to the appropriate one of the five roles.

---

## Roles

This project operates as a five-role multi-agent system modeled on the staff of a Korean newsroom.

| Role | Essence |

|---|---|

| **Editor-in-Chief** | Meta layer outside the matrix — entry, routing, gating, escalation, logging |

| **Reporter** | Writes L2-1 / L2-2 stubs + broad external exploration (breadth-first parallel) |

| **Columnist** | Writes L2-2 full / L2-3 / L2-4 (integrating its own GROUND, deep sequential) |

| **Desk**[^desk] | Qualitative review of L2-2 full hub·stub / L2-3 / L2-4, plus L2-1 on its sub-trigger (the areas the Rubric does not capture — scope per `desk.md`) — the pre-publish gate |

| **Copy Editor** | Deterministic quantitative checks across all Layers (`tools/lint.py`) |

[^desk]: "Desk" is the newsroom desk — the senior editor who reviews a piece for quality and judgment before it runs (as in "copy desk" / "news desk"). Here it is the pre-publish qualitative-review gate. The five roles are modeled on a newspaper newsroom; the agent and its SoT file are both named `desk`.

Per-role capabilities, prompts, and risk mitigations: [`.claude/agents/`](.claude/agents/) is the SoT.

---

## Universal Cycle

Every workflow in this project maps onto a four-stage cycle — ingest, query, lint, and reground all share the same skeleton.

| Stage | Essence | Owner |

|---|---|---|

| **GROUND** | Read the relevant SoT (observe) | Reporter / Columnist read directly from their own context (avoiding the telephone game) |

| **APPLY** | Write/edit following the observed pattern | Reporter / Columnist write the EDITOR block (preserving the AUTO block) |

| **VERIFY** | Confirm lint/tools PASS (verification) | Copy Editor (quantitative) → Desk (qualitative — scope per the `desk.md` matrix), divided |

| **ADAPT** | On VERIFY failure, return to GROUND | Reporter / Columnist (no qualitative self-review) |

**The 5 invariants** (APPLY stage): read first, follow the pattern, preserve policy, minimal change, stay in scope.

### The Four Loops

The VERIFY·ADAPT stages run at four scopes; the four together are the project's feedback machinery — one skeleton, widening in scope and slowing in timescale. The [GROUND Ladder](.claude/agents/README.md#ground-ladder) is not a fifth loop: it disciplines input acquisition once, at cycle entry, before there is anything to correct. The content-authoring cycles inside the Inner·Outer·Reground loops enter GROUND through it; the Meta loop's GROUND deliberately keeps no ladder (rationale in that section).

|---|---|---|---|

### Reground

The **Reground loop** — the workflow that re-aligns the derived layer (L2-3 · L2-4 + L2-2 hub·timeline) with ground truth — **published pages come back around as GROUND input**. The blind spot it closes: the quality machinery points only at sources, so nothing ever re-reads whether the pages the wiki itself produced have drifted. Three triggers (condition → realign against · surfacing · execution):

- **Update** — upstream sources changed → the sources · `lint staleness` · [`staleness-reground-runbook`](.claude/operations/staleness-reground-runbook.md) (Columnist)

- **Follow-up** — our own claims carry an unresolved status or a matured deadline → elapsed reality · `lint contradiction`'s `[Reground status]` · Desk re-adjudication ending at the operator gate. **No close path exists yet**: the build stamps every claim `status: open` and nothing writes `resolved`, so a surfaced item re-fires on every run. The first non-empty surface is the trigger to build an adjudication ledger (operator gate)

- **Correction** — our own pages disagree with each other or with a generated artifact → self-consistency · the F2 canonical total (deliberately narrow) + cross-page via [`bundle-reground-runbook`](.claude/operations/bundle-reground-runbook.md) (Desk, by rotation)

Deterministic lint surfaces only mechanically parseable signals (explicit integers, dates, field comparisons); staleness and `[Reground status]` are advisory, while the F2 canonical total is a hard FAIL. The comparison is exact but inherits any imprecision in the field it reads — `type:` is a regex auto-classification, not a verified judgment. The remaining cross-page coherence is the Desk's qualitative responsibility. A deterministic surface never closes an item by itself. Roles reuse the Universal Cycle — Copy Editor quantitative, Desk qualitative, Columnist rewrite.

The Layer × Cycle matrix (which role sits in which cell), the GROUND Ladder, the Standard ADAPT chain, the escalation procedure, and the Authoring Responsibilities tiering: [`.claude/agents/README.md`](.claude/agents/README.md) is the SoT. The authoring standards per content type and the Evaluation Rubric: [`.claude/layers/`](.claude/layers/) is the SoT (read by Reporter / Columnist on entering the cycle).

---

## Self-Evolution

The guideline layer improves through the same four-stage cycle as content — the **Meta loop**, which proposes, measures, and adopts changes to the instruction SoTs themselves:

| Stage | Content cycle | Guideline self-evolution |

|---|---|---|

| **GROUND** | read the relevant SoT | `mine_feedback` (operator utterances) + `mine_failures` (verifier-grounded defect corpus) |

| **APPLY** | write the EDITOR block | edit the responsible instruction SoT (absorb-by-default) |

| **VERIFY** | Copy Editor (lint) + Desk (qualitative) | Guideline Verification Ladder — lint meta → minimal-edit check → blind review → effect-measurement gate |

| **ADAPT** | fix on defects | severity-ruled re-pass; 3rd same-cause FAIL escalates to the operator |

SoT: workflow + acceptance rule = [`agents/editor-in-chief.md`](.claude/agents/editor-in-chief.md) (§ SoT Self-Evolution Workflow · § Guideline Verification Ladder) · measurement variants = [`operations/proposal-validation-runbook.md`](.claude/operations/proposal-validation-runbook.md) · authoring craft = [`skills/guideline-writing/`](.claude/skills/guideline-writing/SKILL.md). Standing artifacts: the defect corpus (written by `tools/log_defect.py`, committed) · transition records (the accept/reject ledger) · `.claude/memory/` rejected directions. **Adoption always passes the operator gate** — the loop proposes and measures; it never self-adopts.

---

## Directory Structure

The detailed directory layout + the auto-generated vs. human-edited split + placement rules: [`.claude/policies/directory-layout.md`](.claude/policies/directory-layout.md) is the SoT.

---

## Instruction Locations

Each folder has a **single responsibility**; when adding a new instruction, use this taxonomy to decide its exact location. If the classification is ambiguous, explicit approval from the wiki operator is required.

### `.claude/agents/` — 5 Role SoT + Universal Cycle Framework

**Responsibility**: each role's capability boundary, I/O contract, prompt template, and risk-mitigation design + the Layer × Cycle matrix, Universal Cycle, Standard ADAPT chain, and Authoring Responsibilities (README.md).

**When read**: when the corresponding role is invoked (Cognition principle 1 — full-context Read).

**Instructions located here**:

- `README.md` (Layer × Cycle matrix, the four-stage definitions, the standard ADAPT chain, escalation, Authoring Responsibilities)

### `.claude/commands/` — 9 Slash Command SoT + Task Index

**Responsibility**: each slash command's procedure, arguments, output, and per-subcommand sub-procedures (including command-specific sync procedures and mapping rules). README.md holds the Task Index + Convention.

**When read**: when the corresponding command is triggered.

**Instructions located here**:

- `README.md` (Task Index, the "Extend Before Adding" Convention, natural-language usage examples, sub-procedure locations)

- Command sub-procedures (e.g. the conflict-axis sync rule and the theme lifecycle·gate rules in `wiki-lint.md`, and the full theme re-derivation procedure in `wiki-lint-theme-mapping.md`) are the sole responsibility of this folder. The roster is the [`commands/README.md`](.claude/commands/README.md) Sub-procedure Locations table.

### `.claude/layers/` — Content-Type Authoring & Review SoT

**Responsibility**: the instructions needed to **write and review** each wiki content type (L2-1 / L2-2 / L2-3 / L2-4) at high quality against its prescribed format. Page Format + Authoring + Evaluation Rubric are consolidated into one file per content type.

**When read**: when the Reporter / Columnist enters the cycle + during Desk review.

**Instructions located here**:

- `source.md` (L2-1) · `hub.md` (L2-2) · `timeline.md` (L2-2 standalone timeline) · `overview.md` (L2-3 cluster + L2-4 root) · `contradiction.md` (L2-3 theme + L2-4 aggregate) · `synthesis.md` (L2-3 synthesis) · `trail.md` (L2-3 trail)

- `README.md` (Layer definitions, axis structure, common frontmatter, Root Meta Files Exception)

**What does NOT belong here**:

- Qualitative review procedures (the 6 lenses, personas) — the Desk's sole domain, so [`.claude/agents/desk.md`](.claude/agents/desk.md).

- Command sub-procedures (theme lifecycle and gates, sync rule) — [`.claude/commands/wiki-lint.md`](.claude/commands/wiki-lint.md); the full theme re-derivation — [`.claude/commands/wiki-lint-theme-mapping.md`](.claude/commands/wiki-lint-theme-mapping.md).

### `.claude/skills/` — Agent Skills SoT (project-agnostic)

**Responsibility**: Claude Code Agent Skills (each one folder with a `SKILL.md`) — project-independent modules unrelated to any particular content or task type. Two branches coexist: (a) **writing craft** — referenced by the layers via dotted IDs and measured by `tools/lint.py` (accompanied by `criteria.json` + `checks.py`). (b) **coding discipline** — a behavioral skill that fires at authoring time when writing `tools/` Python (not lint-measured; `SKILL.md` only).

**When read**:

- **Explicit Read** (in-project, primary): the layers' mapping table and the craft skill specified by the agent prompt, on the Columnist / Desk entering the cycle.

- **Auto-fire**: any other writing/coding/review task that matches a skill's `description` (the description follows the auto-discovery format, so both paths coexist).

**Instructions located here**:

*Writing craft* (each skill = one folder of `SKILL.md` + `criteria.json` + `checks.py`, referenced by layers' dotted IDs, lint-measured):

- `journalism-writing` (`jrn.*`) — journalism and argumentation (inverted pyramid, Toulmin, Hegelian dialectic, BBC impartiality)

- `consulting-writing` (`con.*`) — management consulting (McKinsey SCR, MECE, BCG bold-bullet)

- `encyclopedia-writing` (`enc.*`) — encyclopedic neutrality (NPOV, summary style, wikilink conventions)

- `scholarly-citation` (`cit.*`) — verifiable attribution and citation (claim atomization, evidence grading, citation typing, anchoring)

- `guideline-writing` (`gdl.*`) — guideline-authoring craft for the instruction layer itself (operative rule vs recital, MUST/SHOULD/MAY, pruning, bloat control, blind review; the deliberation-narrative detectors run in `lint.py meta`)

*Coding discipline* (`SKILL.md` only, not lint-measured):

- `ponytail-coding` — lazy-senior code restraint (the YAGNI ladder, reuse first, root-cause fixes, stated assumptions, verifiable success criteria). Divides labor with `/simplify` (after-the-fact cleanup).

**What does NOT belong here**:

- Content-type page formats, section names, execution order — [`.claude/layers/`](.claude/layers/) (skills cover craft only; the layers apply it to this project).

### `.claude/policies/` — Global Policies

**Responsibility**: conventions affecting the **whole wiki** — directory, naming, language, platform, index/log format, and so on. On a violation, automatic lint detection is the first line of defense.

**When read**: when creating a new file, renaming, or making a language decision (policy changes require explicit approval from the wiki operator).

**Instructions located here**:

- `directory-layout.md` (directory structure + the `_` prefix and placement rules + the `cluster_labels.json` human-edit convention)

- `naming.md` (slug and filename conventions + Reserved meta-doc names + the entity/concept stub thresholds)

- `language.md` (English body text + English frontmatter keys + Meta-Doc English headers + Prose Style avoidance of translationese; Korean body text is an optional `WIKI_LANG=ko` mode)

- `platform.md` (Windows non-Latin filename encoding workaround)

- `index-log-format.md` (the two-tier structure of `wiki/index.md` + `log.md` append-at-bottom)

- `README.md` (file index + invocation convention)

Guideline-authoring voice and plan-bloat control are craft, not policy — they live in the `guideline-writing` skill (`gdl.*`).

### `.claude/operations/` — One-Time Procedures & Infra Setup

**Responsibility**: new-device setup, infra-token renewal, and one-off migration procedures. Rarely read, but the sole SoT when needed.

**When read**: on infra changes (adding a device, renewing a token, etc.).

**Instructions located here**:

- `mobile-inbox-setup.md` (one-time setup for mobile share-sheet → GitHub Contents API)

- `gap-detection-rollout.md` (the rollout plan for gap diagnosis, automatic backfill, and separating the operator surface + the SoT for thresholds, priorities, and the domain set)

- `graph-hosting-setup.md` (setup for publicly deploying the graph browser's `_site/` artifact to Cloudflare Pages)

- `codebase-audit-runbook.md` (the multi-agent batch procedure for ultrareviewing tools/ code and .claude/ instructions — group decomposition, review dimensions, adversarial verify, the mechanical/gated application policy)

- `staleness-reground-runbook.md` (Reground **update mode** — the batch procedure for re-grounding stale derived narratives surfaced by `/wiki-lint staleness`: per-type pipeline, Desk gate, verification, recurrence pitfalls)

- `bundle-reground-runbook.md` (Reground **correction mode** — the Desk reads a published cluster's bundle together to catch the cross-page defects single-page review cannot see: bundle assembly, defect classes, routing, cadence, deterministic-promotion candidates)

- `proposal-validation-runbook.md` (the batch procedure for measuring the effect of self-evolved guideline changes — three variants by type (desk-judged blind rewrite × blind desk, behavioral probe task, lint-scored before/after); the acceptance rule lives in `agents/editor-in-chief.md` § Gate)

### `.claude/hooks/` — Auto-Block & Guard Shell

**Responsibility**: detect harness events and automatically block or give feedback. The user of this folder (Claude) never reads it directly — the harness invokes it automatically.

**Activation**: in `.claude/settings.json`, the hook `command` must be of the form `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh"` — both the prefix and the anchor are mandatory. The Windows shell cannot run a bare `.sh` directly, so without `bash` every hook is silently disabled; a cwd-relative path resolves only while the session sits at the repo root, so without `$CLAUDE_PROJECT_DIR` every hook silently fails as soon as work moves into a subdirectory. Either failure surfaces as a non-blocking error, never as a block — the guard simply stops guarding.

**Instructions located here**:

- `lint-chain-guard.sh` (detects the lint stdout chain marker → blocks writing the report)

- `dispatch.sh` + `dispatch.py` (the single Write|Edit pre/post + Bash commit-gate dispatcher — parses stdin once, merges simultaneously-firing advisories into a single payload, with a shell fallback when python3 is absent. Consolidated responsibilities:)

- guard: exit-2 block when the per-target drift blocks in `lint-report.md` are asymmetric

- - advisory: on a `git … commit` in **command position**, names the guideline files that commit carries (same set as the ladder advisory below; the index first, else the paths the command stages) and prints the Guideline Verification Ladder — never a block, and the payload can land after the commit, so it names the not-yet-run branch too

+ - advisory: on a `git … commit` in **command position**, names the guideline files that commit carries (same set as the ladder advisory below; a commit pathspec decides alone, else the index, else the paths the command stages) and prints the Guideline Verification Ladder — never a block, and the payload can land after the commit, so it names the not-yet-run branch too

- guard: exit-2 block on direct Write|Edit of auto-generated build artifacts (`wiki/index.md`, `graph/_*.json`, etc.) or `raw/` originals — steering you to fix the input and regenerate (re-derivation, human-edited files, and queue files are exceptions; the full list is in `dispatch.py`)

- advisory: after writing a stub, recommend `python tools/build.py` reconciliation + Desk VERIFY₂ (`wiki/entities·concepts·timelines/*.md` — structural prevention of the 2026-05-09 / 05-20 incidents)

- advisory: after editing L2-2 full hub, timeline, L2-3, or L2-4, recommend the layer's `python tools/lint.py` self-VERIFY₀ — target-scoped where the group accepts a target, corpus-wide (judged on own output) where it does not

- advisory: for `*/plans/*.md`, the 5-step self-check, the 4 red-flag types + for the guideline SoTs under `.claude/` and CLAUDE.md (scope SoT: [`agents/editor-in-chief.md`](.claude/agents/editor-in-chief.md) § Guideline Verification Ladder), the Guideline Verification Ladder + a diff bullet-depth check (helper `check_bullet_depth.py`)

- advisory: on editing a desk-judged prose-craft SoT (`.claude/layers/*.md`, `agents/desk|reporter|columnist.md`), recommend the proposal-validation measurement before adoption (SoT: `operations/proposal-validation-runbook.md` + `agents/editor-in-chief.md` § Gate)

- advisory: after writing a `wiki/` page containing an unresolved wikilink, name the targets and require one of four resolution branches before hand-off (branch text in `dispatch.py`; page-existence uses the same `tools/_lib.py` set as `lint graph structure`)

- advisory: on Write of a script-like temporary file directly under the project root, recommend a temp directory (structural prevention of the 2026-05-08 incident)

- advisory: on writing or modifying `tools/**/*.py` or `.claude/hooks/*.py|sh`, recommend loading and applying the `ponytail-coding` skill (the authoring-time code-restraint reflex — the SoT is `skills/ponytail-coding/SKILL.md`; the rule body is not duplicated here)

### `.claude/memory/` — Local Memory

**Responsibility**: project-specific local records of feedback and decisions (separate from the system auto-memory).

**When read**: on entering related work.

> **Note:** a tracked `.gitkeep` keeps this folder in the repo — leave it in place. Anything else you write here stays local.

**Instructions located here**:

- Local notes such as `feedback_*.md`

---

## Human Reviewer Gate

In the following situations, do not proceed automatically:

- A 3rd ADAPT FAIL for the same reason · a Guideline Verification Ladder that has not converged after 3 rotations (regardless of cause)

- A new cluster slug (`graph/cluster_labels.json`) / a new contradiction theme slug

- A new entity (person/company/SW-solution) or concept stub (only past the citation thresholds — `.claude/policies/naming.md` entity/concept stub thresholds)

- Publishing L2-4 root content

- Changes to the skeleton of a guide, rubric, or matrix

- External commit / push (exception: the system-managed inbox queue files `raw/_inbox.md`·`raw/_archive.md`, which `/wiki-ingest` Inbox Mode commits·pushes automatically)

- A large body rewrite (>50% changed)