@crewhaus/spec 0.2.3 → 0.3.0

package/dist/index.js

@@ -512,6 +512,62 @@ const feedbackBlock = z
 })
     .strict()
     .optional();
+/**
+ * v0.3.0 §3.1/§9 — the `memory.wiki` sub-block: the update-in-place semantic
+ * tier over `@crewhaus/wiki-store` (`.crewhaus/wiki/<spec>/`). Presence (with
+ * `enabled` not `false`) registers the ten thredz-vocabulary `wiki_*` tools.
+ * `recallK` caps wiki hits fused into auto-recall (OPTIMIZABLE, PR 20);
+ * `embedder` is the `@crewhaus/embedder` factory grammar enabling hybrid
+ * recall on BOTH the wiki and the fact store; `autoRecall` fuses wiki recall
+ * into the session-start memory bundle; `requireSources` is the learning-mode
+ * write governance (`wiki_write` rejects bodies without a `## Sources`
+ * heading — the `learning:` lowering sets it in PR 17).
+ * `.strict()` so a typo'd sub-key fails the build.
+ */
+const memoryWikiBlock = z
+    .object({
+    enabled: z.boolean().optional(),
+    recallK: z.number().int().positive().max(50).optional(),
+    embedder: z.string().min(1).optional(),
+    autoRecall: z.boolean().optional(),
+    requireSources: z.boolean().optional(),
+})
+    .strict();
+/**
+ * The shared duration-string grammar (Phase 3 §3.1 heartbeat, v0.3.0
+ * `memory.ttl` and `memory.dream.every`). Extended with `d` (days) in
+ * 0.3.0. Parsed to milliseconds at lower time by the compiler's
+ * `parseDurationToMs`.
+ */
+const DURATION_REGEX = /^\d+(?:ms|s|m|h|d)$/;
+/**
+ * v0.3.0 Goal 5 (§6/§9) — the `memory.dream` sub-block: scheduled memory
+ * consolidation. Nested under `memory:` because it consolidates the memory
+ * fabric (facts + wiki + continuity's spec-scoped agenda) — one shared zod
+ * object, minimal union churn.
+ *
+ *   - `every` (required): the consolidation cadence in the shared duration
+ *     grammar (`"24h"`, `"1d"`). Must be >= 5m (enforced at lower time) —
+ *     consolidation is a maintenance pass, not a per-turn hook.
+ *   - `mode`: `full` (default — deterministic phase + ONE bounded model
+ *     synthesis session) | `deterministic` (no model, ever).
+ *   - `budget_usd`: the model phase's item-27 spend cap (OPTIMIZABLE,
+ *     PR 20). `0` — or omitting it — means deterministic only, regardless
+ *     of `mode`; unattended model spend must be opted into by number.
+ *   - `instructions`: optional playbook override; the default is the
+ *     builtin `dream` skill body.
+ * `.strict()` so a typo'd sub-key fails the build.
+ */
+const memoryDreamBlock = z
+    .object({
+    every: z
+        .string()
+        .regex(DURATION_REGEX, 'memory.dream.every must be a duration like "24h", "1d", "30m", or "300s"'),
+    mode: z.enum(["deterministic", "full"]).optional(),
+    budget_usd: z.number().nonnegative().optional(),
+    instructions: z.string().min(1).optional(),
+})
+    .strict();
 /**
  * Feature #53 — cross-session memory block. Its mere presence wires the
  * Remember/Recall tools into the harness (no hand-editing). The auto-*
@@ -519,16 +575,183 @@ const feedbackBlock = z
  * outcomes into `.crewhaus/memories/<name>.jsonl` at run teardown;
  * `autoRecall` injects the top-`recallK` relevant memories into the system
  * prompt at session start (mirrors project-memory auto-load). Carried on the
- * interactive shapes that run a chat loop (cli, channel, managed, research).
+ * agent-loop shapes (cli, channel, managed, research, crew).
+ *
+ * v0.3.0 (§9) extensions — all optional so pre-0.3.0 specs parse (and lower)
+ * unchanged:
+ *   - `backend`: `file` (the default when absent) | `thredz` (reserved — the
+ *     store flip ships with the `thredz:` block, PR 16). Deliberately NOT
+ *     zod-defaulted: only declared fields are carried into the IR, keeping
+ *     existing memory bundles byte-identical.
+ *   - `ttl`: explicit forgetting for auto-captured facts, as a duration
+ *     string in the heartbeat grammar extended with `d` (days) — e.g. "90d".
+ *     Must be >= 1h (enforced at lower time); omit to keep facts forever.
+ *   - `wiki`: the semantic tier (see {@link memoryWikiBlock}).
+ *   - `dream`: scheduled consolidation (see {@link memoryDreamBlock}, §6).
  * `.strict()` so a typo'd sub-key fails the build.
  */
 const memoryBlock = z
     .object({
     enabled: z.boolean().optional(),
+    backend: z.enum(["file", "thredz"]).optional(),
+    ttl: z
+        .string()
+        .regex(DURATION_REGEX, 'memory.ttl must be a duration like "90d", "12h", "30m", "60s", or "500ms"')
+        .optional(),
     autoCapture: z.boolean().optional(),
     autoCaptureThreshold: z.number().int().positive().optional(),
     autoRecall: z.boolean().optional(),
     recallK: z.number().int().positive().max(50).optional(),
+    wiki: memoryWikiBlock.optional(),
+    dream: memoryDreamBlock.optional(),
+})
+    .strict()
+    .optional();
+/**
+ * v0.3.0 Goal 1 (§2.1) — the top-level `continuity:` block: focus, plans,
+ * goals, the proof-of-action ladder, the requirements ledger, and teardown
+ * handoff. THE release's one sanctioned default-on behavior change
+ * (ROADMAP.md:9): on the emit-wired agent-loop shapes (cli, channel, managed,
+ * research, crew) an ABSENT key lowers to the default-on config —
+ * `continuity: false` is the opt-out that restores prior bundle bytes
+ * exactly (byte-diff-pinned).
+ *
+ * Forms: boolean shorthand (`continuity: true|false`) or the strict object:
+ *   - `enabled`: `false` disables (same as the `false` shorthand).
+ *   - `plan`: plan/goal persistence + the Plan and Goal tool families
+ *     (default true; `false` keeps only FocusRead/FocusWrite + MemoryClear).
+ *   - `proof`: `ladder` (default — claimed is free, proven is machine-checked)
+ *     | `require` (refuse plan completion below proven; `init` templates)
+ *     | `off` (no verification). See §2.4.
+ *   - `ledger`: the verbatim requirements ledger (§2.3; default true).
+ *   - `handoff`: deterministic teardown handoff.md (§2.8; default true).
+ *   - `scope`: `auto` (default) | `spec` | `session` — §2.7/§14.5: `auto`
+ *     resolves at lower time to `spec` on cli/research/crew/managed (managed
+ *     additionally tenant-fenced at boot) and `session` (per-conversation)
+ *     on channel; explicit `session` is only accepted on shapes with session
+ *     routing (channel).
+ *   - `focusMaxChars`: hard cap on the mutable tail block (default 4096;
+ *     OPTIMIZABLE, PR 20).
+ *
+ * Also carried (spec-parsed, compiled with an ignored-note comment) on
+ * workflow, batch, voice, browser; deliberately NOT on graph/pipeline/eval/
+ * onchain/onchain-game — the strict union rejects it loudly there, which
+ * beats silent dead config.
+ */
+const continuityObject = z
+    .object({
+    enabled: z.boolean().optional(),
+    plan: z.boolean().optional(),
+    proof: z.enum(["ladder", "require", "off"]).optional(),
+    ledger: z.boolean().optional(),
+    handoff: z.boolean().optional(),
+    scope: z.enum(["auto", "spec", "session"]).optional(),
+    focusMaxChars: z.number().int().positive().optional(),
+})
+    .strict();
+const continuityBlock = z.union([z.boolean(), continuityObject]).optional();
+/**
+ * v0.3.0 Goal 3 (§4.1) — the top-level `thredz:` block: ONE knob that flips
+ * the memory fabric's wiki backend to a hosted Thredz wiki over the published
+ * `thredz-mcp` stdio server (npm, v0.2.0 — 25 tools incl. `goal_*`/`task_*`).
+ *
+ * Forms:
+ *   - boolean shorthand: `thredz: true` ≡ `{ api_key: "$THREDZ_API_KEY" }`
+ *     (`false` ≡ absent — the explicit opt-out).
+ *   - string shorthand: `thredz: $THREDZ_API_KEY` — THE one argument.
+ *   - the strict object:
+ *       · `api_key` (required): credential-lowered to an `IrSecretRef`
+ *         (`lowerCredential` — fail-fast on a malformed `$…` env ref).
+ *       · `base_url`: self-hosted / local Thredz API base
+ *         (`THREDZ_API_BASE` in the synthesized server env).
+ *       · `visibility`: `private` (DEFAULT — overrides Thredz's
+ *         shared-by-default foot-gun) | `shared`; becomes the synthesized
+ *         server's `THREDZ_DEFAULT_VISIBILITY`.
+ *       · `goals`: mirror continuity goal writes to Thredz `goal_write`/
+ *         `goal_update` (spec-scoped ONLY, §14.5 decision 5). Default: on
+ *         when continuity goals are on.
+ *       · `agents`: register an addressable agent handle at boot
+ *         (idempotent `agent_register`). `true` derives the handle from the
+ *         spec name; a string names it explicitly. Default off.
+ *
+ * Carried on the five memory shapes (cli, channel, managed, research, crew);
+ * the strict unions reject it loudly elsewhere. Emit-wiring in this release
+ * is the cli shape (compiled bundle + `crewhaus run`); the other four carry
+ * the block with the 0.2.3-convention ignored-note comment.
+ */
+const THREDZ_HANDLE_RE = /^[a-z][a-z0-9-]{2,31}$/;
+const thredzObject = z
+    .object({
+    api_key: z.string().min(1),
+    base_url: z.string().url().optional(),
+    visibility: z.enum(["private", "shared"]).optional(),
+    goals: z.boolean().optional(),
+    agents: z
+        .union([
+        z.boolean(),
+        z
+            .string()
+            .regex(THREDZ_HANDLE_RE, "thredz.agents must be a lowercase handle matching ^[a-z][a-z0-9-]{2,31}$ (or true to derive one from the spec name)"),
+    ])
+        .optional(),
+})
+    .strict();
+const thredzBlock = z.union([z.boolean(), z.string().min(1), thredzObject]).optional();
+/**
+ * v0.3.0 Goal 2 (§3.3, PR 17) — the top-level `learning:` block: continual
+ * learning as a first-class capability. Presence (with `enabled` not `false`)
+ * registers the builtin `learning-loop` skill with `domain`/`curriculum`/
+ * `sources` substituted at compile time, gates in the `/study` `/reflect`
+ * (and, with `exam`, `/exam`) slash commands, and enforces Sources-required
+ * wiki writes deterministically.
+ *
+ * Learning NEEDS a wiki — the knowledge lives there, not in the prompt — so
+ * the compiler REQUIRES `memory.wiki` (local files) or `thredz:` (hosted)
+ * alongside this block (cross-field CompilerError otherwise).
+ *
+ *   - `domain` (required): one sentence naming the field of expertise —
+ *     substituted into the learning-loop skill body.
+ *   - `curriculum`: spec-relative path to an agent-editable checkbox-ladder
+ *     file (e.g. `curriculum.md`). Optional; without it the skill keeps the
+ *     ladder in the wiki. Whether the file EXISTS is a runtime concern.
+ *   - `sources`: source-allowlist hints (domains/patterns) woven into the
+ *     skill's STUDY gathering rules. Deliberately NOT optimizable — an
+ *     allowlist is a security surface (§7.5).
+ *   - `exam`: spec-relative `dataset` (jsonl) + `graders` (yaml) paths for
+ *     the first-class competency exam: `/exam` drives a programmatic
+ *     eval-runner invocation (the `run_exam` tool — no Bash shell-out), and
+ *     every failed sample is logged as a knowledge gap automatically.
+ *   - `study`: unattended-study toggles, both default ON —
+ *       · `on_heartbeat`: prepend the study-rotation preamble (gaps first,
+ *         ~3:1 study:reflect, bounded per tick) to channel heartbeat
+ *         instructions;
+ *       · `on_dream`: seed the dream model phase's findings with the top
+ *         open knowledge gaps + the next unmastered curriculum rung.
+ *
+ * Carried on the five memory shapes (cli, channel, managed, research, crew);
+ * the strict unions reject it loudly elsewhere. `.strict()` throughout so a
+ * typo'd sub-key fails the build.
+ */
+const learningBlock = z
+    .object({
+    enabled: z.boolean().optional(),
+    domain: z.string().min(1),
+    curriculum: z.string().min(1).optional(),
+    sources: z.array(z.string().min(1)).optional(),
+    exam: z
+        .object({
+        dataset: z.string().min(1),
+        graders: z.string().min(1),
+    })
+        .strict()
+        .optional(),
+    study: z
+        .object({
+        on_heartbeat: z.boolean().optional(),
+        on_dream: z.boolean().optional(),
+    })
+        .strict()
+        .optional(),
 })
     .strict()
     .optional();
