From 560454fdaddb1d8021335d9117255e1062ccd301 Mon Sep 17 00:00:00 2001 From: whitelonng Date: Sun, 19 Jul 2026 23:31:23 +0800 Subject: [PATCH 1/9] fix: complete V3 beta release surface --- .github/workflows/quality.yml | 27 ++++++ README.en.md | 43 ++++++--- README.md | 42 +++++--- package.json | 4 +- src/commands/status.ts | 13 ++- src/commands/uninstall.ts | 2 +- src/commands/workflow.ts | 150 ++++++++++++++++++++++++++++- src/context/store.ts | 51 ++++++---- tests/v3-adapter-contracts.test.ts | 13 +++ tests/v3-command-contracts.test.ts | 63 ++++++++++++ tests/version.test.ts | 5 +- tests/website-docs.test.ts | 42 ++++---- website/docs.html | 125 ++++++++++-------------- website/docs.zh-CN.html | 125 ++++++++++-------------- website/index.html | 12 +-- website/index.zh-CN.html | 12 +-- 16 files changed, 498 insertions(+), 231 deletions(-) create mode 100644 .github/workflows/quality.yml diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml new file mode 100644 index 0000000..a8ba87f --- /dev/null +++ b/.github/workflows/quality.yml @@ -0,0 +1,27 @@ +name: Quality gate + +on: + push: + pull_request: + +permissions: + contents: read + +jobs: + quality: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + - run: npm ci + - name: Lint + run: npm run lint + - name: Typecheck + run: npm run typecheck + - name: Build + run: npm run build + - name: Test + run: npm test diff --git a/README.en.md b/README.en.md index c9bbe39..58479a4 100644 --- a/README.en.md +++ b/README.en.md @@ -17,7 +17,7 @@

License: AGPL-3.0 npm version - Status: stable v0.3.13 + Status: V3 beta v0.3.13 Platforms: Claude Code, Cursor, Codex in ChatGPT desktop and CLI, GitHub Copilot, ZCode

@@ -177,7 +177,7 @@ the original mode entries, never task/session snapshots. `mancode init default `solo` for lightweight implementation, or continue the full `/man` validation and bounded risk-review workflow. - **Keep workflow artifacts on disk**: save research, plans, review reports, - and summaries under `.mancode/local/workflows//`. + and summaries under `.mancode//workflows//`. - **Support team context**: use `/manteam` with confirmed typed entities under `.mancode/shared/`. - **Scan project health**: use `mancode manps` to detect stale TODOs, unused @@ -263,7 +263,7 @@ Context Pack: work. A planning or research request made from default `solo` routes into `/man`. It inspects the project, asks only questions that can change scope, architecture, cost, or acceptance, and recommends 2–3 options when a decision benefits from -guidance. It writes the plan under `.mancode/local/workflows//` only +guidance. It writes the plan under `.mancode/local/workflows//` only after the requirements are ready. Finishing the plan does not automatically start the full workflow. At the plan @@ -350,9 +350,9 @@ it should behave, and why previous decisions were made. ## Installation -**Status**: stable v0.3.13. Claude Code, Cursor, Codex in the ChatGPT desktop app -and CLI, and GitHub Copilot are supported. ZCode adapter support is included, -with project skill discovery kept behind a verification gate before release. +**Status**: V3 beta v0.3.13. Claude Code, Cursor, Codex in the ChatGPT desktop +app and CLI, GitHub Copilot, and ZCode adapters are included. Stable release +still requires the five-host real-session acceptance and the `context beta` B1 gate. Requires Node.js 20 or newer. macOS, Linux, Windows CMD, PowerShell, and Git Bash are supported. Git is optional: without it, initialization continues with solo @@ -426,6 +426,8 @@ mancode list-platforms mancode team identity create --name "" mancode context session new --client mancode workflow create "" --session +mancode workflow list --json +mancode workflow show --json mancode context resume --session mancode workflow requirements finalize --file --expected-revision --session mancode workflow plan revise --file --expected-revision --session @@ -507,9 +509,11 @@ mancode context session new --client codex mancode workflow create man "refactor auth module" --session mancode workflow requirements finalize --file requirements.json --expected-revision --session mancode workflow plan revise --file plan.md --expected-revision --session +mancode workflow plan confirm --plan-decision --expected-revision --session mancode workflow review apply --file review-ledger.json --expected-revision --session mancode workflow verify apply --file verification-ledger.json --expected-revision --session mancode workflow complete --expected-revision --session +mancode context compact --dry-run ``` ### `mancode manps` @@ -635,23 +639,34 @@ Ensure the `.cursor/rules/mancode-*.mdc` files exist. Rules with Mode-specific rules (manba, man, manteam, manps) trigger based on the description field — invoke them by asking for `/manba` or similar. -### How to do a clean reinstall +### How to reinstall V3 adapters ```bash -mancode uninstall --all --force -mancode init -mancode install +mancode uninstall claude-code --force +mancode uninstall cursor --force +mancode uninstall codex --force +mancode uninstall copilot --force +mancode uninstall zcode --force +mancode install claude-code +mancode install cursor +mancode install codex +mancode install copilot +mancode install zcode ``` -### How to completely remove mancode +V3 authority is protected, so `mancode uninstall --all` does not delete workflow +authority. To inspect removable runtime records, run +`mancode context compact --dry-run` first. + +### How to remove the CLI ```bash -mancode uninstall --all --force npm uninstall -g mancode ``` -This removes `.mancode/`, platform config files, and mancode hooks from -`.claude/settings.json`. User-authored rules and instructions are preserved. +Uninstalling each platform removes its mancode bootstrap while preserving +user-authored rules, instructions, and V3 workflow data. The `--all` form is only +supported for projects explicitly initialized with `mancode init --legacy`. ## FAQ diff --git a/README.md b/README.md index 4a2d310..d73f72e 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@

许可证：AGPL-3.0 npm 版本 - 状态：稳定版 v0.3.13 + 状态：V3 Beta v0.3.13 平台：Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI、GitHub Copilot、ZCode

@@ -155,7 +155,7 @@ AGENTS.md # Codex（ChatGPT 桌面端/CLI）：托管 ins - **在存在 UI 时匹配现有设计系统**：检查项目 UI 依赖、Tailwind 配置、CSS 变量和已有组件，让 agent 复用现有颜色、字体和交互模式。 - **先把需求和计划对齐**：`/man` 会调研项目、引导澄清会改变方案的需求、推荐可行选项并生成可确认的持久计划；计划完成后不会自动进入完整实施。 - **自由选择执行强度**：计划确认后，可只保留计划、交给默认 `solo` 轻量开发，或继续完整 `/man` 的验证与有界风险审查。 -- **保留工作流产物**：调研、计划、审查报告和总结会保存到 `.mancode/local/workflows//`。 +- **保留工作流产物**：调研、计划、审查报告和总结会保存到 `.mancode//workflows//`。 - **支持团队上下文**：`/manteam` 通过 `.mancode/shared/` 的类型化实体共享已确认信息。 - **扫描项目健康度**：`mancode manps` 检测陈旧 TODO、未使用依赖、风险依赖和硬编码设计值。 @@ -228,7 +228,7 @@ mancode 不把“当前模式”写进持久状态。需要某种工作方式时 `solo`，当用户要求先调研、给方案或出计划时，也会进入 `/man`。它会先了解项目， 只追问会改变范围、架构、成本或验收的问题；适合由系统推荐的决策会给出 2–3 个 方案、优缺点和明确建议。需求足够清楚后，计划才会写入 -`.mancode/local/workflows//plan.md`。 +`.mancode/local/workflows//plan.md`。 计划完成不会自动开始完整开发。用户在计划关卡选择：交给 `solo` 按已确认计划 轻量开发、继续完整 `/man`、只保留计划，或修改计划。只有选择完整 `/man` 才继续 @@ -305,9 +305,9 @@ src/components/ ## 安装 -**状态**：稳定版 v0.3.13。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、 -Codex CLI 和 GitHub Copilot 均已支持。ZCode adapter 已接入，但项目级 skill -发现路径在发布前仍作为验证门禁。 +**状态**：V3 Beta v0.3.13。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、 +Codex CLI 和 GitHub Copilot 均已接入；ZCode adapter 已接入。正式稳定发布仍需 +完成五平台真实宿主验收和 `context beta` B1 门禁。 需要 Node.js 20 或更高版本。原生支持 macOS、Linux、Windows CMD、 PowerShell 和 Git Bash。Git 是可选依赖：未安装时仍可初始化，只会把团队 @@ -379,6 +379,8 @@ mancode list-platforms mancode team identity create --name "" mancode context session new --client mancode workflow create "" --session +mancode workflow list --json +mancode workflow show --json mancode context resume --session mancode workflow requirements finalize --file --expected-revision --session mancode workflow plan revise --file --expected-revision --session @@ -458,9 +460,11 @@ mancode context session new --client codex mancode workflow create man "refactor auth module" --session mancode workflow requirements finalize --file requirements.json --expected-revision --session mancode workflow plan revise --file plan.md --expected-revision --session +mancode workflow plan confirm --plan-decision --expected-revision --session mancode workflow review apply --file review-ledger.json --expected-revision --session mancode workflow verify apply --file verification-ledger.json --expected-revision --session mancode workflow complete --expected-revision --session +mancode context compact --dry-run ``` ### `mancode manps` @@ -575,23 +579,33 @@ mancode/ （context、practice、solo）在每次对话加载。模式规则（manba、man、manteam、 manps）按 description 触发——输入 `/manba` 等关键词即可激活。 -### 如何完全重装 +### 如何重装 V3 适配器 ```bash -mancode uninstall --all --force -mancode init -mancode install +mancode uninstall claude-code --force +mancode uninstall cursor --force +mancode uninstall codex --force +mancode uninstall copilot --force +mancode uninstall zcode --force +mancode install claude-code +mancode install cursor +mancode install codex +mancode install copilot +mancode install zcode ``` -### 如何完全卸载 mancode +V3 authority 受保护，`mancode uninstall --all` 不会删除工作流权威数据。需要 +清理运行时保留记录时，先用 `mancode context compact --dry-run` 检查候选。 + +### 如何移除 CLI ```bash -mancode uninstall --all --force npm uninstall -g mancode ``` -这会移除 `.mancode/`、平台配置文件和 `.claude/settings.json` 中的 mancode -hooks。用户自定义的 rules 和 instructions 会被保留。 +逐个平台卸载会移除对应的 mancode bootstrap，并保留用户自定义 rules、instructions +和 V3 工作流数据。旧项目若明确使用 `mancode init --legacy`，才支持 legacy 的 +`mancode uninstall --all --force`。 ## 常见问题 diff --git a/package.json b/package.json index bd86b8d..fd6e224 100644 --- a/package.json +++ b/package.json @@ -4,8 +4,8 @@ "description": "AI coding agent workflow harness. Five modes from practice to playoffs: stop over-engineering, reuse project context, and add multi-agent code review.", "type": "module", "license": "AGPL-3.0-only", - "author": "", - "homepage": "https://github.com/whitelonng/mancode", + "author": "whitelonng", + "homepage": "https://whitelonng.github.io/mancode/", "repository": { "type": "git", "url": "git+https://github.com/whitelonng/mancode.git" diff --git a/src/commands/status.ts b/src/commands/status.ts index 73700d3..a1cc529 100644 --- a/src/commands/status.ts +++ b/src/commands/status.ts @@ -872,8 +872,19 @@ function printV3Text(result: V3StatusResult): void { console.log( `Identity: ${result.localIdentity.displayName ?? 'not configured'}`, ); + const sessionEvidenceDetail = result.sessionEvidence.ready + ? 'ready' + : [ + ...result.sessionEvidence.explicitRequiredPlatforms, + ...result.sessionEvidence.missingPlatforms.filter( + (platform) => + !result.sessionEvidence.explicitRequiredPlatforms.includes( + platform, + ), + ), + ].join(', ') || 'none recorded'; console.log( - `Session evidence: ${result.sessionEvidence.ready ? 'ready' : `explicit required (${result.sessionEvidence.explicitRequiredPlatforms.join(', ')})`}`, + `Session evidence: ${result.sessionEvidence.ready ? 'ready' : `explicit required (${sessionEvidenceDetail})`}`, ); if (result.compatibility.failures.length > 0) { console.log(`Compatibility: ${result.compatibility.failures.join(', ')}`); diff --git a/src/commands/uninstall.ts b/src/commands/uninstall.ts index 323e04f..4fa4a97 100644 --- a/src/commands/uninstall.ts +++ b/src/commands/uninstall.ts @@ -104,7 +104,7 @@ async function uninstallV3( if (!platform || options.all) { console.error('✗ mancode authority is protected from bulk uninstall.'); console.error( - ' Remove a single bootstrap with `mancode uninstall `, or complete an explicit mancode archive/migration workflow first.', + ' Remove a single bootstrap with `mancode uninstall `. Inspect runtime retention with `mancode context compact --dry-run`; V3 workflow authority is not bulk-deleted.', ); return EXIT_V3_AUTHORITY_PROTECTED; } diff --git a/src/commands/workflow.ts b/src/commands/workflow.ts index 3200865..e98762b 100644 --- a/src/commands/workflow.ts +++ b/src/commands/workflow.ts @@ -16,9 +16,10 @@ import { startV3SoloHandoff, } from '../context/solo-handoff.js'; import { completeV3Task } from '../context/task-complete.js'; -import { parseTaskRef } from '../context/task-ref.js'; +import { formatTaskRef, parseTaskRef } from '../context/task-ref.js'; import { recordV3Verification } from '../context/verification-record.js'; import { createV3Workflow } from '../context/workflow-create.js'; +import type { WorkflowMetadataV3 } from '../context/workflow-metadata.js'; import { updateV3Workflow } from '../context/workflow-update.js'; import { detectTeamAssessmentSignals } from '../system/detect-team.js'; import { @@ -216,6 +217,15 @@ async function workflowV3( args: string[], options: WorkflowOptions, ): Promise { + if (subcommand === 'list') { + return workflowListV3(rootDir, args, options); + } + if (subcommand === 'show') { + return workflowShowV3(rootDir, args, options); + } + if (subcommand === 'clean') { + return workflowCleanV3(options); + } if (subcommand === 'create') { return workflowCreateV3(rootDir, args, options); } @@ -256,6 +266,144 @@ async function workflowV3( ); } +async function workflowListV3( + rootDir: string, + args: string[], + options: WorkflowOptions, +): Promise { + if (args.length !== 0) { + return printV3Error( + options.json, + 'MANCODE_WORKFLOW_LIST_ARGUMENT_INVALID', + 'Use: workflow list [--json].', + EXIT_INVALID_ARG, + ); + } + try { + const project = await readV3CommandProject(rootDir); + const workflows = await project.store.listWorkflowMetadata(); + if (options.json) { + return printV3Result(true, { + schemaVersion: 1, + workflows, + }); + } + if (workflows.length === 0) { + console.log('No mancode workflows.'); + return EXIT_OK; + } + const active = workflows.filter((item) => + ['in_progress', 'planned', 'blocked'].includes(item.status), + ).length; + console.log( + `mancode workflows (${workflows.length} total, ${active} active)`, + ); + console.log(''); + for (const metadata of workflows) { + console.log(formatV3WorkflowRow(metadata)); + } + return EXIT_OK; + } catch (error) { + return printV3Error( + options.json, + v3ErrorCode(error, 'MANCODE_V3_WORKFLOW_LIST_FAILED'), + error instanceof Error + ? error.message + : 'Unable to list mancode workflows.', + ); + } +} + +async function workflowShowV3( + rootDir: string, + args: string[], + options: WorkflowOptions, +): Promise { + const requested = args[0]; + if (!requested || args.length !== 1) { + return printV3Error( + options.json, + 'MANCODE_WORKFLOW_SHOW_ARGUMENT_INVALID', + 'Use: workflow show [--json].', + EXIT_INVALID_ARG, + ); + } + try { + const project = await readV3CommandProject(rootDir); + const location = await project.store.locateTask(requested); + const [snapshot, activeChildren] = await Promise.all([ + project.store.readTaskSnapshot(location.taskRef), + project.store.listActiveChildTaskRefs(location.taskRef), + ]); + const result = { + schemaVersion: 1, + taskRef: location.taskRef, + metadata: snapshot.metadata, + aggregate: snapshot.aggregate, + aggregateError: snapshot.aggregateError, + activeChildren, + }; + if (options.json) return printV3Result(true, result); + + const metadata = snapshot.metadata; + console.log(`Workflow: ${formatTaskRef(metadata.taskRef)}`); + console.log(`Task: ${metadata.task}`); + console.log(`Mode: ${metadata.workflowMode}`); + console.log(`Status: ${metadata.status}`); + console.log( + `Current step: ${metadata.currentStep}/${maxV3WorkflowStep(metadata.workflowMode)}`, + ); + console.log(`Revision: ${metadata.revision}`); + console.log(`Visibility: ${metadata.visibility}`); + console.log(`Coordination: ${metadata.coordination}`); + console.log(`Updated: ${metadata.updatedAt}`); + if (metadata.blockingReason !== null) { + console.log(`Blocked: ${metadata.blockingReason}`); + } + if (activeChildren.length > 0) { + console.log( + `Children: ${activeChildren.map(formatTaskRef).join(', ')}`, + ); + } + if (snapshot.aggregateError !== null) { + console.log(`Aggregate: ${snapshot.aggregateError}`); + } + return EXIT_OK; + } catch (error) { + return printV3Error( + options.json, + v3ErrorCode(error, 'MANCODE_V3_WORKFLOW_SHOW_FAILED'), + error instanceof Error + ? error.message + : 'Unable to show the mancode workflow.', + ); + } +} + +function workflowCleanV3(options: WorkflowOptions): number { + return printV3Error( + options.json, + 'MANCODE_V3_WORKFLOW_CLEAN_UNSUPPORTED', + 'V3 workflow authority is durable and is not deleted by workflow clean. Use `mancode context compact --dry-run` to inspect eligible runtime retention records.', + EXIT_INVALID_ARG, + ); +} + +function formatV3WorkflowRow(metadata: WorkflowMetadataV3): string { + return [ + formatTaskRef(metadata.taskRef), + metadata.workflowMode, + metadata.status, + `Step ${metadata.currentStep}/${maxV3WorkflowStep(metadata.workflowMode)}`, + `r${metadata.revision}`, + metadata.task, + ].join(' '); +} + +function maxV3WorkflowStep(mode: WorkflowMetadataV3['workflowMode']): number { + return mode === 'manba' ? 5 : 9; +} + async function workflowUpdateV3( rootDir: string, args: string[], diff --git a/src/context/store.ts b/src/context/store.ts index b490ac6..b4a1531 100644 --- a/src/context/store.ts +++ b/src/context/store.ts @@ -336,14 +336,9 @@ export class V3ContextStore { }; } - /** - * Lists non-terminal children from canonical metadata only. Callers that - * need a completion gate must hold the parent task lock while invoking it; - * V3 child creation takes that same parent lock before publishing. - */ - async listActiveChildTaskRefs(parentTaskRef: TaskRef): Promise { - const parent = parseTaskRefValue(parentTaskRef); - const children: TaskRef[] = []; + /** Lists every canonical V3 workflow without relying on a session pointer. */ + async listWorkflowMetadata(): Promise { + const workflows: WorkflowMetadataV3[] = []; for (const namespace of ['local', 'shared'] as const) { const directory = path.join('.mancode', namespace, 'workflows'); const entries = await readDirectoryEntriesWithin( @@ -352,7 +347,7 @@ export class V3ContextStore { ); for (const taskId of entries.sort(compareUtf8)) { try { - assertUlid(taskId, 'workflow child directory'); + assertUlid(taskId, 'workflow directory'); } catch { throw new Error('MANCODE_CONTEXT_COLLECTION_ENTRY_INVALID'); } @@ -367,22 +362,42 @@ export class V3ContextStore { 'metadata.json', parseWorkflowMetadata, ); - if ( - metadata.parent !== null && - sameTaskRef(metadata.parent.taskRef, parent) && - !isTerminalWorkflowStatus(metadata.status) - ) { - children.push(metadata.taskRef); + if (!sameTaskRef(metadata.taskRef, taskRef)) { + throw new Error('MANCODE_CONTEXT_TASK_LOCATION_MISMATCH'); } + workflows.push(metadata); } } - return children.sort( + return workflows.sort( (left, right) => - compareUtf8(left.namespace, right.namespace) || - compareUtf8(left.taskId, right.taskId), + Date.parse(right.updatedAt) - Date.parse(left.updatedAt) || + compareUtf8(left.taskRef.namespace, right.taskRef.namespace) || + compareUtf8(left.taskRef.taskId, right.taskRef.taskId), ); } + /** + * Lists non-terminal children from canonical metadata only. Callers that + * need a completion gate must hold the parent task lock while invoking it; + * V3 child creation takes that same parent lock before publishing. + */ + async listActiveChildTaskRefs(parentTaskRef: TaskRef): Promise { + const parent = parseTaskRefValue(parentTaskRef); + return (await this.listWorkflowMetadata()) + .filter( + (metadata) => + metadata.parent !== null && + sameTaskRef(metadata.parent.taskRef, parent) && + !isTerminalWorkflowStatus(metadata.status), + ) + .map((metadata) => metadata.taskRef) + .sort( + (left, right) => + compareUtf8(left.namespace, right.namespace) || + compareUtf8(left.taskId, right.taskId), + ); + } + private mancodeRoot(): string { return path.join(this.projectRoot, '.mancode'); } diff --git a/tests/v3-adapter-contracts.test.ts b/tests/v3-adapter-contracts.test.ts index bc052b3..0cbc025 100644 --- a/tests/v3-adapter-contracts.test.ts +++ b/tests/v3-adapter-contracts.test.ts @@ -73,6 +73,13 @@ describe('V3 adapter bootstrap integration', () => { }); expect(result.activation.managedAdapters.codex).toBe('3'); + logs.mockClear(); + expect(await status(root, {})).toBe(0); + const textOutput = logs.mock.calls.flat().join('\n'); + expect(textOutput).toContain('Session evidence: explicit required'); + expect(textOutput).toContain('codex'); + expect(textOutput).not.toContain('explicit required ()'); + expect(await install(root, 'cursor')).toBe(0); const cursorRule = await readFile( path.join(root, '.cursor', 'rules', 'mancode-v3.mdc'), @@ -578,6 +585,12 @@ describe('V3 adapter bootstrap integration', () => { expect(await uninstall(root, undefined, { all: true })).toBe( EXIT_V3_AUTHORITY_PROTECTED, ); + expect(errors.mock.calls.flat().join('\n')).toContain( + 'context compact --dry-run', + ); + expect(errors.mock.calls.flat().join('\n')).not.toContain( + 'archive/migration workflow', + ); } finally { logs.mockRestore(); errors.mockRestore(); diff --git a/tests/v3-command-contracts.test.ts b/tests/v3-command-contracts.test.ts index 3e617f3..f02d093 100644 --- a/tests/v3-command-contracts.test.ts +++ b/tests/v3-command-contracts.test.ts @@ -33,6 +33,7 @@ import { requirementsLedgerDigest, } from '../src/context/requirements-ledger.js'; import { V3ContextStore } from '../src/context/store.js'; +import type { TaskRef } from '../src/context/task-ref.js'; import { readSession } from '../src/runtime/session.js'; import { readLocalActor } from '../src/team/actor.js'; @@ -197,6 +198,68 @@ describe('V3 CLI command contracts', () => { } }); + it('lists and shows V3 workflows without deleting durable authority', async () => { + const logs = vi.spyOn(console, 'log').mockImplementation(() => {}); + const errors = vi.spyOn(console, 'error').mockImplementation(() => {}); + try { + expect(await workflow(root, 'list', [], { json: true })).toBe(0); + expect(JSON.parse(String(logs.mock.calls.at(-1)?.[0]))).toMatchObject({ + schemaVersion: 1, + workflows: [], + }); + + await teamIdentityCreate(root, { name: 'Fixture User', json: true }); + await contextSessionNew(root, { client: 'fixture', json: true }); + const sessionId = ( + JSON.parse(String(logs.mock.calls.at(-1)?.[0])) as { + session: { sessionId: string }; + } + ).session.sessionId; + await workflow(root, 'create', ['man', 'Discover this V3 task.'], { + session: sessionId, + client: 'fixture', + json: true, + }); + const created = JSON.parse(String(logs.mock.calls.at(-1)?.[0])) as { + taskRef: { namespace: string; taskId: string }; + }; + const task = `${created.taskRef.namespace}:${created.taskRef.taskId}`; + + expect(await workflow(root, 'list', [], { json: true })).toBe(0); + expect(JSON.parse(String(logs.mock.calls.at(-1)?.[0]))).toMatchObject({ + workflows: [ + { + taskRef: created.taskRef, + workflowMode: 'man', + status: 'in_progress', + }, + ], + }); + expect(await workflow(root, 'show', [task], { json: true })).toBe(0); + expect(JSON.parse(String(logs.mock.calls.at(-1)?.[0]))).toMatchObject({ + taskRef: created.taskRef, + metadata: { + task: 'Discover this V3 task.', + revision: 1, + }, + activeChildren: [], + }); + + expect(await workflow(root, 'clean', [], { json: true })).toBe(2); + expect(JSON.parse(String(logs.mock.calls.at(-1)?.[0]))).toMatchObject({ + error: { code: 'MANCODE_V3_WORKFLOW_CLEAN_UNSUPPORTED' }, + }); + await expect( + new V3ContextStore(root).readTaskSnapshot(created.taskRef as TaskRef), + ).resolves.toMatchObject({ + metadata: { task: 'Discover this V3 task.' }, + }); + } finally { + logs.mockRestore(); + errors.mockRestore(); + } + }); + it('reports an empty local coordination view and rejects local conflict queries', async () => { const logs = vi.spyOn(console, 'log').mockImplementation(() => {}); const errors = vi.spyOn(console, 'error').mockImplementation(() => {}); diff --git a/tests/version.test.ts b/tests/version.test.ts index 245cd89..a2e1ae4 100644 --- a/tests/version.test.ts +++ b/tests/version.test.ts @@ -8,7 +8,7 @@ describe('version', () => { expect(VERSION).toMatch(/^\d+\.\d+\.\d+/); }); - it('is a stable release without prerelease tag', () => { + it('keeps the npm version consumable without a prerelease tag', () => { expect(VERSION).not.toMatch(/-(alpha|beta|rc)\./); }); @@ -21,7 +21,8 @@ describe('version', () => { for (const readme of readmes) { expect(readme).toContain(`v${VERSION}`); - expect(readme).toContain(`status-stable%20v${VERSION}`); + expect(readme).toContain(`status-V3%20beta%20v${VERSION}`); + expect(readme).not.toContain(`status-stable%20v${VERSION}`); } }); }); diff --git a/tests/website-docs.test.ts b/tests/website-docs.test.ts index dc8c590..61ccc49 100644 --- a/tests/website-docs.test.ts +++ b/tests/website-docs.test.ts @@ -47,8 +47,8 @@ describe('website documentation', () => { 'refresh-project', 'manps [area]', '--remediate', - 'require-manual', - 'confirm-manual', + 'workflow verify', + 'workflow review', 'governed_execution', 'plan_only', 'blockingUnknowns', @@ -71,13 +71,13 @@ describe('website documentation', () => { ); }); - it('shows workflow commands in a legal governed order', async () => { + it('shows the V3 workflow command contract', async () => { for (const name of ['docs.html', 'docs.zh-CN.html']) { const html = await readPage(name); const start = html.indexOf( name === 'docs.html' - ? '

A valid governed sequence

' - : '

一条合法的治理式执行顺序

', + ? '

A valid V3 sequence

' + : '

一条合法的 V3 顺序

', ); const end = html.indexOf( name === 'docs.html' @@ -87,20 +87,15 @@ describe('website documentation', () => { ); const example = html.slice(start, end); const orderedTokens = [ - '--step 2', - 'requirements <taskId> finalize', - '--step 3', - '--step 4', - 'governed_execution', - '--step 5', - '--step 6', - 'verify <taskId> init', - 'verify <taskId> record', - 'review <taskId> init', - '--step 7', - 'review <taskId> complete', - '--step 9', - '--status completed', + 'workflow create man', + 'workflow list --json', + 'workflow show <local:ULID> --json', + 'workflow requirements <local:ULID> finalize', + 'workflow plan <local:ULID> revise', + 'workflow plan <local:ULID> confirm', + 'workflow review <local:ULID> apply', + 'workflow verify <local:ULID> apply', + 'workflow complete <local:ULID>', ]; let previous = -1; @@ -111,7 +106,10 @@ describe('website documentation', () => { ); previous = current; } - expect(example).not.toContain('--step 4 --plan-version 1'); + expect(example).not.toMatch(/workflow update[^\n]*--step/); + expect(example).not.toContain('workflow decide'); + expect(example).not.toContain('verify <taskId>'); + expect(example).not.toContain('review <taskId>'); } }); @@ -147,8 +145,8 @@ describe('website documentation', () => { expect(chinese).toContain('代码，避免'); expect(chinese).toContain('AI 屎山。'); expect(chinese).toContain('预览适配器'); - expect(english).not.toMatch(/\b(?:V3|Beta)\b/); - expect(chinese).not.toMatch(/\b(?:V3|Beta)\b/); + expect(english).toContain('V3 Beta / v0.3.13'); + expect(chinese).toContain('V3 Beta / v0.3.13'); }); it('documents the cross-session boundary in both languages', async () => { diff --git a/website/docs.html b/website/docs.html index 1374eda..40258b5 100644 --- a/website/docs.html +++ b/website/docs.html @@ -98,10 +98,10 @@

Verify the installation

Files & privacy

mancode works locally, scans only the current project, and sends no telemetry. It deliberately does not rewrite your project's .gitignore, so your team—not the installer—decides which generated context belongs in version control.

