freeharness 0.4.1 → 0.4.2

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

@@ -0,0 +1,94 @@
+// The capabilities a proposal promises a delta spec for, read from its
+// `## Capabilities` section, and the ones whose `specs/<capability>/spec.md`
+// is not on disk yet. An interrupted propose leaves exactly that gap, which
+// the specs glob alone cannot see once a single delta exists.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const COUNTED_LABELS = ['new capabilities:', 'modified capabilities:'];
+function stripHtmlComments(markdown) {
+    let out = '';
+    let from = 0;
+    for (;;) {
+        const open = markdown.indexOf('<!--', from);
+        if (open === -1)
+            return out + markdown.slice(from);
+        out += markdown.slice(from, open);
+        const close = markdown.indexOf('-->', open + 4);
+        if (close === -1)
+            return out;
+        from = close + 3;
+    }
+}
+function firstBacktickedName(bullet) {
+    const open = bullet.indexOf('`');
+    if (open === -1)
+        return '';
+    const close = bullet.indexOf('`', open + 1);
+    return close === -1 ? '' : bullet.slice(open + 1, close).trim();
+}
+function isPlaceholder(name) {
+    return name === '' || name.toLowerCase() === 'none' || (name.startsWith('<') && name.endsWith('>'));
+}
+/**
+ * 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 function parseProposalCapabilities(markdown) {
+    const names = [];
+    const seen = new Set();
+    let inSection = false;
+    let counting = false;
+    for (const rawLine of stripHtmlComments(markdown).split('\n')) {
+        const line = rawLine.trimEnd();
+        if (line.startsWith('# ') || line.startsWith('## ')) {
+            inSection = line.slice(line.indexOf(' ') + 1).trim().toLowerCase() === 'capabilities';
+            counting = false;
+            continue;
+        }
+        if (!inSection)
+            continue;
+        if (line.startsWith('- ')) {
+            const name = counting ? firstBacktickedName(line) : '';
+            if (!isPlaceholder(name) && !seen.has(name)) {
+                seen.add(name);
+                names.push(name);
+            }
+            continue;
+        }
+        if (line.length === 0 || /^\s/.test(line))
+            continue;
+        const label = line.toLowerCase();
+        if (COUNTED_LABELS.some((counted) => label.startsWith(counted)))
+            counting = true;
+        else if (label.startsWith('#') || label.endsWith(':'))
+            counting = false;
+    }
+    return names;
+}
+/**
+ * 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 function missingCapabilitySpecs(changeDir) {
+    let proposal;
+    try {
+        proposal = fs.readFileSync(path.join(changeDir, 'proposal.md'), 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const specsDir = path.resolve(changeDir, 'specs');
+    return parseProposalCapabilities(proposal).filter((capability) => {
+        const specFile = path.resolve(specsDir, capability, 'spec.md');
+        if (!specFile.startsWith(specsDir + path.sep))
+            return true;
+        try {
+            return !fs.statSync(specFile).isFile();
+        }
+        catch {
+            return true;
+        }
+    });
+}

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

@@ -1,5 +1,10 @@
 /** Emits a value as pretty JSON on stdout (the single-document `--json` contract). */
 export declare function printJson(payload: unknown): void;
+/** Flattens repo-controlled text to one line, so a newline cannot forge a sibling instruction line. */
+export declare function sanitizeInline(value: string, maxLength?: number): string;
+export declare function escapeEnvelopeTags(value: string): string;
+/** Attribute values are ids and directory names, never prose: escape every metacharacter. */
+export declare function escapeEnvelopeAttribute(value: string): string;
 /**
  * A task's numbering label for a message (the leading `N.N` of its
  * description), falling back to its line number when the description carries
@@ -54,3 +59,15 @@ export declare function resolveChangeId(projectRoot: string, id: string): 'in-fl
 export declare function validateChangeExists(changeName: string | undefined, projectRoot: string): string;
 /** Validates that a schema resolves; throws with the available list otherwise. */
 export declare function validateSchemaExists(schemaName: string, projectRoot?: string): string;
