freeharness 0.4.1

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

@@ -0,0 +1,229 @@
+// `openspec validate [<item>] [--specs] [--strict] [--json]` over the vendored
+// change-validation slice.
+//
+// Reconstructed from src/commands/validate.ts, minus store/root-selection and
+// the interactive selector. Uses the vendored Validator directly so the JSON
+// shape matches upstream: { items: [{ id, type, valid, issues, durationMs }],
+// summary: { totals, byType }, version }. Type is auto-detected (a change dir
+// under openspec/changes wins; else a spec under openspec/specs). `--specs`
+// (or a bare `validate`) runs the matching bulk set.
+//
+// Metadata depends_on/supersedes: the vendored Validator does not read
+// .openspec.yaml, so a change item's issues are extended here with an ERROR for
+// every unresolved id in either list, and a notice for a depends_on change that
+// is in flight with open tasks. That notice is WARNING under the default
+// (non-strict) verdict, where WARNING never affects validity; under --strict,
+// where the vendored Validator's own strict semantics fail a change on any
+// WARNING, it downgrades to INFO so a normal in-flight dependency never trips
+// --strict on its own (an unresolved id stays ERROR either way).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Validator } from '../../vendor/openspec/validation/validator.js';
+import { discoverSpecFiles } from '../../vendor/openspec/validation/spec-discovery.js';
+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';
+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.
+ */
+function dispositionIssues(projectRoot, changeDir) {
+    const tasksPath = path.join(changeDir, TASKS_FILENAME);
+    if (!fs.existsSync(tasksPath))
+        return [];
+    const tasks = parseAnnotatedTaskLines(fs.readFileSync(tasksPath, 'utf-8'));
+    const issues = [];
+    for (const task of tasks) {
+        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}'`,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * 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
+ * neither an in-flight nor an archived change, and a notice for a `depends_on`
+ * id that is in flight with open tasks.
+ */
+function dependencyIssues(projectRoot, changeDir, strict) {
+    let metadata;
+    try {
+        metadata = readChangeMetadata(changeDir, projectRoot);
+    }
+    catch (error) {
+        // Metadata that cannot be read leaves depends_on and supersedes unresolved, so the file
+        // itself is the finding: reporting nothing would pass a change whose dependency gate was
+        // never run.
+        const reason = error instanceof Error ? error.message : String(error);
+        return [{ level: 'ERROR', path: METADATA_FILENAME, message: `unreadable: ${reason}` }];
+    }
+    if (!metadata)
+        return [];
+    const issues = [];
+    for (const id of metadata.depends_on ?? []) {
+        const resolution = resolveChangeId(projectRoot, id);
+        if (resolution === null) {
+            issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: `depends_on names unresolved change '${id}'` });
+            continue;
+        }
+        if (resolution === 'in-flight') {
+            const tasksPath = path.join(changesDirFor(projectRoot), id, 'tasks.md');
+            // A dispositioned task is resolved, never open, so it never inflates
+            // this notice (it is not this check's job to also validate the
+            // disposition; an invalid one is still reported on the dependency's
+            // own `validate --strict` run).
+            const open = fs.existsSync(tasksPath)
+                ? parseAnnotatedTaskLines(fs.readFileSync(tasksPath, 'utf-8')).filter((t) => !t.done && !t.disposition)
+                : [];
+            if (open.length > 0) {
+                const level = strict ? 'INFO' : 'WARNING';
+                issues.push({
+                    level,
+                    path: METADATA_FILENAME,
+                    message: `depends_on '${id}' is in flight with ${open.length} open task(s)`,
+                });
+            }
+        }
+    }
+    for (const id of metadata.supersedes ?? []) {
+        if (resolveChangeId(projectRoot, id) === null) {
+            issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: `supersedes names unresolved change '${id}'` });
+        }
+    }
+    return issues;
+}
+async function validateChangeItem(validator, projectRoot, id, strict) {
+    const start = Date.now();
+    const changeDir = path.join(changesDirFor(projectRoot), id);
+    const report = await validator.validateChangeDeltaSpecs(changeDir, {
+        mainSpecsDir: path.join(projectRoot, 'openspec', 'specs'),
+        projectRoot,
+    });
+    const issues = [
+        ...report.issues,
+        ...dependencyIssues(projectRoot, changeDir, strict),
+        ...dispositionIssues(projectRoot, changeDir),
+    ];
+    const errors = issues.filter((i) => i.level === 'ERROR').length;
+    const warnings = issues.filter((i) => i.level === 'WARNING').length;
+    const valid = strict ? errors === 0 && warnings === 0 : errors === 0;
+    return { id, type: 'change', valid, issues, durationMs: Date.now() - start };
+}
+async function validateSpecItem(validator, projectRoot, id, specFile) {
+    const start = Date.now();
+    const file = specFile ?? path.join(projectRoot, 'openspec', 'specs', id, 'spec.md');
+    const report = await validator.validateSpec(file);
+    return { id, type: 'spec', valid: report.valid, issues: report.issues, durationMs: Date.now() - start };
+}
+export async function validateHandler(projectRoot, item, options) {
+    const validator = new Validator(!!options.strict);
+    const items = [];
+    const changeExists = (id) => {
+        const p = path.join(changesDirFor(projectRoot), id);
+        return fs.existsSync(p) && fs.statSync(p).isDirectory();
+    };
+    const specExists = (id) => fs.existsSync(path.join(projectRoot, 'openspec', 'specs', id, 'spec.md'));
+    if (item) {
+        if (changeExists(item)) {
+            items.push(await validateChangeItem(validator, projectRoot, item, !!options.strict));
+        }
+        else if (specExists(item)) {
+            items.push(await validateSpecItem(validator, projectRoot, item));
+        }
+        else {
+            throw new Error(`'${item}' is neither a known change nor a known spec.`);
+        }
+    }
+    else if (options.specs) {
+        const discovered = await discoverSpecFiles(path.join(projectRoot, 'openspec', 'specs'));
+        for (const { id, specFile } of discovered) {
+            items.push(await validateSpecItem(validator, projectRoot, id, specFile));
+        }
+    }
+    else {
+        // Bare `validate`: run every active change.
+        for (const id of getAvailableChanges(projectRoot)) {
+            items.push(await validateChangeItem(validator, projectRoot, id, !!options.strict));
+        }
+    }
+    const passed = items.filter((i) => i.valid).length;
+    const failed = items.length - passed;
+    const byType = {};
+    for (const i of items) {
+        const bucket = (byType[i.type] ??= { items: 0, passed: 0, failed: 0 });
+        bucket.items++;
+        if (i.valid)
+            bucket.passed++;
+        else
+            bucket.failed++;
+    }
+    const allValid = failed === 0;
+    if (options.json) {
+        printJson({
+            items,
+            summary: { totals: { items: items.length, passed, failed }, byType },
+            version: '1.0',
+        });
+        return allValid ? 0 : 1;
+    }
+    if (items.length === 0) {
+        console.log('Nothing to validate.');
+        return 0;
+    }
+    for (const i of items) {
+        const label = i.type === 'change' ? 'Change' : 'Specification';
+        if (i.valid) {
+            console.log(`${label} '${i.id}' is valid`);
+        }
+        else {
+            console.error(`${label} '${i.id}' has issues:`);
+            for (const issue of i.issues) {
+                const loc = issue.line ? `${issue.path}:${issue.line}` : issue.path;
+                console.error(`  [${issue.level}] ${loc}: ${issue.message}`);
+            }
+        }
+    }
+    return allValid ? 0 : 1;
+}

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

