@seanmars/tospec 0.23.0 → 0.26.0-beta

package/dist/commands/workflow/instructions.js

@@ -4,13 +4,18 @@
  */
 import path from 'path';
 import * as fs from 'fs';
-import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
+import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, findSchemaWarnings, } from '../../core/artifact-graph/index.js';
 import { getChangeDir, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
 import { resolveRootForCommand, toPlanningHome, toRootOutput, } from '../../core/root-selection.js';
-import { APPLY_RULES_KEY, readProjectConfigWithDiagnostics } from '../../core/project-config.js';
+import { APPLY_RULES_KEY, printProjectConfigDiagnostic, readProjectConfigWithDiagnostics, } from '../../core/project-config.js';
 import { parseTasksFromContent, resolveTaskFiles } from '../../utils/task-progress.js';
-import { validateChangeExists, validateSchemaExists, assertChangeSchema, } from './shared.js';
+import { readSkipSpecsMarker } from '../../utils/change-metadata.js';
+import { findMisplacedSpecFiles, findSkipSpecsContradictions } from '../../utils/spec-files.js';
+import { changeRequiresDeltas } from '../validate.js';
+import { Validator, headerCorrectionClause } from '../../core/validation/validator.js';
+import { validateChangeExists, validateChangeSchema, changeUnreadable, ChangeUnreadableError, } from './shared.js';
 import { emitSuccess } from '../shared-output.js';
+import { attributeValue, inlineField, neutralizeTags } from './prompt-escape.js';
 /**
  * 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
@@ -42,25 +47,37 @@ async function resolveInstructionsTarget(options) {
     }
     const projectRoot = root.path;
     if (options.schema) {
-        validateSchemaExists(options.schema, projectRoot);
-        assertChangeSchema(options.schema);
+        validateChangeSchema(options.schema, projectRoot);
     }
     const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, {
         newChangeHint: 'tospec new change <name>',
     });
     return { root, planningHome: toPlanningHome(root), projectRoot, changeName };
 }
+/**
+ * The change's context, or `change_unreadable` when it exists but does not
+ * load. The schema comes from the change's metadata when not given. Only the
+ * load is wrapped, as in `status --change`: a missing change and a bad
+ * `--schema` are refused before it, under their own codes.
+ */
+function loadInstructionsContext(projectRoot, changeName, schemaName, planningHome) {
+    try {
+        return loadChangeContext(projectRoot, changeName, schemaName, {
+            changeDir: getChangeDir(planningHome, changeName),
+            planningHome,
+        });
+    }
+    catch (error) {
+        throw new ChangeUnreadableError(changeUnreadable(changeName, error, { planningHome, projectRoot, schema: schemaName }).diagnostic);
+    }
+}
 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,
-    });
+    const context = loadInstructionsContext(projectRoot, changeName, options.schema, planningHome);
     // 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  ');
@@ -84,9 +101,7 @@ export async function instructionsCommand(artifactId, options) {
     // while `status` called it ready — and sent the agent to write the specs the
     // change had just declared it has none of.
     const unmetDependencies = instructions.dependencies
-        .filter((d) => !d.done &&
-        !(context.skippedArtifacts?.has(d.id) ?? false) &&
-        context.graph.getArtifact(d.id)?.optional !== true)
+        .filter((d) => !d.done && !isMetWithoutFile(d))
         .map((d) => d.id);
     // `status` says "skipped" for this artifact, so a brief that reads as a
     // plain "write it" sends an agent into the contradiction `validate` rejects
@@ -155,25 +170,28 @@ function blockedDiagnostics(instructions, changeName, missing) {
 }
 export function printInstructionsText(instructions, unmetDependencies, 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}">`);
+    // Every value below is neutralized before it is printed (prompt-escape.ts):
+    // config, metadata and schemas are repo-controlled, and an unescaped closing
+    // tag in any of them would end the block it sits in.
+    console.log(`<artifact id="${attributeValue(artifactId)}" change="${attributeValue(changeName)}" schema="${attributeValue(schemaName)}">`);
     console.log();
     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(inlineField(skippedArtifactMessage(artifactId, changeName)));
+        console.log(inlineField(`Remove skip_specs from the change's .tospec.yaml before writing ${artifactId}.`));
         console.log('</warning>');
         console.log();
     }
     if (unmetDependencies.length > 0) {
         console.log('<warning>');
         console.log('This artifact has unmet dependencies. Complete them first or proceed with caution.');
-        console.log(`Missing: ${unmetDependencies.join(', ')}`);
+        console.log(`Missing: ${inlineField(unmetDependencies.join(', '))}`);
         console.log('</warning>');
         console.log();
     }
     console.log('<task>');
