agent-project-sdlc 0.1.0

package/assets/templates/RELEASE_TEMPLATE.md

@@ -0,0 +1,34 @@
+# Release Note And Rollback Plan（发布说明与回滚方案）
+
+## 1. Release Summary（发布摘要）
+
+- Version:
+- Milestone:
+- Date:
+- Owner:
+
+## 2. Included Changes（包含变更）
+
+- 
+
+## 3. Build Artifacts（构建产物）
+
+| 产物（Artifact） | 位置（Location） | Checksum/Version |
+|---|---|---|
+|  |  |  |
+
+## 4. Smoke Test Result（冒烟测试结果）
+
+- Decision: `PASS` / `BLOCKED`
+- Evidence:
+
+## 5. Deployment Checklist（部署检查清单）
+
+- [ ] 
+
+## 6. Rollback Plan（回滚方案）
+
+- 触发条件（Trigger）:
+- 步骤（Steps）:
+- 数据注意事项（Data considerations）:
+- 负责人（Owner）:

package/assets/templates/REVIEW_TEMPLATE.md

@@ -0,0 +1,31 @@
+# Review Report（评审报告）
+
+## 1. Review 范围
+
+- PRD:
+- 技术方案（Technical design）:
+- 实现文档（Implementation docs）:
+- Diff/commit:
+
+## 2. Findings（发现与风险）
+
+| 严重程度（Severity） | 文件/区域（File/Area） | 发现（Finding） | 建议（Recommendation） |
+|---|---|---|---|
+| P0/P1/P2 |  |  |  |
+
+## 3. 需求一致性
+
+- 
+
+## 4. 架构与可维护性
+
+- 
+
+## 5. Test Gaps（测试缺口）
+
+- 
+
+## 6. Gate Result（阶段结论）
+
+- Decision: `PASS` / `BLOCKED`
+- Required before testing:

package/assets/templates/RFC_TEMPLATE.md

@@ -0,0 +1,36 @@
+# RFC_001: [Change Title]
+
+## 1. 背景
+
+说明为什么需要这次变更。
+
+## 2. 变更内容（Change Content）
+
+- Added:
+- Changed:
+- Removed:
+- Unchanged:
+
+## 3. Product Impact（产品影响）
+
+| 受影响 PRD（Affected PRD） | 影响（Impact） |
+|---|---|
+|  |  |
+
+## 4. Technical Impact Candidates（技术影响候选）
+
+| 模块（Module） | 影响（Impact） | 置信度（Confidence） |
+|---|---|---|
+|  |  | low/medium/high |
+
+## 5. Acceptance Criteria
+
+- [ ] 
+
+## 6. Regression Requirements（回归要求）
+
+- [ ] 
+
+## 7. Status
+
+- Status: DRAFT

package/assets/templates/SKILL_TEMPLATE.md

@@ -0,0 +1,52 @@
+---
+name: example_skill
+description: Use when ...
+---
+
+# Example Skill
+
+## 目的
+
+用中文说明这个 Skill 的职责。保留 `name`、`description`、路径、命令、字段名和枚举的英文精确标识符。
+
+## 角色提示词
+
+用中文描述该角色在对话中的专业姿态、澄清方式、关键取舍和阶段产物生成责任。这里不是复述输入输出，而是说明 Agent 应如何和用户一起把模糊目标推进到可验证交付物。
+
+角色提示词应保持通用，不绑定具体业务项目；如果必须依赖项目事实，应要求读取 `.docs/`、`<harnessRoot>/state/**` 或当前 task contract，而不是写入固定业务假设。
+
+## 输入
+
+- `<harnessRoot>/state/lifecycle.yaml`
+- `<harnessRoot>/state/plan.yaml`
+- 其它阶段需要读取的事实源
+
+## 输出
+
+- 该 Skill 负责生成或更新的产物路径
+- 需要更新的状态文件或索引文件
+- 如有 `.docs/` slice 变化，刷新对应 `overview.md`
+
+## 语义切片
+
+- 说明该 Skill 负责的文档目录按什么语义边界切片。
+- 说明什么时候更新原 slice，什么时候新增、拆分、合并或废弃 slice。
+- 如果该 Skill 不直接生成文档，说明它如何调用下游 Skill 或报告边界变化。
+- 每次切片边界变化后，都要更新 `.docs/INDEX.md`。
+- `overview.md` 是 generated artifact，不手写；slice 变化后运行 `make docs-overview`。
+
+## 规则
+
+1. 中文解释规则，英文标识符保持原样，例如 `current_phase`、`active_skill`、`required_gates`。
+2. 命令保持原样，例如 `make validate-current`。
+3. 阶段和状态枚举保持原样，例如 `SPRINTING`、`done`、`pending_revision`。
+4. 如果该 Skill 执行 open task，说明 `plan.yaml` 中的 `allowed_paths` 和 `required_gates` 如何约束执行范围，并调用对应 gate。
+
+## 完成检查
+
+- [ ] 产物已写入约定路径。
+- [ ] 已判断语义切片边界。
+- [ ] 如当前 task 是 open task，`plan.yaml` 中的执行合同已完整。
+- [ ] 如有 `.docs/` slice 变化，已运行 `make docs-overview`。
+- [ ] 相关英文机器契约未被翻译。
+- [ ] 对应 gate 准备通过。

