recess-cli 3.0.0 → 3.1.0

package/dist/cli.js

@@ -9,6 +9,7 @@ import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, savePro
 import { agentContext, buildCommandSchema, findCommandSchema, remoteCommands, scopedHelp, validateInvocation, } from "./command-schema.js";
 import { runApplicationsCommand } from "./commands/applications.js";
 import { runAppsCommand } from "./commands/apps.js";
+import { readAssignmentSelection, runGoalCurriculumCommand, } from "./commands/goal-curriculum.js";
 import { runChatLogsCommand } from "./commands/chat-logs.js";
 import { runMasteryCommand } from "./commands/mastery.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
@@ -615,7 +616,7 @@ function assertOperationKeyMatchesPreview(operationKey, fingerprint, preview) {
         });
     }
 }
-async function requirePreviewBoundConfirmation(parsed, preview) {
+async function requirePreviewBoundConfirmation(parsed, preview, persistPreview = false) {
     const approvalToken = approvalTokenFor(preview);
     const suppliedOperationKey = flagString(parsed, "operation-key");
     const boundPreview = {
@@ -634,6 +635,9 @@ async function requirePreviewBoundConfirmation(parsed, preview) {
             action: preview.action,
             fingerprint: approvalToken,
             target: preview.target,
+            // Opted-in operations retain the approved receipt in the 0600 ledger so
+            // retries can reach server idempotency after their own write changed state.
+            ...(persistPreview ? { preview } : {}),
         });
         requireConfirmation(false, boundPreview);
     }
@@ -655,8 +659,8 @@ async function requirePreviewBoundConfirmation(parsed, preview) {
     });
     return { operationKey: suppliedOperationKey, fingerprint: approvalToken };
 }
