@warpgogol/forge 2.8.0 → 2.8.2

package/os/session/session.module.ts

@@ -0,0 +1,126 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the session documentation domain commands with the forge kernel registry.</purpose>
+<non-goals>
+  <item>Do not implement handler logic here — delegate to handlers/*.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0537: initial forgeSessionModule registering session.save, session.archive, session.validate, session.list commands.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+
+export const forgeSessionModule: ForgeModule = {
+  name: "forge-session",
+  version: "0.1.0",
+  async register(registry) {
+    const { runSessionSave } = await import("./handlers/save.ts");
+    const { runSessionArchive } = await import("./handlers/archive.ts");
+    const { runSessionValidate } = await import("./handlers/validate.ts");
+    const { runSessionList } = await import("./handlers/list.ts");
+
+    registry.registerCommand({
+      name: "session.save",
+      description:
+        "Convert raw ATIF files from docs/sessions/.raw/ to structured markdown " +
+        "in docs/sessions/ with auto-extracted metadata. Idempotent — same raw " +
+        "file always produces the same output filename. Deletes raw file after " +
+        "conversion unless --keep-raw. Use --raw-file to process a specific file.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/sessions/*.md"],
+      reads: ["docs/sessions/.raw/*"],
+      cacheable: false,
+      flags: {
+        "raw-file": {
+          kind: "string",
+          description: "Process a specific raw file instead of scanning .raw/.",
+        },
+        "keep-raw": {
+          kind: "boolean",
+          description: "Do not delete raw file after conversion.",
+        },
+        "dry-run": {
+          kind: "boolean",
+          description: "Preview without writing files.",
+        },
+      },
+      execute: runSessionSave,
+    });
+
+    registry.registerCommand({
+      name: "session.archive",
+      description:
+        "Move session files older than --max-age-days (default 7) from " +
+        "docs/sessions/ to docs/sessions/archive/. Bidirectional: files in " +
+        "archive/ younger than threshold are moved back to docs/sessions/. " +
+        "Use --dry-run to preview. Age is computed from frontmatter date, " +
+        "not filesystem mtime. Prefer the docs.archive umbrella command " +
+        "unless you need to archive only sessions.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/sessions/*.md", "docs/sessions/archive/**"],
+      reads: ["docs/sessions/**/*.md"],
+      cacheable: false,
+      flags: {
+        "max-age-days": {
+          kind: "string",
+          description: "Age threshold in days (default 7).",
+        },
+        "dry-run": {
+          kind: "boolean",
+          description: "Preview what would be moved without touching the filesystem.",
+        },
+      },
+      execute: runSessionArchive,
+    });
+
+    registry.registerCommand({
+      name: "session.validate",
+      description:
+        "Validate session frontmatter schema (SES-01), id-filename match (SES-02), " +
+        "RFC-id existence (SES-03), raw file hygiene (SES-04), and non-markdown " +
+        "file detection (SES-05). Pass --id to validate a single file, " +
+        "or run without arguments for all. On-demand only — not integrated into " +
+        "build.check.",
+      scope: "workspace",
+      flags: {
+        id: { kind: "string", description: "Target a single session by id." },
+      },
+      reads: ["docs/sessions/**/*.md", "docs/rfcs/**/*.md"],
+      execute: runSessionValidate,
+    });
+
+    registry.registerCommand({
+      name: "session.list",
+      description:
+        "List all sessions. Filter with --date-from, --date-to, --rfc, --type flags. " +
+        "Use --json for machine-readable output. Parses frontmatter on the fly. " +
+        "Includes archived sessions (marked with archived: true).",
+      scope: "workspace",
+      flags: {
+        "date-from": {
+          kind: "string",
+          description: "Filter sessions from this date (YYYY-MM-DD, inclusive).",
+        },
+        "date-to": {
+          kind: "string",
+          description: "Filter sessions up to this date (YYYY-MM-DD, inclusive).",
+        },
+        rfc: {
+          kind: "string",
+          description: "Filter by related RFC id (e.g. RFC-0537).",
+        },
+        type: {
+          kind: "string",
+          description:
+            "Filter by session type (mission, grilling, implementation, review, fix, freeform).",
+        },
+      },
+      reads: ["docs/sessions/**/*.md"],
+      execute: runSessionList,
+    });
+  },
+};

package/os/session/types.ts

