polydeukes 0.5.0 → 0.6.1

package/dist/docs/configuration.md

@@ -1,103 +0,0 @@
-# Configuring Polydeukes
-
-**English** · [한국어](./configuration.ko.md)
-
-> Alpha. This guide covers the config surface as shipped today (schema v2, loader, and
-> the four built-in discipline predicates). Fields and predicates will grow; what is
-> written here is tested and enforced now.
-
-`polydeukes.config.yaml` is the one file where a project declares its disciplines — the
-promises the human and the AI partner both agree to be bound by. It is **data, not code**:
-nothing in it can compute, so nothing in it can lie. The core validates it, the covenant
-package enforces it, and every judgment it causes is measured.
-
-This is the guide layer: the file itself, how discovery fails, the IDE wiring, and what
-enforcement looks like. Every key, with its full rules and pitfalls, lives in
-[the configuration reference](./reference/configuration.md).
-
-## The file
-
-Put exactly one of these at the project root:
-
-| Filename | Note |
-|---|---|
-| `polydeukes.config.yaml` | canonical |
-| `polydeukes.config.yml` | accepted variant |
-| `polydeukes.config.json` | accepted variant (read by the same parser — YAML is a JSON superset) |
-
-Discovery is deliberately strict, and every failure refuses loudly instead of guessing:
-
-- **No config found** → error naming all three candidate filenames. A missing config never
-  silently loads defaults — silent defaults would mean silently unprotected.
-- **More than one found** → error naming the collisions. Ambiguity never picks a winner.
-- **Parse error, or a custom YAML tag** → error naming the file. Custom tags are rejected
-  even though the parser cannot execute them — config data stays uncomputable by contract.
-- **Schema violation** → error naming the key and the file. Unknown keys are rejected
-  wherever the core owns the vocabulary — the top level, and the fixed keys inside a
-  discipline entry — so `protectedPath:` for `protectedPaths:`, or `adaptors:` for
-  `adapters:`, is caught here. Two maps stay open, because their keys are your values
-  rather than the core's: language names under `languages`, and adapter names under
-  `adapters`. A misspelt adapter name is accepted and its block simply goes unread, which
-  leaves that adapter on its defaults — check the name against the adapter's own reference.
-  Inside a namespace the vocabulary belongs to that adapter: the core passes contents
-  through verbatim, and the adapter's own validator rejects what it does not recognise,
-  naming the full field path (see
-  [the `adapters` reference](./reference/configuration.md#adapters)).
-
-## IDE support
-
-The JSON Schema gives autocompletion and validation in editors. It ships inside the
-`polydeukes` package, so the line names a path into your own `node_modules`:
-
-```yaml
-# yaml-language-server: $schema=node_modules/polydeukes/dist/schema/polydeukes.schema.json
-```
-
-For a JSON config, use the standard top-level key instead. The loader accepts it and drops
-it from the resolved config:
-
-```json
-{ "$schema": "node_modules/polydeukes/dist/schema/polydeukes.schema.json" }
-```
-
-**The path is resolved against the directory your config sits in**, not against a project
-root the editor infers. The spelling above is right when the two are the same place. When
-they are not — a config in a monorepo sub-package whose dependencies installed at the
-workspace root — count the levels up yourself:
-
-```yaml
-# yaml-language-server: $schema=../../node_modules/polydeukes/dist/schema/polydeukes.schema.json
-```
-
-`pdks init claude-code` writes the line only when the schema is where the plain spelling
-names it. If the generated config has no such line, that is the case above, and the prefix
-is yours to add — an unresolvable path costs you validation without reporting anything.
-
-If you installed `@polydeukes/core` directly rather than the umbrella, name its own copy:
-
-```yaml
-# yaml-language-server: $schema=node_modules/@polydeukes/core/schema/polydeukes.schema.json
-```
-
-Every value here is a **file path**, not a module specifier: `$schema` is a static string an
-editor reads, so no module resolver runs on it. Code that reads the schema at runtime uses
-the package subpath `polydeukes/schema.json` instead.
-
-## What enforcement looks like
-
-A `disciplines:` entry lands at **advise** by default: a break is recorded as `advised`
-with the discipline's `id` in the telemetry record, the break message with its `why` goes
-to stderr, and the call proceeds (exit 0) — the judgment measures instead of stopping.
-Writing `enforce: block` on an entry is the promotion: that entry then **blocks (exit 2)**
-before the call runs. The sanctioned valve on a block is the witness — a human supplying
-the pass condition on a judgment that actually blocked, recorded as `witnessed` — never
-silent.
-
-What blocks without being asked is the judging chain's own protection, a finite list: the
-`protectedPaths` entries (tool-axis and shell-axis mutations, and mentions without a
-read-only head), the session transcript, and the assembly itself — a missing, ambiguous, or
-invalid config, an unbuilt judge, an unparseable payload, or a routing that could not
-answer. At either level the system fails closed on these, because a dead gate that waves
-things through is the cheapest bypass of all. On the commit surface `adapters.git.enforce: advise` relaxes
-the protected-path verdicts to `advised` as well — it is the observer's setting — while an
-assembly that cannot judge still fails closed.

package/dist/docs/installation.md

@@ -1,212 +0,0 @@
-# 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.
-
-This is the getting-started layer: from an empty project to a first judged call.
-
-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.
-
-Six artifacts, none ever overwritten. What exists is reported and kept — the hook, the
-config, and the discipline files 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. |
-| `.claude/skills/discipline-draft/SKILL.md` | The classification procedure. Describe a recurring problem to your AI partner and it lands as a config entry — judged at advise when a current family can express it, a `draft: true` entry otherwise — and the same file tells the agent to consult `advised` rows in the telemetry log at task boundaries. |
-| `.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 guide](./configuration.md) for the file and its wiring,
-[the configuration reference](./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/configuration.md

@@ -1,338 +0,0 @@
-# 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.