-async function previewBoundWrite(parsed, preview, execute) {
-    const context = await requirePreviewBoundConfirmation(parsed, preview);
+async function previewBoundWrite(parsed, preview, execute, persistPreview = false) {
+    const context = await requirePreviewBoundConfirmation(parsed, preview, persistPreview);
     try {
         const result = await withIdempotencyContext(context, execute);
         await appendJobEvent({
@@ -688,6 +692,41 @@ async function previewBoundWrite(parsed, preview, execute) {
         throw error;
     }
 }
+async function readExecutedPreview(parsed) {
+    const key = flagString(parsed, "operation-key");
+    if (!hasFlag(parsed, "confirm") || !key)
+        return null;
+    const { history } = await getJob(key);
+    const receipt = [...history].reverse().find((event) => event.preview);
+    if (!receipt?.preview)
+        return null;
+    // First confirmation still refreshes server effects. A prior execution
+    // attempt is what makes a stale preflight an idempotent-recovery problem.
+    if (!history.some((event) => event.status !== "awaiting_confirmation" &&
+        event.fingerprint === receipt.fingerprint &&
+        event.action === receipt.action))
+        return null;
+    const saved = receipt.preview;
+    const fingerprint = approvalTokenFor(saved);
+    if (receipt.fingerprint !== fingerprint ||
+        flagString(parsed, "approval-token") !== fingerprint) {
+        throw new CliError("approval_mismatch", "This operation key does not match the approved command. Retry the original command unchanged, or review a new preview.");
+    }
+    assertOperationKeyMatchesPreview(key, fingerprint, saved);
+    return saved;
+}
+/** A retried write must retain its approved fence after changing its own source state. */
+async function recoverExecutedPreview(parsed, expected) {
+    const saved = await readExecutedPreview(parsed);
+    if (!saved)
+        return null;
+    if (saved.action !== expected.action ||
+        JSON.stringify(saved.target) !== JSON.stringify(expected.target) ||
+        JSON.stringify(saved.request) !== JSON.stringify(expected.request)) {
+        throw new CliError("approval_mismatch", "This operation key does not match the approved command. Retry the original command unchanged, or review a new preview.");
+    }
+    return saved;
+}
 async function cleanupPlannerUpload(api, conversationId, signed, includeDelete) {
     if (signed.kind === "multipart") {
         await api.client
@@ -3460,6 +3499,16 @@ export async function executeRecessCommand(argv, options = {}) {
         throw new CliError("invalid_arguments", "Use content-library search, status, set-stage, or submit.");
     }
     if (noun === "goal-templates") {
+        if (verb === "curriculum") {
+            return runGoalCurriculumCommand({
+                parsed,
+                api,
+                writeCommand,
+                resolveTemplateId: (value) => resolveGoalTemplateId(api, value),
+                previewBoundWrite: (args, preview, execute) => previewBoundWrite(args, preview, execute, true),
+                recoverExecutedPreview: (expected) => recoverExecutedPreview(parsed, expected),
+            });
+        }
         const readTemplateDocument = async () => {
             if (!isRemote) {
                 return readJsonFile(flagString(parsed, "file", { required: true }), "Template file");
@@ -3618,6 +3667,174 @@ export async function executeRecessCommand(argv, options = {}) {
                 body: document,
             })));
         }
+        if (verb === "policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            return unwrap(await api.client.GET("/ai/goal-templates/{id}/policy", {
+                params: { path: { id } },
+            }));
+        }
+        if (verb === "set-policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const target = flagString(parsed, "target-modules");
+            const minimum = flagString(parsed, "required-modules");
+            for (const [flag, value] of [
+                ["target-modules", target],
+                ["required-modules", minimum],
+            ]) {
+                if (value === undefined ||
+                    (flag === "required-modules" && value === "all"))
+                    continue;
+                const count = Number(value);
+                if (!Number.isInteger(count) || count < 1 || count > 20)
+                    throw new CliError("invalid_arguments", `--${flag} must be an integer from 1 through 20${flag === "required-modules" ? " or all" : ""}.`);
+            }
+            if (target === undefined && minimum === undefined)
+                throw new CliError("invalid_arguments", "Provide --target-modules or --required-modules N|all");
+            const body = {
+                recipeKey: flagString(parsed, "recipe", { required: true }),
+                ...(target === undefined ? {} : { targetModuleCount: Number(target) }),
+                ...(minimum === undefined
+                    ? {}
+                    : {
+                        requiredModuleCount: minimum === "all" ? null : Number(minimum),
+                    }),
+                expectedVersion: requiredExpectedVersion(parsed),
+            };
+            const requestPreview = {
+                action: "edit shared goal-template assigned target or completion minimum",
+                target: { templateId: id, apiOrigin: api.config.apiOrigin },
+                request: body,
+            };
+            const receipt = await recoverExecutedPreview(parsed, requestPreview);
+            const preview = receipt ?? {
+                ...requestPreview,
+                details: unwrap(await api.client.POST("/ai/goal-templates/{id}/policy", {
+                    params: { path: { id } },
+                    body: { ...body, dryRun: true },
+                })),
+            };
+            // A recovered receipt only skips the now-stale preview. The actual write
+            // still reaches server authorization, idempotency, and expectedVersion.
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/policy", {
+                params: { path: { id } },
+                body: { ...body, dryRun: false },
+            })), true);
+        }
+        if (verb === "migrate-policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const studentIds = flagString(parsed, "students", { required: true })
+                .split(",")
+                .map((value) => value.trim());
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/policy-migration", {
+                params: { path: { id } },
+                body: { studentIds, dryRun: true },
+            }));
+            const preview = {
+                action: "backfill reviewed goal policy identities and migration holds",
+                target: { templateId: id, studentIds },
+                request: { studentIds, fingerprint: preflight.fingerprint },
+                details: preflight,
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/policy-migration", {
+                params: { path: { id } },
+                body: {
+                    studentIds,
+                    fingerprint: preflight.fingerprint,
+                    dryRun: false,
+                },
+            })));
+        }
+        if (verb === "retire-assignments") {
+            const [id, session] = await Promise.all([
+                resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug")),
+                api.client.GET("/auth/admin-cli/session/").then(unwrap),
+            ]);
+            if (session.user.role !== "ADMIN" || session.cliScope !== "full_admin")
+                throw new CliError("forbidden", "Assignment retirement requires a full-admin session.");
+            const goalId = flagString(parsed, "goal", { required: true });
+            const rawIds = flagString(parsed, "todos");
+            const selectionPath = flagString(parsed, "todos-file");
+            if (Boolean(rawIds) === Boolean(selectionPath))
+                throw new CliError("invalid_arguments", "Choose exactly one of --todos or --todos-file with explicit assignment IDs.");
+            const selection = selectionPath
+                ? await readAssignmentSelection(selectionPath)
+                : null;
+            const todoIds = selection?.todoIds ?? rawIds.split(",").map((id) => id.trim());
+            if (!todoIds.length ||
+                todoIds.length > 500 ||
+                todoIds.some((id) => !id) ||
+                new Set(todoIds).size !== todoIds.length)
+                throw new CliError("invalid_arguments", "Choose 1–500 distinct assignment IDs explicitly.");
+            const reason = flagString(parsed, "retirement-reason", {
+                required: true,
+            });
+            const requestPreview = {
+                action: "retire the selected curriculum assignments without completing lessons",
+                target: {
+                    templateId: id,
+                    goalId,
+                    actorId: session.user.id,
+                    apiOrigin: api.config.apiOrigin,
+                },
+                request: { todoIds, reason, selectionFile: selection?.file ?? null },
+            };
+            const receipt = await recoverExecutedPreview(parsed, requestPreview);
+            const preflight = receipt
+                ? receipt.details
+                : unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/assignments/retire", {
+                    params: { path: { id, goalId } },
+                    body: { todoIds, reason, dryRun: true },
+                }));
+            const preview = receipt ?? {
+                ...requestPreview,
+                details: preflight,
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/assignments/retire", {
+                params: { path: { id, goalId } },
+                body: {
+                    todoIds,
+                    reason,
+                    fingerprint: preflight.fingerprint,
+                    dryRun: false,
+                },
+            })));
+        }
+        if (verb === "student-policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const goalId = flagString(parsed, "goal", { required: true });
+            const filePath = path.resolve(flagString(parsed, "file", { required: true }));
+            const bytes = await fs.readFile(filePath);
+            let raw;
+            try {
+                raw = JSON.parse(bytes.toString("utf8"));
+            }
+            catch {
+                throw new CliError("invalid_arguments", "Student policy edit must contain valid JSON");
+            }
+            // Backend Zod is authoritative; preserve exact file bytes in the approval preview.
+            const body = raw;
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/policy", {
+                params: { path: { id, goalId } },
+                body: { ...body, dryRun: true },
+            }));
+            const preview = {
+                action: "review a student policy override or migration hold",
+                target: { templateId: id, goalId },
+                request: body,
+                details: {
+                    ...preflight,
+                    file: {
+                        absolutePath: filePath,
+                        sizeBytes: bytes.byteLength,
+                        sha256: createHash("sha256").update(bytes).digest("hex"),
+                    },
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/policy", {
+                params: { path: { id, goalId } },
+                body: { ...body, dryRun: false },
+            })));
+        }
         if (verb === "patch-spec") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const expectedVersion = requiredExpectedVersion(parsed);
