polydeukes 0.5.0 → 0.6.0

package/dist/covenant-check.js

@@ -11,10 +11,11 @@
  * blocked record. An empty domain is an explicit pass with no records.
  */
 import { resolve } from 'node:path';
-import { collectRangeChanges, collectStagedChanges, collectWorktreeChanges, covenantInputFromStagedChanges, resolveGitAdapterSettings, STAGED_DELETE, STAGED_WRITE, } from '@polydeukes/adapter-git';
+import { collectRangeChanges, collectStagedChanges, collectWorktreeChanges, covenantInputFromStagedChanges, observationSourceReader, resolveGitAdapterSettings, STAGED_DELETE, STAGED_WRITE, } from '@polydeukes/adapter-git';
 import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, } from '@polydeukes/core';
 import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
 import { loadConfig } from './load-config.js';
+import { unobservedPreStateReader } from './pre-state-reader.js';
 /**
  * The TTY witness predicate, or undefined when no valve can exist (no witness configured
  * or no TTY seam). It fires on the first registration that broke, names it from the
@@ -61,7 +62,9 @@ function recordFailClosed(telemetryPath) {
  */
 export function assembleCommitRegistrations(spec) {
     const { config, rootDir, covenant, witness } = spec;
-    const { protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings(config.adapters?.git);
+    const { protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings({
+        namespace: config.adapters?.git,
+    });
     // Union of the common list and the git-additive one, common first so first-occurrence
     // dedupe is deterministic. The session hook reads the common list alone.
     const protectedPaths = normalizeProtectedPaths({
@@ -74,14 +77,13 @@ export function assembleCommitRegistrations(spec) {
             mutatingToolNames: [STAGED_WRITE, STAGED_DELETE],
             witness,
         }),
-        // No shell axis here, so command-family entries are left out. Context-family entries
-        // stay in: with no transcript the compiler gives them skip registrations, which record
-        // `skipped` on a match.
         ...covenant.compileDisciplineRegistrations({
-            disciplines: disciplines.filter((entry) => entry.forbidCommand === undefined),
+            disciplines,
             rootDir,
             shellTools: [],
             commandArgs: [],
+            readPreState: unobservedPreStateReader,
+            observesChangeSet: true,
             witness,
         }),
     ];
@@ -104,7 +106,7 @@ function settleConfig(spec) {
     let telemetryPath;
     try {
         telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
-        const { config } = loadConfig(spec.repoRoot);
+        const { config } = loadConfig({ rootDir: spec.repoRoot });
         telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
         return { settled: true, telemetryPath, config };
     }
@@ -118,12 +120,32 @@ function settleConfig(spec) {
  */
 function collectDomain(repoRoot, domain) {
     if (domain.kind === 'worktree')
-        return collectWorktreeChanges(repoRoot);
+        return collectWorktreeChanges({ repoRoot });
     if (domain.kind === 'range') {
         const separator = domain.ancestry === 'merge-base' ? '...' : '..';
-        return collectRangeChanges(repoRoot, `${domain.base}${separator}${domain.head}`);
+        return collectRangeChanges({
+            repoRoot,
+            range: `${domain.base}${separator}${domain.head}`,
+        });
+    }
+    return collectStagedChanges({ repoRoot });
+}
+/**
+ * The observation's change set: the paths of the collected changes that carry file-change
+ * evidence, in collection order.
+ *
+ * The same definition the judge derives its own set from, so both surfaces name the same
+ * changes. A deletion carries evidence and stays; a binary blob, which the collector gives
+ * a call with no evidence, produces no world of its own — listing it would hand the
+ * change-set relations a path no world can ever answer for.
+ */
+function changedPaths(changes) {
+    const paths = [];
+    for (const call of covenantInputFromStagedChanges({ changes }).toolCalls) {
+        if (call.fileChange !== undefined)
+            paths.push(call.fileChange.path);
     }
-    return collectStagedChanges(repoRoot);
+    return paths;
 }
 /**
  * Assemble the registrations and dispatch every collected change. Any throw here (an
@@ -132,7 +154,7 @@ function collectDomain(repoRoot, domain) {
 async function judgeChanges(spec, domain, telemetryPath, config, changes) {
     try {
         // Inside the try so an invalid adapter namespace fails closed.
-        const { enforce } = resolveGitAdapterSettings(config.adapters?.git);
+        const { enforce } = resolveGitAdapterSettings({ namespace: config.adapters?.git });
         // Real Node resolution of the covenant package, so the commit surface runs the same
         // judges the session hook does; tests inject a directory instead. Awaited before any
         // registration is composed, so a dist the barrel cannot load fails the run closed here
@@ -155,14 +177,24 @@ async function judgeChanges(spec, domain, telemetryPath, config, changes) {
             covenant,
             witness,
         });
+        // One plan and one supply for the run: the per-change loop shares them, so the tree is
+        // read once per named file rather than once per change. `changes` carries the whole
+        // observation because this surface dispatches one change at a time to keep telemetry at
+        // one row per file — a set no judge could derive from the input it is handed.
+        const { files } = covenant.supplySources({
+            plan: covenant.planSources({ registrations }),
+            read: observationSourceReader({ repoRoot: spec.repoRoot, observation: domain }),
+        });
+        const world = { files, changes: changedPaths(changes) };
         for (const change of changes) {
-            const input = covenantInputFromStagedChanges([change]);
+            const input = covenantInputFromStagedChanges({ changes: [change] });
             const { exitCode, results } = await covenant.dispatchCovenants({
                 stdinPayload: JSON.stringify(input),
                 registrations,
                 telemetryPath,
                 dispatcherLabel: 'covenant-check',
                 enforce,
+                world,
             });
             if (exitCode === 2)
                 blocked = true;

package/dist/covenant-module.d.ts

@@ -12,8 +12,8 @@
  * mirror where real Node resolution would always land on the healthy build.
  */
 import type * as covenant from '@polydeukes/covenant';
-/** The covenant surface both roots assemble against. */
-export type CovenantModule = typeof covenant;
+/** The covenant surface both roots assemble against — the members they call, and no more. */
+export type CovenantModule = Pick<typeof covenant, 'dispatchCovenants' | 'compileDisciplineRegistrations' | 'selfModRegistration' | 'shellModRegistration' | 'transcriptModRegistration' | 'planSources' | 'supplySources'>;
 /** Where real Node resolution puts the covenant package's built barrel. */
 export declare function resolveCovenantDist(): string;
 /**

package/dist/covenant-module.js

@@ -11,6 +11,14 @@
  * The `covenantDist` seam selects WHICH dist is imported, so a fixture can inject a gutted
  * mirror where real Node resolution would always land on the healthy build.
  */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -26,7 +34,7 @@ export function resolveCovenantDist() {
  */
 export async function loadCovenantModule(distDir) {
     try {
-        return (await import(pathToFileURL(join(distDir, 'index.js')).href));
+        return (await import(__rewriteRelativeImportExtension(pathToFileURL(join(distDir, 'index.js')).href)));
     }
     catch (error) {
         throw new Error(`the covenant judges could not be loaded from ${distDir} — run 'pnpm build' to rebuild them: ${error instanceof Error ? error.message : String(error)}`);

package/dist/docs/configuration.md

@@ -3,7 +3,7 @@
 **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
+> the declaration grammar). Fields and steps 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

package/dist/docs/installation.md

@@ -43,7 +43,8 @@ judge from your project's own installed package.
 From the project root:
 
 ```sh
-pnpm exec pdks init claude-code
+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`
@@ -51,9 +52,17 @@ 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.
 
-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:
+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 |
 |---|---|
@@ -64,6 +73,25 @@ config, and the discipline files are left alone, the settings file is merged, an
 | `.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
@@ -148,12 +176,12 @@ 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.
+- **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:
@@ -185,8 +213,9 @@ witness:
 
 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.
+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
 

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

@@ -21,11 +21,12 @@ agent-neutrality a claim a test can check rather than a slogan.
 | 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.
+umbrella, which keeps dependencies one-way, through the core alone. It names
+`@polydeukes/core` as a `peerDependency`: the vocabulary is shared with the judge, not
+installed a second time here.
 
 ## Payload translation and the three axes
 
@@ -39,7 +40,9 @@ umbrella, which keeps dependencies one-way, through the core alone.
 
 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.
+`blocked` record and exits `2`, rather than degrading into a guess. The envelope's top-level
+`agent_type` becomes the IR's `actor` — `{ agentType }` inside a subagent, `{}` otherwise;
+`tool_input` is never read for it, since that is the agent's own text.
 
 **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
@@ -62,7 +65,6 @@ the compiler the evidence is unjudgeable, so the entry skips instead of judging
 
 - **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.
 

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

@@ -23,12 +23,13 @@ AI or human.
 
 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.
+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, '<base>..<head>' | '<base>...<head>')` each return the same
+`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 |
@@ -52,7 +53,8 @@ and `staged-delete`. A deletion always carries its evidence. A write carries it
 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.
+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
@@ -87,9 +89,9 @@ 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 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.