polydeukes 0.6.1 → 0.8.0

package/dist/explain.js

@@ -9,15 +9,18 @@
  * nothing and reads no disk. Every failure throws: an answer that cannot be given is never
  * given halfway.
  */
-import { join } from 'node:path';
-import { resolveGitAdapterSettings } from '@polydeukes/adapter-git';
 import { AXIS_NAMES, deriveShape, noopTranscript, RELATION_NAMES } from '@polydeukes/core';
-import { assembleSessionRegistrations } from './claude-code-hook.js';
-import { assembleCommitRegistrations } from './covenant-check.js';
-import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
+import { covenantModule } from './covenant/module.js';
+import { assembleChangeSetRegistrations, assembleCheckRegistrations } from './covenant-check.js';
 import { loadConfig } from './load-config.js';
 /** The three meta-covenant labels: registrations that protect the judging chain itself. */
 const META_LABELS = new Set(['self-mod', 'shell-mod', 'transcript-mod']);
+/**
+ * What the session assembly here is given as its evidence path. The real one is loaded per
+ * call by an adapter, so this renderer names the IR key instead of a file: the assembly
+ * needs a present value to build the conditional registration, and nothing prints it.
+ */
+const SESSION_EVIDENCE_PATH_KEY = 'session.evidencePath';
 /**
  * The description of a declaration entry: its catalogue coordinate (the mechanism, the axes
  * its sources derive, and the relations its entries decide), then what it routes on, how
@@ -58,7 +61,7 @@ function row(kind, label, width, description) {
 /** The description of a meta-covenant registration — how much surface it covers. */
 function metaDescription(registration, surface) {
     if (registration.label === 'transcript-mod') {
-        return 'content predicate · conditional: transcript_path';
+        return 'content predicate · conditional: session.evidencePath';
     }
     return `paths ${registration.protectedPaths.length} (${surface})`;
 }