@@ -5085,7 +5302,40 @@ export async function executeRecessCommand(argv, options = {}) {
                 required: true,
             });
             const checkout = await readRecessGitMetadata(sourceDirectory);
-            const local = await readGoalWorkspaceGitChanges(checkout.root, checkout.metadata.upstreamCommit);
+            const isGoal = checkout.metadata.target.kind === "goal";
+            const session = isGoal
+                ? unwrap(await api.client.GET("/auth/admin-cli/session/"))
+                : null;
+            const actionDescription = `push committed Git changes to a student's Mesa ${checkout.metadata.target.kind} workspace`;
+            const boundTarget = session
+                ? {
+                    studentId: checkout.metadata.studentId,
+                    workspace: checkout.metadata.target,
+                    actorId: session.user.id,
+                    apiOrigin: api.config.apiOrigin,
+                }
+                : null;
+            const receipt = isGoal ? await readExecutedPreview(parsed) : null;
+            if (receipt &&
+                (receipt.action !== actionDescription ||
+                    JSON.stringify(receipt.target) !== JSON.stringify(boundTarget) ||
+                    receipt.request.sourceDirectory !== checkout.root)) {
+                throw new CliError("approval_mismatch", "The approved push belongs to a different checkout, account, or API.");
+            }
+            const localBaseCommit = receipt
+                ? String(receipt.request.localBaseCommit)
+                : checkout.metadata.upstreamCommit;
+            const mesaBaseChangeId = receipt
+                ? String(receipt.request.mesaBaseChangeId)
+                : checkout.metadata.changeId;
+            const local = await readGoalWorkspaceGitChanges(checkout.root, localBaseCommit);
+            if (receipt &&
+                ((checkout.metadata.upstreamCommit !== localBaseCommit &&
+                    checkout.metadata.upstreamCommit !== local.head) ||
+                    (checkout.metadata.upstreamCommit === localBaseCommit &&
+                        checkout.metadata.changeId !== mesaBaseChangeId))) {
+                throw new CliError("approval_mismatch", "The checkout's upstream metadata moved outside the approved push.");
+            }
             const defaultMessage = local.commits.length === 1
                 ? local.commits[0].subject
                 : `recess-cli: push ${local.commits.length} commits (${local.commits.at(-1).subject})`;
