polydeukes 0.5.0 → 0.6.1

package/dist/docs/reference/configuration/index.md

@@ -0,0 +1,474 @@
+# Configuration reference
+
+**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](../../how-to/configure-project.md), and what a verdict looks like when a
+discipline fires is its
+[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`, …) —
+the core ships no language names and never interprets the command string.
+
+```yaml
+languages:
+  typescript:
+    productionGlob: 'packages/*/src/**/*.ts'   # what counts as production source
+    testCmd: 'pnpm --filter {scope} test'      # {scope} is substituted at resolve time
+```
+
+`testCmd` is a template string, not a function. Every `{scope}` occurrence is replaced;
+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
+editor tools and by shell commands alike (`sed -i`, `tee`, redirects, heredocs,
+parent-directory moves). Entries are normalized (trimmed, deduplicated) at resolve time.
+An empty-string entry is rejected at load time — it carries no path meaning.
+
+```yaml
+protectedPaths:
+  - 'packages/core/src'
+  - '.claude/hooks'
+```
+
+**The config file protects itself.** The discovered config file is automatically appended
+to `protectedPaths` — an edit that would lower your own gates goes through the same judge
+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
+adapter, and its value is that adapter's own settings object. The core validates the
+container shape only — the keys and the contents belong to each adapter, which ships
+its own validator for its own vocabulary. An unknown key *inside* a namespace is
+rejected by that adapter's validator, with the full field path in the error.
+
+```yaml
+adapters:
+  git:
+    enforce: advise
+    protectedPaths:
+      - 'packages/core/src'
+```
+
+<a id="adapters-git"></a>
+### `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 judged at block level blocks the
+  commit (exit 2): a protected path, or an entry promoted with `enforce: block`. An ordinary
+  entry keeps its own default `advise` under this setting (see `enforce` below). 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. The judgment criteria stay
+  the same; violations no longer block. 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
+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 when their supply policy is `pass`.**
+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 **and** the declaration's `supply` is `pass`. Without that policy a missing source is
+unjudgeable (exit 2), not an automatic skip.
+
+<a id="telemetry"></a>
+## `telemetry`
+
+Optional.
+
+```yaml
+telemetry:
+  logPath: '.polydeukes/roi.log'   # default when omitted; keep it gitignored
+```
+
+Every judgment — passed, blocked, witnessed, advised, or skipped — appends one record.
+Telemetry is fail-open by design: a logging failure never changes a verdict. The path
+itself is still validated at load time — an empty or whitespace-only `logPath` is
+rejected.
+
+<a id="witness"></a>
+## `witness`
+
+Optional.
+
+```yaml
+witness:
+  token: 'covenant witness'   # the phrase a human types in the conversation
+  ttlMinutes: 10              # validity window, in minutes, from that message
+```
+
+The values of the time-boxed human valve, consumed where the covenants are assembled.
+The valve is sudo, not an exemption: the one property a deterministic gate can compute
+about a judgment chain is "is an accountable human present, right now", and the witness
+is that human supplying the pass condition in person. When a covenant blocks a
+legitimate edit, a human types the agreed token into the conversation; blocked judgments
+can be witnessed open for `ttlMinutes` from that message's timestamp, then blocking
+resumes automatically. Both keys are required when the section is present: the token
+must be non-empty after trimming, the window a finite number greater than zero.
+
+**The valve stands after the verdict, never instead of it.** The judge body always runs.
+A call that would have passed anyway never consults the valve, so an open window changes
+nothing about clean work — and a `witnessed` telemetry row therefore always names a real
+block a human answered for, never a ritual. Only a judgment that actually blocked can be
+witnessed open.
+
+**The token must stand alone on the message's first line.** Invoking the witness is
+distinct from talking about it: a message that quotes, questions, or explains the token
+mid-sentence — or wraps it in backticks — does not open the valve, while a first line
+carrying the token alone does, with any following lines free for the work itself.
+
+A message that invokes — the token alone on the first line, the rest free:
+
+```text
+covenant witness
+
+now fix the hook file
+```
+
+A message that merely mentions — the valve stays shut:
+
+```text
+so when does `covenant witness` expire?
+```
+
+The token's value is free — any phrase works, and it is never checked for a prefix or a
+command shape. Only its placement is constrained.
+
+The token is not a secret — the defense is provenance, not secrecy. A witness counts only
+when the token arrives in a message positively identified as human-typed in the session
+transcript, so an AI that knows the token still cannot forge one. Witnessed judgments are
+recorded as `witnessed`, never silent.
+
+<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
+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.
+
+**`draft` — an unpromoted entry.** The one shape that carries no predicate:
+`{ id, why, draft: true }` and nothing else. A draft registers a practice as prose ahead of
+its promotion — it makes no judgment and no telemetry record on either surface, and
+`pdks explain` shows it as `unpromoted`. `why` is required here (the prose is the entry's
+whole body), and the marker must be the literal `true` — a draft is declared, never
+inferred, so an entry with neither a predicate nor `draft: true` is still a validation
+error, and `draft: false` is rejected as dead data.
+
+```yaml
+disciplines:
+  - 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
+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
+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
+(`enforce: block` or `enforce: advise`) on both surfaces and leaves an absent one unmarked;
+the session header states the default.
+
+```yaml
+  - id: 'hooks-stay-armed'
+    why: 'a command that disarms or reroutes the git gate is a gate bypass in itself.'
+    enforce: advise
+    declare:
+      mechanism: 'forbidden-command'
+      scope: { source: 'command' }
+      extract:
+        hits:
+          - { op: 'source', of: 'command' }
+          - { op: 'lines' }
+          - { op: 'matches', re: 'LEFTHOOK=(0|false|no|off)\b|core\.hooksPath' }
+      relate:
+        - { id: 'gates-armed', relation: { op: 'empty', of: 'hits' }, message: '{value}' }
+```
+
+**Added-direction content is a declaration.** A promise about what an edit *adds* — a
+banned word, a stray `.only`, a citation that resolves nowhere — is written as an
+`added-only` declaration: `pre` and `post` are each cut into lines and keyed by the match,
+`onlyIn` keeps what `post` has and `pre` lacks, and `empty` over that difference is the
+verdict. Existing occurrences are forgiven, so adopting the discipline never blocks a legacy
+codebase. `supply: empty` is what lets a file creation (no `pre`) count as all-added and a
+deletion (no `post`) as adding nothing; the `scope` block replaces `in`/`except` with
+regular expressions over the path.
+
+```yaml
+disciplines:
+  - 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: ['^src/', '^test/'] }
+      supply: { pre: 'empty', post: 'empty' }
+      extract:
+        before:
+          - { op: 'source', of: 'pre' }
+          - { op: 'lines' }
+          - { op: 'keyByPattern', re: '(\.only\()' }
+        after:
+          - { op: 'source', of: 'post' }
+          - { op: 'lines' }
+          - { op: 'keyByPattern', re: '(\.only\()' }
+        added:
+          - { op: 'onlyIn', of: 'after', notIn: 'before' }
+      relate:
+        - id: 'nothing-added'
+          relation: { op: 'empty', of: 'added' }
+          message: 'adds {key}: {value}'
+```
+
+The key is the match text, so a line carrying a word the file already has anywhere is
+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. Creating the file, including with empty contents (`post: ''`), passes.
+
+```yaml
+  - id: 'archived-records-stay-frozen'
+    why: 'an archive that can be edited is not an archive.'
+    declare:
+      mechanism: 'self-absolution-ban'
+      scope: { source: 'target.path', include: ['^records/archive/'] }
+      supply: { pre: 'empty', post: 'empty' }
+      extract:
+        prior: [{ op: 'source', of: 'pre' }]
+        here: [{ op: 'source', of: 'target.path' }]
+        after: [{ op: 'source', of: 'post' }]
+        deleted: [{ op: 'onlyIn', of: 'here', notIn: 'after' }]
+        touched: [{ op: 'union', of: ['prior', 'deleted'] }]
+      relate:
+        - { id: 'frozen', relation: { op: 'empty', of: 'touched' }, message: '{value} is frozen' }
+```
+
+**A command line is a source.** On the session surface a shell call carries its command
+line as the fixed source `command`, and a call that changes no file is still one
+observation — it is judged as a world of its own, with subject `-`. A `forbidden-command`
+declaration reads that source, cuts it into lines, keeps the lines a pattern matches, and
+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.
+
+```yaml
+  - id: 'hooks-stay-armed'
+    why: 'a command that disarms or reroutes the git gate is a gate bypass in itself.'
+    declare:
+      mechanism: 'forbidden-command'
+      scope: { source: 'command' }
+      extract:
+        hits:
+          - { op: 'source', of: 'command' }
+          - { op: 'lines' }
+          - { op: 'matches', re: 'LEFTHOOK=(0|false|no|off)\b|core\.hooksPath' }
+      relate:
+        - { id: 'gates-armed', relation: { op: 'empty', of: 'hits' }, message: '{value}' }
+```
+
+**A precedent is a declaration over the session.** Most declarations ask "is this change
+itself bad"; a `precedent` asks whether a required step happened earlier in the session.
+The change is legitimate — what is missing is the procedure in front of it, so what gets
+judged is the session history: `sources: { session: { transcript: true } }` hands the
+declaration the user turns and tool calls as one snapshot, `toolUses` picks the calls,
+`filter` keeps the ones that ran and **succeeded**, `select` reaches the command line, and
+`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.
+
+```yaml
+  - id: 'dependency-needs-npm-view'
+    why: 'a dependency version must be measured before it is written.'
+    declare:
+      mechanism: 'precedent'
+      scope: { source: 'target.path', include: ['^(packages/[^/]+/)?package\.json$'] }
+      sources: { session: { transcript: true } }
+      supply: { session: 'pass' }
+      extract:
+        npmView:
+          - { op: 'source', of: 'session' }
+          - { op: 'toolUses', names: ['Bash'] }
+          - { op: 'filter', when: [{ field: 'succeeded', eq: true }] }
+          - { op: 'select', path: 'args.command' }
+          - { op: 'matches', re: '\bnpm view ' }
+      relate:
+        - { id: 'npm-view', relation: { op: 'nonEmpty', of: 'npmView' }, message: 'no successful npm view precedes this manifest edit' }
+```
+
+A tool call is evidence the same way: `toolUses` without `names`, then `field name` and
+`matches` over the tool's name, or `toolUses` with `subagentType` for a spawn of one agent
+kind. The other history mechanisms read the same snapshot — `phase-order` relates two
+spawn ordinals with `ordered`, `turn-locality` keeps the user turns inside a time window
+(`userTexts → ageMs → filter lte`), and `stated-ground` requires a user turn matching a
+pattern; the last two are usually scoped on `command`, so that only the shell call they
+apply to is judged.
+
+**A caution on line anchors.** A declaration's `lines` step splits the text first, so `^`
+inside `keyByPattern` or `matches` after it is the start of a line. A pattern that stops
+mid-value — say at the first digit of a version — keys `4.0.5` and `4.0.6` alike, so a bump
+adds nothing to an added-only difference and the discipline silently passes: make the
+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.
+
+**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
+block carries the declaration's `scope`, `sources`, `supply`, `extract`, `relate`, and optional
+`witness`; the entry's `id` is the declaration's name, so the block never carries a
+`discipline` key, and `in`/`except`/`when` are refused — the `scope` block is the scope.
+
+```yaml
+  - 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: '^(?!data/)' }
+      relate:
+        - id: 'placed'
+          relation: { op: 'empty', of: 'outside' }
+          message: '{value} is outside data/'
+```
+
+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
+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
+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
+surface reads the file the way it observes the tree — the disk in a session, the index for a
+staged commit, the `<to>` commit for a range — except that a named file the change itself
+touches is read from the change's `post`, so both surfaces judge the same text. A second
+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
+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
+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' }`
+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
+one of the seven fixed sources or one of the declaration's own `sources`; any other key is
+refused. A source the change does not carry is absent, and the declaration's
+`supply` block says what that means: `error` (the default) makes the call unjudgeable —
+recorded `blocked` at either enforce level — `pass` leaves it unjudged, and `empty` reads
+the absent side as an empty item list and judges on. `empty` is what lets an added-only
+declaration see a creation as all-added and a deletion as adding nothing; it does not apply
+to `state`, the paired source. A declaration comparing before with after therefore needs
+`supply: { state: pass }` to let a file creation through.
+
+A break is recorded like any other family's, with one addition: the telemetry row carries a
+fifth field naming the elements the relation failed on (at most eight per relate entry, with
+the true count beside them). A `skipped` row uses the same field for a reason token instead —
+`no-observation` (the surface has no channel for what the entry reads), `config-fault` (the
+block could not be assembled), or `supply-pass` (the declaration's own `supply: pass` let an
+absent source through). Every declaration also names its `mechanism` — one of eighteen
+catalogue names such as `naming`, `companion`, or `pairing` — and the validator refuses a
+name whose shape the declaration does not match: the axes its sources derive (`change` for
+the fixed names other than `actor`, `actor` for `actor`, `world` for a `file` or `sidecar`
+source, `history` for a `transcript` source) and the relations it relates must fall inside
+what that name admits. A block the compiler cannot resolve — a step name outside the
+registry, an argument outside a step's keys — becomes a skip registration that names its
+location on stderr and routes nothing. A shell write into the declaration's scope whose
+result the judge can compute (a redirect, a heredoc, an append) is judged as the file change
+it makes; one it cannot compute (`sed -i`, an opaque command) records `skipped`. The
+declaration's own `witness` block joins the
+human's witness as a second way to open a blocked verdict.
+
+Adding a discipline is a data edit — no code, no plumbing. Custom judge bodies remain the
+escape layer for the few rules data cannot express.

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

