sdd_history

Instructions

Implementation Reference

• src/tools/sdd-contracts.ts:143-169 (handler)

  The handler function for the 'sdd_history' tool. It queries the contracts table for a given project, orders by created_at DESC, and returns the history entries as JSON.

  // ── Get Project History ────────────────────────────
  server.tool(
    "sdd_history",
    "Get the SDD phase history for a project. Shows all contract transitions in chronological order.",
    {
      project: z.string().max(256).regex(/^[a-zA-Z0-9_.-]+$/).describe("Project identifier"),
      limit: z.number().min(1).max(100).default(20).describe("Max entries to return"),
    },
    async ({ project, limit }) => {
      const db = getDb();
      const rows = db
        .prepare(
          `SELECT id, phase, change_name, status, confidence, executive_summary, created_at
           FROM contracts WHERE project = ? ORDER BY created_at DESC LIMIT ?`
        )
        .all(project, limit);
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ project, history: rows }),
          },
        ],
      };
    }
  );

• src/tools/sdd-contracts.ts:147-150 (schema)

  Input schema for sdd_history: 'project' (string, max 256, alphanumeric+_.-) and 'limit' (number 1-100, default 20).

  {
    project: z.string().max(256).regex(/^[a-zA-Z0-9_.-]+$/).describe("Project identifier"),
    limit: z.number().min(1).max(100).default(20).describe("Max entries to return"),
  },

• src/tools/sdd-contracts.ts:144-169 (registration)

  Registration of 'sdd_history' tool on the McpServer with description and zod-validated parameters.

  server.tool(
    "sdd_history",
    "Get the SDD phase history for a project. Shows all contract transitions in chronological order.",
    {
      project: z.string().max(256).regex(/^[a-zA-Z0-9_.-]+$/).describe("Project identifier"),
      limit: z.number().min(1).max(100).default(20).describe("Max entries to return"),
    },
    async ({ project, limit }) => {
      const db = getDb();
      const rows = db
        .prepare(
          `SELECT id, phase, change_name, status, confidence, executive_summary, created_at
           FROM contracts WHERE project = ? ORDER BY created_at DESC LIMIT ?`
        )
        .all(project, limit);
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ project, history: rows }),
          },
        ],
      };
    }
  );

• src/server.ts:18-18 (registration)

  Call to registerSddTools(server) which registers the sdd_history tool among others.

  registerSddTools(server);

• src/database/index.ts:32-95 (helper)

  Database schema initialization – creates the 'contracts' table with columns (id, phase, change_name, project, status, confidence, executive_summary, data, created_at) which sdd_history queries.

  function initSchema(db: Database.Database): void {
    db.exec(`
      CREATE TABLE IF NOT EXISTS contracts (
        id TEXT PRIMARY KEY,
        phase TEXT NOT NULL,
        change_name TEXT NOT NULL,
        project TEXT NOT NULL,
        status TEXT NOT NULL,
        confidence REAL NOT NULL,
        executive_summary TEXT NOT NULL,
        data TEXT NOT NULL DEFAULT '{}',
        created_at TEXT NOT NULL DEFAULT (datetime('now'))
      );
  
      CREATE TABLE IF NOT EXISTS boards (
        id TEXT PRIMARY KEY,
        project TEXT NOT NULL,
        name TEXT NOT NULL,
        created_at TEXT NOT NULL DEFAULT (datetime('now')),
        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
      );
  
      CREATE TABLE IF NOT EXISTS tasks (
        id TEXT PRIMARY KEY,
        board_id TEXT NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
        title TEXT NOT NULL,
        description TEXT NOT NULL DEFAULT '',
        status TEXT NOT NULL DEFAULT 'backlog',
        priority TEXT NOT NULL DEFAULT 'p2',
        assignee TEXT,
        spec_ref TEXT,
        acceptance_criteria TEXT NOT NULL DEFAULT '',
        dependencies TEXT NOT NULL DEFAULT '[]',
        notes TEXT NOT NULL DEFAULT '[]',
        created_at TEXT NOT NULL DEFAULT (datetime('now')),
        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
        claimed_at TEXT,
        completed_at TEXT
      );
  
      CREATE TABLE IF NOT EXISTS file_reservations (
        id TEXT PRIMARY KEY,
        pattern TEXT NOT NULL,
        agent TEXT NOT NULL,
        expires_at TEXT NOT NULL,
        created_at TEXT NOT NULL DEFAULT (datetime('now'))
      );
  
      CREATE INDEX IF NOT EXISTS idx_tasks_board ON tasks(board_id);
      CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
      CREATE INDEX IF NOT EXISTS idx_contracts_project ON contracts(project);
      CREATE INDEX IF NOT EXISTS idx_reservations_agent ON file_reservations(agent);
  
      CREATE TABLE IF NOT EXISTS audit_log (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        timestamp TEXT DEFAULT (datetime('now')),
        action TEXT NOT NULL,
        entity_type TEXT NOT NULL,
        entity_id TEXT NOT NULL,
        agent_name TEXT,
        details TEXT
      );
    `);
  }