@@ -105,47 +108,59 @@ function renderSurface(spec) {
  * Read the config at `repoRoot`, assemble both surfaces, and render them.
  *
  * The session assembly is given a transcript path, so its `transcript-mod` registration
- * exists here exactly as it does under a normal hook payload — the path is never read,
+ * exists here exactly as it does under a normal call payload — the path is never read,
  * because the injected transcript is the no-op one.
  */
 export async function explain(spec) {
     const { config, configPath } = loadConfig({ rootDir: spec.repoRoot });
-    // Resolved and imported exactly as the two runners do, so what this renders is the table
-    // that would judge: a dist those runners would refuse cannot be rendered as if it worked.
-    // The load names the missing module and the recovery command.
-    const covenant = await loadCovenantModule(resolveCovenantDist());
-    const disciplines = config.disciplines ?? [];
+    // The judge module the two runners assemble against, so what this renders is the table
+    // that would judge.
+    const covenant = covenantModule;
+    const shared = config.disciplines ?? [];
+    const sessionOnly = config.sessionDisciplines ?? [];
+    const changeSetOnly = config.changeSetDisciplines ?? [];
     const drafts = config.drafts ?? [];
-    const session = assembleSessionRegistrations({
+    const session = assembleCheckRegistrations({
         config,
         rootDir: spec.repoRoot,
         covenant,
-        transcriptPath: join(spec.repoRoot, 'transcript.jsonl'),
+        surface: 'session',
+        // The session key alone, and no roster: a roster is what an adapter loads onto each
+        // call, so a reader of the config would be shown one agent's names chosen by this
+        // renderer. The evidence path is the same kind of per-call value and is named by the
+        // key rather than by a filename: what a config reader is being shown is that the
+        // session surface carries a transcript-mod registration, and the renderer prints the
+        // key, never the path. The empty lists are the session a run supplies.
+        session: { evidencePath: SESSION_EVIDENCE_PATH_KEY, userMessages: [], toolCalls: [] },
         transcript: noopTranscript,
     });
-    const commit = assembleCommitRegistrations({
+    const changeSet = assembleChangeSetRegistrations({
         config,
         rootDir: spec.repoRoot,
         covenant,
+        surface: 'changeSet',
     });
-    const gitSettings = resolveGitAdapterSettings({ namespace: config.adapters?.git });
     const text = [
         `pdks explain — ${configPath}`,
         '',
         renderSurface({
-            header: 'surface: session (claude-code hook) · disciplines: advise unless enforce: block · meta: block',
+            header: 'input: call IR (one call, stdin) · ' +
+                `disciplines ${shared.length} · sessionDisciplines ${sessionOnly.length} · ` +
+                'disciplines: advise unless enforce: block · meta: block',
             registrations: session,
             drafts,
-            disciplines,
+            disciplines: [...shared, ...sessionOnly],
             selfModScope: 'common; includes the config file itself',
         }),
         '',
         renderSurface({
-            header: `surface: commit (git pre-commit) · enforce: ${gitSettings.enforce} · disciplines: advise unless enforce: block`,
-            registrations: commit,
+            header: 'input: --diff (change set, stdin) · ' +
+                `disciplines ${shared.length} · changeSetDisciplines ${changeSetOnly.length} · ` +
+                'disciplines: advise unless enforce: block',
+            registrations: changeSet,
             drafts,
-            disciplines,
-            selfModScope: 'common ∪ adapters.git; deduped, includes the config file itself',
+            disciplines: [...shared, ...changeSetOnly],
+            selfModScope: 'common; includes the config file itself',
         }),
         '',
     ].join('\n');

package/dist/load-config.d.ts

@@ -4,7 +4,7 @@
  *
  * This lives in its own module rather than in the package barrel because ESM re-exports are
  * eager: importing `loadConfig` from the barrel would instantiate both composition roots,
- * putting the session adapter on the commit surface's load path where it is never used. A
+ * putting the session adapter on the change-set surface's load path where it is never used. A
  * workspace missing only that dist would then kill `pdks covenant check` before its
  * fail-closed handler could record a row. Both composition roots import this module directly
  * for the same reason.
@@ -20,6 +20,17 @@ export declare const CONFIG_FILENAMES: readonly ['polydeukes.config.yaml', 'poly
 export type LoadConfigSpec = {
     rootDir: string;
 };
+/** {@link discoverConfigPath} input — the directory the candidates are looked for in. */
+export type DiscoverConfigPathSpec = {
+    rootDir: string;
+};
+/** {@link parseConfigSource} input — the config text and the path it was discovered at. */
+export type ParseConfigSourceSpec = {
+    /** The config file's whole text. */
+    source: string;
+    /** rootDir-relative path the source came from — the self-protection entry and error context. */
+    configPath: string;
+};
 /** `LoadedConfig` — the loader's return value. */
 export type LoadedConfig = {
     /** defineConfig() resolution — protectedPaths already includes configPath */
@@ -43,3 +54,16 @@ export type LoadedConfig = {
  * protection surface, guaranteed here so no assembler has to remember.
  */
 export declare function loadConfig(spec: LoadConfigSpec): LoadedConfig;
+/**
+ * The discovery half: the rootDir-relative filename of the one candidate present, or the
+ * throw that names the zero or the collision. Exported so a caller that has to know WHICH
+ * file failed to load — the runner's config-repair branch — asks the same question the
+ * loader does rather than a second spelling of it.
+ */
+export declare function discoverConfigPath(spec: DiscoverConfigPathSpec): string;
+/**
+ * The parse-and-validate half, over a text rather than a file: parse, `$schema` strip,
+ * `defineConfig`, self-protection attach. Exported so the runner can ask whether a text a
+ * call is about to write would load, without opening any file.
+ */
+export declare function parseConfigSource(spec: ParseConfigSourceSpec): LoadedConfig;

package/dist/load-config.js

@@ -4,7 +4,7 @@
  *
  * This lives in its own module rather than in the package barrel because ESM re-exports are
  * eager: importing `loadConfig` from the barrel would instantiate both composition roots,
- * putting the session adapter on the commit surface's load path where it is never used. A
+ * putting the session adapter on the change-set surface's load path where it is never used. A
  * workspace missing only that dist would then kill `pdks covenant check` before its
  * fail-closed handler could record a row. Both composition roots import this module directly
  * for the same reason.
@@ -39,6 +39,17 @@ export const CONFIG_FILENAMES = [
  * protection surface, guaranteed here so no assembler has to remember.
  */
 export function loadConfig(spec) {
+    const configPath = discoverConfigPath({ rootDir: spec.rootDir });
+    const source = readFileSync(join(spec.rootDir, configPath), 'utf-8');
+    return parseConfigSource({ source, configPath });
+}
+/**
+ * The discovery half: the rootDir-relative filename of the one candidate present, or the
+ * throw that names the zero or the collision. Exported so a caller that has to know WHICH
+ * file failed to load — the runner's config-repair branch — asks the same question the
+ * loader does rather than a second spelling of it.
+ */
+export function discoverConfigPath(spec) {
     const { rootDir } = spec;
     const found = CONFIG_FILENAMES.filter((name) => existsSync(join(rootDir, name)));
     if (found.length === 0) {
@@ -47,8 +58,15 @@ export function loadConfig(spec) {
     if (found.length > 1) {
         throw new Error(`ambiguous Polydeukes config in ${rootDir} — found ${found.join(' and ')}; keep exactly one`);
     }
-    const configPath = found[0];
-    const source = readFileSync(join(rootDir, configPath), 'utf-8');
+    return found[0];
+}
+/**
+ * The parse-and-validate half, over a text rather than a file: parse, `$schema` strip,
+ * `defineConfig`, self-protection attach. Exported so the runner can ask whether a text a
+ * call is about to write would load, without opening any file.
+ */
+export function parseConfigSource(spec) {
+    const { source, configPath } = spec;
     // Default core schema — custom tags stay unresolved and surface as errors or
     // warnings depending on version; both escalate to a throw (config-as-data:
     // uncomputable, so it cannot lie).

package/dist/pre-state-reader.d.ts

@@ -13,7 +13,7 @@
  */
 export declare function sessionPreStateReader(location: string): string | null | undefined;
 /**
- * The commit surface's reader: it observes a staged diff, whose payloads already carry the
+ * The change-set surface's reader: it observes a staged diff, whose payloads already carry the
  * pre their own observation saw, and it registers no shell axis — so no derivation ever asks
  * for a pre-state here. Should one arrive, the working tree is not what this surface judges,
  * and answering from it would compare the diff against the wrong baseline; `undefined` says

package/dist/pre-state-reader.js

@@ -21,7 +21,7 @@ export function sessionPreStateReader(location) {
     }
 }
 /**
- * The commit surface's reader: it observes a staged diff, whose payloads already carry the
+ * The change-set surface's reader: it observes a staged diff, whose payloads already carry the
  * pre their own observation saw, and it registers no shell axis — so no derivation ever asks
  * for a pre-state here. Should one arrive, the working tree is not what this surface judges,
  * and answering from it would compare the diff against the wrong baseline; `undefined` says

package/dist/scaffold-project.d.ts

@@ -3,8 +3,8 @@
  *
  * The half of an installation every distribution path shares: the data config the judges
  * read, and the telemetry ignore line. What differs between paths is REGISTRATION — how the
- * agent is told to spawn a judge at all — and that lives one layer up (`initClaudeCode` for
- * the `init` path). The split is what lets a second path reuse this function unchanged
+ * agent is told to spawn a judge at all — and that lives in each agent's own adapter
+ * installer. The split is what lets a second path reuse this function unchanged
  * instead of scaffolding a config a second time, so nothing that registers anything belongs
  * here.
  *

package/dist/scaffold-project.js

@@ -3,8 +3,8 @@
  *
  * The half of an installation every distribution path shares: the data config the judges
  * read, and the telemetry ignore line. What differs between paths is REGISTRATION — how the
- * agent is told to spawn a judge at all — and that lives one layer up (`initClaudeCode` for
- * the `init` path). The split is what lets a second path reuse this function unchanged
+ * agent is told to spawn a judge at all — and that lives in each agent's own adapter
+ * installer. The split is what lets a second path reuse this function unchanged
  * instead of scaffolding a config a second time, so nothing that registers anything belongs
  * here.
  *
@@ -32,7 +32,7 @@ const GITIGNORE_ENTRY = `# Polydeukes telemetry — local observation data, neve
  * {@link schemaDirective} prepends the `yaml-language-server` line when the schema is where
  * that line would name it.
  */
-const GENERATED_CONFIG = `# Polydeukes protection policy — generated by \`pdks init claude-code\`.
+const GENERATED_CONFIG = `# Polydeukes protection policy — generated by \`pdks init\`.
 #
 # This file is data, never code. The judges read it, every verdict traces back to an entry
 # below, and editing it is how you change what is judged.
@@ -50,7 +50,8 @@ languages:
 # The protection list. A tool call whose proven target is one of these paths is blocked, and
 # so is a shell command that mentions one without a read-only head.
 #
-#   .claude/hooks, .claude/settings.json, .grok/hooks — the gate definitions themselves.
+#   .claude/hooks, .claude/settings.json, .grok/hooks, .codex/hooks — the gate definitions
+#     themselves.
 #     Editing them does not evade a judgment, it removes the judgment; the session surface
 #     is the only layer that can watch it happen.
 #
@@ -62,6 +63,7 @@ protectedPaths:
   - '.claude/hooks'
   - '.claude/settings.json'
   - '.grok/hooks'
+  - '.codex/hooks'
 
 # The time-boxed witness — the human valve on a blocked verdict. A human types this token so
 # it stands alone on a message's FIRST line, the window holds for ttlMinutes, then blocking
@@ -79,6 +81,12 @@ witness:
 # The disciplines you judge by, and the three rungs one climbs — shown as three entries so
 # each rung is a line you can copy. Uncomment to start; ids must stay distinct.
 #
+# Three lists, chosen by what a declaration reads. \`disciplines:\` is judged on both
+# surfaces (the changed file's own pre/post and file sources). \`sessionDisciplines:\` is
+# judged only where a live call is observed before it runs (command line, transcript,
+# actor). \`changeSetDisciplines:\` is judged only over a finished change set
+# (\`--diff\`). The loader refuses an entry written in a list its channels do not fit.
+#
 # disciplines:
 #   # A draft: prose only, no predicate. Registered and read, never judged.
 #   - id: 'no-todo-in-shipped-code-draft'

package/dist/schema/polydeukes.schema.json

@@ -33,6 +33,18 @@
       "uniqueItems": true,
       "items": { "$ref": "#/$defs/discipline" }
     },
+    "sessionDisciplines": {
+      "description": "Disciplines only the session surface observes — every entry whose declaration binds a transcript, channel, command, or actor evidence channel. Fully identical entries are copy-paste duplicates (by-id uniqueness and the placement rule are enforced by the runtime validator).",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/discipline" }
+    },
+    "changeSetDisciplines": {
+      "description": "Disciplines only the change-set surface observes — every entry whose declaration binds the changes source. Fully identical entries are copy-paste duplicates (by-id uniqueness and the placement rule are enforced by the runtime validator).",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/discipline" }
+    },
     "witness": { "$ref": "#/$defs/witness" }
   },
   "$defs": {

package/dist/worktree-reader.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The change-set surface's supply body for named file sources — one repo-relative path read from
+ * the working tree.
+ */
+import type { SourceReader } from '@polydeukes/core';
+/** {@link worktreeReader} input — the repository the paths are relative to. */
+export type WorktreeReaderSpec = {
+    repoRoot: string;
+};
+/**
+ * A reader over the working tree under `repoRoot`, with the same absence table the session
+ * surface's disk reader pins in its own package.
+ *
+ * Symlinks are followed: on disk the observable fact IS the target's text, and the session
+ * surface reads the same way. A path the tree holds but cannot give as judgeable text —
+ * a directory, or bytes carrying a NUL — answers `undefined`, which the declaration's
+ * `supply` policy disposes of.
+ */
+export declare function worktreeReader(spec: WorktreeReaderSpec): SourceReader;

package/dist/worktree-reader.js

@@ -0,0 +1,30 @@
+/**
+ * The change-set surface's supply body for named file sources — one repo-relative path read from
+ * the working tree.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * A reader over the working tree under `repoRoot`, with the same absence table the session
+ * surface's disk reader pins in its own package.
+ *
+ * Symlinks are followed: on disk the observable fact IS the target's text, and the session
+ * surface reads the same way. A path the tree holds but cannot give as judgeable text —
+ * a directory, or bytes carrying a NUL — answers `undefined`, which the declaration's
+ * `supply` policy disposes of.
+ */
+export function worktreeReader(spec) {
+    return (path) => {
+        let bytes;
+        try {
+            bytes = readFileSync(join(spec.repoRoot, path));
+        }
+        catch (error) {
+            const { code } = error;
+            if (code === 'ENOENT' || code === 'EISDIR' || code === 'ENOTDIR')
+                return undefined;
+            throw error;
+        }
+        return bytes.includes(0) ? undefined : bytes.toString('utf-8');
+    };
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "polydeukes",
-  "version": "0.6.1",
-  "description": "A development discipline framework for building alongside an AI coding partner — deterministic covenants, a verifiable work ledger, local memory, and adversarial verification. Alpha.",
+  "version": "0.8.0",
+  "description": "A development discipline framework for building alongside an AI coding partner — deterministic covenants, a verifiable work ledger, local memory, and adversarial verification. Beta.",
+  "author": "huskyhoochu <dfg1499@gmail.com>",
   "keywords": [
     "harness",
     "guard",
@@ -28,18 +29,7 @@
     "pdks": "./dist/bin.js",
     "polydeukes": "./dist/bin.js"
   },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./claude-code": {
-      "types": "./dist/claude-code.d.ts",
-      "import": "./dist/claude-code.js"
-    },
     "./schema.json": "./dist/schema/polydeukes.schema.json"
   },
   "files": [
@@ -54,15 +44,12 @@
   },
   "dependencies": {
     "yaml": "2.9.0",
-    "@polydeukes/adapter-claude-code": "^0.6.1",
-    "@polydeukes/core": "^0.6.1",
-    "@polydeukes/covenant": "^0.6.1",
-    "@polydeukes/adapter-git": "^0.6.1"
+    "@polydeukes/core": "^0.8.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "typescript": "7.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/copy-docs.mjs && node scripts/copy-schema.mjs",

package/dist/claude-code-hook.d.ts

@@ -1,79 +0,0 @@
-/**
- * `runClaudeCodeHook` — the assembled session-surface judgment runner.
- *
- * The session counterpart of {@link runCovenantCheck}, and the one place where the Claude
- * Code adapter (tool vocabulary, up-translation) and the covenant package (dispatcher +
- * judge bodies) meet. Packages stay one-way — each depends only on core — so their
- * composition lives here, in the umbrella, and the repository's PreToolUse hook shrinks to
- * a delegator that calls this function. That is what makes the session surface installable:
- * a consumer registers a hook that resolves this package instead of copying assembly.
- *
- * The protection-policy data (protectedPaths / disciplines / witness) is read from the root
- * data config through {@link loadConfig}, which also attaches the config file to its own
- * surface.
- *
- * The valve is the TTL witness, judged over the JSONL transcript provider. The judge body
- * always spawns, and only an outcome that translated to blocked consults the witness —
- * `witnessed` rows are would-block only. Its defence is provenance rather than secrecy: only
- * a real human utterance carries the transcript marking `findUserMessages()` admits.
- *
- * fail-closed: ANY failure — an unbuilt judge body, an unreadable stdin, a missing or
- * invalid config file — resolves to `{ exitCode: 2 }` with one `blocked` record under the
- * `hook` label. Nothing throws: an uncaught rejection would exit the delegator non-blocking,
- * the cheapest bypass vector there is. Recovery from an unbuilt clone is `pnpm build` (it
- * mentions no protected path, so it is never blocked).
- */
-import { type CanonicalTranscript } from '@polydeukes/core';
-import { type CovenantRegistration } from '@polydeukes/covenant';
-import { type CovenantModule } from './covenant-module.ts';
-import { loadConfig } from './load-config.ts';
-/** {@link runClaudeCodeHook} result — the exit code the hook process leaves with. */
-export type ClaudeCodeHookOutcome = {
-    exitCode: 0 | 2;
-};
-/** `runClaudeCodeHook` input — the `CovenantCheckSpec` shape, session side. */
-export type ClaudeCodeHookSpec = {
-    /** Repository root — config discovery and discipline glob scoping both anchor here. */
-    repoRoot: string;
-    /** One raw PreToolUse payload. ABSENT means read fd 0 (the hook's real stdin). */
-    rawPayload?: string;
-    /** Overrides the config's telemetry log path (tests and assembly injection). */
-    telemetryPath?: string;
-    /** Overrides the resolved covenant dist directory (tests and assembly injection). */
-    covenantDist?: string;
-};
-/** {@link assembleSessionRegistrations} input — what the session surface's assembly needs. */
-export type SessionAssemblySpec = {
-    config: ReturnType<typeof loadConfig>['config'];
-    rootDir: string;
-    /**
-     * The covenant surface the registrations are built from — the module the caller loaded
-     * from the resolved dist, so what judges a call is what that dist carries, and what
-     * `explain` renders is what would judge it.
-     */
-    covenant: CovenantModule;
-    /** The payload's transcript path. ABSENT leaves the transcript-mod registration out. */
-    transcriptPath?: string;
-    transcript?: CanonicalTranscript;
-    witness?: CovenantRegistration['witness'];
-};
-/**
- * The session surface's registration set. One assembly, two consumers: the runner below
- * dispatches it, `explain` renders it — so what a reader is shown is the table the judgment
- * actually uses, never a second opinion about it.
- */
-export declare function assembleSessionRegistrations(spec: SessionAssemblySpec): CovenantRegistration[];
-/**
- * The session-surface entry point: the post-hoc state comparison wrapped around the judgment.
- *
- * The comparison sits OUTSIDE {@link judgeHookCall}'s fail-closed try on both ends. Inside
- * it, a comparison failure would become a blocked call — the opposite of a mechanism whose
- * whole purpose is to record rather than stop — so each side carries its own catch and
- * neither can reach the verdict. Observation is fail-open, the direction
- * `appendRecordFailOpen` already established: the worst outcome is a missing datum.
- *
- * Order is the contract. The comparison runs first, so it reads the window the previous call
- * left and its rows land ahead of this call's judgment; the re-establishment runs last, so
- * this call's own judged writes are folded in rather than alarmed on next time.
- */
-export declare function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<ClaudeCodeHookOutcome>;