@manifesto-ai/skills 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,43 @@
+# @manifesto-ai/skills
+
+LLM knowledge pack for Manifesto.
+
+## Codex setup
+
+With npm:
+
+```bash
+npm i -D @manifesto-ai/skills
+npm exec manifesto-skills install-codex
+```
+
+With pnpm:
+
+```bash
+pnpm add -D @manifesto-ai/skills
+pnpm exec manifesto-skills install-codex
+```
+
+This installs the managed `manifesto` skill into `$CODEX_HOME/skills/manifesto` or `~/.codex/skills/manifesto`.
+The setup is explicit so package-manager `postinstall` approval policies do not block installation.
+
+If package-manager exec is unavailable, run:
+
+```bash
+node ./node_modules/@manifesto-ai/skills/scripts/manifesto-skills.mjs install-codex
+```
+
+After installation, restart Codex.
+
+## Claude Code setup
+
+Add this to your `CLAUDE.md`:
+
+```md
+See @node_modules/@manifesto-ai/skills/SKILL.md for Manifesto development rules.
+```
+
+## Notes
+
+- This package does not auto-install Codex files from `postinstall`.
+- The installer refuses to overwrite an existing non-managed `manifesto` skill directory.

package/SKILL.md

@@ -1,14 +1,27 @@
-# Manifesto Skills v0.1
+---
+name: manifesto
+description: Use when working on Manifesto repositories, MEL flows, or Core/Host/SDK/World boundaries. Loads implementation-aligned architecture, patch, effect, and package guidance.
+---
+
+# Manifesto Skills v0.2.0
 
 You are working on a Manifesto-based project. These rules are non-negotiable.
 
+## Scope Note
+
+This skills pack follows the current implementation in this repo.
+
+- `@manifesto-ai/world` is the canonical governed composition package and exact consumer-facing facade.
+- `@manifesto-ai/governance` and `@manifesto-ai/lineage` are implemented code packages and own their protocol-layer behavior.
+- For governed work, prefer top-level `@manifesto-ai/world` for composition and import split-native packages directly only when the task is intentionally limited to governance or lineage.
+
 ## Absolute Rules
 
 1. **Core is pure.** No IO, no `Date.now()`, no side effects, no randomness. `compute()` is a pure function.
 2. **Snapshot is the only medium.** All communication between computations happens through Snapshot. No hidden channels, no return values from effects.
 3. **Three patch ops only.** `set`, `unset`, `merge` (shallow). No other mutation operations exist.
 4. **Effects are declarations.** Core declares requirements; Host executes them. Core never performs IO.
-5. **Errors are values.** Errors live in Snapshot state, never thrown. Core MUST NOT throw for business logic.
+5. **Errors are values.** Errors live in Snapshot state, never thrown. Core must not throw for business logic.
 6. **Flows terminate.** No unbounded loops in Flow. Host controls iteration. All guards required for re-entry safety.
 7. **`$` is reserved.** `$host`, `$mel`, `$system` are platform namespaces. Never use `$` in domain identifiers.
 
@@ -18,17 +31,17 @@ SPEC > FDR > ADR > Code > README. Never invent semantics not in SPEC.
 
 ## Task-Specific Knowledge
 
-Load these BEFORE writing code in each area:
+Load these before writing code in each area:
 
 | Task | Knowledge File |
 |------|---------------|
-| Understanding Core/Host/World boundaries | `@knowledge/architecture.md` |
+| Understanding Core/Host/SDK/World boundaries | `@knowledge/architecture.md` |
 | Writing MEL domain code | `@knowledge/mel-patterns.md` |
 | MEL complete function reference | `@knowledge/mel-reference.md` |
 | Implementing effect handlers | `@knowledge/effect-patterns.md` |
 | Working with state/patches | `@knowledge/patch-rules.md` |
 | Reviewing or debugging | `@knowledge/antipatterns.md` |
