auriga-cli 1.27.0 → 1.29.0

package/dist/utils.d.ts

@@ -92,6 +92,8 @@ export interface LangOption {
     label: string;
     file: string;
 }
+export declare const DEFAULT_WORKFLOW_LANG = "zh-CN";
+export declare const DEFAULT_WORKFLOW_TEMPLATE_FILE = "AGENTS.md";
 export declare const LANGUAGES: LangOption[];
 /**
  * Reads `version` from the packaged manifest. Throws when the package

package/dist/utils.js

@@ -100,9 +100,11 @@ export function execAsync(cmd, opts) {
         });
     });
 }
+export const DEFAULT_WORKFLOW_LANG = "zh-CN";
+export const DEFAULT_WORKFLOW_TEMPLATE_FILE = "AGENTS.md";
 export const LANGUAGES = [
-    { value: "en", label: "English", file: "CLAUDE.md" },
-    { value: "zh-CN", label: "中文", file: "CLAUDE.zh-CN.md" },
+    { value: "zh-CN", label: "中文", file: "AGENTS.md" },
+    { value: "en", label: "English", file: "AGENTS.en.md" },
 ];
 // --- Remote content ---
 const REPO = "Ben2pc/auriga-cli";
@@ -146,7 +148,8 @@ function resolveContentRef() {
     return "main";
 }
 const CONTENT_FILES = [
-    "CLAUDE.md",
+    DEFAULT_WORKFLOW_TEMPLATE_FILE,
+    "AGENTS.en.md",
     "skills-lock.json",
     ".claude-plugin/marketplace.json",
     ".agents/plugins/marketplace.json",
@@ -182,8 +185,10 @@ export async function fetchContentRoot() {
     return tmpDir;
 }
 export async function fetchExtraContent(tmpDir, file) {
-    const content = await fetchFile(file);
     const dest = path.join(tmpDir, file);
+    if (fs.existsSync(dest))
+        return;
+    const content = await fetchFile(file);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.writeFileSync(dest, content);
 }

package/dist/workflow-docs.d.ts

@@ -0,0 +1,4 @@
+export declare const WORKFLOW_PRIMARY_FILE = "AGENTS.md";
+export declare const WORKFLOW_COMPAT_FILE = "CLAUDE.md";
+export declare const WORKFLOW_COMPAT_SYMLINK_TARGET = "AGENTS.md";
+export declare const LEGACY_AGENTS_SYMLINK_TARGET = "CLAUDE.md";

package/dist/workflow-docs.js

@@ -0,0 +1,4 @@
+export const WORKFLOW_PRIMARY_FILE = "AGENTS.md";
+export const WORKFLOW_COMPAT_FILE = "CLAUDE.md";
+export const WORKFLOW_COMPAT_SYMLINK_TARGET = WORKFLOW_PRIMARY_FILE;
+export const LEGACY_AGENTS_SYMLINK_TARGET = WORKFLOW_COMPAT_FILE;

package/dist/workflow-markers.d.ts

@@ -0,0 +1,59 @@
+/** Marker schema version. Frozen contract — bump only with a migration plan. */
+export declare const MARKER_SCHEMA = "v1";
+/** The START marker line for the given template language. Unknown languages
+ *  fall back to English. */
+export declare function workflowStartMarker(lang?: string): string;
+/** Build the END marker line, embedding the managed-block content hash so a
+ *  later upgrade can tell an untouched block from a hand-edited one. */
+export declare function workflowEndMarker(hash: string): string;
+/** Matches the auriga workflow H1 header in either language
+ *  (`# auriga Workflow (vX.Y.Z)` / `# auriga 工作流 (vX.Y.Z)`). */
+export declare const WORKFLOW_HEADER_RE: RegExp;
+/** sha256 of the managed-block body, truncated to 16 hex chars. Not a security
+ *  primitive — just a tamper check to distinguish untouched from hand-edited. */
+export declare function hashBlock(blockBody: string): string;
+export type MarkerParse = {
+    kind: "unmarked";
+} | {
+    kind: "malformed";
+    reason: string;
+} | {
+    kind: "marked";
+    /** Bytes before the START marker line (normally empty). */
+    prefix: string;
+    /** Bytes strictly between the START line and the END line — the managed
+     *  block. Includes the trailing newline that precedes the END line. */
+    blockBody: string;
+    /** Bytes after the END marker line — the project's own user region. */
+    userRegion: string;
+    /** sha256 recorded in the END marker, or null if the marker carried none. */
+    endHash: string | null;
+};
+/**
+ * Classify an AGENTS.md body by its managed-block markers.
+ *
+ *  - `unmarked`   — neither marker present (fresh-target / foreign / old-format)
+ *  - `malformed`  — exactly one marker, or END before START (can't safely splice)
+ *  - `marked`     — a well-formed START…END pair
+ */
+export declare function parseMarkers(content: string): MarkerParse;
+/**
+ * Build a marked AGENTS.md from its three parts. The END marker hash is
+ * computed from `blockBody` here, so callers never hand-maintain it.
+ *
+ * `blockBody` is expected to end with a newline (it is the content the START
+ * line's newline leads into, up to the END line). `parseMarkers` and
+ * `composeMarkedFile` are exact inverses for the block body and user region.
+ *
+ * `lang` selects the START marker's prose language (default English); it does
+ * not affect the parser, which keys on the language-independent token.
+ */
+export declare function composeMarkedFile(opts: {
+    prefix?: string;
+    blockBody: string;
+    userRegion?: string;
+    lang?: string;
+}): string;
+/** True when the first non-blank line is an auriga workflow header. Used to
+ *  tell an old-format (pre-marker) auriga workflow file from a foreign one. */
+export declare function hasAurigaHeader(content: string): boolean;

