v1.21.0

CloudPedagogy Course Engine v1.21.0

Governance Snapshot Contract

Release summary

v1.21.0 introduces a formal governance snapshot contract, completing a key step in the Course Engine’s evolution into a governance‑safe, CI‑ready course infrastructure.

This release provides a deterministic, facts‑only snapshot interface that allows institutions, reviewers, and automation systems to capture and compare the inspectable state of a course without triggering builds, validation, or evaluation.

v1.21.0 does not add new enforcement rules or quality judgements. Instead, it strengthens transparency, auditability, and change‑tracking while preserving human ownership of interpretation and decision‑making.

---

✨ Key features

🧾 Governance snapshot (course-engine snapshot)

• New snapshot command emitting a minimal, diff‑friendly record of course state
• Supports both:
  • source snapshots (course.yml), and
  • artefact snapshots (manifest‑backed build outputs)
• Designed for:
  • CI and automation
  • governance and QA review
  • change tracking and archival

Snapshots are:

• non‑evaluative
• contract‑stable
• deterministic (timestamps aside)
• safe for automated comparison

---

📜 Snapshot JSON contract (v1)

• Versioned, documented JSON shape
• Deterministic field ordering
• Canonical hashing of governance‑relevant components
• Policy information surfaced only when policy resolution occurs
• No inference, scoring, or judgement

This contract is suitable for long‑term institutional use.

---

🔍 Explain mode clarifications

Documentation and behaviour now explicitly distinguish:

• Source explain
  • strict, pre‑normalisation
  • authoring‑time inspection
• Artefact explain
  • canonical, manifest‑backed
  • governance‑authoritative

This removes ambiguity in QA, CI, and audit workflows.

---

📦 Governance pack reliability

• Pack tests no longer depend on committed dist/ artefacts
• Tests now construct isolated artefacts at runtime
• Improves reproducibility and CI robustness

---

🧠 Design principles reinforced

v1.21.0 reinforces the Course Engine’s core commitments:

• facts, not verdicts
• transparency over automation
• inspection over enforcement
• governance without compliance theatre
• human judgement remains central

---

🚫 Explicit non‑goals

This release does not:

• evaluate pedagogical quality
• enforce design intent or AI scoping
• introduce automated approval or compliance
• mutate inputs or outputs
• replace human governance processes

---

🔁 Relationship to recent releases

• v1.20.0 introduced CI‑grade preflight contracts (course-engine check)
• v1.21.0 completes the governance layer by adding a stable course‑state snapshot interface

Together, these releases establish a clear separation between:
environment inspection, state capture, explanation, and validation.

---

📌 Upgrade notes

• No breaking changes
• Fully backwards compatible
• Snapshot is additive and opt‑in
• Existing workflows continue unchanged unless snapshot is invoked

---

🏷 Release tag

• Git tag: v1.21.0
• Branch merged to: master

---

Design principle
The Course Engine reports facts. Humans remain responsible for interpretation and judgement.

v1.20.0 — CI-grade preflight contract and deterministic checks

v1.20.0 — CI-grade preflight contract and deterministic checks

This release introduces a stable, machine-readable preflight diagnostic contract intended for CI pipelines, onboarding workflows, and support tooling, alongside full documentation alignment.

✨ New

• course-engine check preflight interface

  • Deterministic, non-destructive system diagnostics
  • Verifies Python environment, Quarto, Pandoc, PDF (LaTeX), and filesystem write access
  • Designed for onboarding, CI, and support contexts

• Contract-stable JSON output

  • --format json produces a documented, versioned structure
  • Safe to consume programmatically in automation and dashboards
  • Includes environment context, tool presence, PDF readiness, and requirement evaluation

• Deterministic exit codes

  • --strict mode enforces required dependencies
  • Exit codes are explicit and reliable for CI use
  • Non-strict mode remains informational and non-blocking

📚 Documentation

• Handbook updated to reflect the preflight contract as first-class infrastructure
• End-user instructions aligned with real CLI behaviour
• README and changelog clarified for v1.20.0 semantics
• Clear separation reinforced between:
  • inspection and diagnostics
  • validation and policy enforcement
  • pedagogical judgement and tooling

