auriga-cli 1.26.0 → 1.28.0

package/README.md

@@ -13,7 +13,7 @@ This repo itself is a fully configured harness project. You can clone it to see
 | **Workflow** | `CLAUDE.md` auriga workflow: requirement clarification -> TDD -> Review, Harness principles, Subagent usage guide |
 | **Skills** | External development process skills — systematic-debugging, TDD, verification, planning, playwright (spec authoring and architecture design ship as the `spec-design` and `arch-design` skills inside the `auriga-workflow` plugin) |
 | **Recommended Skills** | Optional utility skills (e.g. `codex-agent`, `claude-code-agent`) you can add on top of the workflow skills |
-| **Plugins** | Recommended Claude Code and Codex plugins — skill-creator, claude-md-management, codex, auriga-workflow, auriga-notify, session-instructions-loader |
+| **Plugins** | Recommended Claude Code and Codex plugins — skill-creator, claude-md-management, playground, codex, auriga-workflow, auriga-notify, session-instructions-loader |
 
 ## Quick Start
 
@@ -87,9 +87,10 @@ The **Recommended preset** is checked by default and installs silently with the
 
 ### Workflow
 
-Copies `CLAUDE.md` to the target project and creates an `AGENTS.md` symlink for compatibility with different Agent frameworks. Supports English and Chinese — you choose during installation.
+Installs `CLAUDE.md` into the target project and creates an `AGENTS.md` symlink for compatibility with different Agent frameworks. Supports English and Chinese — you choose during installation.
 
-- Backs up existing `CLAUDE.md` before overwriting
+- **Extensible and upgradable**: the auriga workflow ships inside a managed block delimited by `<!-- AURIGA:WORKFLOW:v1 START/END -->` markers. Add your project-specific instructions *after* the END marker — re-running install upgrades the managed block in place and leaves your section untouched.
+- A pre-marker `CLAUDE.md` (installed by an older version) is migrated to the marked format on the next install, with the old file backed up to `CLAUDE.md.bak`. A foreign `CLAUDE.md` from another tool is kept as your user section below a fresh managed block.
 - Covers: requirement clarification, TDD, code review, branch workflow, subagent orchestration
 
 ### Skills
@@ -133,9 +134,10 @@ npx -y auriga-cli install plugins --agent codex --plugin session-instructions-lo
 | Plugin | Runtime | Description |
 |---|---|---|
 | skill-creator | Claude Code | Create and manage custom skills |
-| claude-md-management | Claude Code | Audit and improve CLAUDE.md |
+| claude-md-management | Claude Code / Codex | Audit and improve CLAUDE.md |
+| playground | Claude Code / Codex | Build interactive HTML playgrounds |
 | codex | Claude Code | Codex cross-model collaboration |
