# octopus Core（工作流标准公共层）

`core/` 是工作流体系标准化后的**公共 Core**：自包含的规则、技能、
清单、模板、schema 与适配器层。`.octopus/` 下的对应文件是**消费副本**
（dogfood 实例），`examples/` 仅承载叙事性示例。

## 不变量 C-1：Core 不引用实例

- Core 内的工件**不得引用** `examples/` 或任何实例专有路径；`core/adapters/**`
  例外——adapter 目录承载后端绑定的 API 形态（工具名、端点），但仍
  **禁止实例机密与实例专有地址**（内网 IP、实例主机名、实例配置路径）。
- 引用方向是**单向的**：`examples/` 与实例层可以引用 Core，Core 永远不
  回头引用它们。
- 机械化校验：`script/check-core-cohesion.ts` 的 C-1 扫描——HARD 模式
  （实例机密/专有地址）对全部 core 生效；SOFT 模式（实例路径/工具名）
  对 `core/adapters/**` 豁免、其余 core 文件生效（见「增量采用」）。

## 不变量 C-2：迁移保编号

- 清单迁移**仅改位置、不改编号**：任何规则 / 技能 / 清单迁入 Core 时，
  其标识符（issue 编号、TD 编号、检查项编号）原样保留。
- 编号是跨实例的稳定契约；重编号会切断历史追溯链。
- 映射登记：`core/CORE-MANIFEST.json`（core 路径 ↔ dogfood 路径 ↔ 批次），
  编号保真映射表骨架见 `core/MIGRATION.md`。

## SSOT 契约（单一事实源）

