# Carseod 看板 (https://docs.ttpi.space/dev-starter/board)

基于 Paseo 原生对象的工作控制面，以及卡片、会话、授权与 workflow 的绑定。

# Carseod 看板

Carseod 是可选的工作控制面，负责“做什么”和“人是否接受”，不负责“怎么实现”。

## 职责

- **Project**：daemon 机器上的一个目录。
- **Card**：一个 work item，`kind` 为 `task` 或 `question`；lane 表示人的验收阶段。
- **Session**：Paseo agent 会话；卡片详情面向一个当前会话。
- **Task**：仅当项目启用 Local Trunk Workflow 时存在；一张卡绑定一个 worktree/task。

## 权威数据

| 数据 | 来源 |
|---|---|
| workspace / session / permission | Paseo daemon |
| task / queue / integration / dev build | 项目仓库的 git common dir |
| card / lane / `workflowTaskId` / attachment metadata | `$PASEO_HOME/plugin-data/carseod/board.json` |
| attachment bytes | `plugin-data/carseod/attachments/<cardId>/` |

Board 不复制 queue/build 状态；它每次读取项目仓库的只读投影 `scripts/workflow-board-status --json`。读取失败只显示为 `workflow 不可用`，不影响看板主体。

## 卡片生命周期

可见 lane：`planned / working / done / archived`。

- 回合结束仍为 `working`；
- workflow 集成完成、dev build 成功且发布成功后自动进入 `done`；
- 归档由人显式操作，并归档 Paseo 工作区；归档是终态；
- `done` 卡片继续输入会恢复为 `working`。

## Task 绑定

workflow 项目中，卡片运行会创建独立 worktree，并调用 `workflow-attach --card-id` 注册 task。卡片只持有 task 指针；集成状态从 workflow 只读投影读取。

`question` 卡片在 `question/…` worktree 中讨论，不注册 task。用户在对话中确认后，可把卡片转为 task，并在原会话中继续执行。

## 边界

- 卡片正文、泳道和会话内容不能替代或静默修改 `PRD.md` / `AGENTS.md`。
- `done` 是人的验收，不是 release；稳定版本仍由 tag 表达。
- board 可以独立于 workflow 运行；workflow 也必须能在没有 board 的机器上运行。


---

# 同步文档平台 (https://docs.ttpi.space/dev-starter/docs-sync)

可选文档同步契约、Fumadocs 共享平台、发布流程与 AI 问答。

# 同步文档平台

文档同步是目标项目可选的能力（PRD C13 / P8）。启用后，文档成为一等产物：功能、结构、接口、命令或机制变化时，必须在同一任务中更新文档。本仓库自身已启用 `docs-sync.json`，内容在 `docs/content`，发布到共享平台。

## 目标项目契约

项目根目录的 `docs-sync.json` 显式启用：

```json
{
  "schema": 1,
  "enabled": true,
  "project": "my-project",
  "contentDir": "docs/content",
  "platform": {
    "url": "https://docs.example.com",
    "tokenEnv": "DOCS_PLATFORM_TOKEN"
  },
  "sync": {
    "baseRef": "main",
    "tracked": ["src/**", "scripts/**"],
    "requireCoverage": true,
    "requireContentChange": true
  }
}
```

页面是普通 Markdown，frontmatter 声明实现范围：

```markdown
---
title: Search
description: How search works.
sources:
  - src/search.ts
---

# Search
```

## 同步模型

- **Coverage**：`sync.tracked` 中每个文件必须被至少一个页面的 `sources` 匹配。
- **Fingerprint lock**：`docs/sync-lock.json` 记录页面与来源文件的 hash；代码变化后必须重新 review 并 stamp。
- **Branch content rule**：分支改 tracked 代码时必须改内容页；只更新锁不算。
- **Integration gate**：集成 runner 在项目 check 后执行 `docs-sync check`，失败不推进 `main`。
- **Agent prompts**：任务 brief、冲突/check-failure handoff 和 Paseo 插件 system prompt 都会注入文档规则。

## 命令