- - - - + + + +
PathWhat it containsBefore committing
.mancode/config.json
.mancode/state.json		Selected adapters, current mode, and active workflow pointers.Review as project configuration; share only when the team wants the same setup.
.mancode/project-profile.json
style-tokens.json		Detected stack, validation commands, and UI tokens.Inspect for internal project details and decide whether reproducibility justifies sharing.
.mancode/workflows/Requirements, plans, review scope, verification evidence, reports, and summaries.Review carefully. Evidence, logs, screenshots, traces, and browser artifacts may contain sensitive data and are often better ignored or sanitized.
.mancode/memory/Team decisions and durable shared context.Commit only information intentionally written for the team.
.mancode/schema.json
.mancode/shared/
.mancode/local/		V3 authority, project policy, sessions, workflow metadata, and local runtime records. Legacy state.json exists only after explicit --legacy initialization.Review workflow evidence and local records before sharing; raw host session keys are never persisted.
.mancode/shared/context/project.json
.mancode/local/cache/style-tokens.json		Detected stack, validation commands, and local UI tokens.Inspect for internal project details and decide whether reproducibility justifies sharing.
.mancode/local/workflows/
.mancode/shared/workflows/		Requirements, plans, review and verification ledgers, reports, checkpoints, and summaries.Review carefully. Evidence and reports may contain sensitive data; shared workflows pass the V3 privacy boundary.
.mancode/shared/context/decisions/
.mancode/shared/team/		Confirmed decisions and durable coordination authority.Commit only information intentionally written for the team.
.claude/, .cursor/, .agents/, .github/, AGENTS.mdAdapter instructions, commands or prompts, skills, hooks, and managed blocks.Share when the adapter is part of the team's development workflow. Content outside mancode's managed blocks remains yours.
Safety boundary

mancode manps scans and reports by default. Remediation is explicit. Irreversible project operations still require human confirmation; installing mancode does not grant the agent permission to publish, delete, or rewrite unrelated work.

@@ -171,19 +171,19 @@

CLI reference

mancode install [platform]

Adapter

Installs or repairs an adapter after initialization. Omit the platform for interactive selection.

  • --force regenerates managed content.
  • --minimal installs solo-mode essentials only.

mancode status [--json]

Inspect

Reports project facts, current mode and workflow, adapter readiness, and Claude hook registration where applicable.

mancode list-platforms

Discover

Lists adapters known to the installed CLI and marks those already configured in the project.

-

mancode workflow <subcommand>

Govern

Creates and validates requirements, plans, verification evidence, reviews, remediation, and completion. See the detailed lifecycle below.

  • Inspect with list and show <taskId> [--json].
  • Prune old completed records with clean --older-than <duration> [--dry-run].
+

mancode workflow <subcommand>

Govern

Creates and validates V3 requirements, plans, verification evidence, reviews, remediation, and completion.

  • Inspect with list and show <namespace:ULID> [--json].
  • Use context compact --dry-run to inspect removable runtime records; V3 workflow authority is not deleted by workflow clean.

mancode manps [area]

Scan

Runs a deterministic health scan for all, deps, security, dead-code, config.

  • --json emits machine-readable output.
  • --remediate enters the explicit remediation path; the default is scan-only.

mancode refresh-project

Rescan

Refreshes project facts after adding Git, a manifest, a framework, or validation commands, then updates installed static adapters.

mancode refresh-style

Design

Refreshes the project profile and design tokens. Reinstall static adapters with --force afterward.

-

mancode uninstall [platform]

Remove

Removes one adapter, or all mancode project artifacts with --all. Use --force for non-interactive confirmation.

+

mancode uninstall [platform]

Remove

Removes one V3 adapter. V3 protects authority from bulk removal; use context compact --dry-run for retention candidates. The --all form is legacy-only.

mancode version

Version

Prints the installed CLI version for upgrade checks and issue reports.

Study the /man workflow

-

/man is a progressive nine-step protocol. It first makes the decision inspectable, then lets the user choose between a lightweight handoff, a plan-only result, or governed execution. Every gate is backed by files under .mancode/workflows/<taskId>/.

-
Who runs these commands?

The installed man skill creates the task, stores its active pointer in .mancode/state.json, writes artifacts, and calls the CLI. The commands below are the machine contract for studying, debugging, or integrating the process. A standalone workflow create does not activate the task pointer by itself.

+

/man is a progressive nine-step protocol. It first makes the decision inspectable, then lets the user choose between a lightweight handoff, a plan-only result, or governed execution. Every gate is backed by V3 files under .mancode/<namespace>/workflows/<ULID>/.

+
Who runs these commands?

The installed V3 mode entry creates the task and reads its Context Pack. The commands below are the machine contract for studying, debugging, or integrating the process. V3 identifies tasks with explicit namespace:ULID TaskRefs and does not use a legacy active pointer.

The nine steps and their gates

@@ -226,78 +226,61 @@

Requirements ledger

} ] } - 
$ mancode workflow requirements <taskId> finalize --file requirements-input.json
+ 
$ mancode workflow requirements <local:ULID> finalize --file requirements-input.json --expected-revision <revision> --session <session-id>

A successful result says ready. A result of needs_clarification is a hard stop: resolve blockingUnknowns, regenerate the input, and finalize again.

The Step 4 decision

-

Solo handoff

Deliver

Use when the plan is settled but implementation risk is routine.

$ mancode workflow handoff <taskId> --to solo
+            
Solo handoff
Deliver
Use when the plan is settled but implementation risk is routine.
$ mancode workflow handoff <local:ULID> --to solo --expected-revision <revision> --session <session-id>
 # after solo implements and verifies
-$ mancode workflow handoff <taskId> --complete

-            
Governed execution
Continue
Use when implementation, evidence, and independent review should remain inside the nine-step record.
$ mancode workflow decide <taskId> --plan-decision governed_execution

-            
Plan only
Stop
Use when the requested deliverable is the confirmed plan, not code.
$ mancode workflow decide <taskId> --plan-decision plan_only

+$ mancode workflow handoff <local:ULID> --complete --expected-revision <revision> --session <session-id>
+

Governed execution

Continue

Use when implementation, evidence, and independent review should remain inside the nine-step record.

$ mancode workflow plan <local:ULID> confirm --plan-decision governed_execution --expected-revision <revision> --session <session-id>
+

Plan only

Stop

Use when the requested deliverable is the confirmed plan, not code.

$ mancode workflow plan <local:ULID> confirm --plan-decision plan_only --expected-revision <revision> --session <session-id>
-

All three choices require an active in-progress man workflow at Step 4, ready requirements, and plan.md. Revision stays at the plan gate, updates the file, and increments --plan-version from the initial v1 to v2, then v3, and so on.

+

All three choices require an active man workflow, confirmed requirements, and plan.md. Revise the plan with workflow plan ... revise; every successful mutation returns the revision required by the next command.

-

A valid governed sequence

-

This condensed trace shows legal ordering. Comments mark files written by the agent; they are not shell commands. The agent advances each numbered step only after its work and artifact are complete.

- 
# Step 1–2: create, scout, clarify, and freeze requirements
-$ mancode workflow create man "refactor auth module" --json
-# agent stores taskId as the active workflow and writes scout-report.md
-$ mancode workflow update <taskId> --step 2
-$ mancode workflow requirements <taskId> finalize --file requirements-input.json
+          
A valid V3 sequence

+          
V3 uses explicit TaskRefs and expected revisions. The CLI owns every durable mutation; do not edit metadata files or use the legacy --step protocol.

+          
# Bootstrap an actor and explicit session
+$ mancode team identity create --name "Your name"
+$ mancode context session new --client codex --json
 
-# Step 3–4: write plan.md and reach the user decision gate
-$ mancode workflow update <taskId> --step 3
-# agent writes plan.md
-$ mancode workflow update <taskId> --step 4
-$ mancode workflow decide <taskId> --plan-decision governed_execution
+# Create, discover, and inspect a task
+$ mancode workflow create man "refactor auth module" --session <session-id> --json
+$ mancode workflow list --json
+$ mancode workflow show <local:ULID> --json
 
-# Step 5–6: implement, initialize verification, and record every required AC
-$ mancode workflow update <taskId> --step 5
-# agent implements the confirmed plan
-$ mancode workflow update <taskId> --step 6
-$ mancode workflow verify <taskId> init
-$ mancode workflow verify <taskId> record --acceptance AC-LOGIN --method automated --result passed --evidence "auth tests passed" --command "npm test -- auth" --exit-code 0
+# Requirements and plan gates (use the revision returned by each command)
+$ mancode workflow requirements <local:ULID> finalize --file requirements-input.json --expected-revision <revision> --session <session-id>
+$ mancode workflow plan <local:ULID> revise --file plan.md --expected-revision <revision> --session <session-id>
+$ mancode workflow plan <local:ULID> confirm --plan-decision governed_execution --expected-revision <revision> --session <session-id>
 
-# Step 7–9: targeted review, report, summary, completion
-# agent writes review-scope.md
-$ mancode workflow review <taskId> init --review-depth targeted --review-domain quality
-$ mancode workflow update <taskId> --step 7
-# agent writes film-report-1.md
-$ mancode workflow review <taskId> complete --review-domain quality --report film-report-1.md
-$ mancode workflow update <taskId> --step 9
-# agent writes summary.md
-$ mancode workflow update <taskId> --status completed

+# Record canonical review and verification ledgers
+$ mancode workflow review <local:ULID> apply --file review-ledger.json --expected-revision <revision> --session <session-id>
+$ mancode workflow verify <local:ULID> apply --file verification-ledger.json --expected-revision <revision> --session <session-id>
+$ mancode workflow complete <local:ULID> --expected-revision <revision> --session <session-id>

Verification, manual checks, and remediation

StepAgent workDurable gate
- - - - + + + +
CaseRequired recordGate behavior
Automatedrecord with acceptance ID, method, result, evidence, exact command, and exit code. A passing result requires exit code 0; a failure requires non-zero.Step 7 and review stay blocked until every required acceptance criterion passes.
Manualrequire-manual explains why automation cannot decide. Only after the user performs the check may the agent call confirm-manual with observed evidence.The workflow is blocked while confirmation is pending.
Review findingreview complete ... --blockers Q1,Q2 stores stable IDs. Fix once with review remediate --resolved Q1,Q2.Remediation invalidates earlier verification; all required criteria must be re-run and re-recorded at Step 9.
User skips reviewreview skip --reason "explicit user request" at Step 6 after verification.The reason is durable, but summary.md and Step 9 completion are still required.
AutomatedThe canonical verification ledger records the criterion, command, exit code, evidence summary, and result.workflow verify ... apply rejects a ledger that does not satisfy the V3 schema and current revision.
ManualThe ledger records why automation cannot decide and only changes to passed after explicit user confirmation.Completion remains blocked while required manual evidence is pending.
Review findingThe canonical review ledger stores stable blocker IDs and their remediation state.Applying a review ledger makes earlier verification stale; apply current verification after review and before completion.
User skips reviewThe review ledger records the explicit user decision and residual risk.Completion still requires a valid summary and every remaining gate.
- 
# manual acceptance: stop and wait after require-manual
-$ mancode workflow verify <taskId> require-manual --acceptance AC-UI --evidence "foreground browser judgment required"
-# only after explicit user confirmation
-$ mancode workflow verify <taskId> confirm-manual --acceptance AC-UI --evidence "user confirmed the interaction"
-
-# one blocker-remediation round
-$ mancode workflow review <taskId> complete --review-domain quality --report film-report-1.md --blockers Q1
-$ mancode workflow update <taskId> --step 9
-$ mancode workflow review <taskId> remediate --resolved Q1
-$ mancode workflow verify <taskId> record --acceptance AC-LOGIN --method automated --result passed --evidence "post-fix tests passed" --command "npm test -- auth" --exit-code 0
+ 
# Update the canonical ledgers after a remediation
+$ mancode workflow review <local:ULID> apply --file review-ledger.json --expected-revision <revision> --session <session-id>
+$ mancode workflow verify <local:ULID> apply --file verification-ledger.json --expected-revision <revision> --session <session-id>
+$ mancode workflow complete <local:ULID> --expected-revision <revision> --session <session-id>

Workflow subcommands

- - - - - - - - + + + + + + +
CommandPurposeImportant options
createStart a man, manba, or manteam record.--parent-task links a diagnostic child; --json exposes the task ID.
requirementsFinalize the Step 2 ledger from JSON.finalize --file.
updateAdvance step, status, plan version, or durable outcome.--step, --status, --plan-version, --blocking-reason, --outcome. Only clarification may use generic --skipped.
decideResolve the Step 4 plan gate.--plan-decision governed_execution|plan_only.
handoffTransfer a confirmed plan to solo and later close it.--to solo, then --complete.
verifyInitialize and record acceptance evidence.init, record, require-manual, confirm-manual; evidence options include --command, --exit-code, and --evidence-file.
reviewInitialize targeted/full review, store reports and blockers, remediate once, or record an explicit skip.--review-depth, --review-domain, --report, --blockers, --resolved, --reason.
list / show / cleanInspect records or remove old completed records.show --json; clean --older-than 30d --dry-run.
createStart a man, manba, or manteam record.--parent <TaskRef> links a diagnostic child; --json exposes the TaskRef.
requirementsFinalize the structured requirements ledger.finalize --file --expected-revision --session.
planRevise a plan or confirm its execution decision.revise --file; confirm --plan-decision; both require revision and session.
updateChange lifecycle status or a blocking reason.--status --expected-revision --session; governed fields use dedicated commands.
handoffTransfer a confirmed local plan to solo and later close it.--to solo or --complete, with revision and session.
verify / reviewApply canonical V3 ledgers.apply --file --expected-revision --session.
list / show / cleanList or inspect V3 TaskRefs. clean is not a V3 authority deletion command.show <namespace:ULID> --json; use context compact --dry-run for retention.
@@ -324,16 +307,14 @@

Refresh project context

Uninstall safely

-

Uninstall preserves user-authored rules, instructions, and unrelated Claude settings. Review workflow records before deletion if they contain decisions or evidence you still need.

+

Uninstalling one adapter preserves user-authored rules, instructions, unrelated Claude settings, and V3 workflow authority. Use context compact --dry-run to inspect eligible runtime retention records.

Remove one adapter

$ mancode uninstall cursor --force
-

Clean reinstall

- 
$ mancode uninstall --all --force
-$ mancode init
-$ mancode install <platform>
-

Remove mancode completely

- 
$ mancode uninstall --all --force
-$ npm uninstall -g mancode
+

Reinstall one adapter

+ 
$ mancode uninstall claude-code --force
+$ mancode install claude-code
+

Remove the CLI

+ 
$ npm uninstall -g mancode
@@ -347,7 +328,7 @@

Claude Code hooks do not run

Cursor rules do not trigger

