polydeukes 0.0.1 → 0.4.0

package/dist/docs/reference/adapter-git.md

@@ -0,0 +1,87 @@
+# `@polydeukes/adapter-git`
+
+**English** · [한국어](./adapter-git.ko.md)
+
+> **The commit surface's translator** — a staged diff becomes the covenant input IR, and
+> the `adapters.git` config namespace is defined here.
+>
+> Alpha. A transitive dependency of the umbrella: you do not install it and you do not
+> import it. The commit surface reaches it through
+> [`pdks covenant check`](./polydeukes.md#pdks-covenant-check).
+
+## What this package owns
+
+The boundary where git's vocabulary is translated away. A staged diff becomes the same
+agent-neutral input IR the session surface produces — the same judgment for every hand,
+AI or human.
+
+| Unit | What it does |
+|---|---|
+| Staged-change collection | Reads the staging area into a list of changes with their content baselines |
+| Pure translation | Folds those changes into one `CovenantInput` |
+| Settings vocabulary | Validates this adapter's own config namespace |
+
+This is a pure library. It knows the staged-diff shape and nothing about installation, hook
+runners, or valves — wiring it into a pre-commit hook is a deployment act that lives in the
+umbrella.
+
+## Staged collection and the `adapters.git` namespace
+
+**Collection is deliberately narrow about what it trusts.**
+
+| Decision | Why |
+|---|---|
+| `--no-renames` forced on | A rename is judged as a deletion plus an addition. A `git mv` of a protected file must not slip through as one opaque rename entry |
+| `pre` from the HEAD blob, `post` from the **staged** blob | Never the worktree, which may have diverged after `git add` |
+| A binary blob yields null content | Rather than lossily decoded bytes |
+| The unborn first commit narrows to all-added | Rather than throwing |
+
+Translation produces one tool call per change, under the adapter-owned names `staged-write`
+and `staged-delete`. A deletion always carries its evidence. A write carries it unless the
+staged blob was binary — there is no text to compare, so the call arrives with no
+`fileChange` at all and is judged on its path alone, the same as any unproven call.
+**The session collections are honestly empty** — the commit surface has no session, and a
+key is never fabricated to look like one.
+
+**The namespace is this adapter's own vocabulary.** The core validates only the container
+shape — one settings object per adapter — and passes the contents through verbatim, so the
+vocabulary, its validator, and its defaults all live here.
+
+| Key | Values | Default | Means |
+|---|---|---|---|
+| `adapters.git.enforce` | `block` \| `advise` | `block` | What a commit-surface verdict *does* |
+| `adapters.git.protectedPaths` | string[] | `[]` | The commit surface's **additive** protection scope, judged on top of the common list |
+
+An unknown key, an `enforce` outside the two values, or a `protectedPaths` that is not an
+array of strings each fail fast with the full field path. The writing reference is
+[the configuration reference's `adapters` section](./configuration.md#adapters).
+
+**The additive scope is additive for a reason.** The level belongs to the observer, and so
+does the scope: entries listed here are judged when work becomes history, and the session
+surface never reads them. That is what lets a repository leave judge *sources* editable in
+a session while still stopping the commit that promotes them.
+
+Under `enforce: advise` the valve is structurally absent: a verdict is recorded as
+`advised`, one advisory line lands on stderr, and the commit proceeds. Only the verdict is
+relaxed — a run that cannot judge still fails closed at exit `2` at either level.
+
+## Where the consumer touches it
+
+- **The `adapters.git` block** in your config.
+- **The pre-commit hook** that runs `pdks covenant check`, wired by hand — the manual
+  procedure for three hook managers is in
+  [installation](../installation.md#the-commit-surface--developing-by-yourself).
+
+No import.
+
+## Declared limits
+
+- **The context family cannot be judged here.** `requirePrecedent` needs session history
+  and a commit has none, so a matching entry records `skipped`. A permanent condition of
+  this surface, not a fault in the entry.
+- **A commit never shows a gitignored file.** Anything outside version control — a built
+  `dist`, a generated hook script — is invisible to this surface by nature. That is why the
+  session surface carries those paths on the common list instead.
+- **The valve needs a human at a terminal.** No TTY means no prompt and no way through: a
+  CI run and an agent-spawned `git commit` reach the same closed door. Nothing is ever
+  persisted, so one answer never covers a later commit.

package/dist/docs/reference/configuration.md

@@ -0,0 +1,294 @@
+# 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; it always blocks.
+
+**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, kept next to the rule) plus, on a
+`forbid` or `requirePrecedent` entry, `in` (the file globs it judges) and `except` (globs
+carved out of that scope).
+
+**`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

@@ -0,0 +1,111 @@
+# `@polydeukes/core`
+
+**English** · [한국어](./core.ko.md)
+
+> **The protocol every covenant speaks** — the input IR, the verdict shape, the config
+> schema, and the telemetry collector.
+>
+> Alpha. A transitive dependency of the umbrella: you do not install it and you do not import
+> it. The consumer entry point is [`polydeukes`](./polydeukes.md).
+
+## What this package owns
+
+The protocol every covenant speaks, and nothing that knows what a covenant is *about*.
+
+| Area | What it is |
+|---|---|
+| Covenant protocol | The stdin-JSON input IR, the verdict shape, the exit-code contract |
+| Config schema | `defineConfig()` validates parsed yaml/json data; the matching JSON Schema ships as a sibling artifact |
+| ROI telemetry | One append-only line collector every package writes through |
+| Fail policy | One table deciding fail-open against fail-closed per failure kind |
+| Protected-path normalization | The declared list becomes the literal strings the dispatcher matches |
+| Transcript seam | The query interface a covenant uses to ask about session history |
+
+Two constraints hold this package's shape. **Zero runtime dependencies** — validation is
+hand-rolled and the published JSON Schema is a sibling artifact the source never reads.
+**No agent, tool, or language literals** — editor tool verbs and test-runner names are
+*values* supplied by configs and adapters, so the core's agent-neutrality is a claim a grep
+can check. Every other package depends on this one; this one depends on none of them.
+
+## 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
+of these verdicts, so this vocabulary is what a blocked row is written in.
+
+```ts
+type CovenantInput = {
+  toolCalls: { name: string; args?: Record<string, unknown>; fileChange?: FileChange }[];
+  subagentSpawns: { kind: string }[];
+  userMessages: { text: string }[];
+};
+
+type FileChange =
+  | { kind: 'create'; path: string; post: string }
+  | { kind: 'modify'; path: string; pre: string; post: string }
+  | { kind: 'delete'; path: string; pre?: string };
+
+type CovenantVerdict = { upheld: true } | { upheld: false; reason: string };
+```
+
+The vocabulary carries no tool or agent names. A concrete tool name is a *value* an adapter
+fills into `name`; `kind` on a spawn is likewise a value. `FileChange` is a discriminated
+union so that a deletion is first-class evidence rather than an unrepresentable case, and
+impossible states — a deletion carrying resulting content, a creation carrying a baseline —
+cannot be written down. `delete.pre` is absent when the baseline was a binary blob, because
+a deletion needs no content to be judged.
+
+**Evidence has exactly one home: the call it belongs to.** `fileChange` absent means *this
+call is unproven*, and no sibling call's evidence stands in for it.
+
+```ts
+function parseInput(stdinJson: string):
+  | { ok: true; value: CovenantInput }
+  | { ok: false; exitCode: 2 };
+
+function verdictToExitCode(verdict: CovenantVerdict): 0 | 1;
+
+function allFileChanges(input: CovenantInput): FileChange[];
+```
+
+`parseInput` never throws. Unparseable JSON, an empty payload, a non-object, a missing
+required collection — each resolves to a blocking `{ ok: false, exitCode: 2 }`, so an
+unjudgeable input can never be mistaken for a valid one.
+
+`verdictToExitCode` returns `0` or `1` and never `2`. Translating a break into a block is
+the wrapper's policy, not the body's — see [exit codes](./polydeukes.md#exit-codes).
+
+`allFileChanges` flattens every call's evidence in call order for consumers that need no
+attribution. Calls without evidence are skipped, never substituted for.
+
+## Where the consumer touches it
+
+Three places, all of them indirect.
+
+- **The config file.** Its schema is defined here. The vocabulary reference is
+  [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.
+
+Everything else here is reached through `polydeukes`.
+
+## Declared limits
+
+- **Adapter namespaces are validated by shape, not by name.** `defineConfig()` checks that
+  `adapters` is a map of plain objects and that each namespace value is an object. It does
+  not check that a namespace *name* is one anybody implements, and it does not look inside
+  the namespace at all. Unknown vocabulary inside `adapters.git` is rejected by the git
+  adapter's own validator, at its own layer — not here.
+- **`requirePrecedent` evidence is layered the same way.** The core fully validates the
+  `command` key, because a shell command is the surface where an agent crosses into the
+  system. Every other key is validated for container shape alone — a flat object holding
+  exactly one key — and its value passes through verbatim for the owning adapter to judge.
+- **The default transcript is a noop.** A consumer that injects no real transcript
+  converges on "nothing happened", which is the safe direction for a valve: it never opens.
+  Real transcripts live behind adapters.
+- **Telemetry is fail-open, alone.** A logging failure never changes a verdict. Every other
+  failure kind in the table resolves toward blocking.

package/dist/docs/reference/covenant.md

@@ -0,0 +1,108 @@
+# `@polydeukes/covenant`
+
+**English** · [한국어](./covenant.ko.md)
+
+> **The judge** — the dispatcher, the discipline library, the meta-covenants, and the TTL
+> witness valve.
+>
+> Alpha. A transitive dependency of the umbrella: you do not install it and you do not
+> import it. What you reach is its behaviour, through the `disciplines:` block in your config
+> and the rows it writes to `.polydeukes/roi.log`.
+
+## What this package owns
+
+The judge. Everything that turns a declared promise into a verdict lives here.
+
+| Unit | What it does |
+|---|---|
+| `runCovenant` wrapper | Runs a judge body, translates its non-blocking `1` into the blocking `2`, and logs every call. No covenant runs unmeasured |
+| Path-routing dispatcher | Registers covenants against protected paths and runs *every* matching one — no short-circuit, so the telemetry never under-counts |
+| Meta-covenants | Three registrations that protect the judging chain itself |
+| TTL witness | The time-boxed human valve, consulted only after a verdict blocked |
+| Delta layer | New-violation-only judgment over a file's before/after pair |
+| Discipline library | Config `disciplines:` entries become enforcement without a line of code |
+
+## Discipline families and meta-covenants
+
+**A `disciplines:` entry belongs to exactly one family**, decided by which predicate key it
+carries. The family determines what evidence the judgment needs — which is also what
+determines whether it can be judged on a given surface.
+
+| Family | Key | Judges | Evidence needed |
+|---|---|---|---|
+| delta | `forbid` | Added-direction content of a file change. Existing debt is forgiven; only new occurrences break | File change |
+| path | `immutable` | Any change to a file that already exists — modification or deletion alike. Creation passes | File change |
+| command | `forbidCommand` | The command line itself | None |
+| context | `requirePrecedent` | Session history — was a qualifying call actually executed *before* this one | A transcript |
+
+`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 [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.
+
+| Registration | Axis | Judges |
+|---|---|---|
+| self-mod | Tool | Mutations to protected paths through editing tools. Only the call's proven mutation target is compared — a protected path inside an edit's *content* is a mention and passes |
+| 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 |
+
+**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 |
+|---|---|
+| `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 |
+| `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
+
+- **The `disciplines:` block** in your config. One entry compiles into one registration,
+  carrying its own telemetry label.
+- **`protectedPaths`**, which the path-routing dispatcher matches against.
+- **The `witness` block**, which arms the TTL valve.
+- **`.polydeukes/roi.log`**, where every judgment lands as one row.
+
+No import. The umbrella assembles this package for both surfaces.
+
+## Declared limits
+
+- **The shell axis leaves `skipped` rows, and that row is the contract.** Predicting a
+  shell command's target from its text is undecidable, so the invariant this axis holds is
+  not "nothing gets through" — it is that **no call passes unrecorded**. A new spelling
+  landing in `skipped` is the declared limit showing itself. A pass with no row at all, or
+  one recorded `passed` without a judgment, is the defect class.
+- **The context family cannot be judged without a session.** On the commit surface there is
+  none, so a matching `requirePrecedent` entry always records `skipped`. That is a permanent
+  condition of that surface.
+- **The command family is absent from the commit surface, and absent without a row.**
+  `forbidCommand` entries are filtered out before compilation there, since a staged diff
+  carries no command line to judge. Unlike the context family this leaves nothing in
+  `.polydeukes/roi.log`, so the log cannot separate a command discipline that never
+  triggered from one that was never registered on that surface.
+- **An unjudgeable entry compiles to a skip registration** — routing intact, no body. A
+  pattern that does not compile skips the same way. Assembly therefore never throws: one
+  unresolvable entry cannot take down its siblings, the meta-covenants, and the valve,
+  which would leave no way to fix the config that caused it.
+- **Complete containment is a non-goal.** There are no blocklists here — enumerating bypass
+  spellings is always one step behind, so the logic is inverted: a mention of a protected
+  path blocks unless proven safe. Residual vectors such as indirect path computation are
+  telemetry targets, not block targets. The two friction valves — the read-only allowlist
+  and the TTL witness — both leave a measurable trace.
+- **The valve stands after the verdict.** Only a judgment that actually blocked can be
+  witnessed open, a mid-sentence mention of the token does not arm it, and an AI can never
+  open the valve for itself.