+/**
+ * Warns when every file a change's schema tracks as tasks contains list
+ * items but not one checkbox. Undefined when the schema tracks no task file
+ * at all (a bare top-level `tasks.md` no artifact declares is not read by
+ * this check; warning about it would be a guess about a file the tool never
+ * opens), when the tracked set has at least one checkbox anywhere, when a
+ * tracked file could not be read (it may hold the checkboxes the unreadable
+ * file lost), or when no tracked file carries a bare list item either. The
+ * message opens with `<file relative to changeDir>:<line of the first bare
+ * list item>`.
+ */
+export declare function findMissingTaskCheckboxWarning(changeDir: string, projectRoot: string): string | undefined;

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

@@ -6,11 +6,44 @@
 // src/root-resolver.ts).
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { getSchemaDir, listSchemas } from '../../vendor/openspec/engine/index.js';
+import { getSchemaDir, listSchemas, parseTaskLines } from '../../vendor/openspec/engine/index.js';
+import { resolveTaskFilesForChange } from '../../vendor/openspec/engine/task-progress.js';
+import { describeNestedChange, findNestedChangesIn } from './nested-change.js';
 /** Emits a value as pretty JSON on stdout (the single-document `--json` contract). */
 export function printJson(payload) {
     console.log(JSON.stringify(payload, null, 2));
 }