@@ -0,0 +1,40 @@
+export interface ValidateChangeOptions {
+    /**
+     * Schema name to resolve+validate before checking the change. Defaults to
+     * `spec-driven`. Set to an empty string / null to skip schema resolution.
+     */
+    schemaName?: string | null;
+    /**
+     * A directory that directly contains `<schemaName>/schema.yaml`, forwarded to
+     * the engine resolver so a schema can be validated with no global install and
+     * no XDG data dir. Mirrors the CLI's optional [userSchemasDir] argument.
+     */
+    userSchemasDir?: string;
+    /**
+     * Strict mode: warnings fail validation in addition to errors (matches
+     * `openspec validate --strict`).
+     */
+    strict?: boolean;
+}
+export interface ValidateChangeResult {
+    valid: boolean;
+    /** One human-readable line per issue: `[LEVEL] path[:line]: message`. */
+    issues: string[];
+}
+/**
+ * Validate an OpenSpec change directory using only the vendored slice.
+ *
+ * The verdict is the authoritative one `openspec validate <change>` uses: the
+ * delta-spec pass (`validateChangeDeltaSpecs`) plus schema resolution. In
+ * non-strict mode a change is valid when that pass reports no ERROR; in strict
+ * mode, no ERROR and no WARNING. A schema-resolution failure fails the change,
+ * since a change cannot be trusted against an unresolvable schema.
+ *
+ * The proposal document is additionally parsed and validated (Why / What
+ * Changes prose + the top-level ChangeSchema), but its findings are ADVISORY
+ * and never flip the verdict — mirroring upstream, where the proposal-level
+ * pass is archive's non-blocking warning source, not a gate. (This is what
+ * keeps a well-formed change with more than ten requirement-deltas from being
+ * failed by the advisory "Consider splitting" ChangeSchema rule.)
+ */
+export declare function validateChange(changeDir: string, opts?: ValidateChangeOptions): Promise<ValidateChangeResult>;

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