-| Looking up SPEC references | `@knowledge/spec-index.md` |
+| Looking up current specs and design docs | `@knowledge/spec-index.md` |
 
 ## Package API Reference
 
@@ -47,7 +60,7 @@ Load when working with a specific package API:
 
 Before submitting any code change, verify:
 
-- [ ] Determinism preserved? (same input → same output)
+- [ ] Determinism preserved? (same input -> same output)
 - [ ] Snapshot is sole communication medium?
 - [ ] All mutations via patches?
 - [ ] No forbidden imports across package boundaries?

package/knowledge/architecture.md

@@ -1,94 +1,86 @@
 # Manifesto Architecture
 
-> Source: Core SPEC v2.0.1, Core FDR v2.0.0, Host SPEC v2.0.2, World SPEC v2.0.3, SDK SPEC v0.1.0
-> Last synced: 2026-02-22
+> Source: `packages/core/docs/core-SPEC.md`, `packages/host/docs/host-SPEC.md`, `packages/sdk/docs/sdk-SPEC-v2.0.0.md`, current `packages/world/src/*`
+> Last synced: 2026-03-31
 
 ## Rules
 
-> **R1**: Core computes, Host executes. These concerns never mix. [FDR-001]
-> **R2**: Snapshot is the only medium of communication. If it's not in Snapshot, it doesn't exist. [FDR-002]
-> **R3**: There is no suspended execution context. All continuity is expressed through Snapshot. [FDR-003]
-> **R4**: Effects are declarations, not executions. Core declares; Host fulfills. [FDR-004]
-> **R5**: If you need a value, read it from Snapshot. There is no other place. [FDR-007]
-
-## The Constitution (7 Principles)
-
-```
-1. Core is a calculator, not an executor.
-2. Schema is the single source of truth.
-3. Snapshot is the only medium of communication.
-4. Effects are declarations, not executions.
-5. Errors are values, not exceptions.
-6. Everything is explainable.
-7. There is no suspended execution context.
-```
+> **R1**: Core computes, Host executes. These concerns never mix.
+> **R2**: Snapshot is the only medium of communication. If it's not in Snapshot, it doesn't exist.
+> **R3**: There is no suspended execution context. All continuity is expressed through Snapshot.
+> **R4**: Effects are declarations, not executions. Core declares; Host fulfills.
+> **R5**: If you need a value, read it from Snapshot. There is no other place.
 
 ## The Fundamental Equation
 
-```
-compute(schema, snapshot, intent, context) → (snapshot', requirements[], trace)
+```typescript
+compute(schema, snapshot, intent, context) -> {
+  patches,
+  systemDelta,
+  trace,
+  status,
+}
 ```
 
-- **Pure**: Same input MUST always produce same output
-- **Total**: MUST always return a result (never throws)
-- **Traceable**: Every step MUST be recorded
-- If `requirements` is empty → computation complete
-- If `requirements` is non-empty → Host fulfills them, then calls `compute()` again
+- **Pure**: Same input must produce the same result.
+- **Total**: Business logic failures are reported as values, not thrown.
+- **Traceable**: Compute returns a trace graph for explainability.
+- **Resumable via Snapshot**: Host applies `patches` + `systemDelta`, then re-enters `compute()` with the new snapshot.
 
-## Data Flow
+## Runtime Paths
 
-```
-Actor submits Intent
-      ↓
-World Protocol (Proposal + Authority)
-      ↓
-Host (compute loop + effect execution)
-      ↓
-Core (pure computation)
-      ↓
-New Snapshot (via patches)
-      ↓
-New World (immutable)
+Two practical paths exist in the current repo:
+
+```text
+SDK-style app
+  createManifesto()
+    -> Host
+    -> Core
 ```
 
-Information flows ONLY through Snapshot. No other channels exist.
+```text
+Governed path
+  Actor submits IntentInstance
+    -> World
+    -> WorldExecutor
+    -> Host
+    -> Core
+    -> new World state + lineage records
+```
 
 ## Package Sovereignty
 
 | Package | Responsibility | MUST NOT |
 |---------|---------------|----------|