+/** Flattens repo-controlled text to one line, so a newline cannot forge a sibling instruction line. */
+export function sanitizeInline(value, maxLength = 300) {
+    const flattened = value.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
+    return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}…` : flattened;
+}
+/** The tags `printInstructionsText` uses to frame its blocks; a block ends only at its own closing tag. */
+const ENVELOPE_TAGS = [
+    'artifact',
+    'dependencies',
+    'dependency',
+    'description',
+    'instruction',
+    'output',
+    'path',
+    'template',
+    'task',
+    'unlocks',
+    'warning',
+];
+// Requires real `name="value"` syntax, not bare text: schema guidance writes
+// `<task ids>`-style placeholders that must not read as a forged opener.
+const ENVELOPE_TAG = new RegExp(`<(/?)(${ENVELOPE_TAGS.join('|')})((?:\\s+[A-Za-z_:][\\w:.-]*="[^"]*")*)\\s*>`, 'gi');
+// Narrow on purpose: escaping every angle bracket also works, but mangles
+// ordinary content like `### Requirement: <name>`.
+export function escapeEnvelopeTags(value) {
+    return value.replace(ENVELOPE_TAG, (_match, slash, tag, attrs) => `&lt;${slash}${tag}${attrs ?? ''}&gt;`);
+}
+/** Attribute values are ids and directory names, never prose: escape every metacharacter. */
+export function escapeEnvelopeAttribute(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
 const TASK_ID = /^(\d+(?:\.\d+)+(?:[A-Za-z]+)?)(?=\s|$)/;
 /**
  * A task's numbering label for a message (the leading `N.N` of its
@@ -127,6 +160,13 @@ export function validateChangeExists(changeName, projectRoot) {
         }
         throw new Error(`Change '${changeName}' not found. Available changes:\n  ${available.join('\n  ')}`);
     }
+    // The directory exists but is a namespace folder wrapping nested change
+    // directories. Every artifact lookup below it would report "not started"
+    // for work that is in fact there, so say what is actually wrong instead.
+    const nested = findNestedChangesIn(changesDirFor(projectRoot), changeName);
+    if (nested) {
+        throw new Error(describeNestedChange(nested));
+    }
     return changeName;
 }
 /** Validates that a schema resolves; throws with the available list otherwise. */
@@ -138,3 +178,144 @@ export function validateSchemaExists(schemaName, projectRoot) {
     }
     return schemaName;
 }
+// ---------------------------------------------------------------------------
+// Tracked tasks with no checkbox.
+//
+// Progress counts checkboxes and nothing else: a tasks file written as plain
+// bullets or a numbered list reads as empty to `status`/`instructions apply`
+// and leaves `archive` with no incomplete task to gate on, though the file
+// carries unfinished work to a reader. `findMissingTaskCheckboxWarning`
+// reports the first bare list item once every file the change tracks as
+// tasks has zero checkboxes.
+// ---------------------------------------------------------------------------
+/** A list item carrying text but no checkbox: `- item`, `* item`, `+ item`, `1. item`, `1) item`. */
+const LIST_ITEM = /^\s*(?:[-*+]|\d{1,9}[.)])\s+\S/;
+/**
+ * The indent, in visual columns, at which a top-level line stops being
+ * content and becomes an indented code block per CommonMark. A tab counts as
+ * four.
+ */
+const CODE_BLOCK_COLUMN = 4;
+/** Leading whitespace of a line in visual columns, a tab counting as four. */
+function indentColumns(line) {
+    let column = 0;
+    for (const char of line) {
+        if (char === ' ')
+            column += 1;
+        else if (char === '\t')
+            column += CODE_BLOCK_COLUMN - (column % CODE_BLOCK_COLUMN);
+        else
+            break;
+    }
+    return column;
+}
+/**
+ * A fenced code block delimiter: a run of three or more backticks or tildes
+ * indented at most three spaces, plus whatever follows it on the line (an
+ * info string on an opener, nothing on a valid closer).
+ */
+const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)/;
+/** The YAML front-matter delimiter: exactly three dashes; a longer run is a thematic break. */
+const FRONT_MATTER = /^-{3}\s*$/;
+const COMMENT_OPEN = '<!--';
+const COMMENT_CLOSE = '-->';
+/**
+ * Index of the first line after a leading YAML front-matter block, or 0 when
+ * the document opens with none. A list under `tags:` is metadata about the
+ * file, not the work it tracks.
+ */
+function skipFrontMatter(lines) {
+    if (lines.length === 0 || !FRONT_MATTER.test(lines[0].replace(/^/, '').trimEnd())) {
+        return 0;
+    }
+    for (let index = 1; index < lines.length; index++) {
+        if (FRONT_MATTER.test(lines[index].trimEnd()))
+            return index + 1;
+    }
+    // An unterminated opener is a thematic break, not front matter: every list
+    // in the document stays visible to the scan.
+    return 0;
+}
+/**
+ * 1-based line of the first list item in rendered content, skipping fenced
+ * code, HTML comments, YAML front matter and top-level indented code. Every
+ * exclusion can only silence the warning, never manufacture one.
+ */
+function findFirstListItemLine(content) {
+    const lines = content.split('\n');
+    let openFence;
+    let inComment = false;
+    let index = skipFrontMatter(lines);
+    for (; index < lines.length; index++) {
+        const line = lines[index];
+        if (inComment) {
+            if (line.includes(COMMENT_CLOSE))
+                inComment = false;
+            continue;
+        }
+        const fence = line.match(FENCE);
+        if (fence) {
+            const marker = fence[1][0];
+            const length = fence[1].length;
+            if (openFence === undefined) {
+                openFence = { marker, length };
+            }
+            else if (marker === openFence.marker && length >= openFence.length && fence[2].trim() === '') {
+                // CommonMark: a closer matches its opener's character, runs at least
+                // as long, and carries no info string.
+                openFence = undefined;
+            }
+            continue;
+        }
+        if (openFence !== undefined)
+            continue;
+        // Only a comment that opens the line hides it: `- [ ] 1.1 do it <!-- note`
+        // is a task line first.
+        if (line.trimStart().startsWith(COMMENT_OPEN)) {
+            if (!line.includes(COMMENT_CLOSE, line.indexOf(COMMENT_OPEN) + COMMENT_OPEN.length)) {
+                inComment = true;
+            }
+            continue;
+        }
+        if (LIST_ITEM.test(line) && indentColumns(line) < CODE_BLOCK_COLUMN)
+            return index + 1;
+    }
+    return undefined;
+}
+/**
+ * Warns when every file a change's schema tracks as tasks contains list
+ * items but not one checkbox. Undefined when the schema tracks no task file
+ * at all (a bare top-level `tasks.md` no artifact declares is not read by
+ * this check; warning about it would be a guess about a file the tool never
+ * opens), when the tracked set has at least one checkbox anywhere, when a
+ * tracked file could not be read (it may hold the checkboxes the unreadable
+ * file lost), or when no tracked file carries a bare list item either. The
+ * message opens with `<file relative to changeDir>:<line of the first bare
+ * list item>`.
+ */
+export function findMissingTaskCheckboxWarning(changeDir, projectRoot) {
+    const files = resolveTaskFilesForChange(changeDir, projectRoot);
+    if (files.length === 0)
+        return undefined;
+    const documents = [];
+    for (const file of files) {
+        let content;
+        try {
+            content = fs.readFileSync(file, 'utf-8');
+        }
+        catch {
+            return undefined;
+        }
+        documents.push({ path: file, content });
+    }
+    if (documents.some((document) => parseTaskLines(document.content).length > 0))
+        return undefined;
+    for (const document of documents) {
+        const line = findFirstListItemLine(document.content);
+        if (line !== undefined) {
+            return (`${path.relative(changeDir, document.path)}:${line} lists tasks but carries no checkbox, so progress has ` +
+                'nothing to flag as incomplete. Write each task as "- [ ] 1.1 Description".');
+        }
+    }
+    return undefined;
+}

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

