freeharness 0.4.1 → 0.4.2

package/node_modules/@freeharness/sdd/dist/src/shim/instructions.js

@@ -13,8 +13,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parse as parseYaml } from 'yaml';
-import { loadChangeContext, generateInstructions, resolveSchema, resolveSchemaForChange, getSchemaDir, resolveArtifactOutputPath, resolveArtifactOutputs, parseTaskLines, METADATA_FILENAME, } from '../../vendor/openspec/engine/index.js';
-import { planningHomeStub, printJson, validateChangeExists, validateSchemaExists } from './shared.js';
+import { loadChangeContext, generateInstructions, resolveSchema, resolveSchemaForChange, getSchemaDir, resolveArtifactOutputs, parseTaskLines, METADATA_FILENAME, } from '../../vendor/openspec/engine/index.js';
+import { findUnreadDeltaFilesSync } from '../../vendor/openspec/validation/spec-discovery.js';
+import { escapeEnvelopeAttribute, escapeEnvelopeTags, findMissingTaskCheckboxWarning, planningHomeStub, printJson, sanitizeInline, validateChangeExists, validateSchemaExists, } from './shared.js';
+import { missingCapabilitySpecs } from './proposal-capabilities.js';
+import { missingDeltaSpecsWarning, specsIncompleteWarning, tasksWithoutCheckboxWarning, unknownArtifactIdWarning, unreadDeltaFileWarning, } from './warnings.js';
 const SPECIAL_TARGETS = new Set(['apply', 'archive']);
 export function instructionsHandler(projectRoot, artifactId, options) {
     const changeName = validateChangeExists(options.change, projectRoot);
@@ -48,7 +51,10 @@ export function instructionsHandler(projectRoot, artifactId, options) {
 }
 export function printInstructionsText(instructions, isBlocked) {
     const { artifactId, changeName, schemaName, changeDir, resolvedOutputPath, description, instruction, template, dependencies, unlocks, } = instructions;
-    console.log(`<artifact id="${artifactId}" change="${changeName}" schema="${schemaName}">`);
+    // a quote in changeName closes the attribute otherwise
+    console.log(`<artifact id="${escapeEnvelopeAttribute(artifactId)}"` +
+        ` change="${escapeEnvelopeAttribute(changeName)}"` +
+        ` schema="${escapeEnvelopeAttribute(schemaName)}">`);
     console.log();
     if (instructions.skipped) {
         console.log('<warning>');
@@ -62,13 +68,13 @@ export function printInstructionsText(instructions, isBlocked) {
         const missing = dependencies.filter((d) => !d.done).map((d) => d.id);
         console.log('<warning>');
         console.log('This artifact has unmet dependencies. Complete them first or proceed with caution.');
-        console.log(`Missing: ${missing.join(', ')}`);
+        console.log(`Missing: ${escapeEnvelopeTags(missing.join(', '))}`);
         console.log('</warning>');
         console.log();
     }
     console.log('<task>');
-    console.log(`Create the ${artifactId} artifact for change "${changeName}".`);
-    console.log(description);
+    console.log(`Create the ${escapeEnvelopeTags(artifactId)} artifact for change "${escapeEnvelopeTags(changeName)}".`);
+    console.log(escapeEnvelopeTags(description));
     console.log('</task>');
     console.log();
     if (dependencies.length > 0) {
@@ -77,50 +83,70 @@ export function printInstructionsText(instructions, isBlocked) {
         console.log();
         for (const dep of dependencies) {
             if (dep.skipped) {
-                console.log(`<dependency id="${dep.id}" status="skipped">`);
+                console.log(`<dependency id="${escapeEnvelopeAttribute(dep.id)}" status="skipped">`);
                 console.log('  <description>Skipped: the change declares skip_specs, so this artifact has no files to read.</description>');
                 console.log('</dependency>');
                 continue;
             }
             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 id="${escapeEnvelopeAttribute(dep.id)}" status="${status}">`);
+            console.log(`  <path>${escapeEnvelopeTags(fullPath)}</path>`);
+            console.log(`  <description>${escapeEnvelopeTags(dep.description)}</description>`);
             console.log('</dependency>');
         }
         console.log('</dependencies>');
         console.log();
     }
     console.log('<output>');
-    console.log(`Write to: ${resolvedOutputPath}`);
+    console.log(`Write to: ${escapeEnvelopeTags(resolvedOutputPath)}`);
     console.log('</output>');
     console.log();
     if (instruction) {
         console.log('<instruction>');
-        console.log(instruction.trim());
+        console.log(escapeEnvelopeTags(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());
+    // Copied verbatim into the output file: only the envelope's own tags are neutralized.
+    console.log(escapeEnvelopeTags(template.trim()));
     console.log('</template>');
     console.log();
     if (unlocks.length > 0) {
         console.log('<unlocks>');
-        console.log(`Completing this artifact enables: ${unlocks.join(', ')}`);
+        console.log(`Completing this artifact enables: ${escapeEnvelopeTags(unlocks.join(', '))}`);
         console.log('</unlocks>');
         console.log();
     }
     console.log('</artifact>');
 }
+/**
+ * Parses one line at a time so each task keeps its own index in the file; the
+ * engine reader stays the single definition of what a task line is.
+ */
+export function parseLocatedTasks(content, sourcePath) {
+    const tasks = [];
+    for (const [index, line] of content.split('\n').entries()) {
+        const [task] = parseTaskLines(line);
+        if (task)
+            tasks.push({ ...task, sourcePath, line: index + 1 });
+    }
+    return tasks;
+}
 function toTaskItems(parsed) {
     const tasks = [];
     for (const task of parsed) {
         if (task.description.length === 0)
             continue;
-        tasks.push({ id: `${tasks.length + 1}`, description: task.description, done: task.done });
+        tasks.push({
+            id: `${tasks.length + 1}`,
+            description: task.description,
+            done: task.done,
+            sourcePath: task.sourcePath,
+            line: task.line,
+        });
     }
     return tasks;
 }
@@ -129,22 +155,29 @@ const SPECS_PATH_PREFIX = 'specs/';
 function isSpecsArtifactPath(generates) {
     return generates.replace(/^(?:\.\/)+/, '').startsWith(SPECS_PATH_PREFIX);
 }
+/** Empty when the schema writes no specs or the change skips any of them, so neither case warns. */
+function activeSpecArtifacts(artifacts, skippedArtifacts) {
+    const specArtifacts = artifacts.filter((artifact) => isSpecsArtifactPath(artifact.generates));
+    return specArtifacts.some((artifact) => skippedArtifacts?.has(artifact.id)) ? [] : specArtifacts;
+}
+function missingCapabilityWarnings(changeDir) {
+    const missing = missingCapabilitySpecs(changeDir).map((capability) => sanitizeInline(capability));
+    return missing.length > 0 ? [specsIncompleteWarning(missing)] : [];
+}
 /**
- * Every artifact still to build before apply's own gate is satisfied, in the
- * schema's declared build order - the transitive closure of `apply.requires`.
- *
- * Apply blocks on the first artifact in `requiredArtifactIds` that is not yet
- * complete, so naming only that one hides the rest of the chain: a change
- * holding only a proposal, whose schema chains specs -> design -> tasks,
- * would be told only "Missing artifacts: tasks" - an instruction that, taken
- * literally, skips every artifact tasks itself depends on.
+ * The status side of the proposal-coverage check. Unlike apply it also fires
+ * with no delta at all, since status has no zero-delta warning to defer to.
  */
+export function collectSpecsIncompleteWarnings(artifacts, changeDir, skippedArtifacts) {
+    return activeSpecArtifacts(artifacts, skippedArtifacts).length > 0 ? missingCapabilityWarnings(changeDir) : [];
+}
 /**
- * Every artifact still to build (`missing`), plus a warning for any id in the
- * `requires` chain that names no artifact in the schema. An unknown id used to
- * be dropped by the `if (!artifact) continue` below with no trace anywhere in
- * the instructions payload - a typo in a schema's `requires` list read as an
- * empty, satisfied dependency instead of the configuration error it is.
+ * Every artifact in the transitive closure of `apply.requires` still to build
+ * (`missing`), in the schema's build order, since naming only the first hop
+ * apply blocks on would hide the rest of the chain. Plus a warning for any
+ * id in the `requires` chain that names no artifact in the schema: without it,
+ * a typo in a schema's `requires` list reads as an empty, satisfied dependency
+ * instead of the configuration error it is.
  */
 function collectMissingPrerequisites(requiredArtifactIds, schema, buildOrder, completed) {
     const byId = new Map(schema.artifacts.map((artifact) => [artifact.id, artifact]));
@@ -175,9 +208,7 @@ function collectMissingPrerequisites(requiredArtifactIds, schema, buildOrder, co
     // real artifact. Pushing it to the end keeps real artifacts in their proper
     // order and leaves the broken one visibly last.
     const missingSorted = [...missing].sort((a, b) => (order.get(a) ?? Number.MAX_SAFE_INTEGER) - (order.get(b) ?? Number.MAX_SAFE_INTEGER));
-    const warnings = unknownIds.length > 0
-        ? [`Schema declares a dependency on an artifact id not defined in this schema: ${unknownIds.join(', ')}.`]
-        : [];
+    const warnings = unknownIds.length > 0 ? [unknownArtifactIdWarning(unknownIds)] : [];
     return { missing: missingSorted, warnings };
 }
 /**
@@ -193,18 +224,22 @@ function collectMissingPrerequisites(requiredArtifactIds, schema, buildOrder, co
  * required artifact, the absent specs are the next step, not a warning. A
  * schema with no spec-producing artifact, or a change carrying `skip_specs`,
  * never triggers it.
+ *
+ * A delta file the merge path never reads still satisfies the specs glob,
+ * so it reads as written here while validate rejects it. Each one is named.
+ * One delta also satisfies the glob, so a capability the proposal lists
+ * without its spec.md is named too.
  */
 function collectApplyWarnings(state, schema, changeDir, changeName, skippedArtifacts) {
     if (state === 'blocked')
         return [];
-    const specArtifacts = schema.artifacts.filter((artifact) => isSpecsArtifactPath(artifact.generates));
+    const specArtifacts = activeSpecArtifacts(schema.artifacts, skippedArtifacts);
     if (specArtifacts.length === 0)
         return [];
-    if (specArtifacts.some((artifact) => skippedArtifacts?.has(artifact.id)))
-        return [];
+    const unreadWarnings = findUnreadDeltaFilesSync(path.join(changeDir, 'specs')).map((file) => unreadDeltaFileWarning(changeName, file));
     const hasDeltas = specArtifacts.some((artifact) => resolveArtifactOutputs(changeDir, artifact.generates).length > 0);
     if (hasDeltas)
-        return [];
+        return [...unreadWarnings, ...missingCapabilityWarnings(changeDir)];
     const metadataPath = path.join(changeDir, METADATA_FILENAME);
     // Names the artifact this schema actually declares rather than the literal
     // "specs": a schema whose spec-producing artifact is, say, "contracts" would
@@ -212,11 +247,7 @@ function collectApplyWarnings(state, schema, changeDir, changeName, skippedArtif
     // With more than one such artifact there is no single right answer, so the
     // id becomes a placeholder instead of a guess.
     const specTarget = specArtifacts.length === 1 ? specArtifacts[0].id : '<artifact-id>';
-    return [
-        `This change has no delta specs and does not declare \`skip_specs: true\`, so \`openspec validate ${changeName}\` fails on it. ` +
-            `Write the delta specs before implementing (\`openspec instructions ${specTarget} --change ${changeName}\`), ` +
-            `or add \`skip_specs: true\` to ${metadataPath} if this change really changes no specified behavior.`,
-    ];
+    return [...unreadWarnings, missingDeltaSpecsWarning(changeName, specTarget, metadataPath)];
 }
 function buildApplyInstructions(projectRoot, changeName, schemaName) {
     const context = loadChangeContext(projectRoot, changeName, schemaName);
@@ -241,13 +272,25 @@ function buildApplyInstructions(projectRoot, changeName, schemaName) {
         if (outputs.length > 0)
             contextFiles[artifact.id] = outputs;
     }
+    // tracksFile may be a glob; resolve every concrete file it matches.
     let parsedTasks = [];
+    const unavailableTrackingFiles = [];
     let tracksFileExists = false;
     if (tracksFile) {
-        const tracksPath = resolveArtifactOutputPath(changeDir, tracksFile);
-        tracksFileExists = fs.existsSync(tracksPath);
-        if (tracksFileExists) {
-            parsedTasks = parseTaskLines(fs.readFileSync(tracksPath, 'utf-8'));
+        const tracksPaths = resolveArtifactOutputs(changeDir, tracksFile);
+        tracksFileExists = tracksPaths.length > 0;
+        for (const tracksPath of tracksPaths) {
+            try {
+                parsedTasks.push(...parseLocatedTasks(fs.readFileSync(tracksPath, 'utf-8'), tracksPath));
+            }
+            catch (error) {
+                const code = error?.code;
+                const message = error instanceof Error ? error.message : String(error);
+                unavailableTrackingFiles.push({
+                    path: tracksPath,
+                    reason: code && !message.includes(code) ? `${code}: ${message}` : message,
+                });
+            }
         }
     }
     const tasks = toTaskItems(parsedTasks);
@@ -264,13 +307,17 @@ function buildApplyInstructions(projectRoot, changeName, schemaName) {
         state = 'blocked';
         instruction = `The ${path.basename(tracksFile)} file is missing and must be created.\nUse openspec-continue-change to generate the tracking file.`;
     }
+    else if (tracksFile && unavailableTrackingFiles.length > 0 && tasks.length === 0) {
+        state = 'blocked';
+        instruction = 'No readable task descriptions are available.';
+    }
     else if (tracksFile && tracksFileExists && tasks.length === 0) {
         state = 'blocked';
         instruction = `The ${path.basename(tracksFile)} file exists but contains no tasks to work on.\nAdd tasks or regenerate it with openspec-continue-change.`;
     }
-    else if (tracksFile && remaining === 0 && total > 0) {
+    else if (tracksFile && unavailableTrackingFiles.length === 0 && remaining === 0 && total > 0) {
         state = 'all_done';
-        instruction = 'All tasks are complete! This change is ready to be archived.';
+        instruction = 'All tracked tasks are complete.\nReview or verify the change as appropriate before archiving.';
     }
     else if (!tracksFile) {
         state = 'ready';
@@ -282,14 +329,23 @@ function buildApplyInstructions(projectRoot, changeName, schemaName) {
             schemaInstruction?.trim() ??
                 'Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification.';
     }
+    if (unavailableTrackingFiles.length > 0) {
+        const details = unavailableTrackingFiles.map((file) => `- ${file.path}: ${file.reason}`).join('\n');
+        instruction += `\nTask completion is not verified because tracking evidence was unavailable:\n${details}`;
+    }
     // Computed regardless of state: a "ready" change (apply.requires satisfied)
     // can still be missing the artifacts its own required artifact transitively
     // depends on - the schema's own gate does not require them, so this is the
     // only place that names the rest of the chain.
     const { missing: missingPrerequisites, warnings: unknownIdWarnings } = collectMissingPrerequisites(requiredArtifactIds, schema, context.graph.getBuildOrder(), context.completed);
+    // Orthogonal to `state`, and checked even when blocked: a tracks file with
+    // no checkbox reads as zero tasks and blocks apply with "contains no tasks
+    // to work on", which names the symptom but not the cause (#1774).
+    const checkboxWarning = findMissingTaskCheckboxWarning(changeDir, projectRoot);
     const warnings = [
         ...unknownIdWarnings,
         ...collectApplyWarnings(state, schema, changeDir, changeName, context.skippedArtifacts),
+        ...(checkboxWarning ? [tasksWithoutCheckboxWarning(checkboxWarning)] : []),
     ];
     return {
         changeName,
@@ -298,6 +354,8 @@ function buildApplyInstructions(projectRoot, changeName, schemaName) {
         contextFiles,
         progress: { total, complete, remaining },
         tasks,
+        taskTrackingConfigured: tracksFile !== null,
+        ...(unavailableTrackingFiles.length > 0 ? { unavailableTrackingFiles } : {}),
         state,
         ...(missingArtifacts.length > 0 ? { missingArtifacts } : {}),
         ...(missingPrerequisites.length > 0 ? { missingPrerequisites } : {}),
@@ -346,7 +404,7 @@ function applyInstructions(projectRoot, changeName, options) {
     if (instructions.warnings && instructions.warnings.length > 0) {
         console.log('### Warnings');
         for (const warning of instructions.warnings) {
-            console.log(`- ${warning}`);
+            console.log(`- ${warning.message}`);
         }
         console.log();
     }
@@ -367,7 +425,8 @@ function applyInstructions(projectRoot, changeName, options) {
     if (instructions.tasks.length > 0) {
         console.log('### Tasks');
         for (const task of instructions.tasks) {
-            console.log(`- ${task.done ? '[x]' : '[ ]'} ${task.description}`);
+            // Upstream prints no location; a text reader needs it as much as the JSON skill does.
+            console.log(`- ${task.done ? '[x]' : '[ ]'} ${task.description} (${task.sourcePath}:${task.line})`);
         }
         console.log();
     }
@@ -442,14 +501,16 @@ function archiveInstructions(projectRoot, changeName, options) {
     console.log(`## Archive Inputs: ${changeName}`);
     console.log();
     if (payload.context) {
+        // Verbatim on purpose: escaping '#' would also fire inside fenced code.
         console.log('### Project Context (required instruction input)');
         console.log(payload.context);
         console.log();
     }
     if (payload.operationGuidance) {
         console.log('### Operation Guidance (advisory)');
+        // Flattened, never truncated: guidance an agent has to follow in full.
         for (const g of payload.operationGuidance)
-            console.log(`- ${g}`);
+            console.log(`- ${sanitizeInline(g, Infinity)}`);
         console.log();
     }
     if (!payload.context && !payload.operationGuidance) {

package/node_modules/@freeharness/sdd/dist/src/shim/list.d.ts

@@ -2,4 +2,4 @@ export interface ListOptions {
     json?: boolean;
     sort?: 'recent' | 'name';
 }
-export declare function listHandler(projectRoot: string, options: ListOptions): Promise<number>;
+export declare function listHandler(projectRoot: string | null, options: ListOptions): Promise<number>;

package/node_modules/@freeharness/sdd/dist/src/shim/list.js

@@ -2,24 +2,43 @@
 //
 // Reconstructed from src/core/list.ts (changes mode), minus store/root-selection.
 // JSON shape matches upstream: { changes: [{ name, completedTasks, totalTasks,
-// lastModified, status }] }, sorted most-recently-modified first by default.
+// lastModified, status }], root }, sorted most-recently-modified first by
+// default. Root resolution is the caller's job (bin.ts): a null projectRoot
+// still yields a valid JSON document, `{ changes: [], root: null }`, on exit
+// code 1, and creates nothing on disk, so a caller such as the emitted /opsx
+// workflows can probe for a project without a write.
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getTaskProgressForChange, formatTaskStatus } from '../../vendor/openspec/engine/index.js';
 import { changesDirFor, printableId, printJson } from './shared.js';
+import { describeNestedChange, findNestedChanges } from './nested-change.js';
+import { nestedChangeWarning } from './warnings.js';
+/** A removed-mid-listing or dangling/looping symlink entry: skip it rather than fail the listing. */
+function isUnresolvableEntryError(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return false;
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ELOOP';
+}
 /** Most recent mtime of any file under a directory (recursive). */
 function getLastModified(dirPath) {
     let latest = null;
     const walk = (dir) => {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
             const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                walk(full);
+            try {
+                if (entry.isDirectory()) {
+                    walk(full);
+                }
+                else {
+                    const stat = fs.statSync(full);
+                    if (latest === null || stat.mtime > latest)
+                        latest = stat.mtime;
+                }
             }
-            else {
-                const stat = fs.statSync(full);
-                if (latest === null || stat.mtime > latest)
-                    latest = stat.mtime;
+            catch (error) {
+                if (!isUnresolvableEntryError(error))
+                    throw error;
             }
         }
     };
@@ -28,6 +47,14 @@ function getLastModified(dirPath) {
 }
 export async function listHandler(projectRoot, options) {
     const { json = false, sort = 'recent' } = options;
+    if (!projectRoot) {
+        if (json)
+            printJson({ changes: [], root: null });
+        else
+            console.error('No OpenSpec root found. Run this inside a project with an openspec/ directory.');
+        return 1;
+    }
+    const root = { path: projectRoot };
     const changesDir = changesDirFor(projectRoot);
     let entries;
     try {
@@ -44,11 +71,13 @@ export async function listHandler(projectRoot, options) {
         .map((e) => e.name);
     if (changeDirs.length === 0) {
         if (json)
-            printJson({ changes: [] });
+            printJson({ changes: [], root });
         else
             console.log('No active changes found.');
         return 0;
     }
+    const nestedFindings = findNestedChanges(changesDir, changeDirs);
+    const nestedByName = new Map(nestedFindings.map((f) => [f.name, f]));
     const changes = [];
     for (const name of changeDirs) {
         const progress = await getTaskProgressForChange(changesDir, name, projectRoot);
@@ -59,6 +88,7 @@ export async function listHandler(projectRoot, options) {
             openTasks: progress.open,
             dispositionedTasks: progress.dispositioned,
             lastModified: getLastModified(path.join(changesDir, name)),
+            ...(nestedByName.has(name) ? { nested: nestedByName.get(name).nested } : {}),
         });
     }
     if (sort === 'recent') {
@@ -75,7 +105,14 @@ export async function listHandler(projectRoot, options) {
                 totalTasks: c.totalTasks,
                 lastModified: c.lastModified.toISOString(),
                 status: c.totalTasks === 0 ? 'no-tasks' : c.openTasks === 0 ? 'complete' : 'in-progress',
+                ...(c.nested ? { nested: c.nested } : {}),
             })),
+            ...(nestedFindings.length > 0
+                ? {
+                    warnings: nestedFindings.map(nestedChangeWarning),
+                }
+                : {}),
+            root,
         });
         return 0;
     }
@@ -83,13 +120,19 @@ export async function listHandler(projectRoot, options) {
     const names = new Map(changes.map((c) => [c.name, printableId(c.name)]));
     const nameWidth = Math.max(...[...names.values()].map((n) => n.length));
     for (const change of changes) {
-        const status = formatTaskStatus({
-            total: change.totalTasks,
-            completed: change.completedTasks,
-            open: change.openTasks,
-            dispositioned: change.dispositionedTasks,
-        });
+        const status = change.nested
+            ? 'not a change'
+            : formatTaskStatus({
+                total: change.totalTasks,
+                completed: change.completedTasks,
+                open: change.openTasks,
+                dispositioned: change.dispositionedTasks,
+            });
         console.log(`  ${names.get(change.name).padEnd(nameWidth)}     ${status}`);
     }
+    for (const finding of nestedFindings) {
+        console.log();
+        console.log(`Warning: ${describeNestedChange(finding)}`);
+    }
     return 0;
 }

package/node_modules/@freeharness/sdd/dist/src/shim/nested-change.d.ts

@@ -0,0 +1,7 @@
+export interface NestedChangeFinding {
+    name: string;
+    nested: string[];
+}
+export declare function findNestedChangesIn(changesDir: string, name: string): NestedChangeFinding | undefined;
+export declare function findNestedChanges(changesDir: string, names: string[]): NestedChangeFinding[];
+export declare function describeNestedChange(finding: NestedChangeFinding): string;

package/node_modules/@freeharness/sdd/dist/src/shim/nested-change.js

@@ -0,0 +1,118 @@
+// Detects `changes/<area>/<name>/` namespace folders wrapping nested change
+// directories, which OpenSpec does not support: a change is a directory
+// directly under `changes/` and nothing else.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { artifactOutputExists, resolveSchema, resolveSchemaForChange, METADATA_FILENAME, } from '../../vendor/openspec/engine/index.js';
+const CHANGE_ROOT_MARKERS = [METADATA_FILENAME, 'proposal.md', 'tasks.md', 'design.md'];
+const DELTA_SPECS_DIR = 'specs';
+const MAX_NESTING_DEPTH = 3;
+function hasChangeRootMarker(dir) {
+    return CHANGE_ROOT_MARKERS.some((marker) => {
+        try {
+            return fs.statSync(path.join(dir, marker)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function hasAnyFileUnder(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (entry.isFile() || entry.isSymbolicLink())
+            return true;
+        if (entry.isDirectory() && hasAnyFileUnder(path.join(dir, entry.name)))
+            return true;
+    }
+    return false;
+}
+function hasSchemaOutput(dir, projectRoot) {
+    try {
+        const schema = resolveSchema(resolveSchemaForChange(dir, undefined, projectRoot), projectRoot);
+        return schema.artifacts.some((artifact) => artifactOutputExists(dir, artifact.generates));
+    }
+    catch {
+        return false;
+    }
+}
+function looksLikeChange(dir, projectRoot) {
+    if (hasChangeRootMarker(dir))
+        return true;
+    if (hasAnyFileUnder(path.join(dir, DELTA_SPECS_DIR)))
+        return true;
+    return hasSchemaOutput(dir, projectRoot);
+}
+function hasOwnFile(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    return entries.some((entry) => !entry.name.startsWith('.') && !entry.isDirectory());
+}
+function readSubdirectories(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.')).map((entry) => entry.name);
+}
+function collectNested(dir, prefix, depth, found, projectRoot) {
+    if (depth > MAX_NESTING_DEPTH)
+        return;
+    for (const child of readSubdirectories(dir)) {
+        const childPath = path.join(dir, child);
+        const id = `${prefix}/${child}`;
+        if (looksLikeChange(childPath, projectRoot)) {
+            found.push(id);
+            continue;
+        }
+        collectNested(childPath, id, depth + 1, found, projectRoot);
+    }
+}
+export function findNestedChangesIn(changesDir, name) {
+    if (name === 'archive' || name.startsWith('.'))
+        return undefined;
+    const dir = path.join(changesDir, name);
+    const projectRoot = path.resolve(changesDir, '..', '..');
+    if (looksLikeChange(dir, projectRoot))
+        return undefined;
+    if (hasOwnFile(dir))
+        return undefined;
+    const nested = [];
+    collectNested(dir, name, 1, nested, projectRoot);
+    if (nested.length === 0)
+        return undefined;
+    return { name, nested: nested.sort() };
+}
+export function findNestedChanges(changesDir, names) {
+    return names
+        .map((name) => findNestedChangesIn(changesDir, name))
+        .filter((finding) => finding !== undefined);
+}
+function flatten(nestedId) {
+    return nestedId.split('/').join('-');
+}
+export function describeNestedChange(finding) {
+    const list = finding.nested.map((id) => `openspec/changes/${id}/`).join(', ');
+    const example = flatten(finding.nested[0]);
+    return (`"${finding.name}" is not a change: it is a folder wrapping ${list}. ` +
+        'A change must be a directory directly under openspec/changes/, so those ' +
+        'nested directories are invisible to OpenSpec while the folder around them ' +
+        'is reported as a change. Nested paths are supported under openspec/specs/ ' +
+        `only. Rename each nested change to a flat name (for example "${example}").`);
+}

package/node_modules/@freeharness/sdd/dist/src/shim/new-change.js

@@ -92,7 +92,9 @@ export function newChangeHandler(projectRoot, name, options) {
     if (!name)
         throw new Error('Missing required argument <name>');
     validateChangeName(name);
-    const schemaName = options.schema ?? DEFAULT_SCHEMA;
+    // An empty or blank flag value (including a trailing `--schema`) is no schema choice,
+    // so it must not reach the lookup as a schema name.
+    const schemaName = options.schema?.trim() ? options.schema : DEFAULT_SCHEMA;
     validateSchemaExists(schemaName, projectRoot);
     const openspecDir = path.join(projectRoot, 'openspec');
     const changeDir = path.join(openspecDir, 'changes', name);

package/node_modules/@freeharness/sdd/dist/src/shim/proposal-capabilities.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Names in document order, deduplicated. Only top-level `- ` bullets count, so
+ * a sub-bullet or a wrapped description line naming code never reads as a
+ * capability; any other unindented label or subheading closes the counted list.
+ */
+export declare function parseProposalCapabilities(markdown: string): string[];
+/**
+ * Listed capabilities without a `spec.md` under the change's `specs/`. A name
+ * that resolves outside `specs/` (an untrusted `../` path) can hold no delta
+ * there, so it counts as missing instead of probing the path.
+ */
+export declare function missingCapabilitySpecs(changeDir: string): string[];