@@ -0,0 +1,114 @@
+// Store-free change validation entry point built on the vendored OpenSpec
+// change-validation slice (parsers + schemas + Validator).
+//
+// Runs with NO global `openspec` on PATH. Given a change directory
+// (`openspec/changes/<id>`), it optionally resolves+validates the governing
+// schema, then parses and validates the change artifacts:
+//   - specs/**/*.md   delta specs (ADDED/MODIFIED/REMOVED/RENAMED)
+//   - proposal.md     Why / What Changes prose + the top-level ChangeSchema
+//   - tasks.md        ambiguous task-numbering check
+// and returns a machine-readable result.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Validator } from '../vendor/openspec/validation/validator.js';
+import { validateSchema } from './validate.js';
+const DEFAULT_SCHEMA_NAME = 'spec-driven';
+/** Render one validation issue as a stable, greppable single line. */
+function formatIssue(issue, advisory = false) {
+    const location = issue.line ? `${issue.path}:${issue.line}` : issue.path;
+    const prefix = advisory ? '[advisory] ' : '';
+    return `${prefix}[${issue.level}] ${location}: ${issue.message}`;
+}
+/**
+ * Validate an OpenSpec change directory using only the vendored slice.
+ *
+ * The verdict is the authoritative one `openspec validate <change>` uses: the
+ * delta-spec pass (`validateChangeDeltaSpecs`) plus schema resolution. In
+ * non-strict mode a change is valid when that pass reports no ERROR; in strict
+ * mode, no ERROR and no WARNING. A schema-resolution failure fails the change,
+ * since a change cannot be trusted against an unresolvable schema.
+ *
+ * The proposal document is additionally parsed and validated (Why / What
+ * Changes prose + the top-level ChangeSchema), but its findings are ADVISORY
+ * and never flip the verdict — mirroring upstream, where the proposal-level
+ * pass is archive's non-blocking warning source, not a gate. (This is what
+ * keeps a well-formed change with more than ten requirement-deltas from being
+ * failed by the advisory "Consider splitting" ChangeSchema rule.)
+ */
+export async function validateChange(changeDir, opts = {}) {
+    const strict = opts.strict ?? false;
+    const lines = [];
+    let schemaOk = true;
+    // 1. Resolve + validate the governing schema (unless explicitly disabled).
+    const schemaName = opts.schemaName === undefined ? DEFAULT_SCHEMA_NAME : opts.schemaName;
+    if (schemaName) {
+        const schemaResult = await validateSchema(schemaName, {
+            ...(opts.userSchemasDir ? { userSchemasDir: opts.userSchemasDir } : {}),
+        });
+        if (!schemaResult.valid) {
+            schemaOk = false;
+            lines.push(formatIssue({
+                level: 'ERROR',
+                path: 'schema',
+                message: `Schema '${schemaName}' failed to resolve/validate: ${schemaResult.message ?? 'unknown error'}`,
+            }));
+        }
+    }
+    // Derive the sibling main specs dir and project root from the change layout
+    // `<root>/openspec/changes/<id>`, so the scenario-loss and task-numbering
+    // checks run. Absent siblings degrade gracefully inside the Validator.
+    const resolvedChangeDir = path.resolve(changeDir);
+    const mainSpecsDir = path.resolve(resolvedChangeDir, '..', '..', 'specs');
+    const projectRoot = path.resolve(resolvedChangeDir, '..', '..', '..');
+    const validator = new Validator(strict);
+    // 2. Authoritative change validation: the delta specs.
+    const deltaReport = await validator.validateChangeDeltaSpecs(resolvedChangeDir, { mainSpecsDir, projectRoot });
+    lines.push(...deltaReport.issues.map((i) => formatIssue(i)));
+    // 3. Advisory: proposal document (Why / What Changes prose + ChangeSchema).
+    const proposalPath = path.join(resolvedChangeDir, 'proposal.md');
+    if (fs.existsSync(proposalPath)) {
+        const proposalReport = await validator.validateChange(proposalPath);
+        lines.push(...proposalReport.issues.map((i) => formatIssue(i, true)));
+    }
+    const valid = schemaOk && deltaReport.valid;
+    return { valid, issues: lines };
+}
+/**
+ * CLI: `node dist/src/validate-change.js <changeDir> [userSchemasDir]`
+ * Prints the verdict and every issue, exits 0 when valid and 1 otherwise.
+ */
+async function main() {
+    const [, , changeDir, userSchemasDir] = process.argv;
+    if (!changeDir) {
+        console.error('usage: node dist/src/validate-change.js <changeDir> [userSchemasDir]');
+        process.exit(1);
+        return;
+    }
+    const result = await validateChange(changeDir, {
+        ...(userSchemasDir ? { userSchemasDir } : {}),
+    });
+    for (const issue of result.issues) {
+        console.log(issue);
+    }
+    if (result.valid) {
+        console.log(`\nvalid (${result.issues.length} non-error issue(s))`);
+        process.exit(0);
+    }
+    else {
+        console.error(`\ninvalid: ${result.issues.length} issue(s) reported`);
+        process.exit(1);
+    }
+}
+// Run as a CLI only when executed directly (not when imported as a module).
+const invokedPath = process.argv[1];
+if (invokedPath) {
+    try {
+        if (fileURLToPath(import.meta.url) === fs.realpathSync(invokedPath)) {
+            void main();
+        }
+    }
+    catch {
+        // If the entry path can't be resolved, don't auto-run.
+    }
+}

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

