freeharness 0.4.1

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/parsers/spec-structure.js

@@ -0,0 +1,77 @@
+import { buildCodeFenceMask } from './code-fence.js';
+const REQUIREMENTS_SECTION_HEADER = /^##\s+Requirements\s*$/i;
+const TOP_LEVEL_SECTION_HEADER = /^##\s+/;
+const DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
+const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/i;
+export function findMainSpecStructureIssues(content) {
+    const normalized = content.replace(/\r\n?/g, '\n');
+    const stripped = stripFencedCodeBlocksPreservingLines(normalized);
+    const lines = stripped.split('\n');
+    const issues = [];
+    const requirementLines = new Map();
+    const requirementsHeaderIndex = lines.findIndex(line => REQUIREMENTS_SECTION_HEADER.test(line));
+    let requirementsEndIndex = lines.length;
+    if (requirementsHeaderIndex !== -1) {
+        for (let i = requirementsHeaderIndex + 1; i < lines.length; i++) {
+            if (TOP_LEVEL_SECTION_HEADER.test(lines[i])) {
+                requirementsEndIndex = i;
+                break;
+            }
+        }
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        if (DELTA_HEADER.test(line)) {
+            issues.push({
+                kind: 'delta-header',
+                line: i + 1,
+                header: trimmed,
+                message: `Main spec contains delta header "${trimmed}". ` +
+                    'Delta headers are only valid inside openspec/changes/<name>/specs/<capability-path>/spec.md ' +
+                    'and truncate the parsed ## Requirements section.',
+            });
+            continue;
+        }
+        const requirementMatch = line.match(REQUIREMENT_HEADER);
+        if (!requirementMatch) {
+            continue;
+        }
+        const insideRequirements = requirementsHeaderIndex !== -1 &&
+            i > requirementsHeaderIndex &&
+            i < requirementsEndIndex;
+        if (!insideRequirements) {
+            issues.push({
+                kind: 'requirement-outside-requirements',
+                line: i + 1,
+                header: trimmed,
+                message: `Requirement header "${trimmed}" appears outside the main ## Requirements section. ` +
+                    'Main specs only parse requirements inside that section, so this requirement is currently invisible to validate, list, and archive.',
+            });
+            continue;
+        }
+        const requirementName = requirementMatch[1].trim();
+        const previousLine = requirementLines.get(requirementName);
+        if (previousLine !== undefined) {
+            issues.push({
+                kind: 'duplicate-requirement',
+                line: i + 1,
+                header: trimmed,
+                message: `Requirement header "${trimmed}" duplicates the requirement declared on line ${previousLine}. ` +
+                    'Requirement names must be unique so spec updates cannot discard one block while updating another.',
+            });
+        }
+        else {
+            requirementLines.set(requirementName, i + 1);
+        }
+    }
+    return issues;
+}
+export function stripFencedCodeBlocksPreservingLines(content) {
+    const lines = content.split('\n');
+    const mask = buildCodeFenceMask(lines);
+    return lines.map((line, i) => (mask[i] ? '' : line)).join('\n');
+}

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/purpose-placeholder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/purpose-placeholder.js

