@nick848/fet 0.1.0

package/dist/scanner.js

@@ -0,0 +1,352 @@
+import Handlebars from "handlebars";
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { CONFIG_FILE } from "./paths.js";
+const SENSITIVE = [
+    /AKIA[0-9A-Z]{16}/,
+    /BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY/,
+    /api[_-]?key\s*[:=]\s*['"][^'"]+['"]/i,
+    /https?:\/\/[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}/,
+];
+const AGENTS_MARK_START = "<!-- FET:AUTO_START -->";
+const AGENTS_MARK_END = "<!-- FET:AUTO_END -->";
+const CONFIG_START = "# FET_MANAGED_START";
+const CONFIG_END = "# FET_MANAGED_END";
+const ROUTE_CANDIDATES = [
+    "src/router/index.ts",
+    "src/router.ts",
+    "src/routes.tsx",
+    "src/App.tsx",
+    "app/router.options.ts",
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts",
+    "nuxt.config.ts",
+    "svelte.config.js",
+    "src/routes/+layout.svelte",
+];
+function detectFromDeps(deps) {
+    let framework = "[NEEDS LLM INPUT]";
+    if (deps.next)
+        framework = "Next.js";
+    else if (deps.nuxt)
+        framework = "Nuxt";
+    else if (deps.svelte || deps["@sveltejs/kit"])
+        framework = "SvelteKit";
+    else if (deps.vue || deps["@vitejs/plugin-vue"])
+        framework = "Vue";
+    else if (deps.react || deps["@vitejs/plugin-react"])
+        framework = "React";
+    else if (deps["@angular/core"])
+        framework = "Angular";
+    const language = deps.typescript || deps["@types/node"] ? "TypeScript" : "JavaScript";
+    let bundler = "[NEEDS LLM INPUT]";
+    if (deps.vite || deps["@vitejs/plugin-react"] || deps["@vitejs/plugin-vue"])
+        bundler = "Vite";
+    else if (deps.webpack)
+        bundler = "webpack";
+    else if (deps["@rspack/core"])
+        bundler = "Rspack";
+    else if (deps.rollup)
+        bundler = "Rollup";
+    else if (deps.next || deps.nuxt)
+        bundler = "(framework default)";
+    let state = "[NEEDS LLM INPUT]";
+    if (deps["@reduxjs/toolkit"] || deps.redux)
+        state = "Redux";
+    else if (deps.pinia)
+        state = "Pinia";
+    else if (deps["@tanstack/react-query"])
+        state = "TanStack Query";
+    else if (deps.zustand)
+        state = "Zustand";
+    else if (deps.mobx)
+        state = "MobX";
+    let ui = "[NEEDS LLM INPUT]";
+    if (deps["@mui/material"])
+        ui = "MUI";
+    else if (deps["antd"])
+        ui = "Ant Design";
+    else if (deps["@chakra-ui/react"])
+        ui = "Chakra";
+    else if (deps["@radix-ui/react-dialog"])
+        ui = "Radix";
+    else if (deps["element-plus"])
+        ui = "Element Plus";
+    else if (deps.tailwindcss)
+        ui = "Tailwind CSS";
+    return { framework, language, bundler, state, ui };
+}
+function shallowTree(cwd, maxDepth, maxEntries) {
+    const lines = [];
+    const walk = (dir, depth, prefix) => {
+        if (lines.length >= maxEntries || depth > maxDepth)
+            return;
+        let entries = [];
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries.sort()) {
+            if (lines.length >= maxEntries)
+                break;
+            if (name === "node_modules" || name === ".git" || name === "dist" || name === "build")
+                continue;
+            const p = join(dir, name);
+            let isDir = false;
+            try {
+                isDir = statSync(p).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            const rel = relative(cwd, p) || ".";
+            lines.push(`${prefix}${isDir ? "📁 " : "📄 "}${rel.replace(/\\/g, "/")}`);
+            if (isDir && depth < maxDepth)
+                walk(p, depth + 1, prefix + "  ");
+        }
+    };
+    walk(cwd, 0, "");
+    return lines.length ? lines.join("\n") : "[empty or unreadable]";
+}
+function buildScriptsTable(pkg) {
+    const s = pkg.scripts;
+    if (!s || !Object.keys(s).length)
+        return "_No scripts in package.json_";
+    const rows = Object.entries(s)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `| \`${k}\` | \`${String(v).replace(/\|/g, "\\|")}\` |`)
+        .join("\n");
+    return ["| Script | Command |", "| --- | --- |", rows].join("\n");
+}
+export function scanProject(cwd) {
+    const warnings = [];
+    const pkgPath = join(cwd, "package.json");
+    let projectName = "";
+    let description = "";
+    let frameworkGuess = "[NEEDS LLM INPUT]";
+    let languageGuess = "[NEEDS LLM INPUT]";
+    let bundlerGuess = "[NEEDS LLM INPUT]";
+    let stateManagementGuess = "[NEEDS LLM INPUT]";
+    let uiLibraryGuess = "[NEEDS LLM INPUT]";
+    let scriptsTable = "";
+    let testCommand = "[NEEDS LLM INPUT]";
+    const deps = {};
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            projectName = pkg.name ?? "";
+            description = pkg.description ?? "";
+            Object.assign(deps, pkg.dependencies, pkg.devDependencies);
+            const d = detectFromDeps(deps);
+            frameworkGuess = d.framework;
+            languageGuess = d.language;
+            bundlerGuess = d.bundler;
+            stateManagementGuess = d.state;
+            uiLibraryGuess = d.ui;
+            scriptsTable = buildScriptsTable(pkg);
+            if (pkg.scripts?.test)
+                testCommand = pkg.scripts.test;
+        }
+        catch {
+            warnings.push("package.json parse failed");
+        }
+    }
+    let readmeExcerpt = "";
+    const readme = join(cwd, "README.md");
+    if (existsSync(readme)) {
+        const text = readFileSync(readme, "utf8");
+        for (const re of SENSITIVE) {
+            if (re.test(text))
+                warnings.push("Possible sensitive pattern in README — review before sharing (DESIGN 14.2).");
+        }
+        readmeExcerpt = text.split(/\r?\n/).slice(0, 45).join("\n");
+    }
+    const foundRoutes = [];
+    for (const r of ROUTE_CANDIDATES) {
+        if (existsSync(join(cwd, r)))
+            foundRoutes.push(r);
+    }
+    const routeFiles = foundRoutes.length > 0
+        ? foundRoutes.map((r) => `- \`${r}\` (heuristic; verify)\n`).join("")
+        : "_No common route entry files detected — [NEEDS LLM INPUT]_";
+    const i18nPaths = ["src/locales", "public/locales", "locales", "i18n", "messages"].filter((p) => existsSync(join(cwd, p)));
+    const i18nHint = i18nPaths.length > 0
+        ? `Detected paths: ${i18nPaths.map((p) => `\`${p}\``).join(", ")}`
+        : "[NEEDS LLM INPUT] — add i18n dirs or run update-context after setup";
+    const eslintHint = existsSync(join(cwd, ".eslintrc.cjs"))
+        ? "`.eslintrc.cjs` present"
+        : existsSync(join(cwd, "eslint.config.js"))
+            ? "`eslint.config.js` (flat) present"
+            : existsSync(join(cwd, ".eslintrc.json"))
+                ? "`.eslintrc.json` present"
+                : "[NEEDS LLM INPUT] — no common ESLint config filename found";
+    const tsconfigHint = existsSync(join(cwd, "tsconfig.json"))
+        ? "`tsconfig.json` present — use `npx tsc --noEmit` for typecheck"
+        : "_No root tsconfig — JS project or nested TSconfigs [NEEDS LLM INPUT]_";
+    const projectTree = shallowTree(cwd, 2, 80);
+    return {
+        projectName,
+        description,
+        frameworkGuess,
+        languageGuess,
+        bundlerGuess,
+        stateManagementGuess,
+        uiLibraryGuess,
+        readmeExcerpt,
+        scriptsTable,
+        testCommand,
+        eslintHint,
+        tsconfigHint,
+        routeFiles,
+        i18nHint,
+        projectTree,
+        warnings,
+    };
+}
+const agentsTpl = Handlebars.compile(`# AGENTS — project context (FET)
+
+> Auto-generated section is between HTML comment markers. Do not remove markers.
+
+<!-- FET:AUTO_START -->
+## Overview
+| Field | Value |
+| --- | --- |
+| Project | {{projectName}} |
+| Description | {{description}} |
+| Framework (guess) | {{frameworkGuess}} |
+| Language (guess) | {{languageGuess}} |
+| Bundler (guess) | {{bundlerGuess}} |
+| State (guess) | {{stateManagementGuess}} |
+| UI (guess) | {{uiLibraryGuess}} |
+
+## Run commands (from package.json)
+{{scriptsTable}}
+
+**Suggested test command:** \`{{testCommand}}\`
+
+## Project tree (depth 2, truncated)
+\`\`\`
+{{projectTree}}
+\`\`\`
+
+## README excerpt
+\`\`\`
+{{readmeExcerpt}}
+\`\`\`
+
+## Routing (heuristic)
+{{routeFiles}}
+
+## i18n
+{{i18nHint}}
+
+## Code quality signals
+- ESLint: {{eslintHint}}
+- TypeScript: {{tsconfigHint}}
+
+## Terminology / business rules
+[NEEDS LLM INPUT]
+
+## Core modules
+[NEEDS LLM INPUT]
+
+## Notes
+- FET does not execute LLMs; use your AI tool to fill sections marked [NEEDS LLM INPUT].
+<!-- FET:AUTO_END -->
+
+## Human / LLM additions
+[NEEDS LLM INPUT]
+`);
+export function renderAgents(scan) {
+    return agentsTpl({
+        projectName: scan.projectName || "[unknown]",
+        description: scan.description || "[none]",
+        frameworkGuess: scan.frameworkGuess,
+        languageGuess: scan.languageGuess,
+        bundlerGuess: scan.bundlerGuess,
+        stateManagementGuess: scan.stateManagementGuess,
+        uiLibraryGuess: scan.uiLibraryGuess,
+        readmeExcerpt: scan.readmeExcerpt || "[no README.md]",
+        scriptsTable: scan.scriptsTable,
+        testCommand: scan.testCommand,
+        eslintHint: scan.eslintHint,
+        tsconfigHint: scan.tsconfigHint,
+        routeFiles: scan.routeFiles,
+        i18nHint: scan.i18nHint,
+        projectTree: scan.projectTree,
+    });
+}
+export function writeAgentsMd(cwd, scan) {
+    const path = join(cwd, "AGENTS.md");
+    const body = renderAgents(scan);
+    if (!existsSync(path)) {
+        writeFileSync(path, body, "utf8");
+        return;
+    }
+    const existing = readFileSync(path, "utf8");
+    const start = existing.indexOf(AGENTS_MARK_START);
+    const end = existing.indexOf(AGENTS_MARK_END);
+    if (start !== -1 && end !== -1 && end > start) {
+        const inner = extractAutoBody(body);
+        const innerStart = start + AGENTS_MARK_START.length;
+        const merged = `${existing.slice(0, innerStart)}\n${inner}\n${existing.slice(end)}`;
+        writeFileSync(path, merged, "utf8");
+        return;
+    }
+    writeFileSync(path, `${existing.trimEnd()}\n\n${body}\n`, "utf8");
+}
+function extractAutoBody(full) {
+    const a = full.indexOf(AGENTS_MARK_START);
+    const b = full.indexOf(AGENTS_MARK_END);
+    if (a === -1 || b === -1)
+        return full.trim();
+    return full.slice(a + AGENTS_MARK_START.length, b).trim();
+}
+export function mergeConfigYaml(cwd, scan) {
+    const p = join(cwd, CONFIG_FILE);
+    const watchDirs = ["src", "tests"].filter((d) => existsSync(join(cwd, d)));
+    const watchYaml = watchDirs.length > 0 ? watchDirs.map((d) => JSON.stringify(d)).join(", ") : "";
+    const blockLines = [
+        CONFIG_START,
+        "# FET managed keys (nested under `fet`) — do not remove markers (DESIGN 3.2.2)",
+        "# Source: fet scanner (package.json, filesystem heuristics)",
+        "fet:",
+        `  framework: ${JSON.stringify(scan.frameworkGuess)}`,
+        `  language: ${JSON.stringify(scan.languageGuess)}`,
+        `  bundler: ${JSON.stringify(scan.bundlerGuess)}`,
+        `  state_management: ${JSON.stringify(scan.stateManagementGuess)}`,
+        `  ui_library: ${JSON.stringify(scan.uiLibraryGuess)}`,
+        "  # DESIGN 6.3 — directories watched by `fet apply`",
+        `  watch_directories: ${watchYaml ? `[${watchYaml}]` : "[]"}`,
+        "  # Test entry (string from package.json scripts.test if any)",
+        `  test_script: ${JSON.stringify(scan.testCommand)}`,
+        "  project_layout: |",
+        ...scan.projectTree.split("\n").map((line) => `    ${line}`),
+        CONFIG_END,
+    ];
+    const block = `${blockLines.join("\n")}\n`;
+    if (!existsSync(p)) {
+        writeFileSync(p, block, "utf8");
+        return;
+    }
+    const raw = readFileSync(p, "utf8");
+    const s = raw.indexOf(CONFIG_START);
+    const e = raw.indexOf(CONFIG_END);
+    if (s !== -1 && e !== -1 && e > s) {
+        const merged = `${raw.slice(0, s)}${block}${raw.slice(e + CONFIG_END.length)}`;
+        writeFileSync(p, merged, "utf8");
+        return;
+    }
+    writeFileSync(p, `${raw.trimEnd()}\n\n${block}`, "utf8");
+}
+export function runUpdateContext(cwd) {
+    const scan = scanProject(cwd);
+    for (const w of scan.warnings)
+        console.warn(`[fet] ${w}`);
+    writeAgentsMd(cwd, scan);
+    mergeConfigYaml(cwd, scan);
+    console.log("[fet] update-context: refreshed AGENTS.md auto block and openspec/config.yaml fet section.");
+}

