# Practitioner learning workflow — local delivery

Implemented in the local repository on 12 September 2026. Not deployed. No production patient records, role grants, content approvals or curriculum nodes were changed.

## Practitioner route

Staff with an active organisation and the effective `manage_orgs_scoped` and `sp_child_manage` capabilities now land on the Speech dashboard from `/dashboard`. The same effective role-capability resolver drives middleware and navigation; a DB-managed role with no capabilities remains denied. No permissions are granted by this change.

Open a child’s Speech Plan → **Concept learning**. The new workspace at `/org/patients/{patientId}/speech/learning` provides English/Hindi practice previews, reviewed-unit assignment, sessions, a partner recorder, unresolved-response review, language-separated evidence and JSON export for the content factory tracker. Links lead to existing profile/targets, home programme and skill progress. The recorder is for the practitioner using real objects and the child’s established communication system; it is not an independently validated child-facing game or speech-recognition service.

## Content and approval

`resources/speech/units/NOUN-PRESENCE-NUMBER/v1/{en,hi}` contains the existing draft practice packages: 20 scenes and 100 prompts per language. The four reserved families and their keys are excluded. Original source: `C:/Git/content/chatgpt/content_factory/languages/{en,hi}/units/NOUN-PRESENCE-NUMBER/v1`. No additional media generation was necessary. Nouns, scope, presence/absence, zero/one/more-than-one and what/where/how-many are mixed; this is not full grammar mastery coverage.

The admin **Learning Unit Reviews** page at `/admin/speech/learning-units` records actual native, access and key reviews by language and exact package hash. Approval records retain actor, findings/evidence, gate, decision and time. Default decision is changes required. Assignment requires all three current gates; content edits or withdrawal block subsequent recording until a new approved assignment. This separate pilot review gate does not replace existing Native Review or curriculum publication workflows.

No review has been approved by this development work. Qualified reviewers must verify the actual forms, scene semantics, access, answer alternatives and scoring. Test fixtures named SYNTHETIC exist only in isolated in-memory test databases.

## Trusted response records

Sessions pin the package, language, revision, content hash and approval IDs. Responses are scored on the server using that snapshot, never a client-supplied answer key, target or correctness flag. Both validity and interpretation default to unknown. Missing/unclear responses go to review; refusal and unanswered opportunities are not accuracy errors. Help is separate from access support. The primary target receives one score; linked concepts receive no duplicate credit.

Response saves use a session lock and unique request ID so network retries cannot double-count; reused IDs with different payloads fail. Completion uses the same lock. Tenant/child/org scoping applies to assignment, reads, recording, review and export. Completed sessions cannot accept new observations.

Human resolution preserves the original automatic result and records a separate one-time decision, note, actor and time. Reports include the original observations needed for interpretation. A human review does not silently promote a response into automatic accuracy or mastery. Reports separate language, content revision/hash, dimension, help and independent evidence. Practice and mixed phases are supported; transfer eligibility and automatic mastery remain false. Existing skill-state tables are unchanged.

## Validation

- `php -d extension=gd vendor/bin/phpunit --testsuite Speech`: **147 tests, 2,235 assertions passed** (includes 12 new tests, 649 assertions).
- New PHP files passed syntax checks; `git diff --check` passed.
- Vite production build passed to `storage/app/learning-workflow-build`; committed/live assets were not replaced. Existing Browserslist age and large-chunk notices remain non-blocking.
- The broad run without GD failed image fixture creation; enabling the installed extension for the test command resolved all 37 environment errors. Global PHP configuration was not changed.
- No real-browser visual or authenticated four-role acceptance walkthrough has been completed for this new implementation.

## Remaining acceptance and deployment

1. Walk through the new routes with synthetic records as admin, practitioner, parent and restricted child. Verify practitioner routes are unavailable to parent/child accounts, context cannot cross organisations, pending approval blocks assignment, and actual screen/access behavior is suitable.
2. Have qualified reviewers perform the three language-specific reviews; do not use synthetic evidence to unlock live assignment.
3. Deploy through the repository’s reviewed release process, build assets, and apply `2026_09_29_000001_create_learning_unit_workflow.php`. It creates one core review table and two tenant tables. Existing migrations are discovered by AppServiceProvider. Apply tenant schema through the deployment’s actual tenant migration process for every relevant database; tests use two in-memory SQLite connections, not a production MySQL migration audit.
4. Confirm the deployed revision and verify effective organisation permissions. The standard deployment script also publishes capability mappings to the identity provider; this action has not been run here and must be considered in the release review.

The existing home-programme and patient/child player remain available, but the new unit is not yet wired into caregiver assignment or restricted child play. Automatic speech recognition, target-specific mastery-policy evaluation, held-out exposure auditing, full prerequisite graph import and the other six native-language packages remain separate integration tasks. This delivery completes the local practitioner pilot implementation, not the entire app or clinical release.