- **Core = 全量权威副本**：规则、技能、\_shared、清单、模板已全部迁入，
  所有修改先落在 `core/`。**builtin overlay 源权威 = core/**（Increment 6b
  起，`packages/octopus/script/generate-builtin.ts` 的 EMBED_SOURCES 从
  core/ 读取——shipped 默认语料为中立版；仅当实例磁盘无
  `<instance-root>/` 目录时 overlay 才生效）。
- **`.octopus/` = 消费镜像**：dogfood 实例通过 `script/core-sync.sh` 从
  Core 单向同步（verbatim / verbatimDir 自动逐文件同步；rewritten /
  split 按术语表落地），永不反向。
- **`examples/` 仅叙事**：只引用 Core，不承载事实源内容。
- 机械化守护：
  - `script/core-sync.sh` — 单向同步（`--check` 只检不写，CI 用）；
  - `script/check-core-parity.ts` — 逐对比较 manifest 登记的文件内容，
    不一致即报漂移；
  - `script/check-core-cohesion.ts` — manifest 路径存在性 + C-1 扫描；
  - `script/check-dangling-refs.ts` — 双侧路径存在性 + core 内部引用
    完整性（intra-core 悬空检出；`--scope-report` 输出覆盖摘要）；
  - `script/check-scaffold-parity.ts` — scaffold-template twin 逐字节
    校验（schema $id owner token 归一化比较）；
  - `script/delink-core.ts` — 去链接化契约执行（#NNNN 活引用 → [org-internal #NNNN]
    注记；幂等；--check 零剩余才过；Inc 6b 字节锁镜像翻转 rewritten 后无递延）；
  - `script/check-core-p1.ts` — P1 零残留终验（私网 IP / 实例主机名 / 个人
    身份 / 旧 owner token 全树 grep；豁免 id-aliases.json 与历史命名空间
    URL 声明；Inc 6b 起无字节锁递延）；
  - `script/check-schema-ids.ts` — core schemas $id 命名空间/文件名匹配
    - id-aliases 一对一/存在性 + 历史接受集声明在位（完整 guards 表见
      文末「机械化守护（guards）」）。

## 发布单元达标（Increment 6a + 6b）

- **去链接化契约已执行**：core/** 全树 #NNNN 活引用已注记化
  （[org-internal #NNNN]），delink:core 幂等可重跑，--check 为零剩余门。
  Inc 6b 已解锁 6a 递延的 60 处字节锁镜像引用（翻转 rewritten 后 core 侧
  全量注记化，0 递延）。
- **P1 零残留终验门**：check:core-p1 扫 core/ 全部文本文件（md/yaml/
  json/ts），命中私网 IP、实例主机名、个人身份、旧 owner token 即 FAIL；
  id-aliases.json（SCH-F401）与 runs-index 历史命名空间声明豁免。
  Inc 6b 已清偿 6a 递延的 2 处旧 owner token 命中（0 递延）。
- **examples/ 方向性**：组织沉积教学案例（叙事），只引用 Core、不被 Core
  引用（C-1 单向）；不入 manifest、不进 cohesion 扫描面。

## 目录语义

| 目录                   | 语义                                                    |
| ---------------------- | ------------------------------------------------------- |
| `core/rules/`          | L1 强制规则的 Core 源（14 份已全部迁入，G0–G3）         |
| `core/skills/`         | 技能整目录的 Core 源（17 个已全部迁入，G4 verbatimDir） |
| `core/skills/_shared/` | 技能共享工件（角色 yaml、评审管线文件等，14 份，G4）    |
| `core/checklists/`     | 清单（13 份已全部迁入，G4）                             |
| `core/templates/`      | 模板（dag.md、runs 布局，2 份已全部迁入，G4）           |
| `core/schemas/`        | JSON Schema（8 份已迁入，G5；$id 已迁至公共命名空间）   |
| `core/adapters/`       | 实例适配层（后端参考实现；SOFT 扫描豁免、HARD 仍生效）  |

## 增量采用

Core 的采用以 `core/CORE-MANIFEST.json` 登记为准——**登记了才算采用**。
G0–G4 批次已完成全量迁移（14 规则、17 技能整目录、\_shared 14 份、
13 清单、2 模板）；后续批次按 `core/MIGRATION.md` 的映射表推进。

### C-1 扫描的增量形态（设计决策）

模式分两级（Increment 3）：

- **HARD**（全 core 生效，含 adapters）：实例主机名、内网 IP 段、实例
  配置路径——实例机密与实例专有地址任何 core 文件不得出现。
- **SOFT**（`core/adapters/**` 豁免）：`.octopus/`、`packages/octopus`、
  后端绑定内容（REST 端点、工作树路径等）——adapter 目录是 Gitea 参考
  实现，允许承载；其余 core 文件不得出现。

G0 三份规则是从实例规则**逐字复制**的，规则正文里出现实例路径字样属
**叙述性引用**，且都在行内代码/围栏内（扫描先剥离，零命中）。
脚本以 `--strict` 开关预留更严形态：`--strict` 时额外对 verbatim 文件
按全模式集扫描（剥离语义同前）。默认扫描面 = core 下全部 `.md` 文件
（含 adapters，adapters 只查 HARD）。扫描匹配前先剥离行内代码 span
（反引号内文字）与围栏代码块——反引号内的是定义性提及（如本文件对
C-1 模式列表的描述），不是活引用。

### manifest 语义（sync 字段）

| sync 值       | 语义                                                                  | parity 校验                                       | core-sync 行为                       |
| ------------- | --------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------ |
| `verbatim`    | 逐字复制                                                              | 字节比较                                          | Core → dogfood 自动 `cp`             |
| `verbatimDir` | 整目录逐字复制（目录级行，core 路径以 `/` 结尾）                      | 递归文件集一致（排除 `.gitkeep`）+ 逐文件字节比较 | Core → dogfood 逐文件同步            |
| `rewritten`   | 接口中立化改写                                                        | 双侧存在 + core 侧 HARD+SOFT 扫描                 | `managed-by: rewrite (no auto-sync)` |
| `split`       | adapter 拆分上提（页名/寻址语义已上提 Core 契约，API 形态留 adapter） | 双侧存在 + core 侧 HARD 扫描（SOFT 豁免）         | `managed-by: split (no auto-sync)`   |
| `core-only`   | Core 原生契约，无 dogfood 对应（`dogfood: null`）                     | core 存在 + HARD+SOFT 扫描，无 dogfood 检查       | `managed-by: core-only`              |

`deferHard: true`（历史字段，**Increment 6a 已全数清零**）：曾标记暂含实例
表述的行；6a 已将全部 27 行中立化改写为 rewritten 并删除该键。现
manifest 中不存在 deferHard 行，cohesion `--strict` 的 deferred 计数为 0。