polydeukes 0.6.0 → 0.7.1

package/dist/docs/installation.md

@@ -1,241 +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    # Claude Code
-pnpm exec pdks init grok           # Grok
-```
-
-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.
-
-Nothing existing is 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. One command-field exception: if
-`.grok/hooks/covenant-pretooluse.json` still names the grok delegator and a Claude
-delegator is on disk, the JSON `command` is rewritten to that Claude file so the host
-does not spawn two judges. Grok collapses two registrations only when `command` AND
-`matcher` are identical, so every grok entry naming that Claude file also takes the matcher
-of the `.claude/settings.json` entry that registers the same command — on a fresh write and
-on every re-run; `timeout` stays. A command you pointed elsewhere is left as it was.
-
-`pdks init claude-code` writes six artifacts:
-
-| 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. |
-
-`pdks init grok` shares the scaffold (config and the ignore line) and writes Grok's own
-registration. A Grok-only tree has four artifacts, and no `.claude/` directory:
-
-| Artifact | What it is |
-|---|---|
-| `.grok/hooks/covenant-pretooluse.mjs` | The hook — the same delegator text, only when no Claude delegator is already on disk. |
-| `.grok/hooks/covenant-pretooluse.json` | The PreToolUse matcher, `timeout` 60 (the host default is 5 seconds, and a timed-out hook fails open), and the command that names one delegator file. In a tree that also has `.claude/settings.json`, the matcher is copied from the settings entry with the same command — Grok reads that file too, and collapses the two registrations into one spawn only when `command` and `matcher` match exactly. That copy leans on Grok's tool-name aliases, so if you later remove `.claude/settings.json`, delete this JSON and run `pdks init grok` again to get the Grok-native matcher back. |
-| `polydeukes.config.yaml` | The same starter policy as above. |
-| `.gitignore` | The same appended ignore line. |
-
-If `.claude/hooks/covenant-pretooluse.mjs` already exists, the JSON command points at that
-file instead of planting a second one. A later `pdks init grok` or `pdks init claude-code`
-retargets an installer-generated grok-mjs command the same way.
-
-An already-open Grok session keeps the hook snapshot from start. Reload from the Hooks tab
-(`r`) or start a new session. The witness valve does not open on Grok — the session log is
-ACP `updates.jsonl`, not Claude's JSONL. A block is recovered from another terminal or the
-commit-surface TTY.
-
-## 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`).
-- **Declarations judge here.** A staged diff carries file changes and nothing else, so
-  protection lists and every `declare` entry over the change judge in full. A declaration
-  scoped on `command` has no command line to read in a staged diff and observes nothing on
-  this surface, and a declaration that reads the session (`precedent` and the other history
-  mechanisms) is recorded as `skipped` — declare those 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` and `.grok/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/adapter-git.md

@@ -1,100 +0,0 @@
-# `@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. It names `@polydeukes/core` as a `peerDependency`: the vocabulary is shared with
-the judge, not installed a second time here.
-
-## Collection and the `adapters.git` namespace
-
-**Three collectors, one shape.** `collectStagedChanges`, `collectWorktreeChanges`, and
-`collectRangeChanges({ repoRoot, range: '<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, 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
-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. There is no `actor` either: the hook cannot tell a
-human's `git commit` from an agent's, so it proves none.
-
-**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
-
-- **A declaration that reads the session cannot be judged here.** A `precedent` 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/covenant.md

@@ -1,116 +0,0 @@
-# `@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.
-
-**This is the install unit for judgment.** An embedder that wants verdicts without the
-umbrella's surfaces installs this package and provides `@polydeukes/core` alongside it — core
-is a `peerDependency` here, so the vocabulary is shared rather than duplicated. The umbrella
-is what satisfies that peer for an ordinary consumer.
-
-| 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 is one declaration** — `judge = relate ∘ extract` over the
-observation as a world. What the declaration's sources bind decides what evidence the
-judgment needs, which is also what decides whether it can be judged on a given surface.
-
-| Sources | Judges | Evidence needed |
-|---|---|---|
-| the fixed names `target.path` · `pre` · `post` · `state` · `changes` | The change itself | A file change |
-| the fixed name `command` | The shell call's command line | A shell call — an Edit carries none |
-| `{ transcript: true }` | Session history — was a qualifying call actually executed *before* this one | A session |
-| `{ file: … }` · `{ sidecar: true }` | Another file, or the spawn-record channel | The surface's reader for it |
-
-The writing guide for these entries is [the configuration reference's `disciplines`
-section](./configuration.md#disciplines); the declaration grammar is the core's
-`algebra-declaration.schema.json`.
-
-**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` | A break recorded without stopping the call — the default for every discipline entry on both surfaces, and the commit surface's outcome under `adapters.git.enforce: advise` |
-| `skipped` | The call reached a registration that could not judge it. **Not a pass** — the recorded absence of a judgment |
-| `unattributed` | A protected entry's on-disk state moved and no judgment row explains it. **Not a verdict** — no call is blocked or passed by it; the session surface writes it after comparing state against a stored baseline |
-
-`unattributed` answers a question the other five cannot. They are all written by a judge
-about a call it was handed, so a write that arrives without a declared call — through an
-interpreter, a test runner's child process, a script that assembles the path from its own
-arguments — leaves no row at all. The comparison observes the result rather than the
-spelling, so it records that write after the fact. It never blocks: the write already
-happened, and the comparison fails open on both sides of the verdict.
-
-## Where the consumer touches it
-
-- **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.
-- **A declaration that reads the session cannot be judged without one.** On the commit
-  surface there is none, so a matching `precedent` (or any other transcript-reading)
-  declaration records `skipped` with the reason `supply-pass`. That is a permanent
-  condition of that surface.
-- **A declaration scoped on `command` is absent from the commit surface, and absent without
-  a row.** A staged diff carries no command line, so no world such a declaration observes is
-  admitted there. This leaves nothing in `.polydeukes/roi.log`, so the log cannot separate a
-  command discipline that never triggered from one whose surface never observed a command.
-- **A declaration the compiler cannot resolve compiles to a skip registration** — routing
-  intact, no body: a step outside the registry, an argument outside a step's keys, a pattern
-  that does not compile, a mechanism whose shape the syntax does not fit. 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. A source the world
-  lacks at judgment time is a different case — the declaration's own `supply` policy
-  disposes of it, and with no policy the body answers unjudgeable (exit 2), never upheld.
-- **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.