polydeukes 0.5.0 → 0.6.1

package/dist/docs/troubleshooting.md

@@ -2,161 +2,136 @@
 
 **English** · [한국어](./troubleshooting.ko.md)
 
-> Alpha. Nine states cover what ships today — five ways a fail-closed system refuses to
-> proceed, and four things worth knowing when a judgment surprises you. Each entry is
-> symptom → cause → recovery.
+Diagnose the failed stage before changing policy. If a session blocks the repair command itself,
+run the repair from your own terminal. `pdks docs` remains usable without project configuration
+or the judging packages, provided its own installed documentation bundle is intact.
 
-This is the guide layer for recovery: the fail-closed states, reading verdicts, and the
-witness valve.
+<a id="no-config"></a>
+## No config found
 
-The one principle behind half of this page: **a gate that cannot judge blocks rather than
-guesses.** A missing config, an ambiguous config, an invalid config, an installer that
-cannot prove resolution, and a judge that cannot be loaded all fail closed, because a dead
-gate that waves things through is the cheapest bypass of all. The recovery is never to
-disable the gate — it is to give it back what it needs to judge. And run that recovery
-**from your own terminal**: inside a session the repair commands are judged by the very
-gate they repair, and while no config is loaded there is no witness valve to open.
-
-## Every call is blocked and there is no config
-
-**Symptom.** On the session surface, every editing tool call and shell command exits 2;
-on the commit surface, every `pdks covenant check` run does. The error says no Polydeukes
-config was found and names the three candidate filenames.
-
-**Cause.** The surface is wired but config discovery found nothing at the project root.
-Discovery looks for exactly these, in this order: `polydeukes.config.yaml`,
-`polydeukes.config.yml`, `polydeukes.config.json`. A missing config never silently loads
-defaults — silent defaults would mean silently unprotected.
-
-**Recovery.** Restore the file from git. On the session path,
-`pnpm exec pdks init claude-code` recreates the missing artifacts; on the commit path the
-config is hand-written — the [install guide](./installation.md)'s commit-surface section
-has a starting point.
+Commands that need configuration exit 2 when none of `polydeukes.config.yaml`,
+`polydeukes.config.yml`, or `polydeukes.config.json` exists directly at the project root.
+Restore the intended file from Git, or use `pdks init claude-code` / `pdks init grok` for a new
+project. Then run `pdks explain`. No configuration means no silent default policy.
 
+<a id="multiple-config"></a>
 ## More than one config file
 
-**Symptom.** Every call exits 2 with an error naming two (or three) config files at once.
-
-**Cause.** Two spellings coexist — say a `polydeukes.config.yaml` created next to a
-project's existing `.yml`. Ambiguity never picks a winner.
+An ambiguity error names the competing files. Merge their intended contents and retain exactly
+one accepted filename. The loader will not choose one on your behalf. Retry `pdks explain`.
 
-**Recovery.** Keep exactly one file and delete the others. If both have content, merge by
-hand first — the loader will not choose for you.
+<a id="invalid-config"></a>
+## Invalid config
 
-## The config is invalid
+Parsing or schema failures exit 2 and name the file; schema errors also identify the offending
+field. Repair invalid YAML, custom tags, unknown fields, or an empty `languages` object.
+Custom YAML tags are rejected even if the parser cannot execute them: configuration is data.
 
-**Symptom.** Every call exits 2 with an error naming the offending file — and, for schema
-violations, the exact key.
+Typos such as `protectedPath:` or `adaptors:` are refused. Adapter namespace names are deliberately
+open, however: `adapters.gti:` can load but is not read by the Git adapter. Its actual key is
+`adapters.git`. After repair, run `pdks explain` and check the assembled registrations.
 
-**Cause.** One of: a YAML parse error; a custom YAML tag (rejected even though the parser
-cannot execute it — config data stays uncomputable by contract); an unknown key (a typo
-like `protectedPath:` is rejected with the full field path — with one open ground: an
-adapter namespace's *name* is not validated, so `adapters.gti:` for `adapters.git:` loads
-clean and its entries are simply never read; that one spelling you check yourself); or an
-empty `languages` block, the schema's one required entry.
+<a id="grok-witness"></a>
+## Grok witness
 