🧭 Design intent

• Preflight checks are informational diagnostics, not quality or compliance assertions
• The Course Engine continues to prioritise:
  • human judgement over automation
  • transparency over optimisation
  • governance support without enforcement

🔒 Stability & compatibility

• No breaking changes to existing course build, explain, report, or validate workflows
• Safe to adopt incrementally
• Backwards compatible with existing course specifications

---

This release formalises the Course Engine’s role as infrastructure for responsible, auditable course production, extending reliability and trust into automated and institutional contexts without shifting responsibility away from human authors.

Course Engine v1.19.0 — Explicit Preflight Diagnostics & CI-Safe Check Output

Release notes

Highlights

• Introduces an explicit, format-selectable preflight diagnostics interface via course-engine check.
• Adds human-readable diagnostics alongside a stable, machine-readable JSON payload suitable for CI, onboarding, and support workflows.
• Clarifies and hardens CLI behaviour without introducing any new validation or enforcement logic.

---

Release description

✨ What’s new

Preflight diagnostics (v1.19.0)

course-engine check now provides a first-class, script-safe diagnostics surface:

• --format text — clear, human-readable environment checks:

  • Python version and platform
  • Quarto and Pandoc presence/version
  • PDF (LaTeX / TinyTeX) readiness
  • Actionable remediation guidance when tools are missing

• --format json — stable, machine-readable output designed for:

  • CI pipelines
  • automated support checks
  • onboarding and environment verification tooling

The legacy --json flag remains supported for compatibility, but --format is now the preferred selector.

---

🔒 Behaviour guarantees

• No schema changes
• No build, render, validation, or governance behaviour changes
• Fully backward compatible with existing check --json workflows
• Non-destructive and safe to run repeatedly

---

📚 Documentation updates

Updated README, End-User Instructions, and Course Engine Handbook to:

• reflect the new preflight diagnostics capability,
• clarify human vs machine output modes,
• reinforce the engine’s governance-first, non-prescriptive design philosophy.

---

🧹 Internal quality improvements

• Minor lint and typing clean-ups
• Hardened __main__ entrypoint behaviour
• Expanded test coverage for preflight JSON output

---

🧭 Why this matters

v1.19.0 strengthens the Course Engine’s role as infrastructure for responsible course production by making environment readiness explicit, inspectable, and automation-friendly — without shifting judgement or responsibility away from the human user.

This is a confidence and adoption release, particularly for institutional, CI, and multi-machine workflows.

v1.18.1 – Governance Pack Profiles & Stable CLI Entrypoint

v1.18.1 – Governance Pack Profiles & Stable CLI Entrypoint

Overview

v1.18 introduces profile-based governance pack composition and completes the
facts-only governance packaging workflow, allowing institutions to generate
deterministic, non-evaluative evidence packs for audit, QA, and lightweight
handover contexts.

v1.18.1 additionally restores and stabilises the python -m course_engine
entrypoint, ensuring consistent CLI behaviour across environments and CI
pipelines.

This release is fully backward compatible and introduces no new validation
or enforcement behaviour.

---

🚀 New in v1.18 (core development work)

Profile-based governance pack composition

• course-engine pack now requires an explicit pack profile:
  • audit
  • qa
  • minimal
• Profiles determine which factual artefacts are included in the generated
  governance pack.
• Profile selection is validated at the CLI layer to prevent ambiguous outputs.

Facts-only governance packs

• Governance packs are:
  • deterministic
  • composition-only
  • policy-agnostic
  • non-evaluative by design
• Packs may be generated from:
  • a course project directory, or
  • a built artefact directory containing manifest.json.

Generated pack README

• Each governance pack includes a generated README.txt that:
  • explains the purpose and limits of the pack,
  • records the selected profile,
  • lists included artefacts,
  • documents generation context.
• README content is explicitly governance-safe and avoids interpretive claims.

---

🛠 Fixed in v1.18.1 (stability & release hygiene)

