npm - polydeukes - Versions diffs - 0.6.0 → 0.7.1 - Mend

polydeukes 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (117) hide show

package/README.ko.md +30 -70
package/README.md +31 -84
package/dist/baseline.d.ts +37 -1
package/dist/baseline.js +68 -1
package/dist/bin.d.ts +3 -4
package/dist/bin.js +79 -93
package/dist/covenant/bash-line.d.ts +130 -0
package/dist/covenant/bash-line.js +566 -0
package/dist/covenant/declaration-engine.d.ts +108 -0
package/dist/covenant/declaration-engine.js +415 -0
package/dist/covenant/discipline.d.ts +103 -0
package/dist/covenant/discipline.js +667 -0
package/dist/covenant/dispatch.d.ts +153 -0
package/dist/covenant/dispatch.js +237 -0
package/dist/covenant/extract-steps.d.ts +122 -0
package/dist/covenant/extract-steps.js +0 -0
package/dist/covenant/mention.d.ts +117 -0
package/dist/covenant/mention.js +209 -0
package/dist/covenant/module.d.ts +25 -0
package/dist/covenant/module.js +23 -0
package/dist/covenant/mutation-rules.d.ts +40 -0
package/dist/covenant/mutation-rules.js +146 -0
package/dist/covenant/relations.d.ts +46 -0
package/dist/covenant/relations.js +68 -0
package/dist/covenant/run-covenant.d.ts +95 -0
package/dist/covenant/run-covenant.js +164 -0
package/dist/covenant/self-mod.d.ts +55 -0
package/dist/covenant/self-mod.js +84 -0
package/dist/covenant/shell-evidence.d.ts +38 -0
package/dist/covenant/shell-evidence.js +247 -0
package/dist/covenant/shell-mod.d.ts +84 -0
package/dist/covenant/shell-mod.js +213 -0
package/dist/covenant/supply.d.ts +54 -0
package/dist/covenant/supply.js +50 -0
package/dist/covenant/transcript-mod.d.ts +60 -0
package/dist/covenant/transcript-mod.js +254 -0
package/dist/covenant/ttl-witness.d.ts +47 -0
package/dist/covenant/ttl-witness.js +80 -0
package/dist/covenant-check.d.ts +72 -39
package/dist/covenant-check.js +260 -121
package/dist/diff-ir.d.ts +28 -0
package/dist/diff-ir.js +310 -0
package/dist/docs/README.ko.md +60 -0
package/dist/docs/README.md +64 -0
package/dist/docs/catalog.json +480 -0
package/dist/docs/concepts/judgment.ko.md +113 -0
package/dist/docs/concepts/judgment.md +113 -0
package/dist/docs/how-to/configure-project.ko.md +99 -0
package/dist/docs/how-to/configure-project.md +98 -0
package/dist/docs/how-to/connect-surfaces.ko.md +120 -0
package/dist/docs/how-to/connect-surfaces.md +121 -0
package/dist/docs/how-to/write-disciplines.ko.md +179 -0
package/dist/docs/how-to/write-disciplines.md +181 -0
package/dist/docs/index.json +2280 -0
package/dist/docs/reference/cli/covenant-check.ko.md +148 -0
package/dist/docs/reference/cli/covenant-check.md +153 -0
package/dist/docs/reference/cli/docs.ko.md +97 -0
package/dist/docs/reference/cli/docs.md +95 -0
package/dist/docs/reference/cli/explain.ko.md +84 -0
package/dist/docs/reference/cli/explain.md +89 -0
package/dist/docs/reference/cli/init.ko.md +119 -0
package/dist/docs/reference/cli/init.md +119 -0
package/dist/docs/reference/configuration/index.ko.md +553 -0
package/dist/docs/reference/{configuration.md → configuration/index.md} +215 -90
package/dist/docs/reference/packages/adapter-claude-code.ko.md +110 -0
package/dist/docs/reference/{adapter-claude-code.md → packages/adapter-claude-code.md} +47 -19
package/dist/docs/reference/packages/adapter-grok.ko.md +77 -0
package/dist/docs/reference/packages/adapter-grok.md +79 -0
package/dist/docs/reference/packages/core.ko.md +174 -0
package/dist/docs/reference/{core.md → packages/core.md} +74 -12
package/dist/docs/reference/packages/polydeukes.ko.md +195 -0
package/dist/docs/reference/packages/polydeukes.md +204 -0
package/dist/docs/reference/packages/sdk-ts.ko.md +161 -0
package/dist/docs/reference/packages/sdk-ts.md +164 -0
package/dist/docs/troubleshooting.ko.md +144 -0
package/dist/docs/troubleshooting.md +103 -151
package/dist/docs/tutorials/first-judgment.ko.md +82 -0
package/dist/docs/tutorials/first-judgment.md +81 -0
package/dist/docs-catalog.d.ts +25 -0
package/dist/docs-catalog.js +450 -0
package/dist/docs-library.d.ts +23 -0
package/dist/docs-library.js +347 -0
package/dist/docs-markdown.d.ts +32 -0
package/dist/docs-markdown.js +150 -0
package/dist/docs-query.d.ts +11 -40
package/dist/docs-query.js +28 -122
package/dist/docs-types.d.ts +105 -0
package/dist/docs-types.js +2 -0
package/dist/explain.d.ts +1 -1
package/dist/explain.js +37 -22
package/dist/load-config.d.ts +1 -1
package/dist/load-config.js +1 -1
package/dist/pre-state-reader.d.ts +1 -1
package/dist/pre-state-reader.js +1 -1
package/dist/scaffold-project.d.ts +2 -2
package/dist/scaffold-project.js +9 -3
package/dist/schema/polydeukes.schema.json +12 -0
package/dist/worktree-reader.d.ts +19 -0
package/dist/worktree-reader.js +30 -0
package/package.json +3 -17
package/dist/claude-code-hook.d.ts +0 -79
package/dist/claude-code-hook.js +0 -372
package/dist/claude-code.d.ts +0 -6
package/dist/claude-code.js +0 -6
package/dist/covenant-module.d.ts +0 -25
package/dist/covenant-module.js +0 -42
package/dist/docs/configuration.md +0 -103
package/dist/docs/installation.md +0 -241
package/dist/docs/reference/adapter-git.md +0 -100
package/dist/docs/reference/covenant.md +0 -116
package/dist/docs/reference/polydeukes.md +0 -315
package/dist/index.d.ts +0 -22
package/dist/index.js +0 -21
package/dist/init-claude-code.d.ts +0 -52
package/dist/init-claude-code.js +0 -469
package/dist/init-grok.d.ts +0 -51
package/dist/init-grok.js +0 -242