-| **Core** | Pure computation, expression evaluation, flow interpretation, patch generation, trace | IO, time, execution, know about Host/World |
-| **Host** | Effect execution, patch application, compute loop, requirement fulfillment | Make decisions, interpret semantics, suppress effects |
-| **World** | Proposal management, authority evaluation, decision recording, lineage | Execute effects, apply patches, compute transitions |
-| **Runtime** | Internal orchestration — 5-stage action pipeline, policy, memory, branches | Public API design, domain logic |
-| **SDK** | Public developer API — `createApp()`, hooks, typed ops. Delegates to Runtime | Contain domain logic, orchestration internals |
-
-## Forbidden Import Matrix
-
-| Package | MUST NOT Import |
-|---------|----------------|
-| core | host, world |
-| host | world governance |
-| world | host internals, core compute |
-| runtime | SDK public surface |
-| sdk | core internals, host internals, world internals |
+| **Core** | Pure computation, expression evaluation, flow interpretation, patch generation, validation, explanation | IO, wall-clock access, effect execution, Host/World policy |
+| **Host** | Effect execution, patch application, compute loop orchestration, requirement fulfillment | Compute semantic meaning, suppress declared effects, make governance decisions |
+| **World** | Proposal lifecycle, authority evaluation, lineage DAG, persistence, governance event emission | Import `@manifesto-ai/host` directly, compute semantic meaning, apply Core patches itself |
+| **SDK** | Public app entrypoint (`createManifesto`), typed effect registration, `dispatchAsync`, typed patch helpers, selected re-exports | Invent semantics outside Core/Host/World public contracts |
+
+## Current Governed Structure
+
+In this repo's implementation:
+
+- `@manifesto-ai/world` is the exact consumer-facing governed facade
+- `@manifesto-ai/governance` is the current governance protocol package
+- `@manifesto-ai/lineage` is the current continuity protocol package
+- top-level `@manifesto-ai/world` re-exports the split-native surfaces needed for explicit composition
 
 ## Snapshot Structure
 
 ```typescript
 type Snapshot = {
-  data: TData;                    // Domain state (+ platform namespaces $host, $mel)
-  computed: Record<string, unknown>; // Derived values (always recalculated)
+  data: unknown;
+  computed: Record<string, unknown>;
   system: {
-    status: 'idle' | 'computing' | 'pending' | 'error';
+    status: "idle" | "computing" | "pending" | "error";
     lastError: ErrorValue | null;
-    errors: readonly ErrorValue[];
-    pendingRequirements: readonly Requirement[];
+    pendingRequirements: Requirement[];
     currentAction: string | null;
   };
-  input: unknown;                 // Transient action input
+  input: unknown;
   meta: {
-    version: number;              // Monotonically increasing
+    version: number;
     timestamp: number;
     randomSeed: string;
     schemaHash: string;
@@ -96,63 +88,35 @@ type Snapshot = {
 };
 ```
 
-## Platform Namespaces
-
-- `$host` — Host-owned internal state (intent slots, execution context). Excluded from hash.
-- `$mel` — Compiler-owned guard state (`$mel.guards.*`). Excluded from hash.
-- `$system.*` — System values (uuid, time.now). Lowered to effects by compiler.
-- Domain schemas MUST NOT define `$`-prefixed fields.
+## Compute / Apply Cycle
 
-## Computation Cycle
-
-```
+```text
 Host calls compute(schema, snapshot, intent, context)
