polydeukes 0.6.0 → 0.7.1

package/dist/docs/reference/{configuration.md → configuration/index.md}

@@ -1,13 +1,15 @@
 # Configuration reference
 
-**English** · [한국어](./configuration.ko.md)
+**English** · [한국어](index.ko.md)
 
 Every key of `polydeukes.config.yaml`, one section per key. The guide — what the file is,
 how discovery fails, and the IDE wiring — is
-[Configuring Polydeukes](../configuration.md), and what a verdict looks like when a
+[Configuring Polydeukes](../../how-to/configure-project.md), and what a verdict looks like when a
 discipline fires is its
-[What enforcement looks like](../configuration.md#what-enforcement-looks-like) section.
+[What enforcement looks like](../../how-to/configure-project.md#choose-advise-or-block)
+section.
 
+<a id="languages"></a>
 ## `languages`
 
 Required. The language axis, first-class. Keys are your values (`typescript`, `python`, …) —
@@ -24,6 +26,7 @@ languages:
 all other braces (`${VAR}`, `{a,b}`, `awk '{print}'`) pass through untouched. A command
 that ignores scope (`pnpm test`) is equally valid.
 
+<a id="protectedpaths"></a>
 ## `protectedPaths`
 
 Optional. Raw path patterns whose files the covenants protect from modification — by
@@ -42,6 +45,7 @@ to `protectedPaths` — an edit that would lower your own gates goes through the
 as everything else. If the file that declares the disciplines were not itself under the
 disciplines, the whole chain would be decoration.
 
+<a id="adapters"></a>
 ## `adapters`
 
 Optional. Adapter namespaces. One config file, one namespace per adapter: each key names an
@@ -52,62 +56,37 @@ rejected by that adapter's validator, with the full field path in the error.
 
 ```yaml
 adapters:
-  git:
-    enforce: advise
-    protectedPaths:
-      - 'packages/core/src'
+  example:
+    someKey: 'a value the example adapter defines'
 ```
 
-### `adapters.git` — the git commit adapter
-
-| Key | Values | Default | Meaning |
-|---|---|---|---|
-| `enforce` | `block` \| `advise` | `block` | Enforcement level of the commit surface |
-| `protectedPaths` | string array | `[]` | Additive protection scope judged by the commit surface only |
-
-- **`block`** — a staged change that breaks a covenant blocks the commit (exit 2). The
-  only way through is the witness valve: a human answering the TTY prompt with the full
-  token. The prompt names what it asks the human to witness — the broken registration,
-  the matched entry, and the fact that the one answer covers the whole commit. An absent
-  namespace, an absent `adapters` map, or an absent `enforce` key all mean `block` — not
-  writing the key selects the strictest level.
-- **`advise`** — the commit surface becomes a backstop without a block: a verdict on a
-  staged change is recorded as an `advised` telemetry event and the commit proceeds
-  (exit 0) with one advisory line on stderr. No TTY prompt fires. Only the verdict is
-  relaxed — a run that cannot judge (missing or invalid config, an unresolvable judge
-  body) still fails closed at exit 2, at either level.
-
-**`protectedPaths` here is an additive scope.** The commit surface judges the union of the
-top-level `protectedPaths` and this list — concatenated (common first) and normalized as one,
-so spelling and dedupe rules are identical for both. The session surface never reads it: the
-list exists for paths whose edit is legitimate work during a session but must pass a judged
-checkpoint when it is promoted into repository history — a judgment chain's own sources are
-the canonical tenant. As the enforcement level is the observer's setting, so is the
-additional scope. There is no subtractive vocabulary: a config line can widen a surface's
-scope, never quietly strip one.
-
-The session surface (the editor-time hook) has no level setting here. What it blocks is the
+**`protectedPaths` is one list for both surfaces.** There is no additive change-set-only scope
+and no surface-level enforcement key in the config. The change-set surface judges the same
+normalized list the session surface does. A violation exits 2 on the session surface; on the
+change-set surface it lands `advised` at exit 0 unless the check runs with `--enforce block`. The
+judge emits only that exit code: whether a commit stops is the user's hook wiring, so a
+telemetry row records the verdict, not the commit's fate — a `blocked` row can sit beside a
+commit that proceeded because the wiring ignored the exit code.
+
+The session surface (the editor-time hook) has no level setting either. What it blocks is the
 judging chain's own protection — `protectedPaths` mutations and mentions on the tool and
 shell axes, the session transcript, an assembly that cannot judge (missing or invalid
 config, unbuilt judge, unparseable payload, a routing that could not answer) — plus any
 entry promoted with `enforce: block`. Every other discipline entry lands `advised` there.
 
-**Declarations that read the session skip on the commit surface.** A commit has no session
-to look at, so a declaration whose `sources` bind the transcript — a `precedent`,
-`phase-order`, `turn-locality` or `stated-ground` entry — cannot be judged there; demanding
-evidence a commit cannot carry would block every matching commit with no legitimate way
-through. The declaration's own `supply: { session: 'pass' }` disposes of the absence: when
-its scope matches a staged change it records a `skipped` telemetry event carrying the reason
-token `supply-pass` and lets the commit proceed. The record carries the entry's `id` and the
-change it would have judged, so a gate that did nothing says so in the data — and it appears
-**only when the entry's scope actually matched**. A declaration scoped on the `command`
-source records nothing at all there: a staged diff carries no command line, so no world it
-observes is ever admitted.
-
-This is the same disposition the session surface uses whenever it has no transcript to
-read. One rule, both surfaces: evidence that cannot be evaluated is skipped and measured,
-never blocked and never silent.
+**A declaration reaches only the surface that observes its channels.** A transcript reader is
+written in `sessionDisciplines` and is never compiled for a change set; a `changes` reader is
+written in `changeSetDisciplines` and is never compiled for one call. The three lists and the
+rule that places an entry in one of them are in [the three discipline
+lists](#three-lists).
+
+A declaration's `supply` policy still governs a channel the surface registers but the host
+does not prove. A host that carries no session (the Grok adapter) leaves a
+`sources: { session: { transcript: true } }` entry's source absent, and `supply: { session: 'pass' }`
+records a `skipped` telemetry event carrying the reason token `supply-pass` and lets the call
+proceed. Without that policy a missing source is unjudgeable (exit 2), not an automatic skip.
 
+<a id="telemetry"></a>
 ## `telemetry`
 
 Optional.
@@ -122,6 +101,7 @@ Telemetry is fail-open by design: a logging failure never changes a verdict. The
 itself is still validated at load time — an empty or whitespace-only `logPath` is
 rejected.
 
+<a id="witness"></a>
 ## `witness`
 
 Optional.
@@ -174,11 +154,141 @@ when the token arrives in a message positively identified as human-typed in the
 transcript, so an AI that knows the token still cannot forge one. Witnessed judgments are
 recorded as `witnessed`, never silent.
 
+<a id="three-lists"></a>
+## The three discipline lists
+
+A discipline is written in one of three lists, and which one is a fact about the declaration
+rather than a choice the author makes. A declaration names the evidence channels it reads in
+its own syntax, and a surface observes some channels and not others, so the list follows from
+the channels.
+
+| List | Judged on | What its declarations read |
+|---|---|---|
+| `disciplines` | both surfaces | the changed file itself (`target.path` · `pre` · `post` · `state`) and `file` sources — nothing else. Drafts live here too |
+| `sessionDisciplines` | the session surface only | at least one of `command` · `transcript` · the `sidecar` channel · `actor`, and never `changes` |
+| `changeSetDisciplines` | the change-set surface only | `changes`, and no session channel |
+
+The session surface is one call a host observed before it ran — an adapter hook, or a program
+calling the SDK with an input IR. It carries the command line, the conversation history, the
+spawn-record channel, and the actor, and it does not carry the finished change set. The
+change-set surface is `pdks covenant check --diff` over a change set some producer finished.
+It carries `changes`, and it carries no command line, no history, and no actor.
+
+<a id="channel-to-list"></a>
+### Channel to list
+
+Each channel appears in a declaration in a fixed syntactic position, and the loader reads
+those positions to derive the list.
+
+| Channel | How it appears in a declaration | List |
+|---|---|---|
+| `transcript` | `sources: { session: { transcript: true } }` | `sessionDisciplines` |
+| `channel` | `sources: { spawns: { sidecar: true } }` | `sessionDisciplines` |
+| `command` | `scope: { source: 'command' }`, or `{ op: 'source', of: 'command' }` in any pipeline | `sessionDisciplines` |
+| `actor` | `{ op: 'source', of: 'actor' }` in any pipeline | `sessionDisciplines` |
+| `changes` | `{ op: 'source', of: 'changes' }` in any pipeline | `changeSetDisciplines` |
+| none of the five | the declaration reads the changed file and `file` sources alone | `disciplines` |
+
+A `witness` block's own `extract` is walked with the body's, so a valve reading the transcript
+puts its entry in `sessionDisciplines` like any other transcript reader.
+
+<a id="placement-rule"></a>
+### The placement rule
+
+`disciplines` takes an entry binding none of the five channels, plus every draft.
+`sessionDisciplines` takes an entry binding at least one session channel and not `changes`.
+`changeSetDisciplines` takes an entry binding `changes` and no session channel. Anything else
+is a `ConfigValidationError` at load time, on both surfaces, and the message names the entry,
+the channels it reads, and the list it belongs in:
+
+```text
+disciplines[7] ('merge-is-the-users-call') reads transcript, command: it belongs in sessionDisciplines
+```
+
+Two shapes have no destination to name. A declaration binding both `changes` and a session
+channel is refused outright, because no surface observes both at once:
+
+```text
+sessionDisciplines[2] ('pairs-across-a-session') reads transcript, changes: no surface observes both changes and a session channel
+```
+
+A draft binds nothing — it carries no declaration — so it belongs in `disciplines`, and a
+draft written in either surface list is refused with `a draft belongs in disciplines`.
+
+Ids are unique across all three lists and the three meta-covenant labels (`self-mod` ·
+`shell-mod` · `transcript-mod`): the telemetry label space is one space, and `pdks explain`
+and every label-keyed reader index by the label alone.
+
+<a id="lists-in-practice"></a>
+### What each surface compiles
+
+`pdks covenant check` reading an input IR on stdin compiles `disciplines` followed by
+`sessionDisciplines`; the same command with `--diff` compiles `disciplines` followed by
+`changeSetDisciplines`. `pdks explain` prints both surfaces with each list's name and count in
+the surface header, so the placement of every entry is readable without running a judgment.
+This repository's live config places 11 judged entries and 1 draft in `disciplines`, 13 in
+`sessionDisciplines`, and 1 (`docs-stay-bilingual`) in `changeSetDisciplines` — 24
+registrations on the session surface and 12 on the change-set surface.
+
+```yaml
+disciplines:            # both surfaces
+  - id: 'covenant-vocabulary'
+    declare:
+      mechanism: 'added-only'
+      scope: { source: 'target.path', include: ['^packages/'] }
+      supply: { pre: 'empty', post: 'empty' }
+      extract:
+        before: [{ op: 'source', of: 'pre' }, { op: 'lines' }]
+        after: [{ op: 'source', of: 'post' }, { op: 'lines' }]
+        added: [{ op: 'onlyIn', of: 'after', notIn: 'before' }]
+      relate:
+        - { id: 'nothing-added', relation: { op: 'empty', of: 'added' }, message: 'adds {value}' }
+
+sessionDisciplines:     # the session surface only — reads command
+  - id: 'pnpm-only'
+    declare:
+      mechanism: 'forbidden-command'
+      scope: { source: 'command' }
+      extract:
+        hits:
+          - { op: 'source', of: 'command' }
+          - { op: 'lines' }
+          - { op: 'matches', re: '\bnpm install\b' }
+      relate:
+        - { id: 'no-npm', relation: { op: 'empty', of: 'hits' }, message: '{value}' }
+
+changeSetDisciplines:   # the change-set surface only — reads changes
+  - id: 'docs-stay-bilingual'
+    declare:
+      mechanism: 'companion'
+      scope: { source: 'target.path', include: ['\.md$'] }
+      extract:
+        en:
+          - { op: 'source', of: 'target.path' }
+          - { op: 'keyByPattern', re: '^(.+?)(?<!\.ko)\.md$' }
+        koChanged:
+          - { op: 'source', of: 'changes' }
+          - { op: 'items' }
+          - { op: 'keyByPattern', re: '^(.+)\.ko\.md$' }
+      relate:
+        - id: 'ko-follows'
+          relation: { op: 'implies', of: 'en', requires: 'koChanged' }
+          message: '{value} changed without {key}.ko.md'
+```
+
+Moving an entry between lists is the whole edit: the entry's body is unchanged by the move,
+and the loader is what says whether the new place is the right one.
+
+<a id="disciplines"></a>
 ## `disciplines`
 
 Optional. Each entry is one discipline: a practice the team imposes on itself, declared as
-data. A judged entry carries a `declare` block — the one judged form, a declaration whose
-`scope` lives inside the block — an `id` (the telemetry label), and optionally a `why` (the
+data. Everything in this section applies to an entry in any of the three lists; which list an
+entry is written in is decided by [the placement rule](#placement-rule), and
+`sessionDisciplines` and `changeSetDisciplines` take the same entry shape as `disciplines`
+minus the draft form. A judged entry carries a `declare` block — the one judged form, a
+declaration whose `scope` lives inside the block — an `id` (the telemetry label), and
+optionally a `why` (the
 reason, which travels with the block message the agent reads) and an `enforce` level. The
 closed key set is `id` · `why` · `enforce` · `declare`; any other key is refused.
 
@@ -192,11 +302,15 @@ error, and `draft: false` is rejected as dead data.
 
 ```yaml
 disciplines:
-  - id: 'bilingual-docs-sync'
-    why: 'en and ko doc mirrors must move together.'
+  - id: 'benchmark-supports-performance-claim'
+    why: 'a performance claim must be supported by a fresh benchmark run during judgment.'
     draft: true
 ```
 
+A bilingual mirror pair is not a draft. The engine already judges that shape as `companion`
+(this repository's `docs-stay-bilingual` entry). Use `draft: true` only for a promise the
+current grammar cannot express.
+
 A `why` is never judged — it changes no verdict. It is appended to the break message once a
 verdict has blocked, so whoever reads the block gets the rationale in the same line instead
 of having to open this file. A `why` spanning several lines is folded to spaces: the message
@@ -205,10 +319,10 @@ is one line.
 **`enforce` — the entry's own level.** Optional on any judged entry: `block` or `advise`.
 **Absent means `advise`.** Under `advise` a break is recorded as an `advised` telemetry
 event and the call proceeds (exit 0), with the break message still written to stderr;
-`block` is the promotion — it pins the entry at block. The entry's level composes with the
-surface's (`adapters.git.enforce` on the commit surface; the session surface has none) and
-the lenient side wins — an `advise` on either axis makes the entry advise, and an explicit
-`block` never raises a surface the observer set to advise. An unjudgeable body (never
+`block` is the promotion — it pins the entry at block. The config carries no surface-level
+enforcement key: absent or `advise` means `advised` on both surfaces, `block` means exit 2 on
+the session surface and on a change-set check run with `--enforce block` (the change-set
+surface's default posture is advise for every verdict). An unjudgeable body (never
 built, or one that cannot be loaded) still blocks whatever the level. A draft carries no
 `enforce`; any
 other value is rejected at load time. `pdks explain` prints the level an entry declares
@@ -242,21 +356,21 @@ regular expressions over the path.
 
 ```yaml
 disciplines:
-  - id: 'covenant-vocabulary'
-    why: 'control-framing vocabulary is banned in package sources.'
+  - id: 'no-focused-tests-in-src'
+    why: 'a focused test must not land in shared source.'
     declare:
       mechanism: 'added-only'
-      scope: { source: 'target.path', include: ['^packages/[^/]+/src/'] }
+      scope: { source: 'target.path', include: ['^src/', '^test/'] }
       supply: { pre: 'empty', post: 'empty' }
       extract:
         before:
           - { op: 'source', of: 'pre' }
           - { op: 'lines' }
-          - { op: 'keyByPattern', re: '\b(guard|harness|kb)\b' }
+          - { op: 'keyByPattern', re: '(\.only\()' }
         after:
           - { op: 'source', of: 'post' }
           - { op: 'lines' }
-          - { op: 'keyByPattern', re: '\b(guard|harness|kb)\b' }
+          - { op: 'keyByPattern', re: '(\.only\()' }
         added:
           - { op: 'onlyIn', of: 'after', notIn: 'before' }
       relate:
@@ -266,12 +380,13 @@ disciplines:
 ```
 
 The key is the match text, so a line carrying a word the file already has anywhere is
-forgiven, and a line carrying two new words surfaces the first one now and the second on the
-next judgment.
+forgiven. A line carrying two new words surfaces only the first match; the second appears
+on a later judgment **after that first match is removed**. Re-judging the same input yields
+the same first match.
 
 **A frozen path is a declaration too.** A file that may be created once and never modified
 or deleted: `pre` present means a modification, `post` absent means a deletion, and either
-breaks.
+breaks. Creating the file, including with empty contents (`post: ''`), passes.
 
 ```yaml
   - id: 'archived-records-stay-frozen'
@@ -297,7 +412,14 @@ declaration reads that source, cuts it into lines, keeps the lines a pattern mat
 requires the result to be `empty`. It scopes on `command` so that only shell calls are
 admitted: an Edit carries no command line, and a declaration reading a source its world
 lacks is unjudgeable. A multi-line command is judged line by line, so `^` means the start
-of a line; a pattern that would span a line boundary does not match.
+of a line; a pattern that would span a line boundary does not match. Heredoc bodies and
+herestring words are not part of the source: bash passes them to the command as stdin
+data rather than executing them, so a banned token quoted inside one is not a match, and
+whether that data becomes a file write is judged by the shell-evidence path instead. Text
+bash expands first stays in the source — a body under an unquoted delimiter that carries
+`$` or a backtick, and a herestring word holding a substitution — as does a line the
+tokenizer could not finish reading. What the receiving command does with its stdin is not
+judged: a script fed to an interpreter is data to bash and a program to the interpreter.
 
 ```yaml
   - id: 'hooks-stay-armed'
@@ -323,8 +445,9 @@ declaration the user turns and tool calls as one snapshot, `toolUses` picks the
 `matches` finds the required one; `nonEmpty` is the verdict. A call the covenant blocked,
 one a human refused, and one that simply failed are not precedent. The pattern is matched
 anywhere in a command line — a line that merely mentions the command counts, a declared
-limit. `supply: { session: 'pass' }` is what makes the commit surface record `skipped`
-instead of blocking every matching commit.
+limit. `supply: { session: 'pass' }` is what disposes of an absent session on a host that proves
+none; an entry reading the transcript is written in `sessionDisciplines`, so a change set never
+compiles it at all.
 
 ```yaml
   - id: 'dependency-needs-npm-view'
@@ -360,10 +483,12 @@ adds nothing to an added-only difference and the discipline silently passes: mak
 pattern span the whole value that can change. Both failure shapes compile, run, and answer
 `passed`, so measure a new entry against a real file and a realistic edit.
 
-**The cheap way through is the honest one.** Unlike the witness, session evidence lives on
-the AI's own surface, so it is not forgery-proof. It does not need to be: the least
-effortful way to open this gate is to actually run the command, and that is exactly the
-behaviour the discipline exists to induce.
+**Witnesses and precedent evidence are different.** A pattern seeking precedent evidence must
+distinguish the required action from a mere mention. Session evidence lives on the AI's own
+surface, so it is not forgery-proof; the design relies on the least effortful way to satisfy
+the check being to actually run the command, which is the behaviour the discipline exists to
+induce. A pattern alone does not eliminate the possibility of forged evidence. Test both valid
+and violating cases.
 
 **`declare` — declaration family.** One judgment written as data, in the algebra grammar
 the core publishes as `algebra-declaration.schema.json`: `judge = relate ∘ extract`. The
@@ -372,37 +497,37 @@ block carries the declaration's `scope`, `sources`, `supply`, `extract`, `relate
 `discipline` key, and `in`/`except`/`when` are refused — the `scope` block is the scope.
 
 ```yaml
-  - id: 'db-only-under-knowledge'
-    why: 'a *.db file may exist only under _docs/knowledge/'
+  - id: 'db-files-only-under-data'
+    why: 'a *.db file may exist only under data/'
     declare:
       mechanism: 'naming'
       scope: { source: 'target.path', include: ['\.db$'] }
       extract:
         outside:
           - { op: 'source', of: 'target.path' }
-          - { op: 'matches', re: '^(?!_docs/knowledge/)' }
+          - { op: 'matches', re: '^(?!data/)' }
       relate:
         - id: 'placed'
           relation: { op: 'empty', of: 'outside' }
-          message: '{value} is outside _docs/knowledge/'
+          message: '{value} is outside data/'
 ```
 
-This repository's live config carries the same declaration as `sqlite-only-under-knowledge`.
+This repository's live config uses the same mechanism with `_docs/knowledge/` as
+`sqlite-only-under-knowledge`.
 
 Each observation is judged as one **world** with seven source names: `target.path` (the
 repo-relative path), `pre` and `post` (the file's text on the side the change carries —
 a creation has no `pre`, a deletion no `post`), `state` (`{ pre, post }`, present only
 on a modification), and `changes` (every path the observation changes — the one call on the
-session surface, the whole staged set on the commit surface), and `command` (the shell
+session surface, the whole staged set on the change-set surface), and `command` (the shell
 call's command line — present on a shell call only, and a shell call that changes no file
 is one world of its own, so a declaration scoped on `command` sees it while one scoped on
 `target.path` does not), and `actor` (the observation's actor — described below). A
-declaration that reads `changes` is judged only where the whole change set is observed: the
-session surface records it `skipped`, the same disposition the commit surface gives a
-declaration that reads the session, because one call can never carry the other half of a
-pair. This repository's live config
-carries one — `docs-stay-bilingual`, an `implies` over the `.md`/`.ko.md` pair, advised
-on the commit surface when one side is staged without the other. A declaration that needs a
+declaration that reads `changes` is written in `changeSetDisciplines` and compiled only where
+the whole change set is observed, because one call never carries the other half of a pair.
+This repository's live config carries one — `docs-stay-bilingual`, an `implies` over the
+`.md`/`.ko.md` pair, advised on the change-set surface when one side is staged without the
+other. A declaration that needs a
 file outside the target names it in a `sources` block, `sources: { en: { file:
 'locales/en.json' } }`, and reads it as `{ op: 'source', of: 'en' }`; the path is
 repo-relative (no leading `/`, no `..` segment) and the name may not be one of the seven. The
@@ -412,16 +537,16 @@ touches is read from the change's `post`, so both surfaces judge the same text.
 kind, `sources: { spawns: { sidecar: true } }`, names the session's spawn-record channel
 instead of a path — the subagent records the host keeps beside the transcript, supplied as
 one JSON array; where the channel lives is the surface's fact, so the value is the marker
-`true`, and on the commit surface (which has no session) the channel is always absent. A
+`true`, and on the change-set surface (which has no session) the channel is always absent. A
 third kind, `sources: { session: { transcript: true } }`, names the session's own
 conversation history — the user turns and tool calls the surface reads, handed to the
 declaration as one snapshot whose entries carry their
 observation ordinal; the history steps (`toolUses`, `userTexts`, `first`, `ageMs`) read it, and
 `agentType` reads the parsed sidecar. This repository's live config carries one —
-`tests-before-implementation`, an `ordered` over the ordinals of two subagent spawns, which
-the commit surface (no session) records `skipped`. The seventh fixed name, `actor`, is the
+`tests-before-implementation`, an `ordered` over the ordinals of two subagent spawns, written
+in `sessionDisciplines`. The seventh fixed name, `actor`, is the
 observation's actor — `{ agentType }` inside a subagent, `{}` in the main session, absent
-where the surface proves none (the commit surface) — read as `{ op: 'source', of: 'actor' }`
+where the surface proves none (the change-set surface) — read as `{ op: 'source', of: 'actor' }`
 followed by `select` on `agentType`; it derives the `actor` axis the `producer-owned` and
 `actor-scope` mechanisms require, and this repository's live config carries one of each
 (`tests-are-the-writers`, `commits-come-from-the-main-session`). A `supply` key must name

package/dist/docs/reference/packages/adapter-claude-code.ko.md

@@ -0,0 +1,110 @@
+# `@polydeukes/adapter-claude-code`
+
+[English](adapter-claude-code.md) · **한국어**
+
+> **Claude Code의 설치 단위**입니다. PreToolUse 페이로드가 약속(covenant) 입력 IR이 되고,
+> 판정기가 읽는 파일 변경 증거와 대화 기록(transcript) 통로가 함께 실립니다. 세션 표면을
+> 프로젝트에 설치하는 것도 이 패키지가 합니다.
+>
+> 알파입니다. `polydeukes`와 함께 설치하며, `polydeukes`는 이 패키지의 `peerDependency`입니다.
+
+<a id="ownership"></a>
+## 담당하는 기능
+
+Claude Code의 입력을 공통 형식으로 번역합니다. 에이전트와 도구의 구체적인 이름은 이 패키지에서 처리하고 코어에는 넣지 않습니다. 코어가 특정 에이전트에 의존하지 않는다는
+제약은 테스트로 확인합니다.
+
+| 단위 | 하는 일 |
+|---|---|
+| `pdks-claude-code` 실행 파일 | 하위 명령 하나 `pdks-claude-code init`으로 프로젝트에 세션 표면을 등록합니다 |
+| `runHook` | PreToolUse 페이로드 하나를 입력 IR로 바꾸고 판정기를 스폰합니다 |
+| 페이로드 상향 번역 | 원본 PreToolUse 페이로드가 `CovenantInput`이 됩니다 |
+| 예상 변경 후 상태 | 편집이 적용되면 파일이 무엇을 담을지 디스크를 건드리지 않고 계산합니다 |
+| 파일 변경 증거 | 디스크의 변경 전 상태와 예상 변경 후 상태를 짝지어 변경 증거를 만듭니다 |
+| 대화 기록(transcript) 제공자 | 세션 JSONL 파일을 `CanonicalTranscript`로 바꿉니다 |
+
+생성된 훅 위임자가 불러오는 것이 `runHook({ repoRoot })`입니다. `tools`와 `session` 증거를
+실은 입력 IR을 만든 뒤 `repoRoot`에서 `pdks covenant check --enforce block`을 스폰하고 그
+자식 프로세스의 종료 코드를 그대로 돌려줍니다. 판정은 그 자식 프로세스가 하며, 이 패키지에는
+판정 코드가 없습니다.
+
+**이 패키지는 텔레메트리 행을 쓰지 않습니다.** 스폰 전에 실패하면 그 사실을 한 줄로 만들어
+`pdks`의 표준 입력으로 보내고, `pdks`가 fail-closed 행을 기록합니다. 호출 하나에 행 하나는
+그대로입니다. 판정기를 불러오지도 않습니다. `polydeukes`와 `@polydeukes/core` 모두
+`peerDependencies`이므로 어휘와 판정기를 공유할 뿐 사본을 따로 설치하지 않습니다.
+
+<a id="translation"></a>
+## 페이로드 번역과 세 축
+
+**판정기에 증거를 전달하는 축은 셋**이며, 축마다 제공할 수 있는 증거가 다릅니다.
+
+| 축 | 싣는 것 | 결과 |
+|---|---|---|
+| 도구 | 증명된 `fileChange`입니다. 도구가 실행되기 전에 계산된 변형 대상입니다 | 증명된 대상만 판정합니다. 편집 **내용** 안의 보호 경로는 언급이고 통과합니다 |
+| 셸 | 실행 전에는 대상을 계산할 수 없는 경우가 많은 명령줄입니다 | 계산되는 쓰기는 편집처럼 판정하고, 나머지는 추측하지 않고 기록합니다 |
+| 대화 기록 | 세션 자신의 기록입니다 | 전체 경로 등가로 판정하고 보호 조상으로는 보지 않습니다 |
+
+번역 과정에서 실패하면 어느 단계에서든 호출을 차단합니다(fail-closed).
+서브에이전트 종류가 지정된 `Task` 호출은 스폰에 대응시킵니다. 분류할 수 없는 페이로드는 번역 **실패**이고, `blocked` 한 행을 기록하고
+종료 `2`를 냅니다. 추측으로 물러서지 않습니다. 봉투 최상위의 `agent_type`은 IR의 `actor`가
+됩니다. 서브에이전트 안에서는 `{ agentType }`, 그 밖에는 `{}`입니다. `tool_input`은 에이전트
+자신의 텍스트이므로 여기서 읽지 않습니다.
+
+**변경 후의 증거는 파일을 다시 읽는 대신 계산합니다.** `Edit`, `Write`, `MultiEdit`을
+메모리에서 적용해 예상 변경 후 상태를 구합니다. 다중 편집도 순서대로 적용합니다. 내용을
+확인하는 규율(discipline)은 현재 파일이 아니라 **제안된** 결과를 판정합니다.
+변경 후 상태를 계산할 수 없으면 증거를 만들지 않습니다. 실제 도구도 같은 편집을 거부하기
+때문입니다. 파일을 바꾸지 않는 호출에 변경 증거를 만들어 넣지도 않습니다.
+
+**대화 기록은 사람이 친 것으로 확정된 메시지만 받아들입니다.** 증인 밸브가 사람 전용인
+근거가 이것입니다. AI는 자기 증인을 합성할 수 없습니다. 읽기 실패는 빈 대화 기록이 아니라
+`undefined`로 답합니다. 빈 세션은 아직 아무 말도 하지 않은 것이라 판정 대상이고, 읽을 수
+없는 세션은 증거 통로 자체가 없는 것이라 건너뜁니다. 어느 경우에도 이 부재만으로 증인 밸브가 작업을 허용하지는 않습니다.
+
+**선행(`precedent`)은 선언이지 어댑터 평가기가 아닙니다.** 이 어댑터는 대화 기록
+스냅샷을 공급합니다. 성공한 `toolUses`를 추출해 대조하는 것은 선언 엔진입니다. 이
+패키지에 별도 선례 평가기는 없습니다. 문법은
+[설정 — 규율](../configuration/index.ko.md#disciplines)에 있습니다.
+
+<a id="consumer-contract"></a>
+## 사용자와의 접점
+
+프로젝트 루트에서 두 줄이면 Claude Code 세션 표면이 섭니다.
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npx pdks-claude-code init
+```
+
+`pdks-claude-code init`은 프로젝트에서 `polydeukes`를 찾고, 에이전트와 무관한 초기 파일을
+만드는 `pdks init`을 스폰한 뒤, Claude Code 산출물 넷을 기존 파일을 덮지 않고 씁니다.
+다시 실행하면 이미 있는 산출물마다 `skipped`로 보고하고 아무것도 덮어쓰지 않습니다.
+산출물 전체 목록은 [`pdks init`](../cli/init.ko.md#init-claude-code)에 있습니다.
+
+- **생성된 훅.** 이 패키지의 `runHook`을 불러옵니다. 패키지를 갱신하면 실행할 구현도 바뀌지만
+  훅 파일은 그대로입니다.
+
+별도 설정 네임스페이스는 없습니다.
+
+<a id="limits"></a>
+## 선언된 한계
+
+- **자식 프로세스의 쓰기는 관측 밖입니다.** 이 표면이 판정하는 것은 **선언된 도구
+  호출**입니다. 프로세스를 띄우고 그 프로세스가 파일을 쓰는 명령은, 테스트 러너든 빌드든,
+  명령에 대해 판정되지 자식이 한 일에 대해 판정되지 않습니다. 추적되는 파일에 대해서는
+  변경 집합 표면에서 결과를 별도로 관측할 수 있습니다.
+- **증거는 후상태를 계산할 수 있는 곳에만 있습니다.** 변형 도구 넷이 전부 증거를 내고
+  노트북도 그렇습니다. `NotebookEdit`는 셀 단위 `modify` 증거를 냅니다. 증거가 없는 것은
+  이 어댑터가 해소하지 못하는 페이로드입니다. 읽을 수 없거나 파싱되지 않는 노트북, 이름을
+  붙일 수 없는 셀, 알지 못하는 편집 모드가 그렇습니다.
+- **증거 없는 호출은 보수적으로 판정합니다.** 증명된 대상이 없으므로 호출 인자에 보호
+  경로가 언급됐는지 대조합니다.
+- **저장소 밖 조상은 범위 밖입니다.** 프로젝트 루트 위의 경로는 여기서 관측하지 않습니다.
+  그 범위는 에이전트 실행 환경의 권한 정책으로 제한해야 합니다.
+- **`polydeukes`를 찾지 못하면 행이 남지 않습니다.** 프로젝트에서 우산 패키지를 찾지 못하면
+  스폰할 프로세스도, 기록할 로그 경로도 없습니다. 훅은 stderr에 한 줄을 남기고 종료 코드
+  `2`를 내며 텔레메트리 로그에는 아무것도 추가되지 않습니다. 스폰 전 실패 가운데 이 경우만
+  그렇고, 나머지는 모두 `pdks`에 도달해 행을 남깁니다.
+- **Grok는 `@polydeukes/adapter-grok`로 설치합니다.** 그 패키지가 자기 위임자와 명부를
+  씁니다. 두 세션 어댑터를 한 프로젝트에 함께 설치하면 호출마다 판정기가 두 번 실행될 수
+  있습니다.