polydeukes 0.0.1 → 0.3.0

package/dist/docs/installation.md

@@ -0,0 +1,208 @@
+# Installing Polydeukes
+
+**English** · [한국어](./installation.ko.md)
+
+> Alpha. This guide covers the install paths that ship today, and everything here is the
+> measured behaviour of the published packages.
+
+One devDependency, one command per surface. The umbrella package `polydeukes` is the only
+thing you install — it carries the core, the judge, and the adapters as its own
+dependencies, and `pdks` is its CLI (an alias of `polydeukes`).
+
+**Two surfaces ship, for two different situations — pick the one that matches how the
+project is developed.** A project built alongside an AI partner in Claude Code wires the
+**session surface**: a PreToolUse hook that judges every editing tool call and shell
+command as it is declared. A project you develop yourself wires the **commit surface**: a
+pre-commit hook that judges the staged diff, so the discipline you declared for yourself
+is applied at the moment work becomes history. They enforce the same config vocabulary,
+but they answer different situations — there is no general reason to wire both in one
+project.
+
+## Prerequisites
+
+- **Node.js ≥ 24** — the engines floor of every published package.
+- **A package manager** — pnpm and npm both work; examples below use pnpm.
+- **Claude Code** — only for the session surface. The commit surface needs no AI tool at
+  all: just git and a way to run a pre-commit hook.
+
+## Install
+
+```sh
+pnpm add -D polydeukes
+```
+
+(or `npm install --save-dev polydeukes`.)
+
+This must be a real project dependency, not a one-off `npx` run — both surfaces load the
+judge from your project's own installed package.
+
+## The session surface — developing with an AI partner
+
+From the project root:
+
+```sh
+pnpm exec pdks init claude-code
+```
+
+The command installs into the directory it is invoked from, and it proves the `polydeukes`
+package resolves there **before writing anything** — if it does not (say, the install step
+was skipped), it prints the install command and exits 2 with zero files written, never a
+half-wired tree.
+
+Five artifacts, none ever overwritten. What exists is reported and kept — the hook, the
+config, and the discipline file are left alone, the settings file is merged, and
+`.gitignore` is only ever appended to — so re-running is always safe:
+
+| Artifact | What it is |
+|---|---|
+| `.claude/hooks/covenant-pretooluse.mjs` | The hook — a thin delegator that loads the judge from the installed package. Upgrading the package upgrades the judge; this file never changes. |
+| `.claude/settings.json` | The PreToolUse registration for editing tools and shell calls. **Merged, never replaced** — your other hooks and permissions stay. |
+| `polydeukes.config.yaml` | The starter protection policy: a placeholder `languages` block, a minimum `protectedPaths` list, and the witness block. The comments in the file explain why each entry is there. |
+| `.claude/rules/polydeukes.md` | A scoped discipline file telling your AI partner that `pdks docs` exists and which topic answers what. It carries `paths` frontmatter, so it loads when a Polydeukes path is in play rather than sitting in every session's context. |
+| `.gitignore` | An appended ignore rule for `.polydeukes/`, with its comment line — telemetry is local observation data and never belongs in history. |
+
+## First edit — `languages`
+
+The generated config ships a placeholder language profile, because the installer cannot
+know your stack:
+
+```yaml
+languages:
+  placeholder:
+    productionGlob: 'src/**'
+    testCmd: 'echo "set a verification command for {scope}"'
+```
+
+Rename the key to your language, point `productionGlob` at your production sources, and put
+your real verification command in `testCmd`. (On the commit-surface path you write this
+block yourself as part of the config below.) The placeholder is valid as generated and no
+judgment path reads these values yet, so it cannot produce a wrong verdict while it waits —
+but `languages` is the schema's one required block, so *removing* it (or emptying it) makes
+the config invalid, and an invalid config blocks every call. Edit it, don't delete it.
+
+## The commit surface — developing by yourself
+
+This path is for applying your own discipline to your own commits — no AI tool involved.
+It has no installer today; the wiring is two small manual steps.
+
+**First, the config.** Create `polydeukes.config.yaml` at the project root (there is no
+generator on this path — the file is yours from the first line):
+
+```yaml
+languages:
+  typescript:
+    productionGlob: 'src/**'
+    testCmd: 'pnpm test'
+
+# Judged at commit time: a staged change to these paths stops the commit
+# until you answer the witness prompt in person.
+protectedPaths:
+  - 'db/migrations'
+
+witness:
+  token: 'pdks witness'
+  ttlMinutes: 10
+```
+
+Add `.polydeukes/` to your `.gitignore` too — telemetry is local observation data.
+
+**Then, the hook.** One command judges what is currently staged and exits 2 on a broken
+covenant:
+
+```sh
+pnpm exec pdks covenant check
+```
+
+Register it as a pre-commit hook. With **lefthook**:
+
+```yaml
+# lefthook.yml
+pre-commit:
+  commands:
+    covenant:
+      priority: 1
+      interactive: true   # keep the witness prompt visible — see below
+      run: ./node_modules/.bin/pdks covenant check
+```
+
+With **husky**:
+
+```sh
+# .husky/pre-commit
+./node_modules/.bin/pdks covenant check
+```
+
+With plain **`.git/hooks`** (make it executable):
+
+```sh
+#!/bin/sh
+# .git/hooks/pre-commit
+./node_modules/.bin/pdks covenant check
+```
+
+Three things to know about this surface:
+
+- **The valve is a TTY prompt.** At the default `block` level, a commit that stages a
+  protected change stops at a prompt only a human at a terminal can answer. Configure your
+  hook runner so it does not swallow that prompt (lefthook needs `interactive: true`).
+- **Two discipline families judge here.** A staged diff carries file changes and nothing
+  else, so protection lists and the delta and path families (`forbid`, `immutable`) judge
+  in full. A command-family entry (`forbidCommand`) has no command line to read in a
+  staged diff and is not assembled on this surface, and a context-family entry
+  (`requirePrecedent`) is recorded as `skipped` — declare those two where an AI partner's
+  session exists to be judged.
+- **The commit surface has its own additive scope.** Paths that are fine to edit freely
+  but whose promotion into history deserves a judged checkpoint go under the adapter
+  namespace, judged on top of the shared list:
+
+  ```yaml
+  adapters:
+    git:
+      protectedPaths:
+        - 'src/policy'
+  ```
+
+## The witness valve
+
+Both surfaces carry the same valve, spelled for their situation. It sits **after** the
+verdict — only a judgment that actually blocked can be witnessed open — and every allowance
+is recorded as `witnessed`, never silent.
+
+```yaml
+witness:
+  token: 'pdks witness'
+  ttlMinutes: 10
+```
+
+- **Session surface:** a human types the token so it stands alone on the first line of a
+  conversation message; the window holds for `ttlMinutes`, then blocking resumes. An agent
+  cannot open the valve for itself — only human-authored messages count.
+- **Commit surface:** the blocked commit shows a TTY prompt, and typing the full token
+  there opens that one commit.
+
+Change the token and window as you like — the token is not a secret; the defence is
+provenance, not confidentiality. **Keep the block**: on the session surface the generated
+protection list covers `.claude/hooks`, so without a valve the first blocked call would
+freeze the project until a human edits the config from their own terminal.
+
+## Prove the gate is live
+
+Prove it once on the surface you wired, then read the telemetry.
+
+- **Session surface:** ask your agent to append a line to
+  `.claude/hooks/covenant-pretooluse.mjs` (a protected path). The call must come back
+  blocked.
+- **Commit surface:** stage an edit to a path on your protection list and run
+  `git commit`. It must stop at the witness prompt (answer it, or abort with Ctrl-C).
+
+```sh
+cat .polydeukes/roi.log
+```
+
+Every judgment appends exactly one record — `passed`, `blocked`, `witnessed`, `advised`, or
+`skipped` — so the block you just caused is the last line. A gate you have watched block
+once is a gate you know is wired.
+
+From here: [the configuration reference](./configuration.md) for every field and for
+writing your own disciplines, and [troubleshooting](./troubleshooting.md) when something
+blocks and you don't know why.

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