package/dist/workflow-markers.js

@@ -0,0 +1,116 @@
+// Managed-block markers for the installed AGENTS.md.
+//
+// auriga-cli installs its workflow document wrapped in a pair of HTML-comment
+// markers. Everything *between* the markers is the "managed block" — owned by
+// auriga-cli, replaced wholesale on upgrade. Everything *outside* (notably the
+// region after the END marker) is the project's own — auriga-cli never touches
+// it. This lets a downstream project extend its AGENTS.md while still
+// receiving workflow upgrades.
+//
+// Markers are HTML comments so both Claude Code and Codex (which read the same
+// file via the CLAUDE.md → AGENTS.md symlink) treat them as inert.
+//
+// This module is the single source of truth for the marker contract; it is
+// imported by both src/workflow.ts (install / upgrade) and src/state.ts
+// (presence detection). It deliberately has no heavy imports so state.ts /
+// server.ts don't pull in @inquirer/prompts transitively.
+import { createHash } from "node:crypto";
+/** Marker schema version. Frozen contract — bump only with a migration plan. */
+export const MARKER_SCHEMA = "v1";
+/**
+ * START marker line, one per template language. Only the prose differs — the
+ * structural `AURIGA:WORKFLOW:v1 START` token is language-independent, so the
+ * parser (`START_LINE_RE`) keys on the token alone and never needs to know the
+ * language. The English `AGENTS.en.md` gets the English marker; `AGENTS.md`
+ * gets the Chinese one, so a downstream file never carries a comment in the
+ * wrong language for its document.
+ */
+const WORKFLOW_START_MARKERS = {
+    en: `<!-- AURIGA:WORKFLOW:${MARKER_SCHEMA} START — Managed block, maintained by auriga-cli. Do not edit by hand; upgrades replace it wholesale. Put project-specific instructions after the END marker below. -->`,
+    "zh-CN": `<!-- AURIGA:WORKFLOW:${MARKER_SCHEMA} START — 受管区块,由 auriga-cli 维护,请勿手改;升级会整块覆盖。工程专属规则写在下方 END 标记之后。 -->`,
+};
+/** The START marker line for the given template language. Unknown languages
+ *  fall back to English. */
+export function workflowStartMarker(lang) {
+    return WORKFLOW_START_MARKERS[lang ?? "en"] ?? WORKFLOW_START_MARKERS.en;
+}
+/** Build the END marker line, embedding the managed-block content hash so a
+ *  later upgrade can tell an untouched block from a hand-edited one. */
+export function workflowEndMarker(hash) {
+    return `<!-- AURIGA:WORKFLOW:${MARKER_SCHEMA} END sha256=${hash} -->`;
+}
+// Marker line regexes (multiline — matched against the whole file body).
+// START tolerates any trailing comment text after `START`; END optionally
+// carries `sha256=<hex>`.
+const START_LINE_RE = /^<!--\s*AURIGA:WORKFLOW:v1\s+START\b.*?-->[ \t]*$/m;
+const END_LINE_RE = /^<!--\s*AURIGA:WORKFLOW:v1\s+END(?:\s+sha256=([0-9a-f]+))?[ \t]*-->[ \t]*$/m;
+/** Matches the auriga workflow H1 header in either language
+ *  (`# auriga Workflow (vX.Y.Z)` / `# auriga 工作流 (vX.Y.Z)`). */
+export const WORKFLOW_HEADER_RE = /^#\s+auriga\s+(?:Workflow|工作流)\s*\(v\d+\.\d+\.\d+\)/;
+/** sha256 of the managed-block body, truncated to 16 hex chars. Not a security
+ *  primitive — just a tamper check to distinguish untouched from hand-edited. */
+export function hashBlock(blockBody) {
+    return createHash("sha256").update(blockBody, "utf8").digest("hex").slice(0, 16);
+}
+/**
+ * Classify an AGENTS.md body by its managed-block markers.
+ *
+ *  - `unmarked`   — neither marker present (fresh-target / foreign / old-format)
+ *  - `malformed`  — exactly one marker, or END before START (can't safely splice)
+ *  - `marked`     — a well-formed START…END pair
+ */
+export function parseMarkers(content) {
+    const startMatch = START_LINE_RE.exec(content);
+    const endMatch = END_LINE_RE.exec(content);
+    if (!startMatch && !endMatch)
+        return { kind: "unmarked" };
+    if (!startMatch || !endMatch) {
+        return {
+            kind: "malformed",
+            reason: startMatch ? "START marker without a matching END" : "END marker without a matching START",
+        };
+    }
+    if (startMatch.index >= endMatch.index) {
+        return { kind: "malformed", reason: "END marker precedes START marker" };
+    }
+    const startLineEnd = content.indexOf("\n", startMatch.index);
+    if (startLineEnd < 0 || startLineEnd > endMatch.index) {
+        return { kind: "malformed", reason: "START marker line is not terminated before END" };
+    }
+    const endLineEnd = content.indexOf("\n", endMatch.index);
+    return {
+        kind: "marked",
+        prefix: content.slice(0, startMatch.index),
+        blockBody: content.slice(startLineEnd + 1, endMatch.index),
+        userRegion: endLineEnd < 0 ? "" : content.slice(endLineEnd + 1),
+        endHash: endMatch[1] ?? null,
+    };
+}
+/**
+ * Build a marked AGENTS.md from its three parts. The END marker hash is
+ * computed from `blockBody` here, so callers never hand-maintain it.
+ *
+ * `blockBody` is expected to end with a newline (it is the content the START
+ * line's newline leads into, up to the END line). `parseMarkers` and
+ * `composeMarkedFile` are exact inverses for the block body and user region.
+ *
+ * `lang` selects the START marker's prose language (default English); it does
+ * not affect the parser, which keys on the language-independent token.
+ */
+export function composeMarkedFile(opts) {
+    return ((opts.prefix ?? "") +
+        workflowStartMarker(opts.lang) + "\n" +
+        opts.blockBody +
+        workflowEndMarker(hashBlock(opts.blockBody)) + "\n" +
+        (opts.userRegion ?? ""));
+}
+/** True when the first non-blank line is an auriga workflow header. Used to
+ *  tell an old-format (pre-marker) auriga workflow file from a foreign one. */
+export function hasAurigaHeader(content) {
+    for (const line of content.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        return WORKFLOW_HEADER_RE.test(line);
+    }
+    return false;
+}