@@ -0,0 +1,83 @@
+# `@polydeukes/adapter-claude-code`
+
+[English](adapter-claude-code.md) · **한국어**
+
+> **세션 표면의 번역기**입니다. PreToolUse 페이로드가 약속(covenant) 입력 IR이 되고,
+> 판정기가 읽는 파일 변경 증거와 대화 기록(transcript) 통로가 함께 실립니다.
+>
+> 알파입니다. 통합 패키지의 의존성으로 설치되므로 일반 사용자가 따로 설치하거나 불러올 필요는 없습니다. 세션 표면은
+> [`polydeukes/claude-code`](polydeukes.ko.md#session-export)를 통해 닿습니다.
+
+<a id="ownership"></a>
+## 담당하는 기능
+
+Claude Code의 입력을 공통 형식으로 번역합니다. 에이전트와 도구의 구체적인 이름은 이 패키지에서 처리하고 코어에는 넣지 않습니다. 코어가 특정 에이전트에 의존하지 않는다는
+제약은 테스트로 확인합니다.
+
+| 단위 | 하는 일 |
+|---|---|
+| 페이로드 상향 번역 | 원본 PreToolUse 페이로드가 `CovenantInput`이 됩니다 |
+| 예상 변경 후 상태 | 편집이 적용되면 파일이 무엇을 담을지 디스크를 건드리지 않고 계산합니다 |
+| 파일 변경 증거 | 디스크의 변경 전 상태와 예상 변경 후 상태를 짝지어 변경 증거를 만듭니다 |
+| 대화 기록(transcript) 제공자 | 세션 JSONL 파일을 `CanonicalTranscript`로 바꿉니다 |
+| 텔레메트리 배선 | 전체 처리 경로에서 호출이 기록되도록 연결합니다 |
+
+이 패키지는 약속(covenant) 패키지를 결코 불러오지 않습니다. 판정 전달 함수는 통합 패키지가
+**주입**하고, 그래서 의존은 코어를 통해 한 방향으로만 흐릅니다. `@polydeukes/core`는
+`peerDependency`로 부릅니다. 판정기와 같은 어휘를 공유하며 별도 사본을 설치하지 않습니다.
+
+<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` 서브패스를 통해 이 어댑터를 불러옵니다. 패키지를 갱신하면 실행할 구현도 바뀌지만 훅 파일은 그대로입니다.
+
+일반 사용자가 직접 불러올 필요는 없으며 별도 설정 네임스페이스도 없습니다.
+
+<a id="limits"></a>
+## 선언된 한계
+
+- **자식 프로세스의 쓰기는 관측 밖입니다.** 이 표면이 판정하는 것은 **선언된 도구
+  호출**입니다. 프로세스를 띄우고 그 프로세스가 파일을 쓰는 명령은, 테스트 러너든 빌드든,
+  명령에 대해 판정되지 자식이 한 일에 대해 판정되지 않습니다. 추적되는 파일에 대해서는
+  커밋 표면에서 결과를 별도로 관측할 수 있습니다.
+- **증거는 후상태를 계산할 수 있는 곳에만 있습니다.** 변형 도구 넷이 전부 증거를 내고
+  노트북도 그렇습니다. `NotebookEdit`는 셀 단위 `modify` 증거를 냅니다. 증거가 없는 것은
+  이 어댑터가 해소하지 못하는 페이로드입니다. 읽을 수 없거나 파싱되지 않는 노트북, 이름을
+  붙일 수 없는 셀, 알지 못하는 편집 모드가 그렇습니다.
+- **증거 없는 호출은 보수적으로 판정합니다.** 증명된 대상이 없으므로 호출 인자에 보호
+  경로가 언급됐는지 대조합니다.
+- **저장소 밖 조상은 범위 밖입니다.** 프로젝트 루트 위의 경로는 여기서 관측하지 않습니다.
+  그 범위는 에이전트 실행 환경의 권한 정책으로 제한해야 합니다.

package/dist/docs/reference/{adapter-claude-code.md → packages/adapter-claude-code.md}

@@ -1,14 +1,15 @@
 # `@polydeukes/adapter-claude-code`
 
-**English** · [한국어](./adapter-claude-code.ko.md)
+**English** · [한국어](adapter-claude-code.ko.md)
 
 > **The session surface's translator** — PreToolUse payloads become the covenant input IR,
 > with the file-change evidence and the transcript channel the judge reads.
 >
 > Alpha. A transitive dependency of the umbrella: you do not install it and you do not
 > import it. The session surface reaches it through
-> [`polydeukes/claude-code`](./polydeukes.md#subpaths).
+> [`polydeukes/claude-code`](polydeukes.md#session-export).
 
+<a id="ownership"></a>
 ## What this package owns
 
 The boundary where Claude Code's vocabulary is translated away. Agent and tool literals
@@ -21,12 +22,14 @@ agent-neutrality a claim a test can check rather than a slogan.
 | Virtual post-state | Computes what a file *would* contain after an edit applies, without touching disk |
 | File-change evidence | Pairs the disk pre-state with the virtual post-state into union evidence |
 | Transcript provider | Turns a session JSONL file into a `CanonicalTranscript` |
-| Precedent evaluator | This adapter's own evidence vocabulary for the context family |
 | Telemetry wiring | Drives the full funnel so exactly one row lands per call |
 
 This package never imports the covenant package. The dispatch seam is *injected* by the
-umbrella, which keeps dependencies one-way, through the core alone.
+umbrella, which keeps dependencies one-way, through the core alone. It names
+`@polydeukes/core` as a `peerDependency`: the vocabulary is shared with the judge, not
+installed a second time here.
 
+<a id="translation"></a>
 ## Payload translation and the three axes
 
 **Three axes reach the judge**, and they differ in what evidence they can carry.
@@ -39,7 +42,9 @@ umbrella, which keeps dependencies one-way, through the core alone.
 
 Translation is fail-closed at every step. A `Task` call carrying a subagent type maps to a
 spawn; a payload that cannot be classified is a translation *failure* that logs one
-`blocked` record and exits `2`, rather than degrading into a guess.
+`blocked` record and exits `2`, rather than degrading into a guess. The envelope's top-level
+`agent_type` becomes the IR's `actor` — `{ agentType }` inside a subagent, `{}` otherwise;
+`tool_input` is never read for it, since that is the agent's own text.
 
 **Evidence is computed, never read back.** The virtual post-state applies `Edit`, `Write`,
 and `MultiEdit` in memory — sequential multi-edit application included — so a content-aware
@@ -53,19 +58,20 @@ witness valve human-only: an AI cannot synthesize its own witness. A read failur
 judged, an unreadable one is no evidence channel at all and is skipped. Either way the
 valve turns off, never open.
 
-**The precedent evaluator judges two keys.** `subagent` is exact spawn-kind equality, since
-a kind is a value rather than a pattern; `tool` matches observed tool names as a regular
-expression. Any key outside this vocabulary returns `undefined` — the handshake that tells
-the compiler the evidence is unjudgeable, so the entry skips instead of judging on a guess.
+**Precedent is a declaration, not an adapter evaluator.** This adapter supplies the
+transcript snapshot. The declaration engine extracts succeeded `toolUses` and matches them;
+there is no separate precedent evaluator in this package. The grammar is in
+[Configuration — disciplines](../configuration/index.md#disciplines).
 
+<a id="consumer-contract"></a>
 ## Where the consumer touches it
 
 - **The generated hook**, which loads this adapter through the umbrella's `claude-code`
   subpath. Upgrading the package upgrades what runs; the hook file itself never changes.
-- **`requirePrecedent` entries** using the `subagent` or `tool` evidence keys.
 
 No import, and no configuration namespace of its own.
 
+<a id="limits"></a>
 ## Declared limits
 
 - **A child process's writes are outside observation.** This surface judges *declared tool