Coaching work plan

Current restoration target: the user has requested the v0 coaching and conversation-assistance experience. The v0 source comparison and restoration contract supersedes the earlier one-suggestion/skill-bound approach as the target design. The restoration is now implemented in source; lesson/progression redesign stays frozen. Implementation and verification records the new independent contracts and current verification limits.

September 16 priority change: voice conversation is the primary experience. Lesson/curriculum and progression redesign are frozen while chat coaching is corrected. Direct corrected wording plus a brief actionable explanation replaces hint-first help for new turns; continuing the conversation never requires a repair exercise. Automatically recommended skills must not redirect the topic. The earlier wave/lesson sequence below is deferred where it conflicts with this decision. Current implementation and verification are recorded in the chat-first checkpoint.

How the coaching plan gets built. The seams between work areas are in coaching contracts. Section references (§n) point into the coaching plan.

Team

One integration agent plans, writes reports, reviews and verifies. Three domain agents build. For this wave the user's instruction to execute is handled in the current task: integration dispatches the three bounded assignments and relays their reports. Domain agents do not communicate directly with each other. The user performs Git checkpoints.

Agent	Domain	Owns (edits only these)	Consumes
A · Language & Config	What the app knows: languages, scripts, romanization, traits, constructs, starters, policies, bibliography, and the YAML loader	config/**, schemas/**, references.bib, native/src/languages.rs (becoming native/src/languages/**), native/src/config/**, native/src/linguistics/adapter.rs (prompt text), src/domain/language/**	nothing upstream
B · Coach & Learner Core	What the app does: turn plans, coach and persona operations, feedback policy, learner model, persistence, native actions	native/src/{coaching,progression,execution,turn_plan,model,store,conversation_prompt}.rs, native/src/schema.sql, new native/src/{learner_state,openers,policy,fluency}.rs, native/src/bin/export-contracts.rs, server/audio_input.py	A's resolver API
C · Experience & Game	What the learner sees and feels: chat surfaces, coach card, start panel, profile, reward presentation, sound, motion	src/features/**, src/state/**, src/styles/**, src/ui/**, src/platform/audio/**, src/assets/** (not config), frontend tests	generated src/contracts.ts; fixtures
I · Integration	Plan, contracts, sequencing, reviews, docs	docs/website/docs/coaching-*.md, AGENTS.md, DESIGN.md, DATA-MODEL.md, BUILD-PLAN.md, workflow/reports/coaching-*	everything

Shared-file rules:

• src/contracts.ts is generated only, by B's export-contracts. C never edits it.
• An agent that needs a change outside its area writes a change request in its hand-back instead of making the edit.
• A owns language guidance text and exposes it through functions. B owns task prompts and calls those functions. Neither edits the other's prompt text.

Wave-one ownership exceptions (integration assignment):

• C owns src/domain/skills/**, src/types.ts, and src/domain/language/conversation-view.ts plus its tests for revision identity, grouping and rendering. A retains the rest of src/domain/language/**, including sentence punctuation. C adapts skill types to B's generated Outcome; it does not author a second enum or compute native credit.
• C also owns the bounded src/platform/ipc/workspace.ts change exposing the existing conversation pagination argument, with tests. B may register its new revision module in native/src/lib.rs; unrelated app lifecycle code stays outside this assignment.
• B owns src/assets/skill-catalogs/catalog.json for the bounded catalog code/version correction. C does not edit this file during wave one. B reports the chosen version representation before C changes evidence consumers.
• B owns any new revision schema SQL and Rust revision module needed for this wave. Changes to module declarations or other files outside its assignment require a concrete change request; integration assigns the file before editing.
• These exceptions take precedence over the broad ownership rows for wave one only.

Current integration checkpoint

The user committed wave one at bdb664e and authorized wave two. Active assignments and ownership exceptions are in workflow/reports/coaching-w2-integration.md; wave-one exceptions below do not automatically carry forward. Integration relays all dependencies in the existing three-agent team.

Wave-one integration checkpoint

The launch brief is workflow/reports/coaching-w1-integration.md. The user has authorized erasing and recreating SkellySpeak development data as needed. B can implement the current schema directly; no migration or preservation gate remains. Coordinate native runs for workspace ownership.

Every hand-back must explain how its behavior supports the learner's agency: guidance is inspectable and language-specific, focus creates natural opportunities without turning the partner into an examiner, revisions preserve the learner's exact earlier wording, and rewards name valid evidence. Do not claim linguistic validity from prompt snapshots or proficiency from XP.

Cycle

For each wave:

1. The integration agent writes one report per agent: brief, contract excerpt, acceptance checks.
2. Integration dispatches each report to its assigned agent in this task.
3. The agents work in parallel, each only in its own files.
4. Each agent returns a hand-back report to integration, which relays dependent contract changes.
5. The integration agent reviews the diffs on disk, runs the gate, and reconciles contract drift.
6. The user commits (agents never touch git), and the next wave begins.

Verification gate (every agent, before hand-back):

npm test
npm run build
cd native && cargo clippy --lib -- -D warnings && cargo test --lib
cargo run --bin export-contracts -- --check

Plus the citation test (from wave 1) and any snapshot tests the wave adds.

Paid inference: allowed for live QA and evaluation, bounded. Before a run, state the request count, the model (the Fast binding where possible) and the purpose. Stop at the stated count, and report the actual usage. No open-ended or looping runs.

Hand-back template:

## Hand-back: <agent> · wave <n>
Done:             plan item → files changed → test that proves it
Not done / why:
Verification:     gate output summary; name any failing command
Paid inference:   requests, model, purpose (or "none")
Contract drift:   anything that differs from coaching-contracts.md, and why
Change requests:  edits needed outside my area
Discovered:       defects or facts found in passing, with file:line
Inferred vs read: label any file:line not read during this wave

House rules (repeated in every report):

• No git writes.
• No fallbacks, and every error reaches the UI.
• No fake UI.
• Development user data is disposable, including conversations, progress and generation receipts. Resets needed for development are authorized without repeat confirmation. Do not build migrations or compatibility solely to preserve it. Planned coaching changes target v13; keep user_version and SCHEMA_VERSION aligned. Report actual resets in the hand-back.
• Never listen for Tauri close requests.
• Cite research by references.bib key.
• Linguistic content starts at review: needs_review.

Waves

Wave 0 · Foundation (integration) — done

• The coaching plan, this work plan, contracts, references.bib, a static reading view (docs/website/static/coaching-plan.html), and pointers in AGENTS.md, DESIGN.md and BUILD-PLAN.md.
• The wave 1 reports are in workflow/reports/coaching-w1-*.md.

Wave 1 · Fix what's broken (§14 wave 1) — checkpointed

A	B	C
Romanization scheme registry + guidance function; inject it into the gloss adapter; guard test "every declared scheme reaches a prompt"; add ؟ to TERMINAL_PUNCT; assessment-guidance function holding the Arabic rule; citation-key test over references.bib	Use A's romanization and assessment functions in coaching.rs; 5 outcomes in the Rust contract; catalog codes match hierarchy; real or removed catalog version; focus into persona and coach prompts; planned schema v13 turns.replaces_turn_id + ReviseTurn action + replaces_message_id populated + revision recorded	Wire Edit & try again to ReviseTurn; remove the requestTurn rejection; the collapsed "Earlier version" view; replace mock-only TurnView tests with GuidedPage integration tests

Order: A's two functions and B's ReviseTurn contract land first. C builds rendering and test scaffolding against fixtures, then wires to the real action.

Exit checks:

• An Arabic gloss prompt snapshot contains the ALA-LC rules.
• Revising the latest turn creates a new turn with replaces_turn_id, and the persona reply regenerates.
• revision = true reaches the evidence records.
• Focus text appears in the persona prompt snapshot.

Wave 2 · Config as data; coach contract; conversation starts (§4–6, §10) — accepted for continuation

A	B	C
YAML loader + schemars schemas + startup load-error event; config/languages/**; config/constructs/** from the current catalog (lens, nav, requires, opportunity); config/starters/*.yaml; config/policy/feedback.yaml; resolver + hashing	CoachObservation / CoachDecision + policy; candidate constructs; hint-first; coach_retry_check; candidates_sent / items_returned; StartConversation + persona_opening; mechanical starter selection	ConversationStart panel (starters, Surprise me, Describe it, live composer, beginner tray); message chip + coach card; "Fixed" note; startup config-error screen

A delivers a loader API stub (types plus a hardcoded implementation) at the start of the wave, so B can code against it while A builds the real loader.

Wave 3 · Learner model, fluency, game layer (§5.1, §7, §9, §11) — in progress

User accepted Wave 2 for continuation on 2026-09-13. UI polish is owned by separate work. First structural slice: editable estimator policy, deterministic construct state projection, and native learner-state read/YAML-export commands. Reward policy, persisted XP events and at-most-once display claims are now implemented. The first profile view now exposes construct estimates, variety filters, source inspection and reversible exclusions (see workflow/reports/coaching-w3-profile.md). The next profile slice adds registry-lens grouping and partner-scoped estimates; verification is recorded in workflow/reports/coaching-w3-partner-profile.md. Fluency, calibrated per-lens assessments, openers, session review and remaining reward causes/effects remain planned. See workflow/reports/coaching-w3-foundation.md.

The fluency foundation is being built separately from live recording integration: strict timestamp parsing, local signal analysis/alignment and hosted multipart field support. Status and the required transcript-ownership seam are recorded in workflow/reports/coaching-w3-fluency-foundation.md. Source support does not imply deployed service support or learner-visible fluency measurements.

A	B	C
estimator.yaml, game.yaml; test of the three reward rules; content pass for es/ar/zh (validated by the project lead)	Observation → ConstructState fold; XP from evidence; reward events; LearnerState YAML export; fluency pipeline (verbose_json timestamps, local silence detection, alignment, hallucination gate, server accepts the fields); coach_openers (when proactivity is standard or higher), session_review	Profile / open learner model; session goal and review; reward tiers, sound, motion, juice levels, reduced motion; stars and flower from XP; partner milestones; "Removed … no speech detected" notice

Wave 4 · Measure

• Integration: harness design and labelling guide.
• A: fixture sets per language.
• B: bounded opt-in harness runner (the bench.rs pattern, --ignored).
• C: toggles for hint-first vs explicit and for game surfaces on vs off.
• User: a labelled coach set for es/ar/zh.

Risks

Risk	Mitigation
B carries the most work	Starters and policies go to A; presentation goes to C; B computes. If B slips, coach_openers moves to wave 4.
Prompt text edited by two agents	A owns language guidance behind functions; B owns task prompts.
Rust/TS drift	export-contracts --check in every gate; C uses only generated types and fixtures.
execution.rs size	Only B touches it; new behaviour goes in new modules.
Other in-flight work	Each wave starts from a committed tree.
Unverified claims	Hand-backs separate what was read from what was inferred; integration re-runs the gate.

Explicit lessons addition

Source implementation connects the chooser, structured lesson generation, optional private coach practice, conversation handoff, exposure accounting and quoted recaps. Lifecycle tests cover persistence, failures, duplicate actions, ownership, revision and deletion. The visual/live-provider checkpoint is distinct from those automated checks; see workflow/reports/lessons.md.

Implemented lesson category selection and the optional two-question recall quiz. Native grading persists the first answer and projects separate 0/1 bonus XP without skill evidence. Verification and remaining visual/provider checks are recorded in workflow/reports/lessons.md.

Workspace design pass — 14 September 2026

Practice/Learn/Review source implementation places existing lessons in Learn, private coaching and evidence in study tabs, and saved reward provenance in a ledger. See coaching-contracts.md and notes/workspace-redesign-report.md at the repository root for behavior and verification limits. Live native inspection remains separate from automated checks.