@@ -699,12 +922,11 @@ const cliOptionsBlock = z
  * message at each tick; pair with HEARTBEAT.md in cwd for richer
  * playbook reads.
  */
-const HEARTBEAT_DURATION_REGEX = /^\d+(?:ms|s|m|h)$/;
 const heartbeatBlock = z
     .object({
     every: z
         .string()
-        .regex(HEARTBEAT_DURATION_REGEX, 'heartbeat.every must be a duration like "2h", "30m", "60s", or "500ms"'),
+        .regex(DURATION_REGEX, 'heartbeat.every must be a duration like "1d", "2h", "30m", "60s", or "500ms"'),
     instructions: z.string().min(1),
 })
     .strict()
@@ -757,6 +979,9 @@ const cliSchema = z
     budget: budgetBlock,
     feedback: feedbackBlock,
     memory: memoryBlock,
+    continuity: continuityBlock,
+    thredz: thredzBlock,
+    learning: learningBlock,
     observability: observabilityBlock,
     cli: cliOptionsBlock,
     chains: chainsBlock,
@@ -785,6 +1010,9 @@ const workflowSchema = z
     permissions: permissionsBlock,
     compaction: compactionBlock,
     failure_taxonomy: failureTaxonomyBlock,
+    // v0.3.0 — carried but not emit-wired in 0.3.0 (ignored-note comment in
+    // the generated bundle; NOT default-on here).
+    continuity: continuityBlock,
     chains: chainsBlock,
     wallets: walletsBlock,
     contracts: contractsBlock,