package/assets/templates/TECH_DESIGN_TEMPLATE.md

@@ -0,0 +1,54 @@
+# [Feature/Capability] Technical Design
+
+## 1. 关联产品需求
+
+- PRD:
+- Requirement IDs:
+
+## 2. 现有上下文
+
+- 当前模块（Current modules）:
+- 相关 APIs（Related APIs）:
+- 相关数据（Related data）:
+
+## 3. 方案架构
+
+- 领域边界（Domain boundary）:
+- 主要组件（Main components）:
+- 数据流（Data flow）:
+
+```txt
+Input
+-> Validation
+-> Core processing
+-> Persistence / side effects
+-> Output
+```
+
+## 4. 接口契约（Interface Contract）
+
+| 接口（Interface） | 方法/事件（Method/Event） | 请求（Request） | 响应（Response） | 错误（Errors） |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+## 5. 数据模型（Data Model）
+
+| 实体（Entity） | 字段（Fields） | 负责人（Owner） | 备注（Notes） |
+|---|---|---|---|
+|  |  |  |  |
+
+## 6. 任务拆分（Task Breakdown）
+
+| Task ID | 标题（Title） | Allowed Paths | Required Gates | Implementation Doc |
+|---|---|---|---|---|
+| DEV-001 |  | `src/**`, `tests/**` | `make lint`, `make test-current-domain` | `.docs/04_implementation/...` |
+
+## 7. 风险与缓解
+
+| 风险（Risk） | 等级（Level） | 缓解措施（Mitigation） |
+|---|---|---|
+|  | P1 |  |
+
+## 8. 需要关注的方案偏移
+
+- 

package/assets/templates/TEST_PLAN_TEMPLATE.md

@@ -0,0 +1,29 @@
+# Test Plan（测试计划）
+
+## 1. Scope（范围）
+
+- PRD:
+- Technical design:
+- Implementation docs:
+- Review report:
+
+## 2. Test Matrix（测试矩阵）
+
+| 需求（Requirement） | 场景（Scenario） | 测试类型（Test Type） | 测试用例（Test Case） | 结果（Result） |
+|---|---|---|---|---|
+|  |  | unit/integration/e2e/regression |  | pending |
+
+## 3. Regression Checklist（回归检查清单）
+
+- [ ] 
+
+## 4. Coverage Gaps（覆盖缺口）
+
+| 缺口（Gap） | 风险（Risk） | 后续动作（Follow-up） |
+|---|---|---|
+|  |  |  |
+
+## 5. Final Result（最终结论）
+
+- Decision: `PASS` / `BLOCKED`
+- Evidence:

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { commands } from "./commands/index.js";
+const [command = "help", ...args] = process.argv.slice(2);
+async function main() {
+    const handler = commands[command] ?? commands.help;
+    await handler(args);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`sdlc-harness: ${message}`);
+    process.exitCode = 1;
+});

package/dist/commands/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctor(): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,16 @@
+import { runDoctor } from "../lib/doctor.js";
+export async function doctor() {
+    const report = await runDoctor(process.cwd());
+    for (const line of report.info) {
+        console.log(line);
+    }
+    for (const warning of report.warnings) {
+        console.warn(`warning: ${warning}`);
+    }
+    for (const error of report.errors) {
+        console.error(`error: ${error}`);
+    }
+    if (report.errors.length > 0) {
+        process.exitCode = 1;
+    }
+}

package/dist/commands/index.d.ts

@@ -0,0 +1,3 @@
+export type CommandHandler = (args: string[]) => Promise<void> | void;
+export declare const commands: Record<string, CommandHandler>;
+export declare function help(): void;

