polydeukes 0.3.0 → 0.5.0

package/dist/docs/reference/configuration.md

@@ -0,0 +1,338 @@
+# Configuration reference
+
+**English** · [한국어](./configuration.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
+discipline fires is its
+[What enforcement looks like](../configuration.md#what-enforcement-looks-like) section.
+
+## `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.
+
+## `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.
+
+## `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'
+```
+
+### `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
+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.
+
+**Context-family disciplines skip on the commit surface.** A commit has no session to look
+at, so a `requirePrecedent` entry cannot be judged there — demanding evidence a commit
+cannot carry would block every matching commit with no legitimate way through.
+
+They are not filtered out, though. They assemble like any other discipline and become
+*skip registrations*: routing intact, no judge body. When one matches a staged change it
+records a `skipped` telemetry event 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**, so a commit
+touching nothing the entry cares about records nothing at all.
+
+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.
+
+## `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.
+
+## `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.
+
+## `disciplines`
+
+Optional. Each entry is one discipline: a practice the team imposes on itself, declared as
+data. An entry carries exactly **one** predicate (zero or two is rejected), an `id` (the
+telemetry label), and optionally a `why` (the reason, which travels with the block message
+the agent reads) plus, on a `forbid` or `requirePrecedent` entry, `in` (the file globs it
+judges) and `except` (globs carved out of that scope).
+
+**`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: 'bilingual-docs-sync'
+    why: 'en and ko doc mirrors must move together.'
+    draft: true
+```
+
+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: 'no-console-log'
+    why: 'console output belongs to the logger; measure the habit before blocking it.'
+    forbid: 'console\.log\('
+    enforce: advise
+```
+
+**`forbid` — content delta.** Blocks an edit that *adds* a new match of the pattern.
+Existing occurrences are forgiven: adopting a discipline never blocks a legacy codebase,
+because the judgment direction is "what did this edit add", not "what does the file
+contain".
+
+```yaml
+disciplines:
+  - id: 'covenant-vocabulary'
+    why: 'control-framing vocabulary is banned in package sources.'
+    in:
+      - 'packages/*/src/**'
+    forbid: '\b(guard|harness|kb)\b'
+```
+
+**`immutable` — path family.** Blocks modification of existing files that match; creating
+new files is allowed.
+
+```yaml
+  - id: 'archived-records-stay-frozen'
+    why: 'an archive that can be edited is not an archive.'
+    immutable: 'records/archive/**'
+```
+
+**`forbidCommand` — command family.** Blocks shell commands matching the pattern, even
+when the command mentions no protected path. This is how gate-disarming commands are
+caught. A multi-line command is judged twice over — the pattern is tested against each
+line and against the whole string, so `^` means the start of a line while a pattern
+spanning a line boundary still matches (the whole-content caution further down applies
+to the delta and context families). An empty pattern is rejected at load time, here and
+on `forbid` alike — it would match every command.
+
+```yaml
+  - id: 'hooks-stay-armed'
+    why: 'a command that disarms or reroutes the git gate is a gate bypass in itself.'
+    forbidCommand: 'LEFTHOOK=(0|false|no|off)\b|core\.hooksPath'
+```
+
+**`requirePrecedent` — context family.** Blocks a change that arrives without a required
+step having happened earlier in the session. The other three families all ask "is this
+change itself bad"; this one asks something else. The change is legitimate — what is
+missing is the procedure in front of it, so what gets judged is not the mutation but the
+session history.
+
+Evidence means an **execution**, not a request. A call the covenant blocked, one a human
+refused, and one that simply failed all leave the same trace in a session, and none of
+them is precedent — the transcript is read for what actually ran and reported success.
+That is what keeps the cheapest way through the gate being the thing the discipline
+asks for.
+
+Two consequences are worth knowing before you write one. The outcome is read per command
+LINE, so a chain where the required command ran but a later step failed does not count.
+And the pattern is matched at the start of a simple command, so the same words in an
+argument or a comment do not count either. **In both cases running the command on its own
+opens the gate** — the block message says so.
+
+```yaml
+  - id: 'dependency-needs-npm-view'
+    why: 'a dependency version must be measured before it is written.'
+    in:
+      - 'package.json'
+      - 'packages/*/package.json'
+    when: '(^|\n)\s*"[^"]+"\s*:\s*"[~^]?\d[^"]*"'
+    requirePrecedent:
+      command: 'npm view '
+```
+
+The evidence vocabulary is layered. `command` is the core's own key — a shell call is a surface
+every agent shares — and the core validates it fully, rejecting an empty string or a pattern that
+does not compile. It is matched **at the start of a simple command**, not anywhere in the command
+line, so `echo "npm view yaml"` and a mention parked behind a `#` are not evidence while `cd pkg &&
+npm view yaml` is. Every other key belongs to an adapter: the core checks the container only (a flat
+object carrying exactly one evidence key) and passes the value through verbatim, and the adapter
+that owns the word validates and judges it. The Claude Code adapter brings two: `subagent` (exact
+match on a spawn kind) and `tool` (a regex over tool names) — so "query the docs tool before
+touching this" is expressible today. Both follow the same execution rule as `command`. An evidence
+key no assembled adapter recognizes cannot be judged, so the entry compiles to a skip registration:
+routing stays, the body is dropped, assembly names the fault once on stderr, and every matching
+change afterwards records `skipped` rather than a verdict. A typo therefore never passes itself off
+as adapter vocabulary — but it does leave the discipline inert, and the `skipped` rows are where
+that shows.
+
+`when` (optional) is the trigger: an added-direction delta regex, combinable with
+`requirePrecedent` and with nothing else. When it is absent, every change inside `in`
+scope triggers the discipline. The two keys divide the work — `in` says which files are
+watched, `when` says which change in them demands the precedent.
+
+**A caution on line anchors.** These patterns are matched against the file's whole content
+as a single string, and the config schema takes a regex string with no flags. `^` therefore
+anchors to the start of the *file*, not the start of a line, so a line-shaped pattern
+written with `^` matches only the first line and the discipline silently stops firing —
+the regex still compiles, the judgment still runs, and the verdict is `passed`. Write
+`(^|\n)` when you mean the start of a line. This is why the example above carries
+`(^|\n)\s*"[^"]+"…` rather than `^\s*"[^"]+"…`.
+
+**And a caution on match length.** The delta keys on the matched *text*: a change is only
+seen as added when the matched string itself differs between the file's before and after.
+A pattern that stops mid-value — say at the first digit of a version — produces the same
+match text for `4.0.5` and `4.0.6`, so a version bump adds nothing to the delta and the
+discipline silently passes. Make the pattern span the whole value that can change; the
+example above runs through the closing quote (`\d[^"]*"`) for exactly this reason. Both
+failure shapes are the same class: the regex compiles, the verdict says `passed`, and
+nothing tells you the discipline is inert — so when you add an entry, measure it against
+a real file and a realistic edit, not a one-line snippet.
+
+The kind of change matters at the trigger. With `when` present, a deletion never triggers
+— deleting adds no content. With `when` absent, deletion triggers like any other change in
+scope, since the declared scope is the whole mutation.
+
+**The cheap way through is the honest one.** Unlike the witness, this 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 call the tool, and that is exactly the behaviour the
+discipline exists to induce.
+
+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/core.md

@@ -29,8 +29,10 @@ can check. Every other package depends on this one; this one depends on none of
 
 ## The judged protocol
 
-This is the contract the shipped judge bodies speak: a body reads a `CovenantInput` from
-stdin and answers with an exit code. Every row in `.polydeukes/roi.log` traces back to one
+This is the contract the shipped judges speak: a judge receives a `CovenantInput` — parsed
+once from the stdin-JSON payload the surface hands the dispatcher — and answers with a
+verdict the wrapper translates into an exit code. Every row in `.polydeukes/roi.log` traces
+back to one
 of these verdicts, so this vocabulary is what a blocked row is written in.
 
 ```ts
@@ -83,10 +85,10 @@ attribution. Calls without evidence are skipped, never substituted for.
 Three places, all of them indirect.
 
 - **The config file.** Its schema is defined here. The vocabulary reference is
-  [configuration.md](../configuration.md).
-- **The JSON Schema artifact** — `@polydeukes/core/schema.json`, an exports subpath. Under
-  a default pnpm layout it does not resolve from a consumer's top-level `node_modules`,
-  because the core arrives as a transitive dependency; the working spellings are in
+  [the configuration reference](./configuration.md).
+- **The JSON Schema artifact** — `@polydeukes/core/schema.json`, an exports subpath, for a
+  project that installs this package directly. A consumer of the umbrella names the copy
+  bundled there instead; both spellings are in
   [configuration.md's IDE section](../configuration.md#ide-support).
 - **The protocol above** — reading a `blocked` row means reading the vocabulary a body
   answered in.

package/dist/docs/reference/covenant.md

@@ -37,7 +37,7 @@ determines whether it can be judged on a given surface.
 
 `when` is a trigger, not a family: it narrows a `requirePrecedent` entry and combines with
 nothing else. The writing guide for these entries — the four predicate forms, the two
-pitfalls — is [configuration.md's `disciplines` section](../configuration.md#disciplines-optional).
+pitfalls — is [the configuration reference's `disciplines` section](./configuration.md#disciplines).
 
 **Three meta-covenants** protect the judging chain. They are covenants like any other; the
 vocabulary below applies to them unchanged.
@@ -48,9 +48,9 @@ vocabulary below applies to them unchanged.
 | shell-mod | Shell | The same, through a command line. A command mentioning a protected path passes only if its leading word proves it read-only |
 | transcript-mod | Transcript | Writes to the live session transcript, judged by whole-path **equality** — never as a protected ancestor |
 
-**Five verdict words** are the telemetry contract. A row in `.polydeukes/roi.log` carries
-exactly one of them, and the CLI, the docs, and the tests use the same word for the same
-event. How to read a row is in
+**Six words** are the telemetry contract — five verdicts and one observation. A row in
+`.polydeukes/roi.log` carries exactly one of them, and the CLI, the docs, and the tests use
+the same word for the same event. How to read a row is in
 [troubleshooting](../troubleshooting.md#reading-a-verdict).
 
 | Verdict | Means |
@@ -58,8 +58,16 @@ event. How to read a row is in
 | `passed` | The call was judged and upheld the covenant |
 | `blocked` | The call was judged and broke it |
 | `witnessed` | A **blocked** verdict a human opened in person. Never silent, never a clean call |
-| `advised` | The commit surface at `enforce: advise` recorded a break without stopping it |
+| `advised` | A break recorded without stopping the call — the default for every discipline entry on both surfaces, and the commit surface's outcome under `adapters.git.enforce: advise` |
 | `skipped` | The call reached a registration that could not judge it. **Not a pass** — the recorded absence of a judgment |
+| `unattributed` | A protected entry's on-disk state moved and no judgment row explains it. **Not a verdict** — no call is blocked or passed by it; the session surface writes it after comparing state against a stored baseline |
+
+`unattributed` answers a question the other five cannot. They are all written by a judge
+about a call it was handed, so a write that arrives without a declared call — through an
+interpreter, a test runner's child process, a script that assembles the path from its own
+arguments — leaves no row at all. The comparison observes the result rather than the
+spelling, so it records that write after the fact. It never blocks: the write already
+happened, and the comparison fails open on both sides of the verdict.
 
 ## Where the consumer touches it
 

package/dist/docs/reference/polydeukes.md

@@ -21,23 +21,39 @@ you do not install and do not import.
 
 ## Subcommands
 
-The bin is `pdks`, with `polydeukes` as an alias. There are no flags and no options
-anywhere: two subcommands take an exact two-word form, and `docs` takes an optional topic.
+The bin is `pdks`, with `polydeukes` as an alias. Every argument form is matched against a
+finite table: `covenant check` takes an optional domain flag, `init claude-code` is exact,
+`explain` takes one word, and `docs` takes an optional topic.
 
 ### `pdks covenant check`
 
-The commit-surface judgment runner, invoked from a pre-commit hook. It discovers the config
-at the working directory, collects the staging area through the git adapter, translates it
-into the covenant input IR, and dispatches it through the same judge bodies the session hook
-spawns.
+`pdks covenant check [--worktree | --range <base>..<head>]` — the commit-surface judgment
+runner. It discovers the config at the working directory,
+collects one observation of the repository through the git adapter, translates it into the
+covenant input IR, and dispatches it through the same in-process judges the session hook calls.
+Which observation is the domain flag's choice — the same violation receives the same verdict
+in all three:
+
+| Form | Domain | `pre` → `post` |
+|---|---|---|
+| `pdks covenant check` | The staging area — what a pre-commit hook judges | HEAD blob → staged blob |
+| `pdks covenant check --worktree` | The working tree, untracked (non-ignored) files included | HEAD blob → bytes on disk |
+| `pdks covenant check --range <base>..<head>` | Two refs; `<base>...<head>` reads from their merge-base, the PR reading | base blob → head blob |
+
+`--worktree` and `--range` are diagnostic calls — run them after a task, before a PR, or in
+CI. Only the staged form is a gate, so only it can prompt for the witness token; the other
+two report exit `2` without a prompt, since there is no commit for a human to open.
 
 | Situation | Result |
 |---|---|
-| Staged changes break nothing | exit `0` |
+| The domain's changes break nothing | exit `0` |
 | A staged change breaks a covenant, `enforce: block`, config has a `witness` block | Prompts once on `/dev/tty` for the witness token; an unanswered or wrong answer exits `2` |
 | The same, with no `witness` block in the config | exit `2` with no prompt — the valve is built from that block, so without it nothing can open a block |
-| A staged change breaks a covenant, `enforce: advise` | One advisory line on stderr, exit `0`, recorded `advised` |
-| Empty staging area | exit `0` — an explicit pass, not a skipped run |
+| A worktree or range change breaks a covenant, `enforce: block` | exit `2`, never a prompt |
+| A change breaks a covenant, `enforce: advise` | One advisory line on stderr, exit `0`, recorded `advised` |
+| Empty domain (nothing staged, a clean tree, identical refs) | exit `0` — an explicit pass, not a skipped run |
+| A range naming a ref git cannot resolve, or two refs with no merge-base | exit `2`, one `blocked` row |
+| `--range` without an argument, an argument without `..`, both flags at once, or an unknown flag | The usage line on stderr, exit `2` |
 | No config, more than one config, or an invalid one | exit `2` |
 | A judge body that cannot be loaded | exit `2` |
 
@@ -48,7 +64,7 @@ permanent condition of the commit surface, not a fault.
 ### `pdks init claude-code`
 
 The session-surface installer. It proves that `polydeukes` resolves from the directory it
-was invoked in **before writing anything**, then creates five artifacts:
+was invoked in **before writing anything**, then creates six artifacts:
 
 | Artifact | Kind |
 |---|---|
@@ -56,6 +72,7 @@ was invoked in **before writing anything**, then creates five artifacts:
 | `.claude/settings.json` | Merged — the PreToolUse registration is added to whatever the file already carries |
 | `polydeukes.config.yaml` | Created — the starter policy, with a placeholder `languages` block |
 | `.claude/rules/polydeukes.md` | Created — tells the AI partner to ask [`pdks docs`](#pdks-docs-topic) instead of searching the web |
+| `.claude/skills/discipline-draft/SKILL.md` | Created — the classification procedure: a described problem becomes a config entry (judged at advise, or `draft: true`), and advised rows are consulted in the telemetry log |
 | `.gitignore` | Appended — one line for `.polydeukes/` |
 
 Nothing existing is overwritten: an artifact already present is reported as skipped and left
@@ -78,10 +95,10 @@ package, so the answer comes from the installed version rather than from the net
 | Topic | Answers from |
 |---|---|
 | `install` | [installation](../installation.md), in full |
-| `config` | [configuration](../configuration.md) — the Reference section |
-| `discipline` | [configuration](../configuration.md) — the `disciplines` section |
+| `config` | [the configuration reference](./configuration.md), in full |
+| `discipline` | [the configuration reference](./configuration.md) — the `disciplines` section |
 | `covenant` | [configuration](../configuration.md) — What enforcement looks like |
-| `witness` | [configuration](../configuration.md)'s `witness` section, then [troubleshooting](../troubleshooting.md)'s valve section |
+| `witness` | [the configuration reference](./configuration.md)'s `witness` section, then [troubleshooting](../troubleshooting.md)'s valve section |
 
 **Every failure leaves stdout at zero bytes.** A missing bundled document, a heading the
 document no longer carries, an unknown topic — each names what was missing on stderr and
@@ -96,11 +113,59 @@ the package.
 `pdks init claude-code` writes a discovery file that points an AI partner at this
 subcommand; see the artifact table above.
 
+### `pdks explain`
+
+The assembly reader. It loads the config at the working directory, assembles both surfaces'
+registration sets through the same functions the two judgment runners use, and prints them
+without judging — no judge thunk is called, no telemetry row is written, no transcript is
+read.
+
+```text
+pdks explain — polydeukes.config.yaml
+
+surface: session (claude-code hook)
+  registrations 23 · judged 11 · skip 9 · meta 3 · excluded 0 · draft 1
+  meta     self-mod                 paths 13 (common; includes the config file itself)
+  judge    covenant-vocabulary      forbid · in packages/*/src/** · except … · why ✓
+  skip     covenant-vocabulary      a shell write in scope whose result this layer cannot compute
+  draft    bilingual-docs-sync      unpromoted — no judgment
+  ...
+surface: commit (git pre-commit) · enforce: advise
+  registrations 10 · judged 3 · skip 6 · meta 1 · excluded 3 · draft 1
+  skip     manifest-needs-npm-view  no session transcript to read
+  excluded hooks-stay-armed         forbidCommand — no shell axis on this surface
+  draft    bilingual-docs-sync      unpromoted — no judgment
+```
+
+One line per registration, in the order the surface dispatches them. The kind column has
+five words: `meta` (the registrations protecting the judging chain — `self-mod`,
+`shell-mod`, and on the session surface `transcript-mod`), `judge` (an entry with a judge
+body, with its family, routing scope, and whether it carries a `why`), `skip` (a registration
+that records `skipped` instead of judging, with the reason the compiler gave — the reason
+that otherwise reaches stderr only on a config fault), `excluded` (a `forbidCommand`
+entry on the commit surface, which has no shell axis), and `draft` (an unpromoted
+`draft: true` entry, shown on both surfaces since it belongs to neither). `registrations`
+counts the first three; `excluded` and `draft` are tallied apart because neither ever
+becomes a registration.
+The commit surface's header also names its `adapters.git.enforce` level, since an advising
+surface records the same table but blocks nothing.
+
+The session surface is rendered as the hook sees it under a normal payload — with a
+transcript present — so `transcript-mod` and the context family appear as they do in a
+session; the commit surface shows the context family as skips, which is that surface's
+permanent condition.
+
+| Call | Result |
+|---|---|
+| `pdks explain` | Both surfaces on stdout, exit `0` |
+| `pdks explain <anything>` | The usage line on stderr, exit `2` |
+| no config, two configs, or an invalid one | `pdks explain: <reason>` on stderr, stdout at zero bytes, exit `2` |
+
 ### Any other argument form
 
-Anything that is not one of these forms writes
-`usage: pdks covenant check | pdks init claude-code | pdks docs [topic]` to stderr and
-exits `2`.
+Anything that is not one of these forms writes the usage line —
+`usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain |
+pdks init claude-code | pdks docs [topic]` — to stderr and exits `2`.
 
 ## Exit codes
 
@@ -109,16 +174,16 @@ Three codes exist, and they live at two layers. **What a consumer's hook observe
 
 | Code | Constant | Emitted by | Means |
 |---|---|---|---|
-| `0` | `EXIT_UPHOLD` | Judge body, wrapper, bin | The promise was upheld — the call or commit proceeds |
-| `1` | `EXIT_BREAK_NON_BLOCKING` | Judge body only | A break reported as a signal. The wrapper translates it — into `2` under `enforce: block`, into `0` + an `advised` row under `advise`. It never reaches the surface either way |
+| `0` | `EXIT_UPHOLD` | Judge outcome, wrapper, bin | The promise was upheld — the call or commit proceeds |
+| `1` | `EXIT_BREAK_NON_BLOCKING` | Judge outcome only | A break reported as a signal. The wrapper translates it — into `2` under `enforce: block`, into `0` + an `advised` row under `advise`. It never reaches the surface either way |
 | `2` | `EXIT_BREAK_BLOCKING` | Wrapper, bin, fail-closed paths | The call or commit is refused |
 
-The asymmetry is the protocol's responsibility boundary. A covenant body decides *whether* a
-promise was broken and says so with `0` or `1`; deciding what a break *costs* belongs to the
-wrapper, and that is the one place `enforce` is read. A body can therefore be run, tested, and
-reasoned about without knowing whether the surface it runs under blocks or advises. Only the
-verdict relaxes: every unjudgeable outcome — a body exit of `2` or higher, a signal death —
-stays `2` at either level.
+The asymmetry is the protocol's responsibility boundary. A judge decides *whether* a
+promise was broken and answers `0` or `1` in its outcome; deciding what a break *costs* belongs
+to the wrapper, and that is the one place `enforce` is read. A judge can therefore be run,
+tested, and reasoned about without knowing whether the surface it runs under blocks or advises.
+Only the verdict relaxes: every unjudgeable outcome — an outcome of `2` or higher, a throw
+from the judge — stays `2` at either level.
 
 **Everything unjudgeable resolves to `2`.** A missing config, an invalid one, an
 unparseable payload, a judge body that was never built — each fails closed. The one
@@ -156,15 +221,22 @@ a silently unprotected project.
 function runCovenantCheck(spec: CovenantCheckSpec): Promise<{ exitCode: 0 | 2 }>;
 
 type CovenantCheckSpec = {
-  repoRoot: string;                                  // config discovery and staged collection anchor here
+  repoRoot: string;                                  // config discovery and collection anchor here
   telemetryPath?: string;                            // overrides the config's log path
   covenantDist?: string;                             // overrides the resolved judge directory
   ttyPrompt?: (prompt: string) => string | null;     // the TTY valve seam
+  domain?: CheckDomain;                              // which observation to judge; absent = staged
 };
+
+type CheckDomain =
+  | { kind: 'staged' }
+  | { kind: 'worktree' }
+  | { kind: 'range'; base: string; head: string; ancestry?: 'merge-base' };
 ```
 
 The commit surface's composition root — what [`pdks covenant
-check`](#pdks-covenant-check) runs.
+check`](#pdks-covenant-check) runs. `ancestry: 'merge-base'` is the `<base>...<head>`
+reading; the adapter resolves the merge-base.
 
 `ttyPrompt` absent means a non-TTY environment, and the valve then has no way to open — an
 agent-spawned commit and a CI run reach the same state. The valve is a human at a terminal
@@ -203,8 +275,13 @@ needs no second dependency.
 |---|---|
 | `polydeukes` | The barrel — `loadConfig`, `runCovenantCheck`, `runClaudeCodeHook`, their spec types, `ResolvedConfig` |
 | `polydeukes/claude-code` | `runClaudeCodeHook` and `ClaudeCodeHookSpec` alone |
+| `polydeukes/schema.json` | The config JSON Schema, copied from the core at build time |
 
 The generated hook delegator imports the subpath, not the barrel. ESM imports are eager, so
 importing the barrel would load the commit-surface runner — and the git adapter behind it —
 on every session tool call that will never use them. The subpath is the session surface's
 own entry point, and the barrel is for programmatic consumers.
+
+`polydeukes/schema.json` is for code that reads the schema. A `$schema` line names the file
+path instead — an editor reads that string statically, so no module resolver runs on it. Both
+spellings are in [configuration.md's IDE section](../configuration.md#ide-support).

package/dist/docs/troubleshooting.md

@@ -6,6 +6,9 @@
 > proceed, and four things worth knowing when a judgment surprises you. Each entry is
 > symptom → cause → recovery.
 
+This is the guide layer for recovery: the fail-closed states, reading verdicts, and the
+witness valve.
+
 The one principle behind half of this page: **a gate that cannot judge blocks rather than
 guesses.** A missing config, an ambiguous config, an invalid config, an installer that
 cannot prove resolution, and a judge that cannot be loaded all fail closed, because a dead
@@ -92,7 +95,7 @@ resolves again.
 one record to the telemetry log (`.polydeukes/roi.log` by default, `telemetry.logPath` to
 move it).
 
-**Recovery.** Read the last lines and the five-word vocabulary:
+**Recovery.** Read the last lines and the six-word vocabulary:
 
 | Word | Means |
 |---|---|
@@ -101,6 +104,11 @@ move it).
 | `witnessed` | A blocked verdict a human opened in person. Never silent. |
 | `advised` | Commit surface at `advise` level: a break recorded without stopping the commit. |
 | `skipped` | A registration matched but could not judge — **the recorded absence of a judgment, not a pass.** |
+| `unattributed` | A protected entry changed on disk and no judgment explains it — **an observation, not a verdict.** Nothing was blocked; the write already happened. |
+
+An `unattributed` row names the entry, not the file inside it. Rebuilding a protected `dist`
+without a judged call producing one is expected — it says a write reached that entry outside
+the session's view, which is exactly what the row is for.
 
 ## Opening a blocked call — the witness
 
@@ -145,7 +153,9 @@ assembles as a skip registration: routing intact, no judge body. When its scope
 staged change it records `skipped` with the entry's id and proceeds.
 
 **Recovery.** None needed — this is a declared condition of the surface, not a defect. The
-row is the point: a gate that did nothing says so in the data. A context-family entry is
+row is the point: a gate that did nothing says so in the data. `pdks explain` shows the
+same fact before any commit: every context entry appears under the commit surface as a
+`skip` line carrying the reason. A context-family entry is
 really a session-surface tool — on a project that wires only the commit surface, such an
 entry only ever buys telemetry, so declare it where an AI partner's session exists to be
 judged. The row appears only when the entry's scope actually matched, so an unrelated