@@ -5106,36 +5356,44 @@ export async function executeRecessCommand(argv, options = {}) {
                 target: checkout.metadata.target,
                 message,
                 files,
-                expectedChangeId: checkout.metadata.changeId,
+                expectedChangeId: mesaBaseChangeId,
             };
-            const preflight = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
-                body: { ...body, dryRun: true },
-            }));
-            if (preflight.action !== "preview_workspace_files_write") {
+            const preflight = receipt
+                ? null
+                : unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: { ...body, dryRun: true },
+                }));
+            if (preflight && preflight.action !== "preview_workspace_files_write") {
                 throw new CliError("unexpected_response", "Goal workspace push did not return a preview; nothing was written.");
             }
-            const preview = {
-                action: `push committed Git changes to a student's Mesa ${checkout.metadata.target.kind} workspace`,
-                target: preflight.target,
-                request: {
-                    sourceDirectory: checkout.root,
-                    mesaBaseChangeId: checkout.metadata.changeId,
-                    localBaseCommit: checkout.metadata.upstreamCommit,
-                    localHeadCommit: local.head,
-                    commits: local.commits,
-                    message,
-                    changes: local.changes.map((change) => change.action === "delete"
-                        ? change
-                        : {
-                            path: change.path,
-                            action: change.action,
-                            sizeBytes: change.sizeBytes,
-                            sha256: change.sha256,
-                        }),
-                    sizeBytes: local.sizeBytes,
-                },
+            const request = {
+                sourceDirectory: checkout.root,
+                mesaBaseChangeId,
+                localBaseCommit,
+                localHeadCommit: local.head,
+                commits: local.commits,
+                message,
+                changes: local.changes.map((change) => change.action === "delete"
+                    ? change
+                    : {
+                        path: change.path,
+                        action: change.action,
+                        sizeBytes: change.sizeBytes,
+                        sha256: change.sha256,
+                    }),
+                sizeBytes: local.sizeBytes,
+            };
+            if (receipt &&
+                JSON.stringify(receipt.request) !== JSON.stringify(request)) {
+                throw new CliError("approval_mismatch", "The command or committed file bytes differ from the approved push.");
+            }
+            const preview = receipt ?? {
+                action: actionDescription,
+                target: boundTarget ?? preflight.target,
+                request,
                 details: {
                     currentChangeId: preflight.currentChangeId,
+                    resolvedTarget: preflight.target,
                     note: "The committed local diff is published as one atomic Mesa change. Deletes and renames follow Git's diff. A changed Mesa tip refuses the push.",
                 },
             };
@@ -5146,6 +5404,11 @@ export async function executeRecessCommand(argv, options = {}) {
                 if (result.action !== "write_workspace_files") {
                     throw new CliError("unexpected_response", "Goal workspace push returned an unexpected response.");
                 }
+                if (receipt &&
+                    checkout.metadata.upstreamCommit === local.head &&
+                    checkout.metadata.changeId !== result.changeId) {
+                    throw new CliError("approval_mismatch", "The acknowledged checkout revision does not match this recovered push. Its local metadata was preserved.");
+                }
                 await writeRecessGitMetadata(checkout.root, {
                     ...checkout.metadata,
                     changeId: result.changeId,
@@ -5158,7 +5421,7 @@ export async function executeRecessCommand(argv, options = {}) {
                         upstreamCommit: local.head,
                     },
                 };
-            });
+            }, isGoal);
         }
         if (action === "write") {
             const studentId = flagString(parsed, "student", { required: true });
@@ -5179,25 +5442,47 @@ export async function executeRecessCommand(argv, options = {}) {
                 message,
                 files: input.files,
             };
-            const preflight = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
-                body: { ...body, dryRun: true },
-            }));
-            if (preflight.action !== "preview_workspace_files_write") {
+            const session = goalId
+                ? unwrap(await api.client.GET("/auth/admin-cli/session/"))
+                : null;
+            const request = {
+                source: input.source,
+                sourceSha256: input.sha256,
+                fileCount: input.files.length,
+                sizeBytes: input.sizeBytes,
+                message,
+            };
+            const boundTarget = session
+                ? {
+                    studentId,
+                    goalId: goalId,
+                    actorId: session.user.id,
+                    apiOrigin: api.config.apiOrigin,
+                }
+                : null;
+            const receipt = boundTarget
+                ? await recoverExecutedPreview(parsed, {
+                    action: "batch-upsert files in a student's goal workspace",
+                    target: boundTarget,
+                    request,
+                })
+                : null;
+            const preflight = receipt
+                ? null
+                : unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: { ...body, dryRun: true },
+                }));
+            if (preflight && preflight.action !== "preview_workspace_files_write") {
                 throw new CliError("unexpected_response", "Goal workspace write did not return a preview; nothing was written.");
             }