@@ -0,0 +1,116 @@
+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;
+}

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/schemas/base.schema.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const ScenarioSchema: z.ZodObject<{
+    rawText: z.ZodString;
+}, z.core.$strip>;
+export declare const RequirementSchema: z.ZodObject<{
+    text: z.ZodString;
+    scenarios: z.ZodArray<z.ZodObject<{
+        rawText: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Scenario = z.infer<typeof ScenarioSchema>;
+export type Requirement = z.infer<typeof RequirementSchema>;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/schemas/base.schema.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { VALIDATION_MESSAGES } from '../constants.js';
+export const ScenarioSchema = z.object({
+    rawText: z.string().min(1, VALIDATION_MESSAGES.SCENARIO_EMPTY),
+});
+export const RequirementSchema = z.object({
+    // SHALL/MUST body-keyword enforcement lives in the imperative validator
+    // (Validator.applySpecRules), not here: the parser collapses the requirement
+    // header into `text`, so a Zod refine on `text` cannot tell "keyword in header
+    // only" from "keyword in body" and emits a misleading generic error. The
+    // validator recovers the header and emits the targeted hint for both the
+    // main-spec and change-delta paths (#1156).
+    text: z.string()
+        .min(1, VALIDATION_MESSAGES.REQUIREMENT_EMPTY),
+    scenarios: z.array(ScenarioSchema)
+        .min(1, VALIDATION_MESSAGES.REQUIREMENT_NO_SCENARIOS),
+});

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/schemas/change.schema.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+export declare const DeltaOperationType: z.ZodEnum<{
+    ADDED: "ADDED";
+    MODIFIED: "MODIFIED";
+    REMOVED: "REMOVED";
+    RENAMED: "RENAMED";
+}>;
+export declare const DeltaSchema: z.ZodObject<{
+    spec: z.ZodString;
+    operation: z.ZodEnum<{
+        ADDED: "ADDED";
+        MODIFIED: "MODIFIED";
+        REMOVED: "REMOVED";
+        RENAMED: "RENAMED";
+    }>;
+    description: z.ZodString;
+    requirement: z.ZodOptional<z.ZodObject<{
+        text: z.ZodString;
+        scenarios: z.ZodArray<z.ZodObject<{
+            rawText: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    requirements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        scenarios: z.ZodArray<z.ZodObject<{
+            rawText: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    rename: z.ZodOptional<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ChangeSchema: z.ZodObject<{
+    name: z.ZodString;
+    why: z.ZodString;
+    whatChanges: z.ZodString;
+    deltas: z.ZodArray<z.ZodObject<{
+        spec: z.ZodString;
+        operation: z.ZodEnum<{
+            ADDED: "ADDED";
+            MODIFIED: "MODIFIED";
+            REMOVED: "REMOVED";
+            RENAMED: "RENAMED";
+        }>;
+        description: z.ZodString;
+        requirement: z.ZodOptional<z.ZodObject<{
+            text: z.ZodString;
+            scenarios: z.ZodArray<z.ZodObject<{
+                rawText: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        requirements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            scenarios: z.ZodArray<z.ZodObject<{
+                rawText: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        rename: z.ZodOptional<z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        version: z.ZodDefault<z.ZodString>;
+        format: z.ZodLiteral<"openspec-change">;
+        sourcePath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DeltaOperation = z.infer<typeof DeltaOperationType>;
+export type Delta = z.infer<typeof DeltaSchema>;
+export type Change = z.infer<typeof ChangeSchema>;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/schemas/change.schema.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { RequirementSchema } from './base.schema.js';
+import { MIN_WHY_SECTION_LENGTH, MAX_WHY_SECTION_LENGTH, MAX_DELTAS_PER_CHANGE, VALIDATION_MESSAGES } from '../constants.js';
+export const DeltaOperationType = z.enum(['ADDED', 'MODIFIED', 'REMOVED', 'RENAMED']);
+export const DeltaSchema = z.object({
+    spec: z.string().min(1, VALIDATION_MESSAGES.DELTA_SPEC_EMPTY),
+    operation: DeltaOperationType,
+    description: z.string().min(1, VALIDATION_MESSAGES.DELTA_DESCRIPTION_EMPTY),
+    requirement: RequirementSchema.optional(),
+    requirements: z.array(RequirementSchema).optional(),
+    rename: z.object({
+        from: z.string(),
+        to: z.string(),
+    }).optional(),
+});
+export const ChangeSchema = z.object({
+    name: z.string().min(1, VALIDATION_MESSAGES.CHANGE_NAME_EMPTY),
+    why: z.string()
+        .min(MIN_WHY_SECTION_LENGTH, VALIDATION_MESSAGES.CHANGE_WHY_TOO_SHORT)
+        .max(MAX_WHY_SECTION_LENGTH, VALIDATION_MESSAGES.CHANGE_WHY_TOO_LONG),
+    whatChanges: z.string().min(1, VALIDATION_MESSAGES.CHANGE_WHAT_EMPTY),
+    deltas: z.array(DeltaSchema)
+        .min(1, VALIDATION_MESSAGES.CHANGE_NO_DELTAS)
+        .max(MAX_DELTAS_PER_CHANGE, VALIDATION_MESSAGES.CHANGE_TOO_MANY_DELTAS),
+    metadata: z.object({
+        version: z.string().default('1.0.0'),
+        format: z.literal('openspec-change'),
+        sourcePath: z.string().optional(),
+    }).optional(),
+});

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/schemas/index.d.ts

@@ -0,0 +1,3 @@
+export { ScenarioSchema, RequirementSchema, type Scenario, type Requirement, } from './base.schema.js';
+export { SpecSchema, type Spec, } from './spec.schema.js';
+export { DeltaOperationType, DeltaSchema, ChangeSchema, type DeltaOperation, type Delta, type Change, } from './change.schema.js';

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/schemas/index.js

@@ -0,0 +1,3 @@
+export { ScenarioSchema, RequirementSchema, } from './base.schema.js';
+export { SpecSchema, } from './spec.schema.js';
+export { DeltaOperationType, DeltaSchema, ChangeSchema, } from './change.schema.js';

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/schemas/spec.schema.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const SpecSchema: z.ZodObject<{
+    name: z.ZodString;
+    overview: z.ZodString;
+    requirements: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        scenarios: z.ZodArray<z.ZodObject<{
+            rawText: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        version: z.ZodDefault<z.ZodString>;
+        format: z.ZodLiteral<"openspec">;
+        sourcePath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Spec = z.infer<typeof SpecSchema>;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/schemas/spec.schema.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { RequirementSchema } from './base.schema.js';
+import { VALIDATION_MESSAGES } from '../constants.js';
+export const SpecSchema = z.object({
+    name: z.string().min(1, VALIDATION_MESSAGES.SPEC_NAME_EMPTY),
+    overview: z.string().min(1, VALIDATION_MESSAGES.SPEC_PURPOSE_EMPTY),
+    requirements: z.array(RequirementSchema)
+        .min(1, VALIDATION_MESSAGES.SPEC_NO_REQUIREMENTS),
+    metadata: z.object({
+        version: z.string().default('1.0.0'),
+        format: z.literal('openspec'),
+        sourcePath: z.string().optional(),
+    }).optional(),
+});

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/spec-discovery.d.ts

@@ -0,0 +1,39 @@
+export interface DiscoveredSpec {
+    /** Spec id relative to the specs root, forward-slash separated on every platform (e.g. "web" or "platform/session-layout"). */
+    id: string;
+    /** Path to the spec.md file (absolute if the specs root is absolute). */
+    specFile: string;
+}
+/**
+ * Recursively discover every `spec.md` under a specs root, so both the flat
+ * `specs/<id>/spec.md` layout and nested `specs/<area>/<id>/spec.md` layouts
+ * are found (#1353). A `spec.md` sitting directly in the root is ignored,
+ * matching the historical requirement that specs live in a capability folder.
+ * Dot-directories are skipped and symlinked directories are not followed.
+ * An in-capability symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the
+ * artifact graph's globs both count it as content, so dropping it here would
+ * silently lose the delta on archive. A link outside its capability is
+ * rejected and a dangling link is skipped. Results are sorted by id.
+ *
+ * A missing root (ENOENT) yields an empty list, but any other read failure
+ * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
+ * archive/apply merge path, silently dropping an unreadable capability would
+ * recreate the exact data-loss class #1353 is closing.
+ */
+export declare function discoverSpecFiles(specsRoot: string): Promise<DiscoveredSpec[]>;
+/**
+ * True when any regular non-dot file exists anywhere under the given
+ * directory. Used by validate/archive to detect content under a change's
+ * specs/ that contradicts a declared skip_specs marker - including files that
+ * discoverSpecFiles ignores (a root spec.md, stray non-spec.md notes), since
+ * anything there would be silently dropped or misread while the change claims
+ * to have nothing. Dot entries (.DS_Store, .gitkeep, dot-directories) are
+ * skipped to match discoverSpecFiles - they are invisible to every other
+ * code path, so they must not count as spec content. Symlinks DO count
+ * (without being followed): the artifact graph's globs follow them, so a
+ * symlinked spec would read as existing content while the change claims to
+ * have none - it contradicts the marker like any regular file. A missing
+ * directory returns false; other read failures are thrown for the caller to
+ * decide.
+ */
+export declare function hasAnyFileUnder(dirPath: string): Promise<boolean>;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/spec-discovery.js

@@ -0,0 +1,114 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { FileSystemUtils } from '../engine/file-system.js';
+function assertDiscoveredSpecPath(specsRoot, capabilityDir, specFile) {
+    try {
+        FileSystemUtils.assertPathWithin(specsRoot, specFile);
+    }
+    catch {
+        // Direct capability directories may intentionally be external monorepo
+        // links. In that case, confine the file to the capability itself.
+        FileSystemUtils.assertPathWithin(capabilityDir, specFile);
+    }
+}
+/**
+ * Recursively discover every `spec.md` under a specs root, so both the flat
+ * `specs/<id>/spec.md` layout and nested `specs/<area>/<id>/spec.md` layouts
+ * are found (#1353). A `spec.md` sitting directly in the root is ignored,
+ * matching the historical requirement that specs live in a capability folder.
+ * Dot-directories are skipped and symlinked directories are not followed.
+ * An in-capability symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the
+ * artifact graph's globs both count it as content, so dropping it here would
+ * silently lose the delta on archive. A link outside its capability is
+ * rejected and a dangling link is skipped. Results are sorted by id.
+ *
+ * A missing root (ENOENT) yields an empty list, but any other read failure
+ * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
+ * archive/apply merge path, silently dropping an unreadable capability would
+ * recreate the exact data-loss class #1353 is closing.
+ */
+export async function discoverSpecFiles(specsRoot) {
+    const results = [];
+    const walk = async (dir, segments) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (entry.isDirectory()) {
+                await walk(path.join(dir, entry.name), [...segments, entry.name]);
+            }
+            else if (entry.name === 'spec.md' && segments.length > 0) {
+                const specFile = path.join(dir, entry.name);
+                if (entry.isFile()) {
+                    assertDiscoveredSpecPath(specsRoot, dir, specFile);
+                    results.push({ id: segments.join('/'), specFile });
+                }
+                else if (entry.isSymbolicLink()) {
+                    try {
+                        if ((await fs.stat(specFile)).isFile()) {
+                            assertDiscoveredSpecPath(specsRoot, dir, specFile);
+                            results.push({ id: segments.join('/'), specFile });
+                        }
+                    }
+                    catch (err) {
+                        // A dangling link is not content; anything else fails loudly.
+                        if (err?.code !== 'ENOENT')
+                            throw err;
+                    }
+                }
+            }
+        }
+    };
+    await walk(specsRoot, []);
+    // Plain code-point comparison, not localeCompare: the latter follows the
+    // process's ICU locale, so ordering could vary by OS/CI. Code-point ordering
+    // guarantees the deterministic output the docstring promises.
+    return results.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+/**
+ * True when any regular non-dot file exists anywhere under the given
+ * directory. Used by validate/archive to detect content under a change's
+ * specs/ that contradicts a declared skip_specs marker - including files that
+ * discoverSpecFiles ignores (a root spec.md, stray non-spec.md notes), since
+ * anything there would be silently dropped or misread while the change claims
+ * to have nothing. Dot entries (.DS_Store, .gitkeep, dot-directories) are
+ * skipped to match discoverSpecFiles - they are invisible to every other
+ * code path, so they must not count as spec content. Symlinks DO count
+ * (without being followed): the artifact graph's globs follow them, so a
+ * symlinked spec would read as existing content while the change claims to
+ * have none - it contradicts the marker like any regular file. A missing
+ * directory returns false; other read failures are thrown for the caller to
+ * decide.
+ */
+export async function hasAnyFileUnder(dirPath) {
+    let entries;
+    try {
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return false;
+        }
+        throw err;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.')) {
+            continue;
+        }
+        if (entry.isFile() || entry.isSymbolicLink()) {
+            return true;
+        }
+        if (entry.isDirectory() && (await hasAnyFileUnder(path.join(dirPath, entry.name)))) {
+            return true;
+        }
+    }
+    return false;
+}

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/task-lines.d.ts

@@ -0,0 +1,45 @@
+export interface ParsedTask {
+    /** Checkbox state: `[x]`/`[X]` is done, anything else is not. */
+    done: boolean;
+    /** Task text after the checkbox, trimmed (may be empty). */
+    description: string;
+}
+/**
+ * Parses every task line in a tasks file, in document order. Every line matching
+ * the pattern counts, wherever it sits (inside a code fence, HTML comment, or an
+ * indented block), matching upstream.
+ */
+export declare function parseTaskLines(content: string): ParsedTask[];
+/** The annotation keys the tasks template documents. */
+export declare const TASK_ANNOTATION_KEYS: readonly ["Verify", "Interfaces", "Boundary", "Depends", "Disposition"];
+export type TaskAnnotationKey = (typeof TASK_ANNOTATION_KEYS)[number];
+/**
+ * A task resolved outside this change: `superseded`/`moved` name another
+ * change id, `external` carries free-form reference text. `kind` is the raw
+ * first token of the `Disposition:` value, so a value outside the three
+ * documented kinds still parses (a reader such as `validate --strict` reports
+ * it, rather than the parser silently dropping the line).
+ */
+export interface TaskDisposition {
+    kind: string;
+    target: string;
+}
+export interface AnnotatedTask extends ParsedTask {
+    /** 1-based line of the checkbox in the tasks file. */
+    line: number;
+    /** Annotation lines that followed the checkbox, keyed by their label. */
+    annotations: Partial<Record<TaskAnnotationKey, string>>;
+    /** Parsed `Disposition:` line, or null when the task carries none. */
+    disposition: TaskDisposition | null;
+}
+/**
+ * True when the line is one of the documented annotation lines. Such a line is
+ * never a task, whatever precedes it.
+ */
+export declare function isTaskAnnotationLine(line: string): boolean;
+/**
+ * Parses task lines and attaches the annotation lines that directly follow each
+ * task (blank lines and non-annotation prose end the run). The task count is
+ * exactly `parseTaskLines(content).length`.
+ */
+export declare function parseAnnotatedTaskLines(content: string): AnnotatedTask[];