@kunlv/atdc 1.0.0

package/src/utils.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+const { PACKAGE_DIR, PLACEHOLDER } = require('./constants');
+
+function exists(p) {
+  try { fs.accessSync(p); return true; } catch { return false; }
+}
+
+function isSymlink(p) {
+  try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; }
+}
+
+function getSymlinkTarget(p) {
+  try { return fs.readlinkSync(p); } catch { return null; }
+}
+
+function mkdirp(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function createSymlink(target, linkPath) {
+  const linkDir = path.dirname(linkPath);
+  mkdirp(linkDir);
+  if (exists(linkPath) || isSymlink(linkPath)) {
+    fs.rmSync(linkPath, { recursive: true, force: true });
+  }
+  const stat = fs.statSync(target);
+  const type = stat.isDirectory() ? 'dir' : 'file';
+  fs.symlinkSync(target, linkPath, type);
+}
+
+function removeSymlink(linkPath) {
+  if (isSymlink(linkPath)) {
+    fs.unlinkSync(linkPath);
+  } else if (exists(linkPath)) {
+    fs.rmSync(linkPath, { recursive: true, force: true });
+  }
+}
+
+function replaceInFile(filePath, search, replacement) {
+  if (!exists(filePath)) return false;
+  let content = fs.readFileSync(filePath, 'utf8');
+  if (content.includes(replacement)) return false;
+  if (!content.includes(search)) return false;
+  content = content.split(search).join(replacement);
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
+function replaceAllInDir(dir, search, replacement) {
+  if (!exists(dir)) return 0;
+  let count = 0;
+  const walk = (d) => {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const fp = path.join(d, entry.name);
+      if (entry.isDirectory()) { walk(fp); }
+      else if (entry.isFile() && entry.name.endsWith('.md')) {
+        if (replaceInFile(fp, search, replacement)) count++;
+      }
+    }
+  };
+  walk(dir);
+  return count;
+}
+
+function resolvePackageDir() {
+  return PACKAGE_DIR;
+}
+
+function isTerminalInstalled(checkDirs) {
+  return checkDirs.some(exists);
+}
+
+module.exports = {
+  exists, isSymlink, getSymlinkTarget, mkdirp,
+  createSymlink, removeSymlink,
+  replaceInFile, replaceAllInDir,
+  resolvePackageDir, isTerminalInstalled,
+};

package/src/validators/state-validate.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+// state-validate.js — validates .phase-state.json schema integrity
+// Usage: node state-validate.js [--file=<path>]
+
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRED_FIELDS = ['change', 'phase', 'mode', 'tasks', 'verifiedAt', 'archived'];
+const VALID_PHASES = ['open', 'design', 'build', 'verify', 'archive'];
+const VALID_MODES = ['full', 'hotfix', 'tweak'];
+const KNOWN_FIELDS = [
+  ...REQUIRED_FIELDS, 'verificationReport', 'branchStatus',
+  'startedAt', 'updatedAt'
+];
+
+function findStateFile() {
+  const arg = process.argv.find(a => a.startsWith('--file='));
+  if (arg) return arg.slice(7);
+
+  // Auto-detect: find first active change with .phase-state.json
+  const changesDir = 'openspec/changes';
+  if (!fs.existsSync(changesDir)) return null;
+  const entries = fs.readdirSync(changesDir).filter(e => {
+    if (e === 'archive') return false;
+    const stat = fs.statSync(path.join(changesDir, e));
+    if (!stat.isDirectory()) return false;
+    return fs.existsSync(path.join(changesDir, e, '.phase-state.json'));
+  });
+  if (entries.length === 0) return null;
+  return path.join(changesDir, entries[0], '.phase-state.json');
+}
+
+function main() {
+  const filePath = findStateFile();
+  if (!filePath) {
+    console.log('No .phase-state.json found. Use --file= to specify path.');
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (e) {
+    console.log(`FAIL: invalid JSON in ${filePath}`);
+    console.log(`  ${e.message}`);
+    process.exit(1);
+  }
+
+  console.log(`Validating: ${filePath}`);
+  const errors = [];
+  const warnings = [];
+
+  // Check required fields
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in data)) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+
+  // Check phase value
+  if (data.phase && !VALID_PHASES.includes(data.phase)) {
+    errors.push(`invalid phase "${data.phase}" (valid: ${VALID_PHASES.join(', ')})`);
+  }
+
+  // Check mode value
+  if (data.mode && !VALID_MODES.includes(data.mode)) {
+    errors.push(`invalid mode "${data.mode}" (valid: ${VALID_MODES.join(', ')})`);
+  }
+
+  // Check tasks structure
+  if (data.tasks && typeof data.tasks !== 'object') {
+    errors.push('tasks must be an object with {total, completed}');
+  } else if (data.tasks) {
+    if (typeof data.tasks.total !== 'number') errors.push('tasks.total must be a number');
+    if (typeof data.tasks.completed !== 'number') errors.push('tasks.completed must be a number');
+  }
+
+  // Check types
+  if (data.phase !== undefined && typeof data.phase !== 'string') {
+    errors.push('phase must be a string');
+  }
+  if (data.mode !== undefined && typeof data.mode !== 'string') {
+    errors.push('mode must be a string');
+  }
+  if (data.archived !== undefined && typeof data.archived !== 'boolean') {
+    errors.push('archived must be a boolean');
+  }
+  if (data.verifiedAt !== undefined && data.verifiedAt !== null && typeof data.verifiedAt !== 'string') {
+    errors.push('verifiedAt must be a string or null');
+  }
+
+  // Check unknown fields (warnings only)
+  for (const key of Object.keys(data)) {
+    if (!KNOWN_FIELDS.includes(key)) {
+      warnings.push(`unknown field: ${key}`);
+    }
+  }
+
+  // Report
+  if (errors.length > 0) {
+    console.log(`\nERRORS (${errors.length}):`);
+    errors.forEach(e => console.log(`  ✗ ${e}`));
+  }
+
+  if (warnings.length > 0) {
+    console.log(`\nWARNINGS (${warnings.length}):`);
+    warnings.forEach(w => console.log(`  ⚠ ${w}`));
+  }
+
+  if (errors.length === 0) {
+    if (warnings.length === 0) {
+      console.log('✓ schema valid');
+    } else {
+      console.log('✓ schema valid (with warnings)');
+    }
+  }
+
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+main();

package/templates/.phase-state.json

@@ -0,0 +1,13 @@
+{
+  "$schema": ".atd-code/phase-state.schema.json",
+  "change": "",
+  "phase": "open",
+  "mode": "full",
+  "tasks": { "total": 0, "completed": 0 },
+  "verifiedAt": null,
+  "archived": false,
+  "verificationReport": null,
+  "branchStatus": "pending",
+  "startedAt": "",
+  "updatedAt": ""
+}

package/templates/adr.md

@@ -0,0 +1,62 @@
+# ADR-<序号>: <标题>
+
+> 状态：提议 / 已采纳 / 已废弃 / 已取代
+> 日期：<YYYY-MM-DD>
+> 决策者：<@user 或 AI + user 确认>
+
+---
+
+## 背景
+
+<为什么需要做这个决策？遇到了什么问题？有什么约束？>
+
+---
+
+## 决策
+
+<我们决定做什么？一句话。>
+
+---
+
+## 考虑的方案
+
+### 方案 A：<名称>（✅ 选定）
+
+- 优点：
+- 缺点：
+- 风险：
+
+### 方案 B：<名称>
+
+- 优点：
+- 缺点：
+- 风险：
+- 为什么没选：
+
+### 方案 C：<名称>（如有）
+
+- 优点：
+- 缺点：
+- 风险：
+- 为什么没选：
+
+---
+
+## 后果
+
+### 正面影响
+
+- <决策带来的好处>
+
+### 负面影响 / 需要关注的
+
+- <决策带来的代价、限制、技术债>
+
+---
+
+## 相关
+
+- 被以下 ADR 取代：<ADR-xxx>（如有）
+- 取代以下 ADR：<ADR-xxx>（如有）
+- 相关模块：<模块名>
+- 相关 Change：<change-name>

package/templates/changelog.md

@@ -0,0 +1,21 @@
+# changelog: <change-name>
+
+需求变更记录。每次变更由 `/atd:1-update` 自动追加，按时间倒序排列。
+
+---
+
+## [YYYY-MM-DD] <变更标题>
+
+**类型**：新增 / 修改 / 删除
+**原因**：<变更原因>
+**内容**：<变更描述>
+
+**影响文件**：
+- `proposal.md`：<具体变更>
+- `design.md`：<具体变更>
+- `specs/<模块>/spec.md`：<具体变更>
+- `tasks.md`：<具体变更（新增/删除/修改）>
+
+**Verification Checklist 变更**：
+- 新增：<条目>
+- 删除：<条目>

package/templates/concepts.md

@@ -0,0 +1,35 @@
+# Concepts — <项目名>
+
+> 项目共享领域词汇表。新成员/新 session 快速理解业务语言。
+> 由 `/atd compound` 和 `/atd context` 自动维护，也可手动编辑。
+
+## 核心实体
+
+| 术语 | 英文/代码名 | 含义 | 关联文件 |
+|------|------------|------|---------|
+| <术语> | <代码中的命名> | <业务含义> | <相关文件路径> |
+
+## 命名流程
+
+| 流程名 | 触发条件 | 核心步骤 | 入口函数/API |
+|--------|---------|---------|-------------|
+| <流程名> | <什么情况下触发> | <1-3 步概述> | <函数名或路由> |
+
+## 状态机
+
+| 实体 | 状态 | 含义 | 可流转到 |
+|------|------|------|---------|
+| <实体名> | <状态值> | <业务含义> | <下一状态列表> |
+
+## 约定与缩写
+
+| 缩写/术语 | 全称 | 说明 |
+|-----------|------|------|
+| <缩写> | <全称> | <什么时候用> |
+
+---
+
+> **维护规则**：
+> - 每个术语一行，不超过 3 列（术语、含义、关联）。
+> - 只记录非显而易见的业务概念，不记录通用技术术语（如 "HTTP"、"JSON"）。
+> - 新增概念时同步更新此文件，可通过 `/atd compound` 自动提取。

package/templates/design.md

@@ -0,0 +1,47 @@
+# design: <change-name>
+
+## 模块划分
+
+| 模块 | 职责 | 涉及文件 |
+|------|------|---------|
+| <模块名> | <一句话> | `<文件路径>` |
+
+## 关键接口定义
+
+### <接口名>
+
+```go
+// <函数签名>
+```
+
+- **输入**：<参数说明>
+- **输出**：<返回值说明>
+- **错误处理**：<错误类型及触发条件>
+
+### API 路由（如有）
+
+| 方法 | 路径 | 说明 | 请求/响应 |
+|------|------|------|----------|
+| POST | `/api/v1/xxx` | <说明> | 见 specs |
+
+## 数据流
+
+```
+<调用方> → <函数A> → <函数B> → <存储/外部依赖>
+```
+
+<补充说明：缓存策略、事务边界、并发控制等>
+
+## 关键决策与 ADR
+
+| 决策 | 选项 | 选定 | 理由 |
+|------|------|------|------|
+| <决策点> | A / B / C | <B> | <理由> |
+
+## 外部依赖
+
+- <依赖名称>：<用途>，<是否已存在>
+
+## 风险点
+
+- <风险描述>：<缓解措施>

package/templates/handoff.md

@@ -0,0 +1,64 @@
+# <change-name> 交接文档
+
+> 生成时间：<YYYY-MM-DD HH:MM>
+> 生成方式：/atd:handoff
+
+---
+
+## 做了什么
+
+**动机**：<为什么做这个 change，一句话>
+
+**结果**：<达成了什么，一句话>
+
+---
+
+## 关键决策
+
+| # | 决策 | 选了 | 排除了 | 原因 |
+|---|------|------|--------|------|
+| 1 | <决策主题> | <选定方案> | <排除方案> | <一句话原因> |
+| 2 | ... | ... | ... | ... |
+
+---
+
+## 受影响模块
+
+```
+<模块A>/
+  ├── <文件1>  — <改动简述>
+  ├── <文件2>  — <改动简述>
+<模块B>/
+  └── <文件3>  — <改动简述>
+```
+
+---
+
+## 测试状态
+
+| 覆盖范围 | 状态 | 说明 |
+|---------|------|------|
+| 单元测试 | ✅ / ⚠️ / ❌ | <补充说明> |
+| 集成测试 | ✅ / ⚠️ / ❌ | <补充说明> |
+| 回归测试 | ✅ / ⚠️ / ❌ | <补充说明> |
+
+---
+
+## 未解决问题
+
+- <问题1>：<当前状态，为什么没解决>
+- <问题2>：<当前状态，为什么没解决>
+
+---
+
+## 下一步
+
+<接手的人应该从哪里开始，做什么>
+
+---
+
+## 相关资源
+
+- ADR：`docs/adr/<序号>-<标题>.md`
+- Issue：<链接>
+- 监控面板：<链接>

package/templates/learn-skill.md

@@ -0,0 +1,43 @@
+# prompts/X-<name> · <short_desc>
+
+横向命令，任意时刻可触发：`/atd:<name> <args>`
+
+> 🧠 Auto-harvested by self-learning from session `<YYYY-MM-DD>`
+> 关联 change: `<change-name 或 "独立发现">`
+> 关联 error: `.errors-log.md` 条目 `<YYYY-MM-DD>`
+
+---
+
+## 失败模式
+
+**这个 skill 避免的诊断**：`<named failure pattern>`
+- 症状：`<现象>`
+- 如果不走这个路径会怎样：`<后果>`
+
+---
+
+## 执行步骤
+
+### 1. 确定输入
+
+### 2. 执行
+
+---
+
+## What didn't work
+
+| 尝试 | 排除原因 |
+|------|---------|
+| `<方案 A>` | `<为什么不 work>` |
+| `<方案 B>` | `<为什么不 work>` |
+
+---
+
+## 验证方式
+
+`<passing check — 什么命令/测试验证了这个路径>`
+
+验证输出：
+```
+<paste 关键输出行>
+```

package/templates/progress.json

@@ -0,0 +1,17 @@
+{
+  "change": "",
+  "mode": "direct",
+  "currentStep": "gate-check",
+  "completedTasks": [],
+  "failedAt": null,
+  "failedReason": null,
+  "startedAt": "",
+  "updatedAt": "",
+  "traceability": [],
+  "gateResults": {
+    "gate1": null,
+    "gate2": null,
+    "gate3": null,
+    "gate4": null
+  }
+}

package/templates/proposal.md

@@ -0,0 +1,29 @@
+# change: <name>
+
+## 背景与目标
+
+<对谁 / 做什么 / 达到什么效果，一句话>
+
+## 技术方案
+
+<选定方案名称及核心理由>
+
+## 排除的方案
+
+- <方案 A>：<排除原因>
+- <方案 B>：<排除原因>
+
+## 实施范围
+
+涉及模块：
+- `<模块路径>`：<职责说明>
+
+涉及文件：
+- `<文件路径>`
+
+接口变更：
+- <函数签名 / API 路由>
+
+## 参考文档
+
+- Brainstorming 设计文档：<路径或"无">

package/templates/solution.md

@@ -0,0 +1,36 @@
+---
+title: "<问题标题>"
+date: "<YYYY-MM-DD>"
+change: "<关联的 change 名称，无则省略>"
+branch: "<关联分支，无则省略>"
+tags: ["<标签1>", "<标签2>"]
+difficulty: "<easy|medium|hard>"
+module: "<涉及模块/目录>"
+---
+
+# <问题标题>
+
+## 问题
+
+<遇到了什么问题？症状、报错、异常行为。>
+
+## 根因
+
+<问题根因是什么？排除的调查路径也可以简述。>
+
+## 解决方案
+
+<最终采用的方案，核心代码/配置变更。>
+
+## 排除的方案
+
+- <方案 A>：<排除原因>
+- <方案 B>：<排除原因>
+
+## 教训
+
+<一句话总结，供未来参考。>
+
+## 可检索关键词
+
+<列出 3-5 个关键词，方便未来搜索匹配。例：redis timeout connection pool concurrent>

package/templates/strategy.md

@@ -0,0 +1,39 @@
+# Strategy — <产品名>
+
+> 上次更新：<日期>
+
+## Target Problem
+
+<这个产品解决什么问题？为谁解决？一句话。>
+
+## Approach
+
+<用什么方式解决？核心机制/差异化点是什么？>
+
+## Persona
+
+<目标用户画像：角色、场景、技术水平>
+
+## Key Metrics
+
+| 指标 | 当前值 | 目标 | 含义 |
+|------|--------|------|------|
+| <指标名> | <值> | <值> | <这个指标说明什么> |
+
+## Tracks
+
+> 当前正在推进的工作轨道（按优先级排列，每条 1-2 行）
+
+1. **<轨道名>**：<做什么、达到什么状态>
+2. **<轨道名>**：<做什么、达到什么状态>
+
+## Out of Scope
+
+<当前明确不做的事，避免 scope creep>
+
+---
+
+> **维护规则**：
+> - 策略是锚点，不是计划。Features 归 proposal，排期归 issue tracker。
+> - 每条控制在 1-2 行。新增章节的成本比看起来高，谨慎扩展。
+> - 可重复运行 `/atd strategy` 更新，只刷新 stale 部分。

package/templates/tasks.md

@@ -0,0 +1,41 @@
+# tasks: <change-name>
+
+## 任务清单
+
+### 1. <任务标题>
+
+**目标**: <完成后达到什么状态>
+**Files**: [path/to/file1.go, path/to/file2.go]
+**Dependencies**: none
+**估时**: 10 分钟
+
+实现步骤：
+1.
+2.
+
+验证方式：
+- [ ] `go test ./path/... -run TestXxx`
+
+---
+
+### 2. <任务标题>
+
+**目标**:
+**Files**: []
+**Dependencies**: Task 1
+**估时**: 15 分钟
+
+实现步骤：
+1.
+
+验证方式：
+- [ ]
+
+---
+
+## Verification Checklist
+
+<!-- 由 propose 阶段从 openspec/changes/<name>/specs/ 自动填充 -->
+
+- [ ] 系统 SHALL <需求描述> → Task N
+- [ ] 系统 MUST <需求描述> → Task N