package/dist/skills.d.ts

@@ -0,0 +1,3 @@
+export declare function generateCursorTooling(cwd: string, opts: {
+    force: boolean;
+}): Promise<void>;

package/dist/skills.js

@@ -0,0 +1,142 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { promptSkillConflict } from "./prompt.js";
+const SKILLS = [
+    {
+        fileBase: "explore",
+        name: "/fet-explore",
+        description: "FET: explore (openspec proxy)",
+        body: "Terminal: `fet explore`",
+    },
+    {
+        fileBase: "propose",
+        name: "/fet-propose",
+        description: "FET: propose (openspec proxy)",
+        body: "Terminal: `fet propose`",
+    },
+    {
+        fileBase: "new",
+        name: "/fet-new",
+        description: "FET: new change skeleton",
+        body: "Terminal: `fet new <change-id>` (maps to `openspec new change`).",
+    },
+    {
+        fileBase: "continue",
+        name: "/fet-continue",
+        description: "FET: continue workflow",
+        body: "Terminal: `fet continue`",
+    },
+    {
+        fileBase: "ff",
+        name: "/fet-ff",
+        description: "FET: ff workflow",
+        body: "Terminal: `fet ff`",
+    },
+    {
+        fileBase: "apply",
+        name: "/apply",
+        description: "FET 实施当前任务",
+        body: "在终端执行 `fet apply` 以刷新 `openspec/changes/<change-id>/apply-instructions.md`，然后按该文件实施。",
+    },
+    {
+        fileBase: "fet-validate",
+        name: "/fet-validate",
+        description: "FET: validate current task",
+        body: "Terminal: `fet validate`",
+    },
+    {
+        fileBase: "fet-verify",
+        name: "/fet-verify",
+        description: "FET: final verify",
+        body: "Terminal: `fet verify` or `fet verify --auto`",
+    },
+    {
+        fileBase: "fet-sync",
+        name: "/fet-sync",
+        description: "FET: sync delta specs",
+        body: "Terminal: `fet sync` (requires verify; interactive terminal, DESIGN 8.2).",
+    },
+    {
+        fileBase: "fet-archive",
+        name: "/fet-archive",
+        description: "FET: archive change",
+        body: "Terminal: `fet archive <change>` after verify.",
+    },
+    {
+        fileBase: "bulk-archive",
+        name: "/fet-bulk-archive",
+        description: "FET: bulk archive",
+        body: "Terminal: `fet bulk-archive <id> [<id> ...]`",
+    },
+    {
+        fileBase: "onboard",
+        name: "/fet-onboard",
+        description: "FET: onboard",
+        body: "Terminal: `fet onboard`",
+    },
+    {
+        fileBase: "update-context",
+        name: "/fet-update-context",
+        description: "FET: refresh AGENTS / config",
+        body: "Terminal: `fet update-context`",
+    },
+    {
+        fileBase: "doctor",
+        name: "/fet-doctor",
+        description: "FET: doctor",
+        body: "Terminal: `fet doctor`",
+    },
+];
+function skillMarkdown(s) {
+    return [`---`, `name: ${s.name}`, `description: ${s.description}`, `---`, "", s.body, ""].join("\n");
+}
+export async function generateCursorTooling(cwd, opts) {
+    const skillsDir = join(cwd, ".cursor", "skills");
+    const rulesDir = join(cwd, ".cursor", "rules");
+    mkdirSync(skillsDir, { recursive: true });
+    mkdirSync(rulesDir, { recursive: true });
+    for (const s of SKILLS) {
+        const fname = `${s.fileBase}.md`;
+        const p = join(skillsDir, fname);
+        if (!existsSync(p) || opts.force) {
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, skillMarkdown(s), "utf8");
+            continue;
+        }
+        const existing = readFileSync(p, "utf8");
+        if (existing.includes("FET:") || existing.includes("fet ")) {
+            console.log(`[fet] skip skill (already FET): ${p}`);
+            continue;
+        }
+        const choice = await promptSkillConflict(p);
+        if (choice === "skip") {
+            console.log(`[fet] skipped: ${p}`);
+            continue;
+        }
+        if (choice === "merge") {
+            const merged = `${existing.trimEnd()}\n\n---\n\n## FET (merged)\n\n${s.body}\n`;
+            writeFileSync(p, merged, "utf8");
+            continue;
+        }
+        writeFileSync(p, skillMarkdown(s), "utf8");
+    }
+    const rulePath = join(rulesDir, "fet-context.mdc");
+    const rule = [
+        "---",
+        "description: Load FET/OpenSpec context before modifying project files",
+        "globs:",
+        "  - '**/*'",
+        "---",
+        "",
+        "When making substantive code changes, read `AGENTS.md` and `openspec/config.yaml` first.",
+        "For trivial Q&A you may skip full loading.",
+        "",
+    ].join("\n");
+    if (existsSync(rulePath) && !opts.force) {
+        console.warn(`[fet] skip rule (exists): ${rulePath}`);
+    }
+    else {
+        writeFileSync(rulePath, rule, "utf8");
+    }
+    console.log(`[fet] Cursor skills written under ${skillsDir}`);
+}

