← Files BodhiKitARCHIVED FILE

references/knowledge/state-schema.md

18.1 KB · Nov 21, 2026 · 12:41 UTC

↓ Download file

<!-- Generated from skills/state-schema/SKILL.md; edit the canonical source. -->

# State Schema — Canonical Shape of BodhiKit Tracking Files

This KB is the field-level reference. **Routine skill fires do NOT load it** — the operational surface (discovery, the `bodhi-state` write path and subcommand table, session-type vocabulary, gate/mastery semantics) lives in the `state-ops` KB, and `bodhi-state` owns every JSON mutation, so most sessions never need field shapes at all.

Load this KB only when:

- performing a **manual carve-out** — `learn` skill project scaffolding (the `.bodhi/` skeletons and the parent `.bodhi-profile.json`), the `currentBloomLevel` / `initialBloomLevel` maps;
- running the **script-unavailable fallback** (see *Fallback discipline* below);
- you are `housekeep` skill (rotation and migration);
- you are authoring or reviewing plugin files.

If a field is not listed here, do not add it. If a new field is genuinely needed, update this KB first, then `scripts/bodhi-state`, then the skills that touch it.

See also: `spaced-repetition` KB (intervals and update rules), `state-lifecycle` KB (why the surfaces are shaped this way, and rotation; `housekeep` skill only), `state-migration` KB (version transforms).

## Fallback Discipline (script unavailable, or a declared manual carve-out)

Only after BOTH the `<BODHIKIT_PLUGIN_ROOT>` path and the package-relative lookup come up empty (per the `state-ops` KB), say so plainly, then perform the minimal write by hand following this KB's shapes — Read the file, mutate the parsed JSON in place preserving every unknown field, fill the three v3 per-concept defaults on any concept missing them and set `version: 3` (read-tolerance), Write it back, re-read to verify. Never re-serialize from a schema template.

The same read → mutate-in-place → write → verify discipline applies to the declared manual carve-outs even when the script is available.

## File Shapes

### `learningWithBodhi/<project>/.bodhi/state.json`

Slim. No long narrative fields — session narrative lives in `progress.md`.

```json
{
  "version": 2,
  "projectName": "string",
  "topic": "string",
  "createdAt": "ISO-8601",
  "lastSessionAt": "ISO-8601",
  "totalSessions": 0,
  "sessionDates": ["YYYY-MM-DD"],
  "currentStreak": 0,
  "currentPhase": "string",
  "currentModule": "string",
  "previousModule": "string",
  "currentModuleIndex": 0,
  "lastActivity": "string",
  "initialBloomLevel": { "<sub-topic>": 0 },
  "currentBloomLevel": { "<sub-topic>": 0 },
  "overallCompletion": 0
}
```

- `currentStreak`: consecutive days. Reset to 1 if `sessionDates` gap exceeds 1 day. Maintained by `bodhi-state touch-state`.
- `previousModule`: set automatically by `touch-state --module` when the module advances; read by `gate-check`.
- `initialBloomLevel` / `currentBloomLevel`: a **manual carve-out** (`state-ops` KB *Update Rules*); edit via the Fallback discipline above.
- `lastActivity`: one short sentence (≤120 chars) used by `progress` skill with request context `quick` and `continue` skill. Anything longer belongs in `progress.md`.
- `evidenceKind` / `moduleEvidenceKinds` (optional; never in a scaffolded skeleton): `code`, `problems`, `writing` or `performed`, for the project and per module, keyed by the normalized module name (`Module N.M —` prefix dropped, spacing collapsed, case folded). Effective kind: the module's, else the project's, else `code` (no kind = a code project). Written only by `set-evidence-kind`; a change keeps every review.
- **No `lastSessionSummary` / `bloomResetNote` in v2** — migrated to `progress.md`.

### `learningWithBodhi/<project>/.bodhi/progress.md`

Live narrative document. Latest session in full, then a "Summary of earlier sessions" block with pointers.

```markdown
# Progress Log

## <YYYY-MM-DD> — Session <N> (<short label>)

**Duration:** <approx>
**Activities:**
- <bullets>

**Outcomes:**
- <bullets>

**Bloom adjustments:**
- <area>: <from> → <to>

**Next:** <what the next session should open with>

---

## Summary of earlier sessions

- **<YYYY-MM-DD> — <one-line headline>**
  <optional 1-3 more lines>
  → `archive/<filename>.md`
```

### `learningWithBodhi/<project>/.bodhi/assessments/latest.md`

Most recent assessment in full, then a "Summary of earlier assessments" block with `→ archive/<filename>.md` pointers. Multi-stack projects may have multiple assessments per phase; each becomes its own archive entry.

### `learningWithBodhi/<project>/.bodhi/plan/`