@@ -888,6 +1116,9 @@ const channelSchema = z
     budget: budgetBlock,
     feedback: feedbackBlock,
     memory: memoryBlock,
+    continuity: continuityBlock,
+    thredz: thredzBlock,
+    learning: learningBlock,
     observability: observabilityBlock,
     heartbeat: heartbeatBlock,
     gateway: channelGatewayBlock,
@@ -984,6 +1215,9 @@ const managedSchema = z
     failure_taxonomy: failureTaxonomyBlock,
     budget: budgetBlock,
     memory: memoryBlock,
+    continuity: continuityBlock,
+    thredz: thredzBlock,
+    learning: learningBlock,
     observability: observabilityBlock,
 })
     .strict();
@@ -1101,6 +1335,13 @@ const crewSchema = z
     permissions: permissionsBlock,
     compaction: compactionBlock,
     failure_taxonomy: failureTaxonomyBlock,
+    // v0.3.0 — crew joins the memory-carrying shapes (§9: emit-wired; the
+    // roles share the spec-scoped stores — the plan IS the coordination
+    // surface, §2.7).
+    memory: memoryBlock,
+    continuity: continuityBlock,
+    thredz: thredzBlock,
+    learning: learningBlock,
     chains: chainsBlock,
     wallets: walletsBlock,
     contracts: contractsBlock,
