polydeukes 0.8.0 → 0.10.0

package/dist/covenant/shell-mod.d.ts

@@ -4,7 +4,7 @@
  * Analyzes the command-line strings of *shell* tool calls (names and arg keys are injected
  * values, never source literals) per simple command: the fixed detection rules catch writes
  * to a protected path, undecidable structures (opaque mentions, opaque write targets) fail
- * closed, the read-only allowlist absolves proven reads, and every other protected-path
+ * closed, read-only proof absolves safe reads, and every other protected-path
  * mention breaks — "mention + unproven = block". It judges only its own axis: a non-shell
  * tool call is upheld, since the tool axis belongs to the self-mod meta-covenant and
  * run-all co-existence depends on that boundary.
@@ -18,7 +18,7 @@ import type { CovenantRegistration, MetaCovenantRegistration } from './dispatch.
  * `protectedPaths` are literal path strings; `shellToolNames` are the tool names whose
  * calls carry shell lines; `commandArgNames` are the `args` keys those lines live under;
  * `readOnlyCommands` are allowlist entries — space-separated word sequences (`'cat'`,
- * `'git diff'`). Empty-string entries in every list are ignored (an unguarded `''` would
+ * `'git status'`). Empty-string entries in every list are ignored (an unguarded `''` would
  * match every path / tool / arg / command).
  */
 export type ShellModificationSpec = {
@@ -38,6 +38,16 @@ export type ShellModificationSpec = {
  * redirect-free truncating write. `git status`/`git grep` reject `--output`, so they stay.
  */
 export declare const DEFAULT_READ_ONLY_COMMANDS: string[];
+/**
+ * True when a configured allowlist has the same effective entries as the shipped default.
+ * Conditional readers belong to that default contract and stay disabled for replacements.
+ */
+export declare function usesDefaultReadOnlyCommands(commands: string[]): boolean;
+/**
+ * Prove the finite argument-sensitive readers that cannot be represented by a leading-word
+ * allowlist. Every word must be transparent because these readers inspect their later words.
+ */
+export declare function matchesConditionalReadOnlyCommand(command: SimpleCommand): boolean;
 /**
  * True when the command's leading words match the allowlist entry's word sequence. Exported
  * so the transcript judge's allowlist clause absolves reads by this exact comparison instead
@@ -59,8 +69,9 @@ export declare function judgeShellModification(input: CovenantInput, spec: Shell
 /**
  * `ShellModRegistrationSpec` — the assembly values baked into the registration. The call
  * set is not among them: the dispatcher supplies it to the judge at call time.
- * `readOnlyCommands` REPLACES {@link DEFAULT_READ_ONLY_COMMANDS} when given — no merge,
- * since an assembly wanting to extend the default spreads the constant.
+ * `readOnlyCommands` REPLACES {@link DEFAULT_READ_ONLY_COMMANDS} when given — no merge.
+ * Any replacement, including a superset made by spreading the default, disables the finite
+ * argument-sensitive readers because their proof belongs to the exact shipped default.
  */
 export type ShellModRegistrationSpec = {
     protectedPaths: string[];

package/dist/covenant/shell-mod.js

@@ -4,7 +4,7 @@
  * Analyzes the command-line strings of *shell* tool calls (names and arg keys are injected
  * values, never source literals) per simple command: the fixed detection rules catch writes
  * to a protected path, undecidable structures (opaque mentions, opaque write targets) fail
- * closed, the read-only allowlist absolves proven reads, and every other protected-path
+ * closed, read-only proof absolves safe reads, and every other protected-path
  * mention breaks — "mention + unproven = block". It judges only its own axis: a non-shell
  * tool call is upheld, since the tool axis belongs to the self-mod meta-covenant and
  * run-all co-existence depends on that boundary.
@@ -39,6 +39,58 @@ export const DEFAULT_READ_ONLY_COMMANDS = [
     'git status',
     'git grep',
 ];
+const FIND_WRITE_OR_EXECUTE_ACTIONS = new Set([
+    '-delete',
+    '-exec',
+    '-execdir',
+    '-ok',
+    '-okdir',
+    '-fprint',
+    '-fprint0',
+    '-fprintf',
+    '-fls',
+]);
+function normalizedReadOnlyCommands(commands) {
+    return [
+        ...new Set(commands
+            .map((entry) => entry
+            .split(/\s+/)
+            .filter((word) => word !== '')
+            .join(' '))
+            .filter((entry) => entry !== '')),
+    ].sort();
+}
+/**
+ * True when a configured allowlist has the same effective entries as the shipped default.
+ * Conditional readers belong to that default contract and stay disabled for replacements.
+ */
+export function usesDefaultReadOnlyCommands(commands) {
+    const configured = normalizedReadOnlyCommands(commands);
+    const shipped = normalizedReadOnlyCommands(DEFAULT_READ_ONLY_COMMANDS);
+    return (configured.length === shipped.length && configured.every((entry, i) => entry === shipped[i]));
+}
+/**
+ * Prove the finite argument-sensitive readers that cannot be represented by a leading-word
+ * allowlist. Every word must be transparent because these readers inspect their later words.
+ */
+export function matchesConditionalReadOnlyCommand(command) {
+    if (command.words.length === 0 || command.words.some((word) => word.opaque))
+        return false;
+    const name = commandBasename(command.words[0]);
+    if (name === 'git')
+        return command.words[1]?.text === 'ls-files';
+    if (name === 'find') {
+        return !command.words.some((word) => FIND_WRITE_OR_EXECUTE_ACTIONS.has(word.text));
+    }
+    if (name !== 'sed')
+        return false;
+    const script = command.words[2]?.text;
+    return (command.words[1]?.text === '-n' &&
+        script !== undefined &&
+        /^\d+(?:,\d+)?p$/.test(script) &&
+        command.words.length > 3 &&
+        command.words.slice(3).every((word) => !word.text.startsWith('-')));
+}
 // The rule set is fixed, not injectable: dropping a rule from an assembly would be a
 // detection hole, and no consumer needs a subset.
 const MUTATION_RULES = [redirectWriteRule, teeRule, sedInPlaceRule];
@@ -65,9 +117,9 @@ export function matchesReadOnlyEntry(command, entry) {
  * Judge one simple command. Returns the break reason, or null when the command contributes
  * to uphold. The clause order below is normative: each clause exists to be reached before
  * the next one can absolve. `lineFullyRead` is false when the line carried a span the
- * tokenizer could not read, which withholds the allowlist clause.
+ * tokenizer could not read, which withholds read-only proof.
  */
-function judgeCommand(command, protectedPaths, readOnlyEntries, lineFullyRead) {
+function judgeCommand(command, protectedPaths, readOnlyEntries, conditionalReadersEnabled, lineFullyRead) {
     // (a) Precise rules: a detected mutation whose target carries a protected path breaks.
     for (const rule of MUTATION_RULES) {
         for (const target of rule.detect(command)) {
@@ -100,16 +152,18 @@ function judgeCommand(command, protectedPaths, readOnlyEntries, lineFullyRead) {
     if (command.redirects.some((r) => r.operator.includes('>') && r.target.opaque)) {
         return `opaque redirect target alongside protected path ${mentioned}`;
     }
-    // (e) Read-only allowlist: a proven read absolves the mention — but a nested shell
-    // (`eval`/`sh -c …`) re-parses its string args, so it can never be proven read-only even
-    // if it was injected into the allowlist. Its mention falls through to the backstop. A line
+    // (e) Read-only proof: the allowlist or a finite argument-sensitive reader absolves the
+    // mention. A nested shell (`eval`/`sh -c …`) re-parses its string args, so it can never be
+    // proven read-only even if it was injected into the allowlist. Its mention falls through
+    // to the backstop. A line
     // carrying an unread span is refused the same way: what the scanner never read could be
     // anything, so no head vouches for it.
     const first = command.words[0];
     const firstBasename = first !== undefined ? commandBasename(first) : '';
     if (lineFullyRead &&
         !isNestedShellCommand(firstBasename) &&
-        readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry))) {
+        (readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry)) ||
+            (conditionalReadersEnabled && matchesConditionalReadOnlyCommand(command)))) {
         return null;
     }
     // (f) Backstop — mention + unproven = block.
@@ -133,6 +187,7 @@ export function judgeShellModification(input, spec) {
     const readOnlyEntries = spec.readOnlyCommands
         .map((entry) => entry.split(/\s+/).filter((word) => word !== ''))
         .filter((entry) => entry.length > 0);
+    const conditionalReadersEnabled = usesDefaultReadOnlyCommands(spec.readOnlyCommands);
     for (const call of input.toolCalls) {
         if (!shellToolNames.includes(call.name)) {
             continue;
@@ -167,7 +222,7 @@ export function judgeShellModification(input, spec) {
                 }
             }
             for (const command of commands) {
-                const reason = judgeCommand(command, protectedPaths, readOnlyEntries, unread.length === 0);
+                const reason = judgeCommand(command, protectedPaths, readOnlyEntries, conditionalReadersEnabled, unread.length === 0);
                 if (reason !== null)
                     return { upheld: false, reason };
             }

package/dist/covenant/transcript-mod.js

@@ -13,7 +13,7 @@ import { isNestedShellCommand, tokenizeCommandLine } from './bash-line.js';
 import { pathCandidates, pathSegments, provenChangePath, resolveDotSegments, someStringValue, untokenizableLineCandidates, } from './mention.js';
 import { commandBasename, redirectWriteRule, sedInPlaceRule, teeRule } from './mutation-rules.js';
 import { outcomeFromVerdict, UNJUDGEABLE_OUTCOME } from './run-covenant.js';
-import { DEFAULT_READ_ONLY_COMMANDS, matchesReadOnlyEntry } from './shell-mod.js';
+import { DEFAULT_READ_ONLY_COMMANDS, matchesConditionalReadOnlyCommand, matchesReadOnlyEntry, usesDefaultReadOnlyCommands, } from './shell-mod.js';
 // The rule set is fixed, assembled exactly as shell-mod assembles it: dropping one would be
 // a detection hole, and the two judges must not diverge on what counts as a write.
 const MUTATION_RULES = [redirectWriteRule, teeRule, sedInPlaceRule];
@@ -55,6 +55,7 @@ function resolveTranscript(spec) {
         readOnlyEntries: spec.readOnlyCommands
             .map((entry) => entry.split(/\s+/).filter((word) => word !== ''))
             .filter((entry) => entry.length > 0),
+        conditionalReadersEnabled: usesDefaultReadOnlyCommands(spec.readOnlyCommands),
     };
 }
 /**
@@ -96,7 +97,7 @@ function argsNameTranscript(value, transcript) {
  * it has to break before the allowlist gets a chance to absolve it. The letters skip `(c)`
  * because this ladder has no opaque-mention clause, matching the shell ladder's numbering
  * rather than closing the gap. `lineFullyRead` is false when the line carried a span the
- * tokenizer could not read, which withholds the allowlist clause.
+ * tokenizer could not read, which withholds read-only proof.
  */
 function judgeCommand(command, transcript, lineFullyRead) {
     // (a) Precise rules: a detected mutation whose target is the transcript breaks.
@@ -118,15 +119,17 @@ function judgeCommand(command, transcript, lineFullyRead) {
     if (command.redirects.some((r) => r.operator.includes('>') && r.target.opaque)) {
         return `opaque redirect target alongside the session transcript ${transcript.path}`;
     }
-    // (e) Read-only allowlist: a proven read absolves the mention, in every spelling — but a
-    // nested shell (`eval`/`sh -c …`) re-parses its string args, so it is never provably a read.
+    // (e) Read-only proof: the allowlist or a finite argument-sensitive reader absolves the
+    // mention in every spelling. A nested shell (`eval`/`sh -c …`) re-parses its string args,
+    // so it is never provably a read.
     // A line carrying an unread span is refused the same way: reading the session is free, but
     // only on a line we finished reading.
     const first = command.words[0];
     const firstBasename = first !== undefined ? commandBasename(first) : '';
     if (lineFullyRead &&
         !isNestedShellCommand(firstBasename) &&
-        transcript.readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry))) {
+        (transcript.readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry)) ||
+            (transcript.conditionalReadersEnabled && matchesConditionalReadOnlyCommand(command)))) {
         return null;
     }
     // (f) Backstop — mention + unproven = block.

package/dist/docs/README.ko.md

@@ -2,34 +2,59 @@
 
 [English](./README.md) · **한국어**
 
-> AI 코딩 파트너와 함께 개발하기 위한 규율 프레임워크입니다. 궁금한 곳부터 읽으십시오.
+폴리데우케스는 AI 코딩 파트너와 함께 개발하기 위한 규율(discipline) 프레임워크입니다.
+아래에서 하려는 작업에 맞는 안내를 선택하세요.
 
+<a id="여기서-시작하십시오"></a>
 <a id="start-here"></a>
-## 여기서 시작하십시오
+## 시작하기
 
 | 하려는 것 | 읽을 문서 |
 |---|---|
-| 첫 눈에 보이는 판정을 보고 싶다 | [첫 판정](./tutorials/first-judgment.ko.md) — 설치하고 Claude Code를 배선한 뒤 보호된 편집이 판정되는 모습을 봅니다 |
-| Claude Code, Grok, Codex, git을 연결하고 싶다 | [표면 연결하기](./how-to/connect-surfaces.ko.md) — 세션과 커밋 배선, Grok와 Codex 포함 |
-| 프로젝트 설정을 다듬고 싶다 | [프로젝트 설정하기](./how-to/configure-project.ko.md) — 발견, IDE 지원, advise와 block의 선택 |
-| 실제 규율을 쓰고 싶다 | [규율 작성하기](./how-to/write-disciplines.ko.md) — 실전 선언 예제, 특히 locale key pairing |
+| 첫 판정을 확인하고 싶다 | [첫 판정](./tutorials/first-judgment.ko.md) — 설치와 Claude Code 연동을 마치고 보호 파일 편집에 대한 판정을 확인합니다 |
+| Claude Code, Grok, Codex, git을 연결하고 싶다 | [표면 연결하기](./how-to/connect-surfaces.ko.md) — 세션과 커밋 연동 설정, Grok와 Codex 포함 |
+| 프로젝트 설정을 다듬고 싶다 | [프로젝트 설정하기](./how-to/configure-project.ko.md) — 설정 파일 찾기, IDE 지원, advise와 block 선택 |
+| 실제 규율을 쓰고 싶다 | [규율 작성하기](./how-to/write-disciplines.ko.md) — 번역 키 짝 맞춤을 포함한 선언 예제 |
 | 차단이나 건너뜀에서 회복하고 싶다 | [문제 해결](./troubleshooting.ko.md) — fail-closed 상태, 증인 밸브, 로그 |
 | 이 프레임워크가 왜 있는지 알고 싶다 | [왜 폴리데우케스인가?](./why-polydeukes.ko.md) — 설계 백서 |
 | 이 문서에 기여하고 싶다 | [문서에 기여하기](./contributing.ko.md) — 영한 쌍, 안정 ID, 카탈로그, 검사 |
 
 <a id="reference"></a>
-## 레퍼런스
+## 참조
 
-설정 키, 하위 명령, 종료 코드를 설명합니다. 계획이 아니라 현재 동작을 기준으로 서술합니다.
+<a id="reference-cli"></a>
+### CLI 명령어
 
-| 문서 | 답하는 것 |
+| 명령어 | 용도 |
+|---|---|
+| [`pdks covenant check`](./reference/cli/covenant-check.ko.md) | 입력 IR이나 unified diff를 판정하고 결과와 종료 코드 확인 |
+| [`pdks init`](./reference/cli/init.ko.md) | 프로젝트 설정 생성 |
+| [`pdks explain`](./reference/cli/explain.ko.md) | 등록된 규율과 강제 수준 확인 |
+| [`pdks docs`](./reference/cli/docs.ko.md) | 설치된 문서 검색과 조회 |
+
+<a id="reference-configuration"></a>
+### 설정
+
+[설정 참조](./reference/configuration/index.ko.md)에서 `polydeukes.config.yaml`의 키와
+강제 수준, 규율 목록, 증인 설정을 확인합니다.
+
+<a id="reference-declaration-language"></a>
+### 선언 언어
+
+[선언 언어 참조](./reference/declaration-language/index.ko.md)에서 소스, 추출 단계,
+조합 연산, 관계, 기전의 전체 문법과 제약을 확인합니다.
+
+<a id="reference-packages"></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로 |
 | [`@polydeukes/adapter-codex`](./reference/packages/adapter-codex.ko.md) | Codex 세션 표면입니다. 훅 페이로드에서 입력 IR로, 패치가 건드리는 파일마다 원소 하나 |
+| [`@polydeukes/sdk-ts`](./reference/packages/sdk-ts.ko.md) | TypeScript에서 판정기를 호출하고 결과를 처리하는 방법 |
 
 <a id="shape-of-the-thing"></a>
 ## 한 페이지로 보는 구조
@@ -37,16 +62,16 @@
 폴리데우케스는 개발자나 AI 에이전트가 하려는 일을 판정하고 결과를 기록합니다.
 기본값으로는 작업을 차단하지 않습니다. 설계의 바탕은 다음 세 가지입니다.
 
-**약속은 가두기 위한 울타리가 아닙니다.** 여기서 확인하는 규율은 개발자가 이미 스스로 지켜 온 것들입니다. AI에게만큼 사람에게도 똑같이 적용되고, 프레임워크를 만든
-사람도 매일 그 판정을 받습니다.
+**약속(covenant)은 합의한 개발 관행을 검사합니다.** 같은 규율을 사람과 AI의 작업에
+적용하며, 이 프로젝트의 작성자도 일상적인 개발에서 사용합니다.
 
-**판정과 차단은 별개의 결정입니다.** 선언된 규율은 적용 범위에 해당하는 호출마다 판정합니다.
-위반했을 때 호출을 차단할지는 별도로 정합니다. 기본값으로는 사유를 기록하고 호출을 계속합니다.
-작성자는 `enforce: block`으로 차단을 선택할 수 있습니다. 별도 선택 없이 차단하는 것은
-프레임워크 자체를 보호하는 경우뿐입니다.
+**판정과 차단은 별도로 정합니다.** 선언된 규율은 적용 범위에 해당하는 호출을 판정합니다.
+기본값으로는 위반 사유를 기록하고 호출을 계속합니다. 위반을 차단하려면 항목에
+`enforce: block`을 설정합니다. 프레임워크 자체의 보호 기능은 세션 호출을 기본으로 차단합니다.
 
-**모든 판정은 행 하나를 남깁니다.** `.polydeukes/roi.log`가 판정 결과마다 한 줄씩, 낱말 여섯 개짜리 어휘로 담습니다. 이 프로젝트가 자기 결함을 찾는
-방법이 그 기록입니다. 백서에 적힌 결함들도 전부 코드를 읽어서가 아니라 행을 세어서 나왔습니다.
+**판정 결과를 기록합니다.** `.polydeukes/roi.log`에 판정 결과와 관련 정보가 쌓입니다.
+이 로그로 위반, 건너뛴 검사, 예상과 다른 결과를 조사할 수 있습니다.
+[설계 설명](./why-polydeukes.ko.md)에서는 기록을 바탕으로 프로젝트를 개선한 과정을 다룹니다.
 
 <a id="two-surfaces"></a>
 ## 두 표면

package/dist/docs/README.md

@@ -2,8 +2,8 @@
 
 **English** · [한국어](./README.ko.md)
 
-> A development discipline framework for building alongside an AI coding partner. Start where your
-question is.
+Polydeukes is a development discipline framework for building alongside an AI coding partner.
+Choose a guide for your task below.
 
 <a id="start-here"></a>
 ## Start here
@@ -21,36 +21,58 @@ question is.
 <a id="reference"></a>
 ## Reference
 
-Every key, every subcommand, every exit code. These describe the present state only — nothing here
-is aspirational.
+<a id="reference-cli"></a>
+### CLI commands
 
-| Document | Answers |
+| Command | Purpose |
+|---|---|
+| [`pdks covenant check`](./reference/cli/covenant-check.md) | Judge an input IR or unified diff; read verdicts and exit codes |
+| [`pdks init`](./reference/cli/init.md) | Create project configuration |
+| [`pdks explain`](./reference/cli/explain.md) | Inspect registered disciplines and enforcement |
+| [`pdks docs`](./reference/cli/docs.md) | Search and retrieve installed documentation |
+
+<a id="reference-configuration"></a>
+### Configuration
+
+[Configuration reference](./reference/configuration/index.md) covers `polydeukes.config.yaml`
+keys, enforcement levels, discipline lists, and witness settings.
+
+<a id="reference-declaration-language"></a>
+### Declaration language
+
+[Declaration language reference](./reference/declaration-language/index.md) lists every source,
+extraction step, combinator, relation, and mechanism with its syntax and constraints.
+
+<a id="reference-packages"></a>
+### Packages
+
+| Package | Responsibility |
 |---|---|
-| [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 |
 | [`@polydeukes/adapter-codex`](./reference/packages/adapter-codex.md) | Codex session surface — hook payloads become the input IR, one element per file the patch touches |
+| [`@polydeukes/sdk-ts`](./reference/packages/sdk-ts.md) | Call the judge from TypeScript and handle its result |
 
+<a id="the-shape-of-the-thing-in-one-page"></a>
 <a id="shape-of-the-thing"></a>
-## The shape of the thing, in one page
+## How it works
 
 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.
+**Covenants check agreed development practices.** The same disciplines apply to human and AI
+work. This project's authors use them in daily development.
 
-**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.
+**Judging and stopping are separate decisions.** Every declared discipline is judged on matching
+calls. By default, a violation is recorded with its reason and the call continues. Set
+`enforce: block` on an entry to stop violations. The framework's own protections block session
+calls by default.
 
-**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.
+**Judgments are recorded.** `.polydeukes/roi.log` stores verdicts and their context. Use the log
+to investigate violations, skipped checks, and unexpected results. The
+[design explanation](./why-polydeukes.md) describes how these records informed the project.
 
 <a id="two-surfaces"></a>
 ## Two surfaces