-**Recovery.** Fix the named key in the named file. The error is specific on purpose — no
-rewrite-and-hope needed.
+A hook not yet loaded and an unavailable witness valve are different problems:
 
-## `pdks init claude-code` refuses to run
+- After `pdks init grok`, reload the Hooks tab or start a new session. Verify an actual call and
+  its telemetry; a successful installer run does not prove the open host loaded the hook.
+- Grok's ACP history does not supply the Claude-format human message required by the current
+  session witness valve. Reloading does not add that capability. Perform a necessary repair
+  from your own terminal rather than trying to send a Claude witness token through Grok.
 
-**Symptom.** The installer prints an install command and exits 2 without creating anything.
+A commit witness authorizes its staged check only. It cannot release a blocked Grok tool call.
 
-**Cause.** Preflight: before writing any file, the installer proves the `polydeukes`
-package resolves from the target project root. A hook generated without that would block
-every call through its own fail-closed catch — an uneditable tree. The usual trigger is
-running via a one-off `npx` without installing, or running in the wrong directory (it
-installs where it is invoked).
+<a id="config-fault"></a>
+## Config-fault
 
-**Recovery.** `pnpm add -D polydeukes` in the project you meant, then re-run from that
-root. Zero files were written, so there is no partial state to clean up.
+The configuration loaded, but an entry could not compile into a judgment. A matching registration
+records `skipped` with `config-fault`; `pdks explain` shows the fault. Check extraction step names,
+arguments, regex syntax, and paired versus single extraction use. Fix the named declaration and
+repeat the same observation. A skipped entry is not a passing one.
 
+<a id="judge-cannot-be-loaded"></a>
 ## The judge cannot be loaded
 
-**Symptom.** Every call exits 2 with `covenant hook failed closed: Cannot find package
-'polydeukes'` — or an error naming a judge-body file that does not exist.
+A missing package or judging module fails closed. Reinstall the package or run the complete
+workspace build from your own terminal. The generated hook delegates to the installed package;
+it is not an independent copy of the judge. Verify another real call after repair. A failure
+before telemetry can load may leave no row at all.
+
+The session hook prefixes the message with `covenant hook failed closed:` and the commit check
+with `covenant check failed closed:`. The two shapes you will see:
 
-**Cause.** The hook is wired but the package it delegates to is gone or incomplete: the
-dependency was removed, the tree is a fresh clone that was never installed, or (in a
-source clone of this repository) the judge's build output is missing. The installer's
-preflight prevents *wiring* a project into this state, but nothing prevents a wired
-project from entering it later.
+```text
+covenant hook failed closed: Cannot find package 'polydeukes' imported from …
+covenant check failed closed: the covenant judges could not be loaded from … — run 'pnpm build' to rebuild them: Cannot find module './self-mod.js' …
+```
 
-**Recovery.** From your own terminal, reinstall the dependency (`pnpm install`, or
-`pnpm add -D polydeukes` if it was removed). In a source clone, run the build. The hook
-file itself needs no repair — it is a delegator, and it recovers the moment the package
-resolves again.
+The first is the installed package missing; the second is a source checkout whose judge
+build output is missing or partial.
 
+<a id="reading-verdict"></a>
 ## Reading a verdict
 
-**Symptom.** Something was blocked (or passed) and you want to know what the record says.
+| Record | Meaning |
+|---|---|
+| `passed` | The observed input was judged and upheld the covenant. |
+| `blocked` | A violation stopped the operation. |
+| `witnessed` | A blocking result was allowed through its witness valve. |
+| `advised` | A violation was recorded without stopping the operation, on either surface. |
+| `skipped` | No judgment was possible for the matching registration. This is not a pass. |
+| `unattributed` | Baseline comparison found protected changes without an explaining judgment, or could not read a valid baseline. This is an observation, not a verdict. |
 
