@seanmars/tospec 0.19.0-beta.8 → 0.20.0

package/dist/commands/workflow/instructions.js

@@ -1,73 +1,68 @@
 /**
- * Instructions Command
- *
- * Generates enriched instructions for creating artifacts or applying tasks.
- * Includes both artifact instructions and apply instructions.
+ * `tospec instructions` — enriched briefs for creating an artifact, or for the
+ * apply phase.
  */
 import path from 'path';
 import * as fs from 'fs';
 import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
 import { getChangeDir, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
 import { resolveRootForCommand, toPlanningHome, toRootOutput, } from '../../core/root-selection.js';
-import { readProjectConfig } from '../../core/project-config.js';
-import { parseTasksFromContent } from '../../utils/task-progress.js';
+import { APPLY_RULES_KEY, readProjectConfigWithDiagnostics } from '../../core/project-config.js';
+import { parseTasksFromContent, resolveTaskFiles } from '../../utils/task-progress.js';
 import { validateChangeExists, validateSchemaExists, assertChangeSchema, } from './shared.js';
 import { emitSuccess } from '../shared-output.js';
-// -----------------------------------------------------------------------------
-// Types
-// -----------------------------------------------------------------------------
 /**
- * The `--json` null-shape.
- *
- * This command's success payload is flat — `instruction`, `state`, `tasks` and
- * the rest sit at the top level, and the skill templates read them from there —
- * so there is no wrapper key to null. The shape therefore nulls `instruction`,
- * which both success shapes (artifact and apply) actually carry; the previous
- * `instructions: null` named a key that appeared in neither, so the rule
- * "a failure payload mirrors its success payload with the data keys nulled"
- * could not be checked against anything.
+ * The `--json` null-shape. This command's success payload is flat, so there is
+ * no wrapper key to null; `instruction` is the one key both success shapes
+ * (artifact and apply) carry.
  *
- * Exported so the commander-level shape table and this command's own catch
- * block cannot drift apart — they did, and only one of them carried `root`.
+ * Exported so the commander-level shape table and this command's catch block
+ * cannot drift apart.
  */
 export const INSTRUCTIONS_FAILURE_PAYLOAD = {
     instruction: null,
     root: null,
 };
 /**
- * The one argument this command accepts that is not a schema artifact: it asks
- * for the apply phase rather than a document to write.
- *
- * Exported so the CLI's dispatch and the "valid arguments" list read the same
- * value — they did not, and the list left `apply` out (round 4 report 13).
+ * The one argument this command accepts that is not a schema artifact. Exported
+ * so the CLI's dispatch and the "valid arguments" list read one value.
  */
 export const APPLY_ARGUMENT = 'apply';
-// -----------------------------------------------------------------------------
-// Artifact Instructions Command
-// -----------------------------------------------------------------------------
-export async function instructionsCommand(artifactId, options) {
-    const root = await resolveRootForCommand(options, { json: options.json });
+async function resolveInstructionsTarget(options) {
+    // No implicit root, as `status`: "Change 'x' not found. No changes exist."
+    // about a directory that is no project sends the agent to `new change`
+    // instead of `init`.
+    const root = await resolveRootForCommand(options, {
+        json: options.json,
+        allowImplicitRoot: false,
+        failurePayload: INSTRUCTIONS_FAILURE_PAYLOAD,
+    });
     if (!root) {
-        return;
+        return null;
     }
-    const planningHome = toPlanningHome(root);
     const projectRoot = root.path;
-    // Validate the schema before resolving the change (round 4 report 15): after
-    // it, the guard never fired in an empty project, so the caller was told to
-    // create a change first and only then learned the schema was never usable.
     if (options.schema) {
         validateSchemaExists(options.schema, projectRoot);
         assertChangeSchema(options.schema);
     }
-    const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint: 'tospec new change <name>' });
-    // loadChangeContext will auto-detect schema from metadata if not provided
+    const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, {
+        newChangeHint: 'tospec new change <name>',
+    });
+    return { root, planningHome: toPlanningHome(root), projectRoot, changeName };
+}
+export async function instructionsCommand(artifactId, options) {
+    const target = await resolveInstructionsTarget(options);
+    if (!target) {
+        return;
+    }
+    const { root, planningHome, projectRoot, changeName } = target;
+    // The schema comes from the change's metadata when not given.
     const context = loadChangeContext(projectRoot, changeName, options.schema, {
         changeDir: getChangeDir(planningHome, changeName),
         planningHome,
     });
-    // Round 4 report 13. The list came from the schema's artifacts alone, so it
-    // omitted `apply` — the one argument this command accepts that is not an
-    // artifact, and the one a reader who mistyped is most likely to have wanted.
+    // Includes `apply`: the schema's artifacts alone omit the one valid argument
+    // that is not an artifact.
     const validArgumentList = () => [...context.graph.getAllArtifacts().map((a) => a.id), APPLY_ARGUMENT].join('\n  ');
     if (!artifactId) {
         throw new Error(`Missing required argument <artifact>. Valid arguments:\n  ${validArgumentList()}`);
@@ -76,24 +71,91 @@ export async function instructionsCommand(artifactId, options) {
     if (!artifact) {
         throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'. Valid arguments:\n  ${validArgumentList()}`);
     }
-    // readProjectConfig never throws: missing/unparseable configs are null.
-    const projectConfig = readProjectConfig(root.path);
+    // Never throws: a missing or unparseable config comes back null with the
+    // reason in `diagnostics`.
+    const { config: projectConfig, diagnostics: configDiagnostics } = readProjectConfigWithDiagnostics(root.path);
     const instructions = generateInstructions(context, artifactId, projectRoot, {
         projectConfig,
+        configDiagnostics,
     });
     const isBlocked = instructions.dependencies.some((d) => !d.done);
+    // `status` says "skipped" for this artifact, so a brief that reads as a
+    // plain "write it" sends an agent into the contradiction `validate` rejects
+    // (marker set, spec files present). Said first, in both output modes.
+    const isSkipped = context.skippedArtifacts?.has(artifactId) ?? false;
     if (options.json) {
-        emitSuccess({ ...instructions }, toRootOutput(root));
+        // `configWarnings` becomes `status[]`, the envelope field every command
+        // reports non-fatal trouble in.
+        const { configWarnings, ...payload } = instructions;
+        // First, ahead of any config warning: it is the one entry telling an agent
+        // not to write the artifact yet. The alternative is inferring it from
+        // `dependencies[].done`.
+        const status = [
+            ...skippedDiagnostics(instructions, changeName, isSkipped),
+            ...blockedDiagnostics(instructions, changeName),
+            ...(configWarnings ?? []).map(({ code, message }) => ({
+                severity: 'warning',
+                code,
+                message,
+            })),
+        ];
+        emitSuccess({
+            ...payload,
+            ...(status.length ? { status } : {}),
+        }, toRootOutput(root));
         return;
     }
-    printInstructionsText(instructions, isBlocked);
+    printInstructionsText(instructions, isBlocked, { skipped: isSkipped });
+}
+/**
+ * The "declared away" warning, as a `status[]` entry — the JSON half of the
+ * `<warning>` block the human output prints. Empty unless the change's
+ * metadata skips this artifact.
+ */
+function skippedDiagnostics(instructions, changeName, skipped) {
+    if (!skipped)
+        return [];
+    return [
+        {
+            severity: 'warning',
+            code: 'artifact_skipped',
+            message: skippedArtifactMessage(instructions.artifactId, changeName),
+            fix: `Remove skip_specs from the change's .tospec.yaml before writing ${instructions.artifactId}.`,
+        },
+    ];
+}
+function skippedArtifactMessage(artifactId, changeName) {
+    return `Change '${changeName}' declared '${artifactId}' away (skip_specs: true in .tospec.yaml). Writing it now leaves the marker contradicting the files, which validation rejects.`;
 }
-export function printInstructionsText(instructions, isBlocked) {
-    const { artifactId, changeName, schemaName, changeDir, resolvedOutputPath, description, instruction, context, rules, template, validation, dependencies, unlocks, } = instructions;
-    // Opening tag
+/**
+ * The unmet-dependency warning, as a `status[]` entry — the JSON half of the
+ * `<warning>` block the human output prints. Empty when nothing is missing, so
+ * the caller can concatenate it unconditionally.
+ */
+function blockedDiagnostics(instructions, changeName) {
+    const missing = instructions.dependencies.filter((d) => !d.done).map((d) => d.id);
+    if (missing.length === 0)
+        return [];
+    return [
+        {
+            severity: 'warning',
+            code: 'artifact_blocked',
+            message: `Artifact '${instructions.artifactId}' has unmet dependencies: ${missing.join(', ')}. Complete them first or proceed with caution.`,
+            fix: `Run: tospec instructions ${missing[0]} --change ${changeName}`,
+        },
+    ];
+}
+export function printInstructionsText(instructions, isBlocked, flags = {}) {
+    const { artifactId, changeName, schemaName, changeDir, resolvedOutputPath, description, instruction, context, rules, template, validation, dependencies, unlocks, changeMetadata, } = instructions;
     console.log(`<artifact id="${artifactId}" change="${changeName}" schema="${schemaName}">`);
     console.log();
-    // Warning for blocked artifacts
+    if (flags.skipped) {
+        console.log('<warning>');
+        console.log(skippedArtifactMessage(artifactId, changeName));
+        console.log(`Remove skip_specs from the change's .tospec.yaml before writing ${artifactId}.`);
+        console.log('</warning>');
+        console.log();
+    }
     if (isBlocked) {
         const missing = dependencies.filter((d) => !d.done).map((d) => d.id);
         console.log('<warning>');
@@ -102,13 +164,29 @@ export function printInstructionsText(instructions, isBlocked) {
         console.log('</warning>');
         console.log();
     }
-    // Task directive
     console.log('<task>');
     console.log(`Create the ${artifactId} artifact for change "${changeName}".`);
     console.log(description);
     console.log('</task>');
     console.log();
-    // Project context (AI constraint - do not include in output)
+    // What `tospec new change` recorded, same as the JSON payload's
+    // `changeMetadata`: without it the text reader never learns the goal or which
+    // ADRs drove the change.
+    const decisions = changeMetadata.decisions ?? [];
+    if (changeMetadata.goal || decisions.length > 0) {
+        console.log('<change_context>');
+        if (changeMetadata.goal) {
+            console.log(`Goal: ${changeMetadata.goal}`);
+        }
+        if (decisions.length > 0) {
+            console.log('Decisions driving this change (read them under tospec/decisions/):');
+            for (const file of decisions) {
+                console.log(`- ${file}`);
+            }
+        }
+        console.log('</change_context>');
+        console.log();
+    }
     if (context) {
         console.log('<project_context>');
         console.log('<!-- This is background information for you. Do NOT include this in your output. -->');
@@ -116,7 +194,6 @@ export function printInstructionsText(instructions, isBlocked) {
         console.log('</project_context>');
         console.log();
     }
-    // Rules (AI constraint - do not include in output)
     if (rules && rules.length > 0) {
         console.log('<rules>');
         console.log('<!-- These are constraints for you to follow. Do NOT include this in your output. -->');
@@ -126,7 +203,6 @@ export function printInstructionsText(instructions, isBlocked) {
         console.log('</rules>');
         console.log();
     }
-    // Dependencies (files to read for context)
     if (dependencies.length > 0) {
         console.log('<dependencies>');
         console.log('Read the current contents of these files before creating this artifact (re-read them from disk even if you saw them earlier - they may have been edited since):');
@@ -142,29 +218,23 @@ export function printInstructionsText(instructions, isBlocked) {
         console.log('</dependencies>');
         console.log();
     }
-    // Output location
     console.log('<output>');
     console.log(`Write to: ${resolvedOutputPath}`);
     console.log('</output>');
     console.log();
-    // Instruction (guidance)
     if (instruction) {
         console.log('<instruction>');
         console.log(instruction.trim());
         console.log('</instruction>');
         console.log();
     }
-    // Template
     console.log('<template>');
     console.log('<!-- Use this as the structure for your output file. Fill in the sections. -->');
     console.log(template.trim());
     console.log('</template>');
     console.log();
-    // The schema's own acceptance criteria, rendered only when it declares some.
-    // This block used to be a fixed placeholder, so the one thing an agent needed
-    // in order not to fail validation was the one thing the brief left out — and
-    // an empty block claimed the artifact had no criteria at all. Printed like
-    // <project_context> and <rules>: present when there is something to say.
+    // The schema's own acceptance criteria, present only when it declares some:
+    // an empty block would claim there are none.
     if (validation) {
         console.log('<success_criteria>');
         if (validation.requiredSections.length > 0) {
@@ -173,26 +243,23 @@ export function printInstructionsText(instructions, isBlocked) {
         for (const [section, minLength] of Object.entries(validation.minSectionLength)) {
             console.log(`Section "${section}" must be at least ${minLength} characters.`);
         }
+        for (const [section, maxLength] of Object.entries(validation.maxSectionLength ?? {})) {
+            console.log(`Section "${section}" should stay under ${maxLength} characters.`);
+        }
         console.log('</success_criteria>');
         console.log();
     }
-    // Unlocks
     if (unlocks.length > 0) {
         console.log('<unlocks>');
         console.log(`Completing this artifact enables: ${unlocks.join(', ')}`);
         console.log('</unlocks>');
         console.log();
     }
-    // Closing tag
     console.log('</artifact>');
 }
-// -----------------------------------------------------------------------------
-// Apply Instructions Command
-// -----------------------------------------------------------------------------
 /**
- * Maps a change's schema to the planning skill that produces its artifacts,
- * so blocked-state instructions point at a skill that actually exists
- * (see skill-generation.ts for the generated list).
+ * The planning skill that produces a schema's artifacts, so blocked-state
+ * instructions point at a skill that exists.
  */
 function planningSkillFor(schemaName) {
     if (schemaName === 'issue')
@@ -202,44 +269,50 @@ function planningSkillFor(schemaName) {
     return 'tospec-propose (sdd) or tospec-issue (issue)';
 }
 /**
- * Parses tasks.md content and extracts task items with their completion status.
+ * How to name the tracked task file in a message to the user. `path.basename`
+ * alone turns a glob (`tasks/*.md`) into a bare `*.md`, which names no file, so
+ * a glob keeps the `tracks` value as the schema authored it.
+ */
+function describeTracksFile(tracksFile) {
+    return /[*?[\]]/.test(tracksFile) ? tracksFile : path.basename(tracksFile);
+}
+/**
  * Shares `parseTasksFromContent` with task progress so the apply instructions
  * and the reported `x/y` can never disagree about what counts as a task.
  */
 function parseTasksFile(content) {
-    return parseTasksFromContent(content).map((task, i) => ({
-        // The number the task carries in the file ("1.2"), not this array's index.
-        // They diverge the moment a slice starts at 2.1 or a task is deleted, and
-        // the id is the field a caller would naturally quote back to the user —
-        // while the real numbering sat buried at the head of `description`.
-        // Falls back to the ordinal for a task written without one.
-        id: /^(\d+(?:\.\d+)*)\s/.exec(task.text)?.[1] ?? `${i + 1}`,
-        description: task.text,
-        done: task.done,
-    }));
+    return parseTasksFromContent(content).map((task, i) => {
+        // The number the file gives the task, not this array's index: they diverge
+        // the moment a slice starts at 2.1 or a task is deleted, and the id is what
+        // a caller quotes back. Falls back to the ordinal when there is none.
+        const numbered = /^(\d+(?:\.\d+)*)\s+(.*)$/.exec(task.text);
+        return {
+            id: numbered?.[1] ?? `${i + 1}`,
+            // Without that number, since `id` carries it and a consumer joining the
+            // two would render "1.1 1.1 Write a failing test".
+            description: numbered?.[2] ?? task.text,
+            done: task.done,
+        };
+    });
 }
 /**
- * Generates apply instructions for implementing tasks from a change.
- * Schema-aware: reads apply phase configuration from schema to determine
- * required artifacts, tracking file, and instruction.
+ * Apply instructions for a change, from the schema's `apply` block: required
+ * artifacts, tracking file, and instruction.
  */
 export async function generateApplyInstructions(projectRoot, changeName, schemaName, options = {}) {
     const planningHome = options.planningHome ?? resolveCurrentPlanningHomeSync({ startPath: projectRoot });
-    // loadChangeContext will auto-detect schema from metadata if not provided
+    // The schema comes from the change's metadata when not given.
     const context = loadChangeContext(projectRoot, changeName, schemaName, {
         changeDir: getChangeDir(planningHome, changeName),
         planningHome,
     });
     const changeDir = context.changeDir;
-    // Get the full schema to access the apply phase configuration
     const schema = resolveSchema(context.schemaName, projectRoot);
     const applyConfig = schema.apply;
-    // Determine required artifacts and tracking file from schema
-    // Fallback: if no apply block, require all artifacts
+    // No apply block: require every artifact.
     const requiredArtifactIds = applyConfig?.requires ?? schema.artifacts.map((a) => a.id);
     const tracksFile = applyConfig?.tracks ?? null;
     const schemaInstruction = applyConfig?.instruction ?? null;
-    // Check which required artifacts are missing
     const missingArtifacts = [];
     for (const artifactId of requiredArtifactIds) {
         const artifact = schema.artifacts.find((a) => a.id === artifactId);
@@ -247,7 +320,6 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             missingArtifacts.push(artifactId);
         }
     }
-    // Build context files from all existing artifacts in schema
     const contextFiles = {};
     for (const artifact of schema.artifacts) {
         const outputs = resolveArtifactOutputs(changeDir, artifact.generates);
@@ -255,22 +327,22 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             contextFiles[artifact.id] = outputs;
         }
     }
-    // Parse tasks if tracking file exists
+    // Through `resolveTaskFiles`, the resolver `list`, the dashboard and archive's
+    // completeness gate share: `apply.tracks` names an artifact by its `generates`
+    // value, which may be a glob (`tasks/*.md`). Treated as a literal path it
+    // finds no file, so a multi-file schema reports `blocked` and `0/0`.
     let tasks = [];
     let tracksFileExists = false;
     if (tracksFile) {
-        const tracksPath = path.join(changeDir, tracksFile);
-        tracksFileExists = fs.existsSync(tracksPath);
-        if (tracksFileExists) {
-            const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
-            tasks = parseTasksFile(tasksContent);
+        const trackedFiles = resolveTaskFiles(changeDir, projectRoot).filter((file) => fs.existsSync(file));
+        tracksFileExists = trackedFiles.length > 0;
+        for (const file of trackedFiles) {
+            tasks.push(...parseTasksFile(await fs.promises.readFile(file, 'utf-8')));
         }
     }
-    // Calculate progress
     const total = tasks.length;
     const complete = tasks.filter((t) => t.done).length;
     const remaining = total - complete;
-    // Determine state and instruction
     let state;
     let instruction;
     const planningSkill = planningSkillFor(context.schemaName);
@@ -279,14 +351,12 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         instruction = `Cannot apply this change yet. Missing artifacts: ${missingArtifacts.join(', ')}.\nStop and send the user back to ${planningSkill} to create the missing artifacts first.`;
     }
     else if (tracksFile && !tracksFileExists) {
-        // Tracking file configured but doesn't exist yet
-        const tracksFilename = path.basename(tracksFile);
+        const tracksFilename = describeTracksFile(tracksFile);
         state = 'blocked';
         instruction = `The ${tracksFilename} file is missing and must be created.\nStop and send the user back to ${planningSkill} to generate the tracking file.`;
     }
     else if (tracksFile && tracksFileExists && total === 0) {
-        // Tracking file exists but contains no tasks
-        const tracksFilename = path.basename(tracksFile);
+        const tracksFilename = describeTracksFile(tracksFile);
         state = 'blocked';
         instruction = `The ${tracksFilename} file exists but contains no tasks.\nAdd tasks to ${tracksFilename} or stop and send the user back to ${planningSkill} to regenerate it.`;
     }
@@ -295,7 +365,6 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         instruction = 'All tasks are complete! This change is ready to be archived.\nConsider running tests and reviewing the changes before archiving.';
     }
     else if (!tracksFile) {
-        // No tracking file configured in schema - ready to apply
         state = 'ready';
         instruction = schemaInstruction?.trim() ?? 'All required artifacts complete. Proceed with implementation.';
     }
@@ -303,12 +372,10 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         state = 'ready';
         instruction = schemaInstruction?.trim() ?? 'Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification.';
     }
-    // Schema artifacts that do not exist yet but that `apply.requires` does not
-    // insist on. Reported, not blocking: sdd's apply requires only `tasks`, so a
-    // change missing proposal/design/specs still reaches `state: "ready"` — while
-    // the instruction it is handed says things like "test only the seam design.md
-    // chose". Naming the absent files is what stops that reading as a reference to
-    // something the agent simply failed to find.
+    // Absent artifacts `apply.requires` does not insist on: reported, not
+    // blocking. sdd's apply requires only `tasks`, so a change missing
+    // proposal/design/specs reaches `ready` while its instruction still refers
+    // to them.
     const missingContext = schema.artifacts
         .filter((artifact) => !contextFiles[artifact.id] && !missingArtifacts.includes(artifact.id))
         .map((artifact) => artifact.id);
@@ -317,6 +384,10 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
 
 Not present in this change: ${missingContext.join(', ')}. Ignore any part of the above that refers to them.`;
     }
+    // The project's own context and rules, as every artifact's instructions carry.
+    const { config: projectConfig, diagnostics: configWarnings } = readProjectConfigWithDiagnostics(projectRoot);
+    const configContext = projectConfig?.context?.trim() || undefined;
+    const applyRules = projectConfig?.rules?.[APPLY_RULES_KEY];
     return {
         changeName,
         changeDir,
@@ -328,39 +399,61 @@ Not present in this change: ${missingContext.join(', ')}. Ignore any part of the
         missingArtifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
         missingContext: missingContext.length > 0 ? missingContext : undefined,
         instruction,
+        ...(configContext ? { context: configContext } : {}),
+        ...(applyRules?.length ? { rules: applyRules } : {}),
+        ...(configWarnings.length ? { configWarnings } : {}),
     };
 }
 export async function applyInstructionsCommand(options) {
-    const root = await resolveRootForCommand(options, { json: options.json });
-    if (!root) {
+    const target = await resolveInstructionsTarget(options);
+    if (!target) {
         return;
     }
-    const planningHome = toPlanningHome(root);
-    const projectRoot = root.path;
-    // Validate the schema before resolving the change (round 4 report 15): after
-    // it, the guard never fired in an empty project, so the caller was told to
-    // create a change first and only then learned the schema was never usable.
-    if (options.schema) {
-        validateSchemaExists(options.schema, projectRoot);
-        assertChangeSchema(options.schema);
-    }
-    const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint: 'tospec new change <name>' });
-    // generateApplyInstructions uses loadChangeContext which auto-detects schema
+    const { root, planningHome, projectRoot, changeName } = target;
     const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
         planningHome,
     });
     if (options.json) {
-        emitSuccess({ ...instructions }, toRootOutput(root));
+        // As in the artifact payload: `configWarnings` becomes the envelope's
+        // `status[]`, not a field of its own.
+        const { configWarnings, ...payload } = instructions;
+        emitSuccess({
+            ...payload,
+            ...(configWarnings?.length
+                ? {
+                    status: configWarnings.map(({ code, message }) => ({
+                        severity: 'warning',
+                        code,
+                        message,
+                    })),
+                }
+                : {}),
+        }, toRootOutput(root));
         return;
     }
     printApplyInstructionsText(instructions);
 }
 export function printApplyInstructionsText(instructions) {
-    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
+    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction, context, rules, } = instructions;
     console.log(`## Apply: ${changeName}`);
     console.log(`Schema: ${schemaName}`);
     console.log();
-    // Warning for blocked state
+    // The same tags the artifact instructions use, so an agent reading either
+    // treats project constraints the same way.
+    if (context) {
+        console.log('<project_context>');
+        console.log(context);
+        console.log('</project_context>');
+        console.log();
+    }
+    if (rules && rules.length > 0) {
+        console.log('<rules>');
+        for (const rule of rules) {
+            console.log(`- ${rule}`);
+        }
+        console.log('</rules>');
+        console.log();
+    }
     if (state === 'blocked' && missingArtifacts) {
         console.log('### ⚠️ Blocked');
         console.log();
@@ -368,7 +461,6 @@ export function printApplyInstructionsText(instructions) {
         console.log(`Use the ${planningSkillFor(schemaName)} skill to create these first.`);
         console.log();
     }
-    // Context files (dynamically from schema)
     const contextFileEntries = Object.entries(contextFiles);
     if (contextFileEntries.length > 0) {
         console.log('### Context Files');
@@ -379,7 +471,6 @@ export function printApplyInstructionsText(instructions) {
         }
         console.log();
     }
-    // Progress (only show if we have tracking)
     if (progress.total > 0 || tasks.length > 0) {
         console.log('### Progress');
         if (state === 'all_done') {
@@ -390,16 +481,16 @@ export function printApplyInstructionsText(instructions) {
         }
         console.log();
     }
-    // Tasks
     if (tasks.length > 0) {
         console.log('### Tasks');
         for (const task of tasks) {
             const checkbox = task.done ? '[x]' : '[ ]';
-            console.log(`- ${checkbox} ${task.description}`);
+            // Joined again here: the number is stored apart only so a caller can
+            // address a task by it.
+            console.log(`- ${checkbox} ${task.id} ${task.description}`);
         }
         console.log();
     }
-    // Instruction
     console.log('### Instruction');
     console.log(instruction);
 }