Compliance course workspace with Ask Kwilo

Status: approved for implementation, 25 September 2026. The founder approved this plan after reviewing the visual concept. Implementation and verification are in progress.

Companion: implementation plan. Preserves the existing Compliance workspace and /compliance/outcomes routes.

Why this exists

1. Who asked: the founder, after using staging, asked to simplify CO–PO mapping, attainment and agents, and specifically reuse the Analytics Ask Kwilo pattern.
2. Observed pain: the founder could not identify the first task or how to use the agents. The browser walkthrough reproduced empty selectors, repeated context selection, zero-row suggestions offered for acceptance, and conflicting progress messages.
3. Cost of omission: faculty must reconstruct evidence relationships and coordinators must explain the UI. Inconsistent completion messages can send them back to already completed work. Time saved and institution-wide impact have not been measured.
4. Validation: the founder's difficulty and observed staging behavior are validated. Whether the proposed layout improves faculty performance remains a pilot hypothesis; it is not validated by the generated mockup.
5. Success: faculty identify their next task unaided, review evidence in one course, and obtain explainable results without entering technical IDs. If removed after a week, they should specifically miss the next-task guidance, preserved context and inline evidence explanation.

Proposed experience

The image illustrates spacing and hierarchy, not an exact permission model or real generated evidence. Implement with Kwilo tokens, Manrope and existing @kwilo/ui primitives. Preserve role-appropriate existing navigation until equivalent destinations are available. Keep Improvement and Readiness reachable; their omission from the image is not a removal decision.

• Course header shows name, code, programme, period and section. The right-hand Ask Kwilo button opens the familiar panel.
• Five persistent tasks: Outcomes, Assessments, Marks, Attainment, Course file. These are accessible tabs with status, not mandatory sequential pages; users can inspect later tasks before prerequisites are complete.
• A compact next-task card gives the missing item, reason, responsible role and a direct action. It remains useful with the assistant closed or unavailable.
• The main area contains outcome rows, mapping matrices, marks and results. The assistant explains and proposes; it does not duplicate large editors inside chat.
• Ask Kwilo displays course/task/source context, source links, a question composer and two or three relevant actions. A selected row can focus an explanation without changing the course.
• On wide screens dock the panel at approximately 380–420px. Dock only when at least 640px remains for the work area; otherwise use an accessible overlay drawer. At narrow/mobile widths use a full-width drawer. Keyboard users can close it with Escape and return to the opening control.
• Closing the panel preserves its current session. Changing tenant, actor or course aborts pending requests and clears that course's visible conversation before new content appears. Draft review work is saved independently.

Release boundaries

Release A — the mockup as a working course experience: honest task status, shared Ask Kwilo shell, outcomes review with saved progress, confirmed-syllabus citations, real grounded questions, explicit draft saving and existing approval actions. All five tabs remain usable through current editors, with readable task labels.

Release B — complete faculty workflow: contextual assistance for assessment and programme mappings, assessment picker, compatible evidence selection, coordinator-approved reusable course policy templates, explicit calculation/issuance, report drafting and improvement follow-up.

Release C — coordinator consolidation: programme setup in dependency order, scoped readiness, review coverage across the supported draft types and replacement of the primary Assistants navigation after capability parity is verified.

Each release is independently reviewable. A visual shell with a nonfunctional free-text composer is not Release A.

Outcome review and approval semantics

1. Reuse applicable approved outcomes by default. Offer a revised draft explicitly; never regenerate automatically on page load.
2. For a proposal, show all suggested rows with source citations. A reviewer may edit, mark reviewed, or exclude a row with a reason. Edits clear that row's reviewed mark.
3. Save review progress per actor, proposal and pinned input hash, including row decisions and edited content. Display Saving/Saved/Save failed accurately. Unsaved edits survive conflicts in memory for reconciliation.
4. Reviewing a row is not academic approval. Final Save reviewed draft uses the existing proposal acceptance path, preserving source validation and optimistic concurrency.
5. A separate Approve outcomes action uses the existing authorized outcome approval route. Do not introduce a new HOD role or infer approval authority from a title.
6. The current backend has draft/approved outcomes, not a submitted state. Release A therefore uses Save reviewed draft and Approve outcomes. A formal Submit for approval/assigned approver workflow is a separate product change; the mockup's footer must be corrected accordingly.
7. An approved revision remains immutable. Editing creates a new revision; issued evidence remains tied to its original inputs.