-**Cause.** Not a failure — this is the measurement working. Every judgment appends exactly
-one record to the telemetry log (`.polydeukes/roi.log` by default, `telemetry.logPath` to
-move it).
+Judgments append telemetry at `.polydeukes/roi.log` unless `telemetry.logPath` changes the location.
+Logging is fail-open: a write failure does not alter the verdict. Exit 0 means the operation may
+continue, not that every discipline passed.
 
-**Recovery.** Read the last lines and the six-word vocabulary:
+<a id="opening-a-blocked-call"></a>
+## Opening a blocked call
 
-| Word | Means |
-|---|---|
-| `passed` | Judged, upheld the covenant. |
-| `blocked` | Judged, broke it. The call did not run. |
-| `witnessed` | A blocked verdict a human opened in person. Never silent. |
-| `advised` | Commit surface at `advise` level: a break recorded without stopping the commit. |
-| `skipped` | A registration matched but could not judge — **the recorded absence of a judgment, not a pass.** |
-| `unattributed` | A protected entry changed on disk and no judgment explains it — **an observation, not a verdict.** Nothing was blocked; the write already happened. |
+In a supported Claude Code session, type the configured witness token alone on the first line
+of a human message, then retry within its configured TTL. The message may also precede an
+intentional protected edit; no previous failed attempt is required. The token is not a secret.
+The valve checks human provenance and applies only to a blocking judgment. A successful retry
+appends a `witnessed` row; it does not rewrite the earlier blocked row.
 
-An `unattributed` row names the entry, not the file inside it. Rebuilding a protected `dist`
-without a judged call producing one is expected — it says a write reached that entry outside
-the session's view, which is exactly what the row is for.
+A witness cannot repair missing modules or other failures that prevent judgment assembly.
 
-## Opening a blocked call — the witness
+<a id="blocked-commit"></a>
+## A blocked commit
 
-**Symptom.** A call you and your agent agree should proceed was blocked, and you want it
-through without editing the policy.
+Run the commit from your own terminal and answer its TTY prompt with the complete configured
+token. A non-interactive staged check cannot obtain that answer. The check exits 2 when it refuses;
+Git may report a different nonzero exit code for the failed commit.
 
-**Cause.** The valve exists for exactly this, and it sits *after* the verdict — only a
-judgment that actually blocked can be witnessed open.
+A normal entry blocks only when its own level and the adapter's level both permit blocking.
+Setting only `adapters.git.enforce: block` does not promote default-`advise` entries. Changing a
+level is a policy decision, not a required repair. The prompt is separate from a session message.
 
-**Recovery.** Type the token from your config's `witness:` block so it stands **alone on
-the first line** of a conversation message. The window holds for `ttlMinutes`, then
-blocking resumes on its own. Three things that do not work, by design: quoting or
-mentioning the token mid-sentence (invocation is first-line-standalone only); witnessing a
-call that was never blocked (the valve is consulted only after a block); and the agent
-typing the token for itself (only human-authored messages count — the defence is
-provenance, not secrecy). Every allowance lands as one `witnessed` row.
+<a id="skipped-rows-on-the-commit-surface"></a>
+## `skipped` rows on the commit surface
 
-## A blocked commit
+A transcript-reading declaration with `supply: { session: 'pass' }` records `supply-pass` when the
+commit surface has no session. Use the session surface for that promise; a skip does not verify
+history. Other unavailable channels can produce `no-observation`. Inspect the registration and
+reason instead of treating every missing source as the same failure.
 
-**Symptom.** `git commit` stops at a prompt asking a human to witness a staged protected
-change — or, from an agent, the commit simply fails with exit 2.
+A command-scoped declaration does not match a staged diff's absent command line and records no
+judgment there. Configuration, scope matching, supply, and the final comparison are separate steps.
 
-**Cause.** The commit surface at the default `block` level judges the staged diff, and its
-valve is a TTY prompt. An agent-spawned commit has no TTY, so for it the valve is not even
-assembled — a terminal-holding human is the pass condition, not a workaround.
+<a id="local-state"></a>
+## Moving a project between machines
 
