@oneie/claude 0.5.0 → 0.6.0

package/skills/docs/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: docs
+description: Pick the right documentation type and write it with the right discipline. Use whenever creating or editing any file in text/ that documents a feature — a marketing promise (.md), feature spec (-features.md), UI spec (-ui.md), architecture (-plan.md), explanation (-docs.md), tutorial (-tutorial.md), how-to (-how-to.md), reference (-reference.md), or agent briefing (-agents-docs.md). Invoke this BEFORE writing to choose the type and load its rules; it works on top of the `writer` skill (craft) and the templates (shape). Triggers — "write the docs for X", "document this feature", "write a tutorial/how-to/reference/explanation", "what doc type is this", "split this doc", "this doc mixes concerns".
+---
+
+# docs — the documentation discipline
+
+This skill is the **middle layer** of three. It does not write prose (that's the `writer` skill) and it does not hold the section skeleton (that's the `template-*.md` files). It does one thing the other two can't: **it knows the ONE doc taxonomy, picks the right type for the reader, and enforces the one rule that type lives or dies by.**
+
+A generic writing skill can make any paragraph clearer. It cannot tell you that the paragraph doesn't belong in a `-reference.md` at all. That judgment is this skill.
+
+**The order:** invoke `docs` (pick type + rules) → copy the matching `template-*.md` (shape) → invoke `writer` (craft the prose) → check `.claude/product-marketing.md` (voice).
+
+The full taxonomy lives in [`text/docs.md`](../../../text/docs.md); the template map in [`text/templates.md`](../../../text/templates.md). This skill is how you *apply* them.
+
+---
+
+## First: which type?
+
+Every doc answers **one reader's one question at one moment.** Find the reader and the question; the type falls out.
+
+| The reader's question | Type | File |
+|---|---|---|
+| "Why would I want this?" | promise | `<slug>.md` |
+| "What does it do?" | features | `<slug>-features.md` |
+| "What does it look like?" | ui | `<slug>-ui.md` |
+| "How is it built?" | plan | `<slug>-plan.md` |
+| "How does it work, and why?" | explanation | `<slug>-docs.md` |
+| "How do I succeed the first time?" | tutorial | `<slug>-tutorial.md` |
+| "How do I do X?" | how-to | `<slug>-how-to.md` |
+| "What's the exact spec?" | reference | `<slug>-reference.md` |
+| "What does an agent need to operate it?" | agent briefing | `<slug>-agents-docs.md` |
+
+If a single file is trying to answer two of these, **it's the wrong file** — split it. A doc that mixes "how do I" steps with "why it works" theory serves neither reader.
+
+**Don't over-create.** Most features need only `.md` + `-plan.md` + `-docs.md`. Reach for tutorial / how-to / reference only when the feature outgrows one explanation file.
+
+---
+
+## The four user docs are a grid
+
+The user-facing types aren't a list — they're the four cells of [Diátaxis](https://diataxis.fr/), split by what the reader is *doing* (practical vs. theoretical) and where they *are* (learning vs. working):
+
+```
+                  PRACTICAL (doing)        THEORETICAL (knowing)
+              ┌─────────────────────────┬─────────────────────────┐
+ LEARNING     │  tutorial               │  explanation (-docs)    │
+ (studying)   │  succeed first time     │  understand how & why   │
+              ├─────────────────────────┼─────────────────────────┤
+ WORKING      │  how-to                 │  reference              │
+ (applying)   │  get this task done     │  look up the exact spec │
+              └─────────────────────────┴─────────────────────────┘
+```
+
+The most common failure is mixing two cells in one doc. The grid is the cure: when a section feels off, name its cell. If it's a different cell than the doc, move it.
+
+---
+
+## The discipline per type
+
+Each type has **one cardinal rule** — the thing it must never do. Break it and the type collapses into another.
+
+### explanation (`-docs.md`) — understanding-oriented
+Background, the mental model, the why. The page that makes every other page click.
+- **Cardinal rule: no steps.** The moment you write "first… then…" you've drifted to tutorial/how-to.
+- Tell: "therefore", "because", "the reason is", "this fits the system by…"
+- Default for most features: this is the one doc you write. (Template `template-teach.md` makes it a complete guide — model + first win + runbook — when no split is needed.)
+
+### tutorial (`-tutorial.md`) — learning-oriented
+One complete story, beginning to a guaranteed success. The reader follows; the doc leads.
+- **Cardinal rule: never fork on reader state.** No "if you have X, do Y." One path. If the reader's setup varies, that's a how-to, not a tutorial.
+- Every command exact and verified. Show the expected output after each step. End on the win.
+- It's about *learning by doing*, not about the task — the result can be a toy; the point is the reader's confidence.
+
+### how-to (`-how-to.md`) — task-oriented
+A practitioner who already knows the concept needs the steps for one real task.
+- **Cardinal rule: no concept-explaining.** No teaching what a campaign is — link to `-docs.md`. Straight to the recipe.
+- Title is a task: "How to…", "Running a…". Assumes competence. Numbered steps + a verify.
+
+### reference (`-reference.md`) — information-oriented
+Complete, precise, neutral. Field types, signal names, limits, defaults, error codes.
+- **Cardinal rule: no opinions, no prose explanation.** If you're tempted to explain *why*, link to `-docs.md`. Reference states *what*.
+- Structure mirrors the code's structure (a table per surface). Exhaustive over readable.
+
+---
+
+## The ONE-specific types
+
+Not Diátaxis — but they obey the same "one reader, one question" law.
+
+### promise (`<slug>.md`) — the buyer, pre-purchase + the genesis contract
+Marketing copy on the surface; a contract underneath. The **first file** — everything else derives from it and reconciles **upward** to it.
+- **Cardinal rule: persuade, don't specify.** Lead with what the persona gets (hire, sell, ship, earn). Drop internal words — `mark`/`warn`/`substrate`/`pheromone` belong nowhere near it (see `.claude/product-marketing.md`).
+- This is the spec the `/do` PROVE stage checks shipped behavior against. Every claim must be true.
+- **Frontmatter is the contract — four machine-read manifests, read like an agency SOW:** `deliverables:` (the exhaustive schedule of work — every item the client receives, each with its own `accept:` bash check; not listed = not promised, listed = ships or the promise settles broken, acceptance indivisible; `assumes:` alongside lists client-side dependencies, green at the making) + `proof:` (the acceptance test — **derived, not authored**: the `&&`-join of every `accept:`, verbatim; it becomes the todo `outcome:`, the TEST assertion, and the PROVE oracle) + `derives:` (the manifest of which files to spawn) + `world:` (the runtime the kept promise puts into the substrate — lifecycle moves + recording signals, workflow steps, agents + `subscribes:` tags, skills, task tags, tracking marks/warns, routing paths). The schedule ⇄ proof law is linted by `.claude/scripts/do-promise-lint.sh <slug>` — the PROMISE gate. Body must carry **"The deliverables (the schedule of work)"** (the SOW table + completeness clause) and **"Out of scope (excluded, in writing)"** (enumerated exclusions). **`derives:` is authoritative** for which conditional docs exist — this skill *confirms/refines* that choice, it does not override it. `/do` presence-checks every `world:` entry like an artifact: missing agent → a `template-agent.md` cycle (+ `subscriptions:register` for its tags) · missing skill → `/skill-creator` · missing workflow/lifecycle stage → a todo cycle · present → skip. Design: `text/promise-plan.md`.
+- **Contract-backed form:** a promise uncomments the `contract:` block in `text/template-feature.md` and mints a generated Move Promise at PROMISE; `do-promise-settle.sh` settles it at close from the proof exit code. Worked example: `text/playbook.md`.
+- Craft is `writer` + `copywriting`, not this skill — but `docs` keeps it from absorbing feature-spec detail (that's `-features.md`).
+
+### features (`<slug>-features.md`) — the builder/PM
+WHAT the feature does: capabilities, scope, use cases, and **non-goals**.
+- **Cardinal rule: no implementation.** What it does, not how it's built (that's `-plan.md`).
+- Non-goals are load-bearing — they're how scope stops creeping.
+
+### ui (`<slug>-ui.md`) — the builder/designer
+WHAT it looks like: screens, component states (empty · loading · error · success · edit), user flows.
+- **Cardinal rule: no backend wiring.** Pair with the `frontend-design` skill for layout quality.
+
+### plan (`<slug>-plan.md`) — the builder
+HOW it's built: signals, TypeDB schema, the authority walk, the reuse verdict.
+- **Cardinal rule: no selling and no user-facing "what it does"** — that's `.md` and `-features.md`.
+
+### agent briefing (`<slug>-agents-docs.md`) — the agent
+A dense, token-lean briefing for an AI agent that must *act*: the signal chain, schema types and their fields, receivers, authority (role → can), compact task recipes, and error → recovery-signal.
+- **Cardinal rule: briefing, not background.** No essays, no motivation, no journey. Tables and signal chains. Optimized for tokens, not warmth.
+- Verify every signal name, receiver, and field against the code (`packages/sdk/src/receivers.ts`, `schema/*.tql`) — invoke `sdk`/`typedb` for accuracy. A wrong signal name here breaks a real agent.
+
+---
+
+## How it composes with the other layers
+
+1. **Pick the type** (this skill) — reader + question → type. If the content spans two types, split before writing.
+2. **Copy the template** — `cp text/template-<type>.md text/<slug>-<suffix>.md`. The template is the shape; never write a doc-spine artifact from scratch.
+3. **Write with `writer`** — apply the craft loop (cut, show-don't-tell, structure, sentence polish). This skill says *what goes where*; `writer` makes each sentence land.
+4. **Check voice** — `.claude/product-marketing.md`: ONE's audience (CEOs + engineers), simple English, banned words. Run `do-reconcile.sh dictionary` on the file before committing (no dead names, no new synonyms).
+
+---
+
+## Self-check before shipping any doc
+
+- [ ] **One reader, one question.** Name them. If you name two, split the file.
+- [ ] **Cardinal rule held.** The type's one forbidden thing is absent (no steps in explanation, no fork in tutorial, no opinion in reference, no essay in agent briefing).
+- [ ] **Right file name.** The suffix matches the type (`-docs` vs `-reference` vs `-how-to`).
+- [ ] **No duplication across files.** If two docs say the same thing, one should link to the other.
+- [ ] **Links resolve.** Cross-references to sibling docs and `file:line` anchors are real.
+- [ ] **Facts verified.** For reference/agent-briefing, every name/signal/field checked against code.
+- [ ] **Voice clean.** No banned words; dictionary reconcile passes.
+
+---
+
+## Common fixes
+
+| Symptom | Fix |
+|---|---|
+| `-docs.md` has numbered steps | Move them to `-how-to.md` (a task) or `-tutorial.md` (a first run); keep only the why |
+| `-tutorial.md` says "if you have X…" | It forks — either pick one path, or it's actually a how-to |
+| `-reference.md` opens with a paragraph of context | Move the prose to `-docs.md`; reference is facts only |
+| `.md` reads like a spec | Move the spec to `-features.md`; the `.md` sells |
+| `-agents-docs.md` reads like a guide | Cut the narration to tables + signal chains |
+| One doc serves both a beginner and an expert | Split: tutorial for the beginner, reference for the expert |
+
+---
+
+*Taxonomy: [`text/docs.md`](../../../text/docs.md). Templates: [`text/templates.md`](../../../text/templates.md). Craft: `writer` skill. Voice: [`.claude/product-marketing.md`](../../product-marketing.md).*

package/skills/mcp/SKILL.md

@@ -0,0 +1,242 @@
+# MCP tools — Model Context Protocol for agents
+
+MCP tools give agents programmatic access to ONE capabilities. They're scaffolded, typed, and auto-discovered.
+
+## Structure
+
+```
+packages/mcp/
+├── src/
+│   ├── index.ts              # MCP server entrypoint
+│   ├── tools/                # tool implementations
+│   │   ├── index.ts          # tool registry + re-exports
+│   │   ├── chat/             # chat-related tools
+│   │   │   ├── index.ts
+│   │   │   └── memory.ts
+│   │   └── {domain}/
+│   │       ├── index.ts
+│   │       └── {action}.ts
+│   └── schema.ts             # Zod schemas for tool inputs
+```
+
+## Pattern: Adding an MCP tool
+
+### 1. Define the schema (input + output types)
+
+```typescript
+// packages/mcp/src/schema.ts
+import { z } from 'zod';
+
+export const memoryToolSchema = z.object({
+  groupId: z.string().describe('Group ID'),
+  content: z.string().describe('Memory content to store'),
+});
+
+export type MemoryToolInput = z.infer<typeof memoryToolSchema>;
+```
+
+### 2. Implement the tool
+
+```typescript
+// packages/mcp/src/tools/chat/memory.ts
+import { SubstrateClient } from '@oneie/sdk';
+import { memoryToolSchema, MemoryToolInput } from '../schema';
+
+export async function memoryTool(input: MemoryToolInput): Promise<string> {
+  const client = new SubstrateClient();
+  const memory = await client.memory(input.groupId);
+  
+  if (!memory) {
+    return 'No memory found for this group.';
+  }
+  
+  return JSON.stringify(memory);
+}
+
+export const MEMORY_TOOL = {
+  name: 'memory',
+  description: 'Read or write group memory',
+  inputSchema: memoryToolSchema,
+  execute: memoryTool,
+};
+```
+
+**Rules:**
+- Schema first (using Zod)
+- Function receives typed input
+- Function returns string (MCP protocol requirement)
+- Tool object has name, description, inputSchema, execute
+- Tool calls SDK methods, never direct HTTP/DB
+
+### 3. Register the tool
+
+```typescript
+// packages/mcp/src/tools/chat/index.ts
+export { MEMORY_TOOL } from './memory';
+export * as chatTools from './index';
+
+// packages/mcp/src/tools/index.ts
+import * as chatTools from './chat';
+export const TOOLS = [
+  chatTools.MEMORY_TOOL,
+  // other tools
+] as const;
+
+// packages/mcp/src/index.ts
+import { TOOLS } from './tools';
+
+export const mcpServer = {
+  tools: TOOLS,
+  // other MCP config
+};
+```
+
+### 4. Test the tool
+
+```typescript
+// packages/mcp/test/chat.memory.test.ts
+describe('Memory tool', () => {
+  it('returns memory for a group', async () => {
+    const result = await memoryTool({ groupId: 'group-123', content: 'test' });
+    expect(result).toContain('memory');
+  });
+
+  it('returns error message when no memory', async () => {
+    const result = await memoryTool({ groupId: 'nonexistent', content: 'test' });
+    expect(result).toContain('No memory');
+  });
+
+  it('validates input schema', () => {
+    expect(() => {
+      memoryToolSchema.parse({ groupId: 'g1' });  // missing content
+    }).toThrow();
+  });
+});
+```
+
+## Naming conventions
+
+**Tool names:** kebab-case, verb-noun
+- ✓ `read-memory`, `create-task`, `list-actors`
+- ✗ `Memory`, `CREATE_TASK`, `list_actors` (inconsistent)
+
+**Tool descriptions:** one sentence, agent-perspective
+- ✓ "Read or write group memory" (what agent can do)
+- ✗ "Calls the memory API" (implementation detail)
+
+**Input fields:** snake_case, self-documenting
+- ✓ `groupId`, `taskTitle`, `memberEmails`
+- ✗ `gid`, `t`, `e` (unclear)
+
+## Tool categories
+
+| Category | Purpose | Example |
+|----------|---------|---------|
+| **Read** | Fetch data without side effects | `read-memory`, `list-tasks` |
+| **Create** | Add new entity | `create-task`, `create-group` |
+| **Update** | Modify existing entity | `update-memory`, `complete-task` |
+| **Delete** | Remove entity (rare) | `delete-task` |
+| **Execute** | Run an action with side effects | `send-message`, `approve-request` |
+
+## Anti-patterns
+
+❌ **Tool with no schema**
+```typescript
+// WRONG
+export const memoryTool = async (input: any) => { ... };
+```
+**Fix:** Define Zod schema, use typed input.
+
+❌ **Tool calls HTTP directly**
+```typescript
+// WRONG
+async function memoryTool(input: MemoryToolInput) {
+  const res = await fetch('/api/memory', { body: JSON.stringify(input) });
+  return res.text();
+}
+```
+**Fix:** Use SDK client: `const client = new SubstrateClient(); client.memory(...)`
+
+❌ **Tool without description**
+```typescript
+// WRONG
+const MEMORY_TOOL = {
+  name: 'memory',
+  inputSchema: memoryToolSchema,
+  execute: memoryTool,
+};
+```
+**Fix:** Add description for agent context.
+
+❌ **Tool that modifies global state**
+```typescript
+// WRONG
+let cachedMemory: any;
+export async function memoryTool(input: MemoryToolInput) {
+  cachedMemory = await client.memory(input.groupId);  // cache is a bug
+  return JSON.stringify(cachedMemory);
+}
+```
+**Fix:** No caching in tools. Each invocation is independent.
+
+## Composability rules
+
+**New tool composes SDK methods:**
+```typescript
+// GOOD — reuses existing SDK
+async function createTaskTool(input: CreateTaskInput) {
+  const client = new SubstrateClient();
+  const task = await client.createTask(input);  // SDK handles DB, validation
+  return JSON.stringify(task);
+}
+```
+
+**New tool creates novel capability:**
+```typescript
+// GOOD — when no SDK method exists yet
+async function analyzeMemoryTool(input: AnalyzeMemoryInput) {
+  const client = new SubstrateClient();
+  const memory = await client.memory(input.groupId);
+  // Analysis logic (not in SDK, because it's agent-specific)
+  const analysis = analyzeForSentiment(memory.content);
+  return JSON.stringify(analysis);
+}
+```
+
+## Error handling
+
+```typescript
+export async function memoryTool(input: MemoryToolInput): Promise<string> {
+  try {
+    const client = new SubstrateClient();
+    const memory = await client.memory(input.groupId);
+    
+    if (!memory) {
+      return 'No memory found for this group. Create one first.';
+    }
+    
+    return JSON.stringify(memory);
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      return `Invalid input: ${error.message}`;
+    }
+    if (error instanceof AuthenticationError) {
+      return 'You do not have permission to access this memory.';
+    }
+    throw error;  // Let parent handle unexpected errors
+  }
+}
+```
+
+**Rules:**
+- Validate input (Zod does this for you)
+- Return user-facing error messages (not stack traces)
+- Don't catch unexpected errors (let them propagate)
+- Never expose sensitive data (API keys, DB queries) in error messages
+
+## See also
+
+- `packages/mcp/CLAUDE.md` — MCP development guide
+- `packages/sdk/src/receivers.ts` — receiver registry (every tool calls a receiver)
+- `text/receiver-names-shipped-vs-spec.md` — which receivers exist
+- `@modelcontextprotocol/sdk` — MCP protocol docs

package/skills/oneie/SKILL.md

@@ -31,7 +31,7 @@ packages/templates/       — @oneie/templates (16 C-suite + marketing + service
 
 ## When to use
 
-- User asks about `oneie <verb>` — see `text/cli-reference-plan.md`
+- User asks about `oneie <verb>` — see `text/cli-reference.md`
 - User touches `packages/{sdk,mcp,templates}/` — see the per-package README
 - User wants to mint a token for an agent — route to `oneie launch <uid> --dry-run`, then handoff docs
 - User asks why buy/sell isn't in ONE — [launch-handoff.md](../../docs/launch-handoff.md) is the "why"
@@ -44,7 +44,7 @@ packages/templates/       — @oneie/templates (16 C-suite + marketing + service
 
 ## See Also
 
-- [cli-reference.md](../../text/cli-reference-plan.md)
+- [cli-reference.md](../../text/cli-reference.md)
 - [sdk-reference.md](../../text/sdk-reference-plan.md)
 - [mcp-tools.md](../../text/mcp-tools-plan.md)
 - [launch-handoff.md](../../docs/launch-handoff.md)

package/skills/promise-make/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: promise-make
+description: State terms + exactly one checkable proof — make a promise as a signal any actor can send. Use whenever an operator or agent commits to an outcome that should be held, watched, and settled — "promise that X", "commit to Y", "make a promise", "I'll deliver Z by the time the proof passes". Refuses a promise with no observable. Emits signal("promise:make", { slug, terms, proof }) and closes the loop with a receipt.
+---
+
+# promise-make — state terms + exactly one checkable proof
+
+**Purpose:** Turn a commitment into a promise Thing the world holds: frozen terms + ONE proof observable. One signal in, one `promised` state out, announced to everyone staked on the `promise` tag. The run-time face of what `/do`'s PROMISE stage does at build time.
+
+Source of truth: `one.ie/web/src/lib/resolvers/promises.ts` (receiver `promise:make`) · briefing: `text/promise-signals-agents-docs.md` · contract: `text/promise-signals.md`.
+
+---
+
+## HARD RULES
+
+- **Refuse a promise with no observable.** Empty or vague `proof` → do NOT emit the signal. The resolver rejects it anyway (`{ok:false, error:'a promise needs one observable'}`), but the refusal happens here first: ask for the one checkable thing, or dissolve the request with a stated reason. Never a silent return.
+- **Exactly ONE proof.** If the terms need two *independent* observables, that's two promises — split them into two slugs. But a **multi-part delivery is one promise with a schedule** (covenant clause 1, `text/promises.md`): enumerate the deliverables in `terms` like an agency SOW — every item the receiver gets, each with its own acceptance check in words — and make the ONE `proof` the observable that is true only when *every* line shipped (acceptance indivisible, no partial credit). Not enumerated = not promised. If no single observable can cover the whole schedule, the schedule is two promises.
+- **Terms freeze at the making.** The resolver inserts with `ON CONFLICT(slug) DO NOTHING` — a re-make of an existing slug changes nothing. Never "update" a promise's terms; make a new slug.
+- **Know which rail the proof settles on.** A shell-shaped proof (`test -f`, `grep`, `&&`, `;`, `$()`, backticks) is a BUILD-time observable — it settles at PROVE via `do-promise-settle.sh`, and `promise:settle` will refuse it. A runtime observable (a D1 row, a fetch, a signal receipt, a maker-attested verdict) settles via `promise:settle`. State which rail at make-time so the maker isn't surprised at settle-time.
+- **Identity is the session, never the body.** `maker` becomes `ctx.ownerSlug` server-side. Never pass an `actorId` in the payload expecting it to matter — it doesn't, by design (IDOR-safe).
+- **Closed loop.** Emit → read the response → `mark` mentally on `{ok:true}`, surface the error verbatim on `{ok:false}`. No silent returns.
+
+## When to use
+
+- An operator says "promise that…", "commit to…", "hold me to…"
+- An agent takes on work whose completion should route future work (reputation via `promise:<slug>→proof`)
+- A `/do` promise file's `world.skills` fan-out names a commitment that must exist as a run-time object
+- A deal needs an unpriced spine before money attaches (a priced promise rides the deal rail on top of this)
+
+**Not for:** settling (that's `promise-settle`), reading (`promise:get`, public, no skill needed), or build-time promise files in `text/` (that's the `docs` skill + `template-feature.md`).
+
+## The signal (exact shape)
+
+```ts
+signal("promise:make", {
+  slug:  "ship-weekly-digest",         // ^[a-zA-Z0-9_:/-]{1,128}$ — the promise's name, forever
+  terms: "A digest email goes to every subscriber each week.",  // frozen prose, hashed sha256
+  proof: "promise:get shows a broadcast_sends row for the current week"  // ONE observable
+})
+```
+
+Response on success:
+
+```json
+{ "ok": true, "slug": "ship-weekly-digest", "state": "promised", "terms_hash": "<sha256 of terms>" }
+```
+
+What the resolver does (so you don't re-do it): inserts the D1 `promises` row (state `promised`, strength 0, resistance 0), fire-and-forgets a TypeDB `thing` with `thing-type "promise"`, and fire-and-forgets `world:announce` with tags `["promise", "made", slug]` — every subscriber staked on those tags gets it in their inbox Space.
+
+## Process
+
+1. **Extract the terms.** One sentence of what will be true. If the ask is fuzzy, tighten it with the maker before emitting — frozen fuzz is worse than no promise.
+2. **Extract the ONE proof.** Ask: "what single check settles this?" If the answer is "well, A and B" → two promises. If the answer is "you'll know it when you see it" → refuse, with the reason stated.
+3. **Classify the proof rail.** Shell-shaped → tell the maker it settles at PROVE via CLI, not via `promise:settle`. Runtime-checkable → `promise:settle` works.
+4. **Pick the slug.** Kebab, stable, matches `^[a-zA-Z0-9_:/-]{1,128}$`. It becomes the path endpoint `promise:<slug>→proof` — choose like it's permanent, because it is.
+5. **Emit** `signal("promise:make", { slug, terms, proof })` — authenticated (the session's `ctx.ownerSlug` becomes the maker who alone may settle).
+6. **Close the loop.** `{ok:true, state:"promised"}` → report slug + terms_hash back to the maker. `{ok:false}` → surface the error verbatim (`slug + terms required` · `invalid slug` · `a promise needs one observable` · `forbidden: authentication required`) and fix the input. If the slug already existed, `promise:get` it and tell the maker the prior terms stand — nothing was overwritten.
+
+## Worked example
+
+Operator: *"Promise the client their movers landing page will be live."*
+
+1. Terms: "The elitemoversca landing page is live at its production URL."
+2. Proof (one, runtime-checkable): "GET https://elitemoversca.com returns 200 with the hero headline present."
+3. Rail: runtime observable → settles via `promise:settle`. Good.
+4. Slug: `elitemoversca-landing-live`.
+5. Emit:
+   ```ts
+   signal("promise:make", {
+     slug:  "elitemoversca-landing-live",
+     terms: "The elitemoversca landing page is live at its production URL.",
+     proof: "GET https://elitemoversca.com returns 200 with the hero headline present"
+   })
+   ```
+6. Response `{ ok: true, slug: "elitemoversca-landing-live", state: "promised", terms_hash: "9f2c…" }` → report: "Promised. Terms frozen (hash 9f2c…). Settles kept when the page answers 200 — run `promise-settle` when it's live. Everyone staked on the `promise` tag was announced."
+
+Counter-example (must refuse): *"Promise we'll make the client happy."* → No observable. Reply: "A promise needs one checkable proof — what single thing, when true, means this is kept? (e.g. a signed renewal, a ≥ 4-star review row)." Do not emit.
+
+## Quality checks
+
+- [ ] Exactly one proof observable, stated in the payload
+- [ ] Proof rail classified (shell → PROVE/CLI · runtime → `promise:settle`) and told to the maker
+- [ ] Slug matches the regex and won't need renaming
+- [ ] Response read and reported — `ok:true` receipt or verbatim error, never silence
+- [ ] No body-field identity games — session auth only
+
+## Cross-references
+
+- Settle side: `.claude/skills/promise-settle/SKILL.md`
+- Receiver source: `one.ie/web/src/lib/resolvers/promises.ts` (`make`, lines 36–67)
+- Agent briefing (payloads, errors, recovery): `text/promise-signals-agents-docs.md`
+- The contract this skill serves: `text/promise-signals.md` (`world.skills` names this skill)
+- Build-time twin: `/do` PROMISE stage + `text/template-feature.md` (contract: block)

package/skills/promise-settle/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: promise-settle
+description: Run the proof, move the path, announce the verdict — settle a promise and never return silently. Use whenever a promise's proof can now be checked — "settle the promise", "did we keep it", "the work is done, close the promise", or when a watched promise's observable flips. Emits signal("promise:settle", { slug, kept?, composite? }); kept → mark, broken → warn, no observable → dissolve. Refuses shell-shaped proofs (those settle at PROVE via do-promise-settle.sh).
+---
+
+# promise-settle — run the proof, move the path, announce the verdict
+
+**Purpose:** Close a promise's loop. Check the one observable the promise froze at make-time, then emit the verdict: kept → `mark` on `promise:<slug>→proof` (strength climbs, routing follows), broken → `warn` (resistance climbs, the path decays honestly), no observable → dissolve with a receipt. There is no third outcome and no silent one.
+
+Source of truth: `one.ie/web/src/lib/resolvers/promises.ts` (receiver `promise:settle`) · briefing: `text/promise-signals-agents-docs.md` · contract: `text/promise-signals.md`.
+
+---
+
+## HARD RULES
+
+- **Never return silently.** Every settle attempt ends in exactly one of: `settled-kept` (mark) · `settled-broken` (warn) · `dissolved` (no observable) · a surfaced refusal (`forbidden` / `already settled` / `shell proof settles at PROVE via CLI` / `not_found`). Report which one, verbatim.
+- **Run the proof BEFORE emitting.** The resolver does not execute proofs — the verdict is the maker's authorized assertion (`kept: true|false`). So this skill IS the proof-runner: actually check the observable (fetch the URL, read the row, `promise:get` the dependent state) and set `kept` from the real result. Emitting `kept:true` without checking is declaring green — green is earned, never declared.
+- **`kept` defaults to true server-side** (`data.kept !== false`). Therefore: to settle broken you MUST pass `kept: false` explicitly. Omitting it after a failed check would lie. Pass the boolean explicitly both ways.
+- **Shell-shaped proofs never settle here.** `test -f` / `grep` / `&&` / `;` / `$()` / backticks in the proof → the resolver refuses (`shell proof settles at PROVE via CLI`). Route those to `.claude/scripts/do-promise-settle.sh <slug>` at PROVE instead — same verdict table, CLI rail.
+- **Only the maker settles.** The resolver compares the persisted `maker` to `ctx.ownerSlug` — session identity only, a body `actorId` is never checked. If you are not the maker, do not attempt; `promise:get` to learn who is.
+- **The ratchet is final.** A terminal promise (`settled-kept` / `settled-broken` / `dissolved`) never re-settles — the resolver returns `already settled`. Do not retry a terminal verdict; report the existing state via `promise:get`.
+- **Disputed → human, not warn.** If the verdict is contested, `human:ask` the oracle before a `warn` lands on someone's path (the standing workflow's rule — `text/promise-signals.md` world.workflow).
+
+## When to use
+
+- The work behind a promise is done and its observable can be checked now
+- A watched promise's `world:do-event` traffic says the proof is worth re-running
+- An operator asks "did we keep the promise?" / "close out the promise"
+- A promise turns out to have no real observable → settle it *dissolved*, with the receipt stated
+
+**Not for:** making promises (`promise-make`), reading state (`promise:get` — public, no skill needed), or build-cycle promises with shell proofs (those are `do-promise-settle.sh`'s at `/close`).
+
+## The signal (exact shape)
+
+```ts
+// 1. Read the promise first — terms, proof, current state
+signal("promise:get", { slug: "elitemoversca-landing-live" })
+// → { ok: true, slug, terms, state: "promised", strength: 0, resistance: 0 }
+
+// 2. RUN the proof yourself (fetch / D1 read / dependent promise:get) → verdict
+
+// 3. Emit the verdict — maker only, kept explicit, composite optional
+signal("promise:settle", {
+  slug: "elitemoversca-landing-live",
+  kept: true,          // EXPLICIT — from the check you just ran; false to settle broken
+  composite: 0.78      // optional rubric score; kept strength += composite×5 (else +1)
+})
+```
+
+Responses (one of, always):
+
+```json
+{ "ok": true,  "slug": "…", "state": "settled-kept",   "strength": 3.9 }
+{ "ok": true,  "slug": "…", "state": "settled-broken", "resistance": 1 }
+{ "ok": true,  "slug": "…", "state": "dissolved" }
+{ "ok": false, "error": "forbidden: only the maker may settle" }
+{ "ok": false, "error": "already settled" }
+{ "ok": false, "error": "shell proof settles at PROVE via CLI" }
+{ "ok": false, "error": "not_found" }
+```
+
+What the resolver does on each verdict: kept → `mark(env, "promise:<slug>", "proof", composite×5 or 1)` + state `settled-kept` + `world:announce` tags `["promise","settlement",slug]` · broken → `warn(…, 1)` + state `settled-broken` + same announce · empty proof → state `dissolved` (belt-and-braces — `promise:make` refuses empty proofs, but the closed-loop leg exists so no path is silent).
+
+## Process
+
+1. **`promise:get` the slug.** Confirm state is `promised` (terminal → report final state, stop) and read the frozen `proof` text.
+2. **Classify the proof.** Shell-shaped → hand off: `bash .claude/scripts/do-promise-settle.sh <slug>` (or tell the operator that's the rail) and stop. Runtime observable → continue.
+3. **Run the observable for real.** Fetch the URL, query the row, check the signal receipt — whatever the proof names. Record the evidence (status code, row id, output line).
+4. **Confirm you are the maker.** Your session slug must equal the persisted `maker`. Not you → report who may settle; do not spoof.
+5. **Emit** `signal("promise:settle", { slug, kept: <checked verdict>, composite? })` — `composite` only if you hold a real rubric score.
+6. **Announce + close the loop.** The resolver already fans `world:announce` to everyone staked on `[promise, settlement, <slug>]` — your job is the human-readable verdict: state (`settled-kept` / `settled-broken` / `dissolved`), the path moved (`promise:<slug>→proof` strength/resistance delta), and the evidence from step 3. On `{ok:false}` report the error verbatim and the recovery (see table in `text/promise-signals-agents-docs.md § Errors → recovery`).
+
+## Worked example
+
+Promise `elitemoversca-landing-live` — proof: "GET https://elitemoversca.com returns 200 with the hero headline present."
+
+1. `signal("promise:get", { slug: "elitemoversca-landing-live" })` → `state: "promised"`. Proceed.
+2. Proof is a runtime fetch — no shell shapes. This rail.
+3. Run it: `curl -s -o /dev/null -w '%{http_code}' https://elitemoversca.com` → `200`; page text contains the hero headline. Evidence: HTTP 200 + headline match. Verdict: kept.
+4. Session slug = persisted maker. Authorized.
+5. `signal("promise:settle", { slug: "elitemoversca-landing-live", kept: true })`
+6. Response `{ ok: true, state: "settled-kept", strength: 1 }` → report: "Settled **kept**. Proof: 200 + hero headline live. Path `promise:elitemoversca-landing-live→proof` strength 0 → 1; verdict announced to everyone staked on [promise, settlement]. The ranker now favors this maker for the next matching work."
+
+Broken variant: the curl returns `522`. Then step 5 is `{ slug, kept: false }` → `{ ok: true, state: "settled-broken", resistance: 1 }` → report the warn and the evidence (522), not a euphemism. The path decays honestly — that is the feature.
+
+## Quality checks
+
+- [ ] Proof actually run, evidence recorded — verdict never asserted unchecked
+- [ ] `kept` passed explicitly (true AND false) — never rely on the server default
+- [ ] Shell-shaped proof routed to `do-promise-settle.sh`, not forced through the signal
+- [ ] Exactly one closing outcome reported, verbatim — kept/broken/dissolved/refusal
+- [ ] Terminal promise not retried — ratchet respected
+- [ ] Disputed verdicts pause for `human:ask` before a warn lands
+
+## Cross-references
+
+- Make side: `.claude/skills/promise-make/SKILL.md`
+- Receiver source: `one.ie/web/src/lib/resolvers/promises.ts` (`settle`, lines 82–137 — IDOR guard, ratchet, shell-proof refusal, verdict table)
+- Agent briefing (payloads, errors, recovery): `text/promise-signals-agents-docs.md`
+- The contract this skill serves: `text/promise-signals.md` (`world.skills` names this skill; `world.tracking` names the mark/warn wires)
+- Build-time twin: `.claude/scripts/do-promise-settle.sh` at `/close` — same verdict table, CLI rail