Existing queue accept-all currently approves complete selections and resumes the run. Replace the ambiguous UI path with draft-only acceptance and explicit subsequent approval; remove automatic advancement with publication side effects from acceptance. Retire the legacy accept-all route with a machine-readable conflict directing clients to the explicit flow once web clients have migrated. Do not silently reinterpret its old success response.

Task status and next action

Add a side-effect-free course workspace read model. It reads applicable source revisions and existing evidence, not only the stored orchestration stage. It must not call CourseRunService.resume, generate content, approve evidence or issue a result during a GET.

States: not_started, needs_input, in_review, ready, complete, stale, unavailable. An active generation is separate activity metadata. Unknown/loading/error is never Complete.

The workspace reports the five tasks, context fingerprint, selected applicable references, safe action identifiers and explicit selection conflicts. Count complete only for the required scope. A stored missing-paper blocker beside an existing approved blueprint requires reconciliation; do not mask the issue by ignoring evidence visibility or source eligibility.

Selection rules, in order:

1. Use an explicitly selected accessible revision, clearly labelled if historical.
2. Otherwise use the single compatible approved/current candidate under the pinned course configuration.
3. If none exists, show the exact missing input and owner.
4. If multiple candidates are compatible, require a decision; never pick the most recently created row merely because it is newest.

Later revisions make applicable previews stale; historical issued reports stay readable. Task status must distinguish 'issued result exists' from 'new evidence needs a new result'. CQI follow-up can remain open after a course result is issued.

Ask Kwilo architecture

Reuse Analytics' panel layout and composer style through a shared app-level presentation component. Keep Analytics' thread, query/card creation and pin behavior in its own adapter. Compliance must not reuse Analytics SQL tools or pin-to-dashboard semantics.

Compliance has two paths:

• Draft actions: map explicit action IDs to the existing obe-co-draft, obe-question-mapping, obe-program-mapping, obe-report-draft and obe-cqi-suggest contracts. Use existing proposal create/generate/review APIs, pinned inputs and idempotency keys. Results appear in the main editor.
• Questions: add a read-only obe-explain capability in the chatbot service, behind a new authorized webapp endpoint. Its bounded context is assembled by the backend from the selected course/task and permitted evidence. The model has no database, write, approval or arbitrary retrieval tools.

Typed replies contain prose, validated citations, references to backend-produced facts and optional allowlisted action suggestions. Sources are untrusted evidence. Validate citation spans against source text, fact references against the supplied facts and action references against the caller's permitted actions. Reject malformed references rather than rendering a plausible answer.

Numeric attainment values, exclusions and denominators are rendered from the deterministic fact pack. A model may explain those facts but cannot recalculate or overwrite them. General academic guidance is labelled as guidance, not an institution-approved rule.

Free-text requests to change records return a proposed action requiring an explicit user control. Asking a question, opening a panel or sending 'approve this' must not perform an academic mutation. Authentication and per-resource permissions are enforced again when the actual action executes.

Use the existing server-to-server agent client, model routing, entitlement/usage limits and sanitized errors. A non-streaming bounded request is sufficient for the first release; show real pending state without invented progress. Conversation history is session-only initially, at most six preceding messages with a total context budget; source data is always rebuilt and authorized server-side. No new permanent chat transcript table is required.

Zero-row results with unresolved reasons become Needs better source, not Ready for review. Show the explanation and direct syllabus repair action. Valid empty CQI results can mean no suggested action; a human can record their own decision. Provider failures retain the manual path and existing approved records.