@@ -0,0 +1,24 @@
+export interface ValidateSchemaOptions {
+    /**
+     * A directory that directly contains `<schemaName>/schema.yaml`. When set and
+     * the file exists, it is validated in preference to the default resolution
+     * order. This mirrors the CLI's optional [userSchemasDir] argument and lets
+     * callers validate a schema with no global install and no XDG data dir.
+     */
+    userSchemasDir?: string;
+    /**
+     * Optional project root; forwarded to the engine resolver so a project-local
+     * `<projectDir>/openspec/schemas/<name>/schema.yaml` takes precedence.
+     */
+    projectDir?: string;
+}
+export interface ValidateSchemaResult {
+    valid: boolean;
+    message?: string;
+}
+/**
+ * Validates a schema by resolving its directory, loading `schema.yaml`, and
+ * running the vendored `parseSchema` (structure + duplicate-id + requires-ref +
+ * cycle checks).
+ */
+export declare function validateSchema(schemaName: string, opts?: ValidateSchemaOptions): Promise<ValidateSchemaResult>;

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

@@ -0,0 +1,72 @@
+// Store-free schema validation entry point built on the vendored OpenSpec engine.
+//
+// Runs with NO global `openspec` on PATH: it resolves the schema directory and
+// parses/validates schema.yaml using only the vendored engine slice.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadSchema, SchemaValidationError } from '../vendor/openspec/engine/schema.js';
+import { resolveSchema, SchemaLoadError } from '../vendor/openspec/engine/resolver.js';
+/**
+ * Validates a schema by resolving its directory, loading `schema.yaml`, and
+ * running the vendored `parseSchema` (structure + duplicate-id + requires-ref +
+ * cycle checks).
+ */
+export async function validateSchema(schemaName, opts = {}) {
+    try {
+        // 1. Explicit user schemas dir override: <userSchemasDir>/<name>/schema.yaml.
+        if (opts.userSchemasDir) {
+            const schemaPath = path.join(opts.userSchemasDir, schemaName, 'schema.yaml');
+            if (fs.existsSync(schemaPath)) {
+                loadSchema(schemaPath); // throws SchemaValidationError on invalid content
+                return { valid: true };
+            }
+            // Fall through to the engine resolver when the override has no such schema.
+        }
+        // 2. Default resolution (project-local -> user data dir -> package built-in)
+        //    plus parse/validation, all via the vendored engine.
+        resolveSchema(schemaName, opts.projectDir);
+        return { valid: true };
+    }
+    catch (err) {
+        const message = err instanceof SchemaValidationError || err instanceof SchemaLoadError
+            ? err.message
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return { valid: false, message };
+    }
+}
+/**
+ * CLI: `node dist/validate.js <schemaName> [userSchemasDir]`
+ * Prints "valid" and exits 0 on success, or the error and exits 1 on failure.
+ */
+async function main() {
+    const [, , schemaName, userSchemasDir] = process.argv;
+    if (!schemaName) {
+        console.error('usage: node dist/validate.js <schemaName> [userSchemasDir]');
+        process.exit(1);
+        return;
+    }
+    const result = await validateSchema(schemaName, userSchemasDir ? { userSchemasDir } : {});
+    if (result.valid) {
+        console.log('valid');
+        process.exit(0);
+    }
+    else {
+        console.error(result.message ?? 'invalid schema');
+        process.exit(1);
+    }
+}
+// Run as a CLI only when executed directly (not when imported as a module).
+const invokedPath = process.argv[1];
+if (invokedPath) {
+    try {
+        if (fileURLToPath(import.meta.url) === fs.realpathSync(invokedPath)) {
+            void main();
+        }
+    }
+    catch {
+        // If the entry path can't be resolved, don't auto-run.
+    }
+}

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