-    console.log(`Create the ${artifactId} artifact for change "${changeName}".`);
-    console.log(description);
+    console.log(inlineField(`Create the ${artifactId} artifact for change "${changeName}".`));
+    console.log(neutralizeTags(description));
     console.log('</task>');
     console.log();
     // What `tospec new change` recorded, same as the JSON payload's
@@ -183,12 +201,12 @@ export function printInstructionsText(instructions, unmetDependencies, flags = {
     if (changeMetadata.goal || decisions.length > 0) {
         console.log('<change_context>');
         if (changeMetadata.goal) {
-            console.log(`Goal: ${changeMetadata.goal}`);
+            console.log(`Goal: ${inlineField(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(`- ${inlineField(file)}`);
             }
         }
         console.log('</change_context>');
@@ -197,7 +215,7 @@ export function printInstructionsText(instructions, unmetDependencies, flags = {
     if (context) {
         console.log('<project_context>');
         console.log('<!-- This is background information for you. Do NOT include this in your output. -->');
-        console.log(context);
+        console.log(neutralizeTags(context));
         console.log('</project_context>');
         console.log();
     }
@@ -205,39 +223,52 @@ export function printInstructionsText(instructions, unmetDependencies, flags = {
         console.log('<rules>');
         console.log('<!-- These are constraints for you to follow. Do NOT include this in your output. -->');
         for (const rule of rules) {
-            console.log(`- ${rule}`);
+            console.log(`- ${inlineField(rule)}`);
         }
         console.log('</rules>');
         console.log();
     }
+    // A dependency met without a file stays in the block, labelled as `status`
+    // labels it, but outside the read instruction and without a path: listed
+    // there, a skipped `specs` sent the agent after a glob that matches nothing.
+    const toRead = dependencies.filter((dep) => !isMetWithoutFile(dep));
+    const metWithoutFile = dependencies.filter(isMetWithoutFile);
     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):');
-        console.log();
-        for (const dep of dependencies) {
-            const status = dep.done ? 'done' : 'missing';
-            const fullPath = path.join(changeDir, dep.path);
-            console.log(`<dependency id="${dep.id}" status="${status}">`);
-            console.log(`  <path>${fullPath}</path>`);
-            console.log(`  <description>${dep.description}</description>`);
-            console.log('</dependency>');
+        if (toRead.length > 0) {
+            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):');
+            console.log();
+            for (const dep of toRead) {
+                printDependency(dep, dep.done ? 'done' : 'missing', path.join(changeDir, dep.path));
+            }
+        }
+        if (metWithoutFile.length > 0) {
+            if (toRead.length > 0)
+                console.log();
+            console.log('Not written, and this change does not need them, so there is no file to read:');
+            console.log();
+            for (const dep of metWithoutFile) {
+                // `skipped` first, as `status` ranks it: the change's declaration is
+                // the stronger statement than the schema's "may be omitted".
+                printDependency(dep, dep.skipped ? 'skipped' : 'optional');
+            }
         }
         console.log('</dependencies>');
         console.log();
     }
     console.log('<output>');
-    console.log(`Write to: ${resolvedOutputPath}`);
+    console.log(`Write to: ${inlineField(resolvedOutputPath)}`);
     console.log('</output>');
     console.log();
     if (instruction) {
         console.log('<instruction>');
-        console.log(instruction.trim());
+        console.log(neutralizeTags(instruction.trim()));
         console.log('</instruction>');
         console.log();
     }
     console.log('<template>');
     console.log('<!-- Use this as the structure for your output file. Fill in the sections. -->');
-    console.log(template.trim());
+    console.log(neutralizeTags(template.trim()));
     console.log('</template>');
     console.log();
     // The schema's own acceptance criteria, present only when it declares some:
@@ -245,25 +276,41 @@ export function printInstructionsText(instructions, unmetDependencies, flags = {
     if (validation) {
         console.log('<success_criteria>');
         if (validation.requiredSections.length > 0) {
-            console.log(`Required sections: ${validation.requiredSections.map((s) => `## ${s}`).join(', ')}`);
+            console.log(`Required sections: ${inlineField(validation.requiredSections.map((s) => `## ${s}`).join(', '))}`);
         }
         for (const [section, minLength] of Object.entries(validation.minSectionLength)) {
-            console.log(`Section "${section}" must be at least ${minLength} characters.`);
+            console.log(`Section "${inlineField(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(`Section "${inlineField(section)}" should stay under ${maxLength} characters.`);
         }
         console.log('</success_criteria>');
         console.log();
     }
     if (unlocks.length > 0) {
         console.log('<unlocks>');
-        console.log(`Completing this artifact enables: ${unlocks.join(', ')}`);
+        console.log(`Completing this artifact enables: ${inlineField(unlocks.join(', '))}`);
         console.log('</unlocks>');
         console.log();
     }
     console.log('</artifact>');
 }
+/**
+ * Declared away by the change, or optional and not written: the graph counts
+ * either as met, and neither has a file to read.
+ */
+function isMetWithoutFile(dep) {
+    return !dep.done && (dep.skipped === true || dep.optional);
+}
+/** One `<dependency>` element; `fullPath` is omitted when there is no file to read. */
+function printDependency(dep, status, fullPath) {
+    console.log(`<dependency id="${attributeValue(dep.id)}" status="${status}">`);
+    if (fullPath !== undefined) {
+        console.log(`  <path>${inlineField(fullPath)}</path>`);
+    }
+    console.log(`  <description>${inlineField(dep.description)}</description>`);
+    console.log('</dependency>');
+}
 /**
  * The planning skill that produces a schema's artifacts, so blocked-state
  * instructions point at a skill that exists.
@@ -275,6 +322,18 @@ function planningSkillFor(schemaName) {
         return 'tospec-propose';
     return 'tospec-propose (sdd) or tospec-issue (issue)';
 }
+/**
+ * The `apply_archive_would_refuse` fix for a refusal that carries
+ * `suggestedHeader`. Only a sister change's spelling needs the sentence on
+ * archive order: that refusal is the one a folded match once promised the
+ * sister's archive would settle. A main-spec name is settled already.
+ */
+function headerCorrectionFix({ operation, source }, suggestedHeader) {
+    const edit = headerCorrectionClause(operation, suggestedHeader);
+    return source === 'sister-change'
+        ? `${edit}, the name the in-progress change that adds it uses. Archive matches requirement names exactly, so archiving that change first does not resolve it.`
+        : `${edit}, the name the main spec uses. Archive matches requirement names exactly.`;
+}
 /**
  * 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
@@ -286,13 +345,19 @@ function describeTracksFile(tracksFile) {
 /**
  * Shares `parseTasksFromContent` with task progress so the apply instructions
  * and the reported `x/y` can never disagree about what counts as a task.
+ * Exported so the backtracking test clock holds only the parse.
  */
-function parseTasksFile(content) {
+export function parseTasksFile(content) {
     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);
+        //
+        // `[^\r\n]*` as in TASK_PATTERN, whose text can hold U+2028/U+2029: `.*`
+        // stopped there, so the id fell back to the ordinal, and `\s+` re-split the
+        // blanks before it, 2.6 s for `1.1` + 80k blanks + `a<U+2028>b`. Task text
+        // holds no CR or LF, so this always reaches its end.
+        const numbered = /^(\d+(?:\.\d+)*)\s+([^\r\n]*)$/.exec(task.text);
         return {
             id: numbered?.[1] ?? `${i + 1}`,
             // Without that number, since `id` carries it and a consumer joining the
@@ -308,11 +373,7 @@ function parseTasksFile(content) {
  */
 export async function generateApplyInstructions(projectRoot, changeName, schemaName, options = {}) {
     const planningHome = options.planningHome ?? resolveCurrentPlanningHomeSync({ startPath: projectRoot });
-    // The schema comes from the change's metadata when not given.
-    const context = loadChangeContext(projectRoot, changeName, schemaName, {
-        changeDir: getChangeDir(planningHome, changeName),
-        planningHome,
-    });
+    const context = loadInstructionsContext(projectRoot, changeName, schemaName, planningHome);
     const changeDir = context.changeDir;
     const schema = resolveSchema(context.schemaName, projectRoot);
     const applyConfig = schema.apply;
@@ -320,13 +381,27 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     const requiredArtifactIds = applyConfig?.requires ?? schema.artifacts.map((a) => a.id);
     const tracksFile = applyConfig?.tracks ?? null;
     const schemaInstruction = applyConfig?.instruction ?? null;
-    const missingArtifacts = [];
+    // A required artifact still empty or holding its template blocks like an
+    // absent one: counted by existence alone, a copied tasks template reached
+    // `ready` and its placeholders were handed over as the work, while `status`
+    // called it a stub. Read from `context.stubs`, so the two cannot disagree.
+    // Kept apart from the absent ones only for the wording: a stub's file is on
+    // disk, and calling it "missing" sends the reader looking for a file that is
+    // right there.
+    const absentArtifacts = [];
+    const stubArtifacts = [];
     for (const artifactId of requiredArtifactIds) {
         const artifact = schema.artifacts.find((a) => a.id === artifactId);
-        if (artifact && resolveArtifactOutputs(changeDir, artifact.generates).length === 0) {
-            missingArtifacts.push(artifactId);
+        if (!artifact)
+            continue;
+        if (resolveArtifactOutputs(changeDir, artifact.generates).length === 0) {
+            absentArtifacts.push(artifactId);
+        }
+        else if (context.stubs?.has(artifactId)) {
+            stubArtifacts.push(artifactId);
         }
     }
+    const missingArtifacts = [...absentArtifacts, ...stubArtifacts];
     const contextFiles = {};
     for (const artifact of schema.artifacts) {
         const outputs = resolveArtifactOutputs(changeDir, artifact.generates);
@@ -353,9 +428,70 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     let state;
     let instruction;
     const planningSkill = planningSkillFor(context.schemaName);
+    // 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);
+    // `specs` is the one absent artifact apply must not wave away: when the
+    // schema requires it and the change did not declare it away (skip_specs,
+    // scoped to that id like every other reader of the marker), validate and
+    // archive refuse the change. Told to ignore it, an agent finished the work
+    // and only learned that at archive time. Decided before `state`, because
+    // `all_done` must not call such a change ready to archive.
+    const specsArtifact = schema.artifacts.find((artifact) => artifact.id === 'specs');
+    const specsRequiredButMissing = specsArtifact !== undefined &&
+        !specsArtifact.optional &&
+        missingContext.includes('specs') &&
+        !(context.skippedArtifacts?.has('specs') ?? false);
+    // The opposite fault: skip_specs: true beside spec files. validate refuses
+    // it, and so archive, yet only validate reported it, at apply's step 6, once
+    // the work was done. Read through validate's own helper and under any
+    // schema, as validate reads it, so the two cannot disagree about a change.
+    const skipSpecsMarker = readSkipSpecsMarker(changeDir);
+    const contradictingSpecs = await findSkipSpecsContradictions(changeDir, skipSpecsMarker);
+    // Spec files validate refuses for where they sit (nested, a dot folder, a
+    // misnamed file, specs/spec.md). Neither warning above names them: under
+    // skip_specs they contradict nothing, so apply said ready, while the
+    // "Not present in this change: specs" line told the agent to ignore them,
+    // and validate refused the change only at step 6.
+    const misplacedSpecs = await findMisplacedSpecFiles(path.join(changeDir, 'specs'), {
+        requireDelta: await changeRequiresDeltas(projectRoot, changeDir, { marker: skipSpecsMarker, contradictingSpecs }),
+    });
+    // Deltas archive's merge would refuse (a MODIFIED, REMOVED or RENAMED on a capability
+    // with no main spec, an ADDED that already exists). validate reported them
+    // and apply said ready, so the work was done before archive refused it.
+    // Through validate's own dry run, not a second list of preconditions here,
+    // which would be free to drift from archive's.
+    const archiveRefusals = fs.existsSync(path.join(changeDir, 'specs'))
+        ? await new Validator().findArchiveRefusals(changeDir, path.join(projectRoot, 'tospec', 'specs'))
+        : [];
+    // What keeps an all-done change from archiving. apply_specs_missing and
+    // apply_skip_specs_contradicted cannot both hold, as a declared marker drops
+    // the first; a misplaced file can sit beside either, and is named after
+    // them. A refused delta is named last: the faults above decide which files
+    // archive merges at all.
+    const archiveBlocker = specsRequiredButMissing
+        ? 'it has no delta specs (see the apply_specs_missing warning)'
+        : contradictingSpecs.length > 0
+            ? 'it sets skip_specs: true beside delta spec files (see the apply_skip_specs_contradicted warning)'
+            : misplacedSpecs.length > 0
+                ? 'it has spec files validate refuses for where they sit (see the apply_specs_misplaced warning)'
+                : archiveRefusals.length > 0
+                    ? 'archive would refuse its delta specs (see the apply_archive_would_refuse warning)'
+                    : undefined;
     if (missingArtifacts.length > 0) {
         state = 'blocked';
-        instruction = `Cannot apply this change yet. Missing artifacts: ${missingArtifacts.join(', ')}.\nStop and send the user back to ${planningSkill} to create the missing artifacts first.`;
+        const reasons = [
+            ...(absentArtifacts.length > 0 ? [`Missing artifacts: ${absentArtifacts.join(', ')}.`] : []),
+            // "empty or": a stub is either, and an empty file called a template sends
+            // the reader comparing it against one.
+            ...(stubArtifacts.length > 0 ? [`Still empty or the unfilled template: ${stubArtifacts.join(', ')}.`] : []),
+        ];
+        const action = stubArtifacts.length === 0 ? 'create the missing artifacts' : absentArtifacts.length === 0 ? 'fill them in' : 'create and fill them in';
+        instruction = `Cannot apply this change yet. ${reasons.join(' ')}\nStop and send the user back to ${planningSkill} to ${action} first.`;
     }
     else if (tracksFile && !tracksFileExists) {
         const tracksFilename = describeTracksFile(tracksFile);
@@ -369,7 +505,9 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     }
     else if (tracksFile && remaining === 0 && total > 0) {
         state = 'all_done';
-        instruction = 'All tasks are complete! This change is ready to be archived.\nConsider running tests and reviewing the changes before archiving.';
+        instruction = archiveBlocker
+            ? `All tasks are complete, but this change cannot be archived yet: ${archiveBlocker}.\nResolve that warning before archiving.`
+            : 'All tasks are complete! This change is ready to be archived.\nConsider running tests and reviewing the changes before archiving.';
     }
     else if (!tracksFile) {
         state = 'ready';
@@ -379,17 +517,73 @@ 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.';
     }
-    // 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);
-    if (missingContext.length > 0 && state !== 'blocked') {
+    // Reported even when blocked: an unmatched `apply.tracks` is what produces a
+    // "file is missing" block for a file that exists, so the block needs it.
+    const warnings = findSchemaWarnings(schema);
+    if (specsRequiredButMissing && state !== 'blocked') {
+        // A mistyped value (`skip_specs: "yes"`) is a declaration that failed, not
+        // an absent one: saying "does not declare" sent the user looking for a key
+        // they had written.
+        const marker = context.skipSpecsInvalidReason
+            ? `its skip_specs value is invalid (${context.skipSpecsInvalidReason.replace(/\.$/, '')})`
+            : 'does not set skip_specs: true';
+        warnings.push({
+            code: 'apply_specs_missing',
+            message: `Change '${changeName}' has no delta specs and ${marker}, so validate and archive will refuse it once the work is done.`,
+            fix: `Write the delta specs with ${planningSkill} before implementing, or set \`skip_specs: true\` in the change's .tospec.yaml only when the user confirms it needs no delta spec.`,
+        });
+    }
+    // Reported even when blocked, unlike apply_specs_missing: the planning skill
+    // a block sends the user to does not settle it. Only the user can say
+    // whether the flag or the spec files are wrong.
+    if (contradictingSpecs.length > 0) {
+        warnings.push({
+            code: 'apply_skip_specs_contradicted',
+            message: `Change '${changeName}' sets skip_specs: true but has ${contradictingSpecs.length} spec file(s) (${contradictingSpecs.join(', ')}), so validate and archive will refuse it once the work is done.`,
+            fix: `Remove skip_specs from the change's .tospec.yaml when the user wants these delta specs; delete the spec files only when the user confirms this change needs no delta spec.`,
+        });
+    }
+    // Reported even when blocked, like the contradiction: the planning skill a
+    // block sends the user to does not move files.
+    if (misplacedSpecs.length > 0) {
+        const listed = misplacedSpecs.map((file) => `specs/${file}`).join(', ');
+        warnings.push({
+            code: 'apply_specs_misplaced',
+            message: `Change '${changeName}' has ${misplacedSpecs.length} spec file(s) that archive does not merge where they sit (${listed}), so validate and archive will refuse it once the work is done.`,
+            fix: `Move each file to specs/<capability>/spec.md; \`tospec validate ${changeName}\` names the exact path for each.`,
+        });
+    }
+    // Reported even when blocked, like the two above: the planning skill a block
+    // sends the user to writes deltas against the main specs it reads, and when
+    // the cause is a sister change still unarchived, no edit there settles it.
+    // validate's text verbatim, so its "Archive '<change>' first" hint survives.
+    // `blockedBy` is validate's own field, carried as is, so an agent reads the
+    // order from one place in both commands instead of from the message.
+    // `suggestedHeader` likewise: the refusal's text is the merge's and does not
+    // name the spelling the sister change uses, so the fix has to. For a near
+    // miss of the main spec the merge's text does name it, but the field is what
+    // an agent reads, so the fix names it the same way.
+    for (const { issue: refusal, headerCorrection } of archiveRefusals) {
+        const blockedBy = refusal.blockedBy ?? [];
+        const { suggestedHeader } = refusal;
+        const validateNote = `\`tospec validate ${changeName}\` reports the same finding.`;
+        warnings.push({
+            code: 'apply_archive_would_refuse',
+            message: `Change '${changeName}', specs/${refusal.path}: ${refusal.message}`,
+            fix: blockedBy.length > 0
+                ? `Archive ${blockedBy.map((name) => `'${name}'`).join(', ')} first, then run apply again; no edit to this delta resolves it. ${validateNote}`
+                : suggestedHeader !== undefined && headerCorrection !== undefined
+                    ? `Correct the delta with ${planningSkill} before implementing: ${headerCorrectionFix(headerCorrection, suggestedHeader)} ${validateNote}`
+                    : `Correct the delta with ${planningSkill} before implementing. ${validateNote}`,
+            ...(blockedBy.length > 0 ? { blockedBy } : {}),
+            ...(suggestedHeader === undefined ? {} : { suggestedHeader }),
+        });
+    }
+    const ignorable = specsRequiredButMissing ? missingContext.filter((id) => id !== 'specs') : missingContext;
+    if (ignorable.length > 0 && state !== 'blocked') {
         instruction += `
 
-Not present in this change: ${missingContext.join(', ')}. Ignore any part of the above that refers to them.`;
+Not present in this change: ${ignorable.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);
@@ -409,6 +603,7 @@ Not present in this change: ${missingContext.join(', ')}. Ignore any part of the
         ...(configContext ? { context: configContext } : {}),
         ...(applyRules?.length ? { rules: applyRules } : {}),
         ...(configWarnings.length ? { configWarnings } : {}),
+        ...(warnings.length ? { warnings } : {}),
     };
 }
 export async function applyInstructionsCommand(options) {
@@ -420,43 +615,58 @@ export async function applyInstructionsCommand(options) {
     const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
         planningHome,
     });
+    // Printed in both modes, as `instructions <artifact>` does: the human text
+    // otherwise never said that the context or rules it shows were cut short.
+    for (const warning of instructions.configWarnings ?? []) {
+        printProjectConfigDiagnostic(warning.message);
+    }
     if (options.json) {
         // As in the artifact payload: `configWarnings` becomes the envelope's
         // `status[]`, not a field of its own.
-        const { configWarnings, ...payload } = instructions;
+        const { configWarnings, warnings, ...payload } = instructions;
+        // The change's own warning first: it is the one that decides whether the
+        // work about to start can be archived at all.
+        const status = [
+            ...(warnings ?? []).map(({ code, message, fix, blockedBy, suggestedHeader }) => ({
+                severity: 'warning',
+                code,
+                message,
+                ...(fix ? { fix } : {}),
+                ...(blockedBy ? { blockedBy } : {}),
+                ...(suggestedHeader ? { suggestedHeader } : {}),
+            })),
+            ...(configWarnings ?? []).map(({ code, message }) => ({
+                severity: 'warning',
+                code,
+                message,
+            })),
+        ];
         emitSuccess({
             ...payload,
-            ...(configWarnings?.length
-                ? {
-                    status: configWarnings.map(({ code, message }) => ({
-                        severity: 'warning',
-                        code,
-                        message,
-                    })),
-                }
-                : {}),
+            ...(status.length ? { status } : {}),
         }, toRootOutput(root));
         return;
     }
     printApplyInstructionsText(instructions);
 }
 export function printApplyInstructionsText(instructions) {
-    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction, context, rules, } = instructions;
-    console.log(`## Apply: ${changeName}`);
-    console.log(`Schema: ${schemaName}`);
+    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction, context, rules, warnings, } = instructions;
+    console.log(`## Apply: ${inlineField(changeName)}`);
+    console.log(`Schema: ${inlineField(schemaName)}`);
     console.log();
     // The same tags the artifact instructions use, so an agent reading either
-    // treats project constraints the same way.
+    // treats project constraints the same way — and the same escaping, since the
+    // same repo-controlled text fills them.
     if (context) {
         console.log('<project_context>');
-        console.log(context);
+        console.log(neutralizeTags(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(`- ${inlineField(rule)}`);
         }
         console.log('</rules>');
         console.log();
@@ -464,8 +674,10 @@ export function printApplyInstructionsText(instructions) {
     if (state === 'blocked' && missingArtifacts) {
         console.log('### ⚠️ Blocked');
         console.log();
-        console.log(`Missing artifacts: ${missingArtifacts.join(', ')}`);
-        console.log(`Use the ${planningSkillFor(schemaName)} skill to create these first.`);
+        // Archive's wording for the same list: it holds unfilled templates too, and
+        // the instruction below says which is which.
+        console.log(`Missing or incomplete artifacts: ${missingArtifacts.map(inlineField).join(', ')}`);
+        console.log(`Use the ${planningSkillFor(schemaName)} skill to complete these first.`);
         console.log();
     }
     const contextFileEntries = Object.entries(contextFiles);
@@ -473,7 +685,7 @@ export function printApplyInstructionsText(instructions) {
         console.log('### Context Files');
         for (const [artifactId, filePaths] of contextFileEntries) {
             for (const filePath of filePaths) {
-                console.log(`- ${artifactId}: ${filePath}`);
+                console.log(`- ${inlineField(artifactId)}: ${inlineField(filePath)}`);
             }
         }
         console.log();
@@ -494,11 +706,17 @@ export function printApplyInstructionsText(instructions) {
             const checkbox = task.done ? '[x]' : '[ ]';
             // 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(`- ${checkbox} ${task.id} ${inlineField(task.description)}`);
         }
         console.log();
     }
+    for (const warning of warnings ?? []) {
+        console.log(`Warning: ${inlineField(warning.message)}`);
+        if (warning.fix)
+            console.log(`Fix: ${inlineField(warning.fix)}`);
+        console.log();
+    }
     console.log('### Instruction');
-    console.log(instruction);
+    console.log(neutralizeTags(instruction));
 }
 //# sourceMappingURL=instructions.js.map