polydeukes 0.3.0 → 0.5.0

package/dist/scaffold-project.js

@@ -1,34 +1,36 @@
 /**
- * `scaffoldProject` — the project-side scaffold layer (DIST-02 §3-i).
+ * `scaffoldProject` — the project-side scaffold layer.
  *
  * The half of an installation every distribution path shares: the data config the judges
  * read, and the telemetry ignore line. What differs between paths is REGISTRATION — how the
  * agent is told to spawn a judge at all — and that lives one layer up (`initClaudeCode` for
- * the `init` path, a manifest for the plugin one). The split is what lets a second path
- * reuse this function unchanged instead of scaffolding a config a second time, so nothing
- * that registers anything belongs here.
+ * the `init` path). The split is what lets a second path reuse this function unchanged
+ * instead of scaffolding a config a second time, so nothing that registers anything belongs
+ * here.
  *
- * Nothing existing is ever overwritten (§5-d invariant 1): an artifact that is already there
- * is reported and left alone. The config existence check reads all three discovery
- * candidates rather than the canonical name alone — writing `polydeukes.config.yaml` next to
- * a project's `.yml` makes {@link loadConfig} throw on ambiguity, and the fail-closed session
- * surface then blocks every call, so the installer itself would be what stopped the project.
- * Existence is FILE PRESENCE, never parse success: reading a broken config as "absent" would
- * destroy the very file the consumer was midway through fixing, and fixing it is their job.
+ * Nothing existing is ever overwritten: an artifact that is already there is reported and
+ * left alone. The config existence check reads all three discovery candidates rather than
+ * the canonical name alone — writing `polydeukes.config.yaml` next to a project's `.yml`
+ * makes {@link loadConfig} throw on ambiguity, and the fail-closed session surface then
+ * blocks every call, so the installer itself would be what stopped the project. Existence is
+ * FILE PRESENCE, never parse success: reading a broken config as "absent" would destroy the
+ * very file the consumer was midway through fixing, and fixing it is their job.
  */
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CONFIG_FILENAMES } from './load-config.js';
-/** `.gitignore` name and the telemetry directory entry it must carry (§3-a). */
+/** `.gitignore` name and the telemetry directory entry it must carry. */
 const GITIGNORE = '.gitignore';
 const TELEMETRY_IGNORE_LINE = '.polydeukes/';
 const GITIGNORE_ENTRY = `# Polydeukes telemetry — local observation data, never committed.\n${TELEMETRY_IGNORE_LINE}\n`;
 /**
- * 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.
+ * The generated config: the minimum protection set and the 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.
+ *
+ * {@link schemaDirective} prepends the `yaml-language-server` line when the schema is where
+ * that line would name it.
  */
 const GENERATED_CONFIG = `# Polydeukes protection policy — generated by \`pdks init claude-code\`.
 #
@@ -53,15 +55,12 @@ 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.
+#
+# This list is what blocks. Every \`disciplines:\` entry below lands at advise — a break is
+# recorded and the call goes on — unless the entry itself says \`enforce: block\`.
 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
@@ -75,15 +74,55 @@ protectedPaths:
 witness:
   token: 'pdks witness'
   ttlMinutes: 10
+
+# The disciplines you judge by, and the three rungs one climbs — shown as three entries so
+# each rung is a line you can copy. Uncomment to start; ids must stay distinct.
+#
+# disciplines:
+#   # A draft: prose only, no predicate. Registered and read, never judged.
+#   - id: 'no-todo-in-shipped-code-draft'
+#     why: 'a TODO nobody owns is a decision deferred out of sight'
+#     draft: true
+#
+#   # Promoted to a judgment. Advise is the default — recorded as \`advised\`, never stops
+#   # the call — so this line is optional; it is written here to show the rung.
+#   - id: 'no-todo-in-shipped-code'
+#     why: 'a TODO nobody owns is a decision deferred out of sight'
+#     forbid: 'TODO'
+#     enforce: advise
+#
+#   # The promotion — block is your choice, never the default.
+#   - id: 'no-todo-in-shipped-code-blocking'
+#     why: 'a TODO nobody owns is a decision deferred out of sight'
+#     forbid: 'TODO'
+#     enforce: block
 `;