-  → Core evaluates Flow until:
-    - Flow completes (requirements=[]) → DONE
-    - Effect encountered (requirements=[...]) → Host executes effects, applies patches, calls compute() AGAIN
-    - Error occurs → error recorded in Snapshot
-```
-
-Each `compute()` is complete and independent. There is no "resume".
-
-## Antipatterns
-
-### Intelligent Host
-```typescript
-// FORBIDDEN — Host making decisions
-if (shouldSkipEffect(req)) { return []; }
-
-// Host MUST execute or report failure, never decide
+  -> Core returns patches + systemDelta + trace + status
+  -> Host applies patches
+  -> Host applies systemDelta
+  -> If status is pending, Host fulfills requirements and calls compute() again
 ```
 
-### Value Passing Outside Snapshot
-```typescript
-// FORBIDDEN
-const result = await executeEffect();
-core.compute(schema, snapshot, { ...intent, result });
-
-// CORRECT — Effect returns patches → Host applies → Core reads from Snapshot
-```
+Each `compute()` call is complete and independent. Continuity lives in the snapshot, not in hidden runtime state.
 
-### Execution-Aware Core
-```typescript
-// FORBIDDEN — Core cannot know about execution
-if (effectExecutionSucceeded) { ... }
+## Platform Namespaces
 
-// CORRECT — Core reads state
-if (snapshot.data.syncStatus === 'success') { ... }
-```
+- `$host` is Host-owned internal state.
+- `$mel` is compiler-owned guard state.
+- `$system.*` values are surfaced in MEL and lowered through platform mechanics.
+- Domain schemas must not define `$`-prefixed fields.
 
 ## Why
 
-Separation of concerns enables:
-- **Determinism**: Core testable without mocks (same input → same output)
-- **Auditability**: World tracks all governance decisions with lineage
-- **Portability**: Host swappable per environment (browser/server/edge/WASM)
-- **Reproducibility**: Snapshot serialization enables time-travel debugging
+- **Determinism**: Core can be tested without mocks.
+- **Auditability**: World records proposal and decision lineage.
+- **Portability**: Host remains the execution seam.
+- **Clarity**: SDK is the public app-facing direct-dispatch layer, while World is the explicit governed composition layer around Host.
 
 ## Cross-References
 
-- MEL syntax: @knowledge/mel-patterns.md
-- Effect handlers: @knowledge/effect-patterns.md
-- Patch operations: @knowledge/patch-rules.md
+- MEL syntax: `@knowledge/mel-patterns.md`
+- Effect handlers: `@knowledge/effect-patterns.md`
+- Patch operations: `@knowledge/patch-rules.md`
+- World package API: `@knowledge/packages/world.md`

package/knowledge/effect-patterns.md

@@ -1,52 +1,66 @@
 # Effect Patterns
 
-> Source: Host SPEC v2.0.2 §7, SDK SPEC v0.1.0, Core FDR v2.0.0
-> Last synced: 2026-02-22
+> Source: `packages/host/docs/host-SPEC.md`, `packages/sdk/src/types.ts`, `packages/sdk/src/create-manifesto.ts`
+> Last synced: 2026-03-28
 
 ## Rules
 
-> **R1**: Effect handlers MUST return `Patch[]` and MUST NOT throw exceptions. [HANDLER-1, HANDLER-2]
-> **R2**: Failures MUST be expressed as patches to state (error values in Snapshot). [HANDLER-3]
-> **R3**: Effect handlers MUST NOT contain domain logic. They are pure IO adapters. [HANDLER-4, HANDLER-5]
-> **R4**: Effects are declared by Core, executed by Host. Core never performs IO. [FDR-004]
-> **R5**: Host-generated error patches MUST target `$host` or domain-owned paths, NOT `system.*`. [INV-SNAP-4]
+> **R1**: Effect handlers return `Patch[]` and should not use exceptions as the business-logic result channel.
+> **R2**: Failures should be expressed as state patches or terminal execution results.
+> **R3**: Effect handlers are IO adapters, not policy engines.
+> **R4**: Effects are declared by Core and executed by Host.
+> **R5**: Handler patches should target domain-owned or platform-approved paths, not ad hoc hidden state.
 
 ## Handler Contract
 
-Developers register effect handlers through the **SDK layer** API:
+Developers register effect handlers through the SDK:
 
 ```typescript
