@fission-ai/openspec 1.10.0 → 1.11.0

package/dist/core/templates/workflows/explore.js

@@ -5,7 +5,7 @@ export function getExploreSkillTemplate() {
         description: 'Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.',
         instructions: `Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. For a new change, scaffold it first as described below.
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, investigate the codebase, and run read-only commands or tools without confirmation, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create or update OpenSpec change artifacts (proposals, designs, specs) within a confirmed scope—that's capturing thinking, not implementing. Answering design or clarifying questions is never consent to write. Before the first write-capable action, name the artifacts or files you would change and what you would do, ask a direct yes/no question, and wait for the user's confirmation in a separate message. Confirmation covers only the scope you described; ask again before expanding it. For a new change, scaffold it first as described below.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
@@ -48,22 +48,25 @@ Depending on what the user brings, you might:
 
 **Visualize**
 \`\`\`
-┌─────────────────────────────────────────┐
-│     Use ASCII diagrams liberally        │
-├─────────────────────────────────────────┤
-│                                         │
-│      ┌────────┐         ┌────────┐      │
-│      │ State  │────────▶│ State  │      │
-│      │   A    │         │   B    │      │
-│      └────────┘         └────────┘      │
-│                                         │
-│   System diagrams, state machines,      │
-│   data flows, architecture sketches,    │
-│   dependency graphs, comparison tables  │
-│                                         │
-└─────────────────────────────────────────┘
++------------------------------------------+
+|     Use ASCII diagrams liberally         |
++------------------------------------------+
+|                                          |
+|   [State A] -------> [State B]           |
+|       |                                  |
+|       v                                  |
+|   [State C]                              |
+|                                          |
+|   System diagrams, state machines,       |
+|   data flows, architecture sketches,     |
+|   dependency graphs, comparison tables   |
+|                                          |
++------------------------------------------+
 \`\`\`
 
+**Draw with plain ASCII only** — borders \`+\` \`-\` \`|\`, arrows \`-->\` \`<--\` \`^\` \`v\`, markers \`*\` \`x\`.
+Unicode diagram glyphs can render at different widths across terminals, fonts, and locales, so padded boxes and aligned tables can drift. Keep every diagram character ASCII.
+
 **Surface risks and unknowns**
 - Identify what could go wrong
 - Find gaps in understanding
@@ -164,17 +167,17 @@ User: I'm thinking about adding real-time collaboration
 You: Real-time collab is a big space. Let me think about this...
 
       COLLABORATION SPECTRUM
-      ════════════════════════════════════════════
+      ============================================
 
       Awareness          Coordination         Sync
-          │                   │                 │
-          ▼                   ▼                 ▼
-      ┌────────┐         ┌────────┐        ┌────────┐
-      │Presence│         │Cursors │        │  CRDT  │
-      │  "3    │         │ Multi  │        │Conflict│
-      │online" │         │ select │        │  free  │
-      └────────┘         └────────┘        └────────┘
-          │                   │                 │
+          |                   |                 |
+          v                   v                 v
+      +--------+         +--------+        +--------+
+      |Presence|         |Cursors |        |  CRDT  |
+      |  "3    |         | Multi  |        |Conflict|
+      |online" |         | select |        |  free  |
+      +--------+         +--------+        +--------+
+          |                   |                 |
        trivial            moderate           complex
 
       Where's your head at?
@@ -186,27 +189,27 @@ User: The auth system is a mess
 
 You: [reads codebase]
 
-     ┌─────────────────────────────────────────────┐
-     │              CURRENT AUTH FLOW              │
-     └─────────────────────────────────────────────┘
-                        │
-          ┌─────────────┼─────────────┐
-          ▼             ▼             ▼
-     ┌─────────┐  ┌─────────┐  ┌─────────┐
-     │ Google  │  │  GitHub │  │  Email  │
-     │  OAuth  │  │  OAuth  │  │  Magic  │
-     └────┬────┘  └────┬────┘  └────┬────┘
-          │             │             │
-          └─────────────┼─────────────┘
-                        ▼
-                  ┌───────────┐
-                  │  Session  │
-                  └─────┬─────┘
-                        │
-                        ▼
-                  ┌───────────┐
-                  │   Perms   │
-                  └───────────┘
+     +---------------------------------------------+
+     |              CURRENT AUTH FLOW              |
+     +---------------------------------------------+
+                        |
+          +-------------+-------------+
+          v             v             v
+     +---------+  +---------+  +---------+
+     | Google  |  |  GitHub |  |  Email  |
+     |  OAuth  |  |  OAuth  |  |  Magic  |
+     +----+----+  +----+----+  +----+----+
+          |             |             |
+          +-------------+-------------+
+                        v
+                  +-----------+
+                  |  Session  |
+                  +-----+-----+
+                        |
+                        v
+                  +-----------+
+                  |   Perms   |
+                  +-----------+
 
      I see three tangles. Which one's burning?
 \`\`\`
@@ -238,19 +241,19 @@ User: A CLI tool that tracks local dev environments
 
 You: That changes everything.
 
-     ┌─────────────────────────────────────────────────┐
-     │          CLI TOOL DATA STORAGE                  │
-     └─────────────────────────────────────────────────┘
+     +-------------------------------------------------+
+     |          CLI TOOL DATA STORAGE                  |
+     +-------------------------------------------------+
 
      Key constraints:
-     • No daemon running
-     • Must work offline
-     • Single user
+     - No daemon running
+     - Must work offline
+     - Single user
 
                   SQLite          Postgres
-     Deployment   embedded ✓      needs server ✗
-     Offline      yes ✓           no ✗
-     Single file  yes ✓           no ✗
+     Deployment   embedded        needs server
+     Offline      yes             no
+     Single file  yes             no
 
      SQLite. Not even close.
 
@@ -290,11 +293,11 @@ But this summary is optional. Sometimes the thinking IS the value.
 
 ## Guardrails
 
-- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't implement** - Never write code or implement features. Workflow configuration counts too: creating or editing schemas, templates, or \`openspec/config.yaml\` is a change, not thinking. Creating or updating OpenSpec change artifacts within the confirmed scope is fine, writing anything else is not.
 - **Don't fake understanding** - If something is unclear, dig deeper
 - **Don't rush** - Discovery is thinking time, not task time
 - **Don't force structure** - Let patterns emerge naturally
-- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Don't auto-capture** - Offer to save insights, don't just do it. Read-only commands and tools need no confirmation. Before the first write-capable action—including \`openspec new change\` or another command that writes files—name the artifacts or files and proposed changes, ask a direct yes/no question, and wait for explicit confirmation in a separate user message. That confirmation covers only the described scope; ask again before expanding it. Answers to design or clarifying questions are never consent to write.
 - **Don't manually scaffold changes** - Never create a new change directory under \`openspec/changes/\` by hand. Always use \`openspec new change "<name>"\` (with \`--store <id>\` when applicable) so required metadata such as \`.openspec.yaml\` is created before writing artifacts.
 - **Do visualize** - A good diagram is worth many paragraphs
 - **Do explore the codebase** - Ground discussions in reality
@@ -312,7 +315,7 @@ export function getOpsxExploreCommandTemplate() {
         tags: ['workflow', 'explore', 'experimental', 'thinking'],
         content: `Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. For a new change, scaffold it first as described below.
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, investigate the codebase, and run read-only commands or tools without confirmation, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create or update OpenSpec change artifacts (proposals, designs, specs) within a confirmed scope—that's capturing thinking, not implementing. Answering design or clarifying questions is never consent to write. Before the first write-capable action, name the artifacts or files you would change and what you would do, ask a direct yes/no question, and wait for the user's confirmation in a separate message. Confirmation covers only the scope you described; ask again before expanding it. For a new change, scaffold it first as described below.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
@@ -362,22 +365,25 @@ Depending on what the user brings, you might:
 
 **Visualize**
 \`\`\`
-┌─────────────────────────────────────────┐
-│     Use ASCII diagrams liberally        │
-├─────────────────────────────────────────┤
-│                                         │
-│      ┌────────┐         ┌────────┐      │
-│      │ State  │────────▶│ State  │      │
-│      │   A    │         │   B    │      │
-│      └────────┘         └────────┘      │
-│                                         │
-│   System diagrams, state machines,      │
-│   data flows, architecture sketches,    │
-│   dependency graphs, comparison tables  │
-│                                         │
-└─────────────────────────────────────────┘
++------------------------------------------+
+|     Use ASCII diagrams liberally         |
++------------------------------------------+
+|                                          |
+|   [State A] -------> [State B]           |
+|       |                                  |
+|       v                                  |
+|   [State C]                              |
+|                                          |
+|   System diagrams, state machines,       |
+|   data flows, architecture sketches,     |
+|   dependency graphs, comparison tables   |
+|                                          |
++------------------------------------------+
 \`\`\`
 
+**Draw with plain ASCII only** — borders \`+\` \`-\` \`|\`, arrows \`-->\` \`<--\` \`^\` \`v\`, markers \`*\` \`x\`.
+Unicode diagram glyphs can render at different widths across terminals, fonts, and locales, so padded boxes and aligned tables can drift. Keep every diagram character ASCII.
+
 **Surface risks and unknowns**
 - Identify what could go wrong
 - Find gaps in understanding
@@ -486,11 +492,11 @@ When things crystallize, you might offer a summary - but it's optional. Sometime
 
 ## Guardrails
 
-- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't implement** - Never write code or implement features. Workflow configuration counts too: creating or editing schemas, templates, or \`openspec/config.yaml\` is a change, not thinking. Creating or updating OpenSpec change artifacts within the confirmed scope is fine, writing anything else is not.
 - **Don't fake understanding** - If something is unclear, dig deeper
 - **Don't rush** - Discovery is thinking time, not task time
 - **Don't force structure** - Let patterns emerge naturally
-- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Don't auto-capture** - Offer to save insights, don't just do it. Read-only commands and tools need no confirmation. Before the first write-capable action—including \`openspec new change\` or another command that writes files—name the artifacts or files and proposed changes, ask a direct yes/no question, and wait for explicit confirmation in a separate user message. That confirmation covers only the described scope; ask again before expanding it. Answers to design or clarifying questions are never consent to write.
 - **Don't manually scaffold changes** - Never create a new change directory under \`openspec/changes/\` by hand. Always use \`openspec new change "<name>"\` (with \`--store <id>\` when applicable) so required metadata such as \`.openspec.yaml\` is created before writing artifacts.
 - **Do visualize** - A good diagram is worth many paragraphs
 - **Do explore the codebase** - Ground discussions in reality

package/dist/core/update.js

@@ -23,7 +23,7 @@ import { getAvailableTools } from './available-tools.js';
 import { WORKFLOW_TO_SKILL_DIR, getConfiguredToolsForProfileSync, getToolsNeedingProfileSync, } from './profile-sync-drift.js';
 import { scanInstalledWorkflows as scanInstalledWorkflowsShared, migrateIfNeeded as migrateIfNeededShared, findLegacyToolMigrations, migrateLegacyToolDirs, describeLegacyMigration, legacyMigrationNotice, keptInPlaceNotice, hasMovableContent, } from './migration.js';
 import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
-import { writeSharedSkillTarget, sharedSkillRootOwner } from './shared-skill-target.js';
+import { resolveSharedSkillWriters, writeSharedSkillTarget, } from './shared-skill-target.js';
 import { includesGitHubCopilot, writeCopilotCloudFiles, removeCopilotCloudFiles, isCopilotCloudEnabled, readCopilotCloudOptIn, findUnmanagedCloudFiles } from './github-copilot/cloud-agent.js';
 const require = createRequire(import.meta.url);
 const { version: OPENSPEC_VERSION } = require('../../package.json');
@@ -154,6 +154,9 @@ export class UpdateCommand {
         const deliveryIncludesCommands = delivery !== 'skills';
         // 10. Update tools (all if force, otherwise only those needing update)
         const toolsToUpdate = this.force ? configuredTools : [...toolsToUpdateSet];
+        const sharedSkillWriters = resolveSharedSkillWriters(resolvedProjectPath, configuredAndNewTools
+            .map((toolId) => AI_TOOLS.find((tool) => tool.value === toolId))
+            .filter((tool) => tool !== undefined));
         const updatedTools = [];
         const updatedToolIds = [];
         const failedTools = [];
@@ -173,11 +176,12 @@ export class UpdateCommand {
                 const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : resolvedProjectPath;
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
+                const writesSkills = !tool.skillsDir || sharedSkillWriters.has(tool.value);
                 const toolWorkflows = legacyWorkflowOverrides[tool.value] ?? desiredWorkflows;
                 const skillTemplates = getSkillTemplates(toolWorkflows);
                 const commandContents = getCommandContents(toolWorkflows);
                 // Generate skill files if delivery includes skills
-                if (shouldGenerateSkills) {
+                if (shouldGenerateSkills && writesSkills) {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
@@ -190,7 +194,9 @@ export class UpdateCommand {
                     removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsRoot, skillsDir, toolWorkflows);
                 }
                 // Delete skill directories if delivery is commands-only
-                if (shouldRemoveSkillsForTool(tool.value, delivery) && !hasGlobalSkillTarget(tool)) {
+                if (shouldRemoveSkillsForTool(tool.value, delivery) &&
+                    writesSkills &&
+                    !hasGlobalSkillTarget(tool)) {
                     removedSkillCount += await this.removeSkillDirs(skillsRoot, skillsDir);
                     // Persist the selected owner even when commands-only delivery leaves
                     // this target with no generated skills.
@@ -803,6 +809,10 @@ export class UpdateCommand {
         const newlyConfigured = [];
         const skippedSharedSkillTools = [];
         const workflowOverrides = {};
+        const arbitrationTools = [...new Set([...configuredTools, ...selectedTools])]
+            .map((toolId) => AI_TOOLS.find((tool) => tool.value === toolId))
+            .filter((tool) => tool !== undefined);
+        const sharedSkillWriters = resolveSharedSkillWriters(projectPath, arbitrationTools);
         for (const toolId of selectedTools) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             if (!tool || !toolSupportsSkills(tool))
@@ -813,6 +823,7 @@ export class UpdateCommand {
                 const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : projectPath;
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
+                const writesSkills = !tool.skillsDir || sharedSkillWriters.has(tool.value);
                 const toolWorkflows = (tool.value === 'codex' && inferredCodexWorkflows.length > 0
                     ? inferredCodexWorkflows
                     : desiredWorkflows);
@@ -821,32 +832,23 @@ export class UpdateCommand {
                 }
                 const skillTemplates = getSkillTemplates(toolWorkflows);
                 const commandContents = getCommandContents(toolWorkflows);
-                // A shared skills root (e.g. `.agents`) already owned by another tool
-                // must not be overwritten by a tool inferred from legacy artifacts: a
-                // Codex install detected only from global `~/.codex/prompts` would
-                // otherwise rewrite an existing vendor-neutral `agents` tree with
-                // Codex-specific syntax and flip its ownership marker `agents → codex`.
-                // Leave the established owner in place. (init applies the same
-                // one-writer rule up front when both targets are selected.)
-                //
-                // Skipping here means the tool is never recorded as configured, so a
-                // persistent legacy signal re-offers it on later runs. Because no
-                // replacement is written, this tool is also exempted from immediate
-                // legacy cleanup (see skippedSharedSkillTools) — otherwise a repo-local
-                // `.codex/prompts` would be deleted with nothing put in its place. That
-                // repeat is idempotent and harmless — the alternative is the silent
-                // hijack this prevents.
-                const sharedOwner = shouldGenerateSkills
-                    ? sharedSkillRootOwner(projectPath, tool.value)
+                // Never overwrite a shared skills root owned by another tool. A tool
+                // with its own command surface can still install those commands: this
+                // is how a legacy Antigravity install gains `.agents/workflows` beside
+                // Codex-owned `.agents/skills`. A skills-only tool has no safe artifact
+                // to install, so preserve its legacy files and re-offer it later.
+                const sharedOwner = shouldGenerateSkills && !writesSkills
+                    ? arbitrationTools.find((candidate) => candidate.skillsDir === tool.skillsDir &&
+                        sharedSkillWriters.has(candidate.value))?.value
                     : undefined;
-                if (sharedOwner) {
+                if (sharedOwner && !shouldGenerateCommands) {
                     const ownerName = AI_TOOLS.find((candidate) => candidate.value === sharedOwner)?.name ?? sharedOwner;
                     spinner.info(`Skipped ${tool.name}: ${tool.skillsDir}/skills is already managed by another tool (${ownerName}).`);
                     skippedSharedSkillTools.push(tool.value);
                     continue;
                 }
                 // Create skill files when delivery includes skills
-                if (shouldGenerateSkills) {
+                if (shouldGenerateSkills && writesSkills) {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');

package/dist/core/validation/constants.d.ts

@@ -6,6 +6,8 @@ export declare const MIN_PURPOSE_LENGTH = 50;
 export declare const MAX_WHY_SECTION_LENGTH = 1000;
 export declare const MAX_REQUIREMENT_TEXT_LENGTH = 500;
 export declare const MAX_DELTAS_PER_CHANGE = 10;
+export declare const PURPOSE_PLACEHOLDER_PREFIX = "TBD - created by archiving change ";
+export declare const PURPOSE_PLACEHOLDER_SUFFIX = ". Update Purpose after archive.";
 export declare const VALIDATION_MESSAGES: {
     readonly SCENARIO_EMPTY: "Scenario text cannot be empty";
     readonly REQUIREMENT_EMPTY: "Requirement text cannot be empty";
@@ -26,6 +28,7 @@ export declare const VALIDATION_MESSAGES: {
     readonly DELTA_SPEC_EMPTY: "Spec name cannot be empty";
     readonly DELTA_DESCRIPTION_EMPTY: "Delta description cannot be empty";
     readonly PURPOSE_TOO_BRIEF: "Purpose section is too brief (less than 50 characters)";
+    readonly PURPOSE_IS_PLACEHOLDER: string;
     readonly REQUIREMENT_TOO_LONG: "Requirement text is very long (>500 characters). Consider breaking it down.";
     readonly DELTA_DESCRIPTION_TOO_BRIEF: "Delta description is too brief";
     readonly DELTA_MISSING_REQUIREMENTS: "Delta should include requirements";

package/dist/core/validation/constants.js

@@ -8,6 +8,14 @@ export const MIN_PURPOSE_LENGTH = 50;
 export const MAX_WHY_SECTION_LENGTH = 1000;
 export const MAX_REQUIREMENT_TEXT_LENGTH = 500;
 export const MAX_DELTAS_PER_CHANGE = 10;
+// The Purpose `openspec archive` writes into a main spec it creates when the
+// delta introduced the capability without a usable `## Purpose`. Named here, and
+// composed from these two halves at the write site, so validation recognises the
+// placeholder through the same definition that produces it: a second, hand-copied
+// spelling would stop matching the day the wording changed, and a check that
+// matches nothing looks exactly like a check that found nothing.
+export const PURPOSE_PLACEHOLDER_PREFIX = 'TBD - created by archiving change ';
+export const PURPOSE_PLACEHOLDER_SUFFIX = '. Update Purpose after archive.';
 // Validation messages
 export const VALIDATION_MESSAGES = {
     // Required content
@@ -31,6 +39,10 @@ export const VALIDATION_MESSAGES = {
     DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
     // Warnings
     PURPOSE_TOO_BRIEF: `Purpose section is too brief (less than ${MIN_PURPOSE_LENGTH} characters)`,
+    PURPOSE_IS_PLACEHOLDER: 'Purpose section is still a placeholder rather than a Purpose anyone wrote (the sentence `openspec archive` ' +
+        'writes for a new capability, or a `TBD`/`TODO` marker left in its place). Replace it with what this ' +
+        'capability is for, editing the main spec directly: a `## Purpose` in a delta is read only when the ' +
+        'capability is created, so it cannot replace this one.',
     REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Consider breaking it down.`,
     DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
     DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',

package/dist/core/validation/purpose-placeholder.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Detects a `## Purpose` that is still a placeholder, rather than one somebody
+ * wrote.
+ *
+ * When a delta introduces a capability with no usable `## Purpose`, archive
+ * stamps the placeholder into the new main spec. That text is over
+ * `MIN_PURPOSE_LENGTH`, so the brevity check cannot reach it: the one rule that
+ * exists to catch a Purpose nobody wrote is satisfied by the exact string
+ * meaning nobody wrote one. Nothing else reads it afterwards, so the capability
+ * keeps a to-do in it while every command reports success.
+ *
+ * Two things count, and deliberately nothing else:
+ *
+ * - the placeholder this tool generates, recognised through the same constants
+ *   the writer composes it from, wherever it sits in the Purpose - nobody types
+ *   that sentence by accident;
+ * - a `TBD` or `TODO` **opening** the Purpose, which is the marker left behind
+ *   when someone is told to leave "a brief TBD placeholder" and never comes
+ *   back. Which of the two words got typed says nothing about whether the
+ *   Purpose was written, so both are read the same way.
+ *
+ * A marker inside a sentence is left alone. "The retry budget is TBD pending
+ * benchmarks" is a real Purpose with an open question in it, and reporting it
+ * would teach people to ignore the warning - which costs more than the findings
+ * it would add.
+ *
+ * Fenced code inside the Purpose is quoted material rather than the Purpose
+ * speaking, so it is read out first. Without that, a Purpose documenting the
+ * sentence archive writes is reported as being that sentence: a document about
+ * the placeholder, failing for carrying one.
+ */
+export interface PurposePlaceholderIssue {
+    /** 1-based line of the placeholder text, when it can be located. */
+    line?: number;
+}
+/**
+ * Reports the Purpose of a main spec as an unwritten placeholder, or null when
+ * it reads as authored content.
+ *
+ * An empty Purpose is not reported here - `SPEC_PURPOSE_EMPTY` already covers
+ * it, and reporting both would put two findings on one line. That falls out of
+ * the two rules rather than needing a case of its own.
+ */
+export declare function findPurposePlaceholderIssue(overview: string, content?: string): PurposePlaceholderIssue | null;
+//# sourceMappingURL=purpose-placeholder.d.ts.map

package/dist/core/validation/purpose-placeholder.js

@@ -0,0 +1,117 @@
+import { buildCodeFenceMask } from '../parsers/code-fence.js';
+import { PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX } from './constants.js';
+/**
+ * A `TBD` or `TODO` opening the Purpose. The lookahead keeps it off a longer
+ * word that merely begins with those letters, like "TBDs" or "TODOs", while
+ * still allowing the punctuation a marker is usually written with: `TODO:`,
+ * `TBD -`. It rejects any letter, digit or combining mark rather than only the
+ * ASCII ones `\b` knows about, because a Purpose is prose and prose is not
+ * always written in Latin script - `TBD` followed by an Arabic-Indic digit is
+ * as much a longer word as `TBDs` is.
+ */
+const LEADING_MARKER = /^(?:TBD|TODO)(?![\p{L}\p{N}\p{M}_])/iu;
+const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose[ \t]*$/i;
+const TOP_LEVEL_HEADER = /^ {0,3}#{1,2}(?!#)[ \t]+/;
+/**
+ * The lines of `text` that sit outside a fenced code block, with line endings
+ * normalised first.
+ *
+ * `buildCodeFenceMask` is the masker the requirement and structure parsers
+ * already share, and its own reason for existing is that a second, private
+ * notion of what a fence is drifts from the first. This check reads Markdown
+ * for the same purpose they do, so it reads fences the same way they do.
+ */
+function unfencedLines(text) {
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const fenced = buildCodeFenceMask(lines);
+    return lines.filter((_, index) => !fenced[index]);
+}
+/**
+ * True when the text carries the sentence archive writes. Matched as its two
+ * fixed halves in order, because the change name between them varies - so the
+ * check follows the writer's own definition instead of a second copy of it.
+ */
+function generatedPlaceholderPrefixIndex(text) {
+    let suffixAt = text.indexOf(PURPOSE_PLACEHOLDER_SUFFIX);
+    while (suffixAt !== -1) {
+        // Use the closest prefix before this suffix. An authored explanation can
+        // mention the prefix above the real placeholder; choosing the first prefix
+        // would then point the diagnostic at the explanation instead of the text
+        // the user needs to replace.
+        const prefixAt = text.lastIndexOf(PURPOSE_PLACEHOLDER_PREFIX, suffixAt);
+        if (prefixAt !== -1)
+            return prefixAt;
+        suffixAt = text.indexOf(PURPOSE_PLACEHOLDER_SUFFIX, suffixAt + 1);
+    }
+    return undefined;
+}
+/**
+ * Reports the Purpose of a main spec as an unwritten placeholder, or null when
+ * it reads as authored content.
+ *
+ * An empty Purpose is not reported here - `SPEC_PURPOSE_EMPTY` already covers
+ * it, and reporting both would put two findings on one line. That falls out of
+ * the two rules rather than needing a case of its own.
+ */
+export function findPurposePlaceholderIssue(overview, content) {
+    // An empty Purpose needs no branch of its own: neither rule matches empty
+    // text, so it falls through to null on the line below. An early return for it
+    // would be a guard no test could hold, which is worse than none. A Purpose
+    // that is nothing but a fenced block reduces to the same empty text here, and
+    // is left to the brevity and empty-Purpose rules for the same reason.
+    const prose = unfencedLines(overview).join('\n').trim();
+    const leading = LEADING_MARKER.test(prose);
+    if (!leading && generatedPlaceholderPrefixIndex(prose) === undefined)
+        return null;
+    // Which rule matched decides where the placeholder is, so the locator is told.
+    // When both match the leading marker wins: it sits at or above the generated
+    // sentence, and the earliest marker is the one a reader scanning down meets.
+    return { line: content === undefined ? undefined : findPlaceholderLine(content, leading) };
+}
+/**
+ * The line inside the `## Purpose` section carrying the placeholder, so the
+ * warning points at the text to replace rather than at the file.
+ *
+ * Which line that is depends on the rule that matched. A leading marker is the
+ * section's first non-blank line by definition. The generated sentence is not:
+ * it can follow prose somebody wrote, and naming the first non-blank line then
+ * points at that prose - a line the reader can see is fine, which reads as the
+ * check being wrong rather than the Purpose being unwritten.
+ *
+ * Fenced lines are skipped on the way, for the reason detection skips them, and
+ * so a `## Requirements` quoted inside a fence cannot end the section early.
+ *
+ * Undefined when the placeholder cannot be located - no section header, or a
+ * generated sentence no single line carries. The caller then reports the finding
+ * without a line rather than with a guessed one, since a wrong line number is
+ * worse than none.
+ *
+ * Line endings are normalised first, so the same spec reports the same line
+ * whether it was saved on Windows or on macOS/Linux.
+ */
+function findPlaceholderLine(content, leading) {
+    const lines = content.replace(/\r\n?/g, '\n').split('\n');
+    const fenced = buildCodeFenceMask(lines);
+    const headerIndex = lines.findIndex((line, index) => !fenced[index] && PURPOSE_HEADER.test(line));
+    if (headerIndex === -1)
+        return undefined;
+    const purposeLines = [];
+    for (let i = headerIndex + 1; i < lines.length; i++) {
+        if (fenced[i])
+            continue;
+        if (TOP_LEVEL_HEADER.test(lines[i]))
+            break;
+        if (leading && lines[i].trim())
+            return i + 1;
+        purposeLines.push({ line: i + 1, text: lines[i] });
+    }
+    if (leading)
+        return undefined;
+    const purpose = purposeLines.map(({ text }) => text).join('\n');
+    const prefixAt = generatedPlaceholderPrefixIndex(purpose);
+    if (prefixAt === undefined)
+        return undefined;
+    const lineOffset = purpose.slice(0, prefixAt).split('\n').length - 1;
+    return purposeLines[lineOffset]?.line;
+}
+//# sourceMappingURL=purpose-placeholder.js.map

package/dist/core/validation/validator.js

@@ -12,6 +12,7 @@ import { discoverSpecFiles, hasAnyFileUnder } from '../../utils/spec-discovery.j
 import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../../utils/change-metadata.js';
 import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
 import { findTaskNumberingIssues } from './task-numbering.js';
+import { findPurposePlaceholderIssue } from './purpose-placeholder.js';
 import { getPackageSchemasDir, getSchemaDir } from '../artifact-graph/index.js';
 export class Validator {
     strictMode;
@@ -557,7 +558,21 @@ export class Validator {
                 message: structuralIssue.message,
             });
         }
-        if (spec.overview.length < MIN_PURPOSE_LENGTH) {
+        // The placeholder is longer than MIN_PURPOSE_LENGTH, so the brevity check
+        // below cannot reach it; it is reported on its own terms instead. Checked
+        // first because a hand-written "TBD" is both a placeholder and too brief,
+        // and only one of those two tells the author what to do. (A "TODO" opening
+        // the Purpose reads the same way, so it is the same finding.)
+        const placeholder = findPurposePlaceholderIssue(spec.overview, content);
+        if (placeholder) {
+            issues.push({
+                level: 'WARNING',
+                path: 'overview',
+                line: placeholder.line,
+                message: VALIDATION_MESSAGES.PURPOSE_IS_PLACEHOLDER,
+            });
+        }
+        else if (spec.overview.length < MIN_PURPOSE_LENGTH) {
             issues.push({
                 level: 'WARNING',
                 path: 'overview',

package/dist/utils/requirement-diff.d.ts

@@ -0,0 +1,42 @@
+/** A main-spec requirement block, and how its header matched the delta's. */
+export interface MatchedRequirementBlock {
+    raw: string;
+    /** The header name as the main spec spells it. */
+    name: string;
+    /**
+     * False when the two headers differ only in case or interior spacing. Archive
+     * matches names exactly, so an inexact match is a real problem to report even
+     * though the diff below it is still the one the author meant.
+     */
+    exact: boolean;
+}
+/**
+ * Find the raw markdown block for a requirement by name in a spec file.
+ *
+ * Delegates to extractRequirementsSection() which already handles code fences,
+ * section boundaries, and requirement header parsing. We just look up by name:
+ * exactly first, then falling back to the shared case/whitespace fold so a
+ * header that differs only in spelling still shows its diff, flagged inexact.
+ *
+ * Returns null if no requirement header matches either way.
+ */
+export declare function extractRequirementBlock(specContent: string, requirementName: string): MatchedRequirementBlock | null;
+/**
+ * Compute a unified diff between a main-spec requirement block and the delta
+ * block that replaces it. A null main block (new capability) diffs against the
+ * empty string, so every line reads as an addition.
+ *
+ * Uses structuredPatch to retain unified-diff hunk ranges while omitting the
+ * synthetic file headers, since the caller provides its own labeling.
+ */
+export declare function diffRequirementBlock(baseBlock: string | null, deltaBlock: string, label: string): string;
+/**
+ * Build a map from folded RENAMED TO name to the original main-spec name.
+ * Renames apply in source order, so a chain such as A -> B -> C maps C back to
+ * A. That is the block a later MODIFIED C replaces.
+ */
+export declare function buildRenameMap(renames: Array<{
+    from: string;
+    to: string;
+}>): Map<string, string>;
+//# sourceMappingURL=requirement-diff.d.ts.map