package/dist/commands/index.js

@@ -0,0 +1,30 @@
+import { doctor } from "./doctor.js";
+import { init } from "./init.js";
+import { packageSource } from "./package-source.js";
+import { sync } from "./sync.js";
+import { upgrade } from "./upgrade.js";
+import { validate } from "./validate.js";
+export const commands = {
+    help,
+    init,
+    sync,
+    upgrade,
+    doctor,
+    validate,
+    "validate-harness": (args) => validate(["validate-harness", ...args]),
+    "validate-current": (args) => validate(["validate-current", ...args]),
+    "validate-pm": (args) => validate(["validate-pm", ...args]),
+    "validate-design": (args) => validate(["validate-design", ...args]),
+    "validate-dev": (args) => validate(["validate-dev", ...args]),
+    package: packageSource
+};
+export function help() {
+    console.log(`sdlc-harness commands:
+  init [--adopt] [--harness-folder <path>]
+                       Initialize a new project or adopt an existing one
+  sync                 Materialize canonical assets into the workspace
+  upgrade              Run migrations and then sync
+  doctor               Diagnose project configuration and drift
+  validate <gate>      Run a Harness validation gate
+  package <subcommand> Maintain package canonical source`);
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+export declare function init(args: string[]): Promise<void>;
+export declare function resolveInitHarnessRoot(projectRoot: string, args: string[]): Promise<string | undefined>;

package/dist/commands/init.js

@@ -0,0 +1,56 @@
+import { stdin as input, stdout as output } from "node:process";
+import * as readline from "node:readline/promises";
+import { runInit } from "../lib/init.js";
+import { normalizeHarnessFolderName, readHarnessRootConfig } from "../lib/harness-root.js";
+import { writePackageHarnessRoot } from "../lib/package-json-config.js";
+import { DEFAULT_HARNESS_ROOT } from "../lib/paths.js";
+export async function init(args) {
+    const adopt = args.includes("--adopt");
+    const force = args.includes("--force");
+    const projectRoot = process.cwd();
+    const configuredRoot = await resolveInitHarnessRoot(projectRoot, args);
+    if (configuredRoot) {
+        await writePackageHarnessRoot(projectRoot, configuredRoot);
+        console.log(`configured package.json sdlcHarness.harnessFolderName=${JSON.stringify(configuredRoot)}`);
+    }
+    const report = await runInit(projectRoot, { adopt, force });
+    for (const line of report) {
+        console.log(line);
+    }
+}
+export async function resolveInitHarnessRoot(projectRoot, args) {
+    const argRoot = valueForArg(args, "--harness-folder") ?? valueForArg(args, "--harnessFolderName");
+    if (argRoot) {
+        return normalizeHarnessFolderName(argRoot);
+    }
+    const current = await readHarnessRootConfig(projectRoot);
+    if (current.source !== "default") {
+        return undefined;
+    }
+    return promptHarnessRoot(DEFAULT_HARNESS_ROOT);
+}
+async function promptHarnessRoot(defaultRoot) {
+    if (!input.isTTY || !output.isTTY) {
+        return defaultRoot;
+    }
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(`Harness folder name (default ${defaultRoot}; press Enter to use default): `);
+        return normalizeHarnessFolderName(answer.trim() || defaultRoot);
+    }
+    finally {
+        rl.close();
+    }
+}
+function valueForArg(args, name) {
+    const prefix = `${name}=`;
+    const inline = args.find((arg) => arg.startsWith(prefix));
+    if (inline) {
+        return inline.slice(prefix.length);
+    }
+    const index = args.indexOf(name);
+    if (index >= 0) {
+        return args[index + 1];
+    }
+    return undefined;
+}

package/dist/commands/package-source.d.ts

@@ -0,0 +1 @@
+export declare function packageSource(args: string[]): Promise<void>;

package/dist/commands/package-source.js