Confirm that .cursor/rules/mancode-*.mdc and .cursor/commands/*.md exist. Core context and solo rules are persistent; higher-intensity rules are description-triggered, so invoke the generated mode command explicitly.

A workflow command is rejected

-

Treat the rejection as a gate, not a file-corruption problem. Use mancode workflow show <taskId> --json to inspect the step, requirements readiness, plan decision, verification, review domains, and blockers. Do not edit metadata.json manually.

+

Treat the rejection as a gate, not a file-corruption problem. Use mancode workflow list --json to discover TaskRefs, then mancode workflow show <namespace:ULID> --json to inspect metadata, revision, aggregate, and blockers. Do not edit V3 metadata manually.

Project facts became stale

After adding Git, a manifest, dependencies, or validation scripts, run mancode refresh-project. Use refresh-style for UI tokens. Then repair a static adapter only if its generated files need regeneration.

diff --git a/website/docs.zh-CN.html b/website/docs.zh-CN.html index adf59d2..e6f5aa3 100644 --- a/website/docs.zh-CN.html +++ b/website/docs.zh-CN.html @@ -98,10 +98,10 @@

验证安装结果

文件与隐私

mancode 本地运行，只扫描当前项目，不发送遥测。它不会擅自改写项目的 .gitignore，因此哪些生成上下文应该进入版本控制，需要由你的团队明确决定。

- - - - + + + +
路径包含什么提交前怎么处理
.mancode/config.json
.mancode/state.json		所选平台、当前模式和活动工作流指针。把它当作项目配置检查；只有团队希望共享同一套设置时才提交。
.mancode/project-profile.json
style-tokens.json		识别出的技术栈、验证命令和 UI token。检查是否带有内部项目信息，再权衡复现能力与暴露范围。
.mancode/workflows/需求、计划、评审范围、验证证据、报告与总结。重点检查。日志、截图、trace 和浏览器产物可能含敏感数据，通常应忽略、脱敏或只保留必要摘要。
.mancode/memory/团队决策与长期共享上下文。只提交有意写给团队的内容。
.mancode/schema.json
.mancode/shared/
.mancode/local/		V3 权威、项目策略、会话、工作流元数据和本地运行时记录。只有显式使用 --legacy 初始化后才会出现旧 state.json。共享前检查工作流证据和本地记录；原始宿主 session key 不会持久化。
.mancode/shared/context/project.json
.mancode/local/cache/style-tokens.json		识别出的技术栈、验证命令和本地 UI token。检查是否带有内部项目信息，再权衡复现能力与暴露范围。
.mancode/local/workflows/
.mancode/shared/workflows/		需求、计划、评审和验证台账、报告、checkpoint 与总结。重点检查。证据和报告可能含敏感数据；shared workflow 必须通过 V3 隐私边界。
.mancode/shared/context/decisions/
.mancode/shared/team/		已确认决策与持久化协调权威。只提交有意写给团队的内容。
.claude/、.cursor/、.agents/、.github/、AGENTS.md平台 instructions、命令或 prompt、skills、hooks 与受控区块。团队确实把该适配器作为开发流程的一部分时再共享；mancode 管理标记之外的内容仍归用户所有。
安全边界

mancode manps 默认只扫描和报告，修复必须显式进入 remediation 路径。安装 mancode 也不会赋予 Agent 发布、删除或重写无关工作的权限；不可逆操作仍需人工确认。

@@ -171,19 +171,19 @@

CLI 参考

mancode install [platform]

适配器

初始化后安装或修复一个平台。省略平台名时进入交互选择。

  • --force 重新生成受控内容。
  • --minimal 只安装 solo 的必要内容。

mancode status [--json]

检查

报告项目事实、当前模式和工作流、平台就绪状态，以及适用时的 Claude hook 注册情况。

mancode list-platforms

发现

列出当前 CLI 支持的平台，并标出项目中已经配置的平台。

-

mancode workflow <subcommand>

治理

创建和校验需求、计划、验证证据、评审、修复与完成状态。完整生命周期见下一节。

  • 使用 list 和 show <taskId> [--json] 检查。
  • 使用 clean --older-than <duration> [--dry-run] 清理较早的已完成记录。
+

mancode workflow <subcommand>

治理

创建和校验 V3 需求、计划、验证证据、评审、修复与完成状态。

  • 使用 list 和 show <namespace:ULID> [--json] 检查。
  • 使用 context compact --dry-run 检查可回收的运行时记录；V3 workflow authority 不会被 workflow clean 删除。

mancode manps [area]

扫描

对 all、deps、security、dead-code 或 config 执行确定性健康扫描。

  • --json 输出机器可读结果。
  • --remediate 显式进入修复路径；默认只扫描。

mancode refresh-project

重扫项目

在加入 Git、manifest、框架或验证命令后刷新项目事实，并更新已安装的静态适配器。

mancode refresh-style

设计上下文

刷新项目画像和设计 token，之后可用 --force 重装需要更新的静态适配器。

-

mancode uninstall [platform]

移除

移除一个平台；使用 --all 清理项目内全部 mancode 产物，--force 用于非交互确认。

+

mancode uninstall [platform]

移除

移除一个 V3 适配器。V3 会保护权威数据不被批量删除；用 context compact --dry-run 检查保留候选。--all 只适用于 legacy 项目。

mancode version

版本

输出已安装 CLI 版本，便于升级检查和提交问题。

深入研究 /man 工作流

-

/man 是一个渐进式九步协议：先让决策变得可检查，再由用户选择轻量交接、仅保留计划，或继续治理式执行。每个闸门都由 .mancode/workflows/<taskId>/ 下的文件支撑。

-
谁来运行这些命令？

安装后的 man skill 会创建任务、把活动指针写入 .mancode/state.json、生成产物，并调用 CLI。下面展示的是供研究、排错或集成使用的机器契约。单独执行一次 workflow create 并不会自动激活该任务指针。

+

/man 是一个渐进式九步协议：先让决策变得可检查，再由用户选择轻量交接、仅保留计划，或继续治理式执行。每个闸门都由 V3 的 .mancode/<namespace>/workflows/<ULID>/ 文件支撑。

+
谁来运行这些命令？

安装后的 V3 mode entry 会创建任务并读取 Context Pack。下面展示的是供研究、排错或集成使用的机器契约。V3 使用显式 namespace:ULID TaskRef，不依赖旧的活动指针。

九个步骤与闸门

@@ -226,78 +226,61 @@

结构化需求台账

} ] } - 
$ mancode workflow requirements <taskId> finalize --file requirements-input.json
+ 
$ mancode workflow requirements <local:ULID> finalize --file requirements-input.json --expected-revision <revision> --session <session-id>

成功结果会显示 ready。如果结果是 needs_clarification，必须停止推进，先解决 blockingUnknowns，重新生成输入后再次 finalize。

Step 4 的三种决策

-

交给 solo

实施

计划已经稳定，但实现风险属于日常范围。

$ mancode workflow handoff <taskId> --to solo
+            
交给 solo
实施
计划已经稳定，但实现风险属于日常范围。
$ mancode workflow handoff <local:ULID> --to solo --expected-revision <revision> --session <session-id>
 # solo 实现并验证后
-$ mancode workflow handoff <taskId> --complete

-            
治理式执行
继续
实现、证据和独立评审都需要保留在九步记录内。
$ mancode workflow decide <taskId> --plan-decision governed_execution

-            
只保留计划
停止
用户需要的交付物是计划，而不是代码。
$ mancode workflow decide <taskId> --plan-decision plan_only

+$ mancode workflow handoff <local:ULID> --complete --expected-revision <revision> --session <session-id>
+

治理式执行

继续

实现、证据和独立评审都需要保留在九步记录内。

$ mancode workflow plan <local:ULID> confirm --plan-decision governed_execution --expected-revision <revision> --session <session-id>
+

只保留计划

停止

用户需要的交付物是计划，而不是代码。

$ mancode workflow plan <local:ULID> confirm --plan-decision plan_only --expected-revision <revision> --session <session-id>
-

三种选择都要求：活动中的 man 工作流位于 Step 4、需求已 ready，并且 plan.md 存在。选择修订时仍停留在计划闸门，更新文件，并用 --plan-version 从初始 v1 递增到 v2、v3。

+

三种选择都要求活动中的 man 工作流、已确认需求和 plan.md。使用 workflow plan ... revise 修订计划；每次成功写入都会返回下一个命令需要的 revision。

-

一条合法的治理式执行顺序

-

下面是压缩后的有效顺序。注释表示由 Agent 写入的文件，不是终端命令；只有当前阶段的工作和产物都完成后，Agent 才推进编号步骤。

- 
# Step 1–2：创建、侦察、澄清并冻结需求
-$ mancode workflow create man "refactor auth module" --json
-# Agent 保存活动 taskId，并写入 scout-report.md
-$ mancode workflow update <taskId> --step 2
-$ mancode workflow requirements <taskId> finalize --file requirements-input.json
+          
一条合法的 V3 顺序

+          
V3 使用显式 TaskRef 和 expected revision。所有持久化变更都由 CLI 完成；不要手工编辑 metadata，也不要使用 legacy --step 协议。

+          
# 创建 actor 和显式 session
+$ mancode team identity create --name "Your name"
+$ mancode context session new --client codex --json
 
-# Step 3–4：写入 plan.md，到达用户决策闸门
-$ mancode workflow update <taskId> --step 3
-# Agent 写入 plan.md
-$ mancode workflow update <taskId> --step 4
-$ mancode workflow decide <taskId> --plan-decision governed_execution
+# 创建、发现并检查任务
+$ mancode workflow create man "refactor auth module" --session <session-id> --json
+$ mancode workflow list --json
+$ mancode workflow show <local:ULID> --json
 
-# Step 5–6：实现、初始化验证、记录每个必需 AC
-$ mancode workflow update <taskId> --step 5
-# Agent 实现已确认计划
-$ mancode workflow update <taskId> --step 6
-$ mancode workflow verify <taskId> init
-$ mancode workflow verify <taskId> record --acceptance AC-LOGIN --method automated --result passed --evidence "auth tests passed" --command "npm test -- auth" --exit-code 0
+# 需求和计划闸门（每次使用上一个命令返回的 revision）
+$ mancode workflow requirements <local:ULID> finalize --file requirements-input.json --expected-revision <revision> --session <session-id>
+$ mancode workflow plan <local:ULID> revise --file plan.md --expected-revision <revision> --session <session-id>
+$ mancode workflow plan <local:ULID> confirm --plan-decision governed_execution --expected-revision <revision> --session <session-id>
 
-# Step 7–9：targeted review、报告、总结、完成
-# Agent 写入 review-scope.md
-$ mancode workflow review <taskId> init --review-depth targeted --review-domain quality
-$ mancode workflow update <taskId> --step 7
-# Agent 写入 film-report-1.md
-$ mancode workflow review <taskId> complete --review-domain quality --report film-report-1.md
-$ mancode workflow update <taskId> --step 9
-# Agent 写入 summary.md
-$ mancode workflow update <taskId> --status completed

+# 记录规范化评审和验证台账
+$ mancode workflow review <local:ULID> apply --file review-ledger.json --expected-revision <revision> --session <session-id>
+$ mancode workflow verify <local:ULID> apply --file verification-ledger.json --expected-revision <revision> --session <session-id>
+$ mancode workflow complete <local:ULID> --expected-revision <revision> --session <session-id>

自动验证、手工确认与修复后重验

步骤Agent 工作持久化闸门
- - - - + + + +
场景必须记录闸门行为
自动验证record 必须包含验收 ID、方法、结果、证据、准确命令和退出码。passed 要求退出码 0，failed 要求非 0。所有必需验收标准通过前，Step 7 和 review 都会被阻止。
手工验证require-manual 解释自动化为何不能判断。只有用户亲自执行并确认后，Agent 才能用 confirm-manual 写入观察证据。等待确认期间工作流处于 blocked。
评审发现review complete ... --blockers Q1,Q2 保存稳定 ID；用 review remediate --resolved Q1,Q2 进行唯一一轮修复。任何 remediation 都会使旧验证失效，Step 9 必须重新运行并记录全部必需验收。
用户跳过评审在 Step 6 完成验证后，使用 review skip --reason "explicit user request"。理由会持久保存，但仍需写 summary.md 并到 Step 9 才能完成。
自动验证规范化 verification ledger 记录验收项、命令、退出码、证据摘要与结果。workflow verify ... apply 会拒绝不符合 V3 schema 或 revision 的台账。
手工验证台账记录自动化不能判断的原因；只有用户明确确认后才能改为 passed。必需人工证据未完成时，completion 持续阻塞。
评审发现规范化 review ledger 保存稳定 blocker ID 及其 remediation 状态。应用 review ledger 会使旧验证失效；评审后、完成前必须 apply 当前验证。
用户跳过评审review ledger 记录用户显式决定和残余风险。仍然需要有效 summary 和其余全部门禁。
- 
# 手工验收：require-manual 后必须暂停等待
-$ mancode workflow verify <taskId> require-manual --acceptance AC-UI --evidence "需要前台浏览器和人工判断"
-# 只有用户明确确认后才能执行
-$ mancode workflow verify <taskId> confirm-manual --acceptance AC-UI --evidence "用户确认交互符合预期"
-
-# 唯一一轮 blocker remediation
-$ mancode workflow review <taskId> complete --review-domain quality --report film-report-1.md --blockers Q1
-$ mancode workflow update <taskId> --step 9
-$ mancode workflow review <taskId> remediate --resolved Q1
-$ mancode workflow verify <taskId> record --acceptance AC-LOGIN --method automated --result passed --evidence "修复后测试通过" --command "npm test -- auth" --exit-code 0
+ 
# remediation 后更新规范化台账
+$ mancode workflow review <local:ULID> apply --file review-ledger.json --expected-revision <revision> --session <session-id>
+$ mancode workflow verify <local:ULID> apply --file verification-ledger.json --expected-revision <revision> --session <session-id>
+$ mancode workflow complete <local:ULID> --expected-revision <revision> --session <session-id>

workflow 子命令速查

- - - - - - - - + + + + + + +
命令用途关键选项
create创建 man、manba 或 manteam 记录。--parent-task 关联诊断子任务；--json 输出 task ID。
requirements从 JSON 完成 Step 2 需求台账。finalize --file。
update推进步骤、状态、计划版本或结果。--step、--status、--plan-version、--blocking-reason、--outcome。通用 --skipped 只允许记录 clarification。
decide解决 Step 4 计划闸门。--plan-decision governed_execution|plan_only。
handoff把已确认计划交给 solo，随后关闭该计划。--to solo，完成后使用 --complete。
verify初始化并记录验收证据。init、record、require-manual、confirm-manual；证据选项包括 --command、--exit-code 和 --evidence-file。
review初始化 targeted/full review、保存报告和 blocker、修复一次，或记录用户显式跳过。--review-depth、--review-domain、--report、--blockers、--resolved、--reason。
list / show / clean检查记录或删除较早的已完成记录。show --json；clean --older-than 30d --dry-run。
create创建 man、manba 或 manteam 记录。--parent <TaskRef> 关联诊断子任务；--json 输出 TaskRef。
requirements完成结构化需求台账。finalize --file --expected-revision --session。
plan修订计划或确认执行决策。revise --file；confirm --plan-decision；两者都需要 revision 和 session。
update改变生命周期状态或阻塞原因。--status --expected-revision --session；治理字段使用专用命令。
handoff把已确认的本地计划交给 solo，随后关闭。--to solo 或 --complete，并传 revision 与 session。
verify / review应用规范化 V3 台账。apply --file --expected-revision --session。
list / show / clean列出或检查 V3 TaskRef；clean 不是删除 V3 权威数据的命令。show <namespace:ULID> --json；保留清理使用 context compact --dry-run。
@@ -324,16 +307,14 @@

刷新项目上下文

安全卸载

-

卸载会保留用户自己编写的 rules、instructions 和无关的 Claude settings。删除前先检查工作流记录，避免丢失仍然需要的决策或证据。

+

卸载单个平台会保留用户自己编写的 rules、instructions、无关的 Claude settings 和 V3 工作流权威数据。使用 context compact --dry-run 检查可清理的运行时保留记录。

移除一个适配器

$ mancode uninstall cursor --force
-

完整重装

- 
$ mancode uninstall --all --force
-$ mancode init
-$ mancode install <platform>
-

完全移除 mancode

- 
$ mancode uninstall --all --force
-$ npm uninstall -g mancode
+

重装一个适配器

+ 
$ mancode uninstall claude-code --force
+$ mancode install claude-code
+

移除 CLI

+ 
$ npm uninstall -g mancode
@@ -347,7 +328,7 @@

Claude Code hooks 没有触发

Cursor rules 没有触发

确认 .cursor/rules/mancode-*.mdc 和 .cursor/commands/*.md 都存在。核心上下文与 solo rules 持续生效；高强度规则按描述触发，因此应显式调用生成的模式命令。

workflow 命令被拒绝

-

把拒绝当作流程闸门，而不是元数据损坏。使用 mancode workflow show <taskId> --json 检查步骤、需求就绪状态、计划决策、验证、评审域和 blocker。不要直接编辑 metadata.json。

+

把拒绝当作流程闸门，而不是元数据损坏。先用 mancode workflow list --json 找到 TaskRef，再用 mancode workflow show <namespace:ULID> --json 检查元数据、revision、aggregate 和 blocker。不要手工编辑 V3 metadata。

项目事实已经过期

添加 Git、manifest、依赖或验证脚本后执行 mancode refresh-project；UI token 改变时执行 refresh-style。只有静态适配器的生成文件需要更新时，才重新安装对应平台。

diff --git a/website/index.html b/website/index.html index 76cd820..a4d879e 100644 --- a/website/index.html +++ b/website/index.html @@ -253,7 +253,7 @@

Every task
is not game seven.

/man workflow

From scout report
to final buzzer.

Every planning run leaves a readable trail under - .mancode/workflows/<taskId>/. After approval, hand the plan to lightweight solo + .mancode/<namespace>/workflows/<ULID>/. After approval, hand the plan to lightweight solo delivery or continue through the full governed workflow.

@@ -299,10 +299,10 @@

Read the room
before writing.

project / local
your-project/
 ├── .mancode/
-│   ├── project-profile.json
-│   ├── aesthetics/style-tokens.json
-│   ├── workflows/<taskId>/
-│   └── memory/
+│   ├── shared/context/project.json
+│   ├── local/cache/style-tokens.json
+│   ├── local/workflows/<ULID>/
+│   └── shared/team/
 ├── .claude/
 ├── .cursor/rules/
 ├── .agents/skills/
@@ -439,7 +439,7 @@ 
Stop babysitting
AI bloat.

         中文
         AGPL-3.0
       
-       Stable / v0.3.13
+       V3 Beta / v0.3.13
     
   
 
diff --git a/website/index.zh-CN.html b/website/index.zh-CN.html
index 04a7817..bec2eab 100644
--- a/website/index.zh-CN.html
+++ b/website/index.zh-CN.html
@@ -38,7 +38,7 @@
 
       
02 / 五档强度按风险匹配流程。
不是每个任务
都是抢七。
同一个编码 Agent，日常任务轻装上阵；需要正式方案时先用 /man 对齐需求和计划，再选择 solo 轻量开发或完整治理。针对最新模型自带审查的特点，mancode 会限制 review 轮次，同时给不主动审查的模型保留质量门槛。
日常训练
solo
一次受限 diff 自检、最窄验证，不调用额外 reviewer。
真实诊断
/manba
复现、定位根因、驱动真实路径并回归验证。
先计划再选择
/man
引导需求对齐、方案推荐和持久计划；确认后选择 solo 或完整九步治理。
团队协作
/manteam
共享项目记忆、决策记录与协作约定。
季前赛
/manps
检测陈旧 TODO、依赖风险和硬编码设计值。

 
-      
03 / 先计划再选择solo 交付或完整治理。
/man 工作流
从需求对齐
到确认计划。
每次规划都会在 .mancode/workflows/<taskId>/ 产生可读记录。计划确认后，可交给 solo 轻量开发，也可继续完整九步治理。
  1. 01球探报告梳理代码、风险与未知项
  2. 02需求澄清确认真正要解决的问题
  3. 03计划输出可验证步骤
  4. 04计划关卡solo、完整治理、仅计划或修改
  5. 05实施完整 /man 才进入
  6. 06验证与范围验证后选择审查深度
  7. 07定向审查有证据的质量 finding
  8. 08风险防守高风险时审查安全边界
  9. 09收尾一轮修复、复验、停止

+      
03 / 先计划再选择solo 交付或完整治理。
/man 工作流
从需求对齐
到确认计划。
每次规划都会在 .mancode/<namespace>/workflows/<ULID>/ 产生可读记录。计划确认后，可交给 solo 轻量开发，也可继续完整九步治理。
  1. 01球探报告梳理代码、风险与未知项
  2. 02需求澄清确认真正要解决的问题
  3. 03计划输出可验证步骤
  4. 04计划关卡solo、完整治理、仅计划或修改
  5. 05实施完整 /man 才进入
  6. 06验证与范围验证后选择审查深度
  7. 07定向审查有证据的质量 finding
  8. 08风险防守高风险时审查安全边界
  9. 09收尾一轮修复、复验、停止

 
       

         
04 / 项目感知你的代码库本来就有自己的战术。

@@ -52,10 +52,10 @@ 
先读懂现场，
再开始写。

             
project / local

             
your-project/
 ├── .mancode/
-│   ├── project-profile.json
-│   ├── aesthetics/style-tokens.json
-│   ├── workflows/<taskId>/
-│   └── memory/
+│   ├── shared/context/project.json
+│   ├── local/cache/style-tokens.json
+│   ├── local/workflows/<ULID>/
+│   └── shared/team/
 ├── .claude/
 ├── .cursor/rules/
 ├── .agents/skills/
@@ -88,6 +88,6 @@ 
一项任务。
下个会话继续。

 
       
简单任务少一点仪式。
关键任务多一点纪律。
别再替 AI
收拾臃肿。
> npm install -g mancode
GitHub 上查看 ↗

     
-    
+    
   
 

From 573c7db34fa75e93de7ce68799a97af312a6d13f Mon Sep 17 00:00:00 2001
From: whitelonng 
Date: Sun, 19 Jul 2026 23:47:05 +0800
Subject: [PATCH 2/9] chore: release 0.3.14

---
 README.en.md               | 6 +++---
 README.md                  | 6 +++---
 docs/12-lifecycle.md       | 2 +-
 package-lock.json          | 4 ++--
 package.json               | 2 +-
 tests/website-docs.test.ts | 4 ++--
 website/docs.html          | 2 +-
 website/docs.zh-CN.html    | 2 +-
 website/index.html         | 2 +-
 website/index.zh-CN.html   | 2 +-
 10 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/README.en.md b/README.en.md
index 58479a4..92da94c 100644
--- a/README.en.md
+++ b/README.en.md
@@ -17,7 +17,7 @@
 

   License: AGPL-3.0
   npm version
-  Status: V3 beta v0.3.13
+  Status: V3 beta v0.3.14
   Platforms: Claude Code, Cursor, Codex in ChatGPT desktop and CLI, GitHub Copilot, ZCode
 

 
@@ -350,7 +350,7 @@ it should behave, and why previous decisions were made.
 
 ## Installation
 
-**Status**: V3 beta v0.3.13. Claude Code, Cursor, Codex in the ChatGPT desktop
+**Status**: V3 beta v0.3.14. Claude Code, Cursor, Codex in the ChatGPT desktop
 app and CLI, GitHub Copilot, and ZCode adapters are included. Stable release
 still requires the five-host real-session acceptance and the `context beta` B1 gate.
 
@@ -449,7 +449,7 @@ mancode version
 Simplified output:
 
 ```text
-mancode v0.3.13
+mancode v0.3.14
 
 Project:     my-app
 Runtime:     ready
diff --git a/README.md b/README.md
index d73f72e..a15a90e 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@
 

   许可证：AGPL-3.0
   npm 版本
-  状态：V3 Beta v0.3.13
+  状态：V3 Beta v0.3.14
   平台：Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI、GitHub Copilot、ZCode
 

 
@@ -305,7 +305,7 @@ src/components/
 
 ## 安装
 
-**状态**：V3 Beta v0.3.13。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、
+**状态**：V3 Beta v0.3.14。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、
 Codex CLI 和 GitHub Copilot 均已接入；ZCode adapter 已接入。正式稳定发布仍需
 完成五平台真实宿主验收和 `context beta` B1 门禁。
 
@@ -402,7 +402,7 @@ mancode version
 以下是简化输出示例：
 
 ```text
-mancode v0.3.13
+mancode v0.3.14
 
 Project:     my-app
 Runtime:     ready
diff --git a/docs/12-lifecycle.md b/docs/12-lifecycle.md
index 077e6da..9dfde5c 100644
--- a/docs/12-lifecycle.md
+++ b/docs/12-lifecycle.md
@@ -107,7 +107,7 @@ Node 直接解析 JSON。不存在 jq fallback，也不会调用任何外部进
 
 ```json
 {
-  "version": "0.3.13",
+  "version": "0.3.14",
   "currentMode": "solo",
   "lastMode": "solo",
   "platform": "claude-code",
diff --git a/package-lock.json b/package-lock.json
index 0d8c5a7..af627fe 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mancode",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mancode",
-      "version": "0.3.13",
+      "version": "0.3.14",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "commander": "^12.1.0",
diff --git a/package.json b/package.json
index fd6e224..d5461a8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mancode",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "description": "AI coding agent workflow harness. Five modes from practice to playoffs: stop over-engineering, reuse project context, and add multi-agent code review.",
   "type": "module",
   "license": "AGPL-3.0-only",
diff --git a/tests/website-docs.test.ts b/tests/website-docs.test.ts
index 61ccc49..964d95f 100644
--- a/tests/website-docs.test.ts
+++ b/tests/website-docs.test.ts
@@ -145,8 +145,8 @@ describe('website documentation', () => {
     expect(chinese).toContain('代码，避免');
     expect(chinese).toContain('AI 屎山。');
     expect(chinese).toContain('预览适配器');
-    expect(english).toContain('V3 Beta / v0.3.13');
-    expect(chinese).toContain('V3 Beta / v0.3.13');
+    expect(english).toContain('V3 Beta / v0.3.14');
+    expect(chinese).toContain('V3 Beta / v0.3.14');
   });
 
   it('documents the cross-session boundary in both languages', async () => {
diff --git a/website/docs.html b/website/docs.html
index 40258b5..605447b 100644
--- a/website/docs.html
+++ b/website/docs.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      Documentation / v0.3.13
+      Documentation / v0.3.14
       

         Website
         GitHub
diff --git a/website/docs.zh-CN.html b/website/docs.zh-CN.html
index e6f5aa3..0ca73be 100644
--- a/website/docs.zh-CN.html
+++ b/website/docs.zh-CN.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      文档 / v0.3.13
+      文档 / v0.3.14
       

         官网
         GitHub
diff --git a/website/index.html b/website/index.html
index a4d879e..f0528b1 100644
--- a/website/index.html
+++ b/website/index.html
@@ -439,7 +439,7 @@ 
Stop babysitting
AI bloat.

         中文
         AGPL-3.0
       

-       V3 Beta / v0.3.13
+       V3 Beta / v0.3.14
     
   
 
diff --git a/website/index.zh-CN.html b/website/index.zh-CN.html
index bec2eab..37cad6e 100644
--- a/website/index.zh-CN.html
+++ b/website/index.zh-CN.html
@@ -88,6 +88,6 @@ 
一项任务。
下个会话继续。

 
       
简单任务少一点仪式。
关键任务多一点纪律。
别再替 AI
收拾臃肿。
> npm install -g mancode
GitHub 上查看 ↗

     
-    
+    
   
 

From 7c9c2f18b89dd59ddf62dd135f69a31bfe8f6482 Mon Sep 17 00:00:00 2001
From: whitelonng 
Date: Mon, 20 Jul 2026 01:32:49 +0800
Subject: [PATCH 3/9] release: mancode Continuity 0.3.15

---
 .github/workflows/quality.yml      |  2 +
 README.en.md                       | 28 +++++----
 README.md                          | 26 +++++----
 package-lock.json                  |  4 +-
 package.json                       |  7 ++-
 scripts/verify-dist-adapters.mjs   | 92 ++++++++++++++++++++++++++++++
 src/cli.ts                         |  1 +
 src/commands/status.ts             | 56 +++++++++++++++++-
 src/commands/uninstall.ts          |  2 +-
 src/commands/workflow.ts           |  2 +-
 src/installers/v3-adapter.ts       | 36 ++++++------
 tests/status.test.ts               | 29 ++++++++++
 tests/v3-adapter-contracts.test.ts | 12 +++-
 tests/version.test.ts              |  4 +-
 tests/website-docs.test.ts         | 10 ++--
 website/docs.html                  | 34 +++++------
 website/docs.zh-CN.html            | 34 +++++------
 website/index.html                 |  2 +-
 website/index.zh-CN.html           |  2 +-
 19 files changed, 289 insertions(+), 94 deletions(-)
 create mode 100644 scripts/verify-dist-adapters.mjs

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index a8ba87f..185e516 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -23,5 +23,7 @@ jobs:
         run: npm run typecheck
       - name: Build
         run: npm run build
+      - name: Verify compiled adapters
+        run: npm run test:dist
       - name: Test
         run: npm test
diff --git a/README.en.md b/README.en.md
index 92da94c..96133dc 100644
--- a/README.en.md
+++ b/README.en.md
@@ -17,7 +17,7 @@
 

   License: AGPL-3.0
   npm version
-  Status: V3 beta v0.3.14
+  Status: mancode Continuity v0.3.15
   Platforms: Claude Code, Cursor, Codex in ChatGPT desktop and CLI, GitHub Copilot, ZCode
 

 
@@ -34,6 +34,9 @@ different gears for different stakes: light solo mode for daily practice, `/man`
 for playoff-level engineering discipline, and coaching-staff subagents for
 research, planning, implementation, and review.
 
+**mancode Continuity** is the continuous-context runtime that carries tasks,
+decisions, and verification evidence safely into later conversations.
+
 [Installation](#installation) · [Usage](#usage)
 
 mancode ships with adapters for Claude Code, Cursor, Codex in the ChatGPT
@@ -102,7 +105,7 @@ explicitly resumes the existing TaskRef, preserving continuity without treating
 one window's temporary state as another window's identity.
 
 ```bash
-mancode status --json
+mancode status --brief --json
 mancode context session new --client claude-code
 mancode context resume  --session  --client claude-code
 mancode context show --purpose orient --session  --client claude-code
@@ -350,9 +353,8 @@ it should behave, and why previous decisions were made.
 
 ## Installation
 
-**Status**: V3 beta v0.3.14. Claude Code, Cursor, Codex in the ChatGPT desktop
-app and CLI, GitHub Copilot, and ZCode adapters are included. Stable release
-still requires the five-host real-session acceptance and the `context beta` B1 gate.
+**Status**: mancode Continuity v0.3.15. Claude Code, Cursor, Codex in the ChatGPT
+desktop app and CLI, GitHub Copilot, and ZCode adapters are included.
 
 Requires Node.js 20 or newer. macOS, Linux, Windows CMD, PowerShell, and Git Bash
 are supported. Git is optional: without it, initialization continues with solo
@@ -421,6 +423,7 @@ mancode init
 mancode init --legacy
 mancode status
 mancode status --json
+mancode status --brief --json
 mancode install 
 mancode list-platforms
 mancode team identity create --name ""
@@ -449,7 +452,7 @@ mancode version
 Simplified output:
 
 ```text
-mancode v0.3.14
+mancode v0.3.15
 
 Project:     my-app
 Runtime:     ready
@@ -488,12 +491,15 @@ mancode init
 
 ### `mancode status`
 
-Shows activation, runtime binding, identity/session evidence, transport, and
-the physical readiness of each platform bootstrap and original mode entry.
+The default and full JSON views show activation, runtime binding,
+identity/session evidence, transport, and the physical readiness of each
+platform bootstrap and original mode entry. Coding agents should combine
+`--brief --json` to read only the compact Continuity runtime view.
 
 ```bash
 mancode status
 mancode status --json
+mancode status --brief --json
 ```
 
 ### `mancode workflow`
@@ -639,7 +645,7 @@ Ensure the `.cursor/rules/mancode-*.mdc` files exist. Rules with
 Mode-specific rules (manba, man, manteam, manps) trigger based on the
 description field — invoke them by asking for `/manba` or similar.
 
-### How to reinstall V3 adapters
+### How to reinstall Continuity adapters
 
 ```bash
 mancode uninstall claude-code --force
@@ -654,7 +660,7 @@ mancode install copilot
 mancode install zcode
 ```
 
-V3 authority is protected, so `mancode uninstall --all` does not delete workflow
+Continuity authority is protected, so `mancode uninstall --all` does not delete workflow
 authority. To inspect removable runtime records, run
 `mancode context compact --dry-run` first.
 
@@ -665,7 +671,7 @@ npm uninstall -g mancode
 ```
 
 Uninstalling each platform removes its mancode bootstrap while preserving
-user-authored rules, instructions, and V3 workflow data. The `--all` form is only
+user-authored rules, instructions, and Continuity workflow data. The `--all` form is only
 supported for projects explicitly initialized with `mancode init --legacy`.
 
 ## FAQ
diff --git a/README.md b/README.md
index a15a90e..f453187 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@
 

   许可证：AGPL-3.0
   npm 版本
-  状态：V3 Beta v0.3.14
+  状态：mancode Continuity v0.3.15
   平台：Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI、GitHub Copilot、ZCode
 

 
@@ -36,6 +36,8 @@
 日常任务用轻量 `solo`，关键任务用季后赛级别的 `/man`，复杂任务让教练组 subagents
 负责调研、计划、实现和审查。
 
+**mancode Continuity（连续上下文运行时）**负责把任务、决策和验证证据安全地带到后续对话。
+
 mancode 当前支持 Claude Code、Cursor、ChatGPT 桌面端中的 Codex、Codex CLI、
 GitHub Copilot 和 ZCode。每个平台继续使用原来的 `man*` 入口，并通过静态
 bootstrap 接入统一的 Context Pack 与 workflow authority。
@@ -92,7 +94,7 @@ mancode 把目标、需求、计划、检查结果和交接信息保存在稳定
 窗口的临时状态误当成另一个窗口的身份。
 
 ```bash
-mancode status --json
+mancode status --brief --json
 mancode context session new --client claude-code
 mancode context resume  --session  --client claude-code
 mancode context show --purpose orient --session  --client claude-code
@@ -305,9 +307,8 @@ src/components/
 
 ## 安装
 
-**状态**：V3 Beta v0.3.14。Claude Code、Cursor、ChatGPT 桌面端中的 Codex、
-Codex CLI 和 GitHub Copilot 均已接入；ZCode adapter 已接入。正式稳定发布仍需
-完成五平台真实宿主验收和 `context beta` B1 门禁。
+**状态**：mancode Continuity v0.3.15。Claude Code、Cursor、ChatGPT 桌面端中的
+Codex、Codex CLI、GitHub Copilot 和 ZCode adapter 均已接入。
 
 需要 Node.js 20 或更高版本。原生支持 macOS、Linux、Windows CMD、
 PowerShell 和 Git Bash。Git 是可选依赖：未安装时仍可初始化，只会把团队
@@ -374,6 +375,7 @@ mancode init
 mancode init --legacy
 mancode status
 mancode status --json
+mancode status --brief --json
 mancode install 
 mancode list-platforms
 mancode team identity create --name ""
@@ -402,7 +404,7 @@ mancode version
 以下是简化输出示例：
 
 ```text
-mancode v0.3.14
+mancode v0.3.15
 
 Project:     my-app
 Runtime:     ready
@@ -440,12 +442,14 @@ mancode init
 
 ### `mancode status`
 
-显示 activation、runtime binding、identity/session evidence、transport 和各平台
-bootstrap/原 mode 入口的实际就绪状态。
+默认输出和完整 JSON 显示 activation、runtime binding、identity/session evidence、
+transport 和各平台 bootstrap/原 mode 入口的实际就绪状态。编码 Agent 应组合使用
+`--brief --json`，只读取精简的 Continuity 运行时视图。
 
 ```bash
 mancode status
 mancode status --json
+mancode status --brief --json
 ```
 
 ### `mancode workflow`
@@ -579,7 +583,7 @@ mancode/
 （context、practice、solo）在每次对话加载。模式规则（manba、man、manteam、
 manps）按 description 触发——输入 `/manba` 等关键词即可激活。
 
-### 如何重装 V3 适配器
+### 如何重装 Continuity 适配器
 
 ```bash
 mancode uninstall claude-code --force
@@ -594,7 +598,7 @@ mancode install copilot
 mancode install zcode
 ```
 
-V3 authority 受保护，`mancode uninstall --all` 不会删除工作流权威数据。需要
+Continuity authority 受保护，`mancode uninstall --all` 不会删除工作流权威数据。需要
 清理运行时保留记录时，先用 `mancode context compact --dry-run` 检查候选。
 
 ### 如何移除 CLI
@@ -604,7 +608,7 @@ npm uninstall -g mancode
 ```
 
 逐个平台卸载会移除对应的 mancode bootstrap，并保留用户自定义 rules、instructions
-和 V3 工作流数据。旧项目若明确使用 `mancode init --legacy`，才支持 legacy 的
+和 Continuity 工作流数据。旧项目若明确使用 `mancode init --legacy`，才支持 legacy 的
 `mancode uninstall --all --force`。
 
 ## 常见问题
diff --git a/package-lock.json b/package-lock.json
index af627fe..ba71130 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mancode",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mancode",
-      "version": "0.3.14",
+      "version": "0.3.15",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "commander": "^12.1.0",
diff --git a/package.json b/package.json
index d5461a8..537e599 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "mancode",
-  "version": "0.3.14",
-  "description": "AI coding agent workflow harness. Five modes from practice to playoffs: stop over-engineering, reuse project context, and add multi-agent code review.",
+  "version": "0.3.15",
+  "description": "AI coding agent workflow harness with mancode Continuity for cross-conversation tasks, decisions, verification, and team coordination.",
   "type": "module",
   "license": "AGPL-3.0-only",
   "author": "whitelonng",
@@ -59,13 +59,14 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
+    "test:dist": "node scripts/verify-dist-adapters.mjs",
     "test:windows-smoke": "node scripts/windows-smoke.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "biome check src tests",
     "typecheck": "tsc --noEmit",
     "format": "biome format --write src tests",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm run build && npm test"
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run build && npm run test:dist && npm test"
   },
   "dependencies": {
     "commander": "^12.1.0",
diff --git a/scripts/verify-dist-adapters.mjs b/scripts/verify-dist-adapters.mjs
new file mode 100644
index 0000000..7f2caac
--- /dev/null
+++ b/scripts/verify-dist-adapters.mjs
@@ -0,0 +1,92 @@
+import { spawnSync } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+);
+const cliPath = path.join(repoRoot, 'dist', 'cli.js');
+const projectRoot = await mkdtemp(
+  path.join(tmpdir(), 'mancode-dist-adapters-'),
+);
+
+try {
+  await mkdir(projectRoot, { recursive: true });
+  runCli(['init', '--empty', '--platform', 'all', '--lang', 'en']);
+
+  const generatedFiles = [
+    '.claude/skills/mancode-v3/SKILL.md',
+    '.claude/skills/man/SKILL.md',
+    '.cursor/rules/mancode-v3.mdc',
+    '.cursor/commands/man.md',
+    'AGENTS.md',
+    '.agents/skills/man/SKILL.md',
+    '.github/copilot-instructions.md',
+    '.github/prompts/man.prompt.md',
+  ];
+
+  for (const relativePath of generatedFiles) {
+    const content = await readFile(path.join(projectRoot, relativePath), 'utf8');
+    assertGeneratedContract(relativePath, content);
+  }
+
+  const status = runCli(['status', '--brief', '--json']);
+  const parsed = JSON.parse(status.stdout);
+  assert(
+    parsed.runtime === 'mancode-continuity' && parsed.state === 'active',
+    `compiled status returned an unexpected runtime: ${status.stdout}`,
+  );
+  assert(
+    !status.stdout.includes('"v3"') && !status.stdout.includes('v3_active'),
+    `compiled brief status exposed internal version fields: ${status.stdout}`,
+  );
+
+  console.log(
+    `Verified ${generatedFiles.length} adapters generated by dist/cli.js.`,
+  );
+} finally {
+  await rm(projectRoot, { recursive: true, force: true });
+}
+
+function runCli(args) {
+  const result = spawnSync(process.execPath, [cliPath, ...args], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+  });
+  assert(
+    result.status === 0,
+    `compiled CLI failed (${result.status}): ${result.stderr || result.stdout}`,
+  );
+  return result;
+}
+
+function assertGeneratedContract(relativePath, content) {
+  for (const required of [
+    'mancode status --brief --json',
+    'snapshot already obtained in this conversation',
+    'mancode Continuity',
+  ]) {
+    assert(
+      content.includes(required),
+      `${relativePath} is missing compiled guidance: ${required}`,
+    );
+  }
+  for (const forbidden of [
+    'mancode status --json',
+    'authority: "v3"',
+    'v3_active',
+  ]) {
+    assert(
+      !content.includes(forbidden),
+      `${relativePath} exposes stale guidance: ${forbidden}`,
+    );
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
diff --git a/src/cli.ts b/src/cli.ts
index 41bff6b..2f1e0e2 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -112,6 +112,7 @@ program
   .command('status')
   .description('Show current mancode project status')
   .option('--json', 'Output as JSON (for scripts)')
+  .option('--brief', 'Output compact mancode Continuity runtime status')
   .action(async (options) => {
     const code = await status(process.cwd(), options);
     process.exitCode = code;
diff --git a/src/commands/status.ts b/src/commands/status.ts
index a1cc529..499a0bb 100644
--- a/src/commands/status.ts
+++ b/src/commands/status.ts
@@ -81,6 +81,8 @@ export interface StatusState {
 export interface StatusOptions {
   /** --json: 输出 JSON（脚本用）*/
   json?: boolean;
