git:20260711.c9add96 to git:20260806.bed1b85

+ description: Lesson-plan generation and compliance-check desk (Busabase App-in-Skill) for a dean of studies or training-program lead. Use when the user invokes $kelly-lesson or /kelly-lesson, mentions lesson plan, 备课, 教案, teaching plan compliance, curriculum template, dean of studies, teacher training, wants lesson plans drafted from curriculum materials and the school template, teacher drafts imported and checked against quality standards, a review queue for approving plans, or a library of approved plans exported as documents.

+ Use this skill as the dean-of-studies (教导主任) lesson-plan operator. The school has a required lesson-plan template and quality standards, but teachers' plans vary wildly and checking them all by hand is expensive. Kelly Lesson lets the agent draft plans from curriculum materials plus the school template, run deterministic and agent-assisted compliance checks, and gives the dean a Busabase-backed App-in-Skill review queue (approve / request changes / block) plus a library of approved plans exportable as documents. Teachers' own drafts can also be imported and checked. Reading a curriculum document or a teacher's draft file is a genuine external operation a browser cannot perform: `scripts/ingest_plan.mjs` is the only place a plan enters the system, `scripts/run_checks.mjs` runs the compliance rules, and `scripts/execute_decisions.mjs` prints the plan for approved/changes-requested plans. The AirApp itself only reads Busabase and writes review decisions; export happens through `scripts/export_plans.mjs`, and sending feedback to a teacher is always delegated to another skill (e.g. kelly-email) after explicit approval.

+ Default behavior is AirApp-first. Unless the user explicitly asks only for explanation, ingest/check what's due and give the user the clickable AirApp URL (or the local preview URL when local preview is explicitly requested). Use chat-only mode only when the user says "纯聊天", "chat only", "不要打开 UI", or similar; then present numbered plans (`Plan #1`) and take verdicts in conversation.

+ ## Mandatory Dependencies

+ 1. Read and follow `$kelly-app-skill-creator` for product behavior, visual quality, responsive layout, and the complete canonical `app/` artifact.

+ 2. Read and follow `$busabase` for connection, target Space, node discovery, ChangeRequests, review, and merge behavior.

+ 3. Read and follow `$busabase-app-creator` for resource modeling, AirApp runtime limits, security, validation, and deployment.

+ If a dependency is unavailable, preserve this skill's local artifact and product contracts, stop before the unavailable Busabase operation, and report the exact missing dependency. Do not invent a second data backend.

+ ## Boundary

+ - Ingesting a plan is a local-file-only operation: `scripts/ingest_plan.mjs` reads a JSON payload file the agent prepares (from curriculum materials or a parsed teacher document) and writes it to Busabase. It never fetches documents from remote systems on its own.

+ - The AirApp reads and writes Busabase records only. It must not contact teachers, send messages, export documents, or mutate remote systems.

+ - Feedback to a teacher is approval-required: the app only stores a drafted note (`feedback-draft`) on the plan record; after the dean approves, the agent sends it via other channels/skills (for example kelly-email) and records the real handoff separately. `scripts/execute_decisions.mjs` never performs this send itself — it only writes an execution marker.

+ - Treat plans, teacher names, and school documents as private school data. Never commit local payload files, env files, or generated exports.

+ ## Busabase Resources

+ Four Bases under one application Folder (`kelly-lesson`), declared in `app/app/js/config.js` and `app/resource-map.json`:

+ - `teachers`: teachers referenced by lesson plans.

+ - `plans`: the plan library and review queue in one — structured sections, workflow status, compliance score, and the human decision + execution marker on the same row.

+ - `checks`: per-plan, per-rule compliance check results.

+ - `settings`: one row (`record-id: "config"`) with school profile, template sections, compliance rules, and export/feedback preferences.