Sectional. Generated at plan creation; rewritten only by `plan` skill with request context `regenerate`.

`plan/README.md`: arc overview — current phase pointer, target arc, pace, bulleted phase list with `→ phase-<N>.md` pointers.

`plan/phase-{N}.md`: per-phase goals, duration, success criteria, then `### Module <N>.<M> — <name>` sections with concepts, exercises, success markers. From Module 2 onward each module section carries a `**Prerequisites for next module:**` line naming the concepts the next module builds on, or `none` (feeds `gate-check --prereqs`). `bodhi-state syllabus` reads the headings in phase order and, inside each section, the optional `**Status:** skipped|completed`, `**Target Bloom's:**`, `**Concepts:**` and `**Key terms:**` lines; `spaced-review.json[].module` joins on the heading name (case and spacing ignored).

### `learningWithBodhi/<project>/.bodhi/spaced-review.json`

Whole JSON; written exclusively through `bodhi-state`. `housekeep` skill does not rotate this file.

```json
{
  "version": 3,
  "lastReviewCheck": "ISO-8601",
  "concepts": [
    {
      "name": "string",
      "module": "string",
      "introduced": "YYYY-MM-DD",
      "box": 1,
      "nextReview": "YYYY-MM-DD",
      "lastReviewed": "YYYY-MM-DD",
      "question": "string",
      "lastResult": "string",
      "bloomLevel": 0,
      "feynmanPassed": false,
      "feynmanPassedAt": "YYYY-MM-DD",
      "consecutiveCorrectAtL4Plus": 0,
      "reviewHistory": [
        { "date": "YYYY-MM-DD", "result": "correct|incorrect|partial", "bloomLevel": 3, "boxBefore": 1, "confidence": "sure|mostly|guessing", "source": "string" }
      ]
    }
  ],
  "sessionHistory": [
    { "date": "YYYY-MM-DD", "type": "spaced-review", "conceptsReviewed": 0, "passes": 0, "misses": 0 }
  ]
}
```

- `box`: integer 1–5; intervals and update rules in the `spaced-repetition` KB, implemented by `record-review`.
- `parked` (optional, 1.16.0): `true` = the learner has consciously taken the concept out of review rotation (`bodhi-state park`, surfaced as `forget` skill with request context `--park`); `nextReview` is `null` while parked. Parked concepts leave the due/retention surfaces (reported as counts — `parkedCount` in `due`, `parked` in `mastery`/`snapshot` — never silently) but keep box, Bloom, Feynman, and mastery standing. `park --resume` re-enters rotation (review tomorrow, box preserved). Parking is scheduling, never an outcome.
- `reviewHistory[].retry` (optional, 1.11.1): `true` marks a successive-relearning rep — recorded evidence that did NOT move the box. `reviewHistory[].note` (optional): short free-text annotation (e.g. "learner-initiated demote"). The script caps `reviewHistory` at the most recent 100 entries per concept; older entries roll into a `reviewHistoryArchived` counter and an `archivedSummary` `{ "through": <last archived date>, "appliedEvidence": N, "evidenceAt3Plus": N, "exposure": "taught"|"built", "lastMiss": <date> }` (the last two only when the slice proves it; `built` only from observed work), plus `appliedInspected` / `appliedReported` / `builtBy` for the other bases, only when non-zero, so a later kind change still reads them, and the since-last-miss counts, the exposure floor and `retention`'s first retained gap survive the cut — a truncation never changes what a reader says happened.
- `reviewHistory[].confidence` (optional, 1.11.0): the learner's pre-reveal confidence tag — `sure` / `mostly` / `guessing`, collected by `quiz` skill and `reflect` skill BEFORE the answer is judged. `bodhi-state calibration` aggregates these into overconfidence/underconfidence rates.
- `reviewHistory[].source` (optional): which skill produced the review.
- `reviewHistory[].applied` (optional, 1.20.0): `true` = this outcome was demonstrated in work the tutor read (code that ran, or a written application on a non-code topic: `blooms-taxonomy` KB *Applied Evidence*), not in an explanation or a quiz answer. Written by `record-review --applied`. `bodhi-state` derives `appliedEvidence` (correct + applied entries since the most recent `incorrect`, the same reset as the apply-rung count, whose basis the concept's kind admits) on every read surface; nothing stores it.
- `reviewHistory[].appliedBasis` (optional, beside `applied: true`): `inspected` (a photo or transcript the tutor examined) or `reported` (the learner's word); absent = `observed` (the tutor read the work in the project), as on every code entry. Admitted only while the effective kind is `performed`: `record-review` refuses them elsewhere, readers ignore them elsewhere.
- `reviewHistory[].evidence` (optional): project-relative path of the applied work (`--evidence`). Required for `observed` off `code`: an existing file in the project, beside the exercise's key (`answers.md` / `criteria.md`), and not the key, a `README.md` or under `.bodhi/`.
- `reviewHistory[].selfReport` (optional): `true` on the entry `forget` skill writes — a learner-initiated reset, not a tested outcome. It still resets the box and the since-last-miss counts, but `retention` excludes it (`selfReportsExcluded`); pre-field entries carry `note: "learner-initiated demote"` and are excluded by that note.
- `reviewHistory[].boxBefore` (optional, 1.11.3): the box the concept occupied when this review was answered — the box whose interval scheduled it. Written by `record-review` on every new entry; absent on older entries (readers tolerate absence; `retention` reports how many legacy entries lack it).
- `reviewHistory[].result` is a closed vocabulary: `correct` / `incorrect` / `partial` — enforced by `record-review`, checked by `verify` (1.12.1). A due concept the session never reached gets a **deferral entry** instead: `{ "date": "YYYY-MM-DD", "deferred": true, "days": N, "note": "..." }` — no `result`, written by `defer`. Deferrals are excluded from `retention` (they are scheduling events, not retrieval evidence). Invented values (`skipped`) are repaired by `normalize`.
- `beforeLastReview` (optional): `box`, `nextReview`, `consecutiveCorrectAtL4Plus`, `bloomLevel`, `lastReviewed` and `lastResult` as they were before the latest graded review, with its `date`. Overwritten by `record-review`; read only by `revise-review`.
- `revisedReviews` (optional): entries `revise-review` took out of `reviewHistory` (today's latest, graded wrong), each as recorded plus `revisedOn` and `revisedReason`. No reader counts them; the replacing entry carries `revision: true`.
- `sessionHistory` is an append-only audit trail. `evaluate` skill reads it; routine skills do not. The `type` field is a closed vocabulary enforced in code by `record-session` — the canonical table lives in the `state-ops` KB.

**Per-concept Bloom + Feynman fields (v3):**

- `bloomLevel`: integer 0–6. `0` = uninitialized (no v3 writer has classified it). Ratchets up only — `record-review` takes `max(current, tested-bloom)` on a correct answer and never demotes; even `forget` skill demotes the box, not the Bloom classification. The one exception: `revise-review` restores the level held before the wrong entry.
- `feynmanPassed`: boolean. Set by `set-feynman` on a genuine explain-back (`teach` skill). Set, never unset.
- `feynmanPassedAt` (optional, 1.23.0): date of the latest passing explain-back (`set-feynman`). Mastery counts it only if **after** the last miss (latest `incorrect`, live or `archivedSummary.lastMiss`; `forget` skill included) — not the same day; an undated flag counts only with no miss on record. Derived as `feynmanCurrent`.
- `consecutiveCorrectAtL4Plus`: incremented on correct at tested-bloom ≥ 4 — only on a due review, the rule that moves the box (`spaced-repetition` KB) — early L4 corrects add nothing; reset to 0 on any incorrect, any partial, and on `forget` skill (1.11.2: "3 consecutive correct" means uninterrupted corrects). A correct at a lower tested level leaves the counter untouched. `--retry` reps never touch it.

These fields, plus one `applied` correct since the last miss, feed the mastery formula (`state-ops` KB *Mastery*). **Legacy fallthrough:** `bloomLevel: 0` means no v3 writer has classified the concept, regardless of `lastReviewed`; the gate and `progress` skill rules for it are the `state-ops` KB *Legacy display rule*.

### `learningWithBodhi/<project>/.bodhi/assessment-history.json`

Structured assessment data for `evaluate` skill and `progress` skill. Append-only; never edit past entries.

```json
{
  "version": 1,
  "entries": [
    {
      "date": "YYYY-MM-DD",
      "trigger": "learn-phase2 | assess | evaluate | plan-regenerate",
      "topic": "string",
      "subTopics": [
        { "name": "string", "bloomLevel": 0, "confidence": "high|medium|low", "evidence": "string" }
      ],
      "overallNote": "string",
      "predictionDelta": {
        "predictedBiggestGrowth": "string",
        "measuredBiggestGrowth": "string",
        "predictedBiggestGap": "string",
        "measuredBiggestGap": "string",
        "perTopicBloomPredictions": [ { "name": "string", "predicted": 0, "measured": 0 } ],
        "calibrationNote": "string"
      }
    }
  ]
}
```

- Skills that run assessments (`learn` skill Phase 2, `assess` skill, `evaluate` skill Phase 2, `plan` skill with request context `regenerate`) MUST append an entry here via `bodhi-state record-assessment` (prose version goes to `assessments/latest.md`).
- `predictionDelta` is populated by `evaluate` skill Phase 2.5 (predict-before-reveal); absent elsewhere. See `metacognition` KB.

### `learningWithBodhi/<project>/.bodhi/resources.md`

Markdown log, dated or status-grouped sections. Small; not housekept.

### `learningWithBodhi/<project>`teach` skill-backs/`

Capstone artifacts from `teach-back` skill, at the project root (learner-authored, not internal state). Each post: `teach-backs/<YYYY-MM-DD>-<slug>.md` with a header (thesis, reader, why-it-matters), the learner's prose, and a closing status block (`Status: draft | published | personal-notes`, `Decided:`, `Masters consulted:`, `Post-Phase-6 revisions:`). Only `teach-back` skill writes here. Not housekept.

### `learningWithBodhi/.bodhi-profile.json`

Cross-project learner profile (v2 split layout: this file holds top-level fields; the project list lives in `.bodhi-profile.projects.json`).

```json
{
  "version": 2,
  "careerGoal": "string",
  "whyLearning": "string",
  "priorExperience": "string",
  "learningStyle": "string",
  "overallBloomLevels": { "<area>": 0 },
  "cumulativeStats": {
    "totalSessions": 0,
    "totalExercises": 0,
    "totalConceptsLearned": 0,
    "totalMilestonesReached": 0,
    "totalProjects": 0,
    "teachBacksWritten": 0,
    "teachBacksPublished": 0
  },
  "patterns": {
    "persistentChallenges": ["<topic>"],
    "consistentStrengths": ["<topic>"]
  },
  "learnerBackground": {
    "domains": ["<string>"],
    "analogyHistory": [
      { "concept": "string", "domain": "string", "landed": true, "date": "YYYY-MM-DD" }
    ]
  },
  "lastUpdated": "ISO-8601"
}
```

- `cumulativeStats` counters are incremented via `bodhi-state bump-profile` (the skill decides WHEN — e.g. `practice` skill bumps `totalExercises` on each completed exercise). Two counters the script keeps itself, so no skill calls them: `totalSessions`, bumped by `touch-state` on the first touch of a new day, and `totalConceptsLearned`, bumped by `record-review` on the write that moves a concept's `bloomLevel` from below 3 to 3 or above (`bump-profile` refuses it; with no profile the count is skipped).
- `patterns.persistentChallenges` / `patterns.consistentStrengths` are appended by `bodhi-state profile-update-patterns`, which counts the project's `assessment-history.json`: a sub-topic with 3+ entries at Bloom <3 appends to `persistentChallenges`; 3+ at Bloom 4+ appends to `consistentStrengths`. Append-only and deduplicated — the script does the counting; skills never tally assessments in prose.
- `learnerBackground.domains[]` / `analogyHistory[]`: populated by the analogy-escalation protocol (see `feynman-technique` KB). Read-then-append; never overwrite.

### Project completion (canonical, 1.11.1)

A project is **complete** when every module in every plan phase is finished or explicitly skipped AND the learner confirms. Completion is never inferred silently — `evaluate` skill asks ("Shall we mark this path complete?") and only the learner's yes moves the entry from `activeProjects` to `completedProjects`. Completion gates the capstone offer, the mentor offer, and `teach-back` skill eligibility.

### `learningWithBodhi/.bodhi-profile.projects.json`

Per-project metadata, loaded only by cross-project skills (`mentor` skill, `evaluate` skill, `learn` skill).

```json
{
  "version": 2,
  "activeProjects": [
    { "name": "string", "topic": "string", "startedAt": "YYYY-MM-DD", "currentPhase": "string", "currentModule": "string", "bloomLevel": 0, "pace": "string", "status": "string", "trackPurpose": "string" }
  ],
  "completedProjects": [
    { "name": "string", "completedAt": "YYYY-MM-DD", "finalBloomLevel": 0, "trackPurpose": "string" }
  ]
}
```

Writers: since 1.16.0 the project-list mutations go through `bodhi-state` — `profile-add-project` (`learn` skill append on project start; creates this file if missing), `profile-update-project` (`evaluate` skill refresh of the active entry), `profile-complete-project` (`evaluate` skill on confirmed completion; `learn` skill Phase 1.5(c) replace-archive via `--status`). `mentor` skill writes career fields in the parent profile only. The entry shapes above are constructed by those subcommands and checked by `verify`; hand-editing is fallback-only (apply the Fallback discipline above).

## Schema-Evolution Rules

- Schemas evolve; readers tolerate older `version` values (the script read-tolerates v1/v2 and persists v3 on write). Skills MUST NOT branch behavior on version in prose. Full transforms live in the `state-migration` KB.

SHA-256: 033613b1e873217f17d8800f5b0f449e589e1aa958aded7257b6748dd4dc7b6e