CLI entrypoint restored

• Restored and stabilised python -m course_engine
• Clarified separation between:
  • Typer callback (global options),
  • CLI command registration,
  • Python module entrypoint (__main__.py)
• Ensures consistent behaviour for:
  • local development
  • CI pipelines
  • institutional automation

No behavioural changes

• No changes to:
  • governance pack contents
  • validation logic
  • build or render outputs

---

Behaviour guarantees

• No schema changes
• No enforcement or validation behaviour introduced
• No impact on existing build pipelines
• Fully backward compatible with v1.17.x

---

Governance positioning

This release completes the governance packaging layer:

• The engine computes facts
• Packs bundle those facts without judgement
• Institutions decide how packs are interpreted or used

v1.18 establishes a stable foundation for downstream:

• QA workflows
• audit review
• external assurance
• CI evidence capture

---

Notes on versioning

• v1.18.0 and v1.18.1 are intentionally aligned
• The v1.18.1 tag should be treated as the canonical v1.18 release
• Users should upgrade to v1.18.1 for the fully stabilised CLI experience

v1.17.0 — Governance pack finalisation & workflow hardening

Course Engine v1.17.0 — Workflow Hardening & Governance Pack Finalisation

Release type: Minor (non-breaking)
Focus: Usability, workflow reliability, and governance artefact handling
Audience: End users, maintainers, QA and governance stakeholders

---

Overview

v1.17.0 is a workflow hardening and ergonomics release.

It introduces no schema changes, no new validation rules, and no enforcement behaviour.

Instead, this release focuses on:

• making governance pack generation robust and unambiguous,
• aligning the CLI with real-world user workflows, and
• improving scriptability and CI integration without altering the engine’s governance posture.

All existing courses, manifests, and policies remain fully compatible.

---

What’s new

1. Governance pack command finalised (course-engine pack)

The pack command is now production-ready and stable.

It generates a facts-only governance pack containing:

• explain.json and explain.txt
• summary.txt
• manifest.json (copied when packing from a built artefact)
• optional capability coverage reports (when capability mapping is present)
• a machine-readable pack_manifest.json describing inputs and contents

The pack command:

• never builds or renders content
• never enforces policies
• never evaluates pedagogical quality

It is intended for QA review, audit, assurance, and evidence exchange.

---

2. Artefact auto-detection for common workflows

From v1.17 onward, course-engine pack accepts:

• a direct artefact directory containing manifest.json, or
• a parent output directory if it contains exactly one artefact subdirectory

This matches common user behaviour (e.g. pointing at dist/) while preserving
deterministic and unambiguous governance output.

If multiple candidate artefacts are found, the engine fails with a clear,
human-readable error listing the detected options.

No guessing or silent assumptions are introduced.

---

3. Explicit artefact path emission on build

On successful build, the engine now prints the resolved artefact path:

ARTEFACT=dist/<course-id>

This small change significantly improves:

• scripting and automation
• CI/CD pipelines
• downstream use of explain, validate, and pack

The artefact path is now trivially reusable without path reconstruction or inspection.

---

What has not changed

This release intentionally does not change:

• course schema or authoring rules
• manifest structure
• capability mapping behaviour
• governance signals or policy interpretation
• validation semantics
• explainability contracts

v1.17 reinforces existing design principles rather than extending them.

---

Why this release matters

Institutions adopting Course Engine often move quickly from:

• individual authoring → QA → governance review → automation

v1.17 reduces friction at that transition point by:

• making artefact boundaries explicit,
• stabilising governance pack outputs, and
• improving integration into scripted and institutional workflows.

All without increasing enforcement or constraining academic practice.

---

Compatibility & upgrade notes

• Fully backward compatible with all v1.x courses
• No migration steps required
• Existing demo courses and policies continue to work unchanged

---

Verification

This release has been verified using:

• full test suite execution
• end-to-end demo course builds
• governance pack generation from artefact and parent output directories
• explain, inspect, report, and validate sanity checks

Maintainers should run scripts/verify-release.sh prior to tagging.

---

Summary

