@jennie-shawn/starwork 0.1.0-alpha.2 → 0.1.0-alpha.21

package/docs/m2.6-project-init-feedback/m2.6-project-init-feedback-02-hub-sync-boundary-spec.md

@@ -0,0 +1,198 @@
+# M2.6 Project Init 反馈 02：Hub Sync 可见边界 SPEC
+
+## 状态
+
+- 版本：v0.1 implemented
+- 所属阶段：M2.6 既有功能优化与 A 测稳定化
+- 所属模块：StarWork Core / Project Kit / CLI init / CLI spawn
+- 反馈来源：单项目初始化 A 测
+- 问题类型：Core 架构和目录边界错误
+
+## 用户反馈
+
+单项目 `_system/` 下出现了 `main-repo-sync/`。用户不知道 Main Repo Sync 是什么，也没有建立 Hub，导致单项目工作台第一屏出现多项目架构概念。
+
+## 根因
+
+Project Kit 被设计为独立 Project 和 Satellite Project 共用，但模板把 Hub/Satellite 同步说明作为默认可见目录放进了所有 Project。
+
+这会造成三个问题：
+
+- 单项目用户被迫理解 Hub / main repo / sync。
+- Agent 可能误以为当前项目已经接入 Hub。
+- `_system/` 从“项目工作入口”变成“机制说明堆放处”。
+
+## 目标
+
+独立 Project 初始化结果不能默认出现 Hub 同步目录。
+
+Hub 同步说明只在这些情况出现：
+
+- `starwork spawn` 从 Hub 生成 Satellite Project。
+- `starwork upgrade` 明确将旧主库或旧多项目工作区接入 Hub-like 模式。
+- 用户显式要求把 Project 接入 Hub。
+
+## 非目标
+
+- 不取消 Hub / Satellite 能力。
+- 不删除 `.starwork/sync.json` 作为机制运行层的可能性。
+- 不在本 SPEC 里设计完整 `starwork attach-hub` 命令。
+- 不让独立 Project 默认理解或维护 Hub registry。
+
+## 目录分层决策
+
+### 独立 Project 默认结构
+
+独立 Project 可以有：
+
+```text
+_system/context/current-project.md
+_system/tasks/current-work.md
+_system/identity/README.md
+_system/lessons/README.md
+knowledge/README.md
+.starwork/workspace.json
+.starwork/skills.json
+.starwork/handoff/state.json
+```
+
+独立 Project 默认不应有：
+
+```text
+_system/main-repo-sync/
+_系统/主库同步/
+.core-sync.json
+.internal/
+```
+
+说明：
+
+- `.starwork/handoff/` 可作为 StarWork 机制层保留，但 AGENTS 不应要求用户理解跨项目联络，除非已连接 Hub。
+- `.core-sync.json` 是 legacy mirror，只应出现在 Satellite 或升级兼容场景。
+- `.internal/` 是 Hub/主库协议快照，不应作为独立 Project 默认可见结构。
+
+### Satellite Project 结构
+
+从 Hub 生成的 Satellite 可以有：
+
+```text
+_system/main-repo-sync/README.md
+.starwork/sync.json
+.core-sync.json
+.starwork/internal/
+knowledge/ -> Hub knowledge
+```
+
+AGENTS 需要说明：只有涉及 Hub 资源、共享 skills 或跨项目交接时才读 main-repo-sync。
+
+## 举一反三排查
+
+实现时必须排查所有“独立 Project 默认出现 Hub 机制”的路径：
+
+- `product/core/kits/project/_系统/主库同步/`
+- `product/core/kits/project/.internal/`
+- `product/core/kits/project/.starwork/handoff/`
+- `product/core/kits/project/知识/README.md`
+- `product/core/kits/project/README.md`
+- `product/core/kits/project/AGENTS.md`
+- `product/cli/src/cli.js` 的 `mapKitRelativePathForLanguage()`
+- `product/cli/src/cli.js` 的 `renderEnglishMainRepoSyncReadme()`
+- `product/cli/src/cli.js` 的 `buildInitPlan()` 是否复制所有 Kit 文件
+- `product/cli/src/cli.js` 的 `buildSpawnPlan()` 是否单独补 Satellite 同步文件
+- `product/core/kits/two-kit-architecture-spec.md` 中 Project Kit 目标结构是否仍把 Hub 同步目录作为默认项
+
+排查关键词：
+
+```text
+main-repo-sync
+主库同步
+.core-sync.json
+.internal
+Hub sync
+Satellite
+main repository
+跨项目联络
+```
+
+## 优化方案
+
+### 方案 A：模板拆分
+
+将 Project Kit 中的 Hub 同步相关文件移出默认 Kit，改为 Satellite overlay。
+
+建议结构：
+
+```text
+core/kits/project/
+core/kits/project-satellite-overlay/
+```
+
+`starwork init --type project` 只复制 `project/`。
+
+`starwork spawn` 复制 `project/` 后，再叠加 `project-satellite-overlay/`。
+
+### 方案 B：CLI 过滤
+
+短期可在 `buildInitPlan()` 中过滤 Hub 同步文件：
+
+```text
+_系统/主库同步/**
+_system/main-repo-sync/**
+.core-sync.json
+.internal/**
+```
+
+同时保留 `buildSpawnPlan()` 对 Satellite 的生成。
+
+方案 A 更干净，方案 B 可作为 alpha 热修。
+
+## 验收标准
+
+### 独立 Project 验收
+
+执行：
+
+```bash
+starwork init --type project --language en --pack general --target <tmp> --yes
+starwork doctor --target <tmp>
+```
+
+必须满足：
+
+- 不存在 `_system/main-repo-sync/`。
+- 不存在 `.core-sync.json`。
+- 不存在 `.internal/`。
+- `AGENTS.md` 不出现 main repo / Hub sync 作为默认读取项。
+- `doctor` 通过。
+
+中文同理：
+
+- 不存在 `_系统/主库同步/`。
+- 不存在 `.core-sync.json`。
+- 不存在 `.internal/`。
+
+### Satellite 验收
+
+执行：
+
+```bash
+starwork init --type hub --language en --target <hub> --yes
+starwork spawn --hub <hub> --name Demo --target <project> --language en --yes
+starwork doctor --target <project>
+```
+
+必须满足：
+
+- 存在 `_system/main-repo-sync/README.md` 或等价 Satellite 同步说明。
+- 存在 `.starwork/sync.json`。
+- `.core-sync.json` 仅作为 legacy mirror 出现。
+- `AGENTS.md` 说明 main-repo-sync 只在 Hub 资源、共享 skills 或跨项目交接时读取。
+- `doctor` 通过。
+
+### 防复发验收
+
+- 测试必须同时覆盖 `init project` 和 `spawn satellite`。
+- 测试必须断言独立 Project 不含 Hub 同步目录。
+- 测试必须断言 Satellite 含 Hub 同步说明。
+- `doctor` 不得要求独立 Project 具备 Hub 同步文件。
+- 文档和 CLI help 不得把单项目称为 main repo 或 satellite。