@@ -1,8 +1,8 @@
-import { type ChangeStatus } from '../../vendor/openspec/engine/index.js';
+import { type ChangeStatus, type TaskProgress } from '../../vendor/openspec/engine/index.js';
 export interface StatusOptions {
     change?: string;
     schema?: string;
     json?: boolean;
 }
 export declare function statusHandler(projectRoot: string, options: StatusOptions): Promise<number>;
-export declare function printStatusText(status: ChangeStatus): void;
+export declare function printStatusText(status: ChangeStatus, taskProgress: TaskProgress): void;

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

@@ -5,8 +5,11 @@
 // (artifacts[].status, artifacts[].requires, applyRequires, isPlanningComplete /
 // isComplete). The store-only `root` field is omitted; `planningHome` is the
 // store-free stub from shared.ts (V4-P4, #1703).
-import { loadChangeContext, formatChangeStatus, getTaskProgressForChange, } from '../../vendor/openspec/engine/index.js';
-import { changesDirFor, getAvailableChanges, planningHomeStub, printJson, validateChangeExists, validateSchemaExists, } from './shared.js';
+import { loadChangeContext, formatChangeStatus, getTaskProgressForChange, formatTaskStatus, resolveNextStep, } from '../../vendor/openspec/engine/index.js';
+import { changesDirFor, findMissingTaskCheckboxWarning, getAvailableChanges, planningHomeStub, printJson, validateChangeExists, validateSchemaExists, } from './shared.js';
+import { collectSpecsIncompleteWarnings } from './instructions.js';
+import { readUnknownMetadataKeys } from './validate.js';
+import { tasksWithoutCheckboxWarning, unknownMetadataKeysWarning } from './warnings.js';
 export async function statusHandler(projectRoot, options) {
     if (!options.change) {
         const available = getAvailableChanges(projectRoot);
@@ -31,17 +34,31 @@ export async function statusHandler(projectRoot, options) {
     // checked, so the tasks artifact is complete for a reader's purposes exactly
     // when `open` reaches zero.
     const taskProgress = await getTaskProgressForChange(changesDirFor(projectRoot), changeName, projectRoot);
+    // Reports a tracked tasks file that lists work with no checkbox at all (#1774).
+    const checkboxWarning = findMissingTaskCheckboxWarning(context.changeDir, projectRoot);
+    const unknownKeys = readUnknownMetadataKeys(context.changeDir, projectRoot);
+    const warnings = [
+        ...(checkboxWarning ? [tasksWithoutCheckboxWarning(checkboxWarning)] : []),
+        ...(unknownKeys.length > 0 ? [unknownMetadataKeysWarning(unknownKeys)] : []),
+        ...collectSpecsIncompleteWarnings(context.graph.getAllArtifacts(), context.changeDir, context.skippedArtifacts),
+    ];
     if (options.json) {
         printJson({
             ...status,
             done: taskProgress.done,
             open: taskProgress.open,
             dispositioned: taskProgress.dispositioned,
+            ...(warnings.length > 0 ? { warnings } : {}),
             planningHome: planningHomeStub(projectRoot),
         });
         return 0;
     }
-    printStatusText(status);
+    printStatusText(status, taskProgress);
+    if (warnings.length > 0) {
+        console.log();
+        for (const warning of warnings)
+            console.log(`Warning: ${warning.message}`);
+    }
     return 0;
 }
 function indicator(status) {
@@ -56,7 +73,7 @@ function indicator(status) {
             return '[-]';
     }
 }
-export function printStatusText(status) {
+export function printStatusText(status, taskProgress) {
     const doneCount = status.artifacts.filter((a) => a.status === 'done').length;
     const skippedCount = status.artifacts.filter((a) => a.status === 'skipped').length;
     const total = status.artifacts.length - skippedCount;
@@ -67,6 +84,7 @@ export function printStatusText(status) {
     }
     const skippedSuffix = skippedCount > 0 ? ` (${skippedCount} skipped)` : '';
     console.log(`Progress: ${doneCount}/${total} artifacts complete${skippedSuffix}`);
+    console.log(`Tasks: ${formatTaskStatus(taskProgress)}`);
     console.log();
     for (const artifact of status.artifacts) {
         let line = `${indicator(artifact.status)} ${artifact.id}`;
@@ -78,8 +96,19 @@ export function printStatusText(status) {
         }
         console.log(line);
     }
-    if (status.isPlanningComplete) {
+    // Same inputs as the JSON `nextSteps` sentence, so both surfaces name the same command.
+    const nextStep = resolveNextStep({
+        changeName: status.changeName,
+        artifactStatuses: status.artifacts,
+        allArtifactsComplete: status.isPlanningComplete,
+    });
+    if (status.isPlanningComplete || nextStep) {
         console.log();
+    }
+    if (status.isPlanningComplete) {
         console.log('All planning artifacts complete!');
     }
+    if (nextStep) {
+        console.log(`Next: ${nextStep.command}`);
+    }
 }

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

@@ -1,3 +1,12 @@
+import { type TaskDisposition } from '../../vendor/openspec/validation/task-lines.js';
+/** Why a disposition leaves its unchecked task open; null when it resolves it. */
+export declare function dispositionReason(projectRoot: string, disposition: TaskDisposition): string | null;
+/** The keys the change-metadata schema declares; a test keeps this equal to its zod shape. */
+export declare const KNOWN_METADATA_KEYS: readonly string[];
+/** Keys outside the schema and the `x-` namespace, stripped of control characters for printing. */
+export declare function unknownMetadataKeys(metadata: Record<string, unknown>): string[];
+/** Unreadable metadata yields none: validate reports that file as its own ERROR. */
+export declare function readUnknownMetadataKeys(changeDir: string, projectRoot: string): string[];
 export interface ValidateOptions {
     specs?: boolean;
     strict?: boolean;

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

@@ -23,15 +23,24 @@ import { discoverSpecFiles } from '../../vendor/openspec/validation/spec-discove
 import { parseAnnotatedTaskLines } from '../../vendor/openspec/validation/task-lines.js';
 import { readChangeMetadata } from '../../vendor/openspec/engine/change-metadata.js';
 import { changesDirFor, getAvailableChanges, printJson, resolveChangeId, taskLabel } from './shared.js';
+import { unknownMetadataKeysWarning } from './warnings.js';
 const METADATA_FILENAME = '.openspec.yaml';
 const TASKS_FILENAME = 'tasks.md';
 const DISPOSITION_KINDS = new Set(['superseded', 'moved', 'external']);
-/**
- * Extra issues from a change's `tasks.md` disposition lines: an ERROR for a
- * disposition under a checked task, a kind outside the three documented ones,
- * a `superseded`/`moved` id that resolves to neither an in-flight nor an
- * archived change, and an `external` line without a reference.
- */
+/** Why a disposition leaves its unchecked task open; null when it resolves it. */
+export function dispositionReason(projectRoot, disposition) {
+    const { kind, target } = disposition;
+    if (!DISPOSITION_KINDS.has(kind)) {
+        return `disposition kind '${kind}' is none of superseded, moved, external`;
+    }
+    if (kind === 'external') {
+        return target.trim() === '' ? 'an external disposition needs a reference' : null;
+    }
+    return resolveChangeId(projectRoot, target) === null
+        ? `${kind} disposition names unresolved change '${target}'`
+        : null;
+}
+/** ERRORs for a disposition under a checked task or one `dispositionReason` rejects. */
 function dispositionIssues(projectRoot, changeDir) {
     const tasksPath = path.join(changeDir, TASKS_FILENAME);
     if (!fs.existsSync(tasksPath))
@@ -42,45 +51,43 @@ function dispositionIssues(projectRoot, changeDir) {
         if (!task.disposition)
             continue;
         const label = taskLabel(task);
-        if (task.done) {
-            issues.push({
-                level: 'ERROR',
-                path: TASKS_FILENAME,
-                line: task.line,
-                message: `task ${label}: a disposition belongs to an unchecked task`,
-            });
-            continue;
-        }
-        const { kind, target } = task.disposition;
-        if (!DISPOSITION_KINDS.has(kind)) {
-            issues.push({
-                level: 'ERROR',
-                path: TASKS_FILENAME,
-                line: task.line,
-                message: `task ${label}: disposition kind '${kind}' is none of superseded, moved, external`,
-            });
-        }
-        else if (kind === 'external') {
-            if (target.trim() === '') {
-                issues.push({
-                    level: 'ERROR',
-                    path: TASKS_FILENAME,
-                    line: task.line,
-                    message: `task ${label}: an external disposition needs a reference`,
-                });
-            }
-        }
-        else if (resolveChangeId(projectRoot, target) === null) {
-            issues.push({
-                level: 'ERROR',
-                path: TASKS_FILENAME,
-                line: task.line,
-                message: `task ${label}: ${kind} disposition names unresolved change '${target}'`,
-            });
+        const reason = task.done
+            ? 'a disposition belongs to an unchecked task'
+            : dispositionReason(projectRoot, task.disposition);
+        if (reason) {
+            issues.push({ level: 'ERROR', path: TASKS_FILENAME, line: task.line, message: `task ${label}: ${reason}` });
         }
     }
     return issues;
 }
+/** The keys the change-metadata schema declares; a test keeps this equal to its zod shape. */
+export const KNOWN_METADATA_KEYS = ['schema', 'created', 'skip_specs', 'depends_on', 'supersedes'];
+const EXTENSION_KEY_PREFIX = 'x-';
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
+/** Keys outside the schema and the `x-` namespace, stripped of control characters for printing. */
+export function unknownMetadataKeys(metadata) {
+    return Object.keys(metadata)
+        .filter((key) => !KNOWN_METADATA_KEYS.includes(key) && !key.startsWith(EXTENSION_KEY_PREFIX))
+        .map((key) => key.replace(CONTROL_CHARS, ''));
+}
+/** Unreadable metadata yields none: validate reports that file as its own ERROR. */
+export function readUnknownMetadataKeys(changeDir, projectRoot) {
+    try {
+        const metadata = readChangeMetadata(changeDir, projectRoot);
+        return metadata ? unknownMetadataKeys(metadata) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Same level rule as the in-flight dependency notice, so a typo never trips --strict alone. */
+function metadataKeyIssues(projectRoot, changeDir, strict) {
+    const keys = readUnknownMetadataKeys(changeDir, projectRoot);
+    if (keys.length === 0)
+        return [];
+    const level = strict ? 'INFO' : 'WARNING';
+    return [{ level, path: METADATA_FILENAME, message: unknownMetadataKeysWarning(keys).message }];
+}
 /**
  * Extra issues from a change's `depends_on` / `supersedes` metadata: an ERROR
  * for metadata that cannot be read, an ERROR for every id that resolves to
@@ -144,6 +151,7 @@ async function validateChangeItem(validator, projectRoot, id, strict) {
     const issues = [
         ...report.issues,
         ...dependencyIssues(projectRoot, changeDir, strict),
+        ...metadataKeyIssues(projectRoot, changeDir, strict),
         ...dispositionIssues(projectRoot, changeDir),
     ];
     const errors = issues.filter((i) => i.level === 'ERROR').length;

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

@@ -0,0 +1,21 @@
+import { type NestedChangeFinding } from './nested-change.js';
+export type ShimWarning = {
+    code: string;
+    message: string;
+} & Record<string, unknown>;
+export declare function tasksWithoutCheckboxWarning(message: string): ShimWarning;
+export declare function nestedChangeWarning(finding: NestedChangeFinding): ShimWarning;
+/** One warning covers every unknown id, so the text path prints a single line. */
+export declare function unknownArtifactIdWarning(ids: string[]): ShimWarning;
+/** `keys` arrive already stripped of control characters, since they come from an untrusted file. */
+export declare function unknownMetadataKeysWarning(keys: string[]): ShimWarning;
+/** `path` and `expected` are relative to the change directory. */
+export declare function unreadDeltaFileWarning(changeName: string, file: {
+    path: string;
+    expected: string;
+}): ShimWarning;
+/** `spec` is the capability path, so a reader with several deltas knows which file holds the text. */
+export declare function unappliedDeltaContentWarning(spec: string, message: string): ShimWarning;
+/** `capabilities` are the proposal's listed names, flattened to one line each, with no `specs/<name>/spec.md`. */
+export declare function specsIncompleteWarning(capabilities: string[]): ShimWarning;
+export declare function missingDeltaSpecsWarning(changeName: string, specTarget: string, metadataPath: string): ShimWarning;

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

@@ -0,0 +1,66 @@
+// The one element shape of every shim `--json` `warnings` array. `code` is a
+// stable identifier a reader switches on; `message` equals the text the text
+// output prints after its line prefix (`Warning: `, `- `), so the two surfaces
+// never drift apart.
+import { describeNestedChange } from './nested-change.js';
+export function tasksWithoutCheckboxWarning(message) {
+    return { code: 'tasks_without_checkbox', message };
+}
+export function nestedChangeWarning(finding) {
+    return {
+        code: 'nested_change_directory',
+        name: finding.name,
+        nested: finding.nested,
+        message: describeNestedChange(finding),
+    };
+}
+/** One warning covers every unknown id, so the text path prints a single line. */
+export function unknownArtifactIdWarning(ids) {
+    return {
+        code: 'unknown_artifact_id',
+        ids,
+        message: `Schema declares a dependency on an artifact id not defined in this schema: ${ids.join(', ')}.`,
+    };
+}
+/** `keys` arrive already stripped of control characters, since they come from an untrusted file. */
+export function unknownMetadataKeysWarning(keys) {
+    return {
+        code: 'unknown_metadata_keys',
+        keys,
+        message: `.openspec.yaml has unknown metadata key(s), ignored: ${keys.join(', ')}. ` +
+            'A misspelled key drops its setting; extension keys start with x-.',
+    };
+}
+/** `path` and `expected` are relative to the change directory. */
+export function unreadDeltaFileWarning(changeName, file) {
+    const filePath = `specs/${file.path}`;
+    const expected = `specs/${file.expected}`;
+    return {
+        code: 'unread_delta_file',
+        path: filePath,
+        expected,
+        message: `${filePath} is not a capability's spec.md, so \`openspec validate ${changeName}\` rejects it and archive never merges it. ` +
+            `Move its requirements into ${expected}.`,
+    };
+}
+/** `spec` is the capability path, so a reader with several deltas knows which file holds the text. */
+export function unappliedDeltaContentWarning(spec, message) {
+    return { code: 'unapplied_delta_content', spec, message };
+}
+/** `capabilities` are the proposal's listed names, flattened to one line each, with no `specs/<name>/spec.md`. */
+export function specsIncompleteWarning(capabilities) {
+    return {
+        code: 'specs_incomplete',
+        capabilities,
+        message: `The proposal lists capabilities with no delta spec yet: ${capabilities.join(', ')}. ` +
+            'Write specs/<capability>/spec.md for each before implementing, or drop it from the proposal.',
+    };
+}
+export function missingDeltaSpecsWarning(changeName, specTarget, metadataPath) {
+    return {
+        code: 'missing_delta_specs',
+        message: `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.`,
+    };
+}

package/node_modules/@freeharness/sdd/dist/vendor/openspec/apply/line-endings.d.ts

@@ -0,0 +1,4 @@
+export type LineEnding = '\n' | '\r\n';
+export declare function detectLineEnding(content: string): LineEnding | undefined;
+export declare function applyLineEnding(content: string, ending: LineEnding): string;
+export declare function matchLineEnding(content: string, original: string): string;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/apply/line-endings.js

@@ -0,0 +1,17 @@
+// Line-ending helpers: parsers normalize CRLF to LF on read; these restore a
+// file's own convention on write so an in-place edit does not rewrite every line.
+export function detectLineEnding(content) {
+    const crlf = content.match(/\r\n/g)?.length ?? 0;
+    const lf = content.match(/(?<!\r)\n/g)?.length ?? 0;
+    if (crlf === 0 && lf === 0)
+        return undefined;
+    return crlf >= lf ? '\r\n' : '\n';
+}
+export function applyLineEnding(content, ending) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    return ending === '\n' ? normalized : normalized.replace(/\n/g, '\r\n');
+}
+export function matchLineEnding(content, original) {
+    const ending = detectLineEnding(original);
+    return ending === undefined ? content : applyLineEnding(content, ending);
+}