-**Recovery.** Run the commit from your own terminal and answer the prompt with the full
-token — one answer covers that whole commit. If you want the commit surface to measure
-without stopping, set `adapters.git.enforce: advise`: verdicts are then recorded as
-`advised` and the commit proceeds with one advisory line on stderr. At either level a run
-that *cannot judge* (missing or invalid config, an unresolvable judge) still exits 2 —
-`advise` relaxes the verdict, never the gate's integrity.
+Telemetry and `.polydeukes/baseline.json` are local state, not a portable history supplied by Git.
+A clone without them does not reconstruct prior judgments. The session hook records an absent
+or invalid baseline and establishes one for subsequent comparisons; this is not proof that old
+changes were judged. Preserve needed logs separately when migrating, and check any custom
+`telemetry.logPath` rather than assuming `.polydeukes/` holds all records.
 
-## `skipped` rows on the commit surface
+<a id="next-steps"></a>
+## Next steps
 
-**Symptom.** A `requirePrecedent` discipline that judges normally in sessions always lands
-as `skipped` on commits.
-
-**Cause.** Context-family disciplines judge *session history* — was the required step
-actually executed before this change. A commit has no session to read, so the entry
-assembles as a skip registration: routing intact, no judge body. When its scope matches a
-staged change it records `skipped` with the entry's id and proceeds.
-
-**Recovery.** None needed — this is a declared condition of the surface, not a defect. The
-row is the point: a gate that did nothing says so in the data. `pdks explain` shows the
-same fact before any commit: every context entry appears under the commit surface as a
-`skip` line carrying the reason. A context-family entry is
-really a session-surface tool — on a project that wires only the commit surface, such an
-entry only ever buys telemetry, so declare it where an AI partner's session exists to be
-judged. The row appears only when the entry's scope actually matched, so an unrelated
-commit records nothing.
+- [Connect the surfaces](./how-to/connect-surfaces.md)
+- [Configure the project](./how-to/configure-project.md)
+- [Write disciplines](./how-to/write-disciplines.md)

package/dist/docs/tutorials/first-judgment.ko.md