@@ -0,0 +1,130 @@
+/**
+ * Spec Application Logic
+ *
+ * Extracted from ArchiveCommand to enable standalone spec application.
+ * Applies delta specs from a change to main specs without archiving.
+ */
+export interface SpecUpdate {
+    /** Capability id relative to the specs root, forward-slash separated (e.g. "web" or "platform/session-layout"). */
+    id: string;
+    /** Allowed root for the delta source. */
+    sourceRoot: string;
+    source: string;
+    /** Allowed root for the main-spec target. */
+    targetRoot: string;
+    target: string;
+    exists: boolean;
+}
+/**
+ * Find all delta spec files that need to be applied from a change.
+ */
+export declare function findSpecUpdates(changeDir: string, mainSpecsDir: string): Promise<SpecUpdate[]>;
+/**
+ * Build an updated spec by applying delta operations.
+ * Returns the rebuilt content and counts of operations.
+ */
+export declare function buildUpdatedSpec(update: SpecUpdate, changeName: string, options?: {
+    silent?: boolean;
+    /**
+     * FreeHarness addition (`openspec archive --force`): a MODIFIED or RENAMED
+     * whose header is not in the current spec is skipped with a warning instead
+     * of aborting the fold. Upstream behavior (throw) when unset.
+     */
+    skipUnresolved?: boolean;
+}): Promise<{
+    rebuilt: string;
+    counts: {
+        added: number;
+        modified: number;
+        removed: number;
+        renamed: number;
+    };
+    warnings: string[];
+    /**
+     * Every canonical `### Requirement:` block the delta could act on is gone.
+     * This is only a *candidate* signal for retirement (#1302): the validator, not
+     * this count, decides whether `rebuilt` is actually unwritable - it recognises
+     * requirement shapes this parser sweeps into the preamble, so a spec can be
+     * blockless here and still validate. See `isRetirableSpec` in archive.ts.
+     */
+    noRequirementBlocks: boolean;
+    /**
+     * Every non-blank line of the spec this merge cannot name.
+     *
+     * Retirement deletes the whole file, so the only safe question is whether the
+     * merge can account for all of it. `extractRequirementsSection` splits a spec
+     * into five slices, and auditing a subset is how this guard kept failing: for
+     * seven rounds it looked for requirement-SHAPED text and was beaten by a new
+     * disguise each time, and when it started asking where content landed it
+     * still read only the preamble and the tail - so content simply moved into a
+     * slice nobody checked, and authored prose sitting inside a removed block's
+     * raw was deleted while the report said only "Purpose" was lost.
+     *
+     * So this accounts for the whole file: the title, the `## Purpose` section,
+     * the `## Requirements` header, and, inside each requirement block, the parts
+     * that make up a requirement - its header, its statement, and its scenarios'
+     * bullets. Every other non-blank line is reported and refuses the retirement.
+     *
+     * Fails safe in every direction: a line this cannot classify counts as
+     * unaccounted, which refuses rather than deletes.
+     */
+    unaccountedContent: string[];
+}>;
+/**
+ * Retire a capability whose last requirement a delta removed: delete its main
+ * spec and prune any directories the deletion leaves empty. Returns false when
+ * there was nothing to delete.
+ *
+ * Gated by the caller on the change's `retire_capabilities` marker, so the one
+ * archive action that removes a file from `openspec/specs/` is always something
+ * the author asked for rather than something inferred from a delta's shape. The
+ * file is recoverable from git, which the report names; applying REMOVED already
+ * deletes requirement content from a main spec, so deleting the spec once
+ * nothing is left is the same operation carried to its end rather than a new
+ * kind of act.
+ *
+ * Only the generated `spec.md` is removed - a directory holding anything else (a
+ * nested capability, a hand-kept note) is left in place.
+ *
+ * The target must resolve inside the selected specs root. A capability-directory
+ * symlink must not turn a retirement marker into authorization to delete an
+ * unrelated external file. A symlinked `spec.md` itself is safe: unlink removes
+ * the link and leaves its target alone.
+ *
+ * Directory pruning IS bounded, by REAL paths rather than string prefixes:
+ * `path.resolve` collapses `..` but does not resolve symlinks, and `readdir` and
+ * `rmdir` both follow them, so a symlinked capability directory would otherwise
+ * let the walk delete directories outside the specs root entirely.
+ */
+export declare function retireSpec(update: SpecUpdate, mainSpecsDir: string, options?: {
+    silent?: boolean;
+    displayPath?: string;
+    beforeMutate?: () => Promise<void>;
+    verifyDisplaced?: (displacedPath: string) => Promise<void>;
+    deferDelete?: boolean;
+}): Promise<{
+    retired: boolean;
+    resolvedPath?: string;
+    displacedPath?: string;
+}>;
+export declare function finalizeRetiredSpec(target: string, displacedPath: string, mainSpecsDir: string): Promise<void>;
+/**
+ * Write an updated spec to disk.
+ */
+export declare function writeUpdatedSpec(update: SpecUpdate, rebuilt: string, counts: {
+    added: number;
+    modified: number;
+    removed: number;
+    renamed: number;
+}, options?: {
+    silent?: boolean;
+    displayPath?: string;
+    beforeMutate?: () => Promise<void>;
+}): Promise<void>;
+/**
+ * Build a skeleton spec for new capabilities. When the delta spec authored a
+ * `## Purpose`, carry it over instead of the TBD placeholder (#1413) - archive
+ * invents the Purpose for a brand-new main spec either way, and the author's
+ * own wording beats a placeholder they then have to hand-edit.
+ */
+export declare function buildSpecSkeleton(specFolderName: string, changeName: string, purpose?: string): string;