@@ -0,0 +1,82 @@
+# `@polydeukes/adapter-claude-code`
+
+**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).
+
+## What this package owns
+
+The boundary where Claude Code's vocabulary is translated away. Agent and tool literals
+live *here* by design, so that they never reach the core — which is what makes the core's
+agent-neutrality a claim a test can check rather than a slogan.
+
+| Unit | What it does |
+|---|---|
+| Payload up-translation | A raw PreToolUse payload becomes a `CovenantInput` |
+| 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.
+
+## Payload translation and the three axes
+
+**Three axes reach the judge**, and they differ in what evidence they can carry.
+
+| Axis | Carries | Consequence |
+|---|---|---|
+| Tool | A proven `fileChange` — the mutation target computed before the tool runs | Only the proven target is judged. A protected path inside an edit's *content* is a mention and passes |
+| Shell | A command line whose target is often not computable before execution | Computable writes are judged like an edit; the rest is recorded rather than guessed |
+| Transcript | The session's own record | Judged by whole-path equality, never as a protected ancestor |
+
+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.
+
+**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
+discipline judges the *proposed* result rather than the file as it currently is. An
+unresolvable post-state yields no evidence at all, because the real tool would reject the
+same edit, and evidence is never fabricated for a non-mutating call.
+
+**The transcript admits only positively-identified human messages.** That is what makes the
+witness valve human-only: an AI cannot synthesize its own witness. A read failure answers
+`undefined` rather than an empty transcript — an empty session has said nothing yet and is
+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.
+
+## 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.
+
+## Declared limits
+
+- **A child process's writes are outside observation.** This surface judges *declared tool
+  calls*. A command that spawns a process which then writes files — a test runner, a build
+  — is judged on the command, not on what the child did. The commit surface is the second
+  observation that covers the same ground for tracked files.
+- **Evidence exists only where a post-state can be computed.** All four mutating tools
+  contribute one, notebooks included — a `NotebookEdit` yields cell-level `modify` evidence.
+  What yields nothing is a payload this adapter cannot resolve: an unreadable or unparseable
+  notebook, a cell it cannot name, an edit mode it does not know.
+- **An evidence-free call falls back to the conservative judgment** — the call's arguments
+  are compared for a mention rather than a proven target.
+- **Out-of-repository ancestors stay out of scope.** A path above the project root is not
+  observed here; the agent's own deny policy owns that ground.

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
+[configuration.md's `adapters` section](../configuration.md#adapters-optional).
+
+**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/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
+  [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
+  [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,100 @@
+# `@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 [configuration.md's `disciplines` section](../configuration.md#disciplines-optional).
+
+**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 |
+
+**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
+[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 |
+
+## 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.