Assessment, marks and policy behavior

• Replace Assessment reference entry with an authorized assessment picker showing course, title, date, source type and scoring readiness. Selecting an assessment binds existing evidence without duplicate assessment creation.
• Question/rubric mapping reuses allocation validation, including subparts, optional questions and exact marks conservation. Do not represent lab work as a written paper merely to fit the interface.
• CO–PO/PSO review defaults to an accessible matrix with per-cell rationale/source detail. Retain zero/unmapped explanations, framework edition and revision controls.
• Marks use the reviewed roster and compatible approved blueprint. Distinguish absent, exempt, missing and zero according to the approved method; totals-only evidence must not masquerade as measured CO attainment.
• Course attainment policies are currently offering-scoped. Programme rollup policies are different objects. Introduce versioned course policy templates for coordinator-approved reuse; bind an immutable copy to the offering with template provenance. Never treat a rollup policy as a course policy. Store templates as a distinct course-policy-templates kind in the existing programme revision lifecycle, preserving immutable approved definitions and hashes. Scheme is explicit reviewer-facing metadata; period applicability is checked against the course period. The course has no structured scheme identifier, so never infer a scheme match.
• Bind named policy components to approved assessment blueprints through explicit IDs stored in course configuration. Never require a human to type a blueprint UUID into component_id. Preserve existing issued calculations and support existing explicit batch/component selections.
• Review defaults before calculation; calculate a preview; review workings; then explicitly issue. Generic Continue must not publish a snapshot. Missing policy is a coordinator setup task, not an invitation for faculty to invent thresholds.
• Course file keeps draft, approved and issued reports distinct. Report narrative uses frozen evidence. Improvement action acceptance and later closure do not redefine whether a course result was issued.

Coordinator experience and navigation

Programme setup order: participation/accreditation edition → framework → course policy templates and separate rollup method → course/cohort scope and owners → evidence/review → surveys and programme attainment → reporting and improvement.

Readiness identifies programme, reporting period/cohort, included courses and exclusions. Links retain that context and open the specific missing item. Counts cannot imply accreditation assurance.

Retain current destinations during migration. Remove Assistants from primary navigation only when all five capabilities are reachable in context, with old links directing to an appropriate context selector or task. Do not discard working deep links, disabled-institution history or the Readiness/Improvement functions shown in the existing app.

Data and API additions

Workspace, questions, review-progress, course configuration and course-policy-template endpoints are implemented on the feature branch. Configuration uses an approved policy revision and named assessment bindings; applying an institution method creates a draft course copy requiring its own approval. Current mutation APIs remain authoritative for academic records.

Addition	Purpose
GET /obe/units/{unit}/offerings/{offering}/workspace	Fresh task state, allowed actions and input-selection conflicts; no side effects
POST /obe/units/{unit}/offerings/{offering}/assistant/ask	Read-only grounded answer, bound to a context fingerprint
GET/PUT /obe/units/{unit}/offerings/{offering}/proposals/{proposal}/review-progress	Per-user resumable draft review with expected revision/input hash
Course configuration API	Pins policy/template lineage and component-to-blueprint bindings with optimistic concurrency
Programme course-policy-template API	Create/revise/approve reusable course methods through existing programme-management authorization

New obe.proposal_review_progress and course configuration tables require additive Alembic migrations, tenant-scoped FKs/checks, indexes and RLS consistent with the OBE schema. Register models using existing OBE model aggregation. Do not alter historical proposal review payloads or issued snapshot hashes to backfill convenience state.

Verification and acceptance