-            const preview = {
+            const preview = receipt ?? {
                 action: "batch-upsert files in a student's goal workspace",
-                target: preflight.target,
-                request: {
-                    source: input.source,
-                    sourceSha256: input.sha256,
-                    fileCount: input.files.length,
-                    sizeBytes: input.sizeBytes,
-                    message,
-                },
+                target: boundTarget ?? preflight.target,
+                request,
                 details: {
                     currentChangeId: preflight.currentChangeId,
                     files: preflight.files,
+                    resolvedTarget: preflight.target,
                     note: target.kind === "draft"
                         ? "This writes a complete authoring tree under drafts/<slug>/workspace. Capture it only after the server's goal-workspace validation passes."
                         : "This directly edits the live goal workspace, including modules/ and state/. The write remains bound to the previewed workspace revision.",
@@ -5207,9 +5492,9 @@ export async function executeRecessCommand(argv, options = {}) {
                 body: {
                     ...body,
                     dryRun: false,
-                    expectedChangeId: preflight.currentChangeId,
+                    expectedChangeId: String(preview.details.currentChangeId),
                 },
-            })));
+            })), Boolean(goalId));
         }
         throw new CliError("invalid_arguments", "Use goals files list|read|init|checkout|push|write.");
     }

package/dist/commands/goal-curriculum.js

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { unwrap } from "../api.js";
+import { flagString } from "../args.js";
+import { CliError } from "../errors.js";
+import { flagInteger, positional } from "./shared.js";
+/** Selection files only supply explicit IDs; they never expand a filter into a mutation. */
+export async function readAssignmentSelection(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const stat = await fs.stat(absolutePath);
+    if (!stat.isFile() || stat.size > 1024 * 1024) {
+        throw new CliError("invalid_arguments", "The assignment selection must be a regular JSON file no larger than 1 MiB.");
+    }
+    const bytes = await fs.readFile(absolutePath);
+    let document;
+    try {
+        document = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new CliError("invalid_arguments", "The assignment selection must contain valid JSON.");
+    }
+    if (!document ||
+        typeof document !== "object" ||
+        Array.isArray(document) ||
+        Object.keys(document).length !== 1 ||
+        !("todoIds" in document) ||
+        !Array.isArray(document.todoIds) ||
+        !document.todoIds.every((id) => typeof id === "string")) {
+        throw new CliError("invalid_arguments", 'The selection file must contain exactly {"todoIds":["assignment-uuid", ...]}.');
+    }
+    return {
+        todoIds: document.todoIds,
+        file: {
+            absolutePath,
+            sizeBytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+        },
+    };
+}
+async function readResolutions(filePath) {
+    const absolutePath = path.resolve(filePath);
+    let bytes;
+    try {
+        const stat = await fs.stat(absolutePath);
+        if (!stat.isFile() || stat.size > 1024 * 1024) {
+            throw new CliError("invalid_arguments", "The resolution file must be a regular JSON file no larger than 1 MiB.");
+        }
+        bytes = await fs.readFile(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `File not found: ${absolutePath}`);
+        }
+        throw error;
+    }
+    let document;
+    try {
+        document = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new CliError("invalid_arguments", "The resolution file must contain valid JSON.");
+    }
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+        throw new CliError("invalid_arguments", "The resolution file must contain a JSON object.");
+    }
+    // The backend validates document version, choices, conflict IDs, and whether
+    // each choice is supported by the current three-way comparison.
+    return {
+        document: document,
+        file: {
+            absolutePath,
+            sizeBytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+        },
+    };
+}
+export async function runGoalCurriculumCommand({ parsed, api, resolveTemplateId, previewBoundWrite, recoverExecutedPreview, }) {
+    const verb = positional(parsed, 2, "curriculum operation");
+    const [id, session] = await Promise.all([
+        resolveTemplateId(positional(parsed, 3, "template ID or slug")),
+        api.client.GET("/auth/admin-cli/session/").then(unwrap),
+    ]);
+    if (session.user.role !== "ADMIN" || session.cliScope !== "full_admin") {
+        throw new CliError("forbidden", "Curriculum updates require a full-admin session.");
+    }
+    const environment = {
+        actorId: session.user.id,
+        apiOrigin: api.config.apiOrigin,
+    };
+    if (verb === "status" || verb === "retry") {
+        const jobId = flagString(parsed, "job", { required: true });
+        if (verb === "status") {
+            return unwrap(await api.client.GET("/ai/goal-templates/{id}/curriculum/jobs/{jobId}", {
+                params: { path: { id, jobId } },
+            }));
+        }
+        const requestPreview = {
+            action: "resume the previously approved curriculum job",
+            target: { templateId: id, jobId, ...environment },
+            request: {},
+        };
+        const receipt = await recoverExecutedPreview(requestPreview);
+        const preview = receipt ?? {
+            ...requestPreview,
+            details: {
+                job: unwrap(await api.client.GET("/ai/goal-templates/{id}/curriculum/jobs/{jobId}", {
+                    params: { path: { id, jobId } },
+                })),
+                note: "Resumes this job's stored scope and resolutions. Completed goals are not replayed; stale goals require a new preview.",
+            },
+        };
+        return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/curriculum/jobs/{jobId}/retry", {
+            params: { path: { id, jobId } },
+            body: {},
+        })));
+    }
+    const goalIds = flagString(parsed, "goals", { required: true })
+        .split(",")
+        .map((value) => value.trim());
+    if (goalIds.some((value) => !value) ||
+        new Set(goalIds).size !== goalIds.length) {
+        throw new CliError("invalid_arguments", "--goals must list distinct, nonempty goal IDs.");
+    }
+    if (verb === "backlog") {
+        const dueBefore = flagString(parsed, "due-before");
+        return unwrap(await api.client.GET("/ai/goal-templates/{id}/curriculum/backlog", {
+            params: {
+                path: { id },
+                query: { goalIds: goalIds.join(","), dueBefore },
+            },
+        }));
+    }
+    const targetVersion = flagInteger(parsed, "version", {
+        required: true,
+        min: 1,
+    });
+    const filePath = flagString(parsed, "resolutions-file", {
+        required: verb === "validate-resolutions",
+    });
+    const resolutionFile = filePath ? await readResolutions(filePath) : undefined;
+    const body = {
+        goalIds,
+        targetVersion,
+        resolutions: resolutionFile?.document ?? { version: 1, resolutions: [] },
+    };
+    const requestPreview = {
+        action: verb === "reverse"
+            ? "merge a prior template curriculum version into the selected student goals"
+            : "merge the selected template curriculum version into the selected student goals",
+        target: { templateId: id, goalIds, ...environment },
+        request: { ...body, resolutionFile: resolutionFile?.file ?? null },
+    };
+    const receipt = verb === "apply" || verb === "reverse"
+        ? await recoverExecutedPreview(requestPreview)
+        : null;
+    const comparison = receipt
+        ? receipt.details?.comparison
+        : unwrap(await api.client.POST("/ai/goal-templates/{id}/curriculum/preview", {
+            params: { path: { id } },
+            body,
+        }));
+    if (verb === "preview" || verb === "validate-resolutions") {
+        return { ...comparison, resolutionFile: resolutionFile?.file ?? null };
+    }
+    if (verb !== "apply" && verb !== "reverse") {
+        throw new CliError("invalid_arguments", "Use curriculum backlog|preview|validate-resolutions|apply|status|retry|reverse.");
+    }
+    const preview = receipt ?? {
+        ...requestPreview,
+        details: {
+            comparison,
+            note: "Only the exact selected goals are included. Unresolved conflicts block their goal. Assignments and earned history remain protected; reverse updates preserve changes made since the earlier version.",
+        },
+    };
+    return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/curriculum/apply", {
+        params: { path: { id } },
+        body: {
+            ...body,
+            fingerprint: comparison.fingerprint,
+            operationKey: flagString(parsed, "operation-key", {
+                required: true,
+            }),
+        },
+    })));
+}
+//# sourceMappingURL=goal-curriculum.js.map