@@ -1139,6 +1380,9 @@ const researchSchema = z
     compaction: compactionBlock,
     failure_taxonomy: failureTaxonomyBlock,
     memory: memoryBlock,
+    continuity: continuityBlock,
+    thredz: thredzBlock,
+    learning: learningBlock,
     chains: chainsBlock,
     wallets: walletsBlock,
     contracts: contractsBlock,
@@ -1173,6 +1417,9 @@ const batchSchema = z
     permissions: permissionsBlock,
     compaction: compactionBlock,
     failure_taxonomy: failureTaxonomyBlock,
+    // v0.3.0 — carried but not emit-wired in 0.3.0 (ignored-note comment in
+    // the generated bundle; NOT default-on here).
+    continuity: continuityBlock,
     chains: chainsBlock,
     wallets: walletsBlock,
     contracts: contractsBlock,
@@ -1213,6 +1460,9 @@ const voiceSchema = z
     permissions: permissionsBlock,
     compaction: compactionBlock,
     failure_taxonomy: failureTaxonomyBlock,
+    // v0.3.0 — carried but not emit-wired in 0.3.0 (ignored-note comment in
+    // the generated bundle; NOT default-on here).
+    continuity: continuityBlock,
 })
     .strict();
 // Browser target (Section 25 BROW). Computer-use / browser-driver agent.
@@ -1244,6 +1494,9 @@ const browserSchema = z
     permissions: permissionsBlock,
     compaction: compactionBlock,
     failure_taxonomy: failureTaxonomyBlock,
+    // v0.3.0 — carried but not emit-wired in 0.3.0 (ignored-note comment in
+    // the generated bundle; NOT default-on here).
+    continuity: continuityBlock,
 })
     .strict();
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/spec",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "description": "User-facing spec schema (Zod) + YAML parser",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.2.3",
+    "@crewhaus/errors": "0.3.0",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },