← Files BodhiKitARCHIVED FILE
references/knowledge/state-schema.md
18.1 KB · Nov 21, 2026 · 12:41 UTC
<!-- 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