@dtmd/temper 0.0.3 → 0.0.6

package/README.md

@@ -1,8 +1,8 @@
 # temper-sdk — the authoring face
 
 The typed module library the ratified corpus names as temper's authoring
-medium (`specs/intent/00-intent.md`, the SDK Decision; `specs/architecture/20-surface.md`,
-"The seam — one implementation"). A harness author composes members as typed
+medium (`specs/intent.md`; `specs/model/pipeline.md`, "The SDK"). A harness
+author composes members as typed
 values in the **six-noun model**; `emit` compiles the whole into the declaration
 rows the engine reads, a byte-faithful `.claude/**` projection, and the lock. The
 SDK implements **no semantics** — every type erases at the seam, and the engine
@@ -11,14 +11,15 @@ consumes only declared data, offline, no Node.
 ## The six-noun face
 
 - **`harness()`** — the assembly as one typed value: `members · expect ·
-  require · settings · reachability` (`specs/architecture/40-composition.md`).
-- **`kind<T>()` / `genre<T>()`** — the engine room: a kind is a typed
+  require · settings` (`specs/model/pipeline.md`, "The SDK").
+- **`kind<T>()`** — the engine room: a kind is a typed
   constructor plus five facts of runtime residue (label, locus, layout,
-  registration, edge fields — `specs/architecture/15-kinds.md`). The built-in
-  Claude Code kinds `rule` / `skill` / `memory` are ordinary `kind<T>()` values.
+  registration, edge fields — `specs/model/representation.md`). The built-in
+  Claude Code kinds `rule` / `skill` / `memory` are ordinary `kind<T>()` values;
+  an embedded child kind is the same constructor at the `embedded` locus.
 - **Clause values** — `clause(predicate, { severity, guidance, cite })` over the
   closed predicate algebra (`required`, `maxLines`, …); a floor is an exported
-  clause array, adopted by spread in `expect` (`specs/architecture/10-contracts.md`).
+  clause array, adopted by spread in `expect` (`specs/model/contract.md`).
 - **`needs`** — the capabilities a member uses (`bash("git diff")`); emit derives
   the permission union, so a permission is never authored twice.
 - **`file()` / `` text`…` `` / `blocks()`** — the three prose constructors, one
@@ -26,7 +27,8 @@ consumes only declared data, offline, no Node.
 
 ## What `emit` produces
 
-One deterministic pass over the harness, double-emit verified (law 5):
+One deterministic pass over the harness, double-emit verified
+(`specs/model/pipeline.md`, "Emit"):
 
 - **Declaration rows** — the erased program (kind facts, clauses, requirements,
   assembly facts) on the internal versioned JSON pipe and in the lock's
@@ -43,12 +45,8 @@ projection on disk; the JSON pipe is in-flight, not a committed artifact.
 
 ## Stated bounds — each a named follow-on, never silently faked
 
-- **`blocks()` composes now, renders later** — the shared genre fence format is
-  `(genre-fence-format)`, deferred until its first consumer; emit refuses to
-  project a `blocks()` body until then.
 - **The permission union is carried as data** — the fold into the settings
   artifact lands with the hook/MCP kinds it folds many-to-one.
-- **Publish name/scope** pending the PACKAGING-CHANNELS ruling; `private: true`.
 
 ## Tests
 

package/dist/src/assembly.d.ts

@@ -1,26 +1,34 @@
 /**
- * The assembly — `harness()` takes the whole as one typed value
- * (`specs/architecture/40-composition.md`): `Harness = members · expect · require ·
- * settings · reachability`. Like every SDK type it erases at the seam — the
- * engine never sees the constructor, only the declaration rows it compiles to
- * (`20-surface.md`). There is no second authoring surface: no `temper.toml`, no
- * roster/bindings dialect (the Decision rejects both); composing partial
- * harnesses is ordinary code.
+ * The assembly — `harness()` takes the whole as one typed value: `Harness =
+ * members · expect · require · settings · mode`. Like every SDK type it
+ * erases at the seam — the engine never sees the constructor, only the
+ * declaration rows it compiles to. There is no second authoring surface: no
+ * `temper.toml`, no roster/bindings dialect (the Decision rejects both);
+ * composing partial harnesses is ordinary code.
  */
 import type { Member, KindDefinition } from "./kind.js";
-import type { Clause, Requirement, Severity } from "./contract.js";
+import type { Clause, Requirement } from "./contract.js";
 /**
- * One `expect` binding — universal: every member of `kind` owes these clauses
- * (`40-composition.md`). Keyed by the kind **value**, an import never a string;
- * binding is implicit — a floor is just a clause array spread into `clauses`.
+ * One `expect` binding — universal: every member of `kind` owes these clauses.
+ * Keyed by the kind **value**, an import never a string; binding is implicit
+ * — a floor is just a clause array spread into `clauses`.
  */
 export interface ExpectBinding {
-    readonly kind: KindDefinition<object>;
+    readonly kind: KindDefinition<never>;
     readonly clauses: readonly Clause[];
 }
-/** The composed harness — the five fields, erased to rows at the seam. */
+/**
+ * The declared enforcement-mode vocabulary — how firmly the `PreToolUse` guard
+ * binds a tool call, split by where the finding goes.
+ * `block`: denies the call.
+ * `warn` (default): allows the call and surfaces the finding in-band, into the
+ * live context. `note`: allows the call and records the finding out-of-band
+ * only — the next report, never the session.
+ */
+export type EnforcementMode = "note" | "warn" | "block";
+/** The composed harness — the root member's own fields, erased to rows at the seam. */
 export interface Harness {
-    /** The member roster — the assembly's imports (`40-composition.md`, "`members`"). */
+    /** The member roster — the assembly's imports. */
     readonly members: readonly Member[];
     /** Universal clause bindings, keyed by kind value. */
     readonly expect: readonly ExpectBinding[];
@@ -28,18 +36,23 @@ export interface Harness {
     readonly require: Readonly<Record<string, Requirement>>;
     /** The residual harness-level settings with no member home (a shrinking list). */
     readonly settings: Readonly<Record<string, unknown>>;
-    /** The dead-registration dial — the severity of an unreachable member, or absent (no findings). */
-    readonly reachability?: Severity;
+    /**
+      * The root member's declared enforcement mode — harness-wide, overridable
+    * per member. Defaults to `warn`: temper fabricates no enforcement the
+      * author did not declare.
+    */
+    readonly mode: EnforcementMode;
 }
 /**
  * Compose the harness from its five fields — ordinary code, Turing-completeness
- * quarantined at authoring time (`00-intent.md`, the SDK Decision). Absent
- * fields default empty; the member list is the only required part.
+ * quarantined at authoring time. Absent
+ * fields default empty (`mode` defaults `warn`); the member list is the
+ * only required part.
  */
 export declare function harness(init: {
     members: readonly Member[];
     expect?: readonly ExpectBinding[];
     require?: Readonly<Record<string, Requirement>>;
     settings?: Readonly<Record<string, unknown>>;
-    reachability?: Severity;
+    mode?: EnforcementMode;
 }): Harness;

package/dist/src/assembly.js

@@ -1,16 +1,16 @@
 /**
- * The assembly — `harness()` takes the whole as one typed value
- * (`specs/architecture/40-composition.md`): `Harness = members · expect · require ·
- * settings · reachability`. Like every SDK type it erases at the seam — the
- * engine never sees the constructor, only the declaration rows it compiles to
- * (`20-surface.md`). There is no second authoring surface: no `temper.toml`, no
- * roster/bindings dialect (the Decision rejects both); composing partial
- * harnesses is ordinary code.
+ * The assembly — `harness()` takes the whole as one typed value: `Harness =
+ * members · expect · require · settings · mode`. Like every SDK type it
+ * erases at the seam — the engine never sees the constructor, only the
+ * declaration rows it compiles to. There is no second authoring surface: no
+ * `temper.toml`, no roster/bindings dialect (the Decision rejects both);
+ * composing partial harnesses is ordinary code.
  */
 /**
  * Compose the harness from its five fields — ordinary code, Turing-completeness
- * quarantined at authoring time (`00-intent.md`, the SDK Decision). Absent
- * fields default empty; the member list is the only required part.
+ * quarantined at authoring time. Absent
+ * fields default empty (`mode` defaults `warn`); the member list is the
+ * only required part.
  */
 export function harness(init) {
     return {
@@ -18,6 +18,6 @@ export function harness(init) {
         expect: init.expect ?? [],
         require: init.require ?? {},
         settings: init.settings ?? {},
-        reachability: init.reachability,
+        mode: init.mode ?? "warn",
     };
 }

package/dist/src/builtins.d.ts

@@ -1,40 +1,81 @@
 /**
- * The built-in Claude Code kinds — the face nouns a harness author imports
- * (`specs/architecture/15-kinds.md`, "Built-in and custom kinds"). Each is an
+ * The built-in Claude Code kinds — the face nouns a harness author imports.
+ * Each is an
  * ordinary `kind<T>()` value built with the same constructor every provider uses
  * (ownership not privilege). Their five facts are external facts about the Claude
  * Code harness, cited at the point of claim.
  *
  * These are the SDK's own provider-face exports, surfaced through the
- * `@dtmd/temper/claude-code` subpath (`50-distribution.md`, "Decision: one SDK
- * package — the provider face is a subpath export") — never from the root.
+ * `@dtmd/temper/claude-code` subpath
+ * — never from the root.
  */
 import type { KindDefinition } from "./kind.js";
 import type { Prose } from "./prose.js";
+import type { Clause } from "./contract.js";
 /** A Claude Code skill — a directory whose entry file is `SKILL.md` with YAML frontmatter. */
 export interface Skill {
     /**
-     * The description trigger — always in context; the body loads on invocation
-     * (code.claude.com/docs/en/skills, retrieved 2026-07-02).
-     */
+      * The description trigger — always in context; the body loads on invocation
+      * (code.claude.com/docs/en/skills, retrieved 2026-07-02).
+    */
     readonly description: string;
     /** The optional license field the skill spec carries (agentskills.io/specification). */
     readonly license?: string;
+    /**
+     * Set `true` to prevent Claude from automatically loading this skill — only
+     * the user-invoked channel stays live (code.claude.com/docs/en/skills,
+     * "Control who invokes a skill", retrieved 2026-07-07). Default: `false`.
+     */
+    readonly "disable-model-invocation"?: boolean;
+    /**
+     * Set `false` to hide the skill from the `/` menu — only the
+     * description-trigger channel stays live (code.claude.com/docs/en/skills,
+     * "Control who invokes a skill", retrieved 2026-07-07). Default: `true`.
+     */
+    readonly "user-invocable"?: boolean;
     readonly prose?: Prose;
 }
 /**
  * `skill` — `.claude/skills/<name>/SKILL.md`, a directory unit, YAML frontmatter
- * carrying `name` then `description`; registers a description trigger
+ * carrying `name` then `description`; registers on both documented invocation
+ * channels — user-invoked (`/name`) and description-trigger — modulated per
+ * member by the `disable-model-invocation`/`user-invocable` fields
  * (code.claude.com/docs/en/skills, agentskills.io/specification, retrieved
- * 2026-07-02).
+ * 2026-07-07).
  */
 export declare const skill: KindDefinition<Skill>;
+/**
+ * `command` — `.claude/commands/*.md`, the skill surface's legacy file placement
+ * (Claude Code merged commands into skills; code.claude.com/docs/en/skills,
+ * retrieved 2026-07-07): a lone file (identity from the stem, so no
+ * `identityField` — like `rule`), the skill's field schema by import, registering
+ * on the same two documented invocation channels as `skill`.
+ */
+export declare const command: KindDefinition<Skill>;
+/** A Claude Code subagent definition. */
+export interface Agent {
+    /**
+      * When Claude should delegate to this subagent — the sole registration
+      * channel (code.claude.com/docs/en/sub-agents, retrieved 2026-07-07).
+    */
+    readonly description: string;
+    readonly prose?: Prose;
+}
+/**
+ * `agent` — every markdown file under `.claude/agents`, discovered recursively (a
+ * containing subdirectory is purely organizational), YAML frontmatter carrying
+ * `name` then `description`; identity is the `name` field (never the filename),
+ * the named-field mode; registers on the description-trigger channel only — no
+ * user-invoked slash command (code.claude.com/docs/en/sub-agents, retrieved
+ * 2026-07-07).
+ */
+export declare const agent: KindDefinition<Agent>;
 /** A Claude Code rule — a flat markdown file with an optional `paths` scope. */
 export interface Rule {
     /**
-     * The path scope — a present list matching zero files is a dead edge; an absent
-     * one loads unconditionally (code.claude.com/docs/en/memory, retrieved 2026-07-02).
-     */
+      * The path scope — a present list matching zero files is a dead edge; an absent
+      * one loads unconditionally (code.claude.com/docs/en/memory, retrieved 2026-07-02).
+    */
     readonly paths?: readonly string[];
     readonly prose?: Prose;
 }