@@ -0,0 +1,82 @@
+# 설치하고 첫 판정 확인하기
+
+[English](./first-judgment.md) · **한국어**
+
+빈 예제 프로젝트에 Polydeukes를 설치하고 보호된 파일을 바꾸지 않은 채 쓰기 요청의 판정
+결과를 확인합니다. Node.js 24 이상, pnpm, git이 필요합니다. 실제 세션 호출을 확인하려면
+Claude Code도 필요하지만, 아래 훅 검사 명령은 Claude Code 없이 실행할 수 있습니다.
+
+<a id="claude-code"></a>
+
+## 클로드 코드 연동 설치와 첫 쓰기 요청 검사
+
+기존에 보호 중인 프로젝트 밖에서, 자신의 터미널로 다음 명령을 실행합니다.
+
+```sh
+mkdir pdks-example
+cd pdks-example
+git init
+printf '{"name":"pdks-example","private":true}\n' > package.json
+pnpm add -D polydeukes   # 프로젝트 의존성. 일회성 npx 실행이 아님
+pnpm exec pdks init claude-code
+```
+
+설치기는 각 파일을 만들었으면 `created`, 이미 있어서 보존했으면 `skipped`로 보고합니다.
+초기 설정, 훅 위임 파일, Claude Code 등록 설정, 문서 조회 안내, `discipline-draft` 스킬과
+텔레메트리 제외 항목을 만듭니다. 기존 사용자 파일은 보존하고, 설정은 통째로 덮지 않고
+병합합니다.
+
+생성된 훅에 설정 파일을 쓰려는 요청을 전달합니다.
+
+```sh
+printf '%s\n' '{"tool_name":"Write","tool_input":{"file_path":".claude/settings.json","content":"{}"}}' \
+  | node .claude/hooks/covenant-pretooluse.mjs
+printf 'exit=%s\n' "$?"
+tail -n 5 .polydeukes/roi.log
+```
+
+예상 결과는 `exit=2`입니다. stderr에는 보호 경로를 지목한 메시지가 나오고, 로그에는
+`blocked` 행이 남습니다. 이 명령은 판정만 요청하며 **실제로 파일을 쓰지 않습니다**.
+설정 파일은 그대로이므로 되돌릴 변경도 없습니다.
+
+이번에는 보호 목록 밖의 경로로 같은 검사를 합니다.
+
+```sh
+printf '%s\n' '{"tool_name":"Write","tool_input":{"file_path":"example.txt","content":"hello"}}' \
+  | node .claude/hooks/covenant-pretooluse.mjs
+printf 'exit=%s\n' "$?"
+tail -n 5 .polydeukes/roi.log
+```
+
+초기 설정에서는 `exit=0`과 `passed` 행이 나와야 합니다. 이 명령도 파일을 쓰지는 않습니다.
+설치된 판정기로 차단할 요청과 허용할 요청을 각각 확인한 것입니다.
+
+실제 도구 호출에 훅을 적용하려면 이 프로젝트에서 Claude Code를 엽니다. 일반 텍스트 파일을
+만들도록 요청한 뒤 `.polydeukes/roi.log`에 새 행이 생기는지 확인합니다. 앞의 직접 호출
+검사만으로는 특정 호스트 세션이 훅 등록을 읽었다고 판단할 수 없습니다.
+
+**처음 설정을 바꾸기 전에 확인하세요.** 로더는 발견한 설정 파일을 자동으로 보호합니다.
+`protectedPaths`에 파일명이 없어도 같습니다. 세션에서 의도적으로 편집하려면
+`witness.token`을 읽고, 사람이 직접 메시지 첫 줄에 그 토큰만 입력합니다. 초기 토큰은
+`pdks witness`이며 유효 시간은 10분입니다. 증인(witness) 밸브는 판정기가 차단한 결과에만
+적용됩니다. 에이전트가 사람을 대신해 메시지를 공급할 수는 없습니다. 자신의 터미널에서
+의도한 설정 변경을 직접 수행해도 됩니다.
+
+패키지나 설정을 읽지 못해 검사가 실패하면 자신의 터미널에서 지목된 파일을 고치거나
+패키지를 다시 설치합니다. 밸브를 조립하는 단계에 이르기 전에 발생한 오류는 증인으로 해결할 수 없습니다.
+[설정 오류](../troubleshooting.ko.md#invalid-config)와
+[판정기 로드 실패](../troubleshooting.ko.md#judge-cannot-be-loaded)를 참고하세요.
+
+<a id="next-step"></a>
+
+## 실제 프로젝트에 적용하기
+
+- [프로젝트 설정](../how-to/configure-project.ko.md)에서 임시 언어 이름과 테스트 명령을
+  바꿉니다.
+- Grok이나 git pre-commit 훅은 [관측 표면 연결](../how-to/connect-surfaces.ko.md)을 참고합니다.
+- [규율 작성](../how-to/write-disciplines.ko.md) 예제를 실행하고, 권고 결과를 확인한 뒤 차단
+  여부를 결정합니다.
+
+종료 코드만으로 모든 관측 결과를 알 수는 없습니다. `advised`나 `skipped`가 있어도 exit 0일
+수 있습니다. 진단 메시지와 [판정 결과 어휘](../troubleshooting.ko.md#reading-verdict)를 함께
+확인하세요.

package/dist/docs/tutorials/first-judgment.md

@@ -0,0 +1,81 @@
+# Install and get your first judgment
+
+**English** · [한국어](./first-judgment.ko.md)
+
+Use an empty example project to install Polydeukes and check a protected write without changing
+the protected file. You need Node.js 24 or later, pnpm, and git. Claude Code is needed to observe
+live session calls, but not to run the hook probe below.
+
+<a id="claude-code"></a>
+
+## Install Claude Code integration and check a write
+
+Run these commands in your own terminal, outside an existing protected project:
+
+```sh
+mkdir pdks-example
+cd pdks-example
+git init
+printf '{"name":"pdks-example","private":true}\n' > package.json
+pnpm add -D polydeukes   # a project dependency, not a one-off npx run
+pnpm exec pdks init claude-code
+```
+
+The installer reports `created` or `skipped` for each artifact. It creates a starter config,
+the hook delegator, the Claude Code registration, a documentation discovery file, the
+`discipline-draft` skill, and a telemetry ignore entry. Existing user files are preserved;
+settings are merged rather than replaced.
+
+Now send the generated hook an observation of a proposed write to its settings file:
+
+```sh
+printf '%s\n' '{"tool_name":"Write","tool_input":{"file_path":".claude/settings.json","content":"{}"}}' \
+  | node .claude/hooks/covenant-pretooluse.mjs
+printf 'exit=%s\n' "$?"
+tail -n 5 .polydeukes/roi.log
+```
+
+Expect `exit=2`, a diagnostic naming the protected path on stderr, and a `blocked` row in the
+log. This command only asks for a judgment. It does **not** perform the proposed write, so the
+settings file stays unchanged and there is no destructive edit to undo.
+
+Repeat with a path outside the protection list:
+
+```sh
+printf '%s\n' '{"tool_name":"Write","tool_input":{"file_path":"example.txt","content":"hello"}}' \
+  | node .claude/hooks/covenant-pretooluse.mjs
+printf 'exit=%s\n' "$?"
+tail -n 5 .polydeukes/roi.log
+```
+
+Expect `exit=0` and a `passed` row for this starter configuration. Again, no file is written.
+You have checked both a blocked and an allowed observation using the installed judge.
+
+Open Claude Code in this project to use the same hook on actual tool calls. Ask it to create
+an ordinary text file, then confirm that a new row appears in `.polydeukes/roi.log`. The direct
+probe above does not prove that a particular host session loaded its hook registration.
+
+**Before the first config edit:** the loader automatically protects the discovered config
+file, even though it is not written in `protectedPaths`. For an intentional session edit, read
+`witness.token` and type that token yourself on the first line of a message, with nothing else
+on that line. The starter token is `pdks witness` and its window is ten minutes. The valve
+supplies permission only after a blocking verdict; an agent cannot supply the human message
+for you. Alternatively, make the deliberate configuration edit from your own terminal.
+
+If the probe fails because the package or configuration cannot load, repair the named file or
+reinstall from your own terminal. A witness cannot repair a failure that occurs before the
+valve is assembled. See [configuration errors](../troubleshooting.md#invalid-config) and
+[missing judge](../troubleshooting.md#judge-cannot-be-loaded).
+
+<a id="next-step"></a>
+
+## Continue with a real project
+
+- [Configure the project](../how-to/configure-project.md) to replace the placeholder language
+  and test command.
+- [Connect the surfaces](../how-to/connect-surfaces.md) for Grok or a git pre-commit hook.
+- [Write a discipline](../how-to/write-disciplines.md) and observe an advisory before choosing
+  whether it should block.
+
+An exit code alone does not describe all observations. `advised` and `skipped` can accompany
+exit 0. Read the diagnostic and the [verdict vocabulary](../troubleshooting.md#reading-verdict).

package/dist/docs-catalog.d.ts

@@ -0,0 +1,25 @@
+import type { DocsBundleDocument, DocsBundleSection, DocsIndex, LoadedDocsBundle } from './docs-types.ts';
+/**
+ * Validate the source collection before replacing the output with bundled Markdown and metadata.
+ *
+ * @param spec - Source and non-overlapping output roots, with an optional catalog file path.
+ * @returns Metadata for bundled documents and sections; excluded documents are not copied.
+ * @throws If the roots overlap or the catalog, source files, or topic references fail validation.
+ */
+export declare function buildDocs(spec: {
+    sourceRoot: string;
+    outputRoot: string;
+    catalogPath?: string;
+}): {
+    documents: DocsBundleDocument[];
+    sections: DocsBundleSection[];
+};
+/**
+ * Load a bundle only after its stored index matches the catalog and bundled Markdown.
+ *
+ * @param outputRoot - Built documentation directory containing catalog.json and index.json.
+ * @returns Validated metadata and bundled documents with their original Markdown and sections.
+ * @throws If metadata or documents are missing, invalid, or inconsistent with the stored index.
+ */
+export declare function loadDocsBundle(outputRoot: string): LoadedDocsBundle;
+export type { DocsIndex };