coaiajs 0.5.0 → 0.5.1

package/skills/coaiajs/references/reading-the-store.md

@@ -0,0 +1,66 @@
+# Reading the Store
+
+`coaiajs` owns the writes. Anything that renders a chart store — a dashboard, a report, a
+Twine promotion, another agent — needs the store's shape, and re-deriving that shape by
+hand is where readers quietly go wrong.
+
+It is not a style problem. When a hand-rolled reader drifts from the writer, it does not
+break: it renders **less**. A chart holding real work looks identical to an empty one.
+
+## Use the contract
+
+```typescript
+import { parseStore, getWork, getChartEntity } from 'coaiajs/narrative/contract';
+import { readFile } from 'node:fs/promises';
+
+const store = parseStore(await readFile('./memory.jsonl', 'utf8'));
+const chart = getChartEntity(store, 'chart_1757200000000');
+const work  = getWork(store, 'chart_1757200000000');
+```
+
+The contract keeps three rules:
+
+1. **Zero I/O.** No `fs`, no `process`, no network. The caller owns reading; this owns
+   shape.
+2. **Never imports the server.** The package root is safe to import, but the contract
+   lives behind its own subpath so a renderer pulls nothing it does not need.
+3. **Tolerant by construction, honest about what it skipped.** One unparseable line is
+   skipped and counted in `skipped`, where `parseJsonlMemory` — correctly, for a writer —
+   throws.
+
+Classification is **not** defined in the contract. `jsonl-records.ts` holds the single
+definition, and both the writer and the contract import it. The first draft of the
+contract re-implemented classification by hand and a review measured it returning 73
+entities where the writer returned 76: it dropped the legacy `type:"narrative_beat"`
+dialect and reported the losses as corruption. Duplication relocated rather than removed.
+
+## What it gives you
+
+| Export | Use |
+|---|---|
+| `parseStore(raw)` | `{ entities: Map, relations: [], skipped: number }` |
+| `ENTITY_TYPES` | Every entity kind the writer writes |
+| `MMOT_PHASES`, `CREATING_PHASES` | The vocabularies, including `full` |
+| `chartEntityName`, `desiredOutcomeName`, `currentRealityName` | The naming scheme, once |
+| `getChartEntity`, `getDesiredOutcome`, `getCurrentReality` | Chart parts by id |
+| `getFlatActionSteps`, `getChildCharts`, `getWork` | The two shapes work takes, counted once |
+| `getMmotBeats`, `getMmotEvaluations` | The MMOT trail |
+| `storeRevision`, `revisionOf` | Cheap change detection between reads |
+
+## What `skipped` cannot tell you
+
+Writes are temp-file-plus-rename, so a reader should never see a torn file and
+`skipped > 0` genuinely suggests a foreign or damaged line.
+
+But a store truncated by something *other* than this package can still be a syntactically
+perfect prefix: every whole line parses, and the result is simply a smaller store with
+`skipped === 0`. No reader can detect that from content alone. If it matters, compare
+entity counts across reads.
+
+## Writing from outside
+
+If you must write, go through `KnowledgeGraphManager` or
+`readJsonlMemoryFile` / `writeJsonlMemoryFile`. They preserve fields this package does not
+model — another consumer's metadata survives — and they write atomically. A bare
+`writeFile` over the store truncates first, and a reader landing in that window gets a
+valid partial store.

package/skills/coaiajs/references/structural-tension-charting.md