@@ -56,3 +97,131 @@ export interface Memory {
  * a module-carried memory projects the root file.
  */
 export declare const memory: KindDefinition<Memory>;
+/**
+ * The default contract for `skill` — Anthropic's documented skill contract: the Agent
+ * Skills open standard (agentskills.io), Anthropic's platform upload
+ * validation, and Claude Code's own docs.
+ * All sources retrieved 2026-07-09.
+ *
+ * Checks the strictest documented profile: the spec and upload validation are
+ * hard, Claude Code's runtime is deliberately forgiving ("All fields are
+ * optional") — a skill that passes here loads everywhere the format is
+ * honored, not merely on the machine it was written on; where the runtime
+ * diverges, the clause's own guidance says so.
+ *
+ * Deliberately absent — undecidable, so never gate clauses: whether the
+ * description actually triggers well or reads third-person (semantic);
+ * vagueness/no-op detection (semantic); gerund naming (judgment). Two
+ * decidable spec rules are also absent, pending a vocabulary addition (a
+ * narrow shape predicate governs additions): the name
+ * must not start/end with a hyphen or contain consecutive hyphens; likewise
+ * the platform's "no XML tags in the description."
+ *
+ * Authoring notes the clauses cannot carry: prefer gerund or noun-phrase
+ * names (`processing-pdfs`, `pdf-processing`) over vague ones (`helper`,
+ * `utils`); `disable-model-invocation: true` for side-effectful workflows you
+ * want to time yourself; `user-invocable: false` for background knowledge
+ * that is not a command; `metadata` is the sanctioned home for versioning —
+ * there is no top-level `version` field.
+ */
+export declare const skillDefaultContract: readonly Clause[];
+/**
+ * The default contract for `command` — `skillDefaultContract`'s clauses minus `nameMatchesDir`: a
+ * command is a lone file with no parent directory to match, so the one clause
+ * that ranges over the directory relationship does not apply; every other
+ * documented skill-schema recommendation, name-requiredness included, still
+ * governs a command by the same import (code.claude.com/docs/en/skills,
+ * retrieved 2026-07-07).
+ */
+export declare const commandDefaultContract: readonly Clause[];
+/**
+ * The default contract for `agent` — Anthropic's documented subagent contract
+ * (code.claude.com/docs/en/sub-agents, retrieved 2026-07-07): `name` and
+ * `description` are the only required fields, `name` is a "unique identifier
+ * using lowercase letters and hyphens" (no digits, unlike a skill's `name`), and
+ * "keep `name` values unique across the whole tree" — a same-scope collision
+ * loads only one definition.
+ *
+ * Deliberately narrow, like `ruleDefaultContract`: undecidable properties (whether the
+ * description triggers well, model/permissionMode's semi-open vocabularies) stay
+ * out of the gate — the format documents little else that is decidable.
+ */
+export declare const agentDefaultContract: readonly Clause[];
+/**
+ * The default contract for `rule` — Anthropic's documented contract for a Claude Code
+ * rules file, sourced from the memory docs (`.claude/rules/` landed in
+ * v2.0.64; `packages/rule.anthropic/PACKAGE.md`, the curated authoring
+ * reference this migrates verbatim). All sources retrieved 2026-07-09.
+ *
+ * `paths` is the one documented frontmatter key for rules: glob patterns
+ * (brace expansion supported) that scope the rule to matching files. Rules
+ * without it load at launch with the same priority as CLAUDE.md; path-scoped
+ * rules load when Claude reads a matching file. Note skills now take a
+ * `paths` key too — the two schemas are separate. (Guidance only: an
+ * optional field asserts nothing decidable, so it carries no clause of its
+ * own: `required` is the one
+ * presence predicate, and its absence is not itself a predicate.)
+ * https://code.claude.com/docs/en/memory#path-specific-rules (retrieved 2026-07-09)
+ *
+ * What the clauses cannot carry, as guidance: keep a rule to facts Claude
+ * should hold whenever the rule is in scope — concrete enough to verify ("use
+ * 2-space indentation", not "format code properly"). If an entry is a
+ * multi-step procedure or only matters occasionally, it belongs in a skill
+ * (on-demand) rather than a rule (always-on). Prefer path-scoped rules when
+ * one convention governs scattered paths; prefer per-directory CLAUDE.md when
+ * directory owners maintain their own. Treat rules like code: prune them when
+ * behavior drifts, and test a change by watching whether Claude's behavior
+ * actually shifts.
+ */
+export declare const ruleDefaultContract: readonly Clause[];
+/**
+ * The default contract for the qualified `claude-code.memory` kind — Anthropic's
+ * documented contract for a project `CLAUDE.md` (`packages/memory.anthropic/PACKAGE.md`,
+ * the curated authoring reference this migrates verbatim). Retrieved 2026-07-09.
+ *
+ * Deliberately near-empty, because the format is: `CLAUDE.md` is plain
+ * markdown with no documented frontmatter and no required fields
+ * (code.claude.com/docs/en/memory, retrieved 2026-07-09), so there is no
+ * schema to gate — manufacturing a required field or a forbidden-key list
+ * would fake a check the format does not carry. The single clause is a context-cost
+ * budget; everything else the contract could say is guidance.
+ *
+ * What the clauses cannot carry, as guidance: a `paths:` frontmatter block
+ * belongs on a `.claude/rules/*.md` file, not on `CLAUDE.md` — the memory
+ * docs document `paths` only for rules, so a rules-style header on
+ * `CLAUDE.md` is dead configuration. Split a large file with `@path` imports
+ * (resolved relative to the importing file, absolute allowed, recursion
+ * capped at four hops; wrap a path in backticks to mention it without
+ * importing). If the repo already ships an `AGENTS.md` for other agents,
+ * don't duplicate it — create a `CLAUDE.md` that `@AGENTS.md`-imports it (or
+ * symlink, except on Windows where the import is the recommended bridge).
+ * Mind the loading asymmetry: every ancestor `CLAUDE.md` loads in full at
+ * launch, while files in subdirectories load only when Claude reads a file
+ * there — so a rule that must always hold belongs above the working
+ * directory, not below it. Personal, un-shared notes go in `CLAUDE.local.md`
+ * (gitignored), appended after `CLAUDE.md` at its level.
+ */
+export declare const memoryAnthropicDefaultContract: readonly Clause[];
+/**
+ * The default contract for the qualified `agents-md.memory` kind — the AGENTS.md
+ * standard's contract for a memory file, which is that there is almost none
+ * (`packages/memory.agents-md/PACKAGE.md`, the curated authoring reference
+ * this migrates). Guidance-only, and that is the honest encoding: `AGENTS.md`
+ * "is just standard Markdown" with no required fields, no sections, and no
+ * frontmatter (agents.md, retrieved 2026-07-09); the format deliberately
+ * constrains nothing. A default contract that manufactured a required field, a size
+ * gate, or a forbidden-key list would assert a contract the standard
+ * disclaims. Even the tempting size
+ * number is a *tool's* rule, not the format's: agents read the closest
+ * `AGENTS.md` in the tree (nested, nearest-wins; agents.md, retrieved
+ * 2026-07-09); Codex concatenates the chain root-to-cwd and stops once
+ * combined size hits a byte budget, not a per-file line count
+ * (`project_doc_max_bytes`, 32 KiB default;
+ * developers.openai.com/codex/guides/agents-md, retrieved 2026-07-09);
+ * Gemini CLI reads `GEMINI.md` by default and only treats `AGENTS.md` as an
+ * alias when configured via `context.fileName` (geminicli.com/docs/cli/gemini-md,
+ * retrieved 2026-07-09); Claude Code does not read `AGENTS.md` natively —
+ * bridge it with a `CLAUDE.md` that `@AGENTS.md`-imports it
+ * (code.claude.com/docs/en/memory, retrieved 2026-07-09).
+ */
+export declare const memoryAgentsMdDefaultContract: readonly Clause[];