+  /** --brief: 输出 Continuity 的紧凑运行时状态 */
+  brief?: boolean;
 }
 
 export interface StatusResult {
@@ -202,6 +204,19 @@ export interface V3StatusResult {
   legacyAuthorityPresent: boolean;
 }
 
+export interface ContinuityStatusResult {
+  schemaVersion: 1;
+  runtime: 'mancode-continuity';
+  state: 'active' | 'unavailable';
+  version: string;
+  project: string;
+  ready: boolean;
+  identity: V3StatusResult['localIdentity'];
+  session: V3StatusResult['currentSession'];
+  task: V3StatusResult['currentTask'];
+  blockers: string[];
+}
+
 interface DetectedTeamStatus {
   isTeam: boolean;
   contributors: number;
@@ -452,8 +467,11 @@ async function statusV3(
       adapters,
       legacyAuthorityPresent: legacy.authorityPresent,
     };
+    const output = options.brief ? toContinuityStatus(result) : result;
     if (options.json) {
-      console.log(JSON.stringify(result, null, 2));
+      console.log(JSON.stringify(output, null, 2));
+    } else if (options.brief) {
+      printContinuityText(output as ContinuityStatusResult);
     } else {
       printV3Text(result);
     }
@@ -466,6 +484,30 @@ async function statusV3(
   }
 }
 
+function toContinuityStatus(result: V3StatusResult): ContinuityStatusResult {
+  const blockers = [
+    ...result.compatibility.failures,
+    ...(result.runtime.error === null ? [] : [result.runtime.error]),
+  ];
+  const ready =
+    result.activation.state === 'v3_active' &&
+    result.compatibility.readAllowed &&
+    result.compatibility.writeAllowed &&
+    result.runtime.binding === 'ready';
+  return {
+    schemaVersion: 1,
+    runtime: 'mancode-continuity',
+    state: ready ? 'active' : 'unavailable',
+    version: result.version,
+    project: result.project,
+    ready,
+    identity: result.localIdentity,
+    session: result.currentSession,
+    task: result.currentTask,
+    blockers,
+  };
+}
+
 /** Status is read-only: an invalid ambient session is simply not current. */
 async function readV3StatusSession(rootDir: string) {
   const sessionId = process.env.MANCODE_SESSION_ID;
@@ -846,7 +888,7 @@ function printText(r: StatusResult): void {
 
 function printV3Text(result: V3StatusResult): void {
   console.log('');
-  console.log(`mancode v${result.version}`);
+  console.log(`mancode Continuity v${result.version}`);
   console.log('');
   console.log(`Project:     ${result.project}`);
   console.log(
@@ -913,6 +955,16 @@ function printV3Text(result: V3StatusResult): void {
   console.log('');
 }
 
+function printContinuityText(result: ContinuityStatusResult): void {
+  console.log(`mancode Continuity v${result.version}`);
+  console.log(`Project:  ${result.project}`);
+  console.log(`State:    ${result.state}`);
+  console.log(`Ready:    ${result.ready ? 'yes' : 'no'}`);
+  if (result.blockers.length > 0) {
+    console.log(`Blockers: ${result.blockers.join('; ')}`);
+  }
+}
+
 function formatActivationState(state: string): string {
   return state.replace(/^v3_/, '').replaceAll('_', ' ');
 }
diff --git a/src/commands/uninstall.ts b/src/commands/uninstall.ts
index 4fa4a97..34e1cb4 100644
--- a/src/commands/uninstall.ts
+++ b/src/commands/uninstall.ts
@@ -104,7 +104,7 @@ async function uninstallV3(
   if (!platform || options.all) {
     console.error('✗  mancode authority is protected from bulk uninstall.');
     console.error(
-      '   Remove a single bootstrap with `mancode uninstall `. Inspect runtime retention with `mancode context compact --dry-run`; V3 workflow authority is not bulk-deleted.',
+      '   Remove a single bootstrap with `mancode uninstall `. Inspect runtime retention with `mancode context compact --dry-run`; Continuity workflow authority is not bulk-deleted.',
     );
     return EXIT_V3_AUTHORITY_PROTECTED;
   }
diff --git a/src/commands/workflow.ts b/src/commands/workflow.ts
index e98762b..cc8c133 100644
--- a/src/commands/workflow.ts
+++ b/src/commands/workflow.ts
@@ -384,7 +384,7 @@ function workflowCleanV3(options: WorkflowOptions): number {
   return printV3Error(
     options.json,
     'MANCODE_V3_WORKFLOW_CLEAN_UNSUPPORTED',
-    'V3 workflow authority is durable and is not deleted by workflow clean. Use `mancode context compact --dry-run` to inspect eligible runtime retention records.',
+    'Continuity workflow authority is durable and is not deleted by workflow clean. Use `mancode context compact --dry-run` to inspect eligible runtime retention records.',
     EXIT_INVALID_ARG,
   );
 }
diff --git a/src/installers/v3-adapter.ts b/src/installers/v3-adapter.ts
index 3de59c4..c9b2cce 100644
--- a/src/installers/v3-adapter.ts
+++ b/src/installers/v3-adapter.ts
@@ -581,8 +581,8 @@ export function renderV3Bootstrap(platform: PlatformName): string {
   const sessionArguments = sessionArgumentsFor(platform);
   const sessionCreationGuidance =
     platform === 'codex' || platform === 'zcode'
-      ? 'When status has no `currentSession`, first reuse any explicit session ID already returned in this conversation. Only when neither exists, create one once with `mancode context session new --client codex` in Codex or `mancode context session new --client zcode` in ZCode.'
-      : `When status has no \`currentSession\`, first reuse any explicit session ID already returned in this conversation. Only when neither exists, create one once with \`mancode context session new --client ${platform}\`.`;
+      ? 'When status has no `session`, first reuse any explicit session ID already returned in this conversation. Only when neither exists, create one once with `mancode context session new --client codex` in Codex or `mancode context session new --client zcode` in ZCode.'
+      : `When status has no \`session\`, first reuse any explicit session ID already returned in this conversation. Only when neither exists, create one once with \`mancode context session new --client ${platform}\`.`;
   const spikePlatform =
     platform === 'codex' || platform === 'zcode'
       ? 'the active Codex or ZCode host'
@@ -597,12 +597,12 @@ export function renderV3Bootstrap(platform: PlatformName): string {
     '',
     `- Platform: ${platformLabel}. This file is a non-authoritative bootstrap.`,
     '- Locate the project root before running mancode commands.',
-    '- First run `mancode status --json` from the project root.',
-    '- Treat status values such as `authority: "v3"` and `v3_active` as internal machine fields. In operator-facing narration, say `mancode`; never prefix a mode or action with a version label.',
+    '- Reuse a `mancode status --brief --json` snapshot already obtained in this conversation. Only when no such snapshot exists, run it once from the project root.',
+    '- The compact status is the public mancode Continuity runtime view. In operator-facing narration, say `mancode` or `mancode Continuity`; never prefix a mode or action with a version label.',
     '- An explicitly invoked original `man`, `manba`, `manteam`, `manps`, or `mansolo` entry supplies its authorized action. Its mode-specific steps override conflicting generic no-task or mutation guidance below.',
     '- In particular, `manps` may run local health scans without an actor, session, or TaskRef. `mansolo` needs them only for an explicit governed handoff.',
-    '- If status has no `localIdentity.actorId`, ask for a display name and run `mancode team identity create --name ""` before creating a session.',
-    '- If status reports `currentSession`, reuse it. `currentTask: null` and `MANCODE_TASK_REQUIRED` do not make a session stale.',
+    '- If status has no `identity.actorId`, ask for a display name and run `mancode team identity create --name ""` before creating a session.',
+    '- If status reports `session`, reuse it. `task: null` and `MANCODE_TASK_REQUIRED` do not make a session stale.',
     `- ${sessionCreationGuidance} Pass its returned \`sessionId\` and matching client as \`${sessionArguments}\` to every later session command; an \`export\` inside one command tool does not persist to later command tools.`,
     '- Outside an invoked original mode entry, if no current task and no task is explicitly supplied, report "no task bound" and stop. Do not probe workflow subcommands to work around `MANCODE_TASK_REQUIRED`.',
     '- Bootstrap discovery is read-only: before the operator explicitly requests task work, do not run `mancode init`, `mancode migrate`, `mancode workflow`, or inspect mancode installed package/source.',
@@ -627,6 +627,8 @@ export function renderV3ModeEntry(
   const definition = V3_MODE_DEFINITIONS[mode];
   const sessionArguments = sessionArgumentsFor(platform);
   const sessionClientGuidance = sessionClientGuidanceFor(platform);
+  const statusGuidance =
+    'Reuse a `mancode status --brief --json` snapshot already obtained in this conversation. Only when none exists, run it once from the project root.';
   const sessionCreationGuidance =
     platform === 'codex' || platform === 'zcode'
       ? 'If status has no current session, reuse an explicit session ID already retained in this conversation. Only if neither exists, run `mancode context session new --client codex` in Codex or `mancode context session new --client zcode` in ZCode exactly once, then retain the returned session ID.'
@@ -634,31 +636,31 @@ export function renderV3ModeEntry(
   let authoritySteps: string[];
   if (mode === 'manps') {
     authoritySteps = [
-      '1. Run `mancode status --json` from the project root and require active mancode authority.',
+      `1. ${statusGuidance} Require an active, ready mancode Continuity runtime.`,
       '2. Run the health action below directly. A local scan needs no TaskRef, actor identity, or explicit session.',
       '3. Never read or write legacy mode authority before or after the scan.',
     ];
   } else if (mode === 'mansolo') {
     authoritySteps = [
-      '1. Run `mancode status --json` from the project root. Never read or write legacy mode authority.',
+      `1. ${statusGuidance} Never read or write legacy mode authority.`,
       '2. If no governed task is being handed off, continue with focused solo work without creating a persistent mode, actor, session, or TaskRef.',
-      `3. For an explicit governed handoff, ensure \`localIdentity.actorId\`, reuse or create the current session, and bind the existing TaskRef. ${sessionCreationGuidance} ${sessionClientGuidance}`,
+      `3. For an explicit governed handoff, ensure \`identity.actorId\`, reuse or create the current session, and bind the existing TaskRef. ${sessionCreationGuidance} ${sessionClientGuidance}`,
       `4. For that governed task only, read \`mancode context show --purpose implement ${sessionArguments}\` using the bound or explicit TaskRef.`,
     ];
   } else if (mode === 'man') {
     authoritySteps = [
-      '1. Run `mancode status --json` from the project root. Never read or write the legacy authority file.',
+      `1. ${statusGuidance} Never read or write the legacy authority file.`,
       '2. If the request is only a read-only project orientation, introduction, explanation, or summary, inspect the repository and answer directly without creating an actor, session, TaskRef, or workflow. Do not turn an orientation request into a `plan_only` workflow.',
-      '3. Only for requested governed task work, if `localIdentity.actorId` is absent, ask for a display name and run `mancode team identity create --name ""`.',
-      `4. Reuse \`currentSession.sessionId\` when present. ${sessionCreationGuidance} ${sessionClientGuidance}`,
+      '3. Only for requested governed task work, if `identity.actorId` is absent, ask for a display name and run `mancode team identity create --name ""`.',
+      `4. Reuse \`session.sessionId\` when present. ${sessionCreationGuidance} ${sessionClientGuidance}`,
       `5. Reuse the current TaskRef. To bind a supplied existing task, run \`mancode context resume  ${sessionArguments}\`.`,
       `6. For an existing task, read only the needed Context Pack with \`mancode context show --purpose ${definition.contextPurpose} ${sessionArguments}\`; include \`--task \` when it is not yet bound. For a new task, create it through the mode action first, then read the returned TaskRef's Context Pack.`,
     ];
   } else {
     authoritySteps = [
-      '1. Run `mancode status --json` from the project root. Never read or write the legacy authority file.',
-      '2. If `localIdentity.actorId` is absent, ask for a display name and run `mancode team identity create --name ""`.',
-      `3. Reuse \`currentSession.sessionId\` when present. ${sessionCreationGuidance} ${sessionClientGuidance}`,
+      `1. ${statusGuidance} Never read or write the legacy authority file.`,
+      '2. If `identity.actorId` is absent, ask for a display name and run `mancode team identity create --name ""`.',
+      `3. Reuse \`session.sessionId\` when present. ${sessionCreationGuidance} ${sessionClientGuidance}`,
       `4. Reuse the current TaskRef. To bind a supplied existing task, run \`mancode context resume  ${sessionArguments}\`.`,
       `5. For an existing task, read only the needed Context Pack with \`mancode context show --purpose ${definition.contextPurpose} ${sessionArguments}\`; include \`--task \` when it is not yet bound. For a new task, create it through the mode action first, then read the returned TaskRef's Context Pack.`,
     ];
@@ -700,7 +702,7 @@ export function renderV3ModeEntry(
     '',
     ...actions,
     '',
-    'Treat status values such as `authority: "v3"` and `v3_active` as internal machine fields. In operator-facing narration, say `mancode`; never prefix this mode or its actions with a version label.',
+    'Treat the compact status as the public mancode Continuity runtime view. In operator-facing narration, say `mancode` or `mancode Continuity`; never prefix this mode or its actions with a version label.',
     '',
     mutationGuidance,
     '',
@@ -1313,7 +1315,7 @@ function renderRetiredCursorRule(target: V3LegacyAdapterFileTarget): string {
           : legacyName;
   const guidance =
     mode === 'context' || mode === 'practice'
-      ? 'Run `mancode status --json`, then use the matching mancode mode command.'
+      ? 'Run `mancode status --brief --json`, then use the matching mancode mode command.'
       : `Use the \`/${mode}\` mancode mode command.`;
   return [
     '---',
diff --git a/tests/status.test.ts b/tests/status.test.ts
index 81cf0eb..ce53417 100644
--- a/tests/status.test.ts
+++ b/tests/status.test.ts
@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { init } from '../src/commands/init.js';
 import { install } from '../src/commands/install.js';
 import {
+  type ContinuityStatusResult,
   EXIT_CORRUPT_STATE,
   EXIT_NOT_INITIALIZED,
   EXIT_OK,
@@ -175,12 +176,40 @@ describe('mancode status', () => {
     const logs = await captureLog(() => status(dir));
     const output = logs.join('\n');
 
+    expect(output).toContain(`mancode Continuity v${VERSION}`);
     expect(output).toContain('Activation:  active');
     expect(output).toContain('mancode adapter status:');
     expect(output).not.toContain('V3');
     expect(output).not.toContain('v3_active');
   });
 
+  it('--brief --json exposes only the public Continuity runtime view', async () => {
+    await silentInit(dir, { v3: true, platform: 'codex' });
+
+    const logs = await captureLog(() =>
+      status(dir, { brief: true, json: true }),
+    );
+    const output = logs.join('\n');
+    const result: ContinuityStatusResult = JSON.parse(output);
+
+    expect(result).toMatchObject({
+      schemaVersion: 1,
+      runtime: 'mancode-continuity',
+      state: 'active',
+      version: VERSION,
+      project: path.basename(dir),
+      ready: true,
+      identity: { actorId: null, displayName: null },
+      session: null,
+      task: null,
+      blockers: [],
+    });
+    expect(result).not.toHaveProperty('authority');
+    expect(result).not.toHaveProperty('activation');
+    expect(output).not.toContain('"v3"');
+    expect(output).not.toContain('v3_active');
+  });
+
   it('omits top-level Hooks section for non-Claude Code projects', async () => {
     await silentInit(dir, { platform: 'codex' });
 
diff --git a/tests/v3-adapter-contracts.test.ts b/tests/v3-adapter-contracts.test.ts
index 0cbc025..d7aa4a9 100644
--- a/tests/v3-adapter-contracts.test.ts
+++ b/tests/v3-adapter-contracts.test.ts
@@ -116,13 +116,16 @@ describe('V3 adapter bootstrap integration', () => {
       expect(bootstrap).toContain('# mancode bootstrap');
       expect(bootstrap).toContain('mancode context show --purpose orient');
       expect(bootstrap).toContain('--session ');
-      expect(bootstrap).toContain('First run `mancode status --json`');
+      expect(bootstrap).toContain('mancode status --brief --json');
+      expect(bootstrap).toContain(
+        'snapshot already obtained in this conversation',
+      );
       expect(bootstrap).toContain(
         'In operator-facing narration, say `mancode`',
       );
       expect(bootstrap).toContain('mancode team identity create --name');
       expect(bootstrap).toContain(
-        '`currentTask: null` and `MANCODE_TASK_REQUIRED` do not make a session stale',
+        '`task: null` and `MANCODE_TASK_REQUIRED` do not make a session stale',
       );
       expect(bootstrap).toContain(
         'Do not probe workflow subcommands to work around `MANCODE_TASK_REQUIRED`',
@@ -175,7 +178,10 @@ describe('V3 adapter bootstrap integration', () => {
         expect(entry).toContain('## Enter through mancode');
         expect(entry).toContain('In operator-facing narration, say `mancode`');
         expect(entry).not.toMatch(/\bV3\b/);
-        expect(entry).toContain('mancode status --json');
+        expect(entry).toContain('mancode status --brief --json');
+        expect(entry).toContain(
+          'snapshot already obtained in this conversation',
+        );
         expect(entry).not.toContain('.mancode/state.json');
         if (mode !== 'manps') {
           const sessionCommands = Array.from(
diff --git a/tests/version.test.ts b/tests/version.test.ts
index a2e1ae4..05b95de 100644
--- a/tests/version.test.ts
+++ b/tests/version.test.ts
@@ -21,8 +21,8 @@ describe('version', () => {
 
     for (const readme of readmes) {
       expect(readme).toContain(`v${VERSION}`);
-      expect(readme).toContain(`status-V3%20beta%20v${VERSION}`);
-      expect(readme).not.toContain(`status-stable%20v${VERSION}`);
+      expect(readme).toContain(`status-Continuity%20v${VERSION}`);
+      expect(readme).not.toMatch(/V3%20beta/i);
     }
   });
 });
diff --git a/tests/website-docs.test.ts b/tests/website-docs.test.ts
index 964d95f..2583a8f 100644
--- a/tests/website-docs.test.ts
+++ b/tests/website-docs.test.ts
@@ -71,13 +71,13 @@ describe('website documentation', () => {
     );
   });
 
-  it('shows the V3 workflow command contract', async () => {
+  it('shows the Continuity workflow command contract', async () => {
     for (const name of ['docs.html', 'docs.zh-CN.html']) {
       const html = await readPage(name);
       const start = html.indexOf(
         name === 'docs.html'
-          ? '
A valid V3 sequence
'
-          : '
一条合法的 V3 顺序
',
+          ? '
A valid Continuity sequence
'
+          : '
一条合法的 Continuity 顺序
',
       );
       const end = html.indexOf(
         name === 'docs.html'
@@ -145,8 +145,8 @@ describe('website documentation', () => {
     expect(chinese).toContain('代码，避免');
     expect(chinese).toContain('AI 屎山。');
     expect(chinese).toContain('预览适配器');
-    expect(english).toContain('V3 Beta / v0.3.14');
-    expect(chinese).toContain('V3 Beta / v0.3.14');
+    expect(english).toContain('Continuity / v0.3.15');
+    expect(chinese).toContain('Continuity / v0.3.15');
   });
 
   it('documents the cross-session boundary in both languages', async () => {
diff --git a/website/docs.html b/website/docs.html
index 605447b..ec1fc11 100644
--- a/website/docs.html
+++ b/website/docs.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      Documentation / v0.3.14
+      Documentation / v0.3.15
       

         Website
         GitHub
@@ -90,7 +90,7 @@ 
Non-interactive or targeted initialization

           
Verify the installation

           
$ mancode status
 $ mancode status --json

-          
The human-readable result names the project, current mode, team state, installed adapters, and each adapter's ready or not ready status. JSON is the stable choice for scripts. A ready adapter means its required generated files are present; it does not guarantee that an already-open agent session has reloaded them.

+          
The human-readable result names the project, current mode, team state, installed adapters, and each adapter's ready or not ready status. JSON is the stable choice for scripts; mancode status --brief --json returns the compact public Continuity view used by coding agents. A ready adapter means its required generated files are present; it does not guarantee that an already-open agent session has reloaded them.

           
Reload after setup
Restart or reload the coding agent after initialization. Then start a small request in solo. If an adapter remains not ready, repair it with mancode install <platform> --force.

         

 
@@ -98,9 +98,9 @@ 
Verify the installation

           
Files & privacy

           
mancode works locally, scans only the current project, and sends no telemetry. It deliberately does not rewrite your project's .gitignore, so your team—not the installer—decides which generated context belongs in version control.

           
-            
+            
-            
+            
PathWhat it containsBefore committing
.mancode/schema.json
.mancode/shared/
.mancode/local/		V3 authority, project policy, sessions, workflow metadata, and local runtime records. Legacy state.json exists only after explicit --legacy initialization.Review workflow evidence and local records before sharing; raw host session keys are never persisted.
.mancode/schema.json
.mancode/shared/
.mancode/local/		Continuity authority, project policy, sessions, workflow metadata, and local runtime records. Legacy state.json exists only after explicit --legacy initialization.Review workflow evidence and local records before sharing; raw host session keys are never persisted.

             
.mancode/shared/context/project.json
.mancode/local/cache/style-tokens.json		Detected stack, validation commands, and local UI tokens.Inspect for internal project details and decide whether reproducibility justifies sharing.
.mancode/local/workflows/
.mancode/shared/workflows/		Requirements, plans, review and verification ledgers, reports, checkpoints, and summaries.Review carefully. Evidence and reports may contain sensitive data; shared workflows pass the V3 privacy boundary.
.mancode/local/workflows/
.mancode/shared/workflows/		Requirements, plans, review and verification ledgers, reports, checkpoints, and summaries.Review carefully. Evidence and reports may contain sensitive data; shared workflows pass the Continuity privacy boundary.

             
.mancode/shared/context/decisions/
.mancode/shared/team/		Confirmed decisions and durable coordination authority.Commit only information intentionally written for the team.

             
.claude/, .cursor/, .agents/, .github/, AGENTS.mdAdapter instructions, commands or prompts, skills, hooks, and managed blocks.Share when the adapter is part of the team's development workflow. Content outside mancode's managed blocks remains yours.

           

@@ -111,7 +111,7 @@ 
Files & privacy

           
Continue work across sessions

           
mancode stores goals, requirements, plans, validation results, and handoff notes under a stable TaskRef. A new chat window or supported CLI can resume the same task and load a purpose-specific Context Pack.

           
What is carried forward
This is task continuity, not a copy of raw chat history. Sessions from different clients remain isolated; the new session must identify its own client and explicitly resume the existing TaskRef.

-          
$ mancode status --json
+          
$ mancode status --brief --json
 $ mancode context session new --client claude-code
 $ mancode context resume <namespace:ULID> --session <id> --client claude-code
 $ mancode context show --purpose orient --session <id> --client claude-code

@@ -169,21 +169,21 @@ 
CLI reference

           

             
mancode init
Start
Creates .mancode/, detects the project, scans style tokens where relevant, and installs adapters.
  • Options: --force, --yes, --team, --no-team, --style <name>, --platform <list>, --empty, --lang <locale>.

             
mancode install [platform]
Adapter
Installs or repairs an adapter after initialization. Omit the platform for interactive selection.
  • --force regenerates managed content.
  • --minimal installs solo-mode essentials only.

-            
mancode status [--json]
Inspect
Reports project facts, current mode and workflow, adapter readiness, and Claude hook registration where applicable.

+            
mancode status [--json] [--brief]
Inspect
Reports project facts, current mode and workflow, adapter readiness, and Claude hook registration where applicable. Combine --brief --json for the compact Continuity runtime view.

             
mancode list-platforms
Discover
Lists adapters known to the installed CLI and marks those already configured in the project.

-            
mancode workflow <subcommand>
Govern
Creates and validates V3 requirements, plans, verification evidence, reviews, remediation, and completion.
  • Inspect with list and show <namespace:ULID> [--json].
  • Use context compact --dry-run to inspect removable runtime records; V3 workflow authority is not deleted by workflow clean.

+            
mancode workflow <subcommand>
Govern
Creates and validates Continuity requirements, plans, verification evidence, reviews, remediation, and completion.
  • Inspect with list and show <namespace:ULID> [--json].
  • Use context compact --dry-run to inspect removable runtime records; Continuity workflow authority is not deleted by workflow clean.

             
mancode manps [area]
Scan
Runs a deterministic health scan for all, deps, security, dead-code, config.
  • --json emits machine-readable output.
  • --remediate enters the explicit remediation path; the default is scan-only.

             
mancode refresh-project
Rescan
Refreshes project facts after adding Git, a manifest, a framework, or validation commands, then updates installed static adapters.

             
mancode refresh-style
Design
Refreshes the project profile and design tokens. Reinstall static adapters with --force afterward.

-            
mancode uninstall [platform]
Remove
Removes one V3 adapter. V3 protects authority from bulk removal; use context compact --dry-run for retention candidates. The --all form is legacy-only.

+            
mancode uninstall [platform]
Remove
Removes one Continuity adapter. Continuity protects authority from bulk removal; use context compact --dry-run for retention candidates. The --all form is legacy-only.

             
mancode version
Version
Prints the installed CLI version for upgrade checks and issue reports.

           

         
 
         

           
Study the /man workflow

-          
/man is a progressive nine-step protocol. It first makes the decision inspectable, then lets the user choose between a lightweight handoff, a plan-only result, or governed execution. Every gate is backed by V3 files under .mancode/<namespace>/workflows/<ULID>/.

-          
Who runs these commands?
The installed V3 mode entry creates the task and reads its Context Pack. The commands below are the machine contract for studying, debugging, or integrating the process. V3 identifies tasks with explicit namespace:ULID TaskRefs and does not use a legacy active pointer.

+          
/man is a progressive nine-step protocol. It first makes the decision inspectable, then lets the user choose between a lightweight handoff, a plan-only result, or governed execution. Every gate is backed by Continuity files under .mancode/<namespace>/workflows/<ULID>/.

+          
Who runs these commands?
The installed Continuity mode entry creates the task and reads its Context Pack. The commands below are the machine contract for studying, debugging, or integrating the process. Continuity identifies tasks with explicit namespace:ULID TaskRefs and does not use a legacy active pointer.

 
           
The nine steps and their gates

           
@@ -239,8 +239,8 @@ 
The Step 4 decision
All three choices require an active man workflow, confirmed requirements, and plan.md. Revise the plan with workflow plan ... revise; every successful mutation returns the revision required by the next command.

 
-          
A valid V3 sequence

-          
V3 uses explicit TaskRefs and expected revisions. The CLI owns every durable mutation; do not edit metadata files or use the legacy --step protocol.

+          
A valid Continuity sequence

+          
Continuity uses explicit TaskRefs and expected revisions. The CLI owns every durable mutation; do not edit metadata files or use the legacy --step protocol.
# Bootstrap an actor and explicit session
 $ mancode team identity create --name "Your name"
 $ mancode context session new --client codex --json
@@ -262,7 +262,7 @@ 
A valid V3 sequence

 
           
Verification, manual checks, and remediation

           
StepAgent workDurable gate

           
           
           

-            
+            
@@ -279,8 +279,8 @@ 
Workflow subcommands

             
-            
-            
+            
+            
CaseRequired recordGate behavior
AutomatedThe canonical verification ledger records the criterion, command, exit code, evidence summary, and result.workflow verify ... apply rejects a ledger that does not satisfy the V3 schema and current revision.
AutomatedThe canonical verification ledger records the criterion, command, exit code, evidence summary, and result.workflow verify ... apply rejects a ledger that does not satisfy the Continuity schema and current revision.

             
ManualThe ledger records why automation cannot decide and only changes to passed after explicit user confirmation.Completion remains blocked while required manual evidence is pending.

             
Review findingThe canonical review ledger stores stable blocker IDs and their remediation state.Applying a review ledger makes earlier verification stale; apply current verification after review and before completion.

             
User skips reviewThe review ledger records the explicit user decision and residual risk.Completion still requires a valid summary and every remaining gate.
planRevise a plan or confirm its execution decision.revise --file; confirm --plan-decision; both require revision and session.

             
updateChange lifecycle status or a blocking reason.--status --expected-revision --session; governed fields use dedicated commands.

             
handoffTransfer a confirmed local plan to solo and later close it.--to solo or --complete, with revision and session.
verify / reviewApply canonical V3 ledgers.apply --file --expected-revision --session.
list / show / cleanList or inspect V3 TaskRefs. clean is not a V3 authority deletion command.show <namespace:ULID> --json; use context compact --dry-run for retention.
verify / reviewApply canonical Continuity ledgers.apply --file --expected-revision --session.
list / show / cleanList or inspect Continuity TaskRefs. clean is not a Continuity authority deletion command.show <namespace:ULID> --json; use context compact --dry-run for retention.

           

         

 
@@ -307,7 +307,7 @@ 
Refresh project context

 
         

           
Uninstall safely

-          
Uninstalling one adapter preserves user-authored rules, instructions, unrelated Claude settings, and V3 workflow authority. Use context compact --dry-run to inspect eligible runtime retention records.

+          
Uninstalling one adapter preserves user-authored rules, instructions, unrelated Claude settings, and Continuity workflow authority. Use context compact --dry-run to inspect eligible runtime retention records.

           
Remove one adapter

           
$ mancode uninstall cursor --force

           
Reinstall one adapter

@@ -328,7 +328,7 @@ 
Claude Code hooks do not run

           
Cursor rules do not trigger

           
Confirm that .cursor/rules/mancode-*.mdc and .cursor/commands/*.md exist. Core context and solo rules are persistent; higher-intensity rules are description-triggered, so invoke the generated mode command explicitly.

           
A workflow command is rejected

-          
Treat the rejection as a gate, not a file-corruption problem. Use mancode workflow list --json to discover TaskRefs, then mancode workflow show <namespace:ULID> --json to inspect metadata, revision, aggregate, and blockers. Do not edit V3 metadata manually.

+          
Treat the rejection as a gate, not a file-corruption problem. Use mancode workflow list --json to discover TaskRefs, then mancode workflow show <namespace:ULID> --json to inspect metadata, revision, aggregate, and blockers. Do not edit Continuity metadata manually.

           
Project facts became stale

           
After adding Git, a manifest, dependencies, or validation scripts, run mancode refresh-project. Use refresh-style for UI tokens. Then repair a static adapter only if its generated files need regeneration.

         

diff --git a/website/docs.zh-CN.html b/website/docs.zh-CN.html
index 0ca73be..0a6c3b0 100644
--- a/website/docs.zh-CN.html
+++ b/website/docs.zh-CN.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      文档 / v0.3.14
+      文档 / v0.3.15
       

         官网
         GitHub
@@ -90,7 +90,7 @@ 
指定平台或非交互初始化

           
验证安装结果

           
$ mancode status
 $ mancode status --json

-          
普通输出会列出项目、当前模式、团队状态、已安装平台，以及每个平台的 ready 或 not ready 状态；脚本应使用 JSON。ready 表示适配器要求的生成文件已经存在，但不代表一个早已打开的 Agent 会话已经重新加载这些文件。

+          
普通输出会列出项目、当前模式、团队状态、已安装平台，以及每个平台的 ready 或 not ready 状态；脚本应使用 JSON，编码 Agent 可用 mancode status --brief --json 获取精简的 Continuity 公开视图。ready 表示适配器要求的生成文件已经存在，但不代表一个早已打开的 Agent 会话已经重新加载这些文件。

           
初始化后重载
安装后重启或重新加载编程 Agent，再用 solo 完成一个小任务。如果平台仍显示 not ready，执行 mancode install <platform> --force 修复。

         
 
@@ -98,9 +98,9 @@ 
验证安装结果

           
文件与隐私

           
mancode 本地运行，只扫描当前项目，不发送遥测。它不会擅自改写项目的 .gitignore，因此哪些生成上下文应该进入版本控制，需要由你的团队明确决定。

           
-            
+            
-            
+            
路径包含什么提交前怎么处理
.mancode/schema.json
.mancode/shared/
.mancode/local/		V3 权威、项目策略、会话、工作流元数据和本地运行时记录。只有显式使用 --legacy 初始化后才会出现旧 state.json。共享前检查工作流证据和本地记录；原始宿主 session key 不会持久化。
.mancode/schema.json
.mancode/shared/
.mancode/local/		Continuity 权威、项目策略、会话、工作流元数据和本地运行时记录。只有显式使用 --legacy 初始化后才会出现旧 state.json。共享前检查工作流证据和本地记录；原始宿主 session key 不会持久化。

             
.mancode/shared/context/project.json
.mancode/local/cache/style-tokens.json		识别出的技术栈、验证命令和本地 UI token。检查是否带有内部项目信息，再权衡复现能力与暴露范围。
.mancode/local/workflows/
.mancode/shared/workflows/		需求、计划、评审和验证台账、报告、checkpoint 与总结。重点检查。证据和报告可能含敏感数据；shared workflow 必须通过 V3 隐私边界。
.mancode/local/workflows/
.mancode/shared/workflows/		需求、计划、评审和验证台账、报告、checkpoint 与总结。重点检查。证据和报告可能含敏感数据；shared workflow 必须通过 Continuity 隐私边界。

             
.mancode/shared/context/decisions/
.mancode/shared/team/		已确认决策与持久化协调权威。只提交有意写给团队的内容。

             
.claude/、.cursor/、.agents/、.github/、AGENTS.md平台 instructions、命令或 prompt、skills、hooks 与受控区块。团队确实把该适配器作为开发流程的一部分时再共享；mancode 管理标记之外的内容仍归用户所有。

           

@@ -111,7 +111,7 @@ 
文件与隐私

           
跨会话继续工作

           
mancode 把目标、需求、计划、检查结果和交接信息保存在稳定的 TaskRef 下。新聊天窗口或受支持的 CLI 可以恢复同一项任务，再按当前目的读取精简的 Context Pack。

           
会带过去什么
这是任务上下文的续接，不是原始聊天记录的复制。不同客户端的 session 仍然隔离；新 session 必须使用自己的 client 身份，并显式恢复已有 TaskRef。

-          
$ mancode status --json
+          
$ mancode status --brief --json
 $ mancode context session new --client claude-code
 $ mancode context resume <namespace:ULID> --session <id> --client claude-code
 $ mancode context show --purpose orient --session <id> --client claude-code

@@ -169,21 +169,21 @@ 
CLI 参考

           

             
mancode init
初始化
创建 .mancode/，识别项目，在适用时扫描样式 token，并安装平台适配器。
  • 选项：--force、--yes、--team、--no-team、--style <name>、--platform <list>、--empty、--lang <locale>。

             
mancode install [platform]
适配器
初始化后安装或修复一个平台。省略平台名时进入交互选择。
  • --force 重新生成受控内容。
  • --minimal 只安装 solo 的必要内容。

-            
mancode status [--json]
检查
报告项目事实、当前模式和工作流、平台就绪状态，以及适用时的 Claude hook 注册情况。

+            
mancode status [--json] [--brief]
检查
报告项目事实、当前模式和工作流、平台就绪状态，以及适用时的 Claude hook 注册情况。组合使用 --brief --json 可获得精简的 Continuity 运行时视图。

             
mancode list-platforms
发现
列出当前 CLI 支持的平台，并标出项目中已经配置的平台。

-            
mancode workflow <subcommand>
治理
创建和校验 V3 需求、计划、验证证据、评审、修复与完成状态。
  • 使用 list 和 show <namespace:ULID> [--json] 检查。
  • 使用 context compact --dry-run 检查可回收的运行时记录；V3 workflow authority 不会被 workflow clean 删除。

+            
mancode workflow <subcommand>
治理
创建和校验 Continuity 需求、计划、验证证据、评审、修复与完成状态。
  • 使用 list 和 show <namespace:ULID> [--json] 检查。
  • 使用 context compact --dry-run 检查可回收的运行时记录；Continuity workflow authority 不会被 workflow clean 删除。

             
mancode manps [area]
扫描
对 all、deps、security、dead-code 或 config 执行确定性健康扫描。
  • --json 输出机器可读结果。
  • --remediate 显式进入修复路径；默认只扫描。

             
mancode refresh-project
重扫项目
在加入 Git、manifest、框架或验证命令后刷新项目事实，并更新已安装的静态适配器。

             
mancode refresh-style
设计上下文
刷新项目画像和设计 token，之后可用 --force 重装需要更新的静态适配器。

-            
mancode uninstall [platform]
移除
移除一个 V3 适配器。V3 会保护权威数据不被批量删除；用 context compact --dry-run 检查保留候选。--all 只适用于 legacy 项目。

+            
mancode uninstall [platform]
移除
移除一个 Continuity 适配器。Continuity 会保护权威数据不被批量删除；用 context compact --dry-run 检查保留候选。--all 只适用于 legacy 项目。

             
mancode version
版本
输出已安装 CLI 版本，便于升级检查和提交问题。

           

         
 
         

           
深入研究 /man 工作流

-          
/man 是一个渐进式九步协议：先让决策变得可检查，再由用户选择轻量交接、仅保留计划，或继续治理式执行。每个闸门都由 V3 的 .mancode/<namespace>/workflows/<ULID>/ 文件支撑。

-          
谁来运行这些命令？
安装后的 V3 mode entry 会创建任务并读取 Context Pack。下面展示的是供研究、排错或集成使用的机器契约。V3 使用显式 namespace:ULID TaskRef，不依赖旧的活动指针。

+          
/man 是一个渐进式九步协议：先让决策变得可检查，再由用户选择轻量交接、仅保留计划，或继续治理式执行。每个闸门都由 Continuity 的 .mancode/<namespace>/workflows/<ULID>/ 文件支撑。

+          
谁来运行这些命令？
安装后的 Continuity mode entry 会创建任务并读取 Context Pack。下面展示的是供研究、排错或集成使用的机器契约。Continuity 使用显式 namespace:ULID TaskRef，不依赖旧的活动指针。

 
           
九个步骤与闸门

           
@@ -239,8 +239,8 @@ 
Step 4 的三种决策
三种选择都要求活动中的 man 工作流、已确认需求和 plan.md。使用 workflow plan ... revise 修订计划；每次成功写入都会返回下一个命令需要的 revision。

 
-          
一条合法的 V3 顺序

-          
V3 使用显式 TaskRef 和 expected revision。所有持久化变更都由 CLI 完成；不要手工编辑 metadata，也不要使用 legacy --step 协议。

+          
一条合法的 Continuity 顺序

+          
Continuity 使用显式 TaskRef 和 expected revision。所有持久化变更都由 CLI 完成；不要手工编辑 metadata，也不要使用 legacy --step 协议。
# 创建 actor 和显式 session
 $ mancode team identity create --name "Your name"
 $ mancode context session new --client codex --json
@@ -262,7 +262,7 @@ 
一条合法的 V3 顺序

 
           
自动验证、手工确认与修复后重验

           
步骤Agent 工作持久化闸门

           
           
           

-            
+            
@@ -279,8 +279,8 @@ 
workflow 子命令速查

             
-            
-            
+            
+            
场景必须记录闸门行为
自动验证规范化 verification ledger 记录验收项、命令、退出码、证据摘要与结果。workflow verify ... apply 会拒绝不符合 V3 schema 或 revision 的台账。
自动验证规范化 verification ledger 记录验收项、命令、退出码、证据摘要与结果。workflow verify ... apply 会拒绝不符合 Continuity schema 或 revision 的台账。

             
手工验证台账记录自动化不能判断的原因；只有用户明确确认后才能改为 passed。必需人工证据未完成时，completion 持续阻塞。

             
评审发现规范化 review ledger 保存稳定 blocker ID 及其 remediation 状态。应用 review ledger 会使旧验证失效；评审后、完成前必须 apply 当前验证。

             
用户跳过评审review ledger 记录用户显式决定和残余风险。仍然需要有效 summary 和其余全部门禁。
plan修订计划或确认执行决策。revise --file；confirm --plan-decision；两者都需要 revision 和 session。

             
update改变生命周期状态或阻塞原因。--status --expected-revision --session；治理字段使用专用命令。

             
handoff把已确认的本地计划交给 solo，随后关闭。--to solo 或 --complete，并传 revision 与 session。
verify / review应用规范化 V3 台账。apply --file --expected-revision --session。
list / show / clean列出或检查 V3 TaskRef；clean 不是删除 V3 权威数据的命令。show <namespace:ULID> --json；保留清理使用 context compact --dry-run。
verify / review应用规范化 Continuity 台账。apply --file --expected-revision --session。
list / show / clean列出或检查 Continuity TaskRef；clean 不是删除 Continuity 权威数据的命令。show <namespace:ULID> --json；保留清理使用 context compact --dry-run。

           

         

 
@@ -307,7 +307,7 @@ 
刷新项目上下文

 
         

           
安全卸载

-          
卸载单个平台会保留用户自己编写的 rules、instructions、无关的 Claude settings 和 V3 工作流权威数据。使用 context compact --dry-run 检查可清理的运行时保留记录。

+          
卸载单个平台会保留用户自己编写的 rules、instructions、无关的 Claude settings 和 Continuity 工作流权威数据。使用 context compact --dry-run 检查可清理的运行时保留记录。

           
移除一个适配器

           
$ mancode uninstall cursor --force

           
重装一个适配器

@@ -328,7 +328,7 @@ 
Claude Code hooks 没有触发

           
Cursor rules 没有触发

           
确认 .cursor/rules/mancode-*.mdc 和 .cursor/commands/*.md 都存在。核心上下文与 solo rules 持续生效；高强度规则按描述触发，因此应显式调用生成的模式命令。

           
workflow 命令被拒绝

-          
把拒绝当作流程闸门，而不是元数据损坏。先用 mancode workflow list --json 找到 TaskRef，再用 mancode workflow show <namespace:ULID> --json 检查元数据、revision、aggregate 和 blocker。不要手工编辑 V3 metadata。

+          
把拒绝当作流程闸门，而不是元数据损坏。先用 mancode workflow list --json 找到 TaskRef，再用 mancode workflow show <namespace:ULID> --json 检查元数据、revision、aggregate 和 blocker。不要手工编辑 Continuity metadata。

           
项目事实已经过期

           
添加 Git、manifest、依赖或验证脚本后执行 mancode refresh-project；UI token 改变时执行 refresh-style。只有静态适配器的生成文件需要更新时，才重新安装对应平台。

         

diff --git a/website/index.html b/website/index.html
index f0528b1..58346e7 100644
--- a/website/index.html
+++ b/website/index.html
@@ -439,7 +439,7 @@ 
Stop babysitting
AI bloat.

         中文
         AGPL-3.0
       

-       V3 Beta / v0.3.14
+       Continuity / v0.3.15
     
   
 
diff --git a/website/index.zh-CN.html b/website/index.zh-CN.html
index 37cad6e..a4c72dd 100644
--- a/website/index.zh-CN.html
+++ b/website/index.zh-CN.html
@@ -88,6 +88,6 @@ 
一项任务。
下个会话继续。

 
       
简单任务少一点仪式。
关键任务多一点纪律。
别再替 AI
收拾臃肿。
> npm install -g mancode
GitHub 上查看 ↗

     
-    
+    
   
 

From 7da2016fbfacfae02a6d85767d39b46dd84c8cd2 Mon Sep 17 00:00:00 2001
From: whitelonng 
Date: Mon, 20 Jul 2026 02:55:20 +0800
Subject: [PATCH 4/9] fix: restore git-ref team coordination

---
 README.en.md                          |   6 +-
 README.md                             |   6 +-
 package-lock.json                     |   4 +-
 package.json                          |   2 +-
 src/commands/context.ts               |  15 ++
 src/context/task-head-reconcile.ts    |  49 ++++-
 src/context/workflow-create.ts        |  40 +++-
 src/team/git-ref-operation.ts         |  77 ++++++--
 tests/git-ref-cross-clone-e2e.test.ts | 269 ++++++++++++++++++++++++--
 tests/website-docs.test.ts            |  18 +-
 website/docs.html                     |   2 +-
 website/docs.zh-CN.html               |   2 +-
 website/index.html                    |   2 +-
 website/index.zh-CN.html              |   2 +-
 14 files changed, 439 insertions(+), 55 deletions(-)

diff --git a/README.en.md b/README.en.md
index 96133dc..f789ebe 100644
--- a/README.en.md
+++ b/README.en.md
@@ -17,7 +17,7 @@
 

   License: AGPL-3.0
   npm version
-  Status: mancode Continuity v0.3.15
+  Status: mancode Continuity v0.3.16
   Platforms: Claude Code, Cursor, Codex in ChatGPT desktop and CLI, GitHub Copilot, ZCode
 

 
@@ -353,7 +353,7 @@ it should behave, and why previous decisions were made.
 
 ## Installation
 
-**Status**: mancode Continuity v0.3.15. Claude Code, Cursor, Codex in the ChatGPT
+**Status**: mancode Continuity v0.3.16. Claude Code, Cursor, Codex in the ChatGPT
 desktop app and CLI, GitHub Copilot, and ZCode adapters are included.
 
 Requires Node.js 20 or newer. macOS, Linux, Windows CMD, PowerShell, and Git Bash
@@ -452,7 +452,7 @@ mancode version
 Simplified output:
 
 ```text
-mancode v0.3.15
+mancode v0.3.16
 
 Project:     my-app
 Runtime:     ready
diff --git a/README.md b/README.md
index f453187..f98f441 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@
 

   许可证：AGPL-3.0
   npm 版本
-  状态：mancode Continuity v0.3.15
+  状态：mancode Continuity v0.3.16
   平台：Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI、GitHub Copilot、ZCode
 

 
@@ -307,7 +307,7 @@ src/components/
 
 ## 安装
 
-**状态**：mancode Continuity v0.3.15。Claude Code、Cursor、ChatGPT 桌面端中的
+**状态**：mancode Continuity v0.3.16。Claude Code、Cursor、ChatGPT 桌面端中的
 Codex、Codex CLI、GitHub Copilot 和 ZCode adapter 均已接入。
 
 需要 Node.js 20 或更高版本。原生支持 macOS、Linux、Windows CMD、
@@ -404,7 +404,7 @@ mancode version
 以下是简化输出示例：
 
 ```text
-mancode v0.3.15
+mancode v0.3.16
 
 Project:     my-app
 Runtime:     ready
diff --git a/package-lock.json b/package-lock.json
index ba71130..8ec0e32 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mancode",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mancode",
-      "version": "0.3.15",
+      "version": "0.3.16",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "commander": "^12.1.0",
diff --git a/package.json b/package.json
index 537e599..a5caea0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mancode",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "description": "AI coding agent workflow harness with mancode Continuity for cross-conversation tasks, decisions, verification, and team coordination.",
   "type": "module",
   "license": "AGPL-3.0-only",
diff --git a/src/commands/context.ts b/src/commands/context.ts
index 6092124..9d64da9 100644
--- a/src/commands/context.ts
+++ b/src/commands/context.ts
@@ -55,6 +55,10 @@ import {
   resumeSession,
 } from '../runtime/session.js';
 import { readLocalActor } from '../team/actor.js';
+import {
+  capabilitiesFromGitRefCache,
+  readGitRefTeamCache,
+} from '../team/git-ref-cache.js';
 import {
   listGitRefWorkflowRepairs,
   recoverGitRefWorkflowRepair,
@@ -810,6 +814,16 @@ async function resolveContext(
     projectRoot: project.projectRoot,
     entityHomeStoreContext: project.runtime.entityHomeStoreContext,
   });
+  const capabilities =
+    project.project.config.transport.mode === 'git-ref'
+      ? capabilitiesFromGitRefCache(
+          project.project.config,
+          await readGitRefTeamCache(
+            project.projectRoot,
+            project.project.config,
+          ),
+        )
+      : undefined;
   return resolver.resolve({
     session,
     taskRef: request.taskRef,
@@ -823,6 +837,7 @@ async function resolveContext(
       adapterVersions: project.project.manifest.managedAdapters,
     },
     codeHead: await readCheckoutCodeHead(project.projectRoot),
+    ...(capabilities === undefined ? {} : { capabilities }),
   });
 }
 
diff --git a/src/context/task-head-reconcile.ts b/src/context/task-head-reconcile.ts
index 78d5201..28b1a92 100644
--- a/src/context/task-head-reconcile.ts
+++ b/src/context/task-head-reconcile.ts
@@ -31,15 +31,18 @@ import {
 } from '../runtime/task-operation.js';
 import type { ClaimV1 } from '../team/claims.js';
 import { deriveClaimValidity } from '../team/conflicts.js';
+import { createGitRefTeamManifestStore } from '../team/git-ref-client.js';
 import type { HandoffV1 } from '../team/handoff.js';
+import type { ProjectConfigV1 } from '../team/policy.js';
 import {
   type TaskAggregateManifestV1,
   taskAggregateDigest,
 } from './aggregate.js';
 import { type Ulid, assertUlid, createUlid } from './ids.js';
+import type { SchemaManifestV1 } from './manifest.js';
 import { type StoredTaskSnapshot, V3ContextStore } from './store.js';
 import { assertTaskCodeHeadUnchanged } from './task-mutation.js';
-import { type TaskRef, parseTaskRefValue } from './task-ref.js';
+import { type TaskRef, parseTaskRefValue, sameTaskRef } from './task-ref.js';
 
 const execFile = promisify(execFileCallback);
 
@@ -119,13 +122,19 @@ export async function previewV3TaskHeadReconcile(
     input.projectRoot,
     task.location.taskRoot,
   );
+  const project = await store.readProjectSnapshot();
+  await assertRemoteTaskUnpublished({
+    projectRoot: input.projectRoot,
+    taskRef,
+    config: project.config,
+    manifest: project.manifest,
+  });
   assertReconcileEligible({
     task,
     aggregate,
     previousFence,
     codeHead,
     actorId: input.sessionActorId,
-    transportMode: (await store.readProjectSnapshot()).config.transport.mode,
     claims: coordination.claims,
     handoffs: coordination.handoffs,
     now,
@@ -194,13 +203,18 @@ export async function reconcileV3TaskHead(
     if (reread.fingerprint !== context.task.fingerprint) {
       throw new Error('MANCODE_CONTEXT_STALE');
     }
+    await assertRemoteTaskUnpublished({
+      projectRoot: context.projectRoot,
+      taskRef,
+      config: context.project.config,
+      manifest: context.project.manifest,
+    });
     assertReconcileEligible({
       task: context.task,
       aggregate,
       previousFence,
       codeHead,
       actorId: context.session.actorId,
-      transportMode: context.project.config.transport.mode,
       claims: context.coordination.claims,
       handoffs: context.coordination.handoffs,
       now: context.now,
@@ -396,14 +410,10 @@ function assertReconcileEligible(input: {
   previousFence: TaskHeadFenceV1;
   codeHead: string;
   actorId: Ulid;
-  transportMode: 'local' | 'git-ref';
   claims: ClaimV1[];
   handoffs: HandoffV1[];
   now: Date;
 }): void {
-  if (input.transportMode !== 'local') {
-    throw new Error('MANCODE_GIT_REF_TRANSPORT_NOT_IMPLEMENTED');
-  }
   if (input.task.metadata.ownerActorId !== input.actorId) {
     throw new Error('MANCODE_TASK_OWNER_REQUIRED');
   }
@@ -420,6 +430,31 @@ function assertReconcileEligible(input: {
   assertHandoffsConsistent(input.handoffs);
 }
 
+async function assertRemoteTaskUnpublished(input: {
+  projectRoot: string;
+  taskRef: TaskRef;
+  config: ProjectConfigV1;
+  manifest: SchemaManifestV1;
+}): Promise {
+  if (input.config.transport.mode !== 'git-ref') return;
+  const snapshot = await createGitRefTeamManifestStore(
+    input.projectRoot,
+    input.config,
+    input.manifest,
+  ).pull();
+  const remote = snapshot.manifest;
+  if (remote === null) return;
+  const hasTaskAuthority = [
+    ...remote.ownershipFences,
+    ...remote.taskBundles,
+    ...remote.claims,
+    ...remote.handoffs,
+  ].some((entity) => sameTaskRef(entity.taskRef, input.taskRef));
+  if (hasTaskAuthority) {
+    throw new Error('MANCODE_GIT_REF_TASK_ALREADY_PUBLISHED');
+  }
+}
+
 function assertClaimsConsistent(
   claims: ClaimV1[],
   task: StoredTaskSnapshot,
diff --git a/src/context/workflow-create.ts b/src/context/workflow-create.ts
index 76be0b7..558d440 100644
--- a/src/context/workflow-create.ts
+++ b/src/context/workflow-create.ts
@@ -51,6 +51,11 @@ import { createTaskHeadFence } from '../runtime/task-head-store.js';
 import { readSharedActorProfile } from '../team/actor.js';
 import type { TeamAssessment } from '../team/assessment.js';
 import { createAuthorizationBasis } from '../team/authorization.js';
+import {
+  capabilitiesFromGitRefCache,
+  readGitRefTeamCache,
+} from '../team/git-ref-cache.js';
+import type { ProjectConfigV1 } from '../team/policy.js';
 import { assertTransportCoordinationWriteAllowed } from '../team/transport-migration-freeze.js';
 import { capabilitiesFromProjectConfig } from '../team/transport.js';
 import { VERSION } from '../version.js';
@@ -225,6 +230,7 @@ export async function createV3Workflow(
   if (taskRef.namespace === 'shared') {
     await assertSharedCreationPrerequisites(
       projectRoot,
+      project.config,
       session.actorId,
       input.sharedPrivacyConfirmed === true,
       participants,
@@ -247,6 +253,11 @@ export async function createV3Workflow(
     parent,
     participants,
     explicitScope: input.implementationScope,
+    ownershipEpoch:
+      taskRef.namespace === 'shared' &&
+      project.config.transport.mode === 'git-ref'
+        ? 0
+        : 1,
     timestamp,
   });
   const homeStore = resolveTaskEntityHomeStore(
@@ -527,6 +538,7 @@ async function resolveParentCreationContext(
 
 async function assertSharedCreationPrerequisites(
   projectRoot: string,
+  config: ProjectConfigV1,
   actorId: Ulid,
   privacyConfirmed: boolean,
   participants: readonly Ulid[],
@@ -534,19 +546,40 @@ async function assertSharedCreationPrerequisites(
   if (!privacyConfirmed) {
     throw new Error('MANCODE_PRIVACY_CONFIRMATION_REQUIRED');
   }
-  if ((await readSharedActorProfile(projectRoot, actorId)) === null) {
+  if (!(await actorHasSharedProfile(projectRoot, config, actorId))) {
     throw new Error('MANCODE_JOIN_REQUIRED');
   }
   for (const participantActorId of participants) {
     if (participantActorId === actorId) continue;
     if (
-      (await readSharedActorProfile(projectRoot, participantActorId)) === null
+      !(await actorHasSharedProfile(projectRoot, config, participantActorId))
     ) {
       throw new Error('MANCODE_PARTICIPANT_JOIN_REQUIRED');
     }
   }
 }
 
+async function actorHasSharedProfile(
+  projectRoot: string,
+  config: ProjectConfigV1,
+  actorId: Ulid,
+): Promise {
+  if ((await readSharedActorProfile(projectRoot, actorId)) !== null)
+    return true;
+  if (config.transport.mode !== 'git-ref') return false;
+  const cache = await readGitRefTeamCache(projectRoot, config);
+  if (
+    capabilitiesFromGitRefCache(config, cache).transportFreshness !== 'fresh'
+  ) {
+    throw new Error('MANCODE_TRANSPORT_NOT_FRESH');
+  }
+  return (
+    cache?.manifest?.actorProfiles.some(
+      (profile) => profile.actorId === actorId,
+    ) === true
+  );
+}
+
 async function requireSharedCodeHead(projectRoot: string): Promise {
   const head = await readCheckoutCodeHead(projectRoot);
   if (head === null) throw new Error('MANCODE_TASK_HEAD_CODE_REF_UNAVAILABLE');
@@ -595,6 +628,7 @@ function buildInitialEntities(input: {
   parent: ParentCreationContext | null;
   participants: Ulid[];
   explicitScope: WorkflowCreateScope | undefined;
+  ownershipEpoch: number;
   timestamp: string;
 }): InitialEntities {
   const scope = initialScope(input.parent, input.explicitScope);
@@ -691,7 +725,7 @@ function buildInitialEntities(input: {
     transitionState: 'stable',
     lastOperationId: input.operationId,
     ownerActorId: input.actorId,
-    ownershipEpoch: 1,
+    ownershipEpoch: input.ownershipEpoch,
     participants: input.participants,
     createdBy: {
       actorId: input.actorId,
diff --git a/src/team/git-ref-operation.ts b/src/team/git-ref-operation.ts
index a2dcb04..0739f2c 100644
--- a/src/team/git-ref-operation.ts
+++ b/src/team/git-ref-operation.ts
@@ -13,6 +13,7 @@ import {
   sameTaskRef,
 } from '../context/task-ref.js';
 import { parseWorkflowMetadata } from '../context/workflow-metadata.js';
+import { readOperationJournal } from '../runtime/operation-store.js';
 import { readCheckoutBranch } from '../runtime/project-runtime.js';
 import {
   type OpenedV3TaskOperation,
@@ -203,7 +204,6 @@ export async function syncGitRefTask(
     now,
   });
   try {
-    await assertCleanGitWorktree(context.projectRoot);
     const transport = createGitRefTeamManifestStore(
       context.projectRoot,
       context.project.config,
@@ -211,6 +211,21 @@ export async function syncGitRefTask(
     );
     const snapshot = await transport.pull();
     const bundle = await bundleFromContext(context, now);
+    const remoteTaskPublished =
+      snapshot.manifest?.ownershipFences.some((fence) =>
+        sameTaskRef(fence.taskRef, taskRef),
+      ) === true &&
+      snapshot.manifest.taskBundles.some((remoteBundle) =>
+        sameTaskRef(remoteBundle.taskRef, taskRef),
+      );
+    const taskAuthorityChangesAllowed =
+      remoteTaskPublished &&
+      (remoteBundleMatches(snapshot, bundle) ||
+        (await hasCommittedHandoffCheckpoint(context)));
+    await assertCleanGitWorktree(
+      context.projectRoot,
+      taskAuthorityChangesAllowed ? taskRef : undefined,
+    );
     const result = await synchronizeBundle(
       context,
       transport,
@@ -471,7 +486,7 @@ export async function createGitRefHandoffDraft(
     assertContextMatchesRemoteBundle(context, bundle);
     await Promise.all([
       assertGitRefBundleCodeReachable(context.projectRoot, bundle),
-      assertCleanGitWorktree(context.projectRoot),
+      assertCleanGitWorktree(context.projectRoot, taskRef),
     ]);
     const checkpoint = context.task.latestCheckpoint;
     if (
@@ -571,7 +586,10 @@ export async function mutateGitRefHandoff(
   });
   try {
     if (input.mutation.kind === 'offer') {
-      await assertCleanGitWorktree(opened.context.projectRoot);
+      await assertCleanGitWorktree(
+        opened.context.projectRoot,
+        opened.handoff.taskRef,
+      );
     }
     const kind =
       input.mutation.kind === 'offer'
@@ -848,15 +866,49 @@ function defaultRemoteHandoffSummary(checkpoint: CheckpointV1): HandoffSummary {
   };
 }
 
-async function assertCleanGitWorktree(projectRoot: string): Promise {
-  const { stdout } = await execFile(
-    'git',
-    ['status', '--porcelain=v1', '--untracked-files=all'],
-    { cwd: projectRoot, windowsHide: true },
-  );
+async function assertCleanGitWorktree(
+  projectRoot: string,
+  materializedTaskRef?: TaskRef,
+): Promise {
+  const args = ['status', '--porcelain=v1', '--untracked-files=all'];
+  if (materializedTaskRef !== undefined) {
+    args.push(
+      '--',
+      '.',
+      `:(exclude,top).mancode/shared/workflows/${materializedTaskRef.taskId}/**`,
+    );
+  }
+  const { stdout } = await execFile('git', args, {
+    cwd: projectRoot,
+    windowsHide: true,
+  });
   if (stdout.trim()) throw new Error('MANCODE_HANDOFF_DIRTY_WORKTREE');
 }
 
+async function hasCommittedHandoffCheckpoint(
+  context: OpenedV3TaskOperation,
+): Promise {
+  const checkpoint = context.task.latestCheckpoint;
+  if (
+    checkpoint === null ||
+    checkpoint.kind !== 'handoff_offered' ||
+    context.task.metadata.lastOperationId !== checkpoint.operationId ||
+    context.task.aggregate?.latestCheckpointId !== checkpoint.checkpointId
+  ) {
+    return false;
+  }
+  const journal = await readOperationJournal(
+    context.homeStore,
+    checkpoint.operationId,
+  );
+  return (
+    journal?.type === 'checkpoint_create' &&
+    journal.state === 'committed' &&
+    journal.actorId === context.session.actorId &&
+    journal.sessionId === context.session.sessionId
+  );
+}
+
 function assertPositiveRevision(value: number, label: string): void {
   if (!Number.isSafeInteger(value) || value < 1) {
     throw new Error(`${label} must be a positive integer`);
@@ -883,10 +935,7 @@ async function synchronizeBundle(
   const fence = manifest.ownershipFences.find((candidate) =>
     sameTaskRef(candidate.taskRef, context.taskRef),
   );
-  if (fence === undefined) {
-    throw new Error('MANCODE_TRANSPORT_MIGRATION_REQUIRED');
-  }
-  if (remoteBundleMatches(snapshot, bundle)) {
+  if (fence !== undefined && remoteBundleMatches(snapshot, bundle)) {
     return {
       remoteRevision: manifest.revision,
       ownershipEpoch: fence.ownershipEpoch,
@@ -900,7 +949,7 @@ async function synchronizeBundle(
     actorId: context.session.actorId,
     taskRef: context.taskRef,
     expectedRemoteRevision: manifest.revision,
-    expectedOwnershipEpoch: fence.ownershipEpoch,
+    expectedOwnershipEpoch: fence?.ownershipEpoch ?? 0,
     taskBundle: bundle,
     now,
   });
diff --git a/tests/git-ref-cross-clone-e2e.test.ts b/tests/git-ref-cross-clone-e2e.test.ts
index 7816274..73e4902 100644
--- a/tests/git-ref-cross-clone-e2e.test.ts
+++ b/tests/git-ref-cross-clone-e2e.test.ts
@@ -4,7 +4,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { afterEach, describe, expect, it } from 'vitest';
-import { teamSyncPull } from '../src/commands/team.js';
+import {
+  contextReconcileTaskHead,
+  contextResume,
+} from '../src/commands/context.js';
+import { teamClaim, teamSyncPull, teamSyncPush } from '../src/commands/team.js';
 import { initializeV3Project } from '../src/commands/v3-init.js';
 import { workflow } from '../src/commands/workflow.js';
 import { createV3Checkpoint } from '../src/context/checkpoint-create.js';
@@ -78,6 +82,238 @@ afterEach(async () => {
 });
 
 describe('git-ref coordination across independent clones', () => {
+  it('publishes a newly created git-ref task after its Git commit', async () => {
+    const fixture = await createFixture();
+    const storeA = await strictStore(fixture.cloneA);
+    const [profileA, profileB] = fixture.profiles;
+    if (profileA === undefined || profileB === undefined) {
+      throw new Error('missing fixture actor profiles');
+    }
+    await storeA.publishActorProfile({
+      operationId: id(15),
+      expectedRemoteRevision: 0,
+      profile: profileA,
+    });
+    await storeA.publishActorProfile({
+      operationId: id(16),
+      expectedRemoteRevision: 1,
+      profile: profileB,
+    });
+    await expect(
+      captureJson(() => teamSyncPull(fixture.cloneA, { json: true })),
+    ).resolves.toMatchObject({
+      exitCode: 0,
+      value: { remoteRevision: 2 },
+    });
+    await rm(
+      path.join(
+        fixture.cloneA,
+        '.mancode',
+        'shared',
+        'team',
+        'actors',
+        `${ACTOR_B}.json`,
+      ),
+    );
+
+    const created = await captureJson(() =>
+      workflow(
+        fixture.cloneA,
+        'create',
+        [
+          'manteam',
+          'Publish a new shared task through the public sync sequence.',
+        ],
+        {
+          session: SESSION_A,
+          client: 'vitest-a',
+          participants: [ACTOR_B],
+          confirmShared: true,
+          json: true,
+        },
+      ),
+    );
+    expect(created).toMatchObject({
+      exitCode: 0,
+      value: { metadata: { revision: 1, ownershipEpoch: 0 } },
+    });
+    await publishSharedActorProfile(fixture.cloneA, profileB);
+    const taskRef = created.value.taskRef;
+    const formattedTaskRef = formatTaskRef(taskRef);
+
+    await writeFile(
+      path.join(fixture.cloneA, 'README.md'),
+      '# git-ref cross-clone fixture\n\ncode head\n\nteam task\n',
+    );
+    const dirtyPush = await captureJson(() =>
+      teamSyncPush(fixture.cloneA, {
+        task: formattedTaskRef,
+        expectedTaskRevision: '1',
+        session: SESSION_A,
+        client: 'vitest-a',
+        json: true,
+      }),
+    );
+    expect(dirtyPush).toMatchObject({
+      exitCode: 3,
+      value: { error: { code: 'MANCODE_HANDOFF_DIRTY_WORKTREE' } },
+    });
+
+    const taskRoot = path.join(
+      '.mancode',
+      'shared',
+      'workflows',
+      taskRef.taskId,
+    );
+    await git(fixture.cloneA, ['add', '--force', 'README.md', taskRoot]);
+    await git(fixture.cloneA, ['commit', '-m', 'publish shared task']);
+    const reconciled = await captureJson(() =>
+      contextReconcileTaskHead(fixture.cloneA, formattedTaskRef, {
+        expectedFenceRevision: '1',
+        fromGit: true,
+        session: SESSION_A,
+        client: 'vitest-a',
+        json: true,
+      }),
+    );
+    expect(reconciled.exitCode).toBe(0);
+
+    const synced = await captureJson(() =>
+      teamSyncPush(fixture.cloneA, {
+        task: formattedTaskRef,
+        expectedTaskRevision: '1',
+        session: SESSION_A,
+        client: 'vitest-a',
+        json: true,
+      }),
+    );
+    expect(synced).toMatchObject({
+      exitCode: 0,
+      value: {
+        changed: true,
+        remoteRevision: 3,
+        ownershipEpoch: 0,
+        taskRevision: 1,
+      },
+    });
+    const publishedReconcile = await captureJson(() =>
+      contextReconcileTaskHead(fixture.cloneA, formattedTaskRef, {
+        expectedFenceRevision: '2',
+        fromGit: true,
+        session: SESSION_A,
+        client: 'vitest-a',
+        json: true,
+      }),
+    );
+    expect(publishedReconcile).toMatchObject({
+      exitCode: 3,
+      value: { error: { code: 'MANCODE_GIT_REF_TASK_ALREADY_PUBLISHED' } },
+    });
+
+    await git(fixture.cloneA, ['push', 'origin', 'main']);
+    await git(fixture.cloneB, ['fetch', 'origin']);
+    await git(fixture.cloneB, ['merge', '--ff-only', 'origin/main']);
+    const pulled = await captureJson(() =>
+      teamSyncPull(fixture.cloneB, {
+        task: formattedTaskRef,
+        json: true,
+      }),
+    );
+    expect(pulled).toMatchObject({
+      exitCode: 0,
+      value: {
+        remoteRevision: 3,
+        materializedBundles: [{ status: 'unchanged' }],
+      },
+    });
+    const resumed = await captureJson(() =>
+      contextResume(fixture.cloneB, formattedTaskRef, {
+        session: SESSION_B,
+        client: 'vitest-b',
+        json: true,
+      }),
+    );
+    expect(resumed).toMatchObject({
+      exitCode: 0,
+      value: { taskRef, taskRevision: 1 },
+    });
+
+    const unconfirmedClaim = await captureJson(() =>
+      teamClaim(fixture.cloneB, {
+        task: formattedTaskRef,
+        expectedTaskRevision: '1',
+        paths: ['src/**'],
+        session: SESSION_B,
+        client: 'vitest-b',
+        sync: true,
+        json: true,
+      }),
+    );
+    expect(unconfirmedClaim).toMatchObject({
+      exitCode: 3,
+      value: {
+        error: { code: 'MANCODE_MANTEAM_PLAN_CONFIRMATION_REQUIRED' },
+      },
+    });
+    await expect(
+      new V3ContextStore(fixture.cloneB).readTaskSnapshot(taskRef),
+    ).resolves.toMatchObject({
+      metadata: { revision: 1, ownershipEpoch: 0 },
+    });
+
+    const checkpoint = await createV3Checkpoint({
+      projectRoot: fixture.cloneA,
+      taskRef,
+      sessionId: SESSION_A,
+      expectedTaskRevision: 1,
+      kind: 'handoff_offered',
+      summary: 'Publish a journaled handoff checkpoint after initial sync.',
+      nextAction: 'Pull the successor bundle in the second clone.',
+      checkpointId: id(17),
+      operationId: id(18),
+      now: at(3),
+    });
+    expect(
+      await gitOutput(fixture.cloneA, [
+        'status',
+        '--porcelain=v1',
+        '--untracked-files=all',
+      ]),
+    ).toContain(taskRoot);
+    const updatedSync = await captureJson(() =>
+      teamSyncPush(fixture.cloneA, {
+        task: formattedTaskRef,
+        expectedTaskRevision: String(checkpoint.metadata.revision),
+        session: SESSION_A,
+        client: 'vitest-a',
+        json: true,
+      }),
+    );
+    expect(updatedSync).toMatchObject({
+      exitCode: 0,
+      value: {
+        remoteRevision: 4,
+        taskRevision: checkpoint.metadata.revision,
+        ownershipEpoch: 0,
+      },
+    });
+    const updatedPull = await captureJson(() =>
+      teamSyncPull(fixture.cloneB, { task: formattedTaskRef, json: true }),
+    );
+    expect(updatedPull).toMatchObject({
+      exitCode: 0,
+      value: {
+        remoteRevision: 4,
+        materializedBundles: [
+          {
+            status: 'updated',
+            taskRevision: checkpoint.metadata.revision,
+          },
+        ],
+      },
+    });
+  }, 20_000);
+
   it('fences claims, materializes a quarantined bundle, and transfers ownership once', async () => {
     const fixture = await createFixture();
     const created = await createRemoteTask(fixture.cloneA, fixture.codeHead);
@@ -119,7 +355,7 @@ describe('git-ref coordination across independent clones', () => {
     });
     expect(claim).toMatchObject({
       remoteRevision: 2,
-      ownershipEpoch: 1,
+      ownershipEpoch: 0,
       claim: { state: 'active', ownerActorId: ACTOR_A },
     });
 
@@ -267,7 +503,7 @@ describe('git-ref coordination across independent clones', () => {
         actorId: ACTOR_A,
         taskRef: created.taskRef,
         expectedRemoteRevision: beforeAcceptManifest.revision,
-        expectedOwnershipEpoch: 1,
+        expectedOwnershipEpoch: 0,
         claimId: claim.claim.claimId,
         expectedClaimRevision: 1,
         expiresAt: at(2 * 24 * 60).toISOString(),
@@ -289,11 +525,11 @@ describe('git-ref coordination across independent clones', () => {
     expect(preparedRemoteRevision).toBe(5);
     expect(accepted).toMatchObject({
       remoteRevision: 5,
-      ownershipEpoch: 2,
+      ownershipEpoch: 1,
       handoff: { state: 'accepted', revision: 3 },
       taskBundle: {
         taskRevision: initialBundle.taskRevision + 2,
-        ownershipEpoch: 2,
+        ownershipEpoch: 1,
       },
       forwardRepair: { remoteRevision: 5, ownerActorId: ACTOR_B },
     });
@@ -303,13 +539,13 @@ describe('git-ref coordination across independent clones', () => {
       manifest: {
         revision: 5,
         ownershipFences: [
-          { ownerActorId: ACTOR_B, ownershipEpoch: 2, remoteRevision: 5 },
+          { ownerActorId: ACTOR_B, ownershipEpoch: 1, remoteRevision: 5 },
         ],
         receipts: expect.arrayContaining([
           expect.objectContaining({
             operationId: id(31),
             remoteRevision: 5,
-            ownershipEpoch: 2,
+            ownershipEpoch: 1,
           }),
         ]),
       },
@@ -319,7 +555,7 @@ describe('git-ref coordination across independent clones', () => {
     ).resolves.toMatchObject({
       metadata: {
         ownerActorId: ACTOR_B,
-        ownershipEpoch: 2,
+        ownershipEpoch: 1,
         revision: initialBundle.taskRevision + 2,
         transitionState: 'stable',
       },
@@ -460,7 +696,7 @@ describe('git-ref coordination across independent clones', () => {
           { taskRevision: blocked.metadata.revision, lastOperationId: id(45) },
         ],
         taskBundles: [
-          { taskRevision: blocked.metadata.revision, ownershipEpoch: 1 },
+          { taskRevision: blocked.metadata.revision, ownershipEpoch: 0 },
         ],
       },
     });
@@ -922,9 +1158,9 @@ async function setGitRefConfig(projectRoot: string): Promise {
   );
 }
 
-async function captureJson(
+async function captureJson = SyncPullJson>(
   action: () => Promise,
-): Promise<{ exitCode: number; value: SyncPullJson }> {
+): Promise<{ exitCode: number; value: T }> {
   const writes: string[] = [];
   const previous = console.log;
   console.log = (value: unknown) => writes.push(String(value));
@@ -932,7 +1168,7 @@ async function captureJson(
     const exitCode = await action();
     return {
       exitCode,
-      value: JSON.parse(writes.at(-1) ?? '{}') as SyncPullJson,
+      value: JSON.parse(writes.at(-1) ?? '{}') as T,
     };
   } finally {
     console.log = previous;
@@ -945,6 +1181,15 @@ interface SyncPullJson extends Record {
   >;
 }
 
+interface CommandJson extends Record {
+  error?: { code: string };
+}
+
+interface WorkflowCreateJson extends CommandJson {
+  taskRef: { namespace: 'shared'; taskId: Ulid };
+  metadata: { revision: number; ownershipEpoch: number };
+}
+
 interface WorkflowCompletionJson extends Record {
   metadata: {
     revision: number;
diff --git a/tests/website-docs.test.ts b/tests/website-docs.test.ts
index 2583a8f..686ca72 100644
--- a/tests/website-docs.test.ts
+++ b/tests/website-docs.test.ts
@@ -9,6 +9,13 @@ async function readPage(name: string): Promise {
   return readFile(path.join(website, name), 'utf8');
 }
 
+async function readPackageVersion(): Promise {
+  const packageJson = JSON.parse(
+    await readFile(path.join(root, 'package.json'), 'utf8'),
+  ) as { version: string };
+  return packageJson.version;
+}
+
 function internalAnchors(html: string): string[] {
   return [...html.matchAll(/href="#([^"]+)"/g)].map((match) => match[1]);
 }
@@ -145,8 +152,9 @@ describe('website documentation', () => {
     expect(chinese).toContain('代码，避免');
     expect(chinese).toContain('AI 屎山。');
     expect(chinese).toContain('预览适配器');
-    expect(english).toContain('Continuity / v0.3.15');
-    expect(chinese).toContain('Continuity / v0.3.15');
+    const version = await readPackageVersion();
+    expect(english).toContain(`Continuity / v${version}`);
+    expect(chinese).toContain(`Continuity / v${version}`);
   });
 
   it('documents the cross-session boundary in both languages', async () => {
@@ -160,16 +168,14 @@ describe('website documentation', () => {
   });
 
   it('keeps version labels aligned with package.json', async () => {
-    const packageJson = JSON.parse(
-      await readFile(path.join(root, 'package.json'), 'utf8'),
-    ) as { version: string };
+    const version = await readPackageVersion();
     for (const name of [
       'index.html',
       'index.zh-CN.html',
       'docs.html',
       'docs.zh-CN.html',
     ]) {
-      expect(await readPage(name)).toContain(`v${packageJson.version}`);
+      expect(await readPage(name)).toContain(`v${version}`);
     }
   });
 });
diff --git a/website/docs.html b/website/docs.html
index ec1fc11..5b32e8d 100644
--- a/website/docs.html
+++ b/website/docs.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      Documentation / v0.3.15
+      Documentation / v0.3.16
       

         Website
         GitHub
diff --git a/website/docs.zh-CN.html b/website/docs.zh-CN.html
index 0a6c3b0..02f2a7c 100644
--- a/website/docs.zh-CN.html
+++ b/website/docs.zh-CN.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      文档 / v0.3.15
+      文档 / v0.3.16
       

         官网
         GitHub
diff --git a/website/index.html b/website/index.html
index 58346e7..d1a1eeb 100644
--- a/website/index.html
+++ b/website/index.html
@@ -439,7 +439,7 @@ 
Stop babysitting
AI bloat.

         中文
         AGPL-3.0
       

-       Continuity / v0.3.15
+       Continuity / v0.3.16
     
   
 
diff --git a/website/index.zh-CN.html b/website/index.zh-CN.html
index a4c72dd..9c3d691 100644
--- a/website/index.zh-CN.html
+++ b/website/index.zh-CN.html
@@ -88,6 +88,6 @@ 
一项任务。
下个会话继续。

 
       
简单任务少一点仪式。
关键任务多一点纪律。
别再替 AI
收拾臃肿。
> npm install -g mancode
GitHub 上查看 ↗

     
-    
+    
   
 

From 9129a96a74d8e172e0d767850fb50ac52e686b38 Mon Sep 17 00:00:00 2001
From: whitelonng 
Date: Mon, 20 Jul 2026 13:24:55 +0800
Subject: [PATCH 5/9] fix: harden cross-clone team synchronization

---
 package-lock.json                             |   4 +-
 package.json                                  |   2 +-
 src/runtime/task-operation.ts                 |  55 +++-
 src/team/git-ref-bundle.ts                    | 107 ++++++-
 src/team/git-ref-coordination.ts              |  72 ++++-
 src/team/git-ref-materialization.ts           |  39 ++-
 src/team/git-ref-operation.ts                 |  68 ++++
 src/team/git-ref-task-base.ts                 | 198 ++++++++++++
 src/team/git-ref-transport.ts                 |  14 +-
 src/team/git-ref-workflow-operation.ts        |   4 +
 tests/git-ref-coordination-contracts.test.ts  | 101 ++++++
 tests/git-ref-cross-clone-e2e.test.ts         | 294 +++++++++++++++++-
 ...t-ref-manifest-authority-contracts.test.ts |   3 +
 .../git-ref-materialization-contracts.test.ts |  59 ++++
 14 files changed, 998 insertions(+), 22 deletions(-)
 create mode 100644 src/team/git-ref-task-base.ts

diff --git a/package-lock.json b/package-lock.json
index 8ec0e32..9023ea3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mancode",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mancode",
-      "version": "0.3.16",
+      "version": "0.3.17",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "commander": "^12.1.0",
diff --git a/package.json b/package.json
index a5caea0..0c8c290 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mancode",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "description": "AI coding agent workflow harness with mancode Continuity for cross-conversation tasks, decisions, verification, and team coordination.",
   "type": "module",
   "license": "AGPL-3.0-only",
diff --git a/src/runtime/task-operation.ts b/src/runtime/task-operation.ts
index 0395dd4..ebe1102 100644
--- a/src/runtime/task-operation.ts
+++ b/src/runtime/task-operation.ts
@@ -1,5 +1,8 @@
+import { execFile as execFileCallback } from 'node:child_process';
 import { lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { promisify } from 'node:util';
+import { taskAggregateDigest } from '../context/aggregate.js';
 import { assertCompatibilityGate } from '../context/compatibility.js';
 import { type Ulid, assertUlid, createUlid } from '../context/ids.js';
 import { scanLegacyAuthority } from '../context/layout.js';
@@ -79,6 +82,8 @@ import {
 import { type SessionStateV1, readSession } from './session.js';
 import { assertTaskHeadFenceMatchesAggregate } from './task-head-fence.js';
 
+const execFile = promisify(execFileCallback);
+
 export interface OpenV3TaskOperationInput {
   projectRoot: string;
   taskRef: TaskRef;
@@ -216,11 +221,22 @@ export async function openV3TaskOperation(
         throw new Error('MANCODE_TASK_HEAD_FENCE_MISSING');
       }
       if (input.allowTaskHeadFenceMismatch !== true) {
-        assertTaskHeadFenceMatchesAggregate(
-          coordination.taskHeadFence,
-          task.aggregate,
-          codeHead,
-        );
+        try {
+          assertTaskHeadFenceMatchesAggregate(
+            coordination.taskHeadFence,
+            task.aggregate,
+            codeHead,
+          );
+        } catch (error) {
+          await assertOwnerCodeHeadAdvance({
+            projectRoot,
+            task,
+            fence: coordination.taskHeadFence,
+            codeHead,
+            actorId: session.actorId,
+            originalError: error,
+          });
+        }
       }
     }
     return {
@@ -251,6 +267,35 @@ export async function openV3TaskOperation(
   }
 }
 
+async function assertOwnerCodeHeadAdvance(input: {
+  projectRoot: string;
+  task: StoredTaskSnapshot;
+  fence: NonNullable;
+  codeHead: string;
+  actorId: Ulid;
+  originalError: unknown;
+}): Promise {
+  const { task, fence } = input;
+  if (
+    task.aggregate === null ||
+    task.metadata.ownerActorId !== input.actorId ||
+    fence.taskRevision !== task.metadata.revision ||
+    fence.ownershipEpoch !== task.metadata.ownershipEpoch ||
+    fence.aggregateDigest !== taskAggregateDigest(task.aggregate)
+  ) {
+    throw input.originalError;
+  }
+  try {
+    await execFile(
+      'git',
+      ['merge-base', '--is-ancestor', fence.codeRef.head, input.codeHead],
+      { cwd: input.projectRoot, windowsHide: true },
+    );
+  } catch {
+    throw input.originalError;
+  }
+}
+
 /**
  * A child may continue to be read for diagnosis after its parent changes, but
  * no child mutation may race ahead of the parent snapshot it was created from.
diff --git a/src/team/git-ref-bundle.ts b/src/team/git-ref-bundle.ts
index d3aed09..e90ebac 100644
--- a/src/team/git-ref-bundle.ts
+++ b/src/team/git-ref-bundle.ts
@@ -1,10 +1,15 @@
 import { execFile as execFileCallback } from 'node:child_process';
-import { lstat, mkdir, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { digestCanonicalJson } from '../context/canonical.js';
 import type { StoredTaskSnapshot } from '../context/store.js';
-import { formatTaskRef } from '../context/task-ref.js';
+import {
+  type TaskRef,
+  formatTaskRef,
+  parseTaskRefValue,
+  sameTaskRef,
+} from '../context/task-ref.js';
 import {
   type GitRefJsonValue,
   type GitRefTaskBundleArtifactKind,
@@ -139,6 +144,81 @@ export async function quarantineGitRefTaskBundle(
   return target;
 }
 
+export async function readQuarantinedGitRefTaskBundle(
+  projectRoot: string,
+  remoteRevision: number,
+  taskRef: TaskRef,
+  expected: {
+    taskRevision: number;
+    aggregateDigest: string;
+    ownershipEpoch: number;
+    codeRefHead: string;
+  },
+): Promise {
+  if (!Number.isSafeInteger(remoteRevision) || remoteRevision < 1) {
+    throw new Error('MANCODE_TRANSPORT_REVISION_INVALID');
+  }
+  const parsedTaskRef = parseTaskRefValue(taskRef);
+  const directory = path.join(
+    path.resolve(projectRoot),
+    '.mancode',
+    'local',
+    'quarantine',
+    'git-ref',
+    parsedTaskRef.taskId,
+    String(remoteRevision),
+  );
+  let entries: string[];
+  try {
+    await assertFixedDirectory(projectRoot, [
+      '.mancode',
+      'local',
+      'quarantine',
+      'git-ref',
+      parsedTaskRef.taskId,
+      String(remoteRevision),
+    ]);
+    entries = await readdir(directory);
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    throw error;
+  }
+  const matches: GitRefTaskBundleV1[] = [];
+  for (const entry of entries.sort()) {
+    if (!/^[a-f0-9]{64}\.json$/.test(entry)) continue;
+    const target = path.join(directory, entry);
+    const before = await lstat(target);
+    if (!before.isFile() || before.isSymbolicLink()) {
+      throw new Error('MANCODE_ARTIFACT_PATH_UNSAFE');
+    }
+    const bundle = parseGitRefTaskBundle(
+      JSON.parse(await readFile(target, 'utf8')),
+    );
+    const after = await lstat(target);
+    if (
+      !after.isFile() ||
+      after.isSymbolicLink() ||
+      before.dev !== after.dev ||
+      before.ino !== after.ino
+    ) {
+      throw new Error('MANCODE_ARTIFACT_PATH_UNSAFE');
+    }
+    if (
+      sameTaskRef(bundle.taskRef, parsedTaskRef) &&
+      bundle.taskRevision === expected.taskRevision &&
+      bundle.aggregateDigest === expected.aggregateDigest &&
+      bundle.ownershipEpoch === expected.ownershipEpoch &&
+      bundle.codeRef.head === expected.codeRefHead
+    ) {
+      matches.push(bundle);
+    }
+  }
+  if (matches.length > 1) {
+    throw new Error('MANCODE_TRANSPORT_CACHE_CORRUPT');
+  }
+  return matches[0] ?? null;
+}
+
 function artifact(
   kind: GitRefTaskBundleArtifactKind,
   relativePath: string,
@@ -185,6 +265,20 @@ async function ensureFixedDirectory(
   }
 }
 
+async function assertFixedDirectory(
+  projectRoot: string,
+  segments: string[],
+): Promise {
+  let current = path.resolve(projectRoot);
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    const entry = await lstat(current);
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+      throw new Error('MANCODE_ARTIFACT_PATH_UNSAFE');
+    }
+  }
+}
+
 function isAlreadyExists(error: unknown): error is NodeJS.ErrnoException {
   return (
     typeof error === 'object' &&
@@ -193,3 +287,12 @@ function isAlreadyExists(error: unknown): error is NodeJS.ErrnoException {
     (error as NodeJS.ErrnoException).code === 'EEXIST'
   );
 }
+
+function isNotFound(error: unknown): error is NodeJS.ErrnoException {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error as NodeJS.ErrnoException).code === 'ENOENT'
+  );
+}
diff --git a/src/team/git-ref-coordination.ts b/src/team/git-ref-coordination.ts
index 3c1e789..f59e5a1 100644
--- a/src/team/git-ref-coordination.ts
+++ b/src/team/git-ref-coordination.ts
@@ -60,6 +60,7 @@ export type PrepareGitRefCoordinationMutationInput = BaseGitRefMutation &
   (
     | {
         kind: 'ownership_fence';
+        expectedPredecessorBundleDigest: string | null;
         taskBundle: GitRefTaskBundleV1;
       }
     | {
@@ -172,7 +173,11 @@ export function prepareGitRefCoordinationMutation(
   const context = openMutationContext(manifest, input);
   switch (input.kind) {
     case 'ownership_fence':
-      return prepareOwnershipFence(context, input.taskBundle);
+      return prepareOwnershipFence(
+        context,
+        input.taskBundle,
+        input.expectedPredecessorBundleDigest,
+      );
     case 'claim_acquire':
       return prepareClaimAcquire(
         context,
@@ -324,6 +329,7 @@ function openMutationContext(
 function prepareOwnershipFence(
   context: MutationContext,
   taskBundle: GitRefTaskBundleV1,
+  expectedPredecessorBundleDigest: string | null,
 ): PreparedGitRefCoordinationMutation {
   const metadata = metadataFromBundle(taskBundle);
   assertRemoteTaskEligible(metadata);
@@ -331,6 +337,12 @@ function prepareOwnershipFence(
   if (metadata.ownerActorId === null) {
     throw new Error('MANCODE_TASK_OWNER_REQUIRED');
   }
+  if (
+    (context.taskBundle?.bundleDigest ?? null) !==
+    expectedPredecessorBundleDigest
+  ) {
+    throw new Error('MANCODE_TASK_BUNDLE_DIVERGED');
+  }
   if (context.fence === null) {
     if (
       metadata.ownerActorId !== context.input.actorId ||
@@ -351,17 +363,64 @@ function prepareOwnershipFence(
       throw new Error('MANCODE_TASK_REVISION_CONFLICT');
     }
     if (taskBundle.taskRevision === context.fence.taskRevision) {
+      if (taskBundle.aggregateDigest !== context.fence.aggregateDigest) {
+        throw new Error('MANCODE_SPLIT_BRAIN');
+      }
       if (
-        taskBundle.aggregateDigest !== context.fence.aggregateDigest ||
-        taskBundle.codeRef.head !== context.taskBundle?.codeRef.head
+        taskBundle.codeRef.branch !== context.taskBundle?.codeRef.branch ||
+        taskBundle.codeRef.head === context.taskBundle?.codeRef.head
       ) {
-        throw new Error('MANCODE_SPLIT_BRAIN');
+        throw new Error('MANCODE_REMOTE_FENCE_NO_CHANGE');
       }
-      throw new Error('MANCODE_REMOTE_FENCE_NO_CHANGE');
+      return prepared(
+        context,
+        buildFence(context, taskBundle, metadata.ownerActorId),
+        refreshOwnerClaimsForCodeRef(context, taskBundle, metadata),
+        context.handoffs,
+        taskBundle,
+      );
     }
   }
+  const codeHeadChanged =
+    context.taskBundle !== null &&
+    (taskBundle.codeRef.branch !== context.taskBundle.codeRef.branch ||
+      taskBundle.codeRef.head !== context.taskBundle.codeRef.head);
   const fence = buildFence(context, taskBundle, metadata.ownerActorId);
-  return prepared(context, fence, context.claims, context.handoffs, taskBundle);
+  return prepared(
+    context,
+    fence,
+    codeHeadChanged
+      ? refreshOwnerClaimsForCodeRef(context, taskBundle, metadata)
+      : context.claims,
+    context.handoffs,
+    taskBundle,
+  );
+}
+
+function refreshOwnerClaimsForCodeRef(
+  context: MutationContext,
+  taskBundle: GitRefTaskBundleV1,
+  metadata: WorkflowMetadataV3,
+): ClaimV1[] {
+  return context.claims.map((claim) => {
+    if (
+      claim.state !== 'active' ||
+      claim.ownerActorId !== context.input.actorId ||
+      Date.parse(claim.expiresAt) <= context.now.getTime() ||
+      claim.ownershipEpochAtAcquire !== taskBundle.ownershipEpoch ||
+      claim.implementationScopeDigest !== metadata.implementationScope.digest
+    ) {
+      return claim;
+    }
+    const next = bindClaim(context, {
+      ...claim,
+      revision: claim.revision + 1,
+      lastValidatedTaskRevision: taskBundle.taskRevision,
+      lastValidatedCodeRef: taskBundle.codeRef,
+    });
+    assertClaimTransition(claim, next);
+    return next;
+  });
 }
 
 function prepareClaimAcquire(
@@ -890,6 +949,7 @@ function prepared(
     claims: claims.map(parseClaim).sort(compareClaims),
     handoffs: handoffs.map(parseHandoff).sort(compareHandoffs),
     taskBundle,
+    expectedTaskBundleDigest: context.taskBundle?.bundleDigest ?? null,
     forwardRepair: null,
   };
 }
diff --git a/src/team/git-ref-materialization.ts b/src/team/git-ref-materialization.ts
index 619c998..a9e098d 100644
--- a/src/team/git-ref-materialization.ts
+++ b/src/team/git-ref-materialization.ts
@@ -31,6 +31,11 @@ import {
   readTaskHeadFence,
   replaceTaskHeadFence,
 } from '../runtime/task-head-store.js';
+import { readQuarantinedGitRefTaskBundle } from './git-ref-bundle.js';
+import {
+  readGitRefTaskRemoteBase,
+  recordGitRefTaskRemoteBase,
+} from './git-ref-task-base.js';
 import {
   type GitRefOwnershipFenceV1,
   type GitRefTaskBundleArtifactV1,
@@ -127,16 +132,39 @@ export async function materializeGitRefTaskBundle(
     );
     const current = await readLocalTaskOrNull(projectRoot, bundle);
     const currentFence = await readTaskHeadFence(store, bundle.taskRef);
+    const recordedBase = await readGitRefTaskRemoteBase(
+      projectRoot,
+      bundle.taskRef,
+    );
+    const quarantinedBase =
+      recordedBase === null &&
+      currentFence !== null &&
+      currentFence.remoteRevision !== null
+        ? await readQuarantinedGitRefTaskBundle(
+            projectRoot,
+            currentFence.remoteRevision,
+            bundle.taskRef,
+            {
+              taskRevision: currentFence.taskRevision,
+              aggregateDigest: currentFence.aggregateDigest,
+              ownershipEpoch: currentFence.ownershipEpoch,
+              codeRefHead: currentFence.codeRef.head,
+            },
+          )
+        : null;
+    const effectivePredecessor =
+      recordedBase?.bundle ?? quarantinedBase ?? predecessor;
     const status = classifyMaterialization(
       current,
       bundle,
-      predecessor,
+      effectivePredecessor,
       pendingMetadata,
     );
     if (status === 'created' && currentFence !== null) {
       throw new Error('MANCODE_SPLIT_BRAIN');
     }
-    const materializedPredecessor = status === 'created' ? null : predecessor;
+    const materializedPredecessor =
+      status === 'created' ? null : effectivePredecessor;
     const targetFence = buildTargetFence({
       runtime,
       remoteRevision,
@@ -148,6 +176,7 @@ export async function materializeGitRefTaskBundle(
     });
     if (status === 'unchanged') {
       await writeTargetFence(store, currentFence, targetFence, predecessor);
+      await recordGitRefTaskRemoteBase(projectRoot, remoteRevision, bundle);
       return result(status, bundle, null, targetFence);
     }
     const timestamp = now.toISOString();
@@ -168,6 +197,7 @@ export async function materializeGitRefTaskBundle(
     journal = { ...journal, state: 'applying', updatedAt: timestamp };
     await replaceJournal(projectRoot, journal);
     await applyJournal(projectRoot, journal);
+    await recordGitRefTaskRemoteBase(projectRoot, remoteRevision, bundle);
     journal = {
       ...journal,
       state: 'committed',
@@ -231,6 +261,11 @@ async function recoverTaskMaterializationsWhileLocked(
       continue;
     }
     await applyJournal(projectRoot, journal);
+    await recordGitRefTaskRemoteBase(
+      projectRoot,
+      journal.remoteRevision,
+      journal.targetBundle,
+    );
     await replaceJournal(projectRoot, {
       ...journal,
       state: 'committed',
diff --git a/src/team/git-ref-operation.ts b/src/team/git-ref-operation.ts
index 0739f2c..4971416 100644
--- a/src/team/git-ref-operation.ts
+++ b/src/team/git-ref-operation.ts
@@ -38,6 +38,10 @@ import {
   type GitRefOwnershipForwardRepairV1,
   prepareGitRefCoordinationMutation,
 } from './git-ref-coordination.js';
+import {
+  readGitRefTaskRemoteBase,
+  recordGitRefTaskRemoteBase,
+} from './git-ref-task-base.js';
 import {
   type GitRefTaskBundleV1,
   type GitRefTeamManifestSnapshot,
@@ -211,6 +215,10 @@ export async function syncGitRefTask(
     );
     const snapshot = await transport.pull();
     const bundle = await bundleFromContext(context, now);
+    const remoteBase = await readGitRefTaskRemoteBase(
+      context.projectRoot,
+      taskRef,
+    );
     const remoteTaskPublished =
       snapshot.manifest?.ownershipFences.some((fence) =>
         sameTaskRef(fence.taskRef, taskRef),
@@ -231,6 +239,7 @@ export async function syncGitRefTask(
       transport,
       snapshot,
       bundle,
+      remoteBase?.bundle ?? null,
       operationId,
       now,
     );
@@ -240,6 +249,12 @@ export async function syncGitRefTask(
       context.project.config,
       refreshed,
     );
+    const refreshedManifest = requireRemoteManifest(refreshed);
+    await recordGitRefTaskRemoteBase(
+      context.projectRoot,
+      refreshedManifest.revision,
+      requireRemoteBundle(refreshedManifest, taskRef),
+    );
     return { bundle, ...result };
   } finally {
     await context.release();
@@ -275,6 +290,10 @@ export async function acquireGitRefClaim(
     );
     let snapshot = await transport.pull();
     const bundle = await bundleFromContext(context, now);
+    const remoteBase = await readGitRefTaskRemoteBase(
+      context.projectRoot,
+      taskRef,
+    );
     if (!remoteBundleMatches(snapshot, bundle)) {
       await assertCleanGitWorktree(context.projectRoot);
       const bootstrapOperationId = createUlid(now.getTime());
@@ -283,6 +302,7 @@ export async function acquireGitRefClaim(
         transport,
         snapshot,
         bundle,
+        remoteBase?.bundle ?? null,
         bootstrapOperationId,
         now,
       );
@@ -290,6 +310,11 @@ export async function acquireGitRefClaim(
     }
     const manifest = requireRemoteManifest(snapshot);
     const fence = requireRemoteFence(manifest, taskRef);
+    await recordGitRefTaskRemoteBase(
+      context.projectRoot,
+      manifest.revision,
+      requireRemoteBundle(manifest, taskRef),
+    );
     const remote = context.project.config.transport.remote;
     if (remote === null) throw new Error('MANCODE_TRANSPORT_UNAVAILABLE');
     const remoteIdentityHash = await resolveGitRefRemoteIdentityHash(
@@ -326,6 +351,11 @@ export async function acquireGitRefClaim(
       context.project.config,
       refreshed,
     );
+    await recordGitRefTaskRemoteBase(
+      context.projectRoot,
+      requireRemoteManifest(refreshed).revision,
+      requireRemoteBundle(requireRemoteManifest(refreshed), taskRef),
+    );
     const claim = requireRemoteManifest(refreshed).claims.find(
       (candidate) => candidate.claimId === claimId,
     );
@@ -928,6 +958,7 @@ async function synchronizeBundle(
   transport: GitRefTeamManifestStore,
   snapshot: GitRefTeamManifestSnapshot,
   bundle: GitRefTaskBundleV1,
+  remoteBase: GitRefTaskBundleV1 | null,
   operationId: Ulid,
   now: Date,
 ): Promise> {
@@ -943,6 +974,22 @@ async function synchronizeBundle(
       changed: false,
     };
   }
+  if (fence !== undefined && fence.ownerActorId !== context.session.actorId) {
+    throw new Error('MANCODE_TASK_OWNER_REQUIRED');
+  }
+  const remoteBundle =
+    fence === undefined ? null : requireRemoteBundle(manifest, context.taskRef);
+  if (
+    (remoteBundle === null) !== (remoteBase === null) ||
+    (remoteBundle !== null &&
+      (remoteBase === null ||
+        remoteBundle.bundleDigest !== remoteBase.bundleDigest))
+  ) {
+    throw new Error('MANCODE_TASK_BUNDLE_DIVERGED');
+  }
+  if (remoteBundle !== null) {
+    await assertCodeRefFastForward(context.projectRoot, remoteBundle, bundle);
+  }
   const mutation = prepareGitRefCoordinationMutation(manifest, {
     kind: 'ownership_fence',
     operationId,
@@ -950,6 +997,7 @@ async function synchronizeBundle(
     taskRef: context.taskRef,
     expectedRemoteRevision: manifest.revision,
     expectedOwnershipEpoch: fence?.ownershipEpoch ?? 0,
+    expectedPredecessorBundleDigest: remoteBundle?.bundleDigest ?? null,
     taskBundle: bundle,
     now,
   });
@@ -1036,6 +1084,26 @@ function remoteBundleMatches(
   );
 }
 
+async function assertCodeRefFastForward(
+  projectRoot: string,
+  previous: GitRefTaskBundleV1,
+  next: GitRefTaskBundleV1,
+): Promise {
+  if (previous.codeRef.branch !== next.codeRef.branch) {
+    throw new Error('MANCODE_TASK_BUNDLE_DIVERGED');
+  }
+  if (previous.codeRef.head === next.codeRef.head) return;
+  try {
+    await execFile(
+      'git',
+      ['merge-base', '--is-ancestor', previous.codeRef.head, next.codeRef.head],
+      { cwd: projectRoot, windowsHide: true },
+    );
+  } catch {
+    throw new Error('MANCODE_TASK_BUNDLE_DIVERGED');
+  }
+}
+
 function requireRemoteManifest(snapshot: GitRefTeamManifestSnapshot) {
   if (snapshot.manifest === null) {
     throw new Error('MANCODE_TRANSPORT_ACTOR_NOT_JOINED');
diff --git a/src/team/git-ref-task-base.ts b/src/team/git-ref-task-base.ts
new file mode 100644
index 0000000..88a18e1
--- /dev/null
+++ b/src/team/git-ref-task-base.ts
@@ -0,0 +1,198 @@
+import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { type Ulid, assertUlid } from '../context/ids.js';
+import {
+  type TaskRef,
+  parseTaskRefValue,
+  sameTaskRef,
+} from '../context/task-ref.js';
+import { assertKnownKeys, assertRecord } from '../context/validation.js';
+import { replaceFileAtomically } from '../runtime/atomic-file.js';
+import { readProjectRuntimeContext } from '../runtime/project-runtime.js';
+import {
+  type GitRefTaskBundleV1,
+  parseGitRefTaskBundle,
+} from './git-ref-transport.js';
+
+export interface GitRefTaskRemoteBaseV1 {
+  schemaVersion: 1;
+  workspaceId: Ulid;
+  taskRef: TaskRef;
+  remoteRevision: number;
+  bundle: GitRefTaskBundleV1;
+}
+
+export async function readGitRefTaskRemoteBase(
+  projectRoot: string,
+  taskRef: TaskRef,
+): Promise {
+  const parsedTaskRef = parseTaskRefValue(taskRef);
+  const runtime = await readProjectRuntimeContext(projectRoot);
+  const target = remoteBasePath(projectRoot, parsedTaskRef);
+  try {
+    await assertRemoteBaseDirectory(projectRoot);
+    const before = await lstat(target);
+    if (!before.isFile() || before.isSymbolicLink()) {
+      throw new Error('MANCODE_ARTIFACT_PATH_UNSAFE');
+    }
+    const state = parseGitRefTaskRemoteBase(
+      JSON.parse(await readFile(target, 'utf8')),
+    );
+    const after = await lstat(target);
+    if (
+      !after.isFile() ||
+      after.isSymbolicLink() ||
+      before.dev !== after.dev ||
+      before.ino !== after.ino
+    ) {
+      throw new Error('MANCODE_ARTIFACT_PATH_UNSAFE');
+    }
+    if (
+      state.workspaceId !== runtime.workspaceId ||
+      !sameTaskRef(state.taskRef, parsedTaskRef)
+    ) {
+      return null;
+    }
+    return state;
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    if (error instanceof SyntaxError) {
+      throw new Error('MANCODE_TRANSPORT_CACHE_CORRUPT');
+    }
+    throw error;
+  }
+}
+
+export async function recordGitRefTaskRemoteBase(
+  projectRoot: string,
+  remoteRevision: number,
+  bundle: GitRefTaskBundleV1,
+): Promise {
+  const parsedBundle = parseGitRefTaskBundle(bundle);
+  const revision = positiveInteger(remoteRevision);
+  const runtime = await readProjectRuntimeContext(projectRoot);
+  const state = parseGitRefTaskRemoteBase({
+    schemaVersion: 1,
+    workspaceId: runtime.workspaceId,
+    taskRef: parsedBundle.taskRef,
+    remoteRevision: revision,
+    bundle: parsedBundle,
+  });
+  const directory = await ensureRemoteBaseDirectory(projectRoot);
+  const target = remoteBasePath(projectRoot, parsedBundle.taskRef);
+  const temporary = path.join(
+    directory,
+    `.${parsedBundle.taskRef.taskId}.${process.pid}.${Date.now()}.tmp`,
+  );
+  await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, {
+    encoding: 'utf8',
+    flag: 'wx',
+  });
+  await replaceFileAtomically(temporary, target);
+  return state;
+}
+
+export function parseGitRefTaskRemoteBase(
+  value: unknown,
+): GitRefTaskRemoteBaseV1 {
+  assertRecord(value, 'git-ref task remote base');
+  assertKnownKeys(
+    value,
+    ['schemaVersion', 'workspaceId', 'taskRef', 'remoteRevision', 'bundle'],
+    'git-ref task remote base',
+  );
+  if (value.schemaVersion !== 1) {
+    throw new Error('git-ref task remote base schemaVersion must be 1');
+  }
+  assertUlid(value.workspaceId, 'git-ref task remote base workspaceId');
+  const taskRef = parseTaskRefValue(value.taskRef);
+  const bundle = parseGitRefTaskBundle(value.bundle);
+  if (!sameTaskRef(taskRef, bundle.taskRef)) {
+    throw new Error('MANCODE_TRANSPORT_CACHE_IDENTITY_MISMATCH');
+  }
+  return {
+    schemaVersion: 1,
+    workspaceId: value.workspaceId,
+    taskRef,
+    remoteRevision: positiveInteger(value.remoteRevision),
+    bundle,
+  };
+}
+
+async function ensureRemoteBaseDirectory(projectRoot: string): Promise {
+  let current = path.resolve(projectRoot);
+  for (const segment of [
+    '.mancode',
+    'local',
+    'cache',
+    'git-ref',
+    'remote-bases',
+  ]) {
+    current = path.join(current, segment);
+    try {
+      await mkdir(current);
+    } catch (error) {
+      if (!isAlreadyExists(error)) throw error;
+    }
+    const entry = await lstat(current);
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+      throw new Error('MANCODE_ARTIFACT_PATH_UNSAFE');
+    }
+  }
+  return current;
+}
+
+async function assertRemoteBaseDirectory(projectRoot: string): Promise {
+  let current = path.resolve(projectRoot);
+  for (const segment of [
+    '.mancode',
+    'local',
+    'cache',
+    'git-ref',
+    'remote-bases',
+  ]) {
+    current = path.join(current, segment);
+    const entry = await lstat(current);
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+      throw new Error('MANCODE_ARTIFACT_PATH_UNSAFE');
+    }
+  }
+}
+
+function remoteBasePath(projectRoot: string, taskRef: TaskRef): string {
+  const parsed = parseTaskRefValue(taskRef);
+  return path.join(
+    path.resolve(projectRoot),
+    '.mancode',
+    'local',
+    'cache',
+    'git-ref',
+    'remote-bases',
+    `${parsed.taskId}.json`,
+  );
+}
+
+function positiveInteger(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
+    throw new Error('MANCODE_TRANSPORT_REVISION_INVALID');
+  }
+  return value;
+}
+
+function isAlreadyExists(error: unknown): error is NodeJS.ErrnoException {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error as NodeJS.ErrnoException).code === 'EEXIST'
+  );
+}
+
+function isNotFound(error: unknown): error is NodeJS.ErrnoException {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error as NodeJS.ErrnoException).code === 'ENOENT'
+  );
+}
diff --git a/src/team/git-ref-transport.ts b/src/team/git-ref-transport.ts
index d90064f..4ebeef7 100644
--- a/src/team/git-ref-transport.ts
+++ b/src/team/git-ref-transport.ts
@@ -207,6 +207,7 @@ export interface MutateGitRefCoordinationInput {
   taskRef: TaskRef;
   expectedRemoteRevision: number;
   expectedOwnershipEpoch: number;
+  expectedTaskBundleDigest: string | null;
   ownershipFence: GitRefOwnershipFenceV1;
   claims: ClaimV1[];
   handoffs: HandoffV1[];
@@ -511,6 +512,15 @@ export class GitRefTeamManifestStore {
     const previousFence = base.ownershipFences.find((candidate) =>
       sameTaskRef(candidate.taskRef, taskRef),
     );
+    const previousTaskBundle = base.taskBundles.find((bundle) =>
+      sameTaskRef(bundle.taskRef, taskRef),
+    );
+    if (
+      (previousTaskBundle?.bundleDigest ?? null) !==
+      input.expectedTaskBundleDigest
+    ) {
+      throw new Error('MANCODE_TASK_BUNDLE_DIVERGED');
+    }
     if (
       !base.actorProfiles.some((profile) => profile.actorId === input.actorId)
     ) {
@@ -547,9 +557,7 @@ export class GitRefTeamManifestStore {
       previousHandoffs: base.handoffs.filter((handoff) =>
         sameTaskRef(handoff.taskRef, taskRef),
       ),
-      previousTaskBundle: base.taskBundles.find((bundle) =>
-        sameTaskRef(bundle.taskRef, taskRef),
-      ),
+      previousTaskBundle,
       expectedOwnershipEpoch,
       nextRevision,
       fence,
diff --git a/src/team/git-ref-workflow-operation.ts b/src/team/git-ref-workflow-operation.ts
index 4988671..a2f12a7 100644
--- a/src/team/git-ref-workflow-operation.ts
+++ b/src/team/git-ref-workflow-operation.ts
@@ -580,6 +580,10 @@ async function publishTaskMutation(
       taskRef: input.context.taskRef,
       expectedRemoteRevision: input.manifest.revision,
       expectedOwnershipEpoch: input.fence.ownershipEpoch,
+      expectedTaskBundleDigest:
+        input.manifest.taskBundles.find((bundle) =>
+          sameTaskRef(bundle.taskRef, input.context.taskRef),
+        )?.bundleDigest ?? null,
       ownershipFence: fence,
       claims: input.claims,
       handoffs,
diff --git a/tests/git-ref-coordination-contracts.test.ts b/tests/git-ref-coordination-contracts.test.ts
index 07c5635..7081880 100644
--- a/tests/git-ref-coordination-contracts.test.ts
+++ b/tests/git-ref-coordination-contracts.test.ts
@@ -83,6 +83,7 @@ describe('git-ref coordination domain contracts', () => {
       taskRef: TASK_REF,
       expectedRemoteRevision: 1,
       expectedOwnershipEpoch: 0,
+      expectedPredecessorBundleDigest: null,
       taskBundle: initialBundle,
       now: NOW,
     });
@@ -100,6 +101,90 @@ describe('git-ref coordination domain contracts', () => {
     });
   });
 
+  it('advances an owner code ref and refreshes only the owner claim in one CAS', () => {
+    const current = baseManifest({ claims: [activeClaim()] });
+    const previous = current.taskBundles[0];
+    if (previous === undefined) throw new Error('missing current task bundle');
+    const nextBundle = bundleWithCodeHead(previous, 'def5678');
+
+    const prepared = prepareGitRefCoordinationMutation(current, {
+      kind: 'ownership_fence',
+      operationId: id(24),
+      actorId: OWNER_ID,
+      taskRef: TASK_REF,
+      expectedRemoteRevision: 1,
+      expectedOwnershipEpoch: 1,
+      expectedPredecessorBundleDigest: previous.bundleDigest,
+      taskBundle: nextBundle,
+      now: NOW,
+    });
+
+    expect(prepared.ownershipFence).toMatchObject({
+      taskRevision: previous.taskRevision,
+      aggregateDigest: previous.aggregateDigest,
+      ownerActorId: OWNER_ID,
+    });
+    expect(prepared.claims[0]).toMatchObject({
+      claimId: CLAIM_ID,
+      revision: 2,
+      lastValidatedTaskRevision: nextBundle.taskRevision,
+      lastValidatedCodeRef: nextBundle.codeRef,
+      authority: { remoteRevision: '2' },
+    });
+
+    expect(() =>
+      prepareGitRefCoordinationMutation(current, {
+        kind: 'ownership_fence',
+        operationId: id(25),
+        actorId: OWNER_ID,
+        taskRef: TASK_REF,
+        expectedRemoteRevision: 1,
+        expectedOwnershipEpoch: 1,
+        expectedPredecessorBundleDigest: bundleWithCodeHead(previous, 'fedcba9')
+          .bundleDigest,
+        taskBundle: nextBundle,
+        now: NOW,
+      }),
+    ).toThrow('MANCODE_TASK_BUNDLE_DIVERGED');
+
+    const participantClaim = baseManifest({
+      claims: [activeClaim({ ownerActorId: RECEIVER_ID })],
+    });
+    const participantPrepared = prepareGitRefCoordinationMutation(
+      participantClaim,
+      {
+        kind: 'ownership_fence',
+        operationId: id(26),
+        actorId: OWNER_ID,
+        taskRef: TASK_REF,
+        expectedRemoteRevision: 1,
+        expectedOwnershipEpoch: 1,
+        expectedPredecessorBundleDigest: previous.bundleDigest,
+        taskBundle: nextBundle,
+        now: NOW,
+      },
+    );
+    expect(participantPrepared.claims[0]).toEqual(participantClaim.claims[0]);
+    const participantRevalidated = prepareGitRefCoordinationMutation(
+      commitPrepared(participantClaim, participantPrepared),
+      {
+        kind: 'claim_revalidate',
+        operationId: id(27),
+        actorId: RECEIVER_ID,
+        taskRef: TASK_REF,
+        expectedRemoteRevision: 2,
+        expectedOwnershipEpoch: 1,
+        claimId: CLAIM_ID,
+        expectedClaimRevision: 1,
+        now: NOW,
+      },
+    );
+    expect(participantRevalidated.claims[0]).toMatchObject({
+      revision: 2,
+      lastValidatedCodeRef: nextBundle.codeRef,
+    });
+  });
+
   it('materializes remote handoffs as fetched without changing business state', () => {
     const current = {
       ...baseManifest({
@@ -171,6 +256,8 @@ describe('git-ref coordination domain contracts', () => {
         taskRef: TASK_REF,
         expectedRemoteRevision: 1,
         expectedOwnershipEpoch: 1,
+        expectedPredecessorBundleDigest:
+          current.taskBundles[0]?.bundleDigest ?? null,
         taskBundle: bundle(
           metadata({ task: 'A divergent task at the same remote revision.' }),
         ),
@@ -223,6 +310,8 @@ describe('git-ref coordination domain contracts', () => {
       taskRef: TASK_REF,
       expectedRemoteRevision: 3,
       expectedOwnershipEpoch: 1,
+      expectedPredecessorBundleDigest:
+        current.taskBundles[0]?.bundleDigest ?? null,
       taskBundle: bundle(metadata({ revision: 8 })),
       now: NOW,
     });
@@ -820,6 +909,18 @@ function bundle(value: WorkflowMetadataV3): GitRefTaskBundleV1 {
   return { ...body, bundleDigest: digestCanonicalJson(body) };
 }
 
+function bundleWithCodeHead(
+  previous: GitRefTaskBundleV1,
+  head: string,
+): GitRefTaskBundleV1 {
+  const body = { ...previous, codeRef: { ...previous.codeRef, head } };
+  const { bundleDigest: _bundleDigest, ...withoutDigest } = body;
+  return {
+    ...withoutDigest,
+    bundleDigest: digestCanonicalJson(withoutDigest),
+  };
+}
+
 function pendingClaim(overrides: Partial = {}): ClaimV1 {
   const scope = {
     paths: ['src/auth/token.ts'],
diff --git a/tests/git-ref-cross-clone-e2e.test.ts b/tests/git-ref-cross-clone-e2e.test.ts
index 73e4902..77589a3 100644
--- a/tests/git-ref-cross-clone-e2e.test.ts
+++ b/tests/git-ref-cross-clone-e2e.test.ts
@@ -1,5 +1,5 @@
 import { execFile as execFileCallback } from 'node:child_process';
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
@@ -52,6 +52,7 @@ import {
   mutateGitRefHandoff,
   syncGitRefTask,
 } from '../src/team/git-ref-operation.js';
+import { readGitRefTaskRemoteBase } from '../src/team/git-ref-task-base.js';
 import type {
   GitRefOwnershipFenceV1,
   GitRefTaskBundleV1,
@@ -314,6 +315,297 @@ describe('git-ref coordination across independent clones', () => {
     });
   }, 20_000);
 
+  it('lets the owner checkpoint and sync after a claimed code commit', async () => {
+    const fixture = await createFixture();
+    const created = await createRemoteTask(fixture.cloneA, fixture.codeHead);
+    const storeA = await strictStore(fixture.cloneA);
+    const initialBundle = await taskBundle(fixture.cloneA);
+    const establishOperationId = id(80);
+    await storeA.establishCoordinationAuthority({
+      operationId: establishOperationId,
+      actorId: ACTOR_A,
+      expectedRemoteRevision: 0,
+      expectedPriorTransportEpoch: null,
+      targetTransportEpoch: 2,
+      actorProfiles: fixture.profiles,
+      ownershipFences: [
+        ownershipFence(initialBundle, ACTOR_A, 1, establishOperationId),
+      ],
+      claims: [],
+      handoffs: [],
+      taskBundles: [initialBundle],
+    });
+    const acquired = await acquireGitRefClaim({
+      projectRoot: fixture.cloneA,
+      taskRef: created.taskRef,
+      sessionId: SESSION_A,
+      expectedTaskRevision: created.metadata.revision,
+      scope: scope('src/auth/**'),
+      claimId: id(81),
+      operationId: id(82),
+      now: at(2),
+    });
+
+    await git(fixture.cloneA, ['push', 'origin', 'main']);
+    await git(fixture.cloneB, ['fetch', 'origin']);
+    await captureJson(() =>
+      teamSyncPull(fixture.cloneB, {
+        task: formatTaskRef(created.taskRef),
+        json: true,
+      }),
+    );
+    await git(fixture.cloneB, ['merge', '--ff-only', 'origin/main']);
+    await rm(
+      path.join(
+        fixture.cloneB,
+        '.mancode',
+        'local',
+        'cache',
+        'git-ref',
+        'remote-bases',
+        `${created.taskRef.taskId}.json`,
+      ),
+    );
+    await expect(
+      acquireGitRefClaim({
+        projectRoot: fixture.cloneB,
+        taskRef: created.taskRef,
+        sessionId: SESSION_B,
+        expectedTaskRevision: created.metadata.revision,
+        scope: scope('src/auth/**'),
+        claimId: id(86),
+        operationId: id(87),
+        now: at(2),
+      }),
+    ).rejects.toThrow('MANCODE_SCOPE_CONFLICT');
+
+    await mkdir(path.join(fixture.cloneA, 'src', 'auth'), { recursive: true });
+    await writeFile(
+      path.join(fixture.cloneA, 'src', 'auth', 'token.ts'),
+      "export const token = 'ready';\n",
+    );
+    await git(fixture.cloneA, ['add', 'src/auth/token.ts']);
+    await git(fixture.cloneA, ['commit', '-m', 'implement claimed code']);
+    const codeHead = await gitOutput(fixture.cloneA, ['rev-parse', 'HEAD']);
+
+    const checkpoint = await createV3Checkpoint({
+      projectRoot: fixture.cloneA,
+      taskRef: created.taskRef,
+      sessionId: SESSION_A,
+      expectedTaskRevision: created.metadata.revision,
+      kind: 'handoff_offered',
+      summary: 'The claimed implementation is committed and ready to hand off.',
+      nextAction: 'Pull the commit and accept the handoff.',
+      checkpointId: id(83),
+      operationId: id(84),
+      now: at(3),
+    });
+    expect(checkpoint.taskHeadFence?.codeRef.head).toBe(codeHead);
+
+    const synced = await syncGitRefTask({
+      projectRoot: fixture.cloneA,
+      taskRef: created.taskRef,
+      sessionId: SESSION_A,
+      expectedTaskRevision: checkpoint.metadata.revision,
+      operationId: id(85),
+      now: at(4),
+    });
+    expect(synced).toMatchObject({
+      changed: true,
+      remoteRevision: 3,
+      bundle: { codeRef: { head: codeHead } },
+    });
+    await expect(storeA.pull()).resolves.toMatchObject({
+      manifest: {
+        claims: [
+          {
+            claimId: acquired.claim.claimId,
+            revision: acquired.claim.revision + 1,
+            lastValidatedTaskRevision: checkpoint.metadata.revision,
+            lastValidatedCodeRef: { head: codeHead },
+          },
+        ],
+      },
+    });
+
+    const unchanged = await syncGitRefTask({
+      projectRoot: fixture.cloneA,
+      taskRef: created.taskRef,
+      sessionId: SESSION_A,
+      expectedTaskRevision: checkpoint.metadata.revision,
+      operationId: id(115),
+      now: at(5),
+    });
+    expect(unchanged.changed).toBe(false);
+    const exactRemoteBase = await readGitRefTaskRemoteBase(
+      fixture.cloneA,
+      created.taskRef,
+    );
+    const remoteAfterUnchangedSync = await storeA.pull();
+    expect(exactRemoteBase?.bundle.bundleDigest).toBe(
+      remoteAfterUnchangedSync.manifest?.taskBundles[0]?.bundleDigest,
+    );
+
+    await git(fixture.cloneA, ['push', 'origin', 'main']);
+    const drafted = await createGitRefHandoffDraft({
+      projectRoot: fixture.cloneA,
+      taskRef: created.taskRef,
+      sessionId: SESSION_A,
+      expectedTaskRevision: checkpoint.metadata.revision,
+      toActorId: ACTOR_B,
+      handoffId: id(88),
+      operationId: id(89),
+      now: at(5),
+    });
+    const offered = await mutateGitRefHandoff({
+      projectRoot: fixture.cloneA,
+      handoffId: drafted.handoff.handoffId,
+      sessionId: SESSION_A,
+      expectedHandoffRevision: drafted.handoff.revision,
+      mutation: { kind: 'offer' },
+      operationId: id(90),
+      now: at(6),
+    });
+
+    const stalePull = await captureJson(() =>
+      teamSyncPull(fixture.cloneB, {
+        task: formatTaskRef(created.taskRef),
+        json: true,
+      }),
+    );
+    expect(stalePull.value).toMatchObject({
+      materializedBundles: [{ status: 'quarantined', codeReachable: false }],
+    });
+    await expect(
+      acceptGitRefHandoffWithRepair({
+        projectRoot: fixture.cloneB,
+        handoffId: drafted.handoff.handoffId,
+        sessionId: SESSION_B,
+        expectedHandoffRevision: offered.handoff.revision,
+        operationId: id(91),
+        now: at(7),
+      }),
+    ).rejects.toThrow('MANCODE_EXPECTED_REVISION_CONFLICT');
+
+    await git(fixture.cloneB, ['pull', '--ff-only']);
+    const currentPull = await captureJson(() =>
+      teamSyncPull(fixture.cloneB, {
+        task: formatTaskRef(created.taskRef),
+        json: true,
+      }),
+    );
+    expect(currentPull.value).toMatchObject({
+      materializedBundles: [
+        {
+          status: 'updated',
+          codeReachable: true,
+          taskRevision: checkpoint.metadata.revision,
+        },
+      ],
+    });
+    const accepted = await acceptGitRefHandoffWithRepair({
+      projectRoot: fixture.cloneB,
+      handoffId: drafted.handoff.handoffId,
+      sessionId: SESSION_B,
+      expectedHandoffRevision: offered.handoff.revision,
+      operationId: id(92),
+      now: at(8),
+    });
+    expect(accepted).toMatchObject({
+      ownershipEpoch: 1,
+      handoff: { state: 'accepted' },
+      taskBundle: { ownershipEpoch: 1 },
+      forwardRepair: { ownerActorId: ACTOR_B },
+    });
+  }, 20_000);
+
+  it('rejects a stale owner clone instead of overwriting a newer code ref', async () => {
+    const fixture = await createFixture();
+    const created = await createRemoteTask(fixture.cloneA, fixture.codeHead);
+    const storeA = await strictStore(fixture.cloneA);
+    const initialBundle = await taskBundle(fixture.cloneA);
+    const establishOperationId = id(100);
+    await storeA.establishCoordinationAuthority({
+      operationId: establishOperationId,
+      actorId: ACTOR_A,
+      expectedRemoteRevision: 0,
+      expectedPriorTransportEpoch: null,
+      targetTransportEpoch: 2,
+      actorProfiles: fixture.profiles,
+      ownershipFences: [
+        ownershipFence(initialBundle, ACTOR_A, 1, establishOperationId),
+      ],
+      claims: [],
+      handoffs: [],
+      taskBundles: [initialBundle],
+    });
+    await captureJson(() =>
+      teamSyncPull(fixture.cloneA, {
+        task: formatTaskRef(created.taskRef),
+        json: true,
+      }),
+    );
+    await git(fixture.cloneA, ['push', 'origin', 'main']);
+    await git(fixture.cloneB, ['fetch', 'origin']);
+    await captureJson(() =>
+      teamSyncPull(fixture.cloneB, {
+        task: formatTaskRef(created.taskRef),
+        json: true,
+      }),
+    );
+    await git(fixture.cloneB, ['merge', '--ff-only', 'origin/main']);
+    await createSession(fixture.cloneB, {
+      actorId: ACTOR_A,
+      sessionId: id(101),
+      client: 'vitest-a-stale',
+      identitySource: 'explicit',
+      now: NOW,
+    });
+
+    await writeFile(
+      path.join(fixture.cloneA, 'src-a.ts'),
+      'export const a = 1;\n',
+    );
+    await git(fixture.cloneA, ['add', 'src-a.ts']);
+    await git(fixture.cloneA, ['commit', '-m', 'advance owner code ref']);
+    await syncGitRefTask({
+      projectRoot: fixture.cloneA,
+      taskRef: created.taskRef,
+      sessionId: SESSION_A,
+      expectedTaskRevision: created.metadata.revision,
+      operationId: id(102),
+      now: at(2),
+    });
+
+    await writeFile(
+      path.join(fixture.cloneB, 'src-b.ts'),
+      'export const b = 1;\n',
+    );
+    await git(fixture.cloneB, ['add', 'src-b.ts']);
+    await git(fixture.cloneB, ['commit', '-m', 'diverge stale owner code']);
+    await expect(
+      syncGitRefTask({
+        projectRoot: fixture.cloneB,
+        taskRef: created.taskRef,
+        sessionId: id(101),
+        expectedTaskRevision: created.metadata.revision,
+        operationId: id(103),
+        now: at(3),
+      }),
+    ).rejects.toThrow('MANCODE_TASK_BUNDLE_DIVERGED');
+    await expect(storeA.pull()).resolves.toMatchObject({
+      manifest: {
+        taskBundles: [
+          {
+            codeRef: {
+              head: await gitOutput(fixture.cloneA, ['rev-parse', 'HEAD']),
+            },
+          },
+        ],
+      },
+    });
+  }, 20_000);
+
   it('fences claims, materializes a quarantined bundle, and transfers ownership once', async () => {
     const fixture = await createFixture();
     const created = await createRemoteTask(fixture.cloneA, fixture.codeHead);
diff --git a/tests/git-ref-manifest-authority-contracts.test.ts b/tests/git-ref-manifest-authority-contracts.test.ts
index 205f896..805b7c3 100644
--- a/tests/git-ref-manifest-authority-contracts.test.ts
+++ b/tests/git-ref-manifest-authority-contracts.test.ts
@@ -111,6 +111,7 @@ describe('git-ref remote manifest contracts', () => {
         taskRef: taskRef(),
         expectedRemoteRevision: 1,
         expectedOwnershipEpoch: 0,
+        expectedTaskBundleDigest: null,
         ownershipFence: fence(id(21), 2),
         claims: [],
         handoffs: [],
@@ -124,6 +125,7 @@ describe('git-ref remote manifest contracts', () => {
         taskRef: taskRef(),
         expectedRemoteRevision: 1,
         expectedOwnershipEpoch: 0,
+        expectedTaskBundleDigest: null,
         ownershipFence: fence(id(22), 2),
         claims: [],
         handoffs: [],
@@ -137,6 +139,7 @@ describe('git-ref remote manifest contracts', () => {
         taskRef: taskRef(),
         expectedRemoteRevision: 2,
         expectedOwnershipEpoch: 0,
+        expectedTaskBundleDigest: null,
         ownershipFence: { ...fence(id(23), 3), ownerActorId: id(99) },
         claims: [],
         handoffs: [],
diff --git a/tests/git-ref-materialization-contracts.test.ts b/tests/git-ref-materialization-contracts.test.ts
index 97277a1..0605e32 100644
--- a/tests/git-ref-materialization-contracts.test.ts
+++ b/tests/git-ref-materialization-contracts.test.ts
@@ -112,6 +112,65 @@ describe('git-ref task bundle materialization', () => {
       }),
     ).rejects.toThrow('MANCODE_SPLIT_BRAIN');
   });
+
+  it('does not treat an unsynced local revision as a cached remote predecessor', async () => {
+    const source = await bootstrap('source-base', id(30), id(31));
+    const target = await bootstrap('target-base', id(30), id(32));
+    const created = await createSharedWorkflow(source.root, source.sessionId);
+    const first = await bundle(source.root);
+
+    await expect(
+      materializeGitRefTaskBundle({
+        projectRoot: target.root,
+        remoteRevision: 1,
+        ownershipFence: remoteFence(first, 1, id(33)),
+        bundle: first,
+        operationId: id(34),
+        now: NOW,
+      }),
+    ).resolves.toMatchObject({ status: 'created' });
+    await execFile('git', ['fetch', source.root, 'HEAD'], { cwd: target.root });
+    await execFile('git', ['checkout', '--detach', 'FETCH_HEAD'], {
+      cwd: target.root,
+    });
+    await createV3Checkpoint({
+      projectRoot: target.root,
+      taskRef: created.taskRef,
+      sessionId: target.sessionId,
+      expectedTaskRevision: created.metadata.revision,
+      kind: 'diagnostic_started',
+      summary: 'Create an unsynced local predecessor.',
+      operationId: id(35),
+      checkpointId: id(36),
+      now: new Date('2026-07-18T10:01:00.000Z'),
+    });
+
+    await createV3Checkpoint({
+      projectRoot: source.root,
+      taskRef: created.taskRef,
+      sessionId: source.sessionId,
+      expectedTaskRevision: created.metadata.revision,
+      kind: 'diagnostic_started',
+      summary: 'Advance the remote task independently.',
+      operationId: id(37),
+      checkpointId: id(38),
+      now: new Date('2026-07-18T10:01:00.000Z'),
+    });
+    const second = await bundle(source.root);
+
+    await expect(
+      materializeGitRefTaskBundle({
+        projectRoot: target.root,
+        remoteRevision: 2,
+        ownershipFence: remoteFence(second, 2, id(39)),
+        bundle: second,
+        // Simulates a quarantine pull that cached the target before code was reachable.
+        predecessorBundle: second,
+        operationId: id(40),
+        now: new Date('2026-07-18T10:02:00.000Z'),
+      }),
+    ).rejects.toThrow('MANCODE_SPLIT_BRAIN');
+  });
 });
 
 async function bootstrap(label: string, actorId: Ulid, sessionId: Ulid) {

From effcaf9ad16a00fc5e4eb4cd0f6c1a1984c3e957 Mon Sep 17 00:00:00 2001
From: whitelonng 
Date: Mon, 20 Jul 2026 15:41:30 +0800
Subject: [PATCH 6/9] fix: align 0.3.17 release metadata

---
 README.en.md             | 6 +++---
 README.md                | 6 +++---
 website/docs.html        | 2 +-
 website/docs.zh-CN.html  | 2 +-
 website/index.html       | 2 +-
 website/index.zh-CN.html | 2 +-
 6 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.en.md b/README.en.md
index f789ebe..bb8885c 100644
--- a/README.en.md
+++ b/README.en.md
@@ -17,7 +17,7 @@
 

   License: AGPL-3.0
   npm version
-  Status: mancode Continuity v0.3.16
+  Status: mancode Continuity v0.3.17
   Platforms: Claude Code, Cursor, Codex in ChatGPT desktop and CLI, GitHub Copilot, ZCode
 

 
@@ -353,7 +353,7 @@ it should behave, and why previous decisions were made.
 
 ## Installation
 
-**Status**: mancode Continuity v0.3.16. Claude Code, Cursor, Codex in the ChatGPT
+**Status**: mancode Continuity v0.3.17. Claude Code, Cursor, Codex in the ChatGPT
 desktop app and CLI, GitHub Copilot, and ZCode adapters are included.
 
 Requires Node.js 20 or newer. macOS, Linux, Windows CMD, PowerShell, and Git Bash
@@ -452,7 +452,7 @@ mancode version
 Simplified output:
 
 ```text
-mancode v0.3.16
+mancode v0.3.17
 
 Project:     my-app
 Runtime:     ready
diff --git a/README.md b/README.md
index f98f441..17d485d 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@
 

   许可证：AGPL-3.0
   npm 版本
-  状态：mancode Continuity v0.3.16
+  状态：mancode Continuity v0.3.17
   平台：Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI、GitHub Copilot、ZCode
 

 
@@ -307,7 +307,7 @@ src/components/
 
 ## 安装
 
-**状态**：mancode Continuity v0.3.16。Claude Code、Cursor、ChatGPT 桌面端中的
+**状态**：mancode Continuity v0.3.17。Claude Code、Cursor、ChatGPT 桌面端中的
 Codex、Codex CLI、GitHub Copilot 和 ZCode adapter 均已接入。
 
 需要 Node.js 20 或更高版本。原生支持 macOS、Linux、Windows CMD、
@@ -404,7 +404,7 @@ mancode version
 以下是简化输出示例：
 
 ```text
-mancode v0.3.16
+mancode v0.3.17
 
 Project:     my-app
 Runtime:     ready
diff --git a/website/docs.html b/website/docs.html
index 5b32e8d..bf697a1 100644
--- a/website/docs.html
+++ b/website/docs.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      Documentation / v0.3.16
+      Documentation / v0.3.17
       

         Website
         GitHub
diff --git a/website/docs.zh-CN.html b/website/docs.zh-CN.html
index 02f2a7c..8da17da 100644
--- a/website/docs.zh-CN.html
+++ b/website/docs.zh-CN.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      文档 / v0.3.16
+      文档 / v0.3.17
       

         官网
         GitHub
diff --git a/website/index.html b/website/index.html
index d1a1eeb..1ec8e71 100644
--- a/website/index.html
+++ b/website/index.html
@@ -439,7 +439,7 @@ 
Stop babysitting
AI bloat.

         中文
         AGPL-3.0
       

-       Continuity / v0.3.16
+       Continuity / v0.3.17
     
   
 
diff --git a/website/index.zh-CN.html b/website/index.zh-CN.html
index 9c3d691..8e11e67 100644
--- a/website/index.zh-CN.html
+++ b/website/index.zh-CN.html
@@ -88,6 +88,6 @@ 
一项任务。
下个会话继续。

 
       
简单任务少一点仪式。
关键任务多一点纪律。
别再替 AI
收拾臃肿。
> npm install -g mancode
GitHub 上查看 ↗

     
-    
+    
   
 

From 2ad544ec68fd816d97c02bb18df24554a047998a Mon Sep 17 00:00:00 2001
From: whitelonng 
Date: Mon, 20 Jul 2026 20:09:17 +0800
Subject: [PATCH 7/9] fix: reconcile git-pulled team bundles

---
 src/team/git-ref-materialization.ts           |  7 +-
 .../git-ref-materialization-contracts.test.ts | 72 +++++++++++++++++++
 2 files changed, 78 insertions(+), 1 deletion(-)

diff --git a/src/team/git-ref-materialization.ts b/src/team/git-ref-materialization.ts
index a9e098d..6c9bcb2 100644
--- a/src/team/git-ref-materialization.ts
+++ b/src/team/git-ref-materialization.ts
@@ -175,7 +175,12 @@ export async function materializeGitRefTaskBundle(
       now,
     });
     if (status === 'unchanged') {
-      await writeTargetFence(store, currentFence, targetFence, predecessor);
+      await writeTargetFence(
+        store,
+        currentFence,
+        targetFence,
+        materializedPredecessor,
+      );
       await recordGitRefTaskRemoteBase(projectRoot, remoteRevision, bundle);
       return result(status, bundle, null, targetFence);
     }
diff --git a/tests/git-ref-materialization-contracts.test.ts b/tests/git-ref-materialization-contracts.test.ts
index 0605e32..b9e7068 100644
--- a/tests/git-ref-materialization-contracts.test.ts
+++ b/tests/git-ref-materialization-contracts.test.ts
@@ -113,6 +113,55 @@ describe('git-ref task bundle materialization', () => {
     ).rejects.toThrow('MANCODE_SPLIT_BRAIN');
   });
 
+  it('advances the fence when Git already supplied the target aggregate', async () => {
+    const source = await bootstrap('source-git-update', id(50), id(51));
+    const target = await bootstrap('target-git-update', id(52), id(53));
+    const created = await createSharedWorkflow(source.root, source.sessionId);
+    const first = await bundle(source.root);
+
+    await materializeGitRefTaskBundle({
+      projectRoot: target.root,
+      remoteRevision: 1,
+      ownershipFence: remoteFence(first, 1, id(54)),
+      bundle: first,
+      operationId: id(55),
+      now: NOW,
+    });
+
+    await createV3Checkpoint({
+      projectRoot: source.root,
+      taskRef: created.taskRef,
+      sessionId: source.sessionId,
+      expectedTaskRevision: created.metadata.revision,
+      kind: 'diagnostic_started',
+      summary: 'Advance the task before the other clone pulls Git.',
+      operationId: id(56),
+      checkpointId: id(57),
+      now: new Date('2026-07-18T10:01:00.000Z'),
+    });
+    const second = await bundle(source.root);
+
+    // Simulate a normal Git pull updating tracked task files before team sync.
+    await writeBundleArtifacts(target.root, second);
+    await expect(
+      materializeGitRefTaskBundle({
+        projectRoot: target.root,
+        remoteRevision: 2,
+        ownershipFence: remoteFence(second, 2, id(58)),
+        bundle: second,
+        operationId: id(59),
+        now: new Date('2026-07-18T10:02:00.000Z'),
+      }),
+    ).resolves.toMatchObject({
+      status: 'unchanged',
+      taskRevision: second.taskRevision,
+      taskHeadFence: {
+        taskRevision: second.taskRevision,
+        remoteRevision: 2,
+      },
+    });
+  });
+
   it('does not treat an unsynced local revision as a cached remote predecessor', async () => {
     const source = await bootstrap('source-base', id(30), id(31));
     const target = await bootstrap('target-base', id(30), id(32));
@@ -247,6 +296,29 @@ async function bundle(root: string): Promise {
   });
 }
 
+async function writeBundleArtifacts(
+  root: string,
+  bundle: GitRefTaskBundleV1,
+): Promise {
+  const taskRoot = path.join(
+    root,
+    '.mancode',
+    'shared',
+    'workflows',
+    bundle.taskRef.taskId,
+  );
+  for (const artifact of bundle.artifacts) {
+    const target = path.join(taskRoot, artifact.relativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(
+      target,
+      typeof artifact.content === 'string'
+        ? artifact.content
+        : `${JSON.stringify(artifact.content, null, 2)}\n`,
+    );
+  }
+}
+
 function remoteFence(
   bundle: GitRefTaskBundleV1,
   remoteRevision: number,

From 2c30c4eb57f7b9fa5d102a47bc2e0fdaef04393c Mon Sep 17 00:00:00 2001
From: whitelonng 
Date: Mon, 20 Jul 2026 20:31:18 +0800
Subject: [PATCH 8/9] fix: serialize git-ref materialization

---
 src/team/git-ref-handoff-repair.ts            |  1 +
 src/team/git-ref-materialization.ts           | 53 +++++++++++--
 src/team/git-ref-workflow-repair.ts           |  1 +
 .../git-ref-materialization-contracts.test.ts | 75 ++++++++++++++++---
 4 files changed, 113 insertions(+), 17 deletions(-)

diff --git a/src/team/git-ref-handoff-repair.ts b/src/team/git-ref-handoff-repair.ts
index 442463a..849b501 100644
--- a/src/team/git-ref-handoff-repair.ts
+++ b/src/team/git-ref-handoff-repair.ts
@@ -181,6 +181,7 @@ export async function recoverGitRefHandoffRepair(
       bundle: journal.prepared.targetBundle,
       predecessorBundle: journal.prepared.predecessorBundle,
       pendingMetadata: journal.pendingMetadata,
+      taskLockHeld: true,
       operationId: createUlid(),
     });
     journal = await transitionJournal(
diff --git a/src/team/git-ref-materialization.ts b/src/team/git-ref-materialization.ts
index 6c9bcb2..14cadac 100644
--- a/src/team/git-ref-materialization.ts
+++ b/src/team/git-ref-materialization.ts
@@ -31,6 +31,7 @@ import {
   readTaskHeadFence,
   replaceTaskHeadFence,
 } from '../runtime/task-head-store.js';
+import { taskEntityKey } from '../runtime/task-operation.js';
 import { readQuarantinedGitRefTaskBundle } from './git-ref-bundle.js';
 import {
   readGitRefTaskRemoteBase,
@@ -67,6 +68,8 @@ export interface MaterializeGitRefTaskBundleInput {
   bundle: GitRefTaskBundleV1;
   predecessorBundle?: GitRefTaskBundleV1 | null;
   pendingMetadata?: WorkflowMetadataV3 | null;
+  /** The caller already holds the canonical task lock. */
+  taskLockHeld?: boolean;
   operationId?: Ulid;
   now?: Date;
 }
@@ -119,12 +122,14 @@ export async function materializeGitRefTaskBundle(
   const store = resolveCoordinationEntityHomeStore(
     runtime.entityHomeStoreContext,
   );
-  const locks = await acquireEntityLocks(
-    store,
-    operationId,
-    [`remote_task:${bundle.taskRef.taskId}`],
-    { now },
-  );
+  const locks = input.taskLockHeld
+    ? []
+    : await acquireEntityLocks(
+        store,
+        operationId,
+        [taskEntityKey(bundle.taskRef)],
+        { now },
+      );
   try {
     await recoverTaskMaterializationsWhileLocked(
       projectRoot,
@@ -165,6 +170,20 @@ export async function materializeGitRefTaskBundle(
     }
     const materializedPredecessor =
       status === 'created' ? null : effectivePredecessor;
+    if (
+      status === 'unchanged' &&
+      currentFence !== null &&
+      taskHeadFenceMatchesTarget({
+        currentFence,
+        runtime,
+        remoteRevision,
+        ownershipFence,
+        bundle,
+      })
+    ) {
+      await recordGitRefTaskRemoteBase(projectRoot, remoteRevision, bundle);
+      return result(status, bundle, null, currentFence);
+    }
     const targetFence = buildTargetFence({
       runtime,
       remoteRevision,
@@ -237,7 +256,7 @@ export async function recoverGitRefTaskMaterializations(
     if (journal.state === 'committed') continue;
     const recoveryOperationId = createUlid();
     const locks = await acquireEntityLocks(store, recoveryOperationId, [
-      `remote_task:${journal.targetBundle.taskRef.taskId}`,
+      taskEntityKey(journal.targetBundle.taskRef),
     ]);
     try {
       repaired += await recoverTaskMaterializationsWhileLocked(
@@ -437,6 +456,26 @@ function buildTargetFence(input: {
   });
 }
 
+function taskHeadFenceMatchesTarget(input: {
+  currentFence: TaskHeadFenceV1;
+  runtime: Awaited>;
+  remoteRevision: number;
+  ownershipFence: GitRefOwnershipFenceV1;
+  bundle: GitRefTaskBundleV1;
+}): boolean {
+  return (
+    input.currentFence.workspaceId === input.runtime.workspaceId &&
+    sameTaskRef(input.currentFence.taskRef, input.bundle.taskRef) &&
+    input.currentFence.taskRevision === input.bundle.taskRevision &&
+    input.currentFence.aggregateDigest === input.bundle.aggregateDigest &&
+    input.currentFence.ownershipEpoch === input.bundle.ownershipEpoch &&
+    input.currentFence.codeRef.head === input.bundle.codeRef.head &&
+    input.currentFence.checkoutId === input.runtime.checkoutId &&
+    input.currentFence.remoteRevision === input.remoteRevision &&
+    input.currentFence.lastOperationId === input.ownershipFence.lastOperationId
+  );
+}
+
 async function writeTargetFence(
   store: ReturnType,
   current: TaskHeadFenceV1 | null,
diff --git a/src/team/git-ref-workflow-repair.ts b/src/team/git-ref-workflow-repair.ts
index a670420..edb365a 100644
--- a/src/team/git-ref-workflow-repair.ts
+++ b/src/team/git-ref-workflow-repair.ts
@@ -243,6 +243,7 @@ export async function recoverGitRefWorkflowRepair(
       bundle: targetBundle,
       predecessorBundle: journal.prepared.predecessorBundle,
       pendingMetadata: journal.pendingMetadata,
+      taskLockHeld: true,
       operationId: createUlid(),
     });
     journal = await transitionJournal(
diff --git a/tests/git-ref-materialization-contracts.test.ts b/tests/git-ref-materialization-contracts.test.ts
index b9e7068..6ce22dd 100644
--- a/tests/git-ref-materialization-contracts.test.ts
+++ b/tests/git-ref-materialization-contracts.test.ts
@@ -9,7 +9,11 @@ import { createV3Checkpoint } from '../src/context/checkpoint-create.js';
 import { type Ulid, createUlid } from '../src/context/ids.js';
 import { V3ContextStore } from '../src/context/store.js';
 import { createV3Workflow } from '../src/context/workflow-create.js';
+import { resolveCoordinationEntityHomeStore } from '../src/runtime/entity-home-store.js';
+import { acquireEntityLocks } from '../src/runtime/local-lock.js';
+import { readProjectRuntimeContext } from '../src/runtime/project-runtime.js';
 import { createSession } from '../src/runtime/session.js';
+import { taskEntityKey } from '../src/runtime/task-operation.js';
 import {
   createLocalActor,
   createSharedActorProfile,
@@ -113,6 +117,35 @@ describe('git-ref task bundle materialization', () => {
     ).rejects.toThrow('MANCODE_SPLIT_BRAIN');
   });
 
+  it('serializes materialization through the canonical task lock', async () => {
+    const source = await bootstrap('source-lock', id(60), id(61));
+    const target = await bootstrap('target-lock', id(62), id(63));
+    await createSharedWorkflow(source.root, source.sessionId);
+    const remote = await bundle(source.root);
+    const runtime = await readProjectRuntimeContext(target.root);
+    const store = resolveCoordinationEntityHomeStore(
+      runtime.entityHomeStoreContext,
+    );
+    const locks = await acquireEntityLocks(store, id(64), [
+      taskEntityKey(remote.taskRef),
+    ]);
+
+    try {
+      await expect(
+        materializeGitRefTaskBundle({
+          projectRoot: target.root,
+          remoteRevision: 1,
+          ownershipFence: remoteFence(remote, 1, id(65)),
+          bundle: remote,
+          operationId: id(66),
+          now: NOW,
+        }),
+      ).rejects.toThrow('MANCODE_LOCK_HELD');
+    } finally {
+      await Promise.all(locks.map((lock) => lock.release()));
+    }
+  });
+
   it('advances the fence when Git already supplied the target aggregate', async () => {
     const source = await bootstrap('source-git-update', id(50), id(51));
     const target = await bootstrap('target-git-update', id(52), id(53));
@@ -143,16 +176,15 @@ describe('git-ref task bundle materialization', () => {
 
     // Simulate a normal Git pull updating tracked task files before team sync.
     await writeBundleArtifacts(target.root, second);
-    await expect(
-      materializeGitRefTaskBundle({
-        projectRoot: target.root,
-        remoteRevision: 2,
-        ownershipFence: remoteFence(second, 2, id(58)),
-        bundle: second,
-        operationId: id(59),
-        now: new Date('2026-07-18T10:02:00.000Z'),
-      }),
-    ).resolves.toMatchObject({
+    const adopted = await materializeGitRefTaskBundle({
+      projectRoot: target.root,
+      remoteRevision: 2,
+      ownershipFence: remoteFence(second, 2, id(58)),
+      bundle: second,
+      operationId: id(59),
+      now: new Date('2026-07-18T10:02:00.000Z'),
+    });
+    expect(adopted).toMatchObject({
       status: 'unchanged',
       taskRevision: second.taskRevision,
       taskHeadFence: {
@@ -160,6 +192,29 @@ describe('git-ref task bundle materialization', () => {
         remoteRevision: 2,
       },
     });
+
+    const repeated = await materializeGitRefTaskBundle({
+      projectRoot: target.root,
+      remoteRevision: 2,
+      ownershipFence: remoteFence(second, 2, id(58)),
+      bundle: second,
+      operationId: id(67),
+      now: new Date('2026-07-18T10:03:00.000Z'),
+    });
+    expect(repeated.taskHeadFence).toEqual(adopted.taskHeadFence);
+
+    const refreshed = await materializeGitRefTaskBundle({
+      projectRoot: target.root,
+      remoteRevision: 3,
+      ownershipFence: remoteFence(second, 2, id(58)),
+      bundle: second,
+      operationId: id(68),
+      now: new Date('2026-07-18T10:04:00.000Z'),
+    });
+    expect(refreshed.taskHeadFence).toMatchObject({
+      fenceRevision: adopted.taskHeadFence.fenceRevision + 1,
+      remoteRevision: 3,
+    });
   });
 
   it('does not treat an unsynced local revision as a cached remote predecessor', async () => {

From a0f39f75d50f3ff2e985cd3e45cc250100710e45 Mon Sep 17 00:00:00 2001
From: whitelonng 
Date: Mon, 20 Jul 2026 21:48:34 +0800
Subject: [PATCH 9/9] chore: release 0.3.18

---
 README.en.md             | 6 +++---
 README.md                | 6 +++---
 package-lock.json        | 4 ++--
 package.json             | 2 +-
 website/docs.html        | 2 +-
 website/docs.zh-CN.html  | 2 +-
 website/index.html       | 2 +-
 website/index.zh-CN.html | 2 +-
 8 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/README.en.md b/README.en.md
index bb8885c..c86082b 100644
--- a/README.en.md
+++ b/README.en.md
@@ -17,7 +17,7 @@
 

   License: AGPL-3.0
   npm version
-  Status: mancode Continuity v0.3.17
+  Status: mancode Continuity v0.3.18
   Platforms: Claude Code, Cursor, Codex in ChatGPT desktop and CLI, GitHub Copilot, ZCode
 

 
@@ -353,7 +353,7 @@ it should behave, and why previous decisions were made.
 
 ## Installation
 
-**Status**: mancode Continuity v0.3.17. Claude Code, Cursor, Codex in the ChatGPT
+**Status**: mancode Continuity v0.3.18. Claude Code, Cursor, Codex in the ChatGPT
 desktop app and CLI, GitHub Copilot, and ZCode adapters are included.
 
 Requires Node.js 20 or newer. macOS, Linux, Windows CMD, PowerShell, and Git Bash
@@ -452,7 +452,7 @@ mancode version
 Simplified output:
 
 ```text
-mancode v0.3.17
+mancode v0.3.18
 
 Project:     my-app
 Runtime:     ready
diff --git a/README.md b/README.md
index 17d485d..d818221 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@
 

   许可证：AGPL-3.0
   npm 版本
-  状态：mancode Continuity v0.3.17
+  状态：mancode Continuity v0.3.18
   平台：Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI、GitHub Copilot、ZCode
 

 
@@ -307,7 +307,7 @@ src/components/
 
 ## 安装
 
-**状态**：mancode Continuity v0.3.17。Claude Code、Cursor、ChatGPT 桌面端中的
+**状态**：mancode Continuity v0.3.18。Claude Code、Cursor、ChatGPT 桌面端中的
 Codex、Codex CLI、GitHub Copilot 和 ZCode adapter 均已接入。
 
 需要 Node.js 20 或更高版本。原生支持 macOS、Linux、Windows CMD、
@@ -404,7 +404,7 @@ mancode version
 以下是简化输出示例：
 
 ```text
-mancode v0.3.17
+mancode v0.3.18
 
 Project:     my-app
 Runtime:     ready
diff --git a/package-lock.json b/package-lock.json
index 9023ea3..61744e8 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mancode",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mancode",
-      "version": "0.3.17",
+      "version": "0.3.18",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "commander": "^12.1.0",
diff --git a/package.json b/package.json
index 0c8c290..b2e9989 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mancode",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "AI coding agent workflow harness with mancode Continuity for cross-conversation tasks, decisions, verification, and team coordination.",
   "type": "module",
   "license": "AGPL-3.0-only",
diff --git a/website/docs.html b/website/docs.html
index bf697a1..71e8850 100644
--- a/website/docs.html
+++ b/website/docs.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      Documentation / v0.3.17
+      Documentation / v0.3.18
       

         Website
         GitHub
diff --git a/website/docs.zh-CN.html b/website/docs.zh-CN.html
index 8da17da..ab1a377 100644
--- a/website/docs.zh-CN.html
+++ b/website/docs.zh-CN.html
@@ -24,7 +24,7 @@
 
     

       mancode
-      文档 / v0.3.17
+      文档 / v0.3.18
       

         官网
         GitHub
diff --git a/website/index.html b/website/index.html
index 1ec8e71..2820c4d 100644
--- a/website/index.html
+++ b/website/index.html
@@ -439,7 +439,7 @@ 
Stop babysitting
AI bloat.

         中文
         AGPL-3.0
       

-       Continuity / v0.3.17
+       Continuity / v0.3.18
     
   
 
diff --git a/website/index.zh-CN.html b/website/index.zh-CN.html
index 8e11e67..fbfb3e7 100644
--- a/website/index.zh-CN.html
+++ b/website/index.zh-CN.html
@@ -88,6 +88,6 @@ 
一项任务。
下个会话继续。

 
       
简单任务少一点仪式。
关键任务多一点纪律。
别再替 AI
收拾臃肿。
> npm install -g mancode
GitHub 上查看 ↗

     
-    
+