polydeukes 0.3.0 → 0.5.0

package/dist/docs/configuration.md

@@ -2,15 +2,19 @@
 
 **English** · [한국어](./configuration.ko.md)
 
-> Alpha. This reference describes 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.
+> 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:
@@ -37,325 +41,63 @@ Discovery is deliberately strict, and every failure refuses loudly instead of gu
   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 [`adapters`](#adapters-optional)).
+  naming the full field path (see
+  [the `adapters` reference](./reference/configuration.md#adapters)).
 
 ## IDE support
 
-The published JSON Schema gives autocompletion and validation in editors. The schema file
-ships inside `@polydeukes/core` — a *transitive* dependency of the umbrella — and under
-pnpm's default strict layout transitive dependencies are not exposed at your project's
-top-level `node_modules` (measured 2026-08-03: the file resolves only under
-`node_modules/.pnpm/…`). A `node_modules`-relative `$schema` line therefore does not
-resolve in a default pnpm install. `pdks init claude-code` writes no `$schema` line into
-the generated config for the same reason: no single *file-path* spelling resolves in every
-consumer layout, and a wrong line loses editor validation silently.
-
-Two forms work. The version-pinned public URL is independent of any install layout
-(verified against the `v0.2.0` tag and `main` — swap the tag for the release you
-installed):
+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=https://raw.githubusercontent.com/huskyhoochu/polydeukes/v0.2.0/packages/core/schema/polydeukes.schema.json
+# yaml-language-server: $schema=node_modules/polydeukes/dist/schema/polydeukes.schema.json
 ```
 
-The relative path works only in a layout where `@polydeukes/core` is present at the top
-level of `node_modules`. Whether yours is one is a one-look check — if
-`node_modules/@polydeukes/core/schema/` exists in your project, the line resolves:
-
-```yaml
-# yaml-language-server: $schema=node_modules/@polydeukes/core/schema/polydeukes.schema.json
-```
-
-For a JSON config, use the standard top-level key instead — it is accepted and ignored by
-the loader, with the same two values:
+For a JSON config, use the standard top-level key instead. The loader accepts it and drops
+it from the resolved config:
 
 ```json
-{ "$schema": "https://raw.githubusercontent.com/huskyhoochu/polydeukes/v0.2.0/packages/core/schema/polydeukes.schema.json" }
-```
-
-## Reference
-
-### `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.
-
-```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.
-
-### `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/**'
+{ "$schema": "node_modules/polydeukes/dist/schema/polydeukes.schema.json" }
 ```
 
-**`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.
+**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
-  - 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'
+# yaml-language-server: $schema=../../node_modules/polydeukes/dist/schema/polydeukes.schema.json
 ```
 
-**`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.
+`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.
 
-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.
+If you installed `@polydeukes/core` directly rather than the umbrella, name its own copy:
 
 ```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 '
+# yaml-language-server: $schema=node_modules/@polydeukes/core/schema/polydeukes.schema.json
 ```
 
-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.
+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 violating tool call or shell command is **blocked (exit 2)** before it runs, with the
-discipline's `id` in the telemetry record. The sanctioned valve is the witness — a human
-supplying the pass condition on a judgment that actually blocked, recorded as
-`witnessed` — never silent. On the commit surface under
-`adapters.git.enforce: advise`, a verdict is recorded as `advised` and the commit
-proceeds — a backstop that measures instead of blocking. A missing, ambiguous, or
-invalid config blocks every call until it is fixed: the system fails closed, because a
-dead gate that waves things through is the cheapest bypass of all.
+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

@@ -5,6 +5,8 @@
 > 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`).
@@ -49,8 +51,8 @@ package resolves there **before writing anything** — if it does not (say, the
 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
+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 |
@@ -59,6 +61,7 @@ config, and the discipline file are left alone, the settings file is merged, and
 | `.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`
@@ -203,6 +206,7 @@ Every judgment appends exactly one record — `passed`, `blocked`, `witnessed`,
 `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
+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/adapter-git.md

@@ -25,16 +25,27 @@ This is a pure library. It knows the staged-diff shape and nothing about install
 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 and the `adapters.git` namespace
+
+**Three collectors, one shape.** `collectStagedChanges`, `collectWorktreeChanges`, and
+`collectRangeChanges(repoRoot, '<base>..<head>' | '<base>...<head>')` each return the same
+`StagedChange[]`, so the translator and everything after it is one path.
+
+| Collector | `pre` | `post` | Also |
+|---|---|---|---|
+| staged | HEAD blob | The **staged** blob — never the worktree, which may have diverged after `git add` | |
+| worktree | HEAD blob | The bytes on disk | Untracked, non-ignored files join as `added`; a file missing from disk is `deleted`, whether HEAD held it or only the index did; an unreadable path (a dangling symlink) yields null content and is judged on its path |
+| range | base blob | head blob | `...` resolves the base to `git merge-base`; a ref git cannot resolve, or two refs with no merge-base, throws |
 
 **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 |
+| `--no-renames` forced on, in every collector | 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 |
+| A binary blob or file yields null content | Rather than lossily decoded bytes |
+| The unborn first commit narrows to all-added | Rather than throwing — staged and worktree alike |
+| A type change (`T`) keeps its `pre` side | A symlink replaced by a file is a modification, so a delta judgment still sees what was removed |
+| Every listing ends with `--` | A branch that shares its name with a file is a ref, never an ambiguous argument |
 
 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
@@ -54,7 +65,7 @@ vocabulary, its validator, and its defaults all live here.
 
 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 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