v1.17.0 completes the governance pack workflow and improves
day-to-day usability without altering Course Engine’s governance contract.

It is a stability and readiness release, intended to support
real-world institutional adoption with confidence.

CloudPedagogy Course Engine v1.16.0

CloudPedagogy Course Engine v1.16.0

---

Release summary

v1.16.0 is a release hygiene and workflow hardening update.

This release introduces no schema changes, no new validation rules, and no enforcement behaviour.
Instead, it focuses on ensuring that the Course Engine’s release process, artefact handling, and maintainer workflows are correct, reproducible, and governance-safe.

---

What’s improved

Artefact path semantics hardened

All commands that operate on built outputs now consistently expect the directory that actually contains manifest.json:

• course-engine explain
• course-engine validate
• course-engine pack

If a parent directory is supplied accidentally, the CLI fails fast with a clear, deterministic error message.

This prevents a common class of mistakes in:

• CI pipelines
• QA and audit workflows
• smoke tests and scripted verification

---

Smoke test made path-safe

scripts/smoke_test.sh has been hardened to:

• build demo courses into a known output directory,
• reliably resolve the correct child artefact directory (dist/<course-id>),
• always run explain, validate, and pack against the correct artefact path.

This makes the smoke test reliable for:

• new contributors,
• automated CI checks,
• institutional reproducibility and verification workflows.

---

Release version consistency guaranteed

The following are now fully aligned and verifiable during release:

• CLI-reported version
• Python package metadata version
• build artefact provenance (manifest.json)

This eliminates version drift between:

• installed binaries,
• reported CLI output,
• and generated course artefacts.

---

Pack command stabilised

v1.16.0 introduces a hardened MVP implementation of course-engine pack:

• deterministic output structure,
• explicit artefact detection (source vs built artefact),
• clear error handling for invalid inputs.

The resulting pack output is suitable for:

• QA review,
• audit submission,
• archival and portability workflows.

---

What did not change

• ❌ No course schema changes
• ❌ No new validation logic
• ❌ No policy or enforcement behaviour
• ❌ No changes to build or render outputs

All changes are fully backward compatible.

---

Why this release matters

v1.16.0 strengthens the Course Engine’s role as a governance-credible, audit-safe tool by ensuring that:

• artefact paths are unambiguous,
• maintainer workflows are reproducible,
• CLI behaviour matches real institutional usage patterns.

This is a trust-building release, not a feature expansion.

---

Documentation updates

• README updated for v1.16.0 positioning
• End User Instructions clarified for current CLI semantics
• Smoke test behaviour aligned with artefact path rules
• CHANGELOG updated with full release context

---

Installation

pip install course-engine==1.16.0

Editable install (developers):

pip install -e .

Verify installation:

course-engine --version

---

Release metadata

• Version: v1.16.0
• Tag: v1.16.0
• Branch: master
• Release type: Release hygiene & workflow hardening

---

© CloudPedagogy

v1.15.0 – Explainability & Summary Clarity

CloudPedagogy Course Engine v1.15.0

v1.15.0 is a clarity and explainability refinement release.

It introduces no schema changes, no new validation rules, and no enforcement behaviour.
Instead, it focuses on making course-engine explain outputs accurate, non-interpretive, and safe for governance communication.

This release strengthens trust, precision, and governance credibility without changing the engine’s underlying behaviour.

---

✅ Highlights

Explain mode inference fixed

• course-engine explain now reliably distinguishes between:
  • source projects (course.yml), and
  • built artefacts (directories containing manifest.json)
• Eliminates ambiguous or incorrect explain output when pointing at build directories.

Summary output clarified

• Summary output now reports:
  • Generated at (UTC) instead of Built at (UTC)
• Avoids implying that a build or render occurred when running explain-only commands.

Non-interpretive capability wording

• Capability mapping status in summaries is now reported as:
  • present: yes | no
• Avoids implying completeness, quality, or evaluation.

Email- and report-safe summaries

• course-engine explain --summary is now designed to be:
  • one-screen,
  • non-judgemental,
  • safe to paste directly into emails, QA notes, or governance papers.