package/dist/state.d.ts

@@ -0,0 +1,17 @@
+import type { ChangeFetState, GlobalFetState } from "./types.js";
+export declare function defaultGlobalState(): GlobalFetState;
+export declare function defaultChangeState(changeId: string): ChangeFetState;
+export declare function readJson<T>(path: string): T | null;
+export declare function readGlobalState(cwd: string): GlobalFetState;
+export declare function readChangeState(cwd: string, changeId: string): ChangeFetState | null;
+export declare function writeGlobalState(cwd: string, state: GlobalFetState): void;
+export declare function writeChangeState(cwd: string, state: ChangeFetState): void;
+/** Remove ghost changes, align tasksCompleted from tasks.md (DESIGN 5.1). */
+export declare function reconcileStates(cwd: string, global: GlobalFetState): {
+    global: GlobalFetState;
+    warnings: string[];
+};
+export declare function ensureChangeTracked(global: GlobalFetState, changeId: string): GlobalFetState;
+/** DESIGN 5.3: remove archived change ids from global tracking (single write after success). */
+export declare function removeArchivedChangesFromGlobal(global: GlobalFetState, ids: string[]): GlobalFetState;
+export declare function positionalArgs(rest: string[]): string[];

package/dist/state.js

@@ -0,0 +1,126 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { backupIfExists, writeFileAtomicSync } from "./atomic-write.js";
+import { CHANGES_DIR, GLOBAL_STATE_FILE, changeStatePath, tasksPath } from "./paths.js";
+import { listCompletedTaskIds, readTasksFile } from "./tasks.js";
+export function defaultGlobalState() {
+    return { version: 1, activeChangeId: null, openChanges: [] };
+}
+export function defaultChangeState(changeId) {
+    return {
+        version: 1,
+        changeId,
+        currentPhase: "implement",
+        tasksCompleted: [],
+        currentTaskId: null,
+        verify: { status: "pending" },
+    };
+}
+export function readJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function readGlobalState(cwd) {
+    const p = join(cwd, GLOBAL_STATE_FILE);
+    const s = readJson(p);
+    if (!s || s.version !== 1)
+        return defaultGlobalState();
+    return s;
+}
+export function readChangeState(cwd, changeId) {
+    const p = join(cwd, changeStatePath(changeId));
+    const s = readJson(p);
+    if (!s || s.version !== 1)
+        return null;
+    return s;
+}
+export function writeGlobalState(cwd, state) {
+    const p = join(cwd, GLOBAL_STATE_FILE);
+    backupIfExists(p);
+    writeFileAtomicSync(p, `${JSON.stringify(state, null, 2)}\n`);
+}
+export function writeChangeState(cwd, state) {
+    const p = join(cwd, changeStatePath(state.changeId));
+    backupIfExists(p);
+    writeFileAtomicSync(p, `${JSON.stringify(state, null, 2)}\n`);
+}
+function listChangeIds(cwd) {
+    const root = join(cwd, CHANGES_DIR);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root).filter((name) => {
+        try {
+            return statSync(join(root, name)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Remove ghost changes, align tasksCompleted from tasks.md (DESIGN 5.1). */
+export function reconcileStates(cwd, global) {
+    const warnings = [];
+    const dirs = new Set(listChangeIds(cwd));
+    const nextOpen = global.openChanges.filter((id) => {
+        if (!dirs.has(id)) {
+            warnings.push(`Removed ghost change from openChanges: ${id}`);
+            return false;
+        }
+        return true;
+    });
+    let active = global.activeChangeId;
+    if (active && !dirs.has(active)) {
+        warnings.push(`Active change missing on disk: ${active}; clearing activeChangeId`);
+        active = null;
+    }
+    const g = { ...global, openChanges: nextOpen, activeChangeId: active };
+    for (const id of dirs) {
+        const tp = join(cwd, tasksPath(id));
+        if (!existsSync(tp))
+            continue;
+        let cs = readChangeState(cwd, id);
+        if (!cs) {
+            cs = defaultChangeState(id);
+            writeChangeState(cwd, cs);
+        }
+        const md = readTasksFile(tp);
+        const fromMd = listCompletedTaskIds(md);
+        const merged = [...new Set([...fromMd])].sort();
+        const prev = [...cs.tasksCompleted].sort().join(",");
+        const next = merged.join(",");
+        if (prev !== next) {
+            warnings.push(`Aligned tasksCompleted for ${id} from tasks.md`);
+            cs = { ...cs, tasksCompleted: merged };
+            writeChangeState(cwd, cs);
+        }
+    }
+    return { global: g, warnings };
+}
+export function ensureChangeTracked(global, changeId) {
+    const openChanges = global.openChanges.includes(changeId)
+        ? global.openChanges
+        : [...global.openChanges, changeId];
+    return {
+        ...global,
+        openChanges,
+        activeChangeId: global.activeChangeId ?? changeId,
+    };
+}
+/** DESIGN 5.3: remove archived change ids from global tracking (single write after success). */
+export function removeArchivedChangesFromGlobal(global, ids) {
+    const set = new Set(ids.filter(Boolean));
+    const openChanges = global.openChanges.filter((id) => !set.has(id));
+    let activeChangeId = global.activeChangeId;
+    if (activeChangeId && set.has(activeChangeId))
+        activeChangeId = openChanges[0] ?? null;
+    return { ...global, openChanges, activeChangeId };
+}
+export function positionalArgs(rest) {
+    return rest.filter((a) => !a.startsWith("-"));
+}

package/dist/tasks.d.ts

@@ -0,0 +1,13 @@
+export interface ParsedTask {
+    id: string;
+    title: string;
+    done: boolean;
+    autoNext: boolean;
+    lineIndex: number;
+}
+/** Parse OpenSpec-style tasks.md: markdown checkboxes with leading task ids. */
+export declare function parseTasksMd(content: string): ParsedTask[];
+export declare function listCompletedTaskIds(content: string): string[];
+export declare function firstIncompleteTask(content: string): ParsedTask | null;
+export declare function markTaskDoneInMarkdown(content: string, taskId: string): string;
+export declare function readTasksFile(path: string): string;