-| auriga-workflow | Claude Code / Codex | The auriga workflow plugin — workflow skills plus the git lifecycle hooks that enforce them. Skills: `incremental-impl`, `test-designer`, `spec-design`, `arch-design`, `code-simplify`, `session-compound`, `goalify` (plans an autonomous goal and dispatches it via the built-in `/goal` command), `deep-review` (multi-dimensional PR review orchestrator — parallel per-dimension reviewers synthesized into an actionable punch list), `reviewer-creator` (scaffolds project-level custom reviewers under `docs/rules/review/`), and `git-workflow` (git lifecycle skill). Hooks: `commit-reminder` (PostToolUse on file edits — `Edit` / `Write` / `MultiEdit` in Claude Code, `apply_patch` in Codex — nudges to commit at the next semantic boundary when uncommitted diff vs `HEAD` exceeds 200 lines or 8 files), `pr-create-guard` (PostToolUse on `gh pr create` → injects a PR-body snapshot for five-element self-verification and flags non-Conventional-Commits titles), and `pr-ready-guard` (PreToolUse on `gh pr ready` and non-draft `gh pr create` → blocks on stray planning docs, unfinalized active specs under `docs/specs/`, or unpushed commits). The two PostToolUse hooks reach full Claude Code / Codex parity; Codex currently fails open on `pr-ready-guard`'s PreToolUse `additionalContext` informational path (block path identical). Installed by default through the plugin path. |
+| auriga-workflow | Claude Code / Codex | The auriga workflow plugin — workflow skills plus the git lifecycle hooks that enforce them. Skills: `incremental-impl`, `test-designer`, `spec-design`, `arch-design`, `code-simplify`, `session-compound`, `goalify` (plans an autonomous goal and dispatches it via the built-in `/goal` command), `deep-review` (multi-dimensional PR review orchestrator — parallel per-dimension reviewers synthesized into an actionable punch list), `reviewer-creator` (scaffolds project-level custom reviewers under `docs/rules/review/`), and `git-workflow` (git lifecycle skill). Hooks: `commit-reminder` (PostToolUse on file edits — `Edit` / `Write` / `MultiEdit` in Claude Code, `apply_patch` in Codex — nudges to commit at the next semantic boundary when uncommitted diff vs `HEAD` exceeds 200 lines or 8 files), `pr-create-guard` (PostToolUse on `gh pr create` → injects a PR-body snapshot for five-element self-verification and flags non-Conventional-Commits titles), `pr-ready-guard` (PreToolUse on `gh pr ready` and non-draft `gh pr create` → blocks on stray planning docs, unfinalized active specs under `docs/specs/`, or unpushed commits), and `pr-merge-guard` (PreToolUse on `gh pr merge` → blocks while the PR body's Acceptance criteria section still has unchecked checklist items). The two PostToolUse hooks reach full Claude Code / Codex parity; Codex currently fails open on `pr-ready-guard`'s PreToolUse `additionalContext` informational path (block path identical). Installed by default through the plugin path. |
 | auriga-notify *(opt-in)* | Claude Code | macOS native notification plugin for Claude Code `Notification` events. Focus-aware sound-only mode, click-to-activate, per-project notification grouping, and migrated `config.json` / `icon.png` support. Not installed by `install --all`; install explicitly with `install plugins --plugin auriga-notify`. |
 | session-instructions-loader | Codex | Codex-only SessionStart plugin that injects ancestor `AGENTS.md` files plus repo-configured extra instruction files. |
 

package/README.zh-CN.md

@@ -13,7 +13,7 @@
 | **Workflow** | `CLAUDE.md` 里的 auriga 工作流：需求澄清 → TDD → Review，Harness 原则，Subagent 使用指南 |
 | **Skills** | 外部开发流程 skills —— systematic-debugging、TDD、verification、planning、playwright（spec 撰写与架构设计由 `auriga-workflow` 插件内的 `spec-design`、`arch-design` skill 提供）|
 | **Recommended Skills** | 可选的工具类 skills（如 `codex-agent`、`claude-code-agent`），在 workflow skills 之外按需追加 |
-| **Plugins** | 推荐的 Claude Code 和 Codex 插件 —— skill-creator、claude-md-management、codex、auriga-workflow、auriga-notify、session-instructions-loader |
+| **Plugins** | 推荐的 Claude Code 和 Codex 插件 —— skill-creator、claude-md-management、playground、codex、auriga-workflow、auriga-notify、session-instructions-loader |
 
 ## 快速开始
 
@@ -87,9 +87,10 @@ npx auriga-cli
 
 ### Workflow
 
-将 `CLAUDE.md` 复制到目标项目，并创建 `AGENTS.md` 软链接以兼容不同 Agent 框架。支持中英文版本，安装时可选择。
+将 `CLAUDE.md` 安装到目标项目，并创建 `AGENTS.md` 软链接以兼容不同 Agent 框架。支持中英文版本，安装时可选择。
 
-- 目标已有 `CLAUDE.md` 时会自动备份后覆盖
+- **可扩展、可升级**：auriga 工作流被一对 `<!-- AURIGA:WORKFLOW:v1 START/END -->` 标记包成「受管区块」。把你的工程专属规则写在 END 标记**之后**——再次安装只就地升级受管区块,你的内容原样保留。
+- 旧版本装下的、无标记的 `CLAUDE.md` 会在下次安装时迁移为标记格式,旧文件备份到 `CLAUDE.md.bak`。别的工具生成的 `CLAUDE.md` 会作为用户区保留在全新受管区块下方。
 - 涵盖：需求澄清、TDD、代码 Review、分支工作流、Subagent 编排
 
 ### Skills
@@ -133,9 +134,10 @@ npx -y auriga-cli install plugins --agent codex --plugin session-instructions-lo
 | 插件 | 运行时 | 说明 |
 |---|---|---|
 | skill-creator | Claude Code | 创建和管理自定义 skills |
-| claude-md-management | Claude Code | 审计和改进 CLAUDE.md |
+| claude-md-management | Claude Code / Codex | 审计和改进 CLAUDE.md |
+| playground | Claude Code / Codex | 构建交互式 HTML playground |
 | codex | Claude Code | Codex 跨模型协作 |
-| auriga-workflow | Claude Code / Codex | auriga 工作流插件 —— 工作流 skill 加上强制执行工作流的 git 生命周期 hook。Skills：`incremental-impl`、`test-designer`、`spec-design`、`arch-design`、`code-simplify`、`session-compound`、`goalify`（plan 出自驱 goal 并通过内置 `/goal` 命令分发执行）、`deep-review`（多维度 PR review 编排器——并行派发各维度 reviewer，汇总成可执行的 punch list）、`reviewer-creator`（在 `docs/rules/review/` 下生成项目级自定义 reviewer）、`git-workflow`（git 生命周期 skill）。Hooks：`commit-reminder`（文件编辑的 PostToolUse —— Claude Code 匹配 `Edit` / `Write` / `MultiEdit`，Codex 匹配 `apply_patch` —— 未提交 diff 对比 `HEAD` 超过 200 行或 8 个文件时，提醒在下一个语义边界 commit）、`pr-create-guard`（`gh pr create` 的 PostToolUse —— 注入 PR body 快照供五要素自检，并对不符合 Conventional Commits 的标题提示）、`pr-ready-guard`（`gh pr ready` 与非 draft `gh pr create` 的 PreToolUse —— 拦截游离规划文档、`docs/specs/` 内未结案的活跃 spec、未 push commits）。两个 PostToolUse hook 在 Claude Code / Codex 上完全对齐；Codex 仅对 `pr-ready-guard` 的 PreToolUse `additionalContext` 信息路径 fail-open（block 路径两边一致）。默认通过插件路径安装。 |
+| auriga-workflow | Claude Code / Codex | auriga 工作流插件 —— 工作流 skill 加上强制执行工作流的 git 生命周期 hook。Skills：`incremental-impl`、`test-designer`、`spec-design`、`arch-design`、`code-simplify`、`session-compound`、`goalify`（plan 出自驱 goal 并通过内置 `/goal` 命令分发执行）、`deep-review`（多维度 PR review 编排器——并行派发各维度 reviewer，汇总成可执行的 punch list）、`reviewer-creator`（在 `docs/rules/review/` 下生成项目级自定义 reviewer）、`git-workflow`（git 生命周期 skill）。Hooks：`commit-reminder`（文件编辑的 PostToolUse —— Claude Code 匹配 `Edit` / `Write` / `MultiEdit`，Codex 匹配 `apply_patch` —— 未提交 diff 对比 `HEAD` 超过 200 行或 8 个文件时，提醒在下一个语义边界 commit）、`pr-create-guard`（`gh pr create` 的 PostToolUse —— 注入 PR body 快照供五要素自检，并对不符合 Conventional Commits 的标题提示）、`pr-ready-guard`（`gh pr ready` 与非 draft `gh pr create` 的 PreToolUse —— 拦截游离规划文档、`docs/specs/` 内未结案的活跃 spec、未 push commits）、`pr-merge-guard`（`gh pr merge` 的 PreToolUse —— PR body 的验收标准章节仍有未勾选清单项时拦截合并）。两个 PostToolUse hook 在 Claude Code / Codex 上完全对齐；Codex 仅对 `pr-ready-guard` 的 PreToolUse `additionalContext` 信息路径 fail-open（block 路径两边一致）。默认通过插件路径安装。 |
 | auriga-notify *(opt-in)* | Claude Code | Claude Code `Notification` 事件的 macOS 原生通知插件。支持焦点感知仅提示音、点击唤起终端、按项目分组通知，并迁移旧 `config.json` / `icon.png`。不随 `install --all` 默认安装，需要显式执行 `install plugins --plugin auriga-notify`。 |
 | session-instructions-loader | Codex | Codex-only SessionStart 插件，注入上层目录的 `AGENTS.md` 和仓库配置的额外 instruction 文件。 |
 

package/dist/catalog.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-16T02:00:33.470Z",
+  "generatedAt": "2026-05-16T10:40:59.234Z",
   "workflowSkills": [
     {
       "name": "planning-with-files",
@@ -55,7 +55,7 @@
   "plugins": [
     {
       "name": "auriga-workflow",
-      "description": "(Claude/Codex) The auriga workflow plugin: workflow skills — incremental-impl (implementation slicing), test-designer (independent test design), spec-design (requirement clarification), arch-design (architecture design), code-simplify (code simplification), session-compound (session compounding), goalify (autonomous /goal planning), deep-review (multi-dimensional PR review orchestrator), reviewer-creator (custom reviewer scaffolding), git-workflow (git lifecycle skill) — plus the git lifecycle hooks that enforce them: commit-reminder, pr-create-guard, pr-ready-guard. Dual-Agent compatible (Claude Code + Codex).",
+      "description": "(Claude/Codex) The auriga workflow plugin: workflow skills — incremental-impl (implementation slicing), test-designer (independent test design), spec-design (requirement clarification), arch-design (architecture design), code-simplify (code simplification), session-compound (session compounding), goalify (autonomous /goal planning), deep-review (multi-dimensional PR review orchestrator), reviewer-creator (custom reviewer scaffolding), git-workflow (git lifecycle skill) — plus the git lifecycle hooks that enforce them: commit-reminder, pr-create-guard, pr-ready-guard, pr-merge-guard. Dual-Agent compatible (Claude Code + Codex).",
       "agents": [
         "claude",
         "codex"
@@ -78,9 +78,19 @@
     },
     {
       "name": "claude-md-management",
-      "description": "Audit and improve CLAUDE.md files",
+      "description": "(Claude/Codex) Audit and improve CLAUDE.md files",
       "agents": [
-        "claude"
+        "claude",
+        "codex"
+      ],
+      "external": true
+    },
+    {
+      "name": "playground",
+      "description": "(Claude/Codex) Build interactive HTML playgrounds",
+      "agents": [
+        "claude",
+        "codex"
       ],
       "external": true
     },

package/dist/state.js

@@ -24,6 +24,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parse as parseToml } from "smol-toml";
+import { hasAurigaHeader, parseMarkers } from "./workflow-markers.js";
 /**
  * Shorten an absolute path by replacing the user's $HOME with `~`. Avoids
  * leaking the full username in screenshots and keeps the TopBar label
@@ -147,7 +148,6 @@ function aggregateStatus(records) {
 // ---------------------------------------------------------------------------
 // Workflow
 // ---------------------------------------------------------------------------
-const WORKFLOW_HEADER_RE = /^#\s+auriga\s+Workflow\s*\(v\d+\.\d+\.\d+\)/;
 function workflowPathsForScope(scope, projectRoot, home) {
     if (scope === "user") {
         return [path.join(home, ".claude", "CLAUDE.md")];
@@ -174,23 +174,22 @@ function scanWorkflow(scope, projectRoot, home, warnings) {
     if (content === null) {
         return { status: "not-installed", observedScope: scope };
     }
-    // Walk the first non-blank lines looking for the auriga header. We only
-    // need to know "is this our CLAUDE.md or foreign" — the actual version
-    // string is unused since v1.19.0 dropped update-available status.
-    for (const line of content.split(/\r?\n/)) {
-        if (WORKFLOW_HEADER_RE.test(line)) {
-            return { status: "installed", observedScope: scope };
-        }
-        if (line.trim().length > 0)
-            break;
-    }
-    // CLAUDE.md exists but no recognizable auriga marker. The file is foreign
-    // — not our workflow. Report `not-installed` honestly; the install path
-    // (src/workflow.ts) protects user content by backing it up to
-    // `CLAUDE.md.bak` (backup-once: never clobbers a prior .bak).
+    // "Is this our CLAUDE.md?" — two recognizable shapes:
+    //   - managed-block markers (the current install format). The START marker
+    //     is an HTML comment ahead of the auriga header, so a first-non-blank-
+    //     line header walk would miss it — detect the marker pair directly.
+    //   - an auriga workflow header with no markers (a pre-marker install).
+    //     Still ours; the next install migrates it to the marked format.
+    if (parseMarkers(content).kind === "marked" || hasAurigaHeader(content)) {
+        return { status: "installed", observedScope: scope };
+    }
+    // CLAUDE.md exists but is neither marked nor auriga-headed. The file is
+    // foreign — not our workflow. Report `not-installed` honestly; the install
+    // path (src/workflow.ts) keeps the foreign content as the user region
+    // below a fresh managed block, so nothing is lost.
     warnings.push({
         code: "workflow-foreign-claudemd",
-        message: `Foreign CLAUDE.md detected at the workflow path — no auriga-workflow header. Install will back up to CLAUDE.md.bak.`,
+        message: `Foreign CLAUDE.md detected at the workflow path — no auriga-workflow header. Install will keep your content as the user region below the managed block.`,
     });
     return { status: "not-installed", observedScope: scope };
 }

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 a CLAUDE.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 CLAUDE.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 CLAUDE.md 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 CLAUDE.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 CLAUDE.md while still
+// receiving workflow upgrades.
+//
+// Markers are HTML comments so both Claude Code and Codex (which read the same
+// file via the AGENTS.md → CLAUDE.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 `CLAUDE.md` gets the English marker; `CLAUDE.zh-CN.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 a CLAUDE.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 CLAUDE.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 CLAUDE.md 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.js

@@ -2,6 +2,36 @@ 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 { composeMarkedFile, hasAurigaHeader, hashBlock, parseMarkers, } from "./workflow-markers.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 file (CLAUDE.md)
+ * 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;
+}
 export async function installWorkflow(packageRoot, opts) {
     const lang = opts.interactive
         ? await withEsc(select({
@@ -34,49 +64,100 @@ export async function installWorkflow(packageRoot, opts) {
     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)}`);
+    // 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(sourceClaude, "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 : "";
+    // 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 (!fs.existsSync(targetClaude)) {
+        // 1. Fresh install — write the marked template as-is, no backup.
+        fs.writeFileSync(targetClaude, composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
+        log.ok(`CLAUDE.md installed (${langOpt.label})`);
+    }
+    else {
+        const current = fs.readFileSync(targetClaude, "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(targetClaude);
+                log.warn(`CLAUDE.md 的受管区块缺少校验标记,无法确认是否被改动;升级前已备份到 ${path.basename(bak)}`);
             }
-            else {
-                fs.copyFileSync(targetClaude, bakPath);
-                log.warn(`Existing CLAUDE.md backed up to CLAUDE.md.bak`);
+            else if (parsed.endHash !== hashBlock(parsed.blockBody)) {
+                const bak = backupOnce(targetClaude);
+                log.warn(`CLAUDE.md 的受管区块曾被手改;升级已整块覆盖该区块,改动前的文件见 ${path.basename(bak)}`);
             }
+            fs.writeFileSync(targetClaude, composeMarkedFile({
+                prefix: parsed.prefix,
+                blockBody: sourceBlock,
+                userRegion: parsed.userRegion,
+                lang,
+            }));
+            log.ok(`CLAUDE.md upgraded (${langOpt.label}); your project section was preserved`);
+        }
+        else if (parsed.kind === "unmarked" && hasAurigaHeader(current)) {
+            // 3. Old-format migration — an auriga CLAUDE.md 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(targetClaude);
+            fs.writeFileSync(targetClaude, composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
+            log.warn(`检测到旧版 CLAUDE.md(无受管标记);已备份到 ${path.basename(bak)}。` +
+                `若你改过它,请从备份把工程定制手动迁移到 END 标记之后的用户区。`);
+            log.ok(`CLAUDE.md migrated to the managed-block format (${langOpt.label})`);
+        }
+        else if (parsed.kind === "unmarked") {
+            // 4. Foreign first install — a CLAUDE.md from another tool. Keep its
+            //    content in place as the user region; no backup needed.
+            const foreign = current.endsWith("\n") ? current : current + "\n";
+            fs.writeFileSync(targetClaude, composeMarkedFile({ blockBody: sourceBlock, userRegion: "\n" + foreign, lang }));
+            log.ok(`CLAUDE.md installed (${langOpt.label}); your existing 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(targetClaude);
+            fs.writeFileSync(targetClaude, composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
+            log.warn(`CLAUDE.md 的受管标记已损坏(${parsed.reason});已备份到 ${path.basename(bak)} 并重装。`);
         }
     }
-    fs.copyFileSync(sourceClaude, targetClaude);
-    log.ok(`CLAUDE.md copied (${langOpt.label})`);
-    // Create AGENTS.md symlink
+    // Point AGENTS.md at CLAUDE.md via a symlink (the install shape — Claude
+    // Code and Codex then read the same workflow doc). If the path is already
+    // occupied by something that ISN'T that symlink — a real file from another
+    // tool, or a symlink pointing elsewhere — it holds content or intent we
+    // must not silently destroy. Back it up first (symmetric with how a foreign
+    // / hand-edited CLAUDE.md is preserved above), then replace.
+    let agentsStat;
     try {
-        fs.lstatSync(targetAgents);
-        fs.unlinkSync(targetAgents);
+        agentsStat = fs.lstatSync(targetAgents);
     }
     catch {
-        // does not exist, proceed
+        // does not exist — nothing to preserve.
+    }
+    if (agentsStat) {
+        const pointsToClaude = agentsStat.isSymbolicLink() &&
+            fs.readlinkSync(targetAgents) === "CLAUDE.md";
+        if (!pointsToClaude) {
+            const bak = backupOnce(targetAgents);
+            log.warn(`AGENTS.md 不是指向 CLAUDE.md 的软链;已备份到 ${path.basename(bak)} 后替换为软链。`);
+        }
+        fs.unlinkSync(targetAgents);
     }
     fs.symlinkSync("CLAUDE.md", targetAgents);
     log.ok("AGENTS.md -> CLAUDE.md symlink created");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auriga-cli",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins)",
   "license": "MIT",
   "repository": {
@@ -25,14 +25,14 @@
     "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",
     "test:web-ui-e2e": "tsc -p tsconfig.test.json && node --test dist-test/tests/web-ui-e2e.test.js",
     "test:session-instructions-loader": "node tests/session-instructions-loader.test.mjs",
-    "test:git-guards": "node tests/commit-reminder.test.mjs && node tests/pr-create-guard.test.mjs && node tests/pr-ready-guard.test.mjs"
+    "test:git-guards": "node tests/commit-reminder.test.mjs && node tests/pr-create-guard.test.mjs && node tests/pr-ready-guard.test.mjs && node tests/pr-merge-guard.test.mjs"
   },
   "engines": {
     "node": ">=18"