-// SDK-layer handler signature (what you write)
+type EffectContext<T = unknown> = {
+  readonly snapshot: Readonly<Snapshot<T>>;
+};
+
 type EffectHandler = (
   params: unknown,
-  ctx: AppEffectContext
+  ctx: EffectContext,
 ) => Promise<readonly Patch[]>;
+```
 
-type Patch = {
-  op: 'set' | 'unset' | 'merge';
-  path: string;
-  value?: unknown;
-};
+Host uses a different internal signature, but SDK adapts your handler automatically.
+
+## Registration Pattern
+
+```typescript
+import { createManifesto } from "@manifesto-ai/sdk";
+
+const app = createManifesto({
+  schema: domainSchema,
+  effects: {
+    "api.fetchUser": fetchUser,
+    "api.createTodo": createTodo,
+    "payment.process": processPayment,
+  },
+});
 ```
 
-Note: The Host layer internally uses a different signature `(type, params, context)` but SDK wraps this. Handlers receive effect params, perform IO, and return patches.
+Effect names must match effect types declared in schema or MEL.
 
 ## Patterns
 
-### Successful Effect
+### Successful effect
 
 ```typescript
 async function fetchUser(params: { id: string }): Promise<Patch[]> {
   const response = await fetch(`/users/${params.id}`);
   const data = await response.json();
   return [
-    { op: 'set', path: 'data.user', value: data },
-    { op: 'set', path: 'data.user.error', value: null }
+    { op: "set", path: "data.user.data", value: data },
+    { op: "set", path: "data.user.error", value: null },
   ];
 }
 ```
 
-### Failed Effect (Errors as Patches)
+### Failed effect
 
 ```typescript
 async function fetchUser(params: { id: string }): Promise<Patch[]> {
@@ -54,134 +68,89 @@ async function fetchUser(params: { id: string }): Promise<Patch[]> {
     const response = await fetch(`/users/${params.id}`);
     if (!response.ok) {
       return [
-        { op: 'set', path: 'data.user.error', value: { code: response.status } },
-        { op: 'set', path: 'data.user.data', value: null }
+        { op: "set", path: "data.user.error", value: { code: response.status } },
+        { op: "set", path: "data.user.data", value: null },
       ];
     }
+
     const data = await response.json();
     return [
-      { op: 'set', path: 'data.user.data', value: data },
-      { op: 'set', path: 'data.user.error', value: null }
+      { op: "set", path: "data.user.data", value: data },
+      { op: "set", path: "data.user.error", value: null },
     ];
   } catch (error) {
     return [
-      { op: 'set', path: 'data.user.error', value: { message: error.message } },
-      { op: 'set', path: 'data.user.data', value: null }
+      {
+        op: "set",
+        path: "data.user.error",
+        value: { message: error instanceof Error ? error.message : String(error) },
+      },
+      { op: "set", path: "data.user.data", value: null },
     ];
   }
 }
 ```
 
-### Effect Registration (SDK Layer)
-
-```typescript
-import { createApp } from '@manifesto-ai/sdk';
-
-const app = createApp({
-  schema: domainSchema,
-  effects: {
-    'api.fetchUser': fetchUser,
-    'api.createTodo': createTodo,
-    'payment.process': processPayment,
-  },
-});
-```
-
-Effect names in handlers must match effect type names declared in MEL.
-
-### Collection Effect Handlers
-
-Collection effects (`array.filter`, `array.map`, `record.keys`, etc.) are built-in — you do NOT write handlers for these. They are handled by Core/Host internally.
+## Built-in collection effects
 
-You only write handlers for custom domain effects (API calls, storage, etc.).
+Collection-oriented effects such as `array.filter`, `array.map`, and `record.keys` are platform/compiler features. This document is about custom domain handlers such as API, storage, or integration effects.
 
 ## Antipatterns
 
-### Throwing Handler
+### Throwing as the primary failure channel
 
 ```typescript
