← Files BodhiKitARCHIVED FILE

references/knowledge/state-ops.md

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

↓ Download file

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

# State Ops — The Per-Session Operational Surface

This KB is what a skill needs to *operate* on tracking state: find the project, invoke `scripts/bodhi-state`, write the markdown surfaces. Field-level file shapes live in the `state-schema` KB and are deliberately NOT loaded on routine fires — a skill that cannot see field shapes cannot hand-edit them.

Load the `state-schema` KB only when:

- performing one of the **manual carve-outs** (*Update Rules* below);
- running the **script-unavailable fallback** (see below);
- you are `housekeep` skill (rotation and migration need the full shapes).

See also: `spaced-repetition` KB (intervals and update rules), `state-lifecycle` and `state-migration` KBs (`housekeep` skill only).

## The Write Path: `scripts/bodhi-state` (canonical for ALL JSON writes)

Skills do not hand-edit tracking JSON. Every mutation of `state.json`, `spaced-review.json`, or the profile files goes through the plugin's deterministic writer:

```
"<BODHIKIT_PLUGIN_ROOT>/scripts/bodhi-state" --project <project-dir> <subcommand> [options]
```

If `BODHIKIT_PLUGIN_ROOT` is unset, locate the script once with `find the installed plugin package -type f -name bodhi-state -path "*bodhikit*" 2>/dev/null | head -1` (or the repo checkout's `scripts/bodhi-state` when running via `--plugin-dir`).

What each subcommand owns — the contracts a skill must not work around (`--help` prints the flags):

**Writers**

- `add-concept` — a new concept with the canonical Box-1 defaults. `--bloom N` records the level an assessment classified it at (`learn` skill seeds pass it; a seed at 0 reads as unclassified everywhere downstream).
- `record-review` — Leitner box and `nextReview`, the Bloom ratchet, `consecutiveCorrectAtL4Plus`, the `reviewHistory[]` append. The box and the streak move only on a due review (`spaced-repetition` KB); an early, same-day or first review is recorded and ratchets the level but reports `boxHeld` — do not re-run it hoping for a promotion. `--confidence sure|mostly|guessing` is the learner's pre-reveal calibration tag, never a gate on promotion. `--retry` is a successive-relearning rep: history only, no box/counter/bloom movement (the demotion stands). `--applied` marks an outcome demonstrated in work the tutor read (code that ran, or a non-code written application: `blooms-taxonomy` KB), never an explanation or quiz answer — the only evidence the gate and mastery accept for "can build with it". Off `code` it needs `--evidence <path>`, the learner's file beside the exercise's key; `--applied inspected|reported` (a photo examined, the learner's word) is accepted on `performed` only. The write that first brings a concept to the apply level also counts it in the profile's `totalConceptsLearned` — no skill bumps that.
- `revise-review --reason` — today's latest review, graded wrong: moved to `revisedReviews`, the concept restored, the right grade applied (the one write that may lower the level). Never a second `record-review` (`spaced-repetition` KB).
- `set-feynman` — `feynmanPassed = true` (never unset), `feynmanPassedAt = today`.
- `record-session` — a `sessionHistory[]` entry in the canonical type vocabulary (below); `type`, `subtype` and `date` come from flags, never from `--data`.
- `record-assessment` — an append-only, date-stamped `assessment-history.json` entry.
- `forget` — the learner-initiated demote: box 1, counter reset, a `selfReport` history entry (excluded from `retention`) and a `learner-forget` session entry, `lastActivity`. `--concept` (repeatable) for names containing commas.
- `defer` / `park [--resume]` — scheduling, never an outcome. A deferral rolls `nextReview` and writes a history entry with **no result**; parking leaves rotation with box, bloom, Feynman and counters intact and is reported as a count, never hidden. Do not invent a `result` for a concept that was not reviewed.
- `touch-state` — `state.json` session bookkeeping: dates, streak, `totalSessions`, module advance (`previousModule`). The first touch of a day also bumps the profile's `cumulativeStats.totalSessions` — no skill calls `bump-profile` for that.
- `bump-profile --counter` — `cumulativeStats` increments in `.bodhi-profile.json`.
- `set-evidence-kind --kind K [--module M]` — the project's evidence kind, or one module's (`state-schema` KB; no kind = `code`). Rejects a module matching no plan heading or tracked concept; `--clear` removes one. Writes `state.json` only: every review is kept.
- `profile-add-project` / `profile-update-project` / `profile-complete-project` / `profile-update-patterns` — the `.bodhi-profile.projects.json` list (schema-complete entries, unknown fields preserved) and the count-based `patterns`. Completion is learner-confirmed, never inferred; the skill never tallies assessments in prose.

