freeharness 0.4.1

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

@@ -0,0 +1,483 @@
+// `openspec archive <id>` — folds a change's delta specs into openspec/specs/
+// and moves the change into openspec/changes/archive/.
+//
+// Non-interactive and store-free. Built on the vendored specs-apply slice
+// (vendor/openspec/apply/specs-apply.ts) and the vendored Validator. This is the
+// one command that writes the spec source of truth, so it (1) refuses to archive
+// an invalid change and (2) folds every delta before moving the change, never a
+// move-without-fold that would leave openspec/specs/ stale.
+//
+// V4-P4 additions:
+// - Archive blockers (#1710 findArchiveBlockers, reported INFO by the validator)
+//   and unchecked tasks are listed before anything is written; without `--yes`
+//   they refuse the archive (upstream prompts; this shim is non-interactive).
+// - Supersession: a `Supersedes: <change-id>` line in the change's design.md
+//   names an archived change this one replaces. Archive prints the link, writes
+//   the reverse link (`Superseded-by: <id>`) into the archived record, and
+//   refuses a MODIFIED requirement that carries a superseded requirement's text
+//   unchanged (an in-place edit of a published decision).
+// - Unresolved delta headers: a MODIFIED / REMOVED / RENAMED whose header is not
+//   in openspec/specs/<cap>/spec.md is listed with the blockers and refuses the
+//   archive unless `--force`, which folds the rest and skips those deltas
+//   (vendor/openspec/validation/delta-resolution.ts).
+// - Metadata `depends_on` / `supersedes`: an unarchived `depends_on` change is
+//   listed among the blockers (refusal, same as an unchecked task); `supersedes`
+//   cross-links archived changes the same way the design.md `Supersedes:` line
+//   does, as the union of both sources.
+import { promises as fs } from 'node:fs';
+import * as fssync from 'node:fs';
+import * as path from 'node:path';
+import { Validator } from '../../vendor/openspec/validation/validator.js';
+import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, } from '../../vendor/openspec/apply/specs-apply.js';
+import { parseDeltaSpec } from '../../vendor/openspec/validation/parsers/requirement-blocks.js';
+import { discoverSpecFiles } from '../../vendor/openspec/validation/spec-discovery.js';
+import { findUnresolvedDeltaHeaders, } from '../../vendor/openspec/validation/delta-resolution.js';
+import { parseAnnotatedTaskLines } from '../../vendor/openspec/validation/task-lines.js';
+import { readChangeMetadata } from '../../vendor/openspec/engine/change-metadata.js';
+import { changesDirFor, resolveChangeId, taskLabel, validateChangeExists } from './shared.js';
+import { readFollowUps } from './follow-up.js';
+const SUPERSEDES_LINE = /^\s*Supersedes:\s*(.+?)\s*$/gm;
+const SUPERSEDED_BY_PREFIX = 'Superseded-by:';
+/**
+ * Reads the `Supersedes: <change-id>[, <change-id>...]` lines of a design.md.
+ * Convention: one or more lines, each `Supersedes:` followed by archived change
+ * ids separated by commas. Absent lines -> empty list. Template placeholders
+ * live in HTML comments; a line left as `Supersedes: <!-- ... -->` names nothing.
+ */
+function parseDesignSupersedes(designText) {
+    const content = designText.replace(/<!--[\s\S]*?-->/g, '');
+    const ids = [];
+    for (const match of content.matchAll(SUPERSEDES_LINE)) {
+        for (const id of match[1].split(',')) {
+            const trimmed = id.trim().replace(/^`|`$/g, '');
+            if (trimmed && !ids.includes(trimmed))
+                ids.push(trimmed);
+        }
+    }
+    return ids;
+}
+/**
+ * Resolves the ids a change supersedes: the deduplicated union of design.md's
+ * `Supersedes:` lines and the metadata `supersedes` list, design.md first.
+ */
+export function readSupersedes(designText, metadata) {
+    const ids = parseDesignSupersedes(designText);
+    for (const id of metadata?.supersedes ?? []) {
+        if (!ids.includes(id))
+            ids.push(id);
+    }
+    return ids;
+}
+/** Collapses whitespace so two requirement blocks compare on their words. */
+function normalizeBlockText(raw) {
+    return raw.replace(/\s+/g, ' ').trim();
+}
+/** Every requirement block (any delta section) declared by a change's specs. */
+async function collectRequirementBlocks(changeDir) {
+    const specsDir = path.join(changeDir, 'specs');
+    const out = [];
+    for (const file of await safeDiscover(specsDir)) {
+        const content = await fs.readFile(file.specFile, 'utf-8');
+        const plan = parseDeltaSpec(content);
+        for (const block of [...plan.added, ...plan.modified])
+            out.push({ spec: file.id, block });
+    }
+    return out;
+}
+/**
+ * Resolves the change's `Supersedes:` lines and enforces the supersession
+ * rules: every id names an archived change, and no MODIFIED requirement of this
+ * change repeats a superseded requirement's text unchanged.
+ */
+export async function checkSupersession(changeName, changeDir, changesDir, metadata) {
+    const designPath = path.join(changeDir, 'design.md');
+    const designText = fssync.existsSync(designPath) ? fssync.readFileSync(designPath, 'utf-8') : '';
+    const ids = readSupersedes(designText, metadata);
+    if (ids.length === 0)
+        return [];
+    const links = [];
+    // Only MODIFIED blocks are in-place edits; ADDED blocks are new decisions.
+    const modifiedOnly = [];
+    for (const file of await safeDiscover(path.join(changeDir, 'specs'))) {
+        const plan = parseDeltaSpec(await fs.readFile(file.specFile, 'utf-8'));
+        for (const block of plan.modified)
+            modifiedOnly.push({ spec: file.id, block });
+    }
+    for (const id of ids) {
+        if (id === changeName) {
+            throw new Error(`Change '${changeName}' declares 'Supersedes: ${id}' naming itself. Fix: name the archived change it replaces.`);
+        }
+        const archived = path.join(changesDir, 'archive', id);
+        if (!fssync.existsSync(archived) || !fssync.statSync(archived).isDirectory()) {
+            throw new Error(`Change '${changeName}' declares 'Supersedes: ${id}' but openspec/changes/archive/${id} does not exist. ` +
+                `Fix: supersede only archived changes (check the id with 'ls openspec/changes/archive'), or archive '${id}' first.`);
+        }
+        const superseded = await collectRequirementBlocks(archived);
+        for (const { spec, block } of modifiedOnly) {
+            const same = superseded.find((s) => normalizeBlockText(s.block.raw) === normalizeBlockText(block.raw));
+            if (same) {
+                throw new Error(`Change '${changeName}' supersedes '${id}' but MODIFIED "${block.name}" (specs/${spec}) repeats the ` +
+                    `superseded requirement text unchanged: a published decision is never edited in place. ` +
+                    `Fix: state the new decision as ADDED (or RENAMED) with its own text and leave the superseded text in ` +
+                    `openspec/changes/archive/${id}; when only part of the decision changes, keep the original requirement ` +
+                    `active and cross-link it.`);
+            }
+        }
+        links.push({ change: id, path: archived });
+    }
+    return links;
+}
+async function safeDiscover(specsDir) {
+    try {
+        return await discoverSpecFiles(specsDir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/** Appends the reverse link to the archived record's design.md (idempotent). */
+async function writeSupersededBy(link, changeName) {
+    const designPath = path.join(link.path, 'design.md');
+    const line = `${SUPERSEDED_BY_PREFIX} ${changeName}`;
+    const existing = fssync.existsSync(designPath) ? await fs.readFile(designPath, 'utf-8') : '';
+    if (existing.split('\n').some((l) => l.trim() === line))
+        return;
+    const separator = existing.length === 0 ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+    await fs.writeFile(designPath, `${existing}${separator}${line}\n`, 'utf-8');
+}
+/**
+ * Lines that describe what archive would refuse or what is still open. The
+ * unresolved headers are listed here as well so one refusal names everything.
+ */
+export function listArchiveBlockers(changeDir, issues, unresolved = []) {
+    const blockers = [];
+    for (const issue of issues) {
+        if (issue.level === 'INFO' && /^Archive would refuse this delta/.test(issue.message)) {
+            blockers.push(`[INFO] ${issue.path}: ${issue.message}`);
+        }
+    }
+    for (const u of unresolved)
+        blockers.push(`[WARNING] ${u.entryPath}: ${u.message}`);
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    if (fssync.existsSync(tasksPath)) {
+        // A dispositioned task is resolved outside this change (see
+        // dispositionedTasks below), so it is never a blocker; only a plain
+        // unchecked task refuses the archive.
+        const open = parseAnnotatedTaskLines(fssync.readFileSync(tasksPath, 'utf-8')).filter((t) => !t.done && !t.disposition);
+        if (open.length > 0) {
+            blockers.push(`[INFO] tasks.md: ${open.length} unchecked task(s); first: ${open[0].description || '(no description)'}`);
+        }
+    }
+    return blockers;
+}
+const DISPOSITION_KINDS = new Set(['superseded', 'moved', 'external']);
+/**
+ * Why a task's disposition does not resolve it, or null when it does: a kind
+ * outside the three documented ones, an `external` line without a reference,
+ * or a `superseded`/`moved` target `resolveChangeId` cannot place in flight or
+ * archived. Re-checked here (not merely trusted from an earlier `validate`
+ * run) the same way `listDependencyBlockers` below re-checks `depends_on`.
+ */
+function dispositionBlockerReason(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;
+}
+/**
+ * The change's dispositioned tasks (unchecked, carrying a `Disposition:`
+ * line), for the archive result to print grouped by kind. `listArchiveBlockers`
+ * above already excludes these from the unchecked-task blocker; a task whose
+ * disposition does not resolve is still listed here for display, but also
+ * comes back as a blocker from `listDispositionBlockers`.
+ */
+function dispositionedTasks(changeDir) {
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    if (!fssync.existsSync(tasksPath))
+        return [];
+    const tasks = parseAnnotatedTaskLines(fssync.readFileSync(tasksPath, 'utf-8'));
+    const out = [];
+    for (const task of tasks) {
+        if (task.done || !task.disposition)
+            continue;
+        out.push({
+            kind: task.disposition.kind,
+            task: taskLabel(task),
+            target: task.disposition.target,
+        });
+    }
+    return out;
+}
+/**
+ * Lists every unchecked task whose disposition does not resolve it (an
+ * unknown kind, an unresolved `superseded`/`moved` target, or an empty
+ * `external` reference), naming the task and the reason. Such a task stays a
+ * blocker exactly like a plain unchecked task; a resolving disposition never
+ * appears here.
+ */
+function listDispositionBlockers(projectRoot, changeDir) {
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    if (!fssync.existsSync(tasksPath))
+        return [];
+    const tasks = parseAnnotatedTaskLines(fssync.readFileSync(tasksPath, 'utf-8'));
+    const blockers = [];
+    for (const task of tasks) {
+        if (task.done || !task.disposition)
+            continue;
+        const reason = dispositionBlockerReason(projectRoot, task.disposition);
+        if (reason) {
+            blockers.push(`[INFO] tasks.md: task ${taskLabel(task)} disposition does not resolve it (${reason})`);
+        }
+    }
+    return blockers;
+}
+/**
+ * Lists every `depends_on` change that is not archived, naming it and its
+ * current state (in flight, or unresolved). Has the same effect as an
+ * unchecked task: archiving without `--yes` is refused while any are open.
+ */
+function listDependencyBlockers(projectRoot, metadata) {
+    const blockers = [];
+    for (const id of metadata?.depends_on ?? []) {
+        const resolution = resolveChangeId(projectRoot, id);
+        if (resolution !== 'archived') {
+            blockers.push(`[INFO] depends_on: '${id}' is not archived (${resolution ?? 'unresolved'})`);
+        }
+    }
+    return blockers;
+}
+/**
+ * The validator's "Archive would refuse this delta" pass re-run the way a
+ * `--force` fold runs (unresolved headers skipped), so a waived header is not
+ * still listed as a refusal while a real conflict (an ADDED that already
+ * exists) still is.
+ */
+async function forcedFoldBlockers(changeDir, specsDir, changeName) {
+    const out = [];
+    let updates;
+    try {
+        updates = await findSpecUpdates(changeDir, specsDir);
+    }
+    catch (error) {
+        return [`[INFO] specs: Could not check archive merge conflicts: ${error instanceof Error ? error.message : String(error)}`];
+    }
+    for (const update of updates) {
+        try {
+            await buildUpdatedSpec(update, changeName, { silent: true, skipUnresolved: true });
+        }
+        catch (error) {
+            if (error?.code !== undefined)
+                continue;
+            out.push(`[INFO] ${update.id}/spec.md: Archive would refuse this delta: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return out;
+}
+/**
+ * Archive a change: validate it, fold its delta specs into openspec/specs/, then
+ * move openspec/changes/<name>/ to openspec/changes/archive/<name>/.
+ *
+ * Throws (with an actionable message) rather than partially archiving when the
+ * change is invalid, a fold fails, or the archive destination is already taken.
+ */
+export async function archiveChange(changeName, { projectRoot, yes, force }) {
+    // Resolve + guard the change name against the active changes directory.
+    const name = validateChangeExists(changeName, projectRoot);
+    const changesDir = changesDirFor(projectRoot);
+    const changeDir = path.join(changesDir, name);
+    const specsDir = path.join(projectRoot, 'openspec', 'specs');
+    // Metadata (.openspec.yaml) drives the depends_on blockers and the supersedes
+    // union below. Metadata that cannot be read degrades to "no dependency/supersedes
+    // data" rather than aborting the archive, but the lost gate is listed among the
+    // blockers: without that line the archive would run with its dependency check
+    // silently skipped.
+    let metadata;
+    let metadataBlockers = [];
+    try {
+        metadata = readChangeMetadata(changeDir, projectRoot);
+    }
+    catch (error) {
+        metadata = null;
+        const reason = error instanceof Error ? error.message : String(error);
+        metadataBlockers = [`[INFO] metadata unreadable: ${reason}; depends_on and supersedes not checked`];
+    }
+    // 1. Validate the change. This is the authoritative delta-spec pass — the same
+    //    verdict `openspec validate <change>` uses. Abort on any ERROR; an empty
+    //    change (nothing to validate) reports valid and proceeds.
+    const validator = new Validator(false);
+    const report = await validator.validateChangeDeltaSpecs(changeDir, {
+        mainSpecsDir: specsDir,
+        projectRoot,
+    });
+    if (!report.valid) {
+        const details = report.issues
+            .filter((i) => i.level === 'ERROR')
+            .map((i) => `  [${i.level}] ${i.line ? `${i.path}:${i.line}` : i.path}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Change '${name}' is not valid; refusing to archive:\n${details}`);
+    }
+    // 1b. Blockers: deltas archive would refuse (validator INFO, #1710),
+    //     unresolved delta headers (unless --force already waives them) and
+    //     unchecked tasks. Listed together; without --yes they refuse the archive
+    //     with nothing written (upstream asks; this shim cannot).
+    const unresolved = await findUnresolvedDeltaHeaders(changeDir, specsDir, changesDir);
+    const dependencyBlockers = listDependencyBlockers(projectRoot, metadata);
+    const dispositionBlockers = listDispositionBlockers(projectRoot, changeDir);
+    const blockers = force
+        ? [
+            ...(await forcedFoldBlockers(changeDir, specsDir, name)),
+            ...listArchiveBlockers(changeDir, report.issues.filter((i) => !/^Archive would refuse this delta/.test(i.message))),
+            ...metadataBlockers,
+            ...dependencyBlockers,
+            ...dispositionBlockers,
+        ]
+        : [
+            ...listArchiveBlockers(changeDir, report.issues, unresolved),
+            ...metadataBlockers,
+            ...dependencyBlockers,
+            ...dispositionBlockers,
+        ];
+    if (blockers.length > 0 && !yes) {
+        throw new Error(`Change '${name}' has archive blockers; nothing was written:\n  ${blockers.join('\n  ')}\n` +
+            `Fix the blockers, or pass --yes to archive with open tasks (a refused delta still aborts the fold` +
+            `${unresolved.length > 0 ? '; an unresolved header needs --force' : ''}).`);
+    }
+    // 1c. Unresolved headers are never waived by --yes: the fold would drop them
+    //     silently and the published spec would keep the old requirement. --force
+    //     archives anyway and skips them, each named below.
+    if (unresolved.length > 0 && !force) {
+        throw new Error(`Change '${name}' has ${unresolved.length} unresolved delta header(s); nothing was written:\n  ` +
+            `${unresolved.map((u) => `[WARNING] ${u.entryPath}: ${u.message}`).join('\n  ')}\n` +
+            `Pass --force to archive anyway (those deltas are skipped; the change record keeps their text).`);
+    }
+    // 1d. Supersession links (design.md `Supersedes:`), checked before any write.
+    const supersedes = await checkSupersession(name, changeDir, changesDir, metadata);
+    // 1e. Dispositioned tasks, read while the change still sits at changeDir (the
+    //     move below relocates it).
+    const dispositions = dispositionedTasks(changeDir);
+    // 2. Fold the change's delta specs into openspec/specs/. buildUpdatedSpec does
+    //    the ADDED/MODIFIED/REMOVED/RENAMED merge; writeUpdatedSpec writes it in
+    //    place. A fold that resolves to zero operations is an already-synced
+    //    (early-sync) delta and is skipped, matching upstream's write gate.
+    //
+    //    Capability RETIREMENT (deleting a main spec whose last requirement a
+    //    delta removed) is gated upstream behind an explicit retire_capabilities
+    //    marker and is out of this vendored slice; here every fold rebuilds and
+    //    writes the spec, never deletes one.
+    //    Build every fold BEFORE writing any: buildUpdatedSpec throws on an
+    //    unapplicable delta, so planning the whole change first means one bad
+    //    delta aborts the archive with openspec/specs/ untouched, rather than
+    //    leaving earlier specs half-written.
+    const updates = await findSpecUpdates(changeDir, specsDir);
+    const plan = [];
+    const skipUnresolved = force === true && unresolved.length > 0;
+    for (const update of updates) {
+        const built = await buildUpdatedSpec(update, name, { silent: true, skipUnresolved });
+        plan.push({ update, rebuilt: built.rebuilt, counts: built.counts });
+    }
+    const applied = [];
+    for (const { update, rebuilt, counts } of plan) {
+        const total = counts.added + counts.modified + counts.removed + counts.renamed;
+        if (total === 0)
+            continue; // already in sync — nothing to write
+        await writeUpdatedSpec(update, rebuilt, counts, { silent: true });
+        applied.push(update.id);
+    }
+    // 3. Move the change into changes/archive/<name>/. Refuse to clobber an
+    //    existing archived change of the same name.
+    const archiveDir = path.join(changesDir, 'archive');
+    const archivedTo = path.join(archiveDir, name);
+    await fs.mkdir(archiveDir, { recursive: true });
+    if (fssync.existsSync(archivedTo)) {
+        throw new Error(`An archived change already exists at ${archivedTo}; move or remove it before archiving '${name}'.`);
+    }
+    await fs.rename(changeDir, archivedTo);
+    // 4. Reverse links: the superseded archived record names its successor.
+    for (const link of supersedes)
+        await writeSupersededBy(link, name);
+    // 5. Open follow-ups, read from the archived location (the file moved with the
+    //    directory in step 3): printed as a notice, never a blocker. An item is open
+    //    while its checkbox is unchecked, the rule `follow-up list`, `follow-up claim`
+    //    and the session-start pointer read it by, so the four never disagree.
+    const followUps = readFollowUps(archivedTo).filter((item) => !item.done);
+    return { applied, archivedTo, supersedes, skipped: skipUnresolved ? unresolved : [], dispositions, followUps };
+}
+/**
+ * CLI wrapper for `openspec archive <id>`. Returns the process exit code and
+ * emits either the single-document `--json` result or human-readable lines.
+ */
+export async function archiveHandler(projectRoot, changeName, options) {
+    try {
+        const result = await archiveChange(changeName, {
+            projectRoot,
+            ...(options.yes !== undefined ? { yes: options.yes } : {}),
+            ...(options.force !== undefined ? { force: options.force } : {}),
+        });
+        if (options.json) {
+            console.log(JSON.stringify({
+                archived: true,
+                change: changeName,
+                applied: result.applied,
+                archivedTo: result.archivedTo,
+                supersedes: result.supersedes,
+                skipped: result.skipped.map((u) => ({ operation: u.operation, header: u.header, spec: u.specId, ...(u.addedBy ? { addedBy: u.addedBy } : {}) })),
+                dispositions: result.dispositions,
+                followUps: result.followUps,
+            }, null, 2));
+        }
+        else {
+            if (result.applied.length > 0) {
+                console.log(`Applied spec updates: ${result.applied.join(', ')}`);
+            }
+            else {
+                console.log('No spec updates to apply (already in sync).');
+            }
+            for (const link of result.supersedes) {
+                console.log(`Supersedes ${link.change} (${link.path}); reverse link written to its design.md`);
+            }
+            for (const u of result.skipped) {
+                console.log(`Warning (--force): skipped ${u.operation} "${u.header}" in specs/${u.entryPath} — ${u.message}`);
+            }
+            if (result.dispositions.length > 0) {
+                console.log('Dispositions:');
+                const byKind = new Map();
+                for (const d of result.dispositions) {
+                    const group = byKind.get(d.kind) ?? [];
+                    group.push(d);
+                    byKind.set(d.kind, group);
+                }
+                for (const group of byKind.values()) {
+                    for (const d of group)
+                        console.log(`  ${d.kind}: ${d.task} -> ${d.target}`);
+                }
+            }
+            if (result.followUps.length > 0) {
+                console.log(`follow-ups open: ${result.followUps.length}`);
+                for (const item of result.followUps) {
+                    const suffix = item.from ? ` (from ${item.from})` : '';
+                    console.log(`  ${item.index}. ${item.text}${suffix}`);
+                }
+            }
+            console.log(`Archived change to ${result.archivedTo}`);
+        }
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json) {
+            console.log(JSON.stringify({ archived: false, status: [{ severity: 'error', code: 'archive_error', message }] }, null, 2));
+        }
+        else {
+            console.error(message);
+        }
+        return 1;
+    }
+}

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

@@ -0,0 +1,4 @@
+export interface ContextOptions {
+    json?: boolean;
+}
+export declare function contextHandler(projectRoot: string | null, options: ContextOptions): number;

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

@@ -0,0 +1,48 @@
+// `openspec context [--json]` — store-free minimal working set.
+//
+// Upstream `context` renders the multi-repo working set (root + referenced
+// stores) from the store registry. This slice dropped the store, so the working
+// set is always "this root alone": a `{ root: { path }, members: [] }` brief.
+// When no openspec/ root is found, it reports the `no_openspec_root` diagnostic
+// the /opsx propose workflow checks for (then it falls back to `schemas --json`
+// from the cwd). The `--store` flag, if passed, is accepted and ignored.
+import { planningHomeStub, printJson } from './shared.js';
+export function contextHandler(projectRoot, options) {
+    if (!projectRoot) {
+        const payload = {
+            root: null,
+            members: [],
+            status: [
+                {
+                    severity: 'error',
+                    code: 'no_openspec_root',
+                    message: 'No OpenSpec root found from the current directory.',
+                },
+            ],
+        };
+        if (options.json) {
+            printJson(payload);
+        }
+        else {
+            console.error('No OpenSpec root found from the current directory.');
+        }
+        return 1;
+    }
+    const workingSet = {
+        root: { path: projectRoot },
+        planningHome: planningHomeStub(projectRoot),
+        members: [],
+        status: [],
+    };
+    if (options.json) {
+        printJson(workingSet);
+        return 0;
+    }
+    console.log(`Working context for ${projectRoot}`);
+    console.log();
+    console.log('OpenSpec root');
+    console.log(`  ${projectRoot}`);
+    console.log();
+    console.log('No references declared; the working set is this root alone.');
+    return 0;
+}

package/node_modules/@freeharness/sdd/dist/src/shim/follow-up.d.ts

@@ -0,0 +1,57 @@
+/** One follow-up item, its 1-based position among item lines in file order. */
+export interface FollowUpItem {
+    index: number;
+    text: string;
+    from: string | null;
+    /** Checkbox state: a checked item is settled, whether or not it names a claimant. */
+    done: boolean;
+    /** The claiming change id, null for an item checked by hand with no `-> claimed by` suffix. */
+    claimedBy: string | null;
+}
+/**
+ * Reads every item line of a change's follow-ups.md, ignoring any other line
+ * (heading, blank, comment). Index is the 1-based position among item lines in
+ * file order. Absent file -> empty list.
+ */
+export declare function readFollowUps(dir: string): FollowUpItem[];
+export interface AddFollowUpResult {
+    change: string;
+    index: number;
+}
+/**
+ * Appends an unclaimed item to a change's follow-ups.md, creating the file from
+ * the template when absent. Throws when the change resolves neither in flight
+ * nor archived.
+ */
+export declare function addFollowUp(projectRoot: string, changeId: string, text: string, from?: string): AddFollowUpResult;
+export interface ListedFollowUp {
+    change: string;
+    index: number;
+    text: string;
+    from: string | null;
+    state: 'open';
+}
+/** Every open (unchecked) item of every in-flight and archived change. */
+export declare function listFollowUps(projectRoot: string): ListedFollowUp[];
+export interface ClaimFollowUpResult {
+    change: string;
+    index: number;
+    by: string;
+}
+/**
+ * Rewrites an item as claimed. Refuses an index without an item, an item
+ * already claimed, or a `--by` id that resolves neither in flight nor
+ * archived; every other line of the file is left byte-identical.
+ */
+export declare function claimFollowUp(projectRoot: string, changeId: string, index: number, byId: string): ClaimFollowUpResult;
+export interface FollowUpCommandOptions {
+    json?: boolean;
+    from?: string;
+    by?: string;
+}
+/** CLI wrapper for `openspec follow-up add <change-id> "<text>" [--from <task>]`. */
+export declare function followUpAddHandler(projectRoot: string, changeId: string | undefined, text: string | undefined, options: FollowUpCommandOptions): number;
+/** CLI wrapper for `openspec follow-up list [--json]`. */
+export declare function followUpListHandler(projectRoot: string, options: FollowUpCommandOptions): number;
+/** CLI wrapper for `openspec follow-up claim <change-id> <index> --by <change-id>`. */
+export declare function followUpClaimHandler(projectRoot: string, changeId: string | undefined, indexArg: string | undefined, options: FollowUpCommandOptions): number;