---

🧭 Governance posture (unchanged)

• No new enforcement introduced
• No changes to course schema
• No changes to validation behaviour
• No changes to build or render outputs
• Fully backward compatible with v1.14.x

---

📦 Included in this release

• Updated CLI explain logic
• Refined summary wording and labels
• Documentation updates (README, CHANGELOG, adoption guidance)

---

🔖 Versioning

• Tag: v1.15.0
• Manifest schema: unchanged
• Explain JSON contract: unchanged

---

📖 Documentation

See:

• README.md
• CHANGELOG.md
• docs/ADOPTING_IN_AN_INSTITUTION.md

---

CloudPedagogy Course Engine remains a governance-credible tool that records facts, surfaces declared intent, and supports audit and QA conversations — without automated judgement or enforcement.

CloudPedagogy Course Engine v1.14.0

Stability & Governance Credibility Release

Summary

v1.14.0 is a stability, consistency, and release-credibility release.

It introduces no changes to course schema, validation logic, or governance behaviour.
Instead, it focuses on ensuring that the Course Engine can be trusted, verified, and defensibly released in institutional, QA, and audit contexts.

This release formalises version alignment, release verification, and maintainer workflows to support long-term reliability.

---

What’s new in v1.14.0

Version alignment hardened

• CLI version, Python package version, and build metadata are fully aligned
• Version consistency is explicitly verified as part of release checks
• Eliminates ambiguity between installed version, artefact metadata, and documentation

Release verification workflow formalised

• Introduces a maintainer-facing release verification script:
  • scripts/verify-release.sh
• Verifies:
  • CLI and package version consistency
  • linting, typing, and test health
  • demo course build and manifest generation
  • explain output integrity (source and artefact)
  • policy explain resolution stability

This supports institutional QA, audit, CI, and external review workflows.

This script is not intended for routine development use.

Smoke test clarified (developer sanity check)

• scripts/smoke_test.sh is explicitly positioned as:
  • a fast “does it basically work?” check
  • suitable for local development and environment validation
• Clear separation between:
  • developer confidence (smoke test)
  • release credibility (verify-release)

Repository hygiene improvements

• Ignore rules clarified to avoid accidental masking of tracked content
• Build artefacts and local caches cleanly separated from source control
• Demo content and examples structured for clarity and reuse

---

What has not changed

v1.14.0 does not change:

• course.yml schema
• capability mapping behaviour
• validation rules or enforcement
• governance signal semantics
• explain output structure
• policy evaluation logic

This release is intentionally non-behavioural.

---

Why this release matters

Institutions increasingly require tools that are not just functional, but defensible:

• predictable versioning
• reproducible artefacts
• auditable build outputs
• transparent release processes

v1.14.0 strengthens the Course Engine’s position as a governance-credible production tool without introducing automation, scoring, or enforcement.

---

Recommended usage

Developers

Run smoke tests during development:

bash scripts/smoke_test.sh

Maintainers / release managers

Run full release verification before merging, tagging, or external sharing:

bash scripts/verify-release.sh

---

Documentation updates

• README updated with v1.14 overview
• Changelog updated with release notes
• End-user instructions clarify maintainer vs developer workflows

---

Release metadata

• Tag: v1.14.0
• Commit: 6874861

---

Closing note

v1.14.0 is about trust.

It ensures that when the CloudPedagogy Course Engine is used in curriculum QA, accreditation evidence, AI governance discussions, or external institutional review, the tool itself does not introduce uncertainty.

v1.13.1 — AI Scoping, Governance Signals, and Design Rationale Consolidation

v1.13.1 — AI Scoping, Governance Signals, and Design Rationale Consolidation

Release summary

This release consolidates the v1.13 governance model with final documentation, handbooks, and design records. It formalises AI scoping, absence signals, and policy-driven interpretation as stable, inspectable infrastructure for QA, audit, and institutional review — without introducing automated judgement or compliance enforcement.

No breaking changes are introduced.

---

Overview