+ Resources provision lazily through an idempotent Busabase ChangeRequest the first time the app runs in a Space; see `references/lesson-schema.md` for exact field shapes. Compliance scores, the review queue, the recent-activity feed, and metrics are recomputed client-side from the stored rows on every read (`app/app/js/lesson-model.js`'s `buildSnapshot`/`assembleSnapshot`), so the desk is always fresh regardless of when a browser session loads it relative to the last ingest/checks run.

+ ## First Run And Onboarding

+ On invocation, check the `plans` Base. If it is empty, guide setup before ingesting real plans: ask, turn by turn, school profile (name, kind, term, class length in minutes), the school template sections (keys, labels, which are required), compliance rules with severities and params, subjects and grades in scope, and export preferences (format, output directory, whether DOCX conversion goes through the agent). Write the answers onto the Settings row, then ingest and check:

+ node skills/kelly-lesson/scripts/ingest_plan.mjs payload.json --apply

+ node skills/kelly-lesson/scripts/run_checks.mjs --apply

+ ## Local App

+ Default behavior is AirApp-first — give the user the clickable AirApp URL. Start `pnpm --dir app dev` only when local preview/debugging is explicitly requested.

+ Required app views (hash routes):

+

+ - `#/overview`: teaching-quality command desk — KPI cards (plans total / approved / in revision, compliance pass rate), coverage by grade and subject, per-teacher status summary, review-queue preview, recent activity (derived from each plan's own timestamps).

+ - `#/plans` and `#/plans/<plan_id>`: the plan library — subject, grade, unit, teacher, source badge (`agent_draft`/`teacher_import`), compliance score, workflow status. Detail shows the full structured plan (objectives, key points and difficulties, materials, lesson-flow stages with timing, board plan, homework, reflection, safety notes, curriculum refs) with the compliance panel and an editable notes field alongside.

+ - `#/review`: the review queue — every plan with its workflow state (`needs_review` / `changes_requested` / `approved` / `done` / `blocked`), compliance summary, agent revision suggestions, editable feedback-to-teacher draft, `Review note`, decision buttons (approve / request changes / block), and a stable ref (`Plan #1`). Decisions write directly onto the plan record through `busabase-sdk`.

+ - `#/settings`: sanitized config summary — school profile, template sections, compliance rules with severities, subjects/grades, export prefs, feedback handoff, read live off the Settings Base.

+ - `lang=en` or `lang=zh` forces UI chrome language; with `lang=zh` the demo content itself (school, teachers, plan titles, rules, feedback drafts) is meaningfully localized (北湖中学).

+ - Demo mode never reads or writes Busabase. Decision buttons still work in the UI but act on in-memory state only.

+ 3. For a teacher's document, parse it into the same payload with `"source": "teacher_import"` — do not silently fix deficiencies; let the checks surface them.

+ 4. Run the write path:

+ ```bash

+ node skills/kelly-lesson/scripts/ingest_plan.mjs payload.json --apply

+ ```

+

+ The script validates the payload against the school template sections stored on the Settings row, normalizes teachers/plans/checks, and upserts them into Busabase by natural key (`teacher_id`/name, `plan_id`) so re-ingests are idempotent. Without `--apply` it is a dry run.

+

+ 1. Run `node skills/kelly-lesson/scripts/run_checks.mjs --apply`. Deterministic rules (section presence, stage count and timing, duration sums, homework, measurable-verb heuristics, lab safety) are computed from the compliance rules on the Settings row; per-plan compliance scores are recomputed idempotently.

+ 3. Summarize failures for the dean by ingesting `compliance_summary`/`suggestions`/`feedback_draft` onto the plan record.

+ 4. Give the user the AirApp URL and send them to `#/review`.

+ ## Decisions And Execution Workflow

+ 1. The dean reviews at `#/review`: approve, request changes (with a note), save an edited draft (revise), or block. Decisions write directly onto the plan record. From a standalone local preview the write merges immediately (trusted operator); from the deployed AirApp it creates a pending ChangeRequest for the trusted process to merge.

+ 2. On explicit user request to execute, run `scripts/execute_decisions.mjs` (dry-run by default; `--apply` writes `execution-status: "ready_for_agent"` onto each decided plan with the concrete operation — `publish_plan` (from `approve`) or `request_revision` (from `request_changes`) — and target). No external side effects either way; the plan's workflow `status` never changes.

+ 3. The agent then performs the approved follow-up outside the app: for `publish_plan`, run `scripts/export_plans.mjs` and send the feedback draft via other channels (e.g. kelly-email) after approval; for `request_revision`, redraft the plan per the review note, re-ingest, and re-run checks.

+ 1. `node skills/kelly-lesson/scripts/export_plans.mjs --out <dir>` reads plans with status `approved` or `done` from Busabase and writes each as clean Markdown (default `exports/`, gitignored). Read-only against Busabase — no state is written back.

+ - Use stable ids and natural-key upserts so repeated ingests, checks, and executions are idempotent.

+ - If the plan payload and the school template disagree (unknown rules or sections), stop and reconcile before executing.

+

+ ## Useful Commands

+

+ ```bash

+ node skills/kelly-lesson/scripts/ingest_plan.mjs payload.json --apply

+ node skills/kelly-lesson/scripts/run_checks.mjs --apply

+ node skills/kelly-lesson/scripts/execute_decisions.mjs

+ node skills/kelly-lesson/scripts/execute_decisions.mjs --apply

+ node skills/kelly-lesson/scripts/export_plans.mjs --out exports/

+ pnpm --dir skills/kelly-lesson/app dev

+ ```

+

+ In normal use, invoke `/kelly-lesson`, let the skill ingest/check what's due, and open the AirApp.