@@ -0,0 +1,203 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Type definitions and constants for the session documentation domain —
+session frontmatter, list/archive/validate/save result shapes, and SES
+validation rule identifiers.
+</purpose>
+<non-goals>
+  <item>Do not define handler logic here — that lives in handlers/*.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0537: initial session domain types, constants, and SES rule identifiers.</item>
+  <item>RFC-0884: add checkpoint interfaces, extend SessionFrontmatter with optional checkpoint fields, add SES-06 rule.</item>
+</CHANGE_SUMMARY>
+*/
+
+export const SESSION_DIR = "docs/sessions";
+export const SESSION_RAW_SUBDIR = ".raw";
+export const SESSION_ARCHIVE_SUBDIR = "archive";
+export const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}-[0-9a-f]{6}$/;
+export const SESSION_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}-[0-9a-f]{6}\.md$/;
+
+export const SESSION_TYPES = [
+  "mission",
+  "grilling",
+  "implementation",
+  "review",
+  "fix",
+  "freeform",
+] as const;
+
+export type SessionType = (typeof SESSION_TYPES)[number];
+
+export const SESSION_KNOWN_KEYS = [
+  "id",
+  "date",
+  "duration",
+  "types",
+  "summary",
+  "relatedRfcs",
+  "relatedArtifacts",
+  "decisions",
+  "commits",
+  "files",
+  "commands",
+  "systemDelta",
+  "diagrams",
+  "evidence",
+  "remainingIssues",
+  "checkpoint",
+] as const;
+
+export const SESSION_REQUIRED_KEYS = ["id", "date", "types"] as const;
+
+export const SESSION_REQUIRED_SECTIONS = ["## Transcript"] as const;
+
+// SES validation rules
+export const SES_RULES = {
+  SES_01: "SES-01",
+  SES_02: "SES-02",
+  SES_03: "SES-03",
+  SES_04: "SES-04",
+  SES_05: "SES-05",
+  SES_06: "SES-06",
+} as const;
+
+export type SesRule = (typeof SES_RULES)[keyof typeof SES_RULES];
+
+// ── Session frontmatter (the .md file's YAML frontmatter) ──
+
+export interface SessionCheckpoint {
+  before: string;
+  change: string;
+  after: string;
+}
+
+export interface SessionDiagram {
+  type: "flowchart" | "sequenceDiagram" | "stateDiagram-v2" | "erDiagram" | "none";
+  scope: "current-system" | "session-delta";
+  caption: string;
+  mermaid: string;
+}
+
+export interface SessionEvidenceEntry {
+  claim: string;
+  source?: string;
+  test?: string;
+  command?: string;
+}
+
+export interface SessionSystemDelta {
+  changedContracts: string[];
+  changedSchemas: string[];
+  changedStateMachines: string[];
+  changedInvariants: string[];
+  changedPersistence: string[];
+}
+
+export interface SessionFrontmatter {
+  id: string;
+  date: string;
+  duration: string | null;
+  types: SessionType[];
+  summary: string;
+  relatedRfcs: string[];
+  relatedArtifacts: string[];
+  decisions: string[];
+  commits: string[];
+  files: string[];
+  commands: string[];
+  systemDelta?: SessionSystemDelta;
+  diagrams?: SessionDiagram[];
+  evidence?: SessionEvidenceEntry[];
+  remainingIssues?: string[];
+  checkpoint?: SessionCheckpoint;
+}
+
+// ── session.save ──
+
+export interface SessionSaveResult {
+  command: "session.save";
+  status: "ok";
+  file: string;
+  rawFile: string;
+  rawDeleted: boolean;
+  id: string;
+  types: SessionType[];
+  extractedMetadata: {
+    relatedRfcs: string[];
+    relatedArtifacts: string[];
+    commits: string[];
+    files: string[];
+    commands: string[];
+  };
+  dryRun: boolean;
+}
+
+export interface SessionSaveSkip {
+  rawFile: string;
+  reason: string;
+}
+
+// ── session.archive ──
+
+export interface SessionArchiveMove {
+  id: string;
+  file: string;
+  from: string;
+  to: string;
+  ageDays: number;
+  direction: "into-archive" | "out-of-archive";
+}
+
+export interface SessionArchiveSkip {
+  id: string;
+  file: string;
+  reason: string;
+}
+
+export interface SessionArchiveResult {
+  command: "session.archive";
+  status: "ok";
+  moved: SessionArchiveMove[];
+  skipped: SessionArchiveSkip[];
+  maxAgeDays: number;
+  dryRun: boolean;
+}
+
+// ── session.validate ──
+
+export interface SessionValidationViolation {
+  rule: SesRule;
+  file: string;
+  message: string;
+  severity: "error" | "warning";
+}
+
+export interface SessionValidationResult {
+  command: "session.validate";
+  status: "pass" | "fail";
+  violations: SessionValidationViolation[];
+  checked: number;
+}
+
+// ── session.list ──
+
+export interface SessionListEntry {
+  id: string;
+  date: string;
+  types: SessionType[];
+  summary: string;
+  relatedRfcs: string[];
+  file: string;
+  archived: boolean;
+}
+
+export interface SessionListResult {
+  command: "session.list";
+  status: "ok";
+  sessions: SessionListEntry[];
+  count: number;
+}

package/os/spec/live-spec-list-show-validate.test.ts

@@ -0,0 +1,257 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for spec.live.list and spec.live.validate handlers (RFC-0711).</purpose>
+<non-goals>
+  <item>Do not test merge — covered in live-spec-merge.test.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0711: initial unit tests for spec.live.list and spec.live.validate.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { runSpecLiveList } from "./live-spec-list.ts";
+import { runSpecLiveShow } from "./live-spec-show.ts";
+import { runSpecLiveValidate } from "./live-spec-validate.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../../src/types.ts";
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    logger: {
+      section: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      success: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+const VALID_SPEC = `---
+domain: forge
+title: "Living Spec: forge"
+lastMergedRfc: RFC-9001
+updatedAt: 2026-08-06
+createdAt: 2026-08-06
+history:
+  - rfc: RFC-9001
+    mergedAt: 2026-08-06
+    operation: created
+---
+
+# Living Spec: forge
+
+## Overview
+
+Some content.
+`;
+
+describe("spec.live.list", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-live-list-"));
+    const liveDir = path.join(tmpDir, "docs/specs/live");
+    await fs.mkdir(liveDir, { recursive: true });
+    await fs.writeFile(path.join(liveDir, "forge.md"), VALID_SPEC);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("lists living specs", async () => {
+    const input: ForgeCommandInput = { argv: [], flags: {} };
+    const result = await runSpecLiveList(input, makeContext(tmpDir));
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data?.livingSpecs.length).toBe(1);
+    expect(result.data?.livingSpecs[0]?.domain).toBe("forge");
+    expect(result.data?.livingSpecs[0]?.lastMergedRfc).toBe("RFC-9001");
+  });
+
+  it("returns empty array when directory does not exist", async () => {
+    const emptyDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-live-empty-"));
+    try {
+      const input: ForgeCommandInput = { argv: [], flags: {} };
+      const result = await runSpecLiveList(input, makeContext(emptyDir));
+
+      expect(result.exitCode).toBe(0);
+      expect(result.data?.livingSpecs.length).toBe(0);
+    } finally {
+      await fs.rm(emptyDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("spec.live.show", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-live-show-"));
+    const liveDir = path.join(tmpDir, "docs/specs/live");
+    await fs.mkdir(liveDir, { recursive: true });
+    await fs.writeFile(path.join(liveDir, "forge.md"), VALID_SPEC);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("shows a living spec by domain", async () => {
+    const input: ForgeCommandInput = { argv: [], flags: { domain: "forge" } };
+    const result = await runSpecLiveShow(input, makeContext(tmpDir));
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data?.domain).toBe("forge");
+    expect(result.data?.title).toBe("Living Spec: forge");
+    expect(result.data?.body).toContain("# Living Spec: forge");
+  });
+
+  it("returns error when domain is missing", async () => {
+    const input: ForgeCommandInput = { argv: [], flags: {} };
+    const result = await runSpecLiveShow(input, makeContext(tmpDir));
+
+    expect(result.exitCode).toBe(1);
+    expect(result.summary).toContain("--domain");
+  });
+
+  it("returns error when spec not found", async () => {
+    const input: ForgeCommandInput = { argv: [], flags: { domain: "nonexistent" } };
+    const result = await runSpecLiveShow(input, makeContext(tmpDir));
+
+    expect(result.exitCode).toBe(1);
+    expect(result.summary).toContain("not found");
+  });
+});
+
+describe("spec.live.validate", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-live-validate-"));
+    const rfcDir = path.join(tmpDir, "docs/rfcs");
+    const liveDir = path.join(tmpDir, "docs/specs/live");
+    await fs.mkdir(rfcDir, { recursive: true });
+    await fs.mkdir(liveDir, { recursive: true });
+
+    // Create an implemented RFC so V-LS-03/04 pass
+    const rfcContent = `---
+id: RFC-9001
+title: "Test"
+status: implemented
+kind: architecture
+scope: workspace
+owners:
+  - architecture
+reviewers:
+  - human:test
+createdAt: 2026-08-06
+updatedAt: 2026-08-06
+implementedAt: 2026-08-06
+versionBump: patch
+packagesImpacted: []
+commands:
+  proposed: []
+  added: []
+  changed: []
+  removed: []
+appsImpacted: []
+successSignals: []
+nonGoals: []
+---
+
+# RFC-9001: Test
+
+## Design
+
+### Something
+
+Content.
+`;
+    await fs.writeFile(path.join(rfcDir, "rfc-9001-test.md"), rfcContent);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("passes with zero violations on a valid living spec", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, "docs/specs/live/forge.md"),
+      VALID_SPEC,
+    );
+
+    const input: ForgeCommandInput = { argv: [], flags: {} };
+    const result = await runSpecLiveValidate(input, makeContext(tmpDir));
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data?.status).toBe("pass");
+    expect(result.data?.violations.length).toBe(0);
+    expect(result.data?.specsChecked).toBe(1);
+  });
+
+  it("passes when directory does not exist (empty)", async () => {
+    const emptyDir = await fs.mkdtemp(path.join(os.tmpdir(), "spec-live-validate-empty-"));
+    try {
+      const input: ForgeCommandInput = { argv: [], flags: {} };
+      const result = await runSpecLiveValidate(input, makeContext(emptyDir));
+
+      expect(result.exitCode).toBe(0);
+      expect(result.data?.status).toBe("pass");
+      expect(result.data?.specsChecked).toBe(0);
+    } finally {
+      await fs.rm(emptyDir, { recursive: true, force: true });
+    }
+  });
+
+  it("fails when required frontmatter field is missing", async () => {
+    const invalidSpec = `---
+domain: forge
+title: "Living Spec: forge"
+---
+
+# Living Spec: forge
+`;
+    await fs.writeFile(path.join(tmpDir, "docs/specs/live/forge.md"), invalidSpec);
+
+    const input: ForgeCommandInput = { argv: [], flags: {} };
+    const result = await runSpecLiveValidate(input, makeContext(tmpDir));
+
+    expect(result.exitCode).toBe(1);
+    expect(result.data?.status).toBe("fail");
+    expect(result.data?.violations.length).toBeGreaterThan(0);
+    expect(result.data?.violations.some((v) => v.rule === "V-LS-01")).toBe(true);
+  });
+
+  it("fails when domain does not match filename (V-LS-02)", async () => {
+    const mismatchSpec = `---
+domain: wrong-domain
+title: "Living Spec"
+lastMergedRfc: RFC-9001
+updatedAt: 2026-08-06
+createdAt: 2026-08-06
+history:
+  - rfc: RFC-9001
+    mergedAt: 2026-08-06
+    operation: created
+---
+
+# Living Spec
+`;
+    await fs.writeFile(path.join(tmpDir, "docs/specs/live/forge.md"), mismatchSpec);
+
+    const input: ForgeCommandInput = { argv: [], flags: {} };
+    const result = await runSpecLiveValidate(input, makeContext(tmpDir));
+
+    expect(result.exitCode).toBe(1);
+    expect(result.data?.violations.some((v) => v.rule === "V-LS-02")).toBe(true);
+  });
+});

package/os/spec/live-spec-list.ts

@@ -0,0 +1,78 @@
+/*
+<MODULE_CONTRACT>
+<purpose>spec.live.list handler — lists all living specs in docs/specs/live/ (RFC-0711).</purpose>
+<non-goals>
+  <item>Do not merge or validate — use spec.live.merge / spec.live.validate.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0711: initial spec.live.list handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../src/types.ts";
+import type { SpecLiveListResult, SpecLiveListEntry } from "./live-spec-types.ts";
+
+const LIVE_SPECS_DIR = "docs/specs/live";
+
+export async function runSpecLiveList(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<SpecLiveListResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const liveSpecsDir = path.join(workspaceRoot, LIVE_SPECS_DIR);
+
+  const entries: SpecLiveListEntry[] = [];
+
+  if (existsSync(liveSpecsDir)) {
+    const files = await fs.readdir(liveSpecsDir);
+    for (const file of files) {
+      if (!file.endsWith(".md") || file === "README.md") continue;
+      const filePath = path.join(liveSpecsDir, file);
+      const content = await fs.readFile(filePath, "utf-8");
+      const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (!match) continue;
+      const fm = (YAML.parse(match[1]!) ?? {}) as Record<string, unknown>;
+      entries.push({
+        domain: String(fm["domain"] ?? ""),
+        title: String(fm["title"] ?? ""),
+        lastMergedRfc: String(fm["lastMergedRfc"] ?? ""),
+        updatedAt: String(fm["updatedAt"] ?? ""),
+        historyCount: Array.isArray(fm["history"]) ? fm["history"].length : 0,
+      });
+    }
+  }
+
+  entries.sort((a, b) => a.domain.localeCompare(b.domain));
+
+  const result: SpecLiveListResult = {
+    command: "spec.live.list",
+    status: "ok",
+    livingSpecs: entries,
+  };
+
+  if (outputFormat === "pretty") {
+    if (entries.length === 0) {
+      logger.info("spec.live.list: no living specs found");
+    } else {
+      logger.section(`Living Specs (${entries.length})`);
+      for (const entry of entries) {
+        logger.info(`  ${entry.domain} — ${entry.title} (last: ${entry.lastMergedRfc})`);
+      }
+    }
+  }
+
+  return {
+    data: result,
+    exitCode: 0,
+    summary: `spec.live.list: ${entries.length} living spec(s)`,
+  };
+}