package/docs/m2.6-project-init-feedback/m2.6-project-init-feedback-03-current-project-purity-spec.md

@@ -0,0 +1,238 @@
+# M2.6 Project Init 反馈 03：Current Project 事实源纯度 SPEC
+
+## 状态
+
+- 版本：v0.1 implemented
+- 所属阶段：M2.6 既有功能优化与 A 测稳定化
+- 所属模块：StarWork Core / CLI init / Skills / Blueprint
+- 反馈来源：单项目初始化 A 测
+- 问题类型：Skill 输出污染项目事实源
+
+## 用户反馈
+
+`_system/context/current-project.md` 里出现了 “Initialized as a StarWork project workspace with a custom code-focused structure.” 这类 StarWork 初始化过程描述。用户要的是自己的项目状态，而不是 StarWork 施工记录。
+
+## 根因
+
+`current-project.md` 既被模板当成项目事实源，又被 Agent/blueprint 当成初始化结果摘要的承载位置。
+
+在 Skill 约束不足时，AI 会把以下内容写进项目事实源：
+
+- StarWork 初始化完成情况。
+- blueprint 定制说明。
+- 未使用目录列表。
+- CLI 施工步骤。
+- “下一步运行 doctor” 这类工具建议。
+
+这些内容属于 `.starwork/` 机制层、CLI 输出或会话回复，不属于用户项目事实。
+
+## 目标
+
+`current-project.md` 必须只记录用户项目事实。
+
+它可以记录：
+
+- 项目目标。
+- 当前阶段。
+- 近期重点。
+- 主要事实源。
+- 当前风险。
+- 下一步业务动作。
+
+它不能记录：
+
+- StarWork 初始化日志。
+- blueprint 文件路径。
+- CLI dry-run 结果。
+- 哪些默认目录没有创建。
+- npm / skills / doctor 安装验证过程。
+- Agent 自己的施工解释。
+
+## 非目标
+
+- 不禁止 `.starwork/workspace.json` 记录创建来源。
+- 不禁止 CLI 在终端输出初始化总结。
+- 不禁止 Agent 在对话里向用户汇报执行结果。
+- 不要求 current-project 在初始化后就完整填写。
+
+## 模板要求
+
+独立 Project 默认 `current-project.md` 应是干净占位模板：
+
+```markdown
+# Current Project
+
+## Goal
+
+TBD.
+
+## Current Stage
+
+TBD.
+
+## Focus
+
+- TBD.
+
+## Primary Sources
+
+- TBD.
+
+## Risks
+
+- TBD.
+
+## Next Step
+
+- TBD.
+```
+
+中文对应：
+
+```markdown
+# 当前项目
+
+## 目标
+
+待填写。
+
+## 当前阶段
+
+待填写。
+
+## 近期重点
+
+- 待填写。
+
+## 主要事实源
+
+- 待填写。
+
+## 风险
+
+- 待填写。
+
+## 下一步
+
+- 待填写。
+```
+
+## Blueprint 写入边界
+
+`init-blueprint.json` 不应直接生成或覆盖 `current-project.md`，除非 schema 明确新增专门字段，例如：
+
+```json
+{
+  "project_context": {
+    "goal": "...",
+    "stage": "...",
+    "focus": ["..."],
+    "primary_sources": ["src/", "docs/"]
+  }
+}
+```
+
+即便支持该字段，也必须满足：
+
+- 只写用户项目事实。
+- 不写 StarWork 初始化过程。
+- 不写 CLI 施工信息。
+- 不写 Agent 自我评价。
+
+## Skill 防发挥规则
+
+`starworkInit` 必须明确：
+
+- 创建工作台时，可以把执行结果回复给用户，但不要把执行结果写进 `current-project.md`。
+- 如果用户没有提供项目目标，`current-project.md` 保持 TBD。
+- 如果用户提供的是“我要创建一个代码项目，代码放 src，文档放 docs”，可以写入 primary sources，但不要写“Initialized as StarWork”。
+- “Folders Not Used”“不要创建 outputs/references” 属于规则或 blueprint 约束，不属于 current project。
+
+## 举一反三排查
+
+排查所有可能被 AI 污染的项目事实源：
+
+- `_system/context/current-project.md`
+- `_系统/上下文/当前项目.md`
+- `_system/tasks/current-work.md`
+- `_系统/任务/当前工作.md`
+- `README.md`
+- `AGENTS.md`
+- `.starwork/rules/*.md`
+
+排查关键词：
+
+```text
+Initialized as
+StarWork project workspace
+blueprint
+dry-run
+doctor
+Folders Not Used
+not used
+generated by starwork
+created by starwork
+```
+
+允许这些词出现在：
+
+- `.starwork/workspace.json`
+- CLI stdout
+- 测试断言
+- SPEC 文档
+
+不允许默认出现在：
+
+- `current-project.md`
+- `AGENTS.md`
+- 用户业务 README
+
+## 验收标准
+
+### 文件验收
+
+执行带定制 blueprint 的初始化后：
+
+```bash
+starwork init --target <tmp> --blueprint <init-blueprint.json> --yes
+```
+
+`_system/context/current-project.md` 必须满足：
+
+- 不包含 `Initialized as`。
+- 不包含 `StarWork project workspace`。
+- 不包含 `blueprint`。
+- 不包含 `Folders Not Used`。
+- 不包含 `doctor` 作为初始化步骤。
+- 如果用户没有提供明确项目事实，相关字段保持 `TBD`。
+
+### 行为验收
+
+- `doctor` 仍通过。
+- CLI stdout 可以提示 `doctor` 下一步，但不写入 current-project。
+- `.starwork/workspace.json` 可以记录 `created_by` 和 customization。
+
+### Skill 验收
+
+给 `starworkInit` 一个需求：
+
+```text
+Create an English code project. Use src for code and docs for design docs. Do not use references or outputs.
+```
+
+Agent 生成的 current-project 只能写：
+
+- Goal: code project 或用户真实项目目标。
+- Primary Sources: `src/`, `docs/`.
+
+不得写：
+
+- StarWork 初始化状态。
+- 未使用目录列表。
+- CLI 执行过程。
+
+### 防复发验收
+
+- 新增测试读取初始化后的 current-project，断言不含污染关键词。
+- `starworkInit/SKILL.md` 必须包含“项目事实源纯度”约束。
+- 如果未来新增 `project_context` blueprint 字段，必须有 schema 校验和测试覆盖。

