feat: imported-course mode for needs-analysis, assessment-design, course-builder (#9)

* feat: imported-course mode for needs-analysis, assessment-design, course-builder

Three skills assumed net-new course design and broke down for imported courses
(TMC-430 test report issues #7, #13, #14). Each now branches early on
import_metadata.source:

- needs-analysis: skips the "is training the right intervention?" decision
  gate for credit-bearing imports (the registrar can't be told to remove the
  course); records justification automatically and runs a design-fit check.

- assessment-design: adds Mode 3 (Audit Existing Assessments) alongside the
  existing Mode 1/Mode 2 split. Reads existing rubrics, classifies on Bloom's,
  compares to ILOs, surfaces alignment gaps. Does NOT propose new assessments
  unless asked. Mode 3 takes precedence over Mode 1.

- course-builder: adds gap-fill mode triggered when import_metadata.source is
  set and course_content.modules is non-empty. Generates ONLY artifacts
  upstream skills flagged as missing, instead of regenerating syllabus,
  modules, and rubrics that already exist in the cartridge.

All three skills announce the chosen mode at the start of the conversation,
so the user can override if auto-detection is wrong.

Canonical schema gains optional needs_analysis.mode, assessments.mode,
course_content.mode (record the mode), assessments.audit_notes[] (Mode 3
output), and course_content.recommended_generation_targets[] (gap-fill
output). Additive — no schema version bump.

assessment-design also switches its manifest write to bin/idstack-manifest-merge
(landed in v2.1.0.0), eliminating the misleading "include the COMPLETE schema
structure" instruction.

Smoke test grows from 150 to 153 assertions: each mode-aware skill template
must reference import_metadata.source (drift guard).

Resolves test-report issues #7, #13, #14.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: address Gemini code review findings on PR #9

Two corrections from Gemini Code Assist's review of this PR:

- assessment-design: the manifest-write text said "writes two sections —
  assessments and learning_objectives.alignment_matrix.ilo_to_assessment" but
  the merge tool operates on top-level sections only, and Mode 3 also writes
  to learning_objectives.alignment_matrix.gaps. Clarified to "writes two
  top-level sections — assessments and learning_objectives" with a note about
  reading-then-merging the full learning_objectives section before passing
  it to the merge tool.

- course-builder: gap-fill mode instructions referenced
  course_builder_notes.recommended_generation_targets and
  course_builder_notes.mode, but the canonical schema (and the
  course_content.generated_files reference in the same sentence) puts these
  under course_content. Real bug — Claude following the skill would write to
  a section that isn't whitelisted by bin/idstack-manifest-merge. Renamed
  both to course_content.

Smoke test 153/153 unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: philippos savvides <philippossavvides@mac.lan>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v2.3.0.0 (2026-05-02)
+
+### Added
+- **Imported-course mode for `needs-analysis`, `assessment-design`, and `course-builder`.** The TMC-430 test report flagged that these skills assume net-new course design and break down for imported courses. Each now branches early on `import_metadata.source`:
+  - `needs-analysis` skips the "is training the right intervention?" decision gate for credit-bearing imports (the registrar can't be told to remove the course); records the rationale and confidence automatically and runs a "design-fit" check instead.
+  - `assessment-design` adds **Mode 3: Audit Existing Assessments** alongside the existing Mode 1/Mode 2 split. Reads the existing rubrics from the cartridge, classifies criteria on Bloom's, compares to ILOs, and surfaces alignment gaps — does NOT propose new assessments unless the user explicitly asks. Mode 3 takes precedence over Mode 1.
+  - `course-builder` adds **gap-fill mode** triggered when `import_metadata.source` is set and `course_content.modules` is non-empty. Generates ONLY the artifacts upstream skills flagged as missing (e.g., a missing rubric, a formative practice quiz set), instead of regenerating the syllabus, modules, and rubrics that already exist in the cartridge.
+  - All three skills announce the chosen mode at the start of the conversation so the user can override if the auto-detection is wrong.
+  - Resolves test-report issues #7, #13, #14.
+- **Canonical schema additions** (additive, no version bump): optional `needs_analysis.mode`, `assessments.mode`, `course_content.mode` (record which mode the skill ran in); `assessments.audit_notes[]` (Mode 3 outputs); `course_content.recommended_generation_targets[]` (gap-fill mode outputs). Per-section item shapes documented in `templates/manifest-schema.md`.
+- **`assessment-design` switches to `bin/idstack-manifest-merge`.** Replaces the inline-write pattern (with its misleading "Include the COMPLETE schema structure" instruction) with two scoped merge calls — one for `assessments`, one for `learning_objectives`. Same atomic-write benefits introduced in v2.1.0.0.
+
+### Changed
+- Smoke test now runs 153 assertions (was 150). New: each of the 3 mode-aware skill templates must reference `import_metadata.source` (drift guard against accidental removal of the mode-detection branch).
+
 ## v2.2.0.1 (2026-05-02)
 
 ### Fixed

VERSION

@@ -1 +1 @@
-2.2.0.1
+2.3.0.0

skills/accessibility-review/SKILL.md

@@ -597,6 +597,7 @@ The merge tool replaces only the named top-level section, preserves every other
     "available_tech": []
   },
   "needs_analysis": {
+    "mode": "",
     "organizational_context": {
       "problem_statement": "",
       "stakeholders": [],
@@ -633,6 +634,7 @@ The merge tool replaces only the named top-level section, preserves every other
     "expertise_reversal_flags": []
   },
   "assessments": {
+    "mode": "",
     "assessment_strategy": "",
     "items": [],
     "formative_checkpoints": [],
@@ -642,9 +644,11 @@ The merge tool replaces only the named top-level section, preserves every other
       "peer_review": false
     },
     "feedback_quality_score": 0,
-    "rubrics": []
+    "rubrics": [],
+    "audit_notes": []
   },
   "course_content": {
+    "mode": "",
     "generated_at": "",
     "expertise_adaptation": "",
     "syllabus": "",
@@ -654,7 +658,8 @@ The merge tool replaces only the named top-level section, preserves every other
     "content_dir": ".idstack/course-content/",
     "generated_files": [],
     "build_timestamp": "",
-    "placeholders_used": []
+    "placeholders_used": [],
+    "recommended_generation_targets": []
   },
   "import_metadata": {
     "source": "",
@@ -876,6 +881,37 @@ These document the **shape of array elements and dictionary values** that the ca
 }
 ```
 
+### Mode field — design-new vs audit-existing
+
+`needs_analysis.mode`, `assessments.mode`, and `course_content.mode` record which operating mode the corresponding skill ran in. Trigger: `import_metadata.source` ∈ `{cartridge, scorm, canvas-api}` plus the relevant section being non-empty (skill-specific check).
+
+Allowed values per skill:
+- `needs_analysis.mode`: `"design-new"` or `"audit-existing"`
+- `assessments.mode`: `"Mode 1"`, `"Mode 2"`, or `"Mode 3"` (Mode 1 = full upstream data, Mode 2 = ILOs-from-scratch, Mode 3 = audit existing assessments)
+- `course_content.mode`: `"build-new"` or `"gap-fill"`
+
+Empty string means the skill hasn't run yet or didn't record the mode (legacy manifests).
+
+**`assessments.audit_notes[]`** — only populated in Mode 3. Records which audit findings the user chose to act on:
+```json
+{
+  "target_id": "A-3",
+  "action": "applied|deferred|declined",
+  "description": "Rubric criterion for ILO-2 added: 'Synthesis depth (1-4 scale)'.",
+  "reason": "Optional — only meaningful for deferred/declined."
+}
+```
+
+**`course_content.recommended_generation_targets[]`** — populated in `gap-fill` mode. Lists artifacts upstream skills flagged as missing, with status:
+```json
+{
+  "description": "Discussion rubric for Module 5",
+  "source": "red-team:alignment-3 | quality-review:learner_support-2 | user-request",
+  "status": "generated|deferred|declined",
+  "output_path": "Optional — set when status=generated, points to the generated file."
+}
+```
+
 ## Feedback
 
 Have feedback or a feature request? [Share it here](https://forms.gle/6LDgDD1M6WWyYvME8) — no GitHub account needed.

skills/assessment-design/SKILL.md

@@ -317,7 +317,7 @@ fi
 
 ## Pipeline Context Check
 
-Determine your operating mode based on available data.
+Determine your operating mode based on available data. **Check Mode 3 first** — it's the more specific case (imported course with existing assessments) and takes precedence over Mode 1 even when both conditions hold.
 
 ### Mode 1: Full Upstream Data
 
@@ -355,6 +355,38 @@ cognitive process) before proceeding to assessment design. Use the same classifi
 approach as the `/learning-objectives` skill: ask for clarification when verbs are
 ambiguous [Alignment-12] [T2].
 
+### Mode 3: Audit Existing Assessments
+
+**Condition (BOTH must be true):**
+- `import_metadata.source` is one of `cartridge`, `scorm`, `canvas-api`
+- `assessments.items` is non-empty (course-import populated it) OR `course_content.assessments` is non-empty (cartridge has assessment artifacts)
+
+**Announce the chosen mode to the user as the first sentence:**
+
+> "Mode 3: audit-existing. The imported course already contains [N] assessments and [M] rubrics — I'll audit them against your ILOs rather than designing new ones from scratch. If you want to add new assessments, say 'design more' at any point."
+
+**What audit-existing does (and doesn't do):**
+
+- ✅ Reads existing rubrics from the manifest (`assessments.rubrics`) or from the cartridge files referenced by `course_content.rubrics`.
+- ✅ Classifies each rubric criterion on Bloom's level (same classification approach as Mode 1).
+- ✅ Compares to the course ILOs from `learning_objectives.ilos`. Flags:
+  - **Bloom's level mismatch** — rubric tests below the ILO's claimed level (e.g., ILO says "analyze" but rubric criteria are "list/describe").
+  - **Untested ILOs** — an ILO has no rubric criterion measuring it.
+  - **Orphaned criteria** — a rubric criterion doesn't measure any stated ILO.
+  - **Missing rubric** — an assessment has weight ≥10% but no rubric.
+  - **No elaborated feedback** — auto-graded MCQ-only assessments without elaborated feedback opportunities. [Assessment-8] [T1]
+- ✅ Output: an audit table per assessment, plus 1-3 rubric-improvement recommendations.
+- ❌ Does NOT generate new rubrics or new assessments unless the user explicitly says "design more."
+
+**Audit workflow steps (replaces Steps 1-4 of the design workflow below):**
+
+1. **Inventory.** List every assessment from `assessments.items` (or derived from cartridge if items is empty). Note type, title, weight, ILOs claimed.
+2. **Per-assessment Bloom's mapping.** For each assessment, examine its rubric criteria and classify each on Bloom's. Record in `assessments.items[].alignment_status` (`"weak" | "moderate" | "strong"` per the canonical schema) based on whether the criteria collectively reach the ILO's claimed level.
+3. **Cross-walk.** Build a `learning_objectives.alignment_matrix.gaps[]` entries for each Bloom-mismatch, untested ILO, or orphaned criterion. Use the canonical `gaps[]` shape: `{ilo, type, description, severity}`.
+4. **Recommendations.** Surface the top 1-3 fixes — usually rubric criterion edits, not new assessments. If the user wants to act on them, propose specific edits and apply via `Edit`. Track applied/deferred fixes in a new optional `assessments.audit_notes` array.
+
+When done, write the manifest using `bin/idstack-manifest-merge` (see "Write Manifest" below). Skip the rest of this skill (Steps 1-4 of the design workflow are for design-new mode only).
+
 ---
 
 ## Assessment Design Workflow
@@ -593,19 +625,32 @@ Consider adding a formative peer review checkpoint to partially address the gap.
 
 ## Write Manifest
 
-Create or update the project manifest at `.idstack/project.json`.
+Save results to `.idstack/project.json` via `bin/idstack-manifest-merge`. The merge tool
+replaces only the named section, preserves every other section verbatim, validates JSON,
+and atomically updates the top-level `updated` timestamp. **This skill writes two
+top-level sections** — `assessments` and `learning_objectives` — so call the merge tool
+twice (once per section). The `learning_objectives` write needs to update the
+`alignment_matrix.ilo_to_assessment` mapping (and in Mode 3, the
+`alignment_matrix.gaps` array as well). Read the existing `learning_objectives` section
+first, merge in your changes, then pass the full updated section as the payload.
 
-**CRITICAL — Manifest Integrity Rules:**
-1. If a manifest already exists, READ it first with the Read tool. Then modify ONLY
-   the `assessments` section and the `learning_objectives.alignment_matrix.ilo_to_assessment`
-   mapping. Preserve all other sections unchanged.
-2. Include the COMPLETE schema structure. Do not omit fields.
-3. Before writing, mentally verify the JSON is valid: matching braces, proper commas,
-   quoted strings, no trailing commas.
-4. The `updated` timestamp must reflect the current time.
-5. If this is a new manifest (no needs analysis or learning objectives were run),
-   initialize ALL sections with empty/default values so downstream skills find the
-   expected structure.
+```bash
+# Section 1: assessments
+"$_IDSTACK/bin/idstack-manifest-merge" --section assessments --payload - <<'PAYLOAD'
+<the assessments payload — see field shape below>
+PAYLOAD
+
+# Section 2: learning_objectives (full section, with updated alignment_matrix)
+# Read existing learning_objectives, merge in the new ilo_to_assessment mapping
+# (and in Mode 3, the new gaps[] entries), then pass the full updated section here.
+"$_IDSTACK/bin/idstack-manifest-merge" --section learning_objectives --payload - <<'PAYLOAD'
+<the merged learning_objectives payload>
+PAYLOAD
+```
+
+If `bin/idstack-manifest-merge` is unavailable: fall back to manual write (Read manifest, modify only the two sections, Write back, preserve all others).
+
+If `.idstack/project.json` does not exist yet, run `bin/idstack-migrate .idstack/project.json` first — that creates a fresh canonical manifest. The merge tool then merges into it.
 
 **Populate the `assessments` section:**
 
@@ -746,6 +791,7 @@ The merge tool replaces only the named top-level section, preserves every other
     "available_tech": []
   },
   "needs_analysis": {
+    "mode": "",
     "organizational_context": {
       "problem_statement": "",
       "stakeholders": [],
@@ -782,6 +828,7 @@ The merge tool replaces only the named top-level section, preserves every other
     "expertise_reversal_flags": []
   },
   "assessments": {
+    "mode": "",
     "assessment_strategy": "",
     "items": [],
     "formative_checkpoints": [],
@@ -791,9 +838,11 @@ The merge tool replaces only the named top-level section, preserves every other
       "peer_review": false
     },
     "feedback_quality_score": 0,
-    "rubrics": []
+    "rubrics": [],
+    "audit_notes": []
   },
   "course_content": {
+    "mode": "",
     "generated_at": "",
     "expertise_adaptation": "",
     "syllabus": "",
@@ -803,7 +852,8 @@ The merge tool replaces only the named top-level section, preserves every other
     "content_dir": ".idstack/course-content/",
     "generated_files": [],
     "build_timestamp": "",
-    "placeholders_used": []
+    "placeholders_used": [],
+    "recommended_generation_targets": []
   },
   "import_metadata": {
     "source": "",
@@ -1025,6 +1075,37 @@ These document the **shape of array elements and dictionary values** that the ca
 }
 ```
 
+### Mode field — design-new vs audit-existing
+
+`needs_analysis.mode`, `assessments.mode`, and `course_content.mode` record which operating mode the corresponding skill ran in. Trigger: `import_metadata.source` ∈ `{cartridge, scorm, canvas-api}` plus the relevant section being non-empty (skill-specific check).
+
+Allowed values per skill:
+- `needs_analysis.mode`: `"design-new"` or `"audit-existing"`
+- `assessments.mode`: `"Mode 1"`, `"Mode 2"`, or `"Mode 3"` (Mode 1 = full upstream data, Mode 2 = ILOs-from-scratch, Mode 3 = audit existing assessments)
+- `course_content.mode`: `"build-new"` or `"gap-fill"`
+
+Empty string means the skill hasn't run yet or didn't record the mode (legacy manifests).
+
+**`assessments.audit_notes[]`** — only populated in Mode 3. Records which audit findings the user chose to act on:
+```json
+{
+  "target_id": "A-3",
+  "action": "applied|deferred|declined",
+  "description": "Rubric criterion for ILO-2 added: 'Synthesis depth (1-4 scale)'.",
+  "reason": "Optional — only meaningful for deferred/declined."
+}
+```
+
+**`course_content.recommended_generation_targets[]`** — populated in `gap-fill` mode. Lists artifacts upstream skills flagged as missing, with status:
+```json
+{
+  "description": "Discussion rubric for Module 5",
+  "source": "red-team:alignment-3 | quality-review:learner_support-2 | user-request",
+  "status": "generated|deferred|declined",
+  "output_path": "Optional — set when status=generated, points to the generated file."
+}
+```
+
 ## Feedback
 
 Have feedback or a feature request? [Share it here](https://forms.gle/6LDgDD1M6WWyYvME8) — no GitHub account needed.