v1.13.1 is a stability and documentation release that completes the v1.13 development cycle.

It finalises the design, rationale, and governance documentation for features introduced in v1.13, ensuring the Course Engine is defensible, auditable, and institution-ready.

Behaviour is unchanged from v1.13.0.

---

Key concepts finalised in v1.13.x

1. AI scoping (v1.13)

Courses may declare explicit, structural AI use boundaries via an optional ai_scoping block in course.yml.

AI scoping:

• records permitted, restricted, and expected AI use
• is machine-readable and manifest-backed
• is informational only (not enforced)
• can suppress advisory absence signals about missing AI boundaries

This cleanly separates:

• why AI is positioned a certain way (design_intent)
• what AI use is allowed or constrained (ai_scoping)

---

2. Governance absence signals

The engine records absence signals in manifest.json when governance-relevant elements are missing (e.g. intent, framework alignment, AI boundaries).

Absence signals:

• are computed automatically
• are advisory by default
• do not block builds
• are interpreted only via policy

This supports QA and review conversations without turning governance into compliance automation.

---

3. Policy-driven interpretation (not enforcement)

Policies define:

• validation thresholds
• signal interpretation (ignore, info, warn, error)
• escalation behaviour for CI contexts

The engine computes facts.
Policies decide what matters.

---

4. Explainability as a contract-stable interface

The explain-only JSON interface (--explain --json) is now explicitly documented as:

• read-only
• contract-stable within major versions
• policy-resolution only (no course facts)
• suitable for CI, dashboards, and governance tooling

Governance facts remain tied to build artefacts (manifest.json).

---

Documentation and handbooks

This release updates and regenerates all canonical documentation, including:

• Course Engine Handbook (Handbook A) — responsible use
• Design & Rationale Handbook (Handbook B) — architectural intent
• Explainability JSON contract
• Policy files guide
• End-user instructions
• v1.13.1 design notes and lessons learned

Markdown sources remain canonical. Word and PDF artefacts are derived.

---

What this release does not do

• No automated approval or compliance decisions
• No pedagogical quality inference
• No mandatory AI usage
• No enforcement of frameworks

---

Why this release matters

v1.13.1 marks the point where the Course Engine becomes:

• governance-credible
• institution-ready
• capability-driven rather than tool-driven
• explicit about human–AI boundaries

It establishes a stable foundation for future work (v1.14+) without retrofitting governance later.

---

Upgrade notes

• Existing courses continue to work unchanged
• ai_scoping is optional
• Absence signals remain advisory unless policies opt into escalation
• Explain outputs remain stable and backward-compatible

v1.11.0 — Explainability Contract & Governance Documentation

v1.11.0 focuses on governance clarity, explainability, and documentation stability.

This release introduces a contract-defined explainability output for the Course Engine, making policy resolution, provenance inspection, and configuration review safe to rely on in CI pipelines, dashboards, and audit workflows — without asserting pedagogical quality or compliance.

Key improvements include:

Explainability & Governance

• Introduced a contract-stable explainability JSON format for inspection and tooling
• Clarified explain-only policy inspection semantics (no validation, no quality claims)
• Documented format selection (--format json|text) with backward compatibility for --json
• Explicit separation between declarative alignment and defensible capability mapping

Documentation & Handbooks

• Updated README and end-user instructions to reflect explainability and validation behaviour
• Refined Handbook A (Course Engine Handbook) to clarify responsibility, limits, and workflows
• Refined Handbook B (Design & Rationale) to document governance-driven design decisions
• Regenerated authoritative PDF and DOCX handbook artefacts from canonical Markdown

Design Records & Structure

• Normalised the v1.10 design record to Markdown
• Added an explicit explainability JSON contract document for downstream tooling
• Minor metadata and project configuration updates

What This Release Does Not Do

• It does not introduce new validation rules
• It does not automate approval or compliance decisions
• It does not change the human–AI responsibility model

v1.11.0 strengthens the Course Engine’s role as governance-aware infrastructure: transparent, inspectable, and intentionally non-evaluative.

Tag: v1.11.0
Branch: master