polydeukes 0.3.0 → 0.4.0

package/dist/docs/reference/configuration.md

@@ -0,0 +1,294 @@
+# Configuration reference
+
+**English** · [한국어](./configuration.ko.md)
+
+Every key of `polydeukes.config.yaml`, one section per key. The guide — what the file is,
+how discovery fails, and the IDE wiring — is
+[Configuring Polydeukes](../configuration.md), and what a verdict looks like when a
+discipline fires is its
+[What enforcement looks like](../configuration.md#what-enforcement-looks-like) section.
+
+## `languages`
+
+Required. The language axis, first-class. Keys are your values (`typescript`, `python`, …) —
+the core ships no language names and never interprets the command string.
+
+```yaml
+languages:
+  typescript:
+    productionGlob: 'packages/*/src/**/*.ts'   # what counts as production source
+    testCmd: 'pnpm --filter {scope} test'      # {scope} is substituted at resolve time
+```
+
+`testCmd` is a template string, not a function. Every `{scope}` occurrence is replaced;
+all other braces (`${VAR}`, `{a,b}`, `awk '{print}'`) pass through untouched. A command
+that ignores scope (`pnpm test`) is equally valid.
+
+## `protectedPaths`
+
+Optional. Raw path patterns whose files the covenants protect from modification — by
+editor tools and by shell commands alike (`sed -i`, `tee`, redirects, heredocs,
+parent-directory moves). Entries are normalized (trimmed, deduplicated) at resolve time.
+An empty-string entry is rejected at load time — it carries no path meaning.
+
+```yaml
+protectedPaths:
+  - 'packages/core/src'
+  - '.claude/hooks'
+```
+
+**The config file protects itself.** The discovered config file is automatically appended
+to `protectedPaths` — an edit that would lower your own gates goes through the same judge
+as everything else. If the file that declares the disciplines were not itself under the
+disciplines, the whole chain would be decoration.
+
+## `adapters`
+
+Optional. Adapter namespaces. One config file, one namespace per adapter: each key names an
+adapter, and its value is that adapter's own settings object. The core validates the
+container shape only — the keys and the contents belong to each adapter, which ships
+its own validator for its own vocabulary. An unknown key *inside* a namespace is
+rejected by that adapter's validator, with the full field path in the error.
+
+```yaml
+adapters:
+  git:
+    enforce: advise
+    protectedPaths:
+      - 'packages/core/src'
+```
+
+### `adapters.git` — the git commit adapter
+
+| Key | Values | Default | Meaning |
+|---|---|---|---|
+| `enforce` | `block` \| `advise` | `block` | Enforcement level of the commit surface |
+| `protectedPaths` | string array | `[]` | Additive protection scope judged by the commit surface only |
+
+- **`block`** — a staged change that breaks a covenant blocks the commit (exit 2). The
+  only way through is the witness valve: a human answering the TTY prompt with the full
+  token. The prompt names what it asks the human to witness — the broken registration,
+  the matched entry, and the fact that the one answer covers the whole commit. An absent
+  namespace, an absent `adapters` map, or an absent `enforce` key all mean `block` — not
+  writing the key selects the strictest level.
+- **`advise`** — the commit surface becomes a backstop without a block: a verdict on a
+  staged change is recorded as an `advised` telemetry event and the commit proceeds
+  (exit 0) with one advisory line on stderr. No TTY prompt fires. Only the verdict is
+  relaxed — a run that cannot judge (missing or invalid config, an unresolvable judge
+  body) still fails closed at exit 2, at either level.
+
+**`protectedPaths` here is an additive scope.** The commit surface judges the union of the
+top-level `protectedPaths` and this list — concatenated (common first) and normalized as one,
+so spelling and dedupe rules are identical for both. The session surface never reads it: the
+list exists for paths whose edit is legitimate work during a session but must pass a judged
+checkpoint when it is promoted into repository history — a judgment chain's own sources are
+the canonical tenant. As the enforcement level is the observer's setting, so is the
+additional scope. There is no subtractive vocabulary: a config line can widen a surface's
+scope, never quietly strip one.
+
+The session surface (the editor-time hook) has no level setting here; it always blocks.
+
+**Context-family disciplines skip on the commit surface.** A commit has no session to look
+at, so a `requirePrecedent` entry cannot be judged there — demanding evidence a commit
+cannot carry would block every matching commit with no legitimate way through.
+
+They are not filtered out, though. They assemble like any other discipline and become
+*skip registrations*: routing intact, no judge body. When one matches a staged change it
+records a `skipped` telemetry event and lets the commit proceed. The record carries the
+entry's `id` and the change it would have judged, so a gate that did nothing says so in
+the data — and it appears **only when the entry's scope actually matched**, so a commit
+touching nothing the entry cares about records nothing at all.
+
+This is the same disposition the session surface uses whenever it has no transcript to
+read. One rule, both surfaces: evidence that cannot be evaluated is skipped and measured,
+never blocked and never silent.
+
+## `telemetry`
+
+Optional.
+
+```yaml
+telemetry:
+  logPath: '.polydeukes/roi.log'   # default when omitted; keep it gitignored
+```
+
+Every judgment — passed, blocked, witnessed, advised, or skipped — appends one record.
+Telemetry is fail-open by design: a logging failure never changes a verdict. The path
+itself is still validated at load time — an empty or whitespace-only `logPath` is
+rejected.
+
+## `witness`
+
+Optional.
+
+```yaml
+witness:
+  token: 'covenant witness'   # the phrase a human types in the conversation
+  ttlMinutes: 10              # validity window, in minutes, from that message
+```
+
+The values of the time-boxed human valve, consumed where the covenants are assembled.
+The valve is sudo, not an exemption: the one property a deterministic gate can compute
+about a judgment chain is "is an accountable human present, right now", and the witness
+is that human supplying the pass condition in person. When a covenant blocks a
+legitimate edit, a human types the agreed token into the conversation; blocked judgments
+can be witnessed open for `ttlMinutes` from that message's timestamp, then blocking
+resumes automatically. Both keys are required when the section is present: the token
+must be non-empty after trimming, the window a finite number greater than zero.
+
+**The valve stands after the verdict, never instead of it.** The judge body always runs.
+A call that would have passed anyway never consults the valve, so an open window changes
+nothing about clean work — and a `witnessed` telemetry row therefore always names a real
+block a human answered for, never a ritual. Only a judgment that actually blocked can be
+witnessed open.
+
+**The token must stand alone on the message's first line.** Invoking the witness is
+distinct from talking about it: a message that quotes, questions, or explains the token
+mid-sentence — or wraps it in backticks — does not open the valve, while a first line
+carrying the token alone does, with any following lines free for the work itself.
+
+A message that invokes — the token alone on the first line, the rest free:
+
+```text
+covenant witness
+
+now fix the hook file
+```
+
+A message that merely mentions — the valve stays shut:
+
+```text
+so when does `covenant witness` expire?
+```
+
+The token's value is free — any phrase works, and it is never checked for a prefix or a
+command shape. Only its placement is constrained.
+
+The token is not a secret — the defense is provenance, not secrecy. A witness counts only
+when the token arrives in a message positively identified as human-typed in the session
+transcript, so an AI that knows the token still cannot forge one. Witnessed judgments are
+recorded as `witnessed`, never silent.
+
+## `disciplines`
+
+Optional. Each entry is one discipline: a practice the team imposes on itself, declared as
+data. An entry carries exactly **one** predicate (zero or two is rejected), an `id` (the
+telemetry label), and optionally a `why` (the reason, kept next to the rule) plus, on a
+`forbid` or `requirePrecedent` entry, `in` (the file globs it judges) and `except` (globs
+carved out of that scope).
+
+**`forbid` — content delta.** Blocks an edit that *adds* a new match of the pattern.
+Existing occurrences are forgiven: adopting a discipline never blocks a legacy codebase,
+because the judgment direction is "what did this edit add", not "what does the file
+contain".
+
+```yaml
+disciplines:
+  - id: 'covenant-vocabulary'
+    why: 'control-framing vocabulary is banned in package sources.'
+    in:
+      - 'packages/*/src/**'
+    forbid: '\b(guard|harness|kb)\b'
+```
+
+**`immutable` — path family.** Blocks modification of existing files that match; creating
+new files is allowed.
+
+```yaml
+  - id: 'archived-records-stay-frozen'
+    why: 'an archive that can be edited is not an archive.'
+    immutable: 'records/archive/**'
+```
+
+**`forbidCommand` — command family.** Blocks shell commands matching the pattern, even
+when the command mentions no protected path. This is how gate-disarming commands are
+caught. A multi-line command is judged twice over — the pattern is tested against each
+line and against the whole string, so `^` means the start of a line while a pattern
+spanning a line boundary still matches (the whole-content caution further down applies
+to the delta and context families). An empty pattern is rejected at load time, here and
+on `forbid` alike — it would match every command.
+
+```yaml
+  - id: 'hooks-stay-armed'
+    why: 'a command that disarms or reroutes the git gate is a gate bypass in itself.'
+    forbidCommand: 'LEFTHOOK=(0|false|no|off)\b|core\.hooksPath'
+```
+
+**`requirePrecedent` — context family.** Blocks a change that arrives without a required
+step having happened earlier in the session. The other three families all ask "is this
+change itself bad"; this one asks something else. The change is legitimate — what is
+missing is the procedure in front of it, so what gets judged is not the mutation but the
+session history.
+
+Evidence means an **execution**, not a request. A call the covenant blocked, one a human
+refused, and one that simply failed all leave the same trace in a session, and none of
+them is precedent — the transcript is read for what actually ran and reported success.
+That is what keeps the cheapest way through the gate being the thing the discipline
+asks for.
+
+Two consequences are worth knowing before you write one. The outcome is read per command
+LINE, so a chain where the required command ran but a later step failed does not count.
+And the pattern is matched at the start of a simple command, so the same words in an
+argument or a comment do not count either. **In both cases running the command on its own
+opens the gate** — the block message says so.
+
+```yaml
+  - id: 'dependency-needs-npm-view'
+    why: 'a dependency version must be measured before it is written.'
+    in:
+      - 'package.json'
+      - 'packages/*/package.json'
+    when: '(^|\n)\s*"[^"]+"\s*:\s*"[~^]?\d[^"]*"'
+    requirePrecedent:
+      command: 'npm view '
+```
+
+The evidence vocabulary is layered. `command` is the core's own key — a shell call is a surface
+every agent shares — and the core validates it fully, rejecting an empty string or a pattern that
+does not compile. It is matched **at the start of a simple command**, not anywhere in the command
+line, so `echo "npm view yaml"` and a mention parked behind a `#` are not evidence while `cd pkg &&
+npm view yaml` is. Every other key belongs to an adapter: the core checks the container only (a flat
+object carrying exactly one evidence key) and passes the value through verbatim, and the adapter
+that owns the word validates and judges it. The Claude Code adapter brings two: `subagent` (exact
+match on a spawn kind) and `tool` (a regex over tool names) — so "query the docs tool before
+touching this" is expressible today. Both follow the same execution rule as `command`. An evidence
+key no assembled adapter recognizes cannot be judged, so the entry compiles to a skip registration:
+routing stays, the body is dropped, assembly names the fault once on stderr, and every matching
+change afterwards records `skipped` rather than a verdict. A typo therefore never passes itself off
+as adapter vocabulary — but it does leave the discipline inert, and the `skipped` rows are where
+that shows.
+
+`when` (optional) is the trigger: an added-direction delta regex, combinable with
+`requirePrecedent` and with nothing else. When it is absent, every change inside `in`
+scope triggers the discipline. The two keys divide the work — `in` says which files are
+watched, `when` says which change in them demands the precedent.
+
+**A caution on line anchors.** These patterns are matched against the file's whole content
+as a single string, and the config schema takes a regex string with no flags. `^` therefore
+anchors to the start of the *file*, not the start of a line, so a line-shaped pattern
+written with `^` matches only the first line and the discipline silently stops firing —
+the regex still compiles, the judgment still runs, and the verdict is `passed`. Write
+`(^|\n)` when you mean the start of a line. This is why the example above carries
+`(^|\n)\s*"[^"]+"…` rather than `^\s*"[^"]+"…`.
+
+**And a caution on match length.** The delta keys on the matched *text*: a change is only
+seen as added when the matched string itself differs between the file's before and after.
+A pattern that stops mid-value — say at the first digit of a version — produces the same
+match text for `4.0.5` and `4.0.6`, so a version bump adds nothing to the delta and the
+discipline silently passes. Make the pattern span the whole value that can change; the
+example above runs through the closing quote (`\d[^"]*"`) for exactly this reason. Both
+failure shapes are the same class: the regex compiles, the verdict says `passed`, and
+nothing tells you the discipline is inert — so when you add an entry, measure it against
+a real file and a realistic edit, not a one-line snippet.
+
+The kind of change matters at the trigger. With `when` present, a deletion never triggers
+— deleting adds no content. With `when` absent, deletion triggers like any other change in
+scope, since the declared scope is the whole mutation.
+
+**The cheap way through is the honest one.** Unlike the witness, this evidence lives on the
+AI's own surface, so it is not forgery-proof. It does not need to be: the least effortful
+way to open this gate is to actually call the tool, and that is exactly the behaviour the
+discipline exists to induce.
+
+Adding a discipline is a data edit — no code, no plumbing. Custom judge bodies remain the
+escape layer for the few rules data cannot express.

package/dist/docs/reference/core.md

@@ -83,10 +83,10 @@ attribution. Calls without evidence are skipped, never substituted for.
 Three places, all of them indirect.
 
 - **The config file.** Its schema is defined here. The vocabulary reference is
-  [configuration.md](../configuration.md).
-- **The JSON Schema artifact** — `@polydeukes/core/schema.json`, an exports subpath. Under
-  a default pnpm layout it does not resolve from a consumer's top-level `node_modules`,
-  because the core arrives as a transitive dependency; the working spellings are in
+  [the configuration reference](./configuration.md).
+- **The JSON Schema artifact** — `@polydeukes/core/schema.json`, an exports subpath, for a
+  project that installs this package directly. A consumer of the umbrella names the copy
+  bundled there instead; both spellings are in
   [configuration.md's IDE section](../configuration.md#ide-support).
 - **The protocol above** — reading a `blocked` row means reading the vocabulary a body
   answered in.

package/dist/docs/reference/covenant.md

@@ -37,7 +37,7 @@ determines whether it can be judged on a given surface.
 
 `when` is a trigger, not a family: it narrows a `requirePrecedent` entry and combines with
 nothing else. The writing guide for these entries — the four predicate forms, the two
-pitfalls — is [configuration.md's `disciplines` section](../configuration.md#disciplines-optional).
+pitfalls — is [the configuration reference's `disciplines` section](./configuration.md#disciplines).
 
 **Three meta-covenants** protect the judging chain. They are covenants like any other; the
 vocabulary below applies to them unchanged.
@@ -48,9 +48,9 @@ vocabulary below applies to them unchanged.
 | shell-mod | Shell | The same, through a command line. A command mentioning a protected path passes only if its leading word proves it read-only |
 | transcript-mod | Transcript | Writes to the live session transcript, judged by whole-path **equality** — never as a protected ancestor |
 
-**Five verdict words** are the telemetry contract. A row in `.polydeukes/roi.log` carries
-exactly one of them, and the CLI, the docs, and the tests use the same word for the same
-event. How to read a row is in
+**Six words** are the telemetry contract — five verdicts and one observation. A row in
+`.polydeukes/roi.log` carries exactly one of them, and the CLI, the docs, and the tests use
+the same word for the same event. How to read a row is in
 [troubleshooting](../troubleshooting.md#reading-a-verdict).
 
 | Verdict | Means |
@@ -60,6 +60,14 @@ event. How to read a row is in
 | `witnessed` | A **blocked** verdict a human opened in person. Never silent, never a clean call |
 | `advised` | The commit surface at `enforce: advise` recorded a break without stopping it |
 | `skipped` | The call reached a registration that could not judge it. **Not a pass** — the recorded absence of a judgment |
+| `unattributed` | A protected entry's on-disk state moved and no judgment row explains it. **Not a verdict** — no call is blocked or passed by it; the session surface writes it after comparing state against a stored baseline |
+
+`unattributed` answers a question the other five cannot. They are all written by a judge
+about a call it was handed, so a write that arrives without a declared call — through an
+interpreter, a test runner's child process, a script that assembles the path from its own
+arguments — leaves no row at all. The comparison observes the result rather than the
+spelling, so it records that write after the fact. It never blocks: the write already
+happened, and the comparison fails open on both sides of the verdict.
 
 ## Where the consumer touches it
 

package/dist/docs/reference/polydeukes.md

@@ -78,10 +78,10 @@ package, so the answer comes from the installed version rather than from the net
 | Topic | Answers from |
 |---|---|
 | `install` | [installation](../installation.md), in full |
-| `config` | [configuration](../configuration.md) — the Reference section |
-| `discipline` | [configuration](../configuration.md) — the `disciplines` section |
+| `config` | [the configuration reference](./configuration.md), in full |
+| `discipline` | [the configuration reference](./configuration.md) — the `disciplines` section |
 | `covenant` | [configuration](../configuration.md) — What enforcement looks like |
-| `witness` | [configuration](../configuration.md)'s `witness` section, then [troubleshooting](../troubleshooting.md)'s valve section |
+| `witness` | [the configuration reference](./configuration.md)'s `witness` section, then [troubleshooting](../troubleshooting.md)'s valve section |
 
 **Every failure leaves stdout at zero bytes.** A missing bundled document, a heading the
 document no longer carries, an unknown topic — each names what was missing on stderr and
@@ -203,8 +203,13 @@ needs no second dependency.
 |---|---|
 | `polydeukes` | The barrel — `loadConfig`, `runCovenantCheck`, `runClaudeCodeHook`, their spec types, `ResolvedConfig` |
 | `polydeukes/claude-code` | `runClaudeCodeHook` and `ClaudeCodeHookSpec` alone |
+| `polydeukes/schema.json` | The config JSON Schema, copied from the core at build time |
 
 The generated hook delegator imports the subpath, not the barrel. ESM imports are eager, so
 importing the barrel would load the commit-surface runner — and the git adapter behind it —
 on every session tool call that will never use them. The subpath is the session surface's
 own entry point, and the barrel is for programmatic consumers.
+
+`polydeukes/schema.json` is for code that reads the schema. A `$schema` line names the file
+path instead — an editor reads that string statically, so no module resolver runs on it. Both
+spellings are in [configuration.md's IDE section](../configuration.md#ide-support).

package/dist/docs/troubleshooting.md

@@ -6,6 +6,9 @@
 > proceed, and four things worth knowing when a judgment surprises you. Each entry is
 > symptom → cause → recovery.
 
+This is the guide layer for recovery: the fail-closed states, reading verdicts, and the
+witness valve.
+
 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
@@ -92,7 +95,7 @@ resolves again.
 one record to the telemetry log (`.polydeukes/roi.log` by default, `telemetry.logPath` to
 move it).
 
-**Recovery.** Read the last lines and the five-word vocabulary:
+**Recovery.** Read the last lines and the six-word vocabulary:
 
 | Word | Means |
 |---|---|
@@ -101,6 +104,11 @@ move it).
 | `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. |
+
+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.
 
 ## Opening a blocked call — the witness
 

package/dist/docs-query.js

@@ -24,11 +24,11 @@ const TOPIC_MAP = {
         seeAlso: 'reference/polydeukes.md',
     },
     config: {
-        sections: [{ file: 'configuration.md', heading: '## Reference' }],
+        sections: [{ file: 'reference/configuration.md' }],
         seeAlso: 'reference/core.md',
     },
     discipline: {
-        sections: [{ file: 'configuration.md', heading: '### `disciplines` (optional)' }],
+        sections: [{ file: 'reference/configuration.md', heading: '## `disciplines`' }],
         seeAlso: 'reference/covenant.md',
     },
     covenant: {
@@ -37,7 +37,7 @@ const TOPIC_MAP = {
     },
     witness: {
         sections: [
-            { file: 'configuration.md', heading: '### `witness` (optional)' },
+            { file: 'reference/configuration.md', heading: '## `witness`' },
             { file: 'troubleshooting.md', heading: '## Opening a blocked call — the witness' },
         ],
         seeAlso: 'reference/covenant.md',
@@ -129,10 +129,10 @@ export function queryDocs(spec) {
     }
     const entry = TOPIC_MAP[spec.topic];
     const body = entry.sections.map((section) => readSection(spec.docsRoot, section)).join('\n');
-    // Resolved against the bundle, not printed as the bare relative name. The reference layer
-    // ships but no topic reads it, so this line is the only way to reach those five documents —
-    // and a reader given `reference/core.md` has to guess where the bundle lives before it can
-    // open anything. A path a file-read tool can take is the difference between a pointer and
-    // a dead end, and a dead end sends the reader back to the web search this command replaces.
+    // Resolved against the bundle, not printed as the bare relative name. A reader given
+    // `reference/core.md` has to guess where the bundle lives before it can open anything, and
+    // this line is the only way most of the reference layer is reached at all. A path a file-read
+    // tool can take is the difference between a pointer and a dead end, and a dead end sends the
+    // reader back to the web search this command replaces.
     return { text: `${body}\nSee also: ${join(spec.docsRoot, entry.seeAlso)}\n` };
 }

package/dist/load-config.d.ts

@@ -32,8 +32,9 @@ export type LoadedConfig = {
  * (no upward walk). Every failure branch throws — silent defaults are forbidden:
  * zero files found (message names all three candidates), two or more found (message
  * names the collisions), a parse error or unresolved custom tag (safe core schema —
- * config data is never executable), or a `ConfigValidationError` from core
- * `defineConfig()` (re-thrown with file-path context, keeping the error type).
+ * config data is never executable; every problem the parser found is enumerated in the
+ * one message), or a `ConfigValidationError` from core `defineConfig()` (re-thrown with
+ * file-path context, keeping the error type).
  *
  * Before returning, the discovered `configPath` is appended to
  * `config.protectedPaths` unless already present — the config file itself joins the

package/dist/load-config.js

@@ -30,8 +30,9 @@ export const CONFIG_FILENAMES = [
  * (no upward walk). Every failure branch throws — silent defaults are forbidden:
  * zero files found (message names all three candidates), two or more found (message
  * names the collisions), a parse error or unresolved custom tag (safe core schema —
- * config data is never executable), or a `ConfigValidationError` from core
- * `defineConfig()` (re-thrown with file-path context, keeping the error type).
+ * config data is never executable; every problem the parser found is enumerated in the
+ * one message), or a `ConfigValidationError` from core `defineConfig()` (re-thrown with
+ * file-path context, keeping the error type).
  *
  * Before returning, the discovered `configPath` is appended to
  * `config.protectedPaths` unless already present — the config file itself joins the
@@ -53,7 +54,13 @@ export function loadConfig(rootDir) {
     const document = parseDocument(source);
     const problems = [...document.errors, ...document.warnings];
     if (problems.length > 0) {
-        throw new Error(`failed to parse ${configPath}: ${problems[0].message}`);
+        // Every problem in one message: reporting only the first costs one fix-rerun loop
+        // per hidden problem. Each parser message already carries its own position; a lone
+        // problem keeps the direct message shape.
+        const detail = problems.length === 1
+            ? problems[0].message
+            : `${problems.length} problems\n${problems.map((problem) => `  - ${problem.message}`).join('\n')}`;
+        throw new Error(`failed to parse ${configPath}: ${detail}`);
     }
     const parsed = document.toJS();
     // Strip the IDE `$schema` reference before delegating — the loader owns no

package/dist/scaffold-project.d.ts

@@ -25,13 +25,4 @@ export type ScaffoldReport = {
     created: string[];
     skipped: string[];
 };
-/**
- * Create the project-side artifacts of a Polydeukes installation in `projectRoot` (§3-i),
- * skipping whatever is already there.
- *
- * Throws when two or more config spellings coexist (§3-a third disposition) — that tree is
- * already stopped, since {@link loadConfig} refuses an ambiguous discovery, and adding
- * artifacts to it would wire a judge whose every call fails closed. The throw lands before
- * any write, so a human deleting one config is all it takes to reopen the path.
- */
 export declare function scaffoldProject(projectRoot: string): ScaffoldReport;

package/dist/scaffold-project.js

@@ -27,8 +27,10 @@ const GITIGNORE_ENTRY = `# Polydeukes telemetry — local observation data, neve
  * The generated config: the §3-d minimum protection set and the §3-e witness block, both
  * mandatory. Emitted as a literal template rather than serialized from an object because
  * the comments ARE the artifact — a consumer's first contact with the protection surface is
- * reading why each entry is on it. No `$schema` line: the consumer-side spelling of that
- * path is unmeasured (§2-c), and a wrong one loses editor validation silently.
+ * reading why each entry is on it.
+ *
+ * {@link schemaDirective} prepends the `yaml-language-server` line when the schema is where
+ * that line would name it (DIST-05 §3-b).
  */
 const GENERATED_CONFIG = `# Polydeukes protection policy — generated by \`pdks init claude-code\`.
 #
@@ -53,15 +55,9 @@ languages:
 #     layer that can watch it happen.
 #
 # A minimum. Add entries as you find you want them.
-#   node_modules, .claude/node_modules — the resolution path. The generated hook loads the
-#     judge by package NAME, so every directory Node's ancestor walk can answer from decides
-#     which code judges this session. A stub planted on that walk replaces the judge outright
-#     and every call then passes with no telemetry row at all.
 protectedPaths:
   - '.claude/hooks'
   - '.claude/settings.json'
-  - 'node_modules'
-  - '.claude/node_modules'
 
 # The time-boxed witness — the human valve on a blocked verdict. A human types this token so
 # it stands alone on a message's FIRST line, the window holds for ttlMinutes, then blocking
@@ -85,6 +81,24 @@ witness:
  * artifacts to it would wire a judge whose every call fails closed. The throw lands before
  * any write, so a human deleting one config is all it takes to reopen the path.
  */
+/** The schema's path from a config sitting in `projectRoot`, as the directive spells it. */
+const SCHEMA_REL = 'node_modules/polydeukes/dist/schema/polydeukes.schema.json';
+/**
+ * The `yaml-language-server` line for a config written into `projectRoot`, or nothing.
+ *
+ * An editor resolves a relative `$schema` against the config file's own directory, and this
+ * command writes the config where it was invoked — so in a monorepo sub-package, whose install
+ * hoisted to the workspace root, {@link SCHEMA_REL} names a path that is not there. The check
+ * is one look at that exact path: present means the line an editor would follow leads to the
+ * schema, absent means it leads nowhere, and a line leading nowhere is worse than none. An
+ * unresolvable `$schema` produces no editor error and no validation, and a line the tool wrote
+ * is not one its user thinks to audit.
+ */
+function schemaDirective(projectRoot) {
+    return existsSync(join(projectRoot, SCHEMA_REL))
+        ? `# yaml-language-server: $schema=${SCHEMA_REL}\n`
+        : '';
+}
 export function scaffoldProject(projectRoot) {
     const report = { created: [], skipped: [] };
     const found = CONFIG_FILENAMES.filter((name) => existsSync(join(projectRoot, name)));
@@ -96,7 +110,7 @@ export function scaffoldProject(projectRoot) {
         report.skipped.push(found[0]);
     }
     else {
-        writeFileSync(join(projectRoot, CONFIG_FILENAMES[0]), GENERATED_CONFIG);
+        writeFileSync(join(projectRoot, CONFIG_FILENAMES[0]), schemaDirective(projectRoot) + GENERATED_CONFIG);
         report.created.push(CONFIG_FILENAMES[0]);
     }
     // The entry is judged as a whole line. A substring test would treat a commented-out line