• A user can complete outcomes review with Ask Kwilo closed; Ask Kwilo can answer a grounded course question and navigate to a source.
• Refresh preserves saved row decisions; editing or revising sources invalidates affected reviewed decisions; concurrent saves cannot silently overwrite each other.
• Page changes cannot display an old course's late reply in the new course; logout clears session conversation.
• Empty source, provider failure, revoked access and outdated evidence each have a clear, non-destructive recovery.
• New list/detail/question/progress/mutation endpoints reject cross-tenant references and enforce assigned course/program access. Test disabled/read-only institutional access separately.
• GET workspace, Ask, save draft and calculate preview never approve or issue. Existing permissions alone do not constitute a request to publish.
• Issued arithmetic matches an independently calculated fixture/workbook and remains unchanged after source edits; optional questions and absence cases are included.
• Responsive browser checks at 1440px, 1200px, 768px and 390px; no forced page overflow, keyboard-accessible tabs/matrix/drawer, focus return and status announcements.
• Pilot several faculty and a coordinator: target at least four of five faculty identifying the next task within 30 seconds; measure completion time before making savings claims.

Non-goals and rejected alternatives

• No relocation from Compliance into Classroom, new mobile app, accreditation framework rewrite, or replacement calculation engine.
• No general chat-first screen, standalone agent chooser as the primary entry, or autonomous record approval/publication.
• No persistent institution-wide chat memory in the first release, new LLM framework, direct browser-to-model calls or Analytics SQL access for Compliance.
• No requirement to finish CQI actions before issuing valid course results; no loss of prior approved evidence when AI fails.
• No automatic application of a universal NBA method or institution policy inferred from a course name.
• No assumed HOD/IQAC role, approval delegation change or submitted-state label without its own specified workflow.
• Overview/proctoring count mismatch and university consent terminology deserve separate fixes; they are not dependencies of the course workspace release.

Evidence and source baseline

Webapp source inspected at 0193e2a1d55792c9ec365f5334ce25b2655ca8d7; chatbot source at a97f63d6fd49fa27ae509e12af579d71f458f8d1. Browser audit was read-only in staging with administrative controls; faculty-role and new generation/calculation tests remain execution work.

The local feature template and feature README referenced by AGENTS were absent. This document follows the existing feature-doc structure and explicitly includes the Product Mindset Gate, behavior, non-goals, rejected alternatives and acceptance criteria.

Changelog

• 2026-09-25: proposed specification after source research, browser walkthrough, Ask Kwilo comparison and founder-requested visual concept. The visual's Submit for approval copy is corrected to the existing draft/approval lifecycle in Release A.

• 2026-09-25: Release A implementation adds evidence-derived tasks, resumable outcome review and grounded course questions. Synthetic browser checks cover refresh, edit-after-review, citations, draft saving, separate approval and responsive layouts. Web checks passed 198 tests plus the conversation-reopen regression; companion chatbot checks passed 50 tests. Real staging inference and faculty/workbook pilots remain rollout checks.

• 2026-09-25: Release C, first slice: programme page grouped into setup, evidence review and reporting in dependency order, with first-programme and coordinator empty states. Readiness gains period/cohort selection, a stated denominator and context-carrying links. The review queue copy now names the drafts it covers. Assistants stays in primary navigation until the parity checklist and the faculty pilot are done.

Readiness scope contract (implementation refinement)

Readiness asks for an academic period or an approved reporting cohort. It only auto-selects a period when exactly one is known. Period readiness includes the active programme curriculum, including courses with no Compliance workspace yet, and retains existing deliveries from inactive curriculum. Explicit period exclusions are shown separately. Multiple sections count as one curriculum course; every participating section must meet a requirement before that course counts as complete. An approved reporting cohort instead counts its explicitly reviewed course deliveries. Programme-wide history rows remain labelled separately from course scope until a cohort is selected; cohort-specific surveys and rollups are filtered to that cohort. Counts are evidence presence, not accreditation certification. When a programme has no known period, readiness still reports programme-level rows over an empty course denominator instead of asking for a choice with nothing to choose. The attainment-trend row stays programme-wide history under a cohort, because it counts cycles across cohorts; the rollup row narrows to the cohort.