package/dist/help.js

@@ -339,6 +339,29 @@ Usage:
     [--kind SIMPLE|BLUEPRINT] [--starter-only] [--include-deleted]
     [--limit 20] [--cursor <id>]
   recess [--json] goal-templates get <template-id|slug> [--spec-only]
+  recess [--json] goal-templates policy <template-id|slug>
+  recess [--json] goal-templates set-policy <template-id|slug> --recipe KEY
+    [--target-modules N] [--required-modules N|all] --expected-version N
+    [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates migrate-policy <template-id|slug> --students ID,ID
+    [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates student-policy <template-id|slug> --goal ID
+    --file <path/edit.json> [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates retire-assignments <template-id|slug> --goal ID
+    [--todos ID,ID | --todos-file <path/selection.json>]
+    --retirement-reason TEXT [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates curriculum backlog <template-id|slug>
+    --goals ID,ID [--due-before YYYY-MM-DD]
+  recess [--json] goal-templates curriculum preview <template-id|slug>
+    --goals ID,ID --version N [--resolutions-file <path/resolutions.json>]
+  recess [--json] goal-templates curriculum validate-resolutions <template-id|slug>
+    --goals ID,ID --version N --resolutions-file <path/resolutions.json>
+  recess [--json] goal-templates curriculum apply|reverse <template-id|slug>
+    --goals ID,ID --version N [--resolutions-file <path/resolutions.json>]
+    [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates curriculum status <template-id|slug> --job ID
+  recess [--json] goal-templates curriculum retry <template-id|slug> --job ID
+    [--confirm --approval-token TOKEN]
   recess [--json] goal-templates versions <template-id> [--version N]
   recess [--json] goal-templates validate-spec --file <path/template.json>
   recess [--json] goal-templates create --file <path/template.json>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {