omegon 0.6.0

package/extensions/openspec/lifecycle-emitter.ts

@@ -0,0 +1,65 @@
+import type { ChangeInfo } from "./types.ts";
+import type { LifecycleMemoryCandidate } from "../project-memory/types.ts";
+
+export function emitArchiveCandidates(change: ChangeInfo): LifecycleMemoryCandidate[] {
+  if (change.stage !== "archived") return [];
+
+  const candidates: LifecycleMemoryCandidate[] = [];
+  for (const spec of change.specs) {
+    for (const section of spec.sections) {
+      if (section.type === "removed") continue;
+      for (const requirement of section.requirements) {
+        candidates.push({
+          sourceKind: "openspec-archive",
+          authority: "explicit",
+          section: "Specs",
+          content: `${requirement.title} (${section.type})`,
+          artifactRef: {
+            type: "openspec-baseline",
+            path: `openspec/baseline/${spec.domain}.md`,
+            subRef: requirement.title,
+          },
+        });
+      }
+    }
+  }
+  return candidates;
+}
+
+export function emitReconcileCandidates(changeName: string, summary?: string, constraints?: string[]): LifecycleMemoryCandidate[] {
+  const candidates: LifecycleMemoryCandidate[] = [];
+
+  for (const constraint of constraints ?? []) {
+    const trimmed = constraint.trim();
+    if (!trimmed || /\b(might|could|should|consider|possible|likely)\b/i.test(trimmed) || /\?$/.test(trimmed)) {
+      continue;
+    }
+    candidates.push({
+      sourceKind: "openspec-assess",
+      authority: "explicit",
+      section: "Constraints",
+      content: trimmed,
+      artifactRef: {
+        type: "openspec-spec",
+        path: `openspec/changes/${changeName}/tasks.md`,
+        subRef: "reconcile_after_assess",
+      },
+    });
+  }
+
+  if (summary && /\b(fixed|resolved|workaround)\b/i.test(summary)) {
+    candidates.push({
+      sourceKind: "openspec-assess",
+      authority: "explicit",
+      section: "Known Issues",
+      content: summary.trim(),
+      artifactRef: {
+        type: "openspec-spec",
+        path: `openspec/changes/${changeName}/tasks.md`,
+        subRef: "reconcile_after_assess",
+      },
+    });
+  }
+
+  return candidates;
+}

package/extensions/openspec/lifecycle-files.ts