package/README.ko.md CHANGED Viewed

@@ -1,80 +1,40 @@
-# polydeukes
+# `polydeukes`
-**한국어** · [English](./README.md)
+[English](./README.md) · **한국어**
-> 스코프 없는 umbrella 패키지입니다. `pdks` CLI 진입점과 config 디스커버리 로더가 살고,
-> 프레임워크의 조각을 저장소가 실제로 돌리는 표면에 맞게 조립하는 유일한 자리입니다.
+Polydeukes는 우산 패키지입니다. 이 패키지 하나에 `pdks` 실행 파일, 판정기,
+두 표면의 조립 루트, 세션 표면 실행기 서브패스, 동봉 스키마가 모두 포함돼 있습니다.
-**알파(alpha) 단계입니다.** 이 패키지는 스코프 없는 `polydeukes` 이름을 예약하고, 스코프
-모듈(`@polydeukes/*`)을 조립할 수 있는 유일한 패키지로 그 위에 섭니다. 다른 모든 의존은 코어를
-통해서만 단방향으로 흐릅니다.
+<a id="overview"></a>
+## 개요
-## 여기 담긴 것
+공개 계약 진입점은 다음과 같습니다.
-- **`loadConfig({ rootDir })`.** config 디스커버리입니다. 주어진 루트 바로 아래에서 정확히 하나의
-  데이터 config(`polydeukes.config` 파일의 yaml·yml·json 형태)를 찾아, 안전 스키마로 해석하고
-  (설정 데이터는 결코 실행되지 않습니다) 코어의 `defineConfig()`에 검증을 맡깁니다. 모든 실패
-  분기는 예외를 던집니다(throw). 조용한 기본값은 금지이고, 발견된 파일은 자기 자신을 보호
-  표면에 편입시킵니다.
-- **`pdks covenant check`.** `pdks` bin의 첫 실물 서브커맨드입니다(`polydeukes`는 별칭).
-  pre-commit 판정 러너로, 스테이징 영역의 변경을 `@polydeukes/adapter-git`이 수집해
-  약속(covenant) 입력 IR로 번역하고, 세션 훅이 부르는 바로 그 in-process 판정기로 보냅니다.
-  판정기는 하나, 표면은 여럿입니다. `--worktree`와 `--range <base>..<head>`는 같은 판정을
-  작업 트리나 ref 범위에 진단 호출로 돌리며, 증인 프롬프트는 뜨지 않습니다. 세션을 읽는 선언(`precedent`와 다른 이력 기전)도 다른 규율과
-  똑같이 조립되지만, 읽을 세션이 없으므로 자기 `supply: pass`가 처분합니다. 스테이징 변경과 매치하면 자기
-  id와 그 변경을 담은 `skipped` 이벤트를 남기고 커밋은 진행됩니다. 여기서 판정하면 걸리는
-  커밋마다 정당하게 통과할 길 없이 막히고, 아예 걸러내면 게이트가 물러섰다는 사실이 가려집니다.
-  세션 표면이 읽을 transcript를 갖지 못했을 때와 같은 처분입니다. 빈 스테이징은 명시적
-  통과이고, config가 없거나 불량이면 닫힌 실패(exit 2)입니다.
-- **`pdks init claude-code`.** 세션 표면 설치기입니다. 아무것도 쓰기 전에 대상 프로젝트에서
-  `polydeukes`가 해소되는지부터 증명하고, 그다음 모든 배포 경로가 공유하는 것(데이터 config와
-  `.polydeukes/` 무시 줄)과 이 경로가 지는 것(위임자 훅, 그 파일이 이미 담고 있던 것에 병합되는
-  `.claude/settings.json` 등록, 그리고 AI 파트너를 `pdks docs`로 보내는 범위 한정 규율 파일)을
-  만듭니다. 기존 산출물은 덮어쓰지 않습니다. 이미 있는 것은 보고하고 그대로 두므로 재실행은
-  아무 일도 하지 않고, 사용자가 고친 내용이 살아남습니다. 생성된 config는 해소 경로를 보호
-  목록에 담고 증인(witness) 블록을 함께 갖습니다. 밸브가 없으면 첫 차단이 곧 프로젝트 정지인데,
-  방금 등록한 훅 자신이 보호 대상이기 때문입니다. config 철자 둘이 공존하는 트리, 파싱되지 않는
-  settings 파일, 해소되지 않는 패키지는 전부 선행 조건 실패입니다. 반쯤 배선된 트리를 남기는
-  대신 파일을 하나도 만들지 않습니다.
-- **`pdks init grok`.** Grok 세션 표면 설치기입니다. 선행 검사와 공유 스캐폴드는 같고, 이 경로가
-  지는 것은 `.grok/hooks/`입니다(timeout 60인 JSON 등록, Claude 위임자가 없을 때만 위임자 파일).
-  Claude 훅 파일이 이미 있으면 JSON command가 그 파일을 가리켜 판정기를 둘 스폰하지 않습니다.
-  나중에 어느 설치기를 다시 돌려도, 설치기가 심은 grok-mjs command는 같은 방식으로 재조준되고,
-  JSON matcher는 그 command의 `.claude/settings.json` 항목을 따릅니다. Grok는 command와
-  matcher가 모두 같을 때만 등록 둘을 하나로 접기 때문입니다. 이미 열린 Grok 세션은 시작 때 훅 스냅샷을 유지합니다. 증인 밸브는 Grok에서 열리지 않습니다.
-- **`pdks docs [topic]`.** 오프라인 문서 열람기입니다. 영어 가이드와 레퍼런스 층이 빌드 시점에
-  `dist/docs`로 복사되므로, 소비자의 AI 파트너는 검색 엔진이 색인한 아무 판본이 아니라 판정을
-  수행하는 코드와 함께 실린 문서를 읽습니다. 인자 없이 부르면 토픽 다섯을 열거하는데, 에이전트가
-  무엇을 물을 수 있는지 아는 경로가 그 목록뿐입니다. 토픽을 주면 그 절을 원문 그대로 돌려주고
-  이어서 읽을 레퍼런스를 한 줄 덧붙입니다. 질의 정의역은 그 다섯 이름뿐입니다. 모르는 토픽, 없는
-  동봉 문서, 문서가 더는 담지 않는 표제는 각각 무엇이 없었는지 stderr에 이름을 적고 exit 2로
-  끝나며 stdout은 0바이트로 둡니다. 절반만 쓰인 답은 에이전트가 그것을 문서로 읽고 그대로
-  인용하므로, 그런 상태를 만드는 경로를 두지 않습니다.
-- **커밋 표면 증인(witness) 밸브.** `block` 수위(기본값)에서 스테이징 영역의 변경이 실제로
-  약속을 깨면 러너가 `/dev/tty`에서 증인 토큰 전문을 1회 묻습니다(부분 문자열은 거부합니다).
-  프롬프트는 깨진 등록과 걸린 항목, 그리고 이 한 번의 답이 커밋 전체를 덮는다는 사실을 적습니다.
-  깨끗한 커밋은 프롬프트를 보지 않습니다. TTY가 없으면, 즉 CI나 에이전트가 띄운 `git commit`
-  이면 프롬프트도 통과할 길도 없습니다. 밸브는 터미널 앞의 인간에게만 닿고, 어떤 상태도 남기지
-  않으며, 증언으로 통과한 판정은 모두 `witnessed`로 기록됩니다. 조용한 우회는 없습니다.
-- **시행 수위.** git 어댑터의 네임스페이스 설정 `adapters.git.enforce: block | advise`가 커밋
-  표면 판정의 처분을 고릅니다. `advise`에서는 밸브 자체가 조립되지 않습니다. 판정은 `advised`
-  이벤트로 기록되고, stderr에 권고 한 줄이 남으며, 커밋은 진행됩니다. 차단하는 대신 측정하는
-  백스톱입니다. 완화되는 것은 판정뿐이라, 판정 자체가 불가능한 실행(설정 없음·무효, 판정 본체
-  해석 불가)은 어느 수위에서든 exit 2로 닫힙니다.
+- `pdks` / `polydeukes` — 실행 파일
+- `polydeukes/schema.json`
-## 전체 지도
+CLI 명령은 다음과 같습니다.
-| 모듈 | 역할 |
-|---|---|
-| `@polydeukes/core` | 약속(covenant) 프로토콜, config 스키마, ROI 텔레메트리, 대화 기록 이음새 |
-| `@polydeukes/covenant` | 디스패처, 판정 본체, Bash 분석, 규율(discipline) 라이브러리 |
-| `@polydeukes/adapter-claude-code` | 세션 표면. PreToolUse 페이로드를 약속(covenant) 입력 IR로 번역 |
-| `@polydeukes/adapter-git` | 커밋 표면. `staged diff`를 약속(covenant) 입력 IR로 번역 |
-| `@polydeukes/ledger` · `@polydeukes/memory` · `@polydeukes/verify` | 청사진 단계 |
+- `pdks covenant check`
+- `pdks init`
+- `pdks-grok init` (`@polydeukes/adapter-grok`가 제공)
+- `pdks explain`
+- `pdks docs [topic]`
-아키텍처 청사진과 설계 근거는
-[프로젝트 저장소](https://github.com/huskyhoochu/polydeukes)에 있습니다.
+<a id="public-symbols"></a>
+## 공개 심볼
-## 라이선스
+없습니다. 이 패키지는 TypeScript 진입점을 공개하지 않습니다. `import 'polydeukes'`는
+`ERR_PACKAGE_PATH_NOT_EXPORTED`로 실패하고, 사용자가 닿는 것은 `pdks` 실행 파일과 동봉된
+스키마입니다. 표면은 판정기에 표준 입력으로 입력을 넘기고 종료 코드를 읽습니다. 에이전트
+어댑터의 훅이 하는 일이 바로 그것입니다. 이 패키지를 peer 의존으로 선언하고 import 없이
+실행 파일을 스폰합니다.
-MIT
+<a id="see-also"></a>
+## 같이 보기
+- [`polydeukes` 패키지 레퍼런스](../../docs/reference/packages/polydeukes.ko.md)
+- [`설정 레퍼런스`](../../docs/reference/configuration/index.ko.md)
+- [`pdks covenant check`](../../docs/reference/cli/covenant-check.ko.md)
+- [`pdks init`](../../docs/reference/cli/init.ko.md)
+- [`pdks explain`](../../docs/reference/cli/explain.ko.md)

package/README.md CHANGED Viewed

@@ -1,94 +1,41 @@
-# polydeukes
+# `polydeukes`
-**English** · [한국어](https://github.com/huskyhoochu/polydeukes/blob/main/packages/polydeukes/README.ko.md)
+**English** · [한국어](./README.ko.md)
-> The unscoped umbrella: the `pdks` CLI entry point and the config discovery loader — the one
-> place where the framework's pieces are assembled for the surfaces a repository actually runs.
+Polydeukes is the umbrella package. Install this package; it ships the `pdks` bin, the judge,
+both surfaces' composition roots, the session-surface runner subpath, and the bundled schema
+artifact.
-**Alpha.** This package reserves the unscoped `polydeukes` name and sits above the scoped
-`@polydeukes/*` modules as the only one allowed to assemble them — every other dependency stays
-one-way, through the core alone.
+<a id="overview"></a>
+## Overview
-## What lives here
+Public contract entry points:
-- **`loadConfig({ rootDir })`** — config discovery. Exactly one root data config (a
-  `polydeukes.config` file in yaml, yml, or json form) directly under the given root, parsed with
-  a safe schema (config data is never executable) and validated by the core's `defineConfig()`.
-  Every failure branch throws — silent defaults are forbidden — and the discovered file attaches
-  itself to its own protection surface.
-- **`pdks covenant check`** — the first real subcommand of the `pdks` bin (`polydeukes` is an
-  alias). A pre-commit judgment runner: staged changes are collected by `@polydeukes/adapter-git`,
-  translated into the covenant input IR, and dispatched through the very in-process judges the
-  session hook calls — one judge, every surface. `--worktree` and `--range <base>..<head>` run the same
-  judgment over the working tree or a ref range as a diagnostic call, with no witness prompt.
-  Declarations that read the session (`precedent` and the other history mechanisms) assemble
-  here like any other, but with no session to read their `supply: pass` takes over: when one
-  matches a staged change it records a `skipped` event carrying its id and that change, and the
-  commit proceeds. Judging them would block every matching commit with no legitimate pass path;
-  filtering them out would hide that a gate stood down. It is the same disposition the session
-  surface uses when it has no transcript. An empty staging area is an explicit pass; a missing or
-  invalid config fails closed.
-- **`pdks explain`** — the assembly reader. It assembles both surfaces' registration sets through
-  the same functions the two runners call and prints them without judging: every registration
-  with its kind (`meta` / `judge` / `skip` / `excluded`), the routing scope of each entry, whether
-  it carries a `why`, and for each skip the compiler's reason — the one that otherwise reaches
-  stderr only when the cause is a config fault. No judge thunk is called and no telemetry row is
-  written. A config that cannot be loaded fails at exit `2` with stdout at zero bytes.
-- **`pdks init claude-code`** — the Claude Code session-surface installer. It proves `polydeukes` resolves
-  from the target project before writing anything, then creates what every distribution path
-  shares (the data config and its `.polydeukes/` ignore line) and what this path owns (a delegator
-  hook, its `.claude/settings.json` registration merged into whatever that file already carries,
-  and a scoped discipline file pointing an AI partner at `pdks docs`). Nothing existing is
-  overwritten: an artifact already there is reported and left alone, so a re-run is a no-op and a
-  consumer's edits survive. The generated config carries the resolution paths on its protection
-  list and a witness block — without the valve the first block would freeze the project, since the
-  hook it just registered is itself protected. Two coexisting config spellings, an unparseable
-  settings file, and a package that cannot be resolved are all precondition failures: each leaves
-  zero files rather than a half-wired tree.
-- **`pdks init grok`** — the Grok session-surface installer. Same preflight and shared scaffold;
-  this path owns `.grok/hooks/` (JSON registration with timeout 60, and a delegator file only when
-  no Claude delegator is on disk). If the Claude hook file already exists, the JSON command points
-  at it so two judges are not spawned. A later run of either installer retargets an
-  installer-generated grok-mjs command the same way, and the JSON matcher follows the
-  `.claude/settings.json` entry for that command — Grok collapses two registrations only when
-  command and matcher both match. An already-open Grok session keeps the hook snapshot from
-  start. The witness valve does not open on Grok.
-- **`pdks docs [topic]`** — the offline documentation reader. The English guides and the reference
-  layer are copied into `dist/docs` at build time, so a consumer's AI partner reads the
-  documentation that shipped with the code doing the judging instead of whichever release a search
-  engine indexed. With no argument it lists the five topics — that listing is how an agent
-  discovers what it may ask at all; with one it returns that topic's section verbatim plus the
-  reference to read next. The query domain is those five names and nothing else: an unknown topic,
-  a bundled document that is missing, and a heading a document no longer carries each name what
-  was missing on stderr and exit 2, leaving stdout at zero bytes. A partially written answer would
-  be read as the document and quoted onward, so no path produces one.
-- **The commit-surface witness valve** — at the `block` level (the default), when a staged change
-  actually breaks a covenant, the runner prompts once on `/dev/tty` for the full witness token (a
-  substring is refused), naming the broken registration, the matched entry, and the commit-wide
-  reach of the one answer. A clean commit never prompts. No TTY — CI, an agent-spawned
-  `git commit` — means no prompt and no way through: the valve is reachable only by a human at a
-  terminal, and nothing is ever persisted. Every witnessed pass is measured as `witnessed`, never
-  silent.
-- **The enforcement level** — the git adapter's namespace setting
-  `adapters.git.enforce: block | advise` selects what a commit-surface verdict does. Under
-  `advise` the valve is structurally absent: a verdict is recorded as an `advised` event, one
-  advisory line lands on stderr, and the commit proceeds — a backstop that measures instead of
-  blocking. Only the verdict is relaxed: a run that cannot judge (missing or invalid config, an
-  unresolvable judge body) fails closed at exit 2 at either level.
+- `pdks` / `polydeukes` — the bin
+- `polydeukes/schema.json`
-## The wider map
+CLI commands:
-| Module | Role |
-|---|---|
-| `@polydeukes/core` | Covenant protocol, config schema, ROI telemetry, transcript seam |
-| `@polydeukes/covenant` | Dispatcher, judge bodies, Bash analysis, discipline library |
-| `@polydeukes/adapter-claude-code` | Session surface — PreToolUse payloads → covenant input IR |
-| `@polydeukes/adapter-git` | Commit surface — staged diffs → covenant input IR |
-| `@polydeukes/ledger` · `@polydeukes/memory` · `@polydeukes/verify` | Blueprint stage |
+- `pdks covenant check`
+- `pdks init`
+- `pdks-grok init` (ships with `@polydeukes/adapter-grok`)
+- `pdks explain`
+- `pdks docs [topic]`
-See the [project repository](https://github.com/huskyhoochu/polydeukes) for the architecture
-blueprint and design rationale.
+<a id="public-symbols"></a>
+## Public symbols
-## License
+None. This package publishes no TypeScript entry point: `import 'polydeukes'` fails with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`, and what a consumer reaches is the `pdks` bin and the
+bundled schema. A surface hands the judge its input on stdin and reads the exit code, which
+is what an agent adapter's hook does — it takes this package as a peer dependency and
+spawns the bin rather than importing it.
-MIT
+<a id="see-also"></a>
+## See also
+- [`polydeukes` package reference](../../docs/reference/packages/polydeukes.md)
+- [`Configuration reference`](../../docs/reference/configuration/index.md)
+- [`pdks covenant check`](../../docs/reference/cli/covenant-check.md)
+- [`pdks init`](../../docs/reference/cli/init.md)
+- [`pdks explain`](../../docs/reference/cli/explain.md)

package/dist/baseline.d.ts CHANGED Viewed

@@ -11,7 +11,7 @@
  * {@link snapshotBaseline} / {@link writeBaseline} / {@link readBaseline} are the I/O
  * points.
  */
-import type { TelemetryRecord } from '@polydeukes/core';
+import { type TelemetryRecord } from '@polydeukes/core';
 /** One hash per protected entry, keyed by the entry exactly as configured. */
 export type BaselineSnapshot = Record<string, string>;
 /**
@@ -80,3 +80,39 @@ export declare function writeBaseline(path: string, snapshot: BaselineSnapshot,
  * Observation is fail-open: the worst outcome is a missing datum, never a blocked call.
  */
 export declare function readBaseline(path: string): StoredBaseline | null;
+/** The label every post-hoc state comparison row carries. */
+export declare const BASELINE_LABEL = "baseline";
+/**
+ * Compare the protected entries' on-disk state against the stored baseline and record what
+ * moved with no judgment explaining it.
+ *
+ * Runs at hook call START, before this call's own judgment rows land, so the window it reads
+ * is the one the previous comparison left open. Returns the record count as of right now —
+ * where the NEXT window opens, which {@link updateBaseline} persists at call end.
+ *
+ * The comparison records, it never blocks: no row it writes and no failure it hits changes
+ * a verdict or an exit code, which is why every caller keeps it outside the judgment path.
+ */
+export declare function compareBaseline(spec: {
+    repoRoot: string;
+    telemetryPath: string;
+    entries: string[];
+}): void;
+/**
+ * Re-establish the baseline at hook call END.
+ *
+ * At call end rather than right after the comparison: refreshing at comparison time would
+ * miss whatever this call's own judged writes changed, leaving detection permanently one
+ * call behind.
+ *
+ * The cut is stamped HERE, beside the snapshot, not at the comparison that opened the call.
+ * Both describe the same instant — everything this call did is already folded into the
+ * hashes — so the rows explaining it belong before the cut. Stamping the earlier instant
+ * instead would re-admit this call's own judgment rows into the next window, where they
+ * would attribute a change they had nothing to do with: a call that merely MENTIONED a
+ * protected entry would then absolve any tamper that followed it.
+ */
+export declare function updateBaseline(spec: {
+    repoRoot: string;
+    entries: string[];
+}): void;

package/dist/baseline.js CHANGED Viewed

@@ -12,8 +12,9 @@
  * points.
  */
 import { createHash } from 'node:crypto';
-import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { appendRecordFailOpen, readRecords, } from '@polydeukes/core';
 /**
  * The two verdict words that explain a change — the ones that mean a mutation of a
  * protected entry was judged and let through anyway.
@@ -164,3 +165,69 @@ export function readBaseline(path) {
         cutAt: typeof cutAt === 'string' ? cutAt : undefined,
     };
 }
+/** The label every post-hoc state comparison row carries. */
+export const BASELINE_LABEL = 'baseline';
+/**
+ * Compare the protected entries' on-disk state against the stored baseline and record what
+ * moved with no judgment explaining it.
+ *
+ * Runs at hook call START, before this call's own judgment rows land, so the window it reads
+ * is the one the previous comparison left open. Returns the record count as of right now —
+ * where the NEXT window opens, which {@link updateBaseline} persists at call end.
+ *
+ * The comparison records, it never blocks: no row it writes and no failure it hits changes
+ * a verdict or an exit code, which is why every caller keeps it outside the judgment path.
+ */
+export function compareBaseline(spec) {
+    const baselinePath = join(spec.repoRoot, '.polydeukes', 'baseline.json');
+    // Read before any row of this comparison lands, so the rows this call is about to write
+    // cannot fall inside the window they would then explain away.
+    const { records } = readRecords(spec.telemetryPath);
+    const stored = readBaseline(baselinePath);
+    if (stored === null) {
+        // Absence and corruption are the same signal. The baseline file is NOT on the protection
+        // list — protecting it would need a comparison of its own — so its disappearance has to
+        // stay legible in the log instead.
+        appendRecordFailOpen(spec.telemetryPath, {
+            event: 'unattributed',
+            label: BASELINE_LABEL,
+            subject: baselinePath,
+        });
+        return;
+    }
+    const changed = findUnattributed({
+        previous: stored.entries,
+        current: snapshotBaseline({ rootDir: spec.repoRoot, entries: spec.entries }),
+        records,
+        // The cut travels with the hashes it belongs to, from the one read above. Rows older
+        // than it were already spent explaining the state that snapshot recorded.
+        cutAt: stored.cutAt,
+    });
+    // One row per changed entry — an aggregate row could not say WHICH gate definition moved.
+    for (const entry of changed) {
+        appendRecordFailOpen(spec.telemetryPath, {
+            event: 'unattributed',
+            label: BASELINE_LABEL,
+            subject: entry,
+        });
+    }
+}
+/**
+ * Re-establish the baseline at hook call END.
+ *
+ * At call end rather than right after the comparison: refreshing at comparison time would
+ * miss whatever this call's own judged writes changed, leaving detection permanently one
+ * call behind.
+ *
+ * The cut is stamped HERE, beside the snapshot, not at the comparison that opened the call.
+ * Both describe the same instant — everything this call did is already folded into the
+ * hashes — so the rows explaining it belong before the cut. Stamping the earlier instant
+ * instead would re-admit this call's own judgment rows into the next window, where they
+ * would attribute a change they had nothing to do with: a call that merely MENTIONED a
+ * protected entry would then absolve any tamper that followed it.
+ */
+export function updateBaseline(spec) {
+    const dotDir = join(spec.repoRoot, '.polydeukes');
+    mkdirSync(dotDir, { recursive: true });
+    writeBaseline(join(dotDir, 'baseline.json'), snapshotBaseline({ rootDir: spec.repoRoot, entries: spec.entries }), new Date().toISOString());
+}

package/dist/bin.d.ts CHANGED Viewed

@@ -6,9 +6,8 @@
  * table. Anything else prints usage and exits 2 — an unknown argument must never pass
  * silently (fail-closed, the same posture as an unjudgeable payload).
  *
- * The real TTY is wired HERE, not in the library: the runner receives an injectable
- * seam, and this shim binds it to /dev/tty. When /dev/tty cannot be opened (git run by
- * CI or by an agent-spawned shell — no controlling terminal), the seam stays absent and
- * the witness valve is structurally unreachable, so only a human at a terminal can arm it.
+ * `covenant check` reads its observation from stdin and nothing else: the IR JSON by
+ * default, a unified diff under `--diff`. No other file descriptor is opened, so the
+ * process never asks a human anything.
  */
 export {};

package/dist/bin.js CHANGED Viewed

@@ -6,50 +6,41 @@
  * table. Anything else prints usage and exits 2 — an unknown argument must never pass
  * silently (fail-closed, the same posture as an unjudgeable payload).
  *
- * The real TTY is wired HERE, not in the library: the runner receives an injectable
- * seam, and this shim binds it to /dev/tty. When /dev/tty cannot be opened (git run by
- * CI or by an agent-spawned shell — no controlling terminal), the seam stays absent and
- * the witness valve is structurally unreachable, so only a human at a terminal can arm it.
+ * `covenant check` reads its observation from stdin and nothing else: the IR JSON by
+ * default, a unified diff under `--diff`. No other file descriptor is opened, so the
+ * process never asks a human anything.
  */
-import { closeSync, openSync, readSync, writeSync } from 'node:fs';
+import { readFileSync, readSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
- * Bind the TTY prompt seam to /dev/tty, or undefined when no terminal exists. The runner
- * composes the prompt text (it is the side that knows what broke); this shim only writes
- * it and reads the line back.
+ * Read stdin to EOF. `readFileSync(0)` returns only what the first read delivers, so a
+ * diff larger than the pipe buffer would arrive truncated and translate to a partial
+ * observation; this loops until a read answers zero bytes.
  */
-function openTtyPrompt() {
-    let fd;
-    try {
-        fd = openSync('/dev/tty', 'r+');
-    }
-    catch {
-        return undefined;
-    }
-    return (prompt) => {
+function readStdin() {
+    const chunks = [];
+    const buffer = Buffer.alloc(65536);
+    for (;;) {
+        let bytes;
         try {
-            writeSync(fd, prompt);
-            const buffer = Buffer.alloc(4096);
-            const bytes = readSync(fd, buffer, 0, buffer.length, null);
-            return buffer
-                .subarray(0, Math.max(bytes, 0))
-                .toString('utf-8')
-                .replace(/\r?\n$/, '');
+            bytes = readSync(0, buffer, 0, buffer.length, null);
         }
-        catch {
-            return null;
+        catch (error) {
+            const { code } = error;
+            // A pipe with no writer left answers EOF this way on some platforms; EAGAIN is a
+            // non-blocking fd with nothing ready yet, which is not the end of the input.
+            if (code === 'EOF')
+                break;
+            if (code === 'EAGAIN')
+                continue;
+            throw error;
         }
-        finally {
-            try {
-                closeSync(fd);
-            }
-            catch {
-                // An EBADF thrown from this finally would override the `return null` above and
-                // escape the seam.
-            }
-        }
-    };
+        if (bytes === 0)
+            break;
+        chunks.push(Buffer.from(buffer.subarray(0, bytes)));
+    }
+    return Buffer.concat(chunks).toString('utf-8');
 }
 /**
  * Write `text` to stdout and end the process — exit 0 once the write drains, exit 2 when
@@ -65,14 +56,14 @@ async function emitAndExit(text) {
     process.exit(0);
 }
 const args = process.argv.slice(2);
-if (args.length === 2 && args[0] === 'init' && args[1] === 'claude-code') {
+if (args.length === 1 && args[0] === 'init') {
     try {
-        // Imported inside the try, not above it: ESM imports are eager, so the installer stays
+        // Imported inside the try, not above it: ESM imports are eager, so the scaffold stays
         // off `covenant check`'s load path, which a pre-commit hook spawns on every commit. A
         // rejected import outside the try would reach node's unhandled-rejection exit 1, the
         // exact crash this bin refuses to make.
-        const { initClaudeCode } = await import('./init-claude-code.js');
-        const { created, skipped } = initClaudeCode({ projectRoot: process.cwd() });
+        const { scaffoldProject } = await import('./scaffold-project.js');
+        const { created, skipped } = scaffoldProject(process.cwd());
         for (const path of created) {
             process.stdout.write(`created ${path}\n`);
         }
@@ -84,36 +75,22 @@ if (args.length === 2 && args[0] === 'init' && args[1] === 'claude-code') {
     catch (error) {
         // A precondition failure leaves zero files; the message names what the user has to do
         // before running this again.
-        process.stderr.write(`pdks init claude-code failed: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(2);
-    }
-}
-if (args.length === 2 && args[0] === 'init' && args[1] === 'grok') {
-    try {
-        const { initGrok } = await import('./init-grok.js');
-        const { created, skipped } = initGrok({ projectRoot: process.cwd() });
-        for (const path of created) {
-            process.stdout.write(`created ${path}\n`);
-        }
-        for (const path of skipped) {
-            process.stdout.write(`skipped ${path} (already present)\n`);
-        }
-        process.exit(0);
-    }
-    catch (error) {
-        process.stderr.write(`pdks init grok failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`pdks init failed: ${error instanceof Error ? error.message : String(error)}\n`);
         process.exit(2);
     }
 }
-if (args[0] === 'docs' && args.length <= 2) {
+if (args[0] === 'docs') {
     try {
         // Imported inside the try for the same reason `init` is: the query core and the
         // markdown behind it have no business on `covenant check`'s load path.
-        const { queryDocs } = await import('./docs-query.js');
+        const { runDocs } = await import('./docs-library.js');
         // The bundle ships beside this file, so the docs root comes from the module's own
         // location — never from the working directory, which is whatever shell invoked us.
         const docsRoot = join(dirname(fileURLToPath(import.meta.url)), 'docs');
-        const { text } = queryDocs({ docsRoot, topic: args[1] });
+        const manifest = JSON.parse(readFileSync(join(docsRoot, '../../package.json'), 'utf8'));
+        if (typeof manifest.version !== 'string')
+            throw new Error('missing package version');
+        const { text } = runDocs({ docsRoot, args: args.slice(1), version: manifest.version });
         await emitAndExit(text);
     }
     catch (error) {
@@ -139,48 +116,57 @@ if (args.length === 1 && args[0] === 'explain') {
     }
 }
 /**
- * Read the `covenant check` flags as a domain, or null when the argv is not one of the
- * three recognized forms: no flags is the staged diff, `--worktree` is the working tree,
- * and `--range <base>..<head>` (or `...` for the merge-base reading) is a ref range.
+ * Read the `covenant check` flags, or null for any argv outside the finite table: `--diff`
+ * at most once, `--enforce` at most once with `advise` or `block`, in either order, and
+ * nothing else.
  */
-function parseCheckDomain(flags) {
-    if (flags.length === 0)
-        return { kind: 'staged' };
-    if (flags.length === 1 && flags[0] === '--worktree')
-        return { kind: 'worktree' };
-    if (flags.length !== 2 || flags[0] !== '--range')
-        return null;
-    const range = flags[1];
-    if (range.startsWith('--'))
-        return null;
-    const mergeBase = range.includes('...');
-    const separator = mergeBase ? '...' : '..';
-    const at = range.indexOf(separator);
-    if (at === -1)
-        return null;
-    const base = range.slice(0, at);
-    const head = range.slice(at + separator.length);
-    if (base === '' || head === '')
+function parseCheckFlags(flags) {
+    let diffMode = false;
+    let enforce;
+    for (let i = 0; i < flags.length; i += 1) {
+        const flag = flags[i];
+        if (flag === '--diff' && !diffMode) {
+            diffMode = true;
+            continue;
+        }
+        if (flag === '--enforce' && enforce === undefined) {
+            const level = flags[i + 1];
+            if (level !== 'advise' && level !== 'block')
+                return null;
+            enforce = level;
+            i += 1;
+            continue;
+        }
         return null;
-    return { kind: 'range', base, head, ...(mergeBase && { ancestry: 'merge-base' }) };
+    }
+    return { diffMode, enforce };
 }
-const domain = args[0] === 'covenant' && args[1] === 'check' ? parseCheckDomain(args.slice(2)) : null;
-if (domain === null) {
-    process.stderr.write('usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain | pdks init claude-code | pdks init grok | pdks docs [topic]\n');
+const check = args[0] === 'covenant' && args[1] === 'check' ? parseCheckFlags(args.slice(2)) : null;
+if (check === null) {
+    process.stderr.write('usage: pdks covenant check [--diff] [--enforce advise|block] | pdks explain | pdks init | pdks docs [topic | search <query> | show <document-id>]\n');
     process.exit(2);
 }
+const { diffMode, enforce } = check;
 try {
     // Loaded here rather than at the top of the file. This runner statically pulls in the
-    // git adapter, the core, and the judge, so a top-level import made every subcommand
-    // wait on all three resolving — and `docs` is the one that has to answer in a tree
-    // where they do not, since a package installed but never built is exactly the state
-    // `pdks docs install` is asked about. The catch below already answers for whatever
-    // this import cannot do, at the same exit 2 it answers everything else with.
+    // core and the judge, so a top-level import made every subcommand wait on both
+    // resolving — and `docs` is the one that has to answer in a tree where they do not,
+    // since a package installed but never built is exactly the state `pdks docs install`
+    // is asked about. The catch below already answers for whatever this import cannot do,
+    // at the same exit 2 it answers everything else with.
     const { runCovenantCheck } = await import('./covenant-check.js');
+    const { covenantInputFromUnifiedDiff } = await import('./diff-ir.js');
+    const text = readStdin();
     const { exitCode } = await runCovenantCheck({
         repoRoot: process.cwd(),
-        ttyPrompt: openTtyPrompt(),
-        domain,
+        // A thunk, not a value: the runner settles the telemetry path before calling it, so a
+        // translation or parse failure lands as the same one blocked row every other
+        // fail-closed branch leaves.
+        input: () => (diffMode ? covenantInputFromUnifiedDiff({ text }) : JSON.parse(text)),
+        // The input mode is the surface: a diff is a finished change set, anything else is one
+        // call the caller observed.
+        surface: diffMode ? 'changeSet' : 'session',
+        ...(enforce !== undefined && { enforce }),
     });
     process.exit(exitCode);
 }