-// FORBIDDEN
+// Avoid this for business logic failures
 async function bad(params) {
-  if (!params.id) throw new Error('Missing id');  // Don't throw!
-  const result = await api.call(params.id);
-  return [{ op: 'set', path: 'data.result', value: result }];
+  if (!params.id) throw new Error("Missing id");
+  return [{ op: "set", path: "data.result", value: await api.call(params.id) }];
 }
 
-// CORRECT
+// Prefer patches
 async function good(params) {
   if (!params.id) {
-    return [{ op: 'set', path: 'data.error', value: 'Missing id' }];
+    return [{ op: "set", path: "data.error", value: "Missing id" }];
   }
-  const result = await api.call(params.id);
-  return [{ op: 'set', path: 'data.result', value: result }];
+  return [{ op: "set", path: "data.result", value: await api.call(params.id) }];
 }
 ```
 
-### Domain Logic in Handler
+### Domain logic in handler
 
 ```typescript
-// FORBIDDEN — Business rule in handler
+// Avoid policy decisions here
 async function purchaseHandler(params) {
-  if (params.amount > 1000) {  // Domain decision!
-    return [{ op: 'set', path: 'data.approval.required', value: true }];
+  if (params.amount > 1000) {
+    return [{ op: "set", path: "data.approval.required", value: true }];
   }
-  // ...
-}
-
-// CORRECT — Handler does IO only, domain logic stays in Flow/MEL
-async function paymentHandler(params) {
-  const result = await paymentGateway.charge(params.amount);
-  return [{ op: 'set', path: 'data.payment.status', value: result.status }];
+  return [];
 }
 ```
 
-### Returning Raw Values
+Keep business rules in Core / Flow / MEL where they remain traceable.
+
+### Returning raw values
 
 ```typescript
-// FORBIDDEN — Returns value, not patches
+// Wrong: not a Patch[]
 async function bad(params) {
-  return await api.fetchData(params.id);  // Returns data directly!
-}
-
-// CORRECT — Returns patches
-async function good(params) {
-  const data = await api.fetchData(params.id);
-  return [{ op: 'set', path: 'data.result', value: data }];
+  return api.fetchData(params.id);
 }
 ```
 
-### Writing to system.*
-
-```typescript
-// FORBIDDEN — Handler must not write system namespace
-return [{ op: 'set', path: 'system.lastError', value: { ... } }];
-
-// CORRECT — Write to $host or domain paths
-return [{ op: 'set', path: 'data.fetchError', value: { ... } }];
-```
-
 ## Requirement Lifecycle
 
 When Core encounters an effect declaration:
-1. Core records a Requirement in `system.pendingRequirements`
-2. Core terminates and returns to Host
-3. Host executes the effect handler
-4. Host applies result patches to Snapshot
-5. Host MUST clear the requirement from `pendingRequirements`
-6. Host calls `compute()` again
-
-**Critical**: Requirement MUST be cleared even if handler fails. Leaving it pending causes infinite loops.
-
-## Why
-
-**Patches as protocol**: Decouples effect execution from Core. Host can serialize, batch, retry, or substitute effects without Core knowing.
 
-**Errors as values**: Same inputs (including failures) always produce same snapshot state. Enables deterministic replay.
+1. Core emits a pending result with requirements in snapshot/system state.
+2. Host executes the matching handler.
+3. Host applies returned patches.
+4. Host updates system state and re-enters compute.
 
-**No domain logic**: Keeps all business decisions in Flow/MEL where they are traceable and deterministic.
+The details differ between Core and Host internals, but the contract is the same: effect execution feeds back through snapshot changes, never hidden channels.
 
 ## Cross-References
 
-- Patch operations: @knowledge/patch-rules.md
-- State structure: @knowledge/architecture.md
-- MEL effect declarations: @knowledge/mel-patterns.md
+- Patch operations: `@knowledge/patch-rules.md`
+- State structure: `@knowledge/architecture.md`
+- SDK package API: `@knowledge/packages/sdk.md`