@@ -0,0 +1,70 @@
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const DURABLE_ROOTS = ["docs", "openspec"] as const;
+
+export interface LifecycleArtifactCheckResult {
+	untracked: string[];
+}
+
+export function isDurableLifecycleArtifact(filePath: string): boolean {
+	const normalized = filePath.replaceAll("\\", "/").replace(/^\.\//, "");
+	return DURABLE_ROOTS.some((root) => normalized === root || normalized.startsWith(`${root}/`));
+}
+
+export function parsePorcelainZ(stdout: string): string[] {
+	const entries = stdout.split("\0").filter(Boolean);
+	const untracked: string[] = [];
+	for (const entry of entries) {
+		if (entry.startsWith("?? ")) {
+			untracked.push(entry.slice(3));
+		}
+	}
+	return untracked;
+}
+
+export function detectUntrackedLifecycleArtifacts(repoPath: string): string[] {
+	try {
+		const stdout = execFileSync(
+			"git",
+			["status", "--porcelain", "--untracked-files=all", "-z", "--", ...DURABLE_ROOTS],
+			{ cwd: repoPath, encoding: "utf-8" },
+		);
+		return parsePorcelainZ(stdout)
+			.filter(isDurableLifecycleArtifact)
+			.sort((a, b) => a.localeCompare(b));
+	} catch {
+		return [];
+	}
+}
+
+export function formatLifecycleArtifactError(result: LifecycleArtifactCheckResult): string {
+	const lines = [
+		"Untracked durable lifecycle artifacts detected.",
+		"",
+		"The following files live under docs/ or openspec/ and are treated as version-controlled project documentation:",
+		...result.untracked.map((file) => `- ${file}`),
+		"",
+		"Resolution:",
+		"- git add the durable lifecycle files listed above, or",
+		"- move transient scratch artifacts outside docs/ and openspec/.",
+	];
+	return lines.join("\n");
+}
+
+export function assertTrackedLifecycleArtifacts(repoPath: string): void {
+	const untracked = detectUntrackedLifecycleArtifacts(repoPath);
+	if (untracked.length === 0) return;
+	throw new Error(formatLifecycleArtifactError({ untracked }));
+}
+
+function runCli(): void {
+	const repoPath = process.cwd();
+	assertTrackedLifecycleArtifacts(repoPath);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+	runCli();
+}

package/extensions/openspec/lifecycle.ts

@@ -0,0 +1,50 @@
+/**
+ * openspec/lifecycle — Canonical lifecycle resolver for OpenSpec surfaces.
+ *
+ * Exports buildLifecycleSummary, the single shared function that both the
+ * status and get surfaces in index.ts call to derive stage, verificationSubstate,
+ * and archiveReady.  Extracting it here makes it importable by tests so that
+ * cross-surface agreement can be asserted against the actual production logic.
+ *
+ * No pi dependency — can be tested standalone.
+ */
+
+import type { ChangeInfo } from "./types.ts";
+import {
+	getAssessmentStatus,
+	resolveLifecycleSummary,
+	type LifecycleSummary,
+} from "./spec.ts";
+import { evaluateLifecycleReconciliation } from "./reconcile.ts";
+
+export type { LifecycleSummary };
+
+/**
+ * Derive the canonical lifecycle summary for a change.
+ *
+ * This is the single source of truth consumed by:
+ *   - the `status` action (list view)
+ *   - the `get` action (detail view)
+ *   - the `archive` gate
+ *   - dashboard-state publication
+ *
+ * All surfaces must call this function rather than re-deriving lifecycle
+ * state locally so that they cannot diverge.
+ */
+export function buildLifecycleSummary(repoPath: string, change: ChangeInfo): LifecycleSummary {
+	const assessment = getAssessmentStatus(repoPath, change.name);
+	const reconciliation = evaluateLifecycleReconciliation(repoPath, change.name);
+	const blockingIssues = reconciliation.issues.filter((issue) => issue.isError !== false);
+	const archiveBlockedReason = blockingIssues.length > 0
+		? blockingIssues.map((issue) => issue.suggestedAction).join(" ")
+		: null;
+	return resolveLifecycleSummary({
+		change,
+		record: assessment.record,
+		freshness: assessment.freshness,
+		archiveBlocked: blockingIssues.length > 0,
+		archiveBlockedReason,
+		archiveBlockedIssueCodes: blockingIssues.map((issue) => issue.code),
+		boundNodeIds: reconciliation.boundNodeIds,
+	});
+}

package/extensions/openspec/reconcile.ts

@@ -0,0 +1,187 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import {
+	getNodeSections,
+	writeNodeDocument,
+} from "../design-tree/tree.ts";
+import type { DesignNode, FileScope } from "../design-tree/types.ts";
+import { resolveBoundDesignNodes } from "./archive-gate.ts";
+import { getChange } from "./spec.ts";
+
+export type ReconciliationIssueCode = "incomplete_tasks" | "missing_design_binding";
+export type PostAssessOutcome = "pass" | "reopen" | "ambiguous";
+export type AssessmentKind = "spec" | "cleave";
+
+export interface ReconciliationIssue {
+	code: ReconciliationIssueCode;
+	message: string;
+	suggestedAction: string;
+	isError?: boolean;
+	severity?: "error" | "warning" | "info";
+}
+
+export interface LifecycleReconciliationStatus {
+	changeName: string;
+	boundNodeIds: string[];
+	issues: ReconciliationIssue[];
+}
+
+export interface PostAssessReconciliationInput {
+	assessmentKind: AssessmentKind;
+	outcome: PostAssessOutcome;
+	summary?: string;
+	changedFiles?: string[];
+	constraints?: string[];
+}
+
+export interface PostAssessReconciliationResult {
+	changeName: string;
+	outcome: PostAssessOutcome;
+	reopened: boolean;
+	warning?: string;
+	updatedTaskState: boolean;
+	updatedNodeIds: string[];
+	appendedFileScope: string[];
+	appendedConstraints: string[];
+}
+
+function findBoundNodes(cwd: string, changeName: string): DesignNode[] {
+	return resolveBoundDesignNodes(cwd, changeName);
+}
+
+export function evaluateLifecycleReconciliation(cwd: string, changeName: string): LifecycleReconciliationStatus {
+	const issues: ReconciliationIssue[] = [];
+	const change = getChange(cwd, changeName);
+	const boundNodes = findBoundNodes(cwd, changeName);
+
+	if (boundNodes.length === 0) {
+		issues.push({
+			code: "missing_design_binding",
+			message: `OpenSpec change '${changeName}' is not bound to any design-tree node via openspec_change or matching node ID. (Legacy node — binding is guaranteed by construction for new nodes created via design_tree_update implement.)`,
+			suggestedAction: "Bind the change to a decided/implementing design node before archive so lifecycle tracking stays traceable.",
+			isError: false,
+			severity: "info",
+		});
+	}
+
+	if (change && change.hasTasks && change.totalTasks > 0 && change.doneTasks < change.totalTasks) {
+		issues.push({
+			code: "incomplete_tasks",
+			message: `OpenSpec change '${changeName}' still has ${change.totalTasks - change.doneTasks} incomplete task(s) in tasks.md.`,
+			suggestedAction: "Reconcile tasks.md to match implemented work or finish the remaining tasks before archive.",
+		});
+	}
+
+	return {
+		changeName,
+		boundNodeIds: boundNodes.map((node) => node.id),
+		issues,
+	};
+}
+
+function appendPostAssessFollowUpTask(changePath: string, input: PostAssessReconciliationInput): boolean {
+	const tasksPath = path.join(changePath, "tasks.md");
+	if (!fs.existsSync(tasksPath)) return false;
+
+	const content = fs.readFileSync(tasksPath, "utf-8");
+	const summary = (input.summary || `Resolve remaining findings from /assess ${input.assessmentKind}`).trim();
+	const escapedSummary = summary.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const existing = new RegExp(`^\\s*-\\s+\\[ \\]\\s+\\d+(?:\\.\\d+)?\\s+${escapedSummary}$`, "m");
+	if (existing.test(content)) return false;
+
+	const groupNumbers = [...content.matchAll(/^##\s+(\d+)\.\s+/gm)].map((m) => parseInt(m[1], 10));
+	const nextGroup = groupNumbers.length > 0 ? Math.max(...groupNumbers) + 1 : 1;
+	const nextTask = `${nextGroup}.1`;
+	const block = [
+		"",
+		`## ${nextGroup}. Post-assess follow-up`,
+		"<!-- skills: typescript -->",
+		`- [ ] ${nextTask} ${summary}`,
+	].join("\n");
+
+	fs.writeFileSync(tasksPath, content.replace(/\s*$/, "") + block + "\n", "utf-8");
+	return true;
+}
+
+function appendImplementationDeltas(
+	node: DesignNode,
+	changedFiles: readonly string[],
+	constraints: readonly string[],
+): { appendedFiles: string[]; appendedConstraints: string[] } {
+	const sections = getNodeSections(node);
+	const existingFiles = new Set(sections.implementationNotes.fileScope.map((entry) => entry.path));
+	const existingConstraints = new Set(sections.implementationNotes.constraints);
+
+	const newFileScope: FileScope[] = [];
+	for (const file of changedFiles) {
+		if (!existingFiles.has(file)) {
+			newFileScope.push({
+				path: file,
+				description: "Post-assess reconciliation delta — touched during follow-up fixes",
+				action: "modified",
+			});
+		}
+	}
+
+	const newConstraints = constraints.filter((constraint) => !existingConstraints.has(constraint));
+	if (newFileScope.length === 0 && newConstraints.length === 0) {
+		return { appendedFiles: [], appendedConstraints: [] };
+	}
+
+	sections.implementationNotes.fileScope.push(...newFileScope);
+	sections.implementationNotes.constraints.push(...newConstraints);
+	writeNodeDocument(node, sections);
+
+	return {
+		appendedFiles: newFileScope.map((entry) => entry.path),
+		appendedConstraints: newConstraints,
+	};
+}
+
+export function applyPostAssessReconciliation(
+	cwd: string,
+	changeName: string,
+	input: PostAssessReconciliationInput,
+): PostAssessReconciliationResult {
+	const change = getChange(cwd, changeName);
+	const boundNodes = findBoundNodes(cwd, changeName);
+	const changedFiles = (input.changedFiles ?? []).map((file) => file.trim()).filter(Boolean);
+	const constraints = (input.constraints ?? []).map((constraint) => constraint.trim()).filter(Boolean);
+
+	let updatedTaskState = false;
+	let warning: string | undefined;
+	const updatedNodeIds: string[] = [];
+	const appendedFileScope: string[] = [];
+	const appendedConstraints: string[] = [];
+
+	if (input.outcome === "ambiguous") {
+		warning = "Post-assess reconciliation could not safely map reviewer prose back into OpenSpec tasks. No semantic task rewriting was attempted.";
+	} else if (input.outcome === "reopen" && change) {
+		updatedTaskState = appendPostAssessFollowUpTask(change.path, input);
+	}
+
+	for (const node of boundNodes) {
+		const delta = appendImplementationDeltas(node, changedFiles, constraints);
+		if (delta.appendedFiles.length > 0 || delta.appendedConstraints.length > 0) {
+			updatedNodeIds.push(node.id);
+			appendedFileScope.push(...delta.appendedFiles);
+			appendedConstraints.push(...delta.appendedConstraints);
+		}
+	}
+
+	return {
+		changeName,
+		outcome: input.outcome,
+		reopened: input.outcome === "reopen",
+		warning,
+		updatedTaskState,
+		updatedNodeIds,
+		appendedFileScope,
+		appendedConstraints,
+	};
+}
+
+export function formatReconciliationIssues(issues: readonly ReconciliationIssue[]): string {
+	return issues.map((issue) => `- ${issue.message}\n  → ${issue.suggestedAction}`).join("\n");
+}