@@ -0,0 +1,24 @@
+import { checkSource, syncSource } from "../lib/package-source.js";
+export async function packageSource(args) {
+    const subcommand = args[0] ?? "help";
+    if (subcommand === "sync-source") {
+        const report = await syncSource(process.cwd());
+        console.log(`package sync-source changed=${report.changed.length}`);
+        return;
+    }
+    if (subcommand === "check-source") {
+        const report = await checkSource(process.cwd());
+        if (report.drift.length > 0) {
+            for (const item of report.drift) {
+                console.error(`drift: ${item}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        console.log("package source OK");
+        return;
+    }
+    console.log(`sdlc-harness package commands:
+  sync-source    Update package canonical assets from this source workspace
+  check-source   Verify package canonical assets match this source workspace`);
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1 @@
+export declare function sync(): Promise<void>;

package/dist/commands/sync.js

@@ -0,0 +1,11 @@
+import { runSync } from "../lib/sync-engine.js";
+export async function sync() {
+    const report = await runSync(process.cwd());
+    console.log(`sync changed=${report.changed.length} skipped=${report.skipped.length} blocked=${report.blocked.length}`);
+    for (const blocked of report.blocked) {
+        console.error(`blocked: ${blocked}`);
+    }
+    if (report.blocked.length > 0) {
+        process.exitCode = 1;
+    }
+}

package/dist/commands/upgrade.d.ts

@@ -0,0 +1 @@
+export declare function upgrade(): Promise<void>;

package/dist/commands/upgrade.js

@@ -0,0 +1,7 @@
+import { runUpgrade } from "../lib/upgrade.js";
+export async function upgrade() {
+    const report = await runUpgrade(process.cwd());
+    for (const line of report) {
+        console.log(line);
+    }
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1 @@
+export declare function validate(args: string[]): Promise<void>;

package/dist/commands/validate.js

@@ -0,0 +1,14 @@
+import { runValidator } from "../lib/validators.js";
+export async function validate(args) {
+    const gate = args[0] ?? "validate-harness";
+    const report = await runValidator(process.cwd(), gate);
+    for (const line of report.info) {
+        console.log(line);
+    }
+    for (const error of report.errors) {
+        console.error(`error: ${error}`);
+    }
+    if (report.errors.length > 0) {
+        process.exitCode = 1;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { commands } from "./commands/index.js";
+export type { HarnessConfig, ManagedFile, SourceMapping } from "./lib/types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { commands } from "./commands/index.js";

package/dist/lib/config.d.ts

@@ -0,0 +1,5 @@
+import type { HarnessConfig } from "./types.js";
+export declare function defaultConfig(root: string): HarnessConfig;
+export declare function readConfig(projectRoot: string): Promise<HarnessConfig>;
+export declare function writeConfigIfMissing(projectRoot: string): Promise<boolean>;
+export declare function normalizeConfig(value: Partial<HarnessConfig>, root?: string): HarnessConfig;

package/dist/lib/config.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
+import { pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { parseYaml, stringifyYaml } from "./yaml.js";
+export function defaultConfig(root) {
+    return {
+        core: {
+            package: "agent-project-sdlc",
+            version: "0.1.0",
+            schema_version: "1"
+        },
+        managed_files: [
+            { path: "AGENTS.md", strategy: "merge-block" },
+            { path: "Makefile", strategy: "merge-block" },
+            { path: harnessPath(root, "skills"), strategy: "managed" },
+            { path: harnessPath(root, "managed", "templates"), strategy: "managed" },
+            { path: harnessPath(root, "managed", "policies"), strategy: "merge-with-local" },
+            { path: harnessPath(root, "managed", "make", "sdlc-harness.mk"), strategy: "managed" },
+            { path: ".github/workflows/harness.yml", strategy: "create-if-missing" }
+        ],
+        local_overrides: [harnessPath(root, "overrides/**"), harnessPath(root, "managed", "policies", "*.local.yaml")],
+        never_overwrite: [".docs/**", harnessPath(root, "state/**"), "src/**", "tests/**"]
+    };
+}
+export async function readConfig(projectRoot) {
+    const root = await harnessRoot(projectRoot);
+    const configPath = path.join(projectRoot, await harnessConfigPath(projectRoot));
+    if (!(await pathExists(configPath))) {
+        return defaultConfig(root);
+    }
+    const parsed = parseYaml(await readText(configPath));
+    return normalizeConfig(parsed, root);
+}
+export async function writeConfigIfMissing(projectRoot) {
+    const root = await harnessRoot(projectRoot);
+    const configPath = path.join(projectRoot, await harnessConfigPath(projectRoot));
+    if (await pathExists(configPath)) {
+        return false;
+    }
+    await writeTextIfChanged(configPath, stringifyYaml(defaultConfig(root)));
+    return true;
+}
+export function normalizeConfig(value, root = ".agent") {
+    const fallback = defaultConfig(root);
+    return {
+        core: {
+            package: value.core?.package ?? fallback.core.package,
+            version: value.core?.version ?? fallback.core.version,
+            schema_version: value.core?.schema_version ?? fallback.core.schema_version
+        },
+        managed_files: value.managed_files ?? fallback.managed_files,
+        local_overrides: value.local_overrides ?? fallback.local_overrides,
+        never_overwrite: value.never_overwrite ?? fallback.never_overwrite
+    };
+}

package/dist/lib/doctor.d.ts

@@ -0,0 +1,6 @@
+export interface DoctorReport {
+    info: string[];
+    warnings: string[];
+    errors: string[];
+}
+export declare function runDoctor(projectRoot: string): Promise<DoctorReport>;

package/dist/lib/doctor.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { readConfig } from "./config.js";
+import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
+import { pathExists } from "./fs.js";
+export async function runDoctor(projectRoot) {
+    const report = { info: [], warnings: [], errors: [] };
+    const root = await harnessRoot(projectRoot);
+    const relativeConfigPath = await harnessConfigPath(projectRoot);
+    const configPath = path.join(projectRoot, relativeConfigPath);
+    if (!(await pathExists(configPath))) {
+        report.errors.push(`missing ${relativeConfigPath}`);
+        return report;
+    }
+    const config = await readConfig(projectRoot);
+    report.info.push(`harness root: ${root}`);
+    report.info.push(`core package: ${config.core.package}@${config.core.version}`);
+    report.info.push(`schema version: ${config.core.schema_version}`);
+    for (const required of [harnessPath(root, "state", "lifecycle.yaml"), harnessPath(root, "state", "plan.yaml"), ".docs/INDEX.md"]) {
+        if (!(await pathExists(path.join(projectRoot, required)))) {
+            report.errors.push(`missing ${required}`);
+        }
+    }
+    for (const managed of config.managed_files) {
+        const exists = await pathExists(path.join(projectRoot, managed.path));
+        if (!exists && managed.strategy !== "create-if-missing") {
+            report.warnings.push(`managed path missing: ${managed.path}`);
+        }
+    }
+    report.info.push("doctor complete");
+    return report;
+}

package/dist/lib/fs.d.ts

@@ -0,0 +1,8 @@
+export declare function pathExists(target: string): Promise<boolean>;
+export declare function readText(target: string): Promise<string>;
+export declare function ensureDir(target: string): Promise<void>;
+export declare function writeTextIfChanged(target: string, content: string): Promise<boolean>;
+export declare function listFiles(root: string): Promise<string[]>;
+export declare function copyTree(sourceRoot: string, destinationRoot: string, options?: {
+    skipGitkeep?: boolean;
+}): Promise<string[]>;

package/dist/lib/fs.js

@@ -0,0 +1,56 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export async function pathExists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readText(target) {
+    return fs.readFile(target, "utf8");
+}
+export async function ensureDir(target) {
+    await fs.mkdir(target, { recursive: true });
+}
+export async function writeTextIfChanged(target, content) {
+    if ((await pathExists(target)) && (await readText(target)) === content) {
+        return false;
+    }
+    await ensureDir(path.dirname(target));
+    await fs.writeFile(target, content, "utf8");
+    return true;
+}
+export async function listFiles(root) {
+    if (!(await pathExists(root))) {
+        return [];
+    }
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listFiles(fullPath)));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+export async function copyTree(sourceRoot, destinationRoot, options = {}) {
+    const changed = [];
+    for (const source of await listFiles(sourceRoot)) {
+        if (options.skipGitkeep && path.basename(source) === ".gitkeep") {
+            continue;
+        }
+        const relative = path.relative(sourceRoot, source);
+        const destination = path.join(destinationRoot, relative);
+        if (await writeTextIfChanged(destination, await readText(source))) {
+            changed.push(destination);
+        }
+    }
+    return changed;
+}

package/dist/lib/harness-root.d.ts

@@ -0,0 +1,9 @@
+export interface HarnessRootConfig {
+    harnessFolderName: string;
+    source: string;
+}
+export declare function readHarnessRootConfig(projectRoot: string): Promise<HarnessRootConfig>;
+export declare function harnessRoot(projectRoot: string): Promise<string>;
+export declare function harnessConfigPath(projectRoot: string): Promise<string>;
+export declare function harnessPath(root: string, ...segments: string[]): string;
+export declare function normalizeHarnessFolderName(value: string): string;