@@ -0,0 +1,71 @@
+# Structural Tension Charting
+
+A chart has three core parts:
+
+1. **Desired Outcome** — what the user wants to create.
+2. **Current Reality** — the honest present state in relation to that outcome.
+3. **Action Steps** — strategic secondary choices that support the primary choice.
+
+Action steps are not independent checklist items. They must make sense together as an
+overview strategy. Test them with: "If these steps were taken, would the desired outcome
+likely be created?"
+
+Each action step is a telescoped chart. Its title becomes the desired outcome of the child
+chart, and it needs its own current reality. Never use "ready to begin" as that reality.
+
+Good current reality examples:
+
+- "No Django experience."
+- "Package builds locally, publish dry-run not inspected."
+- "Budget: $5000."
+- "Completed models section, struggling with views."
+
+Poor current reality examples:
+
+- "Ready to begin."
+- "Need to retrieve the notes."
+- "Excited to start."
+- "Prepared to tackle the action step."
+
+## How a chart is laid out in the store
+
+For a chart with id `chart_1757200000000`:
+
+| Entity | `entityType` |
+|---|---|
+| `chart_1757200000000_chart` | `structural_tension_chart` |
+| `chart_1757200000000_desired_outcome` | `desired_outcome` |
+| `chart_1757200000000_current_reality` | `current_reality` |
+| `chart_1757200000000_action_1` … `_action_N` | `action_step` |
+
+A telescoped child chart is a full chart of its own, carrying `metadata.parentChart` and,
+when it grew out of a specific step, `metadata.parentActionStep`.
+
+## The two shapes work takes
+
+This is the single most common source of a wrong reading. A chart holds its work in **two**
+shapes:
+
+1. `action_step` entities that live on the chart itself.
+2. Telescoped child charts, which is what `add_action_step` produces.
+
+Counting or rendering only one of them under-reports. A chart built entirely with
+`add_action_step` used to report `0/0` progress while holding real work, and a chart
+holding eight of its own steps used to render as "(No action steps yet)".
+
+A child telescoped out of one of the chart's own steps is that same result seen closer up.
+It counts **once**, through the step — not twice.
+
+`getChartProgress`, `listActiveCharts`, `updateChartDueDate`, and
+`coaiajs/narrative/contract`'s `getWork()` all apply that rule. Prefer them over walking
+the graph by hand.
+
+## Moving a date
+
+Use `update_chart_due_date`. It moves the chart and its desired outcome together, records
+the move as an observation on the chart, and reports how many open steps still fall after
+the new date. Pass `redistributeActionSteps: true` to spread those open steps evenly
+between now and the new date.
+
+Do not hand-edit the JSONL to change a date. Several MCP instances can point at one store
+with no lock; a hand-edit races every one of them.

package/skills/coaiajs/references/wampum-belts.md

@@ -0,0 +1,72 @@
+# Wampum Belts
+
+A Wampum Belt is a non-linear mnemonic grid that runs in **parallel** with the linear
+narrative beats. Beats are a sequence; a belt is a surface where position itself carries
+meaning.
+
+Reach for a belt when the order of things is not a line: when a reading depends on where
+it sits relative to its neighbours, when several perspectives on one bead are all true,
+or when a commitment needs a witness rather than a timestamp.
+
+## Shape
+
+A belt has `rows` × `cols` positions. Each position holds at most one bead, written once.
+
+A bead carries:
+
+| Field | Meaning |
+|---|---|
+| `mnemonic` | Short anchor phrase |
+| `color` | `white`, `purple`, `black`, or `mixed` |
+| `position` | `{ row, col }`, zero-indexed, inside the grid |
+| `reading` | The canonical meaning |
+| `relationalReadings` | Optional per-perspective readings, keyed `left` / `center` / `right` / `row:N` / `col:N` |
+| `ceremonyLink` | Optional tie to a chart or a beat |
+| `observations` | Free notes |
+
+`read_wampum_belt` with a `position` resolves the reading for that position: it prefers
+`col:N`, then `row:N`, then the positional label (`left` / `center` / `right`), and falls
+back to the canonical `reading`.
+
+## Ceremony links
+
+`ceremonyLink.ceremonyType` is one of `commitment`, `accountability`, `witness`, or
+`renewal`. With `chartId` it writes a `wampum_holds_accountable` edge to that chart; with
+`beatName` it writes a `wampum_witnesses` edge to that beat.
+
+**The edge is subject to the bead, not the belt.** A relation's identity in the store is
+`(from, to, relationType)`. With the belt as subject, a second bead linking the same chart
+under a different `ceremonyType` collided on that triple: the existence check matched, the
+edge was skipped, and the bead kept a ceremony type the graph had no edge for. Silent
+discard, with the bead's own record disagreeing with the graph and nothing saying so.
+
+A bead id is `bead_<beltId>_<row>_<col>` and a position is written once, so
+`(bead, target, relationType)` is unique by construction and every ceremony link survives
+carrying its own type.
+
+## Tools
+
+```json
+{ "tool": "create_wampum_belt",
+  "arguments": { "title": "Release ceremony", "purpose": "Hold what each step promised", "rows": 2, "cols": 3 } }
+```
+
+```json
+{ "tool": "add_wampum_bead",
+  "arguments": {
+    "beltId": "belt_1757200000000",
+    "mnemonic": "witnessed",
+    "color": "purple",
+    "position": { "row": 0, "col": 1 },
+    "reading": "The publish was seen by someone other than its author",
+    "relationalReadings": { "center": "seen from the middle of the belt" },
+    "ceremonyLink": { "ceremonyType": "witness", "chartId": "chart_1757200000000" }
+  } }
+```
+
+```json
+{ "tool": "read_wampum_belt", "arguments": { "beltId": "belt_1757200000000" } }
+```
+
+Out-of-bounds positions, occupied positions, and non-integer grids are refused with the
+reason named.