```bash
./scripts/docs-sync init --enable --project my-project --title "My Project"
./scripts/docs-sync check
./scripts/docs-sync stamp
./scripts/docs-sync build
./scripts/docs-sync publish
./scripts/docs-sync status
```

`.dev` 布局使用 `./.dev/scripts/docs-sync`。

## 发布

发布是集成后的操作：

```bash
DOCS_PLATFORM_TOKEN=... ./scripts/docs-sync publish
```

平台按内容 hash 保存不可变版本；同一内容重复发布是幂等的。页面、搜索、`llms.txt`、`llms-full.txt` 和 AI 问答都读取当前发布版本。

## 共享 Fumadocs 平台

平台实现在 `apps/docs`，是像 Carseod 一样的共享服务：

- Next.js + Fumadocs UI 渲染 Markdown 页面；
- 多项目发布 API，Bearer project token 鉴权；
- `/data/projects/<project>/versions/<sha256>` 保存不可变内容，`current.json` 指向当前版本；
- 搜索与 AI 问答只基于当前发布快照；
- AI 通过 OpenAI-compatible 流式接口接入，未配置模型时文档和搜索仍可用，AI 返回 503。

部署、TLS、反向代理、模型、持久卷与备份要求见仓库中的 `docs/docs-platform.md` 和 `deploy/docs-platform/`。

## 边界

- 文档内容保存在目标项目 Git 中，平台不是编辑器。
- 发布文档不能静默修改 `PRD.md` / `AGENTS.md`。
- 文档平台与 Carseod 一样集中部署，不复制进每个目标项目。
- 发布内容是公开的；不要写 token、密钥或未脱敏数据。


---

# 治理模型 (https://docs.ttpi.space/dev-starter/governance)

Human Surface、受保护文档，以及从 meaning 到 realization 的变更流程。

# 治理模型

## Human Surface 与 Agent Surface

**Human Surface** 保存用户需要长期理解和控制的项目含义：

```text
PRD.md
AGENTS.md
```

**Agent Surface** 保存技术设计、工作状态与实现事实：

```text
ARCHITECTURE.md
docs/adr/**
.work/**
src/**
tests/**
```

`ARCHITECTURE.md` 与 ADR 是 Agent-maintained canonical technical knowledge；`.work/**` 是可丢弃的工作状态，不能成为理解项目的唯一来源。

## 受保护文档

Agent 不得静默修改 `PRD.md` 或 `AGENTS.md`。需要修改时必须：

```text
detect → propose → show diff → human approval → apply
```

用户直接手工修改 Human Surface 时，修改立即成为新的高层约束。

## Highest affected layer

非平凡变化先判断最高受影响层：

| 层 | 默认处理 |
|---|---|
| L4 | 直接 plan / build / verify |
| L3 | Agent 自主设计、实现、维护技术文档 |
| L2 | 先判断是否改变 Human Surface |
| L1 / L0 | Human decision |

下层实现不得静默重新定义上层含义。

## 默认自主性

只要不改变 Human Surface，Agent 应自主完成模块拆分、internal API、schema、domain object、测试、重构、文件组织与普通实现选择。

只有当正确完成任务需要改变产品含义时，才把问题上浮给用户。

## 技术知识维护

稳定变化以下内容时更新 `ARCHITECTURE.md`：

- system boundary；
- major component；
- 重要 data / control flow；
- ownership boundary；
- architectural invariant；
- critical interface；
- durable technical constraint。

只有值得未来长期解释的技术决策才创建 ADR。普通实现选择不需要 ADR。

## Reconciliation

任务完成后自行检查：

1. 实现是否满足原目标；
2. 是否意外改变产品语义；
3. Architecture / ADR 是否过期；
4. 是否产生值得长期保存的新技术事实；
5. 是否出现必须上浮给用户的问题。


---

# dev-starter (https://docs.ttpi.space/dev-starter)

AI-native project governance, the Local Trunk workflow, and shared services.

# dev-starter

`dev-starter` 是一套 AI-native 项目基础结构与本地多 Agent 工作流。它解决的不是“如何让 AI 多写代码”，而是：

> 如何让 AI 长期参与开发，同时保持项目始终受人的真实意图控制。

