agent-project-sdlc 0.1.0

package/dist/lib/sync-engine.js

@@ -0,0 +1,202 @@
+import path from "node:path";
+import { readConfig } from "./config.js";
+import { harnessRoot } from "./harness-root.js";
+import { copyTree, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { MAKEFILE_BLOCK_END, MAKEFILE_BLOCK_START, MANAGED_BLOCK_END, MANAGED_BLOCK_START } from "./managed-file.js";
+import { packageAssetPath } from "./paths.js";
+export function emptySyncReport() {
+    return {
+        changed: [],
+        skipped: [],
+        blocked: []
+    };
+}
+export async function runSync(projectRoot) {
+    const root = await harnessRoot(projectRoot);
+    const config = await readConfig(projectRoot);
+    const report = emptySyncReport();
+    for (const managedFile of config.managed_files) {
+        await syncManagedFile(projectRoot, root, managedFile, report);
+    }
+    return report;
+}
+async function syncManagedFile(projectRoot, root, managedFile, report) {
+    const destination = path.join(projectRoot, managedFile.path);
+    if (managedFile.path === "AGENTS.md") {
+        await syncAgentsBlock(destination, root, report);
+        return;
+    }
+    if (managedFile.path === "Makefile") {
+        await syncMakefileInclude(destination, root, report);
+        return;
+    }
+    if (managedFile.path === path.join(root, "skills") || managedFile.path === ".harness/agents/skills") {
+        await syncTree(packageAssetPath("skills"), destination, report);
+        return;
+    }
+    if (managedFile.path === ".agents/skills" && root !== ".agents") {
+        await syncTree(packageAssetPath("skills"), destination, report);
+        return;
+    }
+    if (managedFile.path === path.join(root, "managed", "templates") || managedFile.path === ".harness/templates") {
+        await syncTree(packageAssetPath("templates"), destination, report);
+        return;
+    }
+    if (managedFile.path === path.join(root, "managed", "policies") || managedFile.path === ".harness/policies") {
+        await syncTree(packageAssetPath("policies"), destination, report);
+        return;
+    }
+    if (managedFile.path === path.join(root, "managed", "make", "sdlc-harness.mk") ||
+        managedFile.path === ".harness/make/sdlc-harness.mk") {
+        await syncFile(packageAssetPath("make", "sdlc-harness.mk"), destination, report, "skip-if-missing");
+        return;
+    }
+    if (managedFile.path === ".github/workflows/harness.yml") {
+        if (await pathExists(destination)) {
+            report.skipped.push(managedFile.path);
+            return;
+        }
+        await syncFile(packageAssetPath("github", "harness.yml"), destination, report, "skip-if-missing");
+        return;
+    }
+    report.skipped.push(managedFile.path);
+}
+async function syncAgentsBlock(destination, root, report) {
+    const corePath = packageAssetPath("agents", "AGENTS_CORE.md");
+    if (!(await pathExists(corePath))) {
+        report.skipped.push("AGENTS.md");
+        return;
+    }
+    const core = renderAgentsCore(await readText(corePath), root);
+    const block = `${MANAGED_BLOCK_START}\n${core.trim()}\n${MANAGED_BLOCK_END}`;
+    const existing = (await pathExists(destination)) ? await readText(destination) : "";
+    const next = mergeManagedBlock({
+        existing,
+        block,
+        start: MANAGED_BLOCK_START,
+        end: MANAGED_BLOCK_END,
+        pathLabel: "AGENTS.md",
+        insert: "append",
+        report
+    });
+    if (!next) {
+        return;
+    }
+    if (await writeTextIfChanged(destination, next)) {
+        report.changed.push("AGENTS.md");
+    }
+    else {
+        report.skipped.push("AGENTS.md");
+    }
+}
+function renderAgentsCore(content, root) {
+    return content.replaceAll(".agent", root);
+}
+async function syncMakefileInclude(destination, root, report) {
+    const existing = (await pathExists(destination)) ? await readText(destination) : "";
+    const resetDefaultGoal = shouldResetMakeDefaultGoal(existing);
+    const includePath = `${root.replace(/\\/g, "/")}/managed/make/sdlc-harness.mk`;
+    const blockLines = [
+        MAKEFILE_BLOCK_START,
+        "# Included before project targets so project recipes win on name conflicts.",
+        `-include ${includePath}`,
+        MAKEFILE_BLOCK_END
+    ];
+    if (resetDefaultGoal) {
+        blockLines.splice(3, 0, ".DEFAULT_GOAL :=");
+    }
+    const block = blockLines.join("\n");
+    const next = mergeManagedBlock({
+        existing,
+        block,
+        start: MAKEFILE_BLOCK_START,
+        end: MAKEFILE_BLOCK_END,
+        pathLabel: "Makefile",
+        insert: "prepend",
+        report
+    });
+    if (!next) {
+        return;
+    }
+    if (await writeTextIfChanged(destination, next)) {
+        report.changed.push("Makefile");
+    }
+    else {
+        report.skipped.push("Makefile");
+    }
+}
+function shouldResetMakeDefaultGoal(existing) {
+    if (!existing.trim()) {
+        return false;
+    }
+    const startIndex = existing.indexOf(MAKEFILE_BLOCK_START);
+    const endIndex = existing.indexOf(MAKEFILE_BLOCK_END);
+    if (startIndex < 0 && endIndex < 0) {
+        return true;
+    }
+    if (startIndex < 0 || endIndex < startIndex) {
+        return false;
+    }
+    const before = existing.slice(0, startIndex);
+    const after = existing.slice(endIndex + MAKEFILE_BLOCK_END.length);
+    return !before.trim() && Boolean(after.trim());
+}
+function mergeManagedBlock(options) {
+    const { existing, block, start, end, pathLabel, insert, report } = options;
+    const startIndex = existing.indexOf(start);
+    const endIndex = existing.indexOf(end);
+    const hasStart = startIndex >= 0;
+    const hasEnd = endIndex >= 0;
+    if (hasStart !== hasEnd || (hasStart && endIndex < startIndex)) {
+        report.blocked.push(`${pathLabel}: incomplete managed block markers`);
+        return undefined;
+    }
+    if (hasStart &&
+        (existing.indexOf(start, startIndex + start.length) >= 0 || existing.indexOf(end, endIndex + end.length) >= 0)) {
+        report.blocked.push(`${pathLabel}: duplicate managed block markers`);
+        return undefined;
+    }
+    if (hasStart) {
+        const before = existing.slice(0, startIndex);
+        const after = existing.slice(endIndex + end.length);
+        return `${before}${block}${after}`;
+    }
+    if (!existing.trim()) {
+        return `${block}\n`;
+    }
+    if (insert === "prepend") {
+        return `${block}\n\n${existing}`;
+    }
+    return `${existing.trimEnd()}\n\n${block}\n`;
+}
+async function syncTree(source, destination, report) {
+    if (!(await pathExists(source))) {
+        report.skipped.push(path.basename(destination));
+        return;
+    }
+    const files = await listFiles(source);
+    const realFiles = files.filter((file) => !file.endsWith(".gitkeep"));
+    if (realFiles.length === 0) {
+        report.skipped.push(path.basename(destination));
+        return;
+    }
+    const changed = await copyTree(source, destination, { skipGitkeep: true });
+    report.changed.push(...changed);
+}
+async function syncFile(source, destination, report, missingMode) {
+    if (!(await pathExists(source))) {
+        if (missingMode === "block-if-missing") {
+            report.blocked.push(source);
+        }
+        else {
+            report.skipped.push(destination);
+        }
+        return;
+    }
+    if (await writeTextIfChanged(destination, await readText(source))) {
+        report.changed.push(destination);
+    }
+    else {
+        report.skipped.push(destination);
+    }
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,22 @@
+export interface HarnessConfig {
+    core: {
+        package: string;
+        version: string;
+        schema_version: string;
+    };
+    managed_files: ManagedFile[];
+    local_overrides: string[];
+    never_overwrite: string[];
+}
+export interface ManagedFile {
+    path: string;
+    strategy: "merge-block" | "generated" | "generated-compat" | "managed" | "merge-with-local" | "create-if-missing";
+}
+export interface SourceMapping {
+    source: string;
+    target: string;
+    mode: "extract-managed-block" | "copy-tree" | "copy-file" | "extract-harness-targets";
+}
+export interface SourceMappingsFile {
+    source_mappings: SourceMapping[];
+}

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/upgrade.d.ts

@@ -0,0 +1 @@
+export declare function runUpgrade(projectRoot: string): Promise<string[]>;

package/dist/lib/upgrade.js

@@ -0,0 +1,16 @@
+import { runDoctor } from "./doctor.js";
+import { runMigrations } from "./migrations.js";
+import { runSync } from "./sync-engine.js";
+export async function runUpgrade(projectRoot) {
+    const lines = [];
+    const migrationReport = await runMigrations(projectRoot);
+    lines.push(`migrations changed=${migrationReport.changed.length} skipped=${migrationReport.skipped.length}`);
+    const syncReport = await runSync(projectRoot);
+    lines.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
+    const doctor = await runDoctor(projectRoot);
+    lines.push(`doctor warnings=${doctor.warnings.length} errors=${doctor.errors.length}`);
+    if (syncReport.blocked.length > 0 || doctor.errors.length > 0) {
+        throw new Error("upgrade completed with blockers");
+    }
+    return lines;
+}

package/dist/lib/validators.d.ts

@@ -0,0 +1,6 @@
+export interface ValidatorReport {
+    info: string[];
+    errors: string[];
+}
+export declare function runValidator(projectRoot: string, gate: string): Promise<ValidatorReport>;
+export declare function changedFiles(projectRoot: string): Promise<string[]>;

package/dist/lib/validators.js

@@ -0,0 +1,158 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { harnessPath, harnessRoot } from "./harness-root.js";
+import { listFiles, pathExists, readText } from "./fs.js";
+import { parseYaml } from "./yaml.js";
+const execFileAsync = promisify(execFile);
+const validators = {
+    "validate-harness": validateHarness,
+    "validate-current": validateCurrent,
+    "validate-pm": validatePm,
+    "validate-design": validateDesign,
+    "validate-dev": validateDev
+};
+export async function runValidator(projectRoot, gate) {
+    const normalized = normalizeGate(gate);
+    const validator = validators[normalized];
+    if (!validator) {
+        return { info: [], errors: [`unknown validator: ${gate}`] };
+    }
+    return validator(projectRoot);
+}
+function normalizeGate(gate) {
+    return gate.replace(/^make\s+/, "").trim();
+}
+async function validateHarness(projectRoot) {
+    const errors = [];
+    const root = await harnessRoot(projectRoot);
+    for (const required of [
+        "AGENTS.md",
+        ".docs/INDEX.md",
+        harnessPath(root, "config.yaml"),
+        harnessPath(root, "state", "lifecycle.yaml"),
+        harnessPath(root, "state", "plan.yaml"),
+        harnessPath(root, "skills"),
+        harnessPath(root, "managed", "templates"),
+        harnessPath(root, "managed", "policies")
+    ]) {
+        if (!(await pathExists(path.join(projectRoot, required)))) {
+            errors.push(`missing ${required}`);
+        }
+    }
+    return { info: [`validate-harness checked ${projectRoot} (${root})`], errors };
+}
+async function validateCurrent(projectRoot) {
+    const root = await harnessRoot(projectRoot);
+    const lifecycle = await readYamlObject(path.join(projectRoot, root, "state", "lifecycle.yaml"));
+    const current = String(lifecycle.current_phase ?? "");
+    const gateByPhase = {
+        REQUIREMENT_GATHERING: "validate-pm",
+        ARCHITECTING: "validate-design",
+        SPRINTING: "validate-dev"
+    };
+    return runValidator(projectRoot, gateByPhase[current] ?? "validate-harness");
+}
+async function validatePm(projectRoot) {
+    const docs = await markdownFiles(path.join(projectRoot, ".docs/01_product"));
+    const text = await combinedText(docs);
+    const errors = [];
+    if (docs.length === 0)
+        errors.push("No PRD deliverables found");
+    if (!containsAny(text, ["acceptance", "验收"]))
+        errors.push("PRD must include acceptance criteria");
+    if (!containsAny(text, ["out of scope", "不做", "边界"]))
+        errors.push("PRD must include out-of-scope boundaries");
+    if (!containsAny(text, ["open questions", "未决", "待确认"]))
+        errors.push("PRD must include open questions");
+    return { info: [`validate-pm checked ${docs.length} file(s)`], errors };
+}
+async function validateDesign(projectRoot) {
+    const architecture = await markdownFiles(path.join(projectRoot, ".docs/02_architecture"));
+    const techPlan = await markdownFiles(path.join(projectRoot, ".docs/03_tech_plan"));
+    const text = await combinedText([...architecture, ...techPlan]);
+    const errors = [];
+    if (architecture.length === 0)
+        errors.push("No architecture deliverables found");
+    if (techPlan.length === 0)
+        errors.push("No technical plan deliverables found");
+    if (!containsAny(text, ["prd", "requirement", "需求"]))
+        errors.push("Design must cite product requirements");
+    if (!containsAny(text, ["api", "interface", "接口", "contract", "契约"]))
+        errors.push("Design must describe interfaces or contracts");
+    if (!containsAny(text, ["task", "任务", "breakdown"]))
+        errors.push("Design must include task breakdown");
+    return { info: [`validate-design checked ${architecture.length + techPlan.length} file(s)`], errors };
+}
+async function validateDev(projectRoot) {
+    const errors = [];
+    const root = await harnessRoot(projectRoot);
+    const tasksData = await readYamlObject(path.join(projectRoot, root, "state", "plan.yaml"));
+    const tasks = Array.isArray(tasksData.tasks) ? tasksData.tasks : [];
+    if (tasks.length === 0)
+        errors.push("plan.yaml must contain at least one task");
+    const open = tasks.filter((task) => ["pending", "in_progress", "blocked", "pending_revision"].includes(String(task.status)));
+    if (open.length > 0)
+        errors.push(`Open tasks remain: ${open.map((task) => task.id).join(", ")}`);
+    for (const task of tasks) {
+        for (const field of ["id", "title", "status", "summary", "implementation_doc"]) {
+            if (!task[field])
+                errors.push(`Task missing ${field}: ${String(task.id ?? "unknown")}`);
+        }
+        if (["pending", "in_progress", "blocked", "pending_revision"].includes(String(task.status))) {
+            for (const field of ["docs", "allowed_paths", "required_gates", "acceptance_criteria"]) {
+                if (!task[field])
+                    errors.push(`Open task ${task.id} missing ${field}`);
+            }
+            if (!Array.isArray(task.allowed_paths) || task.allowed_paths.length === 0) {
+                errors.push(`Open task ${task.id} must define allowed_paths`);
+            }
+            if (!Array.isArray(task.required_gates) || task.required_gates.length === 0) {
+                errors.push(`Open task ${task.id} must define required_gates`);
+            }
+        }
+        else {
+            for (const field of ["docs", "allowed_paths", "required_gates", "acceptance_criteria", "working_notes"]) {
+                if (task[field])
+                    errors.push(`Closed task ${task.id} must not retain ${field}`);
+            }
+        }
+    }
+    for (const task of tasks.filter((task) => task.status === "done")) {
+        if (task.gate_result !== "PASS")
+            errors.push(`Done task ${task.id} must have gate_result PASS`);
+        const implementationDoc = String(task.implementation_doc ?? "");
+        if (implementationDoc && !(await pathExists(path.join(projectRoot, implementationDoc)))) {
+            errors.push(`Implementation doc missing for ${task.id}: ${implementationDoc}`);
+        }
+    }
+    return { info: [`validate-dev checked ${tasks.length} task(s)`], errors };
+}
+async function readYamlObject(filePath) {
+    if (!(await pathExists(filePath)))
+        return {};
+    return (parseYaml(await readText(filePath)) ?? {});
+}
+async function markdownFiles(root) {
+    const files = await listFiles(root);
+    return files.filter((file) => file.endsWith(".md") && !file.endsWith("overview.md"));
+}
+async function combinedText(files) {
+    const parts = await Promise.all(files.map((file) => readText(file)));
+    return parts.join("\n").toLowerCase();
+}
+function containsAny(text, needles) {
+    return needles.some((needle) => text.includes(needle.toLowerCase()));
+}
+export async function changedFiles(projectRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["status", "--porcelain"], { cwd: projectRoot });
+        return stdout
+            .split("\n")
+            .map((line) => line.slice(3).trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/yaml.d.ts

@@ -0,0 +1,2 @@
+export declare function parseYaml(content: string): unknown;
+export declare function stringifyYaml(value: unknown): string;

package/dist/lib/yaml.js

@@ -0,0 +1,7 @@
+import YAML from "yaml";
+export function parseYaml(content) {
+    return YAML.parse(content);
+}
+export function stringifyYaml(value) {
+    return `${YAML.stringify(value, { lineWidth: 0 })}`;
+}

package/migrations/README.md

@@ -0,0 +1,3 @@
+# Migrations
+
+Schema migrations for `.harness/config.yaml` and managed file layout belong here.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "agent-project-sdlc",
+  "version": "0.1.0",
+  "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
+  "type": "module",
+  "bin": {
+    "sdlc-harness": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "migrations",
+    "source-mappings.yaml"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test ../../tests/sdlc-harness/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.5.0"
+  }
+}

package/source-mappings.yaml

@@ -0,0 +1,19 @@
+source_mappings:
+  - source: "AGENTS.md"
+    target: "packages/sdlc-harness/assets/agents/AGENTS_CORE.md"
+    mode: "extract-managed-block"
+  - source: ".agent/skills"
+    target: "packages/sdlc-harness/assets/skills"
+    mode: "copy-tree"
+  - source: ".agent/managed/templates"
+    target: "packages/sdlc-harness/assets/templates"
+    mode: "copy-tree"
+  - source: ".agent/managed/policies"
+    target: "packages/sdlc-harness/assets/policies"
+    mode: "copy-tree"
+  - source: "Makefile"
+    target: "packages/sdlc-harness/assets/make/sdlc-harness.mk"
+    mode: "extract-harness-targets"
+  - source: ".github/workflows/harness.yml"
+    target: "packages/sdlc-harness/assets/github/harness.yml"
+    mode: "copy-file"