package/dist/workflow.d.ts

@@ -1,14 +1,13 @@
 import { type InstallOpts } from "./utils.js";
 export declare function installWorkflow(packageRoot: string, opts: InstallOpts): Promise<void>;
 /**
- * Uninstall the workflow (CLAUDE.md + AGENTS.md) from `opts.cwd`.
+ * Uninstall the workflow (AGENTS.md + CLAUDE.md) from `opts.cwd`.
  *
  * Safety contract:
  * - `opts.force` MUST be true. The CLI / server caller is responsible for
  *   confirming user intent BEFORE invoking this; we refuse otherwise.
- * - `AGENTS.md` is removed ONLY if it's a symlink (the install-time shape).
- *   A real-file AGENTS.md is left in place with a warning — the user has
- *   diverged from the install pattern and probably hand-edited it.
+ * - Real files are removed only when they are recognizable auriga workflow
+ *   files. Foreign instruction files are left in place with a warning.
  * - Missing files are a no-op: callers can re-run uninstall idempotently.
  * - `.claude/` is not touched; skills / plugins / hooks have their own
  *   uninstall paths.

package/dist/workflow.js

@@ -1,15 +1,58 @@
 import fs from "node:fs";
 import path from "node:path";
 import { input, select } from "@inquirer/prompts";
-import { LANGUAGES, fetchExtraContent, log, withEsc, } from "./utils.js";
+import { DEFAULT_WORKFLOW_LANG, DEFAULT_WORKFLOW_TEMPLATE_FILE, LANGUAGES, fetchExtraContent, log, withEsc, } from "./utils.js";
+import { composeMarkedFile, hasAurigaHeader, hashBlock, parseMarkers, } from "./workflow-markers.js";
+import { LEGACY_AGENTS_SYMLINK_TARGET, WORKFLOW_COMPAT_FILE, WORKFLOW_COMPAT_SYMLINK_TARGET, WORKFLOW_PRIMARY_FILE, } from "./workflow-docs.js";
+/**
+ * Back up `filePath` once. The canonical `<file>.bak` slot is reserved for the
+ * FIRST capture (the user's pre-auriga original) and is never overwritten — a
+ * later capture spills to a timestamped `<file>.bak.<stamp>`. Returns the path
+ * the backup was written to.
+ *
+ * `verbatimSymlinks` copies a symlink AS a symlink, preserving its literal
+ * (possibly relative) target — a foreign AGENTS.md may be a symlink pointing
+ * elsewhere, and we want the backup to preserve that target verbatim rather
+ * than snapshot whatever it currently resolves to. A real workflow file copies
+ * as a real file. `lstat` (not `existsSync`) probes the `.bak` slot so
+ * a backup that is itself a possibly-broken symlink still counts as present
+ * and is not silently overwritten.
+ */
+function backupOnce(filePath) {
+    const bakPath = filePath + ".bak";
+    let bakExists = true;
+    try {
+        fs.lstatSync(bakPath);
+    }
+    catch {
+        bakExists = false;
+    }
+    const dest = bakExists
+        ? `${bakPath}.${new Date().toISOString().replace(/[:.]/g, "-")}`
+        : bakPath;
+    fs.cpSync(filePath, dest, { verbatimSymlinks: true });
+    return dest;
+}
+function lstatMaybe(filePath) {
+    try {
+        return fs.lstatSync(filePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSymlinkTo(filePath, target) {
+    const stat = lstatMaybe(filePath);
+    return !!stat?.isSymbolicLink() && fs.readlinkSync(filePath) === target;
+}
 export async function installWorkflow(packageRoot, opts) {
     const lang = opts.interactive
         ? await withEsc(select({
-            message: "CLAUDE.md language:",
+            message: "Workflow language:",
             choices: LANGUAGES.map((l) => ({ name: l.label, value: l.value })),
-            default: "en",
+            default: DEFAULT_WORKFLOW_LANG,
         }))
-        : (opts.lang ?? "en");
+        : (opts.lang ?? DEFAULT_WORKFLOW_LANG);
     const targetDir = opts.interactive
         ? await withEsc(input({
             message: "Workflow install target directory:",
@@ -26,70 +69,142 @@ export async function installWorkflow(packageRoot, opts) {
         throw new Error(msg);
     }
     const langOpt = LANGUAGES.find((l) => l.value === lang);
-    // Lazy fetch: only download non-default language file when needed
-    if (langOpt.file !== "CLAUDE.md") {
+    // Lazy fetch: only download non-default language files when needed.
+    if (langOpt.file !== DEFAULT_WORKFLOW_TEMPLATE_FILE) {
         console.log(`Fetching ${langOpt.label} template...`);
         await fetchExtraContent(packageRoot, langOpt.file);
     }
-    const sourceClaude = path.join(packageRoot, langOpt.file);
-    const targetClaude = path.join(resolved, "CLAUDE.md");
-    const targetAgents = path.join(resolved, "AGENTS.md");
-    // Back up an existing CLAUDE.md before overwriting, but never clobber
-    // a prior .bak.
-    //
-    // Two regressions to defend against:
-    // 1. F1 (v1.19.0 Slice 0): re-install is the update path now, so a
-    //    second install must not overwrite the user's pre-auriga .bak with
-    //    our previous workflow version.
-    // 2. Codex adversarial review: if the user later replaces an
-    //    auriga-managed CLAUDE.md with foreign content (hand-paste, manual
-    //    edits, etc.) and re-runs install, the foreign content must NOT
-    //    be silently overwritten just because .bak already exists.
-    //
-    // Strategy: only consider the file "safe to overwrite without backup"
-    // when its bytes match the packaged source (i.e. it's the workflow we
-    // installed last time, untouched). Otherwise capture it — to .bak when
-    // free, else to a timestamped slot so .bak stays canonical.
-    if (fs.existsSync(targetClaude)) {
-        const currentBytes = fs.readFileSync(targetClaude);
-        const sourceBytes = fs.readFileSync(sourceClaude);
-        const diverged = !currentBytes.equals(sourceBytes);
-        if (diverged) {
-            const bakPath = targetClaude + ".bak";
-            if (fs.existsSync(bakPath)) {
-                const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-                const stampedPath = `${bakPath}.${stamp}`;
-                fs.copyFileSync(targetClaude, stampedPath);
-                log.warn(`CLAUDE.md.bak already exists; current CLAUDE.md backed up to ${path.basename(stampedPath)}`);
-            }
-            else {
-                fs.copyFileSync(targetClaude, bakPath);
-                log.warn(`Existing CLAUDE.md backed up to CLAUDE.md.bak`);
+    const sourceWorkflow = path.join(packageRoot, langOpt.file);
+    const targetPrimary = path.join(resolved, WORKFLOW_PRIMARY_FILE);
+    const targetCompat = path.join(resolved, WORKFLOW_COMPAT_FILE);
+    // The packaged template is authored with managed-block markers. Extract its
+    // managed block (the auriga workflow body) and its user-region placeholder.
+    // Defensive fallback: if the template somehow lacks markers, treat the whole
+    // file as the managed block with an empty user region.
+    const sourceContent = fs.readFileSync(sourceWorkflow, "utf8");
+    const sourceParsed = parseMarkers(sourceContent);
+    const sourceBlock = sourceParsed.kind === "marked"
+        ? sourceParsed.blockBody
+        : sourceContent.endsWith("\n")
+            ? sourceContent
+            : sourceContent + "\n";
+    const templateUserRegion = sourceParsed.kind === "marked" ? sourceParsed.userRegion : "";
+    const primaryStat = lstatMaybe(targetPrimary);
+    const compatStat = lstatMaybe(targetCompat);
+    const legacyShape = primaryStat?.isSymbolicLink() === true &&
+        fs.readlinkSync(targetPrimary) === LEGACY_AGENTS_SYMLINK_TARGET &&
+        compatStat?.isFile() === true;
+    const primaryForeignSymlink = primaryStat?.isSymbolicLink() === true &&
+        fs.readlinkSync(targetPrimary) !== LEGACY_AGENTS_SYMLINK_TARGET;
+    const compatIsCurrentPrimary = !primaryStat &&
+        compatStat !== undefined &&
+        !isSymlinkTo(targetCompat, WORKFLOW_COMPAT_SYMLINK_TARGET);
+    const currentPath = primaryStat && !primaryStat.isSymbolicLink()
+        ? targetPrimary
+        : legacyShape || compatIsCurrentPrimary
+            ? targetCompat
+            : undefined;
+    let wrotePrimary = false;
+    const writePrimary = (content) => {
+        if (primaryStat?.isSymbolicLink()) {
+            if (primaryForeignSymlink) {
+                const bak = backupOnce(targetPrimary);
+                log.warn(`AGENTS.md 是指向其它目标的软链;已备份到 ${path.basename(bak)} 后改为主文件。`);
             }
+            fs.unlinkSync(targetPrimary);
         }
+        fs.writeFileSync(targetPrimary, content);
+        wrotePrimary = true;
+    };
+    // Installing the workflow doc is one of five cases. The managed block is
+    // always replaced with the packaged version; the cases differ in how the
+    // project's own content (the user region) is preserved or backed up.
+    if (!currentPath) {
+        // 1. Fresh install — write the marked template as-is, no backup.
+        writePrimary(composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
+        log.ok(`AGENTS.md installed (${langOpt.label})`);
     }
-    fs.copyFileSync(sourceClaude, targetClaude);
-    log.ok(`CLAUDE.md copied (${langOpt.label})`);
-    // Create AGENTS.md symlink
-    try {
-        fs.lstatSync(targetAgents);
-        fs.unlinkSync(targetAgents);
+    else {
+        const current = fs.readFileSync(currentPath, "utf8");
+        const parsed = parseMarkers(current);
+        if (parsed.kind === "marked") {
+            // 2. Upgrade — splice the managed block, preserve the user region.
+            //    The END marker carries the block's hash. Three cases:
+            //      - hash present and matches  → block untouched, no backup
+            //      - hash present and mismatch → block hand-edited, back up + warn
+            //      - hash absent               → unverifiable (e.g. the file was
+            //        copied straight from the template, which ships a no-hash END
+            //        marker). Can't prove the block is untouched, so back up
+            //        conservatively rather than risk silently dropping an edit.
+            if (parsed.endHash === null) {
+                const bak = backupOnce(currentPath);
+                log.warn(`工作流文档的受管区块缺少校验标记,无法确认是否被改动;升级前已备份到 ${path.basename(bak)}`);
+            }
+            else if (parsed.endHash !== hashBlock(parsed.blockBody)) {
+                const bak = backupOnce(currentPath);
+                log.warn(`工作流文档的受管区块曾被手改;升级已整块覆盖该区块,改动前的文件见 ${path.basename(bak)}`);
+            }
+            writePrimary(composeMarkedFile({
+                prefix: parsed.prefix,
+                blockBody: sourceBlock,
+                userRegion: parsed.userRegion,
+                lang,
+            }));
+            log.ok(`AGENTS.md upgraded (${langOpt.label}); your project section was preserved`);
+        }
+        else if (parsed.kind === "unmarked" && hasAurigaHeader(current)) {
+            // 3. Old-format migration — an auriga workflow doc from before markers
+            //    existed. The user region can't be recovered from an unmarked file,
+            //    so back the whole thing up and install fresh.
+            const bak = backupOnce(currentPath);
+            writePrimary(composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
+            log.warn(`检测到旧版工作流文档(无受管标记);已备份到 ${path.basename(bak)}。` +
+                `若你改过它,请从备份把工程定制手动迁移到 END 标记之后的用户区。`);
+            log.ok(`AGENTS.md migrated to the managed-block format (${langOpt.label})`);
+        }
+        else if (parsed.kind === "unmarked") {
+            // 4. Foreign first install — a workflow doc from another tool. Keep its
+            //    content in place as the user region; no backup needed.
+            const foreign = current.endsWith("\n") ? current : current + "\n";
+            writePrimary(composeMarkedFile({ blockBody: sourceBlock, userRegion: "\n" + foreign, lang }));
+            log.ok(`AGENTS.md installed (${langOpt.label}); your existing content was kept below the managed block`);
+            if (currentPath === targetPrimary) {
+                log.warn("AGENTS.md already existed; its content was kept below the managed block.");
+            }
+        }
+        else {
+            // 5. Malformed markers — can't locate the block boundaries safely.
+            //    Back up and reinstall fresh rather than splice into a broken file.
+            const bak = backupOnce(currentPath);
+            writePrimary(composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
+            log.warn(`工作流文档的受管标记已损坏(${parsed.reason});已备份到 ${path.basename(bak)} 并重装。`);
+        }
     }
-    catch {
-        // does not exist, proceed
+    // Point CLAUDE.md at AGENTS.md via a compatibility symlink. If CLAUDE.md was
+    // the old primary file and its content was migrated above, replacing it with
+    // the symlink is safe. Otherwise preserve any real file or foreign symlink
+    // before replacing it.
+    const latestCompatStat = lstatMaybe(targetCompat);
+    if (latestCompatStat) {
+        const pointsToPrimary = isSymlinkTo(targetCompat, WORKFLOW_COMPAT_SYMLINK_TARGET);
+        const migratedFromCompat = currentPath === targetCompat && wrotePrimary && !latestCompatStat.isSymbolicLink();
+        if (!pointsToPrimary && !migratedFromCompat) {
+            const bak = backupOnce(targetCompat);
+            log.warn(`CLAUDE.md 不是指向 AGENTS.md 的软链;已备份到 ${path.basename(bak)} 后替换为软链。`);
+        }
+        fs.unlinkSync(targetCompat);
     }
-    fs.symlinkSync("CLAUDE.md", targetAgents);
-    log.ok("AGENTS.md -> CLAUDE.md symlink created");
+    fs.symlinkSync(WORKFLOW_COMPAT_SYMLINK_TARGET, targetCompat);
+    log.ok("CLAUDE.md -> AGENTS.md symlink created");
 }
 /**
- * Uninstall the workflow (CLAUDE.md + AGENTS.md) from `opts.cwd`.
+ * Uninstall the workflow (AGENTS.md + CLAUDE.md) from `opts.cwd`.
  *
  * Safety contract:
  * - `opts.force` MUST be true. The CLI / server caller is responsible for
  *   confirming user intent BEFORE invoking this; we refuse otherwise.
- * - `AGENTS.md` is removed ONLY if it's a symlink (the install-time shape).
- *   A real-file AGENTS.md is left in place with a warning — the user has
- *   diverged from the install pattern and probably hand-edited it.
+ * - Real files are removed only when they are recognizable auriga workflow
+ *   files. Foreign instruction files are left in place with a warning.
  * - Missing files are a no-op: callers can re-run uninstall idempotently.
  * - `.claude/` is not touched; skills / plugins / hooks have their own
  *   uninstall paths.
@@ -109,38 +224,58 @@ export async function uninstallWorkflow(opts) {
     const emit = (line) => {
         opts.onLog?.(line);
     };
-    const targetClaude = path.join(resolved, "CLAUDE.md");
-    const targetAgents = path.join(resolved, "AGENTS.md");
-    // CLAUDE.md — flat file. lstat to avoid following a symlink (would be
-    // unusual but we'd rather refuse to traverse than chase one out).
-    if (fs.existsSync(targetClaude)) {
-        fs.unlinkSync(targetClaude);
-        log.ok("CLAUDE.md removed");
-        emit("removed CLAUDE.md");
-    }
-    else {
-        log.skip("CLAUDE.md not present");
-        emit("CLAUDE.md not present");
-    }
-    // AGENTS.md — only remove symlinks (our install shape). lstatSync
-    // refuses to follow the link so we inspect the link itself.
-    try {
-        const stat = fs.lstatSync(targetAgents);
+    const targetClaude = path.join(resolved, WORKFLOW_COMPAT_FILE);
+    const targetAgents = path.join(resolved, WORKFLOW_PRIMARY_FILE);
+    const isAurigaWorkflowFile = (filePath) => {
+        try {
+            const content = fs.readFileSync(filePath, "utf8");
+            return parseMarkers(content).kind === "marked" || hasAurigaHeader(content);
+        }
+        catch {
+            return false;
+        }
+    };
+    const removeWorkflowPath = (filePath, name) => {
+        let stat;
+        try {
+            stat = fs.lstatSync(filePath);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT") {
+                log.skip(`${name} not present`);
+                emit(`${name} not present`);
+                return;
+            }
+            throw err;
+        }
         if (stat.isSymbolicLink()) {
-            fs.unlinkSync(targetAgents);
-            log.ok("AGENTS.md symlink removed");
-            emit("removed AGENTS.md symlink");
+            const linkTarget = fs.readlinkSync(filePath);
+            const isManagedSymlink = (name === WORKFLOW_PRIMARY_FILE && linkTarget === LEGACY_AGENTS_SYMLINK_TARGET) ||
+                (name === WORKFLOW_COMPAT_FILE && linkTarget === WORKFLOW_COMPAT_SYMLINK_TARGET);
+            if (isManagedSymlink) {
+                fs.unlinkSync(filePath);
+                log.ok(`${name} symlink removed`);
+                emit(`removed ${name} symlink`);
+            }
+            else {
+                log.warn(`foreign ${name} symlink left in place`);
+                emit(`foreign ${name} symlink left in place`);
+            }
+        }
+        else if (stat.isFile() && isAurigaWorkflowFile(filePath)) {
+            fs.unlinkSync(filePath);
+            log.ok(`${name} removed`);
+            emit(`removed ${name}`);
         }
         else {
-            // Real file (or directory) — user diverged from install. Don't
-            // silently destroy their content; warn and leave it.
-            log.warn("AGENTS.md is not a symlink; left in place");
-            emit("AGENTS.md is not a symlink; left in place");
+            log.warn(`foreign ${name} left in place`);
+            emit(`foreign ${name} left in place`);
         }
-    }
-    catch {
-        // ENOENT — already gone, idempotent no-op.
-        log.skip("AGENTS.md not present");
-        emit("AGENTS.md not present");
-    }
+    };
+    // Remove AGENTS.md first because it is the current primary. lstatSync refuses
+    // to follow symlinks, so the legacy AGENTS.md -> CLAUDE.md shape is handled
+    // without deleting CLAUDE.md through the link.
+    removeWorkflowPath(targetAgents, "AGENTS.md");
+    removeWorkflowPath(targetClaude, "CLAUDE.md");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auriga-cli",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins)",
   "license": "MIT",
   "repository": {
@@ -25,8 +25,8 @@
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
     "pretest": "npm run build",
-    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
-    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
+    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-markers.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/goalify.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
+    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-markers.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/goalify.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
     "pretest:e2e": "npm run build",
     "test:e2e": "tsc -p tsconfig.test.json && node --test dist-test/tests/e2e-install.test.js",
     "pretest:web-ui-e2e": "npm run build && npm --prefix ui ci && npm --prefix ui run build",