## 设计分层

```text
L0  Intent                         为什么做？
L1  Outcomes                       最终希望发生什么？
L2  Product Capabilities           产品必须能做什么？有哪些边界？
----------------------------------  Human / Agent boundary
L3  System Design & Architecture   系统内部如何组织？
L4  Implementation                 具体如何实现？
```

- 用户控制 meaning：L0–L2，主要落在 `PRD.md`。
- Agent 控制 realization：`ARCHITECTURE.md`、ADR、代码、测试和技术文档。
- Agent 修改 `PRD.md` / `AGENTS.md` 前必须展示 diff 并获得批准。

## 四个平面

```text
Human meaning        PRD.md / AGENTS.md
      ↓
Control plane        Carseod board（可选）
      ↓
Execution plane      Paseo workspace + git worktree + OMP session
      ↓
Integration plane    task → queue → prefilter → integrator → main → dev build
      ↓
Release plane        vX.Y.Z tag + release artifact
```

## 从这里继续

- [治理模型](governance.md)：Human Surface、受保护文档、变更流程。
- [Local Trunk 工作流](workflow.md)：worktree、queue、串行集成、check 与发布。
- [Carseod 看板](board.md)：卡片、会话、授权与人的验收。
- [同步文档平台](docs-sync.md)：文档作为一等产物，以及共享 Fumadocs 平台。

## 原则

- Intent over implementation。
- Human intent 与 AI output 必须可区分。
- 人的注意力稀缺，技术细节默认由 Agent 承担。
- 长期资产是意图、结果、能力与关键约束，而不是某一种实现。


---

# Local Trunk 工作流 (https://docs.ttpi.space/dev-starter/workflow)

Paseo worktree、共享 Integration Queue、串行集成、check 与发布。

# Local Trunk 工作流

多个 Agent 在短生命周期 worktree 中并行开发；完成后进入共享 Integration Queue；一个 Integrator 决定顺序；集成锁保证一次只有一个任务推进 `main`。

## 不变量

1. Agent 不直接改 `main`；只有 `scripts/integration-runner` 在持有 `integration.lock` 时推进主干。
2. 一个任务 = 一个 Paseo workspace = 一个 git worktree = 一个 branch。
3. 完成 = submit，不是 PR。
4. Queue 位于 git common dir，所有 worktree 共享。
5. 集成串行；冲突回到原任务 Agent。
6. Integrator 只能在 ready 集合内排序，不能违反显式依赖。
7. `Done` 不等于稳定版本；稳定版本只由 `git tag vX.Y.Z` 表达。

## 生命周期

```text
Backlog
  ↓  Paseo New workspace / Carseod card
Developing        worktree + OMP session
  ↓  commit + ./scripts/check
  ↓  INTEGRATION_READY 或 ./scripts/integration-submit
Ready to Integrate
  ↓  integration-runner 预检 + Integrator 排序
Integrating       rebase → check → ff-only main
  ↓
Dev Shipped       main + dev build + publish
  ↓
Done              人的验收（不等于 release）
```

## 集成检查

`scripts/check` 是项目自己的最小 gate，必须 exit 0。集成 runner 还会在启用 `docs-sync.json` 时执行文档 gate：

```text
./scripts/docs-sync check --base <main-before>
```

失败时主干不移动，check 失败上下文回到原任务 workspace。

## 常用命令

```bash
./scripts/task-start TASK-42 "标题"
./scripts/integration-submit
./scripts/integration-runner
./scripts/integration-status
./scripts/release 0.10.0
```

没有 Paseo 时可用 `./scripts/task-start ... --no-paseo`；Integrator 不可用时用 `./scripts/integration-runner --fifo`。

## Paseo 入口

workflow 插件把 workflow 仓库里的 local workspace 请求转成 worktree，自动 attach task、注入 `WORKFLOW_TASK_ID` 与任务规范，并在最终回复检测到 `INTEGRATION_READY` 后自动 submit / integrate。

`question/…` 分支的讨论 worktree 不注册 task、不注入任务规范，也不自动 submit / integrate。