+/** 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`
+        : '';
+}
 /**
- * Create the project-side artifacts of a Polydeukes installation in `projectRoot` (§3-i),
- * skipping whatever is already there.
+ * Create the project-side artifacts of a Polydeukes installation in `projectRoot`, 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.
+ * Throws when two or more config spellings coexist — 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 function scaffoldProject(projectRoot) {
     const report = { created: [], skipped: [] };
@@ -96,7 +135,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

package/dist/schema/polydeukes.schema.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Polydeukes config",
+  "description": "Schema v2 (config as data) — equivalent to the runtime defineConfig() validator; the equivalence is enforced by a contract test.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["languages"],
+  "properties": {
+    "$schema": {
+      "description": "IDE schema reference — accepted and ignored by the runtime validator.",
+      "type": "string"
+    },
+    "languages": {
+      "description": "Language axis, first-class. Keys are user values ('typescript', 'python', ...).",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/languageProfile" }
+    },
+    "protectedPaths": {
+      "description": "Raw protected path patterns — normalization happens at resolve time.",
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "adapters": {
+      "description": "Adapter namespaces — keys are adapter names, values are each adapter's own settings object (contents not validated by the core schema).",
+      "type": "object",
+      "additionalProperties": { "type": "object" }
+    },
+    "telemetry": { "$ref": "#/$defs/telemetry" },
+    "disciplines": {
+      "description": "User-declared disciplines — validated data the covenant package compiles. Fully identical entries are copy-paste duplicates (by-id uniqueness is enforced by the runtime validator).",
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/discipline" }
+    },
+    "witness": { "$ref": "#/$defs/witness" }
+  },
+  "$defs": {
+    "languageProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["productionGlob", "testCmd"],
+      "properties": {
+        "productionGlob": {
+          "description": "What counts as production source for this language.",
+          "anyOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            }
+          ]
+        },
+        "testCmd": {
+          "description": "Shell command template that verifies the given scope — every literal {scope} token is substituted at resolve time.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "telemetry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "logPath": {
+          "description": "Telemetry log path. Defaults to .polydeukes/roi.log when omitted. Must be non-empty after trimming.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    },
+    "witness": {
+      "description": "TTL witness settings — the agreed token and validity window (minutes) consumed by the covenant valve assembly (CONFIG-05).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["token", "ttlMinutes"],
+      "properties": {
+        "token": {
+          "description": "The agreed phrase a human types alone on a message's first line — quoting it mid-sentence is a mention, not an invocation (COVENANT-15). Must be non-empty after trimming; the value itself is free.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "ttlMinutes": {
+          "description": "Validity window in minutes from the user message's timestamp. Must be a finite number > 0.",
+          "type": "number",
+          "exclusiveMinimum": 0
+        }
+      }
+    },
+    "disciplineId": {
+      "description": "Unique handle — telemetry label and verdict reason prefix. The three meta-covenant labels are reserved.",
+      "type": "string",
+      "minLength": 1,
+      "not": { "enum": ["self-mod", "shell-mod", "transcript-mod"] }
+    },
+    "disciplineWhy": {
+      "description": "Prose rationale — never judged, and carried into the break message.",
+      "type": "string"
+    },
+    "enforceLevel": {
+      "description": "The entry's own level. 'advise' records a break without stopping it; 'block' pins the entry at block. Composes with the surface's level, the lenient side winning; absent means advise; 'block' is the promotion rung.",
+      "enum": ["block", "advise"]
+    },
+    "globOrGlobs": {
+      "anyOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      ]
+    },
+    "requirePrecedent": {
+      "description": "Context family — the session evidence one edit requires beforehand. Exactly one evidence key. The core owns and fully validates 'command'; every other key is adapter vocabulary whose value passes through verbatim (unconstrained here, judged by that adapter).",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "properties": {
+        "command": {
+          "description": "Core evidence vocabulary — regex over the shell command strings observed in the session.",
+          "type": "string",
+          "minLength": 1,
+          "format": "regex"
+        }
+      }
+    },
+    "discipline": {
+      "description": "One discipline entry — exactly one predicate family (forbid | immutable | forbidCommand | requirePrecedent), or a draft (id + why + draft: true, no predicate); in/except scope the forbid and requirePrecedent families, and when scopes requirePrecedent only.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "why", "draft"],
+          "properties": {
+            "id": { "$ref": "#/$defs/disciplineId" },
+            "why": {
+              "description": "A draft's only body is its prose, so why is required and non-empty here.",
+              "type": "string",
+              "minLength": 1
+            },
+            "draft": {
+              "description": "Marks an unpromoted entry — declared as prose, never judged, never recorded. Only the literal true exists; false would be dead data synonymous with absence.",
+              "const": true
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "forbid"],
+          "properties": {
+            "id": { "$ref": "#/$defs/disciplineId" },
+            "why": { "$ref": "#/$defs/disciplineWhy" },
+            "enforce": { "$ref": "#/$defs/enforceLevel" },
+            "in": { "$ref": "#/$defs/globOrGlobs" },
+            "except": { "$ref": "#/$defs/globOrGlobs" },
+            "forbid": {
+              "description": "Delta family — string shorthand is equivalent to { added }.",
+              "anyOf": [
+                { "type": "string", "minLength": 1, "format": "regex" },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["added"],
+                  "properties": {
+                    "added": { "type": "string", "minLength": 1, "format": "regex" }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "immutable"],
+          "properties": {
+            "id": { "$ref": "#/$defs/disciplineId" },
+            "why": { "$ref": "#/$defs/disciplineWhy" },
+            "enforce": { "$ref": "#/$defs/enforceLevel" },
+            "immutable": {
+              "description": "Path family — its own glob is the scope.",
+              "$ref": "#/$defs/globOrGlobs"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "forbidCommand"],
+          "properties": {
+            "id": { "$ref": "#/$defs/disciplineId" },
+            "why": { "$ref": "#/$defs/disciplineWhy" },
+            "enforce": { "$ref": "#/$defs/enforceLevel" },
+            "forbidCommand": {
+              "description": "Command family — regex over shell command strings.",
+              "type": "string",
+              "minLength": 1,
+              "format": "regex"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "requirePrecedent"],
+          "properties": {
+            "id": { "$ref": "#/$defs/disciplineId" },
+            "why": { "$ref": "#/$defs/disciplineWhy" },
+            "enforce": { "$ref": "#/$defs/enforceLevel" },
+            "in": { "$ref": "#/$defs/globOrGlobs" },
+            "except": { "$ref": "#/$defs/globOrGlobs" },
+            "when": {
+              "description": "Context-family trigger — added-direction delta regex. Absent means every in-scope change triggers.",
+              "type": "string",
+              "minLength": 1,
+              "format": "regex"
+            },
+            "requirePrecedent": { "$ref": "#/$defs/requirePrecedent" }
+          }
+        }
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polydeukes",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A development discipline framework for building alongside an AI coding partner — deterministic covenants, a verifiable work ledger, local memory, and adversarial verification. Alpha.",
   "keywords": [
     "harness",
@@ -39,7 +39,8 @@
     "./claude-code": {
       "types": "./dist/claude-code-hook.d.ts",
       "import": "./dist/claude-code-hook.js"
-    }
+    },
+    "./schema.json": "./dist/schema/polydeukes.schema.json"
   },
   "files": [
     "dist",
@@ -53,10 +54,10 @@
   },
   "dependencies": {
     "yaml": "2.9.0",
-    "@polydeukes/adapter-claude-code": "^0.3.0",
-    "@polydeukes/covenant": "^0.3.0",
-    "@polydeukes/core": "^0.3.0",
-    "@polydeukes/adapter-git": "^0.3.0"
+    "@polydeukes/adapter-claude-code": "^0.5.0",
+    "@polydeukes/adapter-git": "^0.5.0",
+    "@polydeukes/covenant": "^0.5.0",
+    "@polydeukes/core": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -64,7 +65,7 @@
     "vitest": "^4.1.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node scripts/copy-docs.mjs",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-docs.mjs && node scripts/copy-schema.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   }