**Readers** (no lock file, no writes)

- `due` — due concepts in review order (`priority`, `dueSince`, `overdueDays`, `bloomOutcome`) — by design no box or Bloom number. Each carries `exposure` — `seeded` (never graded), `quizzed-only` (graded only by quiz/reflect retrievals, none at the apply rung since the last miss), `demonstrated` (no instruction on record but an apply-rung correct), `taught` (a `teach` skill, `practice` skill or `pair` skill review), `built` (an `applied` correct) — and `neverTaught`, true for the first two: route those to `teach` skill, not `quiz` skill. `unparseableDates` lists schedule-broken entries rather than skipping them.
- `session-brief --concept` — `teach` skill's branches: pretest vs graded retrieval (`firstExposure`/`pretestApplies`), `isReteach`, box/bloom/Feynman position, `dueForReview`.
- `snapshot` — the whole `progress` skill surface in one call (`project`, `cadence`, `review`, `mastery`, `calibration`). `mastery` / `calibration` / `retention` / `export-anonymized` — its parts and the outcome analytics: retention by spacing gap and `boxBefore`, with `delayedSuccessRate` (every bucket but same-day, which is immediate post-instruction performance; self-reports excluded); an anonymized counts-only export.
- `revision-brief` — today's facts for the revision sheet (`sessionToday`, `suggestedFile`, `existing`); the Stop hook (Codex) or the runtime adapter's close procedure (ChatGPT) reads it.
- `syllabus` — the plan's modules in order (`plan/phase-*.md` headings) joined with each module's evidence row and the `state.json` position: `status` (`done`/`current`/`upcoming` from plan order, or a declared `skipped`), `position` (`index` of `of`), `targetBloom` with label and outcome, `evidence` (the module row plus `summaryTier`, `nextDue`, `dueToday`), `untracked`/`unplanned` for what one side lacks. `plan` skill with request context `view`, `continue` skill's check-in and `progress` skill render it, never re-deriving order or position.
- `gate-check` — the prerequisite verdict (*Prerequisite Gate* below).
- Each reader also gives the effective `evidenceKind`: per concept (`due`, `session-brief`, `revision-brief`, a `gate-check` row's own), per module (`mastery`, `snapshot`, `syllabus`), and the project's (`snapshot.project`, with `evidenceKindRecorded`; `syllabus`).

**Maintenance**

- `migrate-spaced-review` — v1/v2 → v3 once: backup, in-place field fill, marker, verification.
- `normalize` — idempotent repair of executor drift (invented result/type vocabulary, nested bookkeeping, the lossless type fixes: a numeric-string box or level, a string boolean), both files backed up first. `verify` names it only when it can perform the repair.
- `verify` — the schema check the Stop hook (Codex), the runtime adapter's close procedure (ChatGPT) and `dev/check.sh` run.

The script preserves unknown fields by mutating parsed JSON in place, writes atomically, and rejects invalid `sessionHistory` types in code. The skill's job is the pedagogical judgment (which result, which Bloom level, which confidence tag); the script's job is the file.

**Fallback (script unavailable):** only after BOTH the `<BODHIKIT_PLUGIN_ROOT>` path and the package-relative lookup come up empty, say so plainly, then load the `state-schema` KB and perform the minimal write by hand per its *Fallback discipline* — read → mutate the parsed JSON in place → write → verify, preserving every unknown field.

**Markdown surfaces** (`progress.md`, `assessments/latest.md`, plan files, `resources.md`, and the learner-facing `revision/` sheets) are still written by writing it directly: compose the new entry at the top, preserve all existing content verbatim below it.

## Project Discovery Config

Two layers. Per-project overrides global.

**Global:** `~/.bodhikit/config.json`. Optional.

```json
{ "searchPaths": ["$PWD", "~/learningWithBodhi"] }
```

**Per-project:** `<repo-root>/.bodhikit/config.json`. Optional. Highest precedence.

```json
{ "projectRoot": "study/" }
```

- `projectRoot` is a path (relative to the file's directory, or absolute) where the learner keeps `.bodhi/` for THIS repo.

**Discovery is a file-read, NOT a `bodhi-state` subcommand.** There is no `discover`, `--list`, or `list-projects` — do not call the script to find projects. The `bodhi-state` subcommand table above is the *complete* set; discovery is plain filesystem inspection (glob / `ls`), performed as follows:

**Discovery procedure (all skills use this exact procedure):**

1. From the current working directory, walk up to 3 parent levels looking for `.bodhikit/config.json`. If found and it declares `projectRoot`, treat that path as a project root and stop further search unless the caller explicitly wants `--all`.
2. Otherwise, read `~/.bodhikit/config.json` if it exists; if not, use the default `searchPaths: ["$PWD", "~/learningWithBodhi"]`.
3. For each path in `searchPaths`: resolve `$PWD` to cwd (and walk up 3 parents), expand `~`, then look for `learningWithBodhi/` directories.
4. Within each `learningWithBodhi/`, list subdirectories containing `.bodhi/state.json` — e.g. `ls -d <path>/learningWithBodhi/*/.bodhi/state.json 2>/dev/null`. Each match is one project (its dir is the parent of `.bodhi/`).

## Tracking-Surface Map (v2, 1.7.0)

| Surface | Pattern | Live doc | Archive |
|---|---|---|---|
| Sessions / progress | Live + archive + summary | `progress.md` | `progress/archive/<YYYY-MM-DD>[-N].md` |
| Assessments | Live + archive + summary | `assessments/latest.md` | `assessments/archive/<phase>-<topic>.md` |
| Plan | Sectional | `plan/README.md` + `plan/phase-{N}.md` | none |
| State | Slim JSON | `state.json` | none |
| Spaced review | Whole JSON | `spaced-review.json` | none |
| Profile | Split JSON | `.bodhi-profile.json` + `.bodhi-profile.projects.json` | none |
| Resources | Whole MD | `resources.md` | none |
| Assessment history | Append-only JSON | `assessment-history.json` | none |
| Teach-backs (capstone) | Per-post MD files | `teach-backs/<YYYY-MM-DD>-<slug>.md` | none |
| Revision sheets | Per-day MD files (learner take-home, outside `.bodhi/`) | `revision/<YYYY-MM-DD>-<concept>.md` — written at session end per `reflect` skill's `references/revision-sheet.md`; `revision-brief` names the file; the Stop hook (Codex) or the runtime adapter's close procedure (ChatGPT) requires it on a day that studied something | none |

Live-doc mechanics (summary growth, collapse, archive naming) live in the `state-lifecycle` KB. Skills load the live doc + current plan phase by default; `plan` skill and `evaluate` skill may load all phase files. Skills that read archive content MUST announce the read in their turn output.

## `sessionHistory[].type` Canonical Vocabulary (enforced in code by `record-session`)

| `type` | Written by | Meaning |
|---|---|---|
| `spaced-review` | `quiz` skill, `reflect` skill (due-concepts batch) | Routine spaced-review session |
| `quiz` | `quiz` skill (explicit-topic invocation) | Quiz on a specific topic, not by schedule |
| `targeted-reteach` | `teach` skill (re-entering a demoted concept) | Focused re-teach after demotion or precision-gap surfacing |
| `diagnostic-after-gap` | `learn` skill, `assess` skill, `continue` skill (after absence) | Diagnostic after a meaningful gap |
| `learner-forget` | `forget` skill | Learner-initiated demotion |
| `learner-park` | `forget` skill with request context `--park` (and `--unpark`) | Learner-initiated exit from / return to review rotation |
| `pair` | `pair` skill Session End | Pair session touching tracked concepts |
| `practice` | `practice` skill | Exercise session introducing/reviewing concepts |
| `evaluate` | `evaluate` skill | Comprehensive evaluation snapshot |
| `other` | any skill | Escape hatch; **requires `subtype`**. Prefer extending this table over reaching for `other`. |

Optional fields on entries (writers MAY include via `--data`): `conceptsReviewed`, `passes`, `misses`, `partials`, `boxChanges`, `precisionGapMovement`, `habitObservations`, `notes`, `calibrationNote`, `conceptsDemoted`. Readers MUST tolerate unknown fields; the script preserves them.

## Mastery (canonical, computed by `bodhi-state mastery`)

```
mastered = (bloomLevel >= 4)
       AND (consecutiveCorrectAtL4Plus >= 3)
       AND (box >= 4)
       AND (feynmanCurrent)
       AND (appliedEvidence >= 1)
```

`appliedEvidence` counts `applied` corrects since the most recent miss; `feynmanCurrent` is an explain-back dated after it (`state-schema` KB). Without it every other conjunct can be met in conversation. `mastery` and `snapshot` report `blockedOnApplied` (every criterion but this one) beside `blockedOnFeynman`, and each module row carries `applied` (concepts with at least one build since the last miss). `masteredDueForCheck` (per module: `dueForCheck`) names mastered concepts overdue by more than their box interval: still mastered — a skipped check is unverified, not forgotten — and `progress` skill renders them *Solid, due for a check*.

Skills MUST NOT redefine this formula inline; the underlying criteria are the `blooms-taxonomy` KB's.

**Per-module tiers.** `mastery` and `snapshot` also return, per module, `tiers: {unclassified, introduced, familiar, mastered}` — each concept classified against the `blooms-taxonomy` KB's ordered tier ladder (that KB is the canonical definition; `mastered` reuses the formula above, so there is still one home for it). The counts always sum to the module's `concepts`. Skills render these counts and MUST NOT infer a tier from `mastered`/`classified`/`masteryPct` — deriving one from a rollup loses the distribution.

**Legacy display rule:** `bloomLevel: 0` = never classified by a v3 writer. The gate passes it (`no-opinion`); a module whose concepts are all at 0 shows `—`, not 0% (`masteryPct: null`).

## Prerequisite Gate (canonical, computed by `bodhi-state gate-check`)

The `teach` skill Phase 1 gate fires only on the first session of a new module (detected by: no concept whose `module` matches `state.json.currentModule` carries a graded review yet — concepts `learn` skill seeded from the assessment are tracked but not started, and the verdict reports them as `seededOnly`; a deferral is not activity). Per-prerequisite verdicts:

| Verdict | Condition | Gate behavior |
|---|---|---|
| `satisfied` | `bloomLevel >= 3` AND (`box >= 3` OR two or more correct reviews graded at Bloom 3+ **since the most recent miss** — an `incorrect` review or a `forget` skill resets the count — with the latest reviewed within 30 days) AND at least one `applied` correct since that miss | Pass (`reason: box` or `evidence`) |
| `stale-reconfirm` | `bloomLevel >= 3` but box < 3 AND either fewer than two level-3+ corrects since the last miss (`reason: single-evidence` — zero after a `forget` skill) or last review > 30 days ago (`reason: stale`); OR the recall evidence above would pass but no `applied` correct exists since the last miss (`reason: no-applied-evidence`, 1.20.0 — every concept tracked before the flag meets this once) | One quick reconfirm — a single grade is noisy and the Bloom ratchet is one-way, so one review is not settled evidence. For `no-applied-evidence` the reconfirm is a few lines of code the learner writes, recorded `--applied`; for the other reasons a question. Phrase by reason: "we have only seen this once" / "it has been a while" / "you have explained this well; show me once in code" |
| `no-opinion` | `bloomLevel == 0` | Pass (legacy fallthrough) |
| `apply-equivalent` | `1 <= bloomLevel < 3` but `box >= 3` AND last two reviews correct AND one `applied` correct since the last miss (without it: `stale-reconfirm` / `no-applied-evidence`) | Pass (gate-time read only; bloomLevel untouched) |
| `gap` | otherwise | Surface as an offer — never auto-block; the learner decides |

Each prerequisite row also carries `evidenceAt3Plus` (count of level-3+ corrects since the last miss), `appliedEvidence` (built corrects since the last miss) and `bloomLabel`/`bloomOutcome` for learner-facing phrasing (`blooms-taxonomy` KB rendering rule).

Prerequisites come from the plan's `**Prerequisites for next module:**` declaration (passed via `--prereqs`; a declared `none` → `fires: false`) or, as fallback, all concepts of the tracked `previousModule` (the verdict JSON reports `prerequisiteSource: "declared" | "prior-module"` so the skill can tell the learner which mapping it used). When neither is available the gate declines to fire (`fires: false` with the reason) — it never infers a prerequisite module from concept dates; a guessed gate generates false reconfirm questions, which cost more trust than no gate.

## Update Rules

- Markdown live docs: compose the new entry at the top; preserve existing content verbatim; never rotate (that is `housekeep` skill's job, per the `state-lifecycle` KB).
- Skills MUST NOT introduce new top-level fields, files, or directories under `.bodhi/` without updating the `state-schema` KB (and `bodhi-state`) first.
- Skills MUST NOT stuff long narrative into JSON fields — narrative belongs in `progress.md` / `assessments/latest.md`. `lastActivity` is one short sentence (≤120 chars).
- **Manual carve-outs**, the only hand-edits of tracking JSON — load the `state-schema` KB and follow its *Fallback discipline* (read → mutate in place → write → verify): `learn` skill project scaffolding, `evaluate` skill profile writes, and the per-topic Bloom maps in `state.json` (`initialBloomLevel` / `currentBloomLevel`), which no subcommand owns — `learn` skill seeds both; `assess` skill and `evaluate` skill may update `currentBloomLevel`.

SHA-256: 8f6b0e63f4fedc7bb6814d1a7faa024aad6e9341fbfa383928d18f5091037a00