polydeukes 0.6.0 → 0.7.1

package/dist/diff-ir.js

@@ -0,0 +1,310 @@
+/**
+ * unified diff → `CovenantInput`. One pure translation, no judgment and no disk.
+ *
+ * The accepted grammar is finite: `diff --git` blocks and header-less `---`/`+++` blocks,
+ * covering creation, deletion, modification, mode-only changes, renames, and binary blobs.
+ * Anything else throws, so an unrecognised shape fails the run closed instead of translating
+ * to a partial observation.
+ *
+ * A modification's `pre`/`post` are the hunk's `-` and `+` lines, never the whole file: a
+ * unified diff carries the changed lines and the context around them, and reconstructing the
+ * file from them is not a translation. A creation and a deletion carry the whole text because
+ * every line of the file is in the hunk.
+ */
+/** The tool name a staged write is dispatched under — telemetry and configs read it. */
+export const STAGED_WRITE = 'staged-write';
+/** The tool name a staged deletion is dispatched under. */
+export const STAGED_DELETE = 'staged-delete';
+function emptyBlock() {
+    return { binary: false, deletedFile: false, newFile: false, removed: [], added: [] };
+}
+/** A path as git prints it after `rename from` / `rename to`: quoted only when it has to be. */
+function readBarePath(raw) {
+    return raw.startsWith('"') ? unquotePath(raw) : raw;
+}
+/**
+ * Decode git's C-quoted path form: the octal escapes are BYTES of the path, so they are
+ * collected and decoded as UTF-8 together — decoding each one on its own would turn every
+ * non-ASCII character into replacement characters.
+ */
+function unquotePath(quoted) {
+    const body = quoted.slice(1, -1);
+    const bytes = [];
+    for (let at = 0; at < body.length; at += 1) {
+        const char = body[at];
+        if (char !== '\\') {
+            bytes.push(...Buffer.from(char, 'utf-8'));
+            continue;
+        }
+        const next = body[at + 1];
+        const octal = body.slice(at + 1, at + 4);
+        if (/^[0-7]{3}$/.test(octal)) {
+            bytes.push(Number.parseInt(octal, 8));
+            at += 3;
+            continue;
+        }
+        const simple = {
+            t: 0x09,
+            n: 0x0a,
+            r: 0x0d,
+            '"': 0x22,
+            '\\': 0x5c,
+        };
+        bytes.push(simple[next] ?? Buffer.from(next, 'utf-8')[0] ?? 0);
+        at += 1;
+    }
+    return Buffer.from(bytes).toString('utf-8');
+}
+/**
+ * The path a `---`/`+++` line names, or null for `/dev/null`. A quoted path is unquoted
+ * before anything is cut, because a quoted path may itself contain a tab; an unquoted one is
+ * cut at the tab `diff -u` puts its timestamp behind. Exactly one `a/` or `b/` level is
+ * stripped, so a repository directory literally named `a/` survives.
+ */
+function readPath(rest, prefix) {
+    let path;
+    if (rest.startsWith('"')) {
+        const end = rest.lastIndexOf('"');
+        path = unquotePath(rest.slice(0, end + 1));
+    }
+    else {
+        const tab = rest.indexOf('\t');
+        path = tab === -1 ? rest : rest.slice(0, tab);
+    }
+    if (path === '/dev/null')
+        return null;
+    return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+/** The two paths of a `diff --git a/X b/Y` header, or undefined when they cannot be read. */
+function readHeaderPaths(rest) {
+    if (rest.startsWith('"')) {
+        const end = rest.indexOf('" "');
+        if (end === -1)
+            return undefined;
+        const old = unquotePath(rest.slice(0, end + 1));
+        const next = unquotePath(rest.slice(end + 2));
+        return { old: stripOnce(old, 'a/'), new: stripOnce(next, 'b/') };
+    }
+    // Unquoted paths may contain spaces, and git writes no separator between the two. The
+    // halves are equal in length whenever the prefixes are, which is git's own output; the
+    // midpoint split is what recovers them.
+    const middle = rest.length % 2 === 1 ? (rest.length - 1) / 2 : -1;
+    if (middle > 0 && rest[middle] === ' ') {
+        return {
+            old: stripOnce(rest.slice(0, middle), 'a/'),
+            new: stripOnce(rest.slice(middle + 1), 'b/'),
+        };
+    }
+    const at = rest.indexOf(' ');
+    if (at === -1)
+        return undefined;
+    return { old: stripOnce(rest.slice(0, at), 'a/'), new: stripOnce(rest.slice(at + 1), 'b/') };
+}
+function stripOnce(path, prefix) {
+    return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+/** The old and new line counts a hunk header declares, or undefined when it is not one. */
+function readHunkCounts(line) {
+    const match = /^@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@/.exec(line);
+    if (match === null)
+        return undefined;
+    return {
+        old: match[1] === undefined ? 1 : Number.parseInt(match[1], 10),
+        new: match[2] === undefined ? 1 : Number.parseInt(match[2], 10),
+    };
+}
+/**
+ * Split the text into file blocks, reading hunk bodies by the line counts their headers
+ * declare. The counts are what keeps a removed `-- note` line (which reads as `--- note`)
+ * from being taken for a new file header: header lines are only recognised outside a hunk.
+ */
+function parseBlocks(text) {
+    const lines = text.split('\n');
+    const blocks = [];
+    let block;
+    const open = () => {
+        if (block === undefined) {
+            block = emptyBlock();
+            blocks.push(block);
+        }
+        return block;
+    };
+    for (let at = 0; at < lines.length; at += 1) {
+        const line = lines[at];
+        if (line === '' && at === lines.length - 1)
+            continue;
+        if (line.startsWith('diff --cc ') || line.startsWith('diff --combined ')) {
+            throw new Error(`unified diff: combined diffs are not translatable: ${line}`);
+        }
+        if (line.startsWith('diff --git ')) {
+            block = emptyBlock();
+            blocks.push(block);
+            block.headerPaths = readHeaderPaths(line.slice('diff --git '.length));
+            continue;
+        }
+        if (line.startsWith('--- ')) {
+            // A second `---` outside a hunk starts a new header-less block.
+            if (block !== undefined && block.oldPath !== undefined)
+                block = undefined;
+            open().oldPath = readPath(line.slice(4), 'a/');
+            continue;
+        }
+        if (line.startsWith('+++ ')) {
+            const current = open();
+            if (current.oldPath === undefined) {
+                throw new Error(`unified diff: '+++' line with no '---' partner: ${line}`);
+            }
+            current.newPath = readPath(line.slice(4), 'b/');
+            continue;
+        }
+        const counts = readHunkCounts(line);
+        if (counts !== undefined) {
+            const current = open();
+            if (current.oldPath === undefined || current.newPath === undefined) {
+                if (current.headerPaths === undefined) {
+                    throw new Error(`unified diff: hunk with no file header: ${line}`);
+                }
+            }
+            let oldLeft = counts.old;
+            let newLeft = counts.new;
+            while ((oldLeft > 0 || newLeft > 0) && at + 1 < lines.length) {
+                const body = lines[at + 1];
+                at += 1;
+                if (body.startsWith('\\'))
+                    continue;
+                // A line the declared counts have no room for is a malformed hunk: judging the
+                // lines that fit and dropping the rest would be an observation smaller than the
+                // input, so the whole run fails closed instead.
+                if (body.startsWith('+') && newLeft > 0) {
+                    current.added.push(body.slice(1));
+                    newLeft -= 1;
+                    continue;
+                }
+                if (body.startsWith('-') && oldLeft > 0) {
+                    current.removed.push(body.slice(1));
+                    oldLeft -= 1;
+                    continue;
+                }
+                if ((body.startsWith(' ') || body === '') && oldLeft > 0 && newLeft > 0) {
+                    oldLeft -= 1;
+                    newLeft -= 1;
+                    continue;
+                }
+                throw new Error(`unified diff: unknown hunk line: ${body}`);
+            }
+            continue;
+        }
+        if (line.startsWith('rename from ')) {
+            open().renameFrom = readBarePath(line.slice('rename from '.length));
+            continue;
+        }
+        if (line.startsWith('rename to ')) {
+            open().renameTo = readBarePath(line.slice('rename to '.length));
+            continue;
+        }
+        if (line.startsWith('deleted file mode ')) {
+            open().deletedFile = true;
+            continue;
+        }
+        if (line.startsWith('new file mode ')) {
+            open().newFile = true;
+            continue;
+        }
+        if (line.startsWith('Binary files ') || line === 'GIT binary patch') {
+            const current = open();
+            current.binary = true;
+            if (line.endsWith('and /dev/null differ'))
+                current.deletedFile = true;
+        }
+        // Everything else outside a hunk is an extended header line (`index`, `old mode`,
+        // `similarity index`, a binary patch's base85 payload) that names nothing this
+        // translation reads.
+    }
+    return blocks;
+}
+/** The toolCalls one block translates to, in the order the judgment sees them. */
+function blockToolCalls(block) {
+    const { renameFrom, renameTo } = block;
+    if (renameFrom !== undefined && renameTo !== undefined) {
+        return [
+            {
+                name: STAGED_DELETE,
+                args: { file_path: renameFrom },
+                fileChange: { kind: 'delete', path: renameFrom },
+            },
+            {
+                name: STAGED_WRITE,
+                args: { file_path: renameTo },
+                fileChange: {
+                    kind: 'modify',
+                    path: renameTo,
+                    pre: block.removed.join('\n'),
+                    post: block.added.join('\n'),
+                },
+            },
+        ];
+    }
+    // An empty file's deletion or creation carries no `---`/`+++` pair and no hunk, so the
+    // mode line is the only evidence of which one it is.
+    const deletion = block.newPath === null || block.deletedFile;
+    const path = deletion
+        ? (block.oldPath ?? block.headerPaths?.old)
+        : (block.newPath ?? block.headerPaths?.new);
+    if (path === undefined || path === null) {
+        throw new Error('unified diff: a file block names no path');
+    }
+    if (block.binary) {
+        return [{ name: deletion ? STAGED_DELETE : STAGED_WRITE, args: { file_path: path } }];
+    }
+    if (deletion) {
+        return [
+            {
+                name: STAGED_DELETE,
+                args: { file_path: path },
+                fileChange: { kind: 'delete', path, pre: block.removed.join('\n') },
+            },
+        ];
+    }
+    if (block.oldPath === null || block.newFile) {
+        return [
+            {
+                name: STAGED_WRITE,
+                args: { file_path: path },
+                fileChange: { kind: 'create', path, post: block.added.join('\n') },
+            },
+        ];
+    }
+    return [
+        {
+            name: STAGED_WRITE,
+            args: { file_path: path },
+            fileChange: {
+                kind: 'modify',
+                path,
+                pre: block.removed.join('\n'),
+                post: block.added.join('\n'),
+            },
+        },
+    ];
+}
+/**
+ * Translate a unified diff into the covenant input IR: one toolCall per file block in input
+ * order (a rename is two, the deletion first), and no `actor` key — a diff proves no author.
+ */
+export function covenantInputFromUnifiedDiff(spec) {
+    const blocks = parseBlocks(spec.text);
+    // Text that is not blank yet contains no block the grammar recognizes — a colored diff,
+    // a pager banner, anything else — must not translate to "nothing staged": an empty
+    // observation is a pass, and this input may describe a whole commit.
+    if (blocks.length === 0 && spec.text.trim() !== '') {
+        throw new Error('unified diff: no file block recognized in the input');
+    }
+    const toolCalls = [];
+    for (const block of blocks) {
+        if (block.oldPath !== undefined && block.newPath === undefined) {
+            throw new Error(`unified diff: '---' line with no '+++' partner: ${block.oldPath}`);
+        }
+        toolCalls.push(...blockToolCalls(block));
+    }
+    return { toolCalls, subagentSpawns: [], userMessages: [] };
+}

package/dist/docs/README.ko.md

@@ -0,0 +1,60 @@
+# 폴리데우케스 문서
+
+[English](./README.md) · **한국어**
+
+> AI 코딩 파트너와 함께 개발하기 위한 규율 프레임워크입니다. 궁금한 곳부터 읽으십시오.
+
+<a id="start-here"></a>
+## 여기서 시작하십시오
+
+| 하려는 것 | 읽을 문서 |
+|---|---|
+| 첫 눈에 보이는 판정을 보고 싶다 | [첫 판정](./tutorials/first-judgment.ko.md) — 설치하고 Claude Code를 배선한 뒤 보호된 편집이 판정되는 모습을 봅니다 |
+| Claude Code, Grok, git을 연결하고 싶다 | [표면 연결하기](./how-to/connect-surfaces.ko.md) — 세션과 커밋 배선, Grok 포함 |
+| 프로젝트 설정을 다듬고 싶다 | [프로젝트 설정하기](./how-to/configure-project.ko.md) — 발견, IDE 지원, advise와 block의 선택 |
+| 실제 규율을 쓰고 싶다 | [규율 작성하기](./how-to/write-disciplines.ko.md) — 실전 선언 예제, 특히 locale key pairing |
+| 차단이나 건너뜀에서 회복하고 싶다 | [문제 해결](./troubleshooting.ko.md) — fail-closed 상태, 증인 밸브, 로그 |
+| 이 프레임워크가 왜 있는지 알고 싶다 | [왜 폴리데우케스인가?](./why-polydeukes.ko.md) — 설계 백서 |
+| 이 문서에 기여하고 싶다 | [문서에 기여하기](./contributing.ko.md) — 영한 쌍, 안정 ID, 카탈로그, 검사 |
+
+<a id="reference"></a>
+## 레퍼런스
+
+설정 키, 하위 명령, 종료 코드를 설명합니다. 계획이 아니라 현재 동작을 기준으로 서술합니다.
+
+| 문서 | 답하는 것 |
+|---|---|
+| [설정 레퍼런스](./reference/configuration/index.ko.md) | `polydeukes.config.yaml`에 무엇을 넣을 수 있고 각 키가 무엇을 하는지 |
+| [`polydeukes` (`pdks` CLI)](./reference/packages/polydeukes.ko.md) | 패키지 계약과 그 안에 있는 판정기. 서브커맨드는 [`reference/cli/`](./reference/cli/covenant-check.ko.md) |
+| [`@polydeukes/core`](./reference/packages/core.ko.md) | 프로토콜, 입력 IR, 설정 스키마, 텔레메트리 |
+| [`@polydeukes/adapter-claude-code`](./reference/packages/adapter-claude-code.ko.md) | Claude Code 세션 표면입니다. 훅 페이로드에서 입력 IR로 |
+| [`@polydeukes/adapter-grok`](./reference/packages/adapter-grok.ko.md) | Grok 세션 표면입니다. 훅 페이로드에서 입력 IR로 |
+
+<a id="shape-of-the-thing"></a>
+## 한 페이지로 보는 구조
+
+폴리데우케스는 개발자나 AI 에이전트가 하려는 일을 판정하고 결과를 기록합니다.
+기본값으로는 작업을 차단하지 않습니다. 설계의 바탕은 다음 세 가지입니다.
+
+**약속은 가두기 위한 울타리가 아닙니다.** 여기서 확인하는 규율은 개발자가 이미 스스로 지켜 온 것들입니다. AI에게만큼 사람에게도 똑같이 적용되고, 프레임워크를 만든
+사람도 매일 그 판정을 받습니다.
+
+**판정과 차단은 별개의 결정입니다.** 선언된 규율은 적용 범위에 해당하는 호출마다 판정합니다.
+위반했을 때 호출을 차단할지는 별도로 정합니다. 기본값으로는 사유를 기록하고 호출을 계속합니다.
+작성자는 `enforce: block`으로 차단을 선택할 수 있습니다. 별도 선택 없이 차단하는 것은
+프레임워크 자체를 보호하는 경우뿐입니다.
+
+**모든 판정은 행 하나를 남깁니다.** `.polydeukes/roi.log`가 판정 결과마다 한 줄씩, 낱말 여섯 개짜리 어휘로 담습니다. 이 프로젝트가 자기 결함을 찾는
+방법이 그 기록입니다. 백서에 적힌 결함들도 전부 코드를 읽어서가 아니라 행을 세어서 나왔습니다.
+
+<a id="two-surfaces"></a>
+## 두 표면
+
+| 표면 | 판정 대상 | 배선 방법 | 대상 |
+|---|---|---|---|
+| **세션** | 도구 호출, 실행되기 전에 | `pdks-claude-code init` 또는 `pdks-grok init` | AI 파트너와 함께 개발하는 프로젝트 |
+| **커밋** | stdin의 unified diff — 스테이징 영역, 작업 트리, ref 범위 | `git diff --cached`를 파이프로 넘기는 pre-commit 훅, 또는 필요할 때 직접 실행 | 혼자 개발하는 사람, 그리고 CI |
+
+커밋 판정기는 필요할 때 직접 실행할 수도 있습니다. 작업 후에는 `git diff HEAD | pdks covenant check --diff`,
+PR 전에는 `git diff main...HEAD | …`를 사용합니다. 같은 판정 기준을 종료 코드로 답하며 묻지
+않습니다. 관문은 그 코드를 소비하는 쪽입니다.

package/dist/docs/README.md

@@ -0,0 +1,64 @@
+# Polydeukes documentation
+
+**English** · [한국어](./README.ko.md)
+
+> A development discipline framework for building alongside an AI coding partner. Start where your
+question is.
+
+<a id="start-here"></a>
+## Start here
+
+| If you want to | Read |
+|---|---|
+| Get to a first visible judgment | [First judgment](./tutorials/first-judgment.md) — install, wire Claude Code, and watch one protected edit get judged |
+| Connect Claude Code, Grok, or git | [Connect the surfaces](./how-to/connect-surfaces.md) — session and commit setup, including Grok |
+| Shape the project config | [Configure the project](./how-to/configure-project.md) — discovery, IDE support, and advise versus block |
+| Write a real discipline | [Write disciplines](./how-to/write-disciplines.md) — worked declarations, especially locale key pairing |
+| Recover from a block or skip | [Troubleshooting](./troubleshooting.md) — the fail-closed states, the witness valve, and the log |
+| Understand why the framework exists | [Why Polydeukes?](./why-polydeukes.md) — the design whitepaper |
+| Contribute to these docs | [Contributing](./contributing.md) — bilingual pairs, stable IDs, catalog, and checks |
+
+<a id="reference"></a>
+## Reference
+
+Every key, every subcommand, every exit code. These describe the present state only — nothing here
+is aspirational.
+
+| Document | Answers |
+|---|---|
+| [Configuration reference](./reference/configuration/index.md) | What may go in `polydeukes.config.yaml`, and what each key does |
+| [`polydeukes` (the `pdks` CLI)](./reference/packages/polydeukes.md) | Package contract, and the judge that lives inside it; subcommands live under [`reference/cli/`](./reference/cli/covenant-check.md) |
+| [`@polydeukes/core`](./reference/packages/core.md) | The protocol, the input IR, the config schema, telemetry |
+| [`@polydeukes/adapter-claude-code`](./reference/packages/adapter-claude-code.md) | Claude Code session surface — hook payloads become the input IR |
+| [`@polydeukes/adapter-grok`](./reference/packages/adapter-grok.md) | Grok session surface — hook payloads become the input IR |
+
+<a id="shape-of-the-thing"></a>
+## The shape of the thing, in one page
+
+Polydeukes judges what a developer or an AI agent is about to do, records the verdict, and by
+default lets the work proceed. Three ideas carry the rest.
+
+**A covenant is a promise, not a fence.** The disciplines it enforces are the ones a good developer
+already imposes on themselves. They bind the human exactly as much as the AI, and the framework's
+own authors get judged by them daily.
+
+**Judging and stopping are separate decisions.** Every declared discipline is judged on every
+matching call. What a break then does is a second question: by default it is recorded with its
+reason and the call continues. `enforce: block` is a promotion the author chooses. The only things
+that stop a call unasked are the framework's own protections.
+
+**Every judgment leaves a row.** `.polydeukes/roi.log` holds one line per verdict, in a vocabulary
+of six words. That record is how this project finds its own defects — including the ones described
+in the whitepaper, which were all found by counting rows rather than by reading code.
+
+<a id="two-surfaces"></a>
+## Two surfaces
+
+| Surface | Judges | Wired by | For |
+|---|---|---|---|
+| **Session** | A tool call, before it runs | `pdks-claude-code init` or `pdks-grok init` | A project developed with an AI partner |
+| **Commit** | A unified diff on stdin — staged, the working tree, or a ref range | A pre-commit hook piping `git diff --cached`, or run on demand | A human developing alone, and CI |
+
+The commit judge also answers on demand: `git diff HEAD | pdks covenant check --diff` after a task,
+`git diff main...HEAD | …` before a PR. Same verdict a commit would receive, delivered as an exit
+code with no prompt — the gate is whatever consumes that code.