package/docs/m2.6-project-init-feedback/m2.6-project-init-feedback-04-system-placeholder-templates-spec.md

@@ -0,0 +1,213 @@
+# M2.6 Project Init 反馈 04：System 占位模板 SPEC
+
+## 状态
+
+- 版本：v0.1 implemented
+- 所属阶段：M2.6 既有功能优化与 A 测稳定化
+- 所属模块：StarWork Core / Project Kit / Profiles
+- 反馈来源：单项目初始化 A 测
+- 问题类型：Core 模板可用性不足
+
+## 用户反馈
+
+`_system/identity/` 里只有 README，用户和 AI 都不知道下面应该写什么。System 文件夹下的文件应该是模板或占位文档，而不是纯说明。
+
+## 根因
+
+当前 Project Kit 把 `_system/` 当成机制说明层维护，而不是当成用户和 Agent 会长期使用的工作入口。
+
+README 只能解释“这个目录是什么”，但不能稳定指导“这里该写什么”。对 AI 来说，缺少字段模板会导致两种问题：
+
+- 不写，长期上下文缺失。
+- 自由发挥，写入不稳定结构。
+
+## 目标
+
+System 层每个用户可写或候选可写的区域，都要有清晰占位模板。
+
+用户打开后应该能填写；AI 读取后应该知道结构；doctor 或测试应该能判断模板是否存在。
+
+## 非目标
+
+- 不要求用户初始化时填写所有模板。
+- 不让 AI 自动补全用户身份或教训。
+- 不把 system 变成复杂数据库。
+- 不在本 SPEC 中设计 UI 表单。
+
+## System 文件分类
+
+### 事实源文件
+
+必须有明确字段：
+
+```text
+_system/context/current-project.md
+_system/tasks/current-work.md
+```
+
+### 长期上下文目录
+
+至少 README 本身必须是可填写模板：
+
+```text
+_system/identity/README.md
+_system/lessons/README.md
+```
+
+### 机制说明目录
+
+只在相关形态出现：
+
+```text
+_system/main-repo-sync/README.md
+```
+
+独立 Project 默认不出现。
+
+## 建议模板
+
+### current-work
+
+```markdown
+# Current Work
+
+## Now
+
+- TBD.
+
+## Next
+
+- TBD.
+
+## Waiting On
+
+- TBD.
+
+## Notes For Next Agent
+
+- TBD.
+```
+
+### identity
+
+见 `m2.6-project-init-feedback-01-identity-spec.md`。
+
+### lessons
+
+```markdown
+# Lessons
+
+Record reusable lessons that should change future behavior.
+
+## Active Lessons
+
+- TBD.
+
+## Candidate Lessons
+
+- TBD.
+
+## How To Add A Lesson
+
+A good lesson should be specific, reusable, and behavior-changing.
+Do not record ordinary progress summaries here.
+Ask before promoting a candidate lesson into a stable lesson.
+```
+
+中文：
+
+```markdown
+# 教训
+
+记录会改变未来行为的可复用经验。
+
+## 已确认教训
+
+- 待填写。
+
+## 候选教训
+
+- 待填写。
+
+## 写入规则
+
+好的教训应该具体、可复用，并能改变后续行为。
+不要把普通进度摘要写到这里。
+将候选教训提升为稳定教训前需要确认。
+```
+
+### knowledge
+
+独立 Project 默认 `knowledge/README.md` 应说明：
+
+- 存放项目本地知识入口或索引。
+- 不默认是 Hub 链接。
+- 若未来连接 Hub，再转为只读共享知识入口。
+
+## 举一反三排查
+
+排查所有只有说明、没有可填写结构的 system 文件：
+
+- `_system/context/current-project.md`
+- `_system/tasks/current-work.md`
+- `_system/identity/README.md`
+- `_system/lessons/README.md`
+- `knowledge/README.md`
+- 中文镜像下所有对应文件
+- `core/profiles/en/reference-kits/local-starter/**`
+- `core/profiles/zh/templates/**`
+- CLI 英文覆盖函数 `renderSatelliteKitContent()`
+
+排查关键词：
+
+```text
+Put ... here.
+This folder contains ...
+TBD
+待填写
+read-only by default
+snapshot
+candidate
+```
+
+原则：
+
+- 只有机制说明目录可以纯说明。
+- 用户会写的目录必须有字段模板。
+- 只读目录必须说明何时读、何时不能改。
+
+## 验收标准
+
+### 文件验收
+
+中英文 `starwork init --type project` 后：
+
+- current-project 存在，并包含 Goal/Stage/Focus/Risks/Next 或中文等价字段。
+- current-work 存在，并包含 Now/Next/Waiting On/Notes For Next Agent 或中文等价字段。
+- identity README 存在，并包含 Durable Context/Communication Preferences/Stable Constraints 或中文等价字段。
+- lessons README 存在，并包含 Active Lessons/Candidate Lessons/How To Add A Lesson 或中文等价字段。
+- knowledge README 对独立 Project 不写成 Hub 只读链接。
+
+### AI 验收
+
+只给 Agent system 目录后，Agent 应能判断：
+
+- 当前项目状态写 current-project。
+- 当前推进写 current-work。
+- 用户偏好和长期背景写 identity。
+- 可复用经验写 lessons。
+- 普通进度不能写 lessons。
+
+### Doctor 验收
+
+`starwork doctor` 至少检查：
+
+- system 事实源文件存在。
+- identity 和 lessons 入口存在。
+- 如果未来新增 schema，可检查必需标题。
+
+### 防复发验收
+
+- 新增 snapshot 或文本断言测试，覆盖中英文 Project 初始化模板。
+- 测试不得只检查文件存在，还要检查关键标题。